Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): correct sync dialog for missing credential + resume after reconnect (#1743)

Andrew Mikofalvyfc3e907b5049
diff --git a/.changeset/sync-no-credential-recovery.md b/.changeset/sync-no-credential-recovery.md
new file mode 100644
index 000000000..b5e106332
--- /dev/null
+++ b/.changeset/sync-no-credential-recovery.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fix the sync status dialog and recovery when a GitHub credential is missing. Previously a credential-less fetch/push was misclassified as a retryable network error, so the popover showed "Offline" with a raw `could not read Username … Device not configured` stderr blob and "Sync now" / "Retry" buttons that could never succeed — and the one useful action, reconnecting GitHub, was never offered. Now this is classified as an auth error (`auth-no-credential`): the dialog reads "Reconnect required" with a clear one-line message ("GitHub sign-in is missing or expired. Reconnect to resume syncing.") and a single "Connect GitHub" button. Reconnecting resumes sync without an app restart, and the auth-error state no longer persists across restarts. The server also sets `GIT_TERMINAL_PROMPT=0` so git fails fast instead of attempting a no-TTY prompt.
diff --git a/packages/app/src/components/SyncStatusBadge.test.ts b/packages/app/src/components/SyncStatusBadge.test.ts
index 2645d558f..0578c7d48 100644
--- a/packages/app/src/components/SyncStatusBadge.test.ts
+++ b/packages/app/src/components/SyncStatusBadge.test.ts
@@ -120,6 +120,15 @@ describe('formatSyncFailureCode — neutral collapsed copy', () => {
expect(formatSyncFailureCode('auth-403')).not.toBe(formatPushFailureCode('auth-403'));
expect(formatSyncFailureCode('auth-403')).toBe(formatPullFailureCode('auth-403'));
});
+
+ test('auth-no-credential copy directs the user to reconnect (all three formatters)', async () => {
+ const { formatSyncFailureCode, formatPushFailureCode, formatPullFailureCode } = await import(
+ './SyncStatusBadge'
+ );
+ for (const fmt of [formatSyncFailureCode, formatPushFailureCode, formatPullFailureCode]) {
+ expect(fmt('auth-no-credential')).toMatch(/reconnect/i);
+ }
+ });
});
describe('computeSyncErrorLines — collapse + label truth table', () => {
diff --git a/packages/app/src/components/SyncStatusBadge.tsx b/packages/app/src/components/SyncStatusBadge.tsx
index 3b6588774..879d101f2 100644
--- a/packages/app/src/components/SyncStatusBadge.tsx
+++ b/packages/app/src/components/SyncStatusBadge.tsx
@@ -169,6 +169,8 @@ export function formatPushFailureCode(code: SyncErrorCode): string {
return t`GitHub authentication failed. Try signing in again.`;
case 'auth-scope-mismatch':
return t`Your GitHub token is missing required scopes. Try signing in again.`;
+ case 'auth-no-credential':
+ return t`GitHub sign-in is missing or expired. Reconnect to resume syncing.`;
case 'semantic-protected-branch':
return t`The default branch is protected — pushes need a pull request.`;
default:
@@ -184,6 +186,8 @@ export function formatPullFailureCode(code: SyncErrorCode): string {
return t`GitHub authentication failed. Try signing in again.`;
case 'auth-scope-mismatch':
return t`Your GitHub token is missing required scopes. Try signing in again.`;
+ case 'auth-no-credential':
+ return t`GitHub sign-in is missing or expired. Reconnect to resume syncing.`;
default:
return t`Fetch failed — check the server logs for details.`;
}
@@ -197,6 +201,8 @@ export function formatSyncFailureCode(code: SyncErrorCode): string {
return t`GitHub authentication failed. Try signing in again.`;
case 'auth-scope-mismatch':
return t`Your GitHub token is missing required scopes. Try signing in again.`;
+ case 'auth-no-credential':
+ return t`GitHub sign-in is missing or expired. Reconnect to resume syncing.`;
case 'semantic-protected-branch':
return t`The default branch is protected — pushes need a pull request.`;
default:
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index 4feac0cc7..2d9b163f6 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -1662,6 +1662,7 @@
"u3wRF-": ["Published"],
"u6Hp4N": ["Markdown"],
"u7H-Wn": ["Show panel (", ["panelShortcutLabel"], ")"],
+ "uCaIdy": ["GitHub sign-in is missing or expired. Reconnect to resume syncing."],
"uF9ruK": ["Saving"],
"uH_S-u": [["loadErrorTitle"], ": ", ["message"]],
"uKRYiW": ["Sync status unavailable — server error."],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index 41faf8dbb..496bd32fe 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -2442,6 +2442,10 @@ msgstr "Git identity isn't set — commits use a default author. Set yours so te
msgid "GitHub authentication failed. Try signing in again."
msgstr "GitHub authentication failed. Try signing in again."
+#: src/components/SyncStatusBadge.tsx
+msgid "GitHub sign-in is missing or expired. Reconnect to resume syncing."
+msgstr "GitHub sign-in is missing or expired. Reconnect to resume syncing."
+
#: src/lib/keyboard-shortcuts.ts
msgid "Global"
msgstr "Global"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 87b1a965e..ab0de2ed6 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -1662,6 +1662,7 @@
"u3wRF-": ["Ƥũƀĺĩśĥēď"],
"u6Hp4N": ["Ḿàŕķďōŵń"],
"u7H-Wn": ["Śĥōŵ ƥàńēĺ (", ["panelShortcutLabel"], ")"],
+ "uCaIdy": ["ĜĩţĤũƀ śĩĝń-ĩń ĩś ḿĩśśĩńĝ ōŕ ēxƥĩŕēď. Ŕēćōńńēćţ ţō ŕēśũḿē śŷńćĩńĝ."],
"uF9ruK": ["Śàvĩńĝ"],
"uH_S-u": [["loadErrorTitle"], ": ", ["message"]],
"uKRYiW": ["Śŷńć śţàţũś ũńàvàĩĺàƀĺē — śēŕvēŕ ēŕŕōŕ."],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index 78fce2596..2397597cd 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -2437,6 +2437,10 @@ msgstr ""
msgid "GitHub authentication failed. Try signing in again."
msgstr ""
+#: src/components/SyncStatusBadge.tsx
+msgid "GitHub sign-in is missing or expired. Reconnect to resume syncing."
+msgstr ""
+
#: src/lib/keyboard-shortcuts.ts
msgid "Global"
msgstr ""
diff --git a/packages/core/src/schemas/api/sync-seed.ts b/packages/core/src/schemas/api/sync-seed.ts
index f3ef94b1a..2cd4b6e88 100644
--- a/packages/core/src/schemas/api/sync-seed.ts
+++ b/packages/core/src/schemas/api/sync-seed.ts
@@ -45,6 +45,7 @@ export const SYNC_ERROR_CODES = [
'auth-403',
'auth-401',
'auth-scope-mismatch',
+ 'auth-no-credential',
'semantic-protected-branch',
] as const;
diff --git a/packages/server/src/api-extension.test.ts b/packages/server/src/api-extension.test.ts
index 49fabd306..13dae834d 100644
--- a/packages/server/src/api-extension.test.ts
+++ b/packages/server/src/api-extension.test.ts
@@ -3,7 +3,9 @@ import { existsSync, mkdirSync, symlinkSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
-import { safeSubdir, sanitizeFilename } from './api-extension.ts';
+import { resumeSyncOnAuthEvent, safeSubdir, sanitizeFilename } from './api-extension.ts';
+import type { AuthEvent } from './local-ops/types.ts';
+import type { SyncEngine } from './sync-engine.ts';
describe('safeSubdir', () => {
const baseDir = '/home/user/content';
@@ -540,3 +542,53 @@ describe('handleUploadAsset — same-dir sha256 dedup (FR-2)', () => {
expect(res.deduped).toBe(false);
});
});
+
+describe('resumeSyncOnAuthEvent (reconnect → resume wiring)', () => {
+ const makeEngineStub = (impl?: () => Promise<void>) => {
+ const calls: number[] = [];
+ const engine = {
+ notifyCredentialsChanged: () => {
+ calls.push(Date.now());
+ return impl ? impl() : Promise.resolve();
+ },
+ } as unknown as SyncEngine;
+ return { engine, calls, getSyncEngine: () => engine };
+ };
+
+ const completeEvent: AuthEvent = { type: 'complete', host: 'github.com', login: 'octocat' };
+ const verificationEvent: AuthEvent = {
+ type: 'verification',
+ user_code: 'ABCD-1234',
+ verification_uri: 'https://github.com/login/device',
+ expires_in: 900,
+ };
+ const errorEvent: AuthEvent = { type: 'error', message: 'denied' };
+
+ test('a complete event resumes sync via notifyCredentialsChanged', () => {
+ const stub = makeEngineStub();
+ resumeSyncOnAuthEvent(completeEvent, stub.getSyncEngine);
+ expect(stub.calls.length).toBe(1);
+ });
+
+ test('non-complete events do not resume sync', () => {
+ const stub = makeEngineStub();
+ resumeSyncOnAuthEvent(verificationEvent, stub.getSyncEngine);
+ resumeSyncOnAuthEvent(errorEvent, stub.getSyncEngine);
+ expect(stub.calls.length).toBe(0);
+ });
+
+ test('absent getSyncEngine is a no-op (engine dormant / not yet constructed)', () => {
+ expect(() => resumeSyncOnAuthEvent(completeEvent, undefined)).not.toThrow();
+ });
+
+ test('a null engine is a no-op', () => {
+ expect(() => resumeSyncOnAuthEvent(completeEvent, () => null)).not.toThrow();
+ });
+
+ test('a rejected notifyCredentialsChanged is swallowed (best-effort)', async () => {
+ const stub = makeEngineStub(() => Promise.reject(new Error('boom')));
+ expect(() => resumeSyncOnAuthEvent(completeEvent, stub.getSyncEngine)).not.toThrow();
+ expect(stub.calls.length).toBe(1);
+ await Promise.resolve();
+ });
+});
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index bb3afd32e..277f0b1eb 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -559,6 +559,16 @@ export function __resetRenameTelemetryForTesting(): void {
_renameAttributionCounter = null;
}
+export function resumeSyncOnAuthEvent(
+ event: AuthEvent,
+ getSyncEngine?: () => SyncEngine | null,
+): void {
+ if (event.type !== 'complete') return;
+ void getSyncEngine?.()
+ ?.notifyCredentialsChanged()
+ .catch(() => {});
+}
+
export const ROLLBACK_ORIGIN = {
source: 'local' as const,
skipStoreHooks: false,
@@ -8283,6 +8293,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
});
return;
}
+ resumeSyncOnAuthEvent(event, getSyncEngine);
if (!res.writableEnded && !res.destroyed) {
try {
res.write(`${JSON.stringify(event)}\n`);
diff --git a/packages/server/src/error-classification.test.ts b/packages/server/src/error-classification.test.ts
index a3ab27bbb..6368385cf 100644
--- a/packages/server/src/error-classification.test.ts
+++ b/packages/server/src/error-classification.test.ts
@@ -109,6 +109,47 @@ describe('classifyGitError', () => {
expect(r.subclass).toBe('scope-mismatch');
expect(r.retryable).toBe(false);
});
+
+ test('no credential — "could not read Username … Device not configured" (no GIT_TERMINAL_PROMPT)', () => {
+ const r = classifyGitError(
+ mkErr(
+ 'fatal: could not read Username',
+ "fatal: could not read Username for 'https://github.com': Device not configured",
+ ),
+ );
+ expect(r.class).toBe('auth');
+ expect(r.subclass).toBe('no-credential');
+ expect(r.retryable).toBe(false);
+ expect(r.userFacingCode).toBe('auth-no-credential');
+ });
+
+ test('no credential — "terminal prompts disabled" (with GIT_TERMINAL_PROMPT=0)', () => {
+ const r = classifyGitError(
+ mkErr(
+ 'fatal: could not read Username',
+ "fatal: could not read Username for 'https://github.com': terminal prompts disabled",
+ ),
+ );
+ expect(r.class).toBe('auth');
+ expect(r.subclass).toBe('no-credential');
+ expect(r.retryable).toBe(false);
+ expect(r.userFacingCode).toBe('auth-no-credential');
+ });
+
+ test('no credential — could not read Password', () => {
+ const r = classifyGitError(
+ mkErr(
+ 'fatal',
+ "could not read Password for 'https://github.com': terminal prompts disabled",
+ ),
+ );
+ expect(r.class).toBe('auth');
+ expect(r.subclass).toBe('no-credential');
+ });
+
+ test('deriveUserFacingCode maps auth/no-credential', () => {
+ expect(deriveUserFacingCode('auth', 'no-credential')).toBe('auth-no-credential');
+ });
});
describe('Class 3 — Semantic (non-retryable)', () => {
@@ -400,11 +441,13 @@ describe('classifyGitError', () => {
'auth-403',
'auth-401',
'auth-scope-mismatch',
+ 'auth-no-credential',
'semantic-protected-branch',
]);
const samples = [
mkErr('Could not resolve host: github.com'),
mkErr('HTTP 403: forbidden'),
+ mkErr("fatal: could not read Username for 'https://github.com': terminal prompts disabled"),
mkErr('CONFLICT'),
mkErr('lfs storage quota exceeded'),
mkErr('Unknown error'),
diff --git a/packages/server/src/error-classification.ts b/packages/server/src/error-classification.ts
index 538374f97..a41fe19de 100644
--- a/packages/server/src/error-classification.ts
+++ b/packages/server/src/error-classification.ts
@@ -1,7 +1,13 @@
import type { SyncErrorCode } from '@inkeep/open-knowledge-core';
type NetworkSubclass = 'dns' | 'timeout' | '5xx' | '429' | 'connection-refused' | 'unknown-network';
-type AuthSubclass = '401' | '403' | 'expired-token' | 'scope-mismatch' | 'unknown-auth';
+type AuthSubclass =
+ | '401'
+ | '403'
+ | 'expired-token'
+ | 'scope-mismatch'
+ | 'no-credential'
+ | 'unknown-auth';
type SemanticSubclass =
| 'non-fast-forward'
| 'protected-branch'
@@ -66,6 +72,7 @@ export function deriveUserFacingCode(
if (cls === 'auth' && subclass === '403') return 'auth-403';
if (cls === 'auth' && subclass === '401') return 'auth-401';
if (cls === 'auth' && subclass === 'scope-mismatch') return 'auth-scope-mismatch';
+ if (cls === 'auth' && subclass === 'no-credential') return 'auth-no-credential';
if (cls === 'semantic' && subclass === 'protected-branch') return 'semantic-protected-branch';
return null;
}
@@ -93,6 +100,11 @@ const AUTH_PATTERNS: RegExp[] = [
/fatal:.*repository.*not found/i, // often auth-related on private repos
];
+const NO_CREDENTIAL_PATTERNS: RegExp[] = [
+ /could not read (username|password)/i,
+ /terminal prompts disabled/i,
+];
+
const SCOPE_MISMATCH_PATTERNS: RegExp[] = [
/insufficient scopes/i,
/missing.*scope/i,
@@ -245,6 +257,15 @@ function classifyGitErrorBase(error: Error | unknown): ClassifiedErrorBase {
};
}
+ if (matchesAny(combined, NO_CREDENTIAL_PATTERNS)) {
+ return {
+ class: 'auth',
+ subclass: 'no-credential',
+ retryable: false,
+ message: 'No GitHub credential available — reconnect to resume syncing',
+ rawStderr: raw,
+ };
+ }
if (matchesAny(combined, SCOPE_MISMATCH_PATTERNS)) {
return {
class: 'auth',
diff --git a/packages/server/src/git-handle.test.ts b/packages/server/src/git-handle.test.ts
index 7dea521f3..eadaf9843 100644
--- a/packages/server/src/git-handle.test.ts
+++ b/packages/server/src/git-handle.test.ts
@@ -26,6 +26,10 @@ describe('buildGitEnv', () => {
expect(env.LC_ALL).toBe('C');
});
+ test('disables terminal prompts (no-TTY server-spawned git)', () => {
+ expect(buildGitEnv().GIT_TERMINAL_PROMPT).toBe('0');
+ });
+
test('preserves PATH so a bare-command credential helper resolves', () => {
withEnv('PATH', '/custom/bin:/usr/bin', () => {
expect(buildGitEnv().PATH).toBe('/custom/bin:/usr/bin');
diff --git a/packages/server/src/git-handle.ts b/packages/server/src/git-handle.ts
index 584d647b9..71ba2f48b 100644
--- a/packages/server/src/git-handle.ts
+++ b/packages/server/src/git-handle.ts
@@ -21,7 +21,7 @@ type CredentialHelperUnsafeGitOptions = SimpleGitOptions & {
};
export function buildGitEnv(): Record<string, string> {
- const env: Record<string, string> = { LANG: 'C', LC_ALL: 'C' };
+ const env: Record<string, string> = { LANG: 'C', LC_ALL: 'C', GIT_TERMINAL_PROMPT: '0' };
if (process.env.PATH !== undefined) {
env.PATH = process.env.PATH;
}
diff --git a/packages/server/src/sync-engine.test.ts b/packages/server/src/sync-engine.test.ts
index 57888a0f7..bcac7e406 100644
--- a/packages/server/src/sync-engine.test.ts
+++ b/packages/server/src/sync-engine.test.ts
@@ -1351,3 +1351,85 @@ describe('SyncEngine getStatus() with restored state', () => {
expect(status.lastPushedSha).toBe('abc123');
});
});
+
+interface InternalState {
+ state: SyncState;
+ pausedReason?: string;
+ pushError?: string;
+ pullError?: string;
+ pushErrorCode?: string;
+ pullErrorCode?: string;
+}
+
+describe('SyncEngine auth-error recovery', () => {
+ const statePath = () => join(okDir, 'sync-state.json');
+
+ test('does not restore a persisted auth-error pausedReason (re-attempts on restart)', async () => {
+ writeFileSync(
+ statePath(),
+ JSON.stringify({
+ version: 1,
+ lastSyncUtc: null,
+ lastFetchUtc: null,
+ lastPushedSha: null,
+ consecutiveFailures: 0,
+ inflightConflicts: [],
+ pausedReason: 'auth-error',
+ }),
+ 'utf-8',
+ );
+ const engine = makeEngine({ syncEnabled: false });
+ await engine.start();
+ expect(engine.getStatus().pausedReason).toBeUndefined();
+ });
+
+ test('saveStateNow does not persist auth-error when set in-memory', async () => {
+ const engine = makeEngine({ syncEnabled: true });
+ const internal = engine as unknown as InternalState;
+ internal.state = 'auth-error';
+ internal.pausedReason = 'auth-error';
+
+ await engine.destroy(); // saveStateNow flushes the in-memory pausedReason
+
+ const reloaded = JSON.parse(readFileSync(statePath(), 'utf-8')) as { pausedReason?: string };
+ expect(reloaded.pausedReason).toBeUndefined();
+ });
+
+ test('notifyCredentialsChanged clears auth-error and re-evaluates', async () => {
+ const engine = makeEngine({ syncEnabled: true });
+ const internal = engine as unknown as InternalState;
+ internal.state = 'auth-error';
+ internal.pausedReason = 'auth-error';
+ internal.pushError = 'no credential';
+ internal.pullError = 'no credential';
+ internal.pushErrorCode = 'auth-no-credential';
+ internal.pullErrorCode = 'auth-no-credential';
+ expect(engine.getStatus().state).toBe('auth-error');
+
+ await engine.notifyCredentialsChanged();
+
+ const status = engine.getStatus();
+ expect(status.state).not.toBe('auth-error');
+ expect(status.pausedReason).toBeUndefined();
+ expect(status.pushError).toBeUndefined();
+ expect(status.pullError).toBeUndefined();
+ expect(status.pushErrorCode).toBeUndefined();
+ expect(status.pullErrorCode).toBeUndefined();
+ expect(status.state).toBe('dormant');
+ await engine.destroy();
+ });
+
+ test('notifyCredentialsChanged is a no-op when sync is disabled', async () => {
+ const engine = makeEngine({ syncEnabled: false });
+ (engine as unknown as InternalState).pausedReason = 'auth-error';
+ await engine.notifyCredentialsChanged();
+ expect(engine.getStatus().pausedReason).toBe('auth-error');
+ });
+
+ test('notifyCredentialsChanged is a no-op when not parked on auth-error', async () => {
+ const engine = makeEngine({ syncEnabled: true });
+ const before = engine.getStatus().state;
+ await engine.notifyCredentialsChanged();
+ expect(engine.getStatus().state).toBe(before);
+ });
+});
diff --git a/packages/server/src/sync-engine.ts b/packages/server/src/sync-engine.ts
index 3486b4bed..e284ba120 100644
--- a/packages/server/src/sync-engine.ts
+++ b/packages/server/src/sync-engine.ts
@@ -442,6 +442,29 @@ export class SyncEngine {
void this.probePushPermissionInternal('refresh');
}
+ async notifyCredentialsChanged(): Promise<void> {
+ if (!this.syncEnabled) return;
+ if (this.state !== 'auth-error' && this.pausedReason !== 'auth-error') return;
+
+ this.pausedReason = undefined;
+ this.clearPushError();
+ this.clearPullError();
+ this.consecutiveFailures = 0;
+
+ this.hasRemote = await this.probeRemote();
+ if (!this.hasRemote) {
+ this.transitionTo('dormant');
+ this.saveStateNow();
+ return;
+ }
+
+ this.transitionTo('idle');
+ this.schedulePull(0);
+ this.schedulePush();
+ this.saveStateNow();
+ void this.probePushPermissionInternal('refresh');
+ }
+
async trigger(op: 'sync' | 'push' | 'pull' = 'sync'): Promise<void> {
this.consecutiveFailures = 0;
if (
@@ -768,7 +791,8 @@ export class SyncEngine {
private async runPullCycle(): Promise<void> {
if (this.pullInFlight) return;
- if (this.state === 'dormant' || this.state === 'disabled') return;
+ if (this.state === 'dormant' || this.state === 'disabled' || this.state === 'auth-error')
+ return;
if (this.state === 'conflict') {
this.schedulePull(); // retry after interval but don't fetch while conflicted
return;
@@ -1578,7 +1602,9 @@ export class SyncEngine {
private saveStateNow(): void {
try {
const persistedReason =
- this.pausedReason === 'no-push-permission' ? undefined : this.pausedReason;
+ this.pausedReason === 'no-push-permission' || this.pausedReason === 'auth-error'
+ ? undefined
+ : this.pausedReason;
const data: PersistedSyncState = {
version: 1,
lastSyncUtc: this.lastSyncUtc,
@@ -1606,7 +1632,9 @@ export class SyncEngine {
this.lastPushedSha = data.lastPushedSha ?? null;
this.consecutiveFailures = data.consecutiveFailures ?? 0;
this.pausedReason =
- data.pausedReason === 'no-push-permission' ? undefined : data.pausedReason;
+ data.pausedReason === 'no-push-permission' || data.pausedReason === 'auth-error'
+ ? undefined
+ : data.pausedReason;
const inflightFiles = data.inflightConflicts ?? [];
if (inflightFiles.length > 0) {