Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(desktop): dev sessions auto-reclaim a stale foreign server (#1590)

mike-inkeepc400a36b319f
diff --git a/.changeset/desktop-dev-reclaim-stale-server.md b/.changeset/desktop-dev-reclaim-stale-server.md
new file mode 100644
index 000000000..eb79afc05
--- /dev/null
+++ b/.changeset/desktop-dev-reclaim-stale-server.md
@@ -0,0 +1,31 @@
+---
+"@inkeep/open-knowledge-desktop": patch
+"@inkeep/open-knowledge-core": patch
+"@inkeep/open-knowledge": patch
+---
+
+feat(desktop): dev sessions auto-reclaim a stale foreign server (dev-only)
+
+When a desktop dev session (`electron-vite dev` / `bun run dev` — `!app.isPackaged`)
+opens a project whose contentDir already has a live Open Knowledge server it did
+not spawn — a leftover from a prior packaged-app run, a `ok start` CLI, or another
+instance — it previously **attached** to that server. Devs then ran their editor
+against a stale server + core build instead of their working tree, with no signal
+anything was wrong.
+
+The dev attach path now **terminates that foreign server and spawns a fresh
+own-build server in its place** (reusing the same SIGTERM → grace → SIGKILL ladder
+as the user-initiated restart, then falling through the existing `runClean` + spawn
+path). It is gated strictly to dev: packaged builds still attach to a live server,
+which is the intended shared-server behavior. A server this session spawned itself
+is never reclaimed (pid guard), and if termination fails (e.g. EPERM, cross-user
+server) the session falls back to attaching rather than leaving the project
+window-less.
+
+Because no user action initiated the teardown, the freshly-spawned window surfaces
+an **act-then-inform** notice (new `ok:server-reclaimed` bridge event) naming the
+side effect: connected agents (Claude Code, Codex, Cursor) just lost their Open
+Knowledge MCP connection and should restart the agent — or toggle its Open
+Knowledge MCP server off and on — to reconnect.
+
+No effect on published/packaged behavior.
diff --git a/packages/app/src/lib/desktop-bridge-types.ts b/packages/app/src/lib/desktop-bridge-types.ts
index d5f272ab3..ab6915f32 100644
--- a/packages/app/src/lib/desktop-bridge-types.ts
+++ b/packages/app/src/lib/desktop-bridge-types.ts
@@ -419,6 +419,7 @@ export interface OkDesktopBridge {
onShareReceived(cb: (payload: OkShareReceivedPayload) => void): OkUnsubscribe;
onServerVersionDrift(cb: (info: OkServerVersionDriftInfo) => void): OkUnsubscribe;
onServerRestarted(cb: (info: { readonly appRuntime: string }) => void): OkUnsubscribe;
+ onServerReclaimed(cb: (info: { readonly appRuntime: string }) => void): OkUnsubscribe;
restartServer(projectPath: string): Promise<OkServerRestartOutcome>;
setThemeSource(source: OkThemeSource): Promise<{ ok: true }>;
signalThemeApplied(opts?: { reducedTransparency?: boolean }): void;
diff --git a/packages/app/src/lib/install-server-drift-listener.test.ts b/packages/app/src/lib/install-server-drift-listener.test.ts
index 2124c0db9..df515cca3 100644
--- a/packages/app/src/lib/install-server-drift-listener.test.ts
+++ b/packages/app/src/lib/install-server-drift-listener.test.ts
@@ -29,6 +29,7 @@ import {
driftToastBody,
installServerDriftListener,
RESTART_DISRUPTION_WARNING,
+ reclaimNoticeMessage,
restartFailureMessage,
restartSuccessMessage,
} from '@/lib/install-server-drift-listener';
@@ -44,14 +45,18 @@ function makeBridge(opts?: { restartOutcome?: OkServerRestartOutcome; restartRej
bridge: OkDesktopBridge;
fireDrift: (info: OkServerVersionDriftInfo) => void;
fireRestarted: (appRuntime: string) => void;
+ fireReclaimed: (appRuntime: string) => void;
restartServer: ReturnType<typeof mock>;
unsubDrift: ReturnType<typeof mock>;
unsubRestarted: ReturnType<typeof mock>;
+ unsubReclaimed: ReturnType<typeof mock>;
} {
let driftCb: ((info: OkServerVersionDriftInfo) => void) | null = null;
let restartedCb: ((info: { appRuntime: string }) => void) | null = null;
+ let reclaimedCb: ((info: { appRuntime: string }) => void) | null = null;
const unsubDrift = mock(() => {});
const unsubRestarted = mock(() => {});
+ const unsubReclaimed = mock(() => {});
const restartServer = mock(async () => {
if (opts?.restartReject) throw new Error('channel closed');
return opts?.restartOutcome ?? { ok: true };
@@ -66,15 +71,21 @@ function makeBridge(opts?: { restartOutcome?: OkServerRestartOutcome; restartRej
restartedCb = cb;
return unsubRestarted;
},
+ onServerReclaimed: (cb: (info: { appRuntime: string }) => void) => {
+ reclaimedCb = cb;
+ return unsubReclaimed;
+ },
restartServer,
} as unknown as OkDesktopBridge;
return {
bridge,
fireDrift: (info) => driftCb?.(info),
fireRestarted: (appRuntime) => restartedCb?.({ appRuntime }),
+ fireReclaimed: (appRuntime) => reclaimedCb?.({ appRuntime }),
restartServer,
unsubDrift,
unsubRestarted,
+ unsubReclaimed,
};
}
@@ -115,6 +126,16 @@ describe('drift copy', () => {
expect(restartSuccessMessage('0.8.2')).toContain('0.8.2');
});
+ test('reclaim notice names the dev session, the version, MCP, and the agent remedy', () => {
+ const msg = reclaimNoticeMessage('0.8.2');
+ expect(msg.toLowerCase()).toContain('dev session');
+ expect(msg).toContain('0.8.2');
+ expect(msg).toContain('terminated');
+ expect(msg).toContain('MCP');
+ expect(msg.toLowerCase()).toContain('restart the agent');
+ expect(msg).toContain('Claude Code');
+ });
+
test('eperm failure points at a different account + reboot, never `ok stop all`', () => {
const msg = restartFailureMessage('eperm');
expect(msg.toLowerCase()).toContain('different account');
@@ -132,13 +153,14 @@ describe('installServerDriftListener', () => {
expect(installServerDriftListener({ bridge: undefined })).toBeUndefined();
});
- test('subscribes to both events and unsubscribes on teardown', () => {
+ test('subscribes to all three events and unsubscribes on teardown', () => {
const h = makeBridge();
const cleanup = installServerDriftListener({ bridge: h.bridge });
expect(cleanup).toBeDefined();
cleanup?.();
expect(h.unsubDrift).toHaveBeenCalledTimes(1);
expect(h.unsubRestarted).toHaveBeenCalledTimes(1);
+ expect(h.unsubReclaimed).toHaveBeenCalledTimes(1);
});
type DriftNode = {
@@ -216,4 +238,16 @@ describe('installServerDriftListener', () => {
expect(toastSuccess).toHaveBeenCalledTimes(1);
expect(toastSuccess.mock.calls[0]?.[0]).toBe(restartSuccessMessage('0.8.2'));
});
+
+ test('reclaimed event shows a transient warning (not a success) naming the side effect', () => {
+ toastWarning.mockClear();
+ toastSuccess.mockClear();
+ const h = makeBridge();
+ installServerDriftListener({ bridge: h.bridge });
+ h.fireReclaimed('0.8.2');
+ expect(toastWarning).toHaveBeenCalledTimes(1);
+ expect(toastWarning.mock.calls[0]?.[0]).toBe(reclaimNoticeMessage('0.8.2'));
+ expect(toastWarning.mock.calls[0]?.[1]).toMatchObject({ duration: 15_000 });
+ expect(toastSuccess).not.toHaveBeenCalled();
+ });
});
diff --git a/packages/app/src/lib/install-server-drift-listener.ts b/packages/app/src/lib/install-server-drift-listener.ts
index 74f5fb774..b3515d06d 100644
--- a/packages/app/src/lib/install-server-drift-listener.ts
+++ b/packages/app/src/lib/install-server-drift-listener.ts
@@ -26,6 +26,10 @@ export function restartSuccessMessage(appRuntime: string): string {
return `Restarted — now running v${appRuntime}.`;
}
+export function reclaimNoticeMessage(appRuntime: string): string {
+ return `Started a fresh Open Knowledge server (v${appRuntime}) for this dev session — the server already running for this project was terminated. Connected agents (Claude Code, Codex, Cursor) just lost their Open Knowledge MCP connection; restart the agent, or toggle its Open Knowledge MCP server off and on, to reconnect.`;
+}
+
export function restartFailureMessage(reason: 'eperm' | 'other'): string {
return reason === 'eperm'
? "Couldn't restart the server — it's running under a different account. Restart your computer to clear it, then reopen this project."
@@ -78,8 +82,13 @@ export function installServerDriftListener(opts: {
toast.success(restartSuccessMessage(info.appRuntime));
});
+ const unsubscribeReclaimed = bridge.onServerReclaimed((info) => {
+ toast.warning(reclaimNoticeMessage(info.appRuntime), { duration: 15_000 });
+ });
+
return () => {
unsubscribeDrift();
unsubscribeRestarted();
+ unsubscribeReclaimed();
};
}
diff --git a/packages/app/tests/stress/file-tree-create.e2e.ts b/packages/app/tests/stress/file-tree-create.e2e.ts
index 25f69db6a..549671db4 100644
--- a/packages/app/tests/stress/file-tree-create.e2e.ts
+++ b/packages/app/tests/stress/file-tree-create.e2e.ts
@@ -187,6 +187,7 @@ async function installDelayedDesktopSessionBridge(
onShareReceived: () => unsubscribe,
onServerVersionDrift: () => unsubscribe,
onServerRestarted: () => unsubscribe,
+ onServerReclaimed: () => unsubscribe,
restartServer: async () => ({ ok: true }),
dialog: {
openFolder: async () => null,
diff --git a/packages/app/tests/stress/fixtures/handoff-mocks.ts b/packages/app/tests/stress/fixtures/handoff-mocks.ts
index 4ba626861..df6414fbb 100644
--- a/packages/app/tests/stress/fixtures/handoff-mocks.ts
+++ b/packages/app/tests/stress/fixtures/handoff-mocks.ts
@@ -220,6 +220,7 @@ export async function installHandoffMocks(page: Page, cfg: HandoffMockConfig): P
onShareReceived: () => () => {},
onServerVersionDrift: () => () => {},
onServerRestarted: () => () => {},
+ onServerReclaimed: () => () => {},
restartServer: async () => ({ ok: true as const }),
setThemeSource: async (): Promise<{ ok: true }> => ({ ok: true }),
signalThemeApplied: (): void => {},
diff --git a/packages/core/src/desktop-bridge.ts b/packages/core/src/desktop-bridge.ts
index 0f994a70f..70be8e9b8 100644
--- a/packages/core/src/desktop-bridge.ts
+++ b/packages/core/src/desktop-bridge.ts
@@ -389,6 +389,10 @@ export interface OkServerRestartedInfo {
readonly appRuntime: string;
}
+export interface OkServerReclaimedInfo {
+ readonly appRuntime: string;
+}
+
export type OkServerRestartOutcome =
| { readonly ok: true }
| { readonly ok: false; readonly reason: 'eperm' | 'other' };
@@ -408,6 +412,7 @@ export interface OkDesktopBridge {
onServerVersionDrift(cb: (info: OkServerVersionDriftInfo) => void): OkUnsubscribe;
onServerRestarted(cb: (info: OkServerRestartedInfo) => void): OkUnsubscribe;
+ onServerReclaimed(cb: (info: OkServerReclaimedInfo) => void): OkUnsubscribe;
restartServer(projectPath: string): Promise<OkServerRestartOutcome>;
setThemeSource(source: OkThemeSource): Promise<{ ok: true }>;
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index ca1b35ba0..d88442d70 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -550,6 +550,7 @@ function ensureWindowManager() {
appVersion: app.getVersion(),
selfProtocolVersion: PROTOCOL_VERSION,
selfRuntimeVersion: RUNTIME_VERSION,
+ reclaimForeignServerInDev: !app.isPackaged,
setTimeout: (cb, ms) => setTimeout(cb, ms),
killProbe: (pid, signal) => {
process.kill(pid, signal as NodeJS.Signals | 0);
diff --git a/packages/desktop/src/main/window-manager.ts b/packages/desktop/src/main/window-manager.ts
index 05df40a2e..dcb28b88a 100644
--- a/packages/desktop/src/main/window-manager.ts
+++ b/packages/desktop/src/main/window-manager.ts
@@ -119,6 +119,7 @@ export interface WindowManagerDeps {
appVersion: string;
selfProtocolVersion?: number;
selfRuntimeVersion?: string;
+ reclaimForeignServerInDev?: boolean;
setTimeout(cb: () => void, ms: number): unknown;
killProbe(pid: number, signal: number | NodeJS.Signals): void;
showGate: ShowGateRegistry;
@@ -394,18 +395,50 @@ export class WindowManager {
const candidate = this.tryAttachExistingServer(lockDir);
const attached =
candidate !== null && (await this.probeAttachableLock(candidate)) ? candidate : null;
+ let pendingServerReclaimedToast = false;
if (attached) {
- return this.attachToExistingServer({
- projectPath,
- canonicalKey,
- projectName,
- lock: attached,
- pendingDeepLinkDoc: opts.pendingDeepLinkDoc,
- pendingBranch: opts.pendingBranch,
- pendingMultiCandidate: opts.pendingMultiCandidate,
- pendingShareBranchSwitch: opts.pendingShareBranchSwitch,
- pendingServerRestartedToast: opts.pendingServerRestartedToast,
- });
+ const isForeign = this.spawnedDetachedPids.get(canonicalKey) !== attached.pid;
+ let reclaimed = false;
+ if (this.deps.reclaimForeignServerInDev === true && isForeign) {
+ const term = await this.terminateServerByPid(lockDir, attached.pid);
+ if (term.ok) {
+ this.deps.log?.info(
+ {
+ event: 'desktop-dev-reclaim',
+ outcome: 'terminated',
+ escalated: term.escalated,
+ pid: attached.pid,
+ projectPath,
+ },
+ '[window-manager] dev-mode reclaimed foreign server; spawning fresh own-build server',
+ );
+ reclaimed = true;
+ } else {
+ this.deps.log?.warn(
+ {
+ event: 'desktop-dev-reclaim',
+ outcome: term.reason,
+ pid: attached.pid,
+ projectPath,
+ },
+ '[window-manager] dev-mode reclaim could not terminate the foreign server; attaching to it instead',
+ );
+ }
+ }
+ if (!reclaimed) {
+ return this.attachToExistingServer({
+ projectPath,
+ canonicalKey,
+ projectName,
+ lock: attached,
+ pendingDeepLinkDoc: opts.pendingDeepLinkDoc,
+ pendingBranch: opts.pendingBranch,
+ pendingMultiCandidate: opts.pendingMultiCandidate,
+ pendingShareBranchSwitch: opts.pendingShareBranchSwitch,
+ pendingServerRestartedToast: opts.pendingServerRestartedToast,
+ });
+ }
+ pendingServerReclaimedToast = true;
}
if (this.deps.runClean) {
@@ -608,6 +641,15 @@ export class WindowManager {
});
}
+ if (pendingServerReclaimedToast) {
+ registerPendingDelivery(
+ window.webContents,
+ 'ok:server-reclaimed',
+ { appRuntime: this.deps.appVersion },
+ { event: 'did-finish-load' },
+ );
+ }
+
const disposeShowGate = this.deps.showGate.register(window, { kind: 'editor' });
if (this.deps.rendererDevUrl) {
diff --git a/packages/desktop/src/preload/index.ts b/packages/desktop/src/preload/index.ts
index f89c7c2b6..c04ad26be 100644
--- a/packages/desktop/src/preload/index.ts
+++ b/packages/desktop/src/preload/index.ts
@@ -10,6 +10,7 @@ import type {
OkMcpWiringShowPayload,
OkMenuAction,
OkOnboardingShowPayload,
+ OkServerReclaimedInfo,
OkServerRestartedInfo,
OkServerVersionDriftInfo,
OkShareReceivedPayload,
@@ -225,6 +226,13 @@ const bridge: OkDesktopBridge = {
return () => ipcRenderer.removeListener('ok:server-restarted', listener);
},
+ onServerReclaimed(cb: (info: OkServerReclaimedInfo) => void) {
+ const listener = (_event: IpcRendererEvent, info: OkServerReclaimedInfo) => cb(info);
+ // biome-ignore lint/plugin/no-loosely-typed-webcontents-ipc: preload-side subscription wrapper (precedent #14)
+ ipcRenderer.on('ok:server-reclaimed', listener);
+ return () => ipcRenderer.removeListener('ok:server-reclaimed', listener);
+ },
+
restartServer: (projectPath: string) => invoke('ok:project:restart-server', projectPath),
setThemeSource: (source: OkThemeSource) => invoke('ok:theme:set-source', { source }),
diff --git a/packages/desktop/src/shared/bridge-contract.ts b/packages/desktop/src/shared/bridge-contract.ts
index 8ff758590..40004f932 100644
--- a/packages/desktop/src/shared/bridge-contract.ts
+++ b/packages/desktop/src/shared/bridge-contract.ts
@@ -378,6 +378,10 @@ export interface OkServerRestartedInfo {
readonly appRuntime: string;
}
+export interface OkServerReclaimedInfo {
+ readonly appRuntime: string;
+}
+
export type OkServerRestartOutcome =
| { readonly ok: true }
| { readonly ok: false; readonly reason: 'eperm' | 'other' };
@@ -397,6 +401,7 @@ export interface OkDesktopBridge {
onServerVersionDrift(cb: (info: OkServerVersionDriftInfo) => void): OkUnsubscribe;
onServerRestarted(cb: (info: OkServerRestartedInfo) => void): OkUnsubscribe;
+ onServerReclaimed(cb: (info: OkServerReclaimedInfo) => void): OkUnsubscribe;
restartServer(projectPath: string): Promise<OkServerRestartOutcome>;
setThemeSource(source: OkThemeSource): Promise<{ ok: true }>;
diff --git a/packages/desktop/src/shared/ipc-events.ts b/packages/desktop/src/shared/ipc-events.ts
index 37faa704b..3a0a8cf8e 100644
--- a/packages/desktop/src/shared/ipc-events.ts
+++ b/packages/desktop/src/shared/ipc-events.ts
@@ -3,6 +3,7 @@ import type {
OkLocalOpAuthEvent,
OkLocalOpCloneEvent,
OkMenuAction,
+ OkServerReclaimedInfo,
OkServerRestartedInfo,
OkServerVersionDriftInfo,
OkShareReceivedPayload,
@@ -76,4 +77,5 @@ export interface EventChannels {
'ok:server-version-drift': { payload: OkServerVersionDriftInfo };
'ok:server-restarted': { payload: OkServerRestartedInfo };
+ 'ok:server-reclaimed': { payload: OkServerReclaimedInfo };
}
diff --git a/packages/desktop/tests/main/window-manager.test.ts b/packages/desktop/tests/main/window-manager.test.ts
index 1dc5453bb..efb0abc11 100644
--- a/packages/desktop/tests/main/window-manager.test.ts
+++ b/packages/desktop/tests/main/window-manager.test.ts
@@ -753,6 +753,108 @@ describe('WindowManager', () => {
expect(env.windows.length).toBe(1);
});
+ test('reclaimForeignServerInDev terminates a foreign server and spawns fresh via utility-fork, firing ok:server-reclaimed on did-finish-load', async () => {
+ env.deps.reclaimForeignServerInDev = true;
+ let killed = false;
+ const killProbe = mock((_pid: number, signal: string) => {
+ if (signal === 'SIGTERM') killed = true;
+ });
+ env.deps.killProbe = killProbe;
+ enableAttachProbe({ readServerLock: () => (killed ? null : liveLock) });
+
+ const wm = new WindowManager(env.deps);
+ const promise = wm.createProjectWindow({ projectPath: '/tmp/dragon' });
+ for (let i = 0; i < 50 && env.utilities.length === 0; i++) await wait(0);
+ expect(killProbe).toHaveBeenCalledWith(65792, 'SIGTERM');
+ expect(env.utilities.length).toBe(1);
+ env.utilities[0]?.fire({ type: 'ready', port: 52777, apiOrigin: 'http://localhost:52777' });
+ const ctx = await promise;
+
+ expect(ctx.ownsServer).toBe(true);
+ expect(ctx.port).toBe(52777);
+
+ const w = env.windows[0];
+ if (!w) throw new Error('no window created');
+ const reclaimSends = () =>
+ (w.webContents.send as ReturnType<typeof mock>).mock.calls.filter(
+ (c: unknown[]) => c[0] === 'ok:server-reclaimed',
+ );
+ expect(reclaimSends().length).toBe(0);
+ w.fireDomReady();
+ expect(reclaimSends().length).toBe(0);
+ w.fireDidFinishLoad();
+ expect(reclaimSends().length).toBe(1);
+ expect((reclaimSends()[0] as unknown[])[1]).toEqual({ appRuntime: '9.9.9-test' });
+ });
+
+ test('without reclaimForeignServerInDev (production default), a foreign server is attached — no termination, no reclaim notice', async () => {
+ const killProbe = mock(() => {});
+ env.deps.killProbe = killProbe;
+ enableAttachProbe();
+ const wm = new WindowManager(env.deps);
+ const ctx = await wm.createProjectWindow({ projectPath: '/tmp/dragon' });
+ expect(ctx.ownsServer).toBe(false);
+ expect(ctx.port).toBe(59534);
+ expect(env.utilities.length).toBe(0);
+ expect(killProbe).not.toHaveBeenCalled();
+ const w = env.windows[0];
+ if (!w) throw new Error('no window created');
+ w.fireDidFinishLoad();
+ const reclaimSends = (w.webContents.send as ReturnType<typeof mock>).mock.calls.filter(
+ (c: unknown[]) => c[0] === 'ok:server-reclaimed',
+ );
+ expect(reclaimSends.length).toBe(0);
+ });
+
+ test('reclaim does NOT terminate a server THIS session spawned (own-pid guard)', async () => {
+ env.deps.reclaimForeignServerInDev = true;
+ const killProbe = mock(() => {});
+ env.deps.killProbe = killProbe;
+ const ownLock = { ...liveLock, pid: 6666, port: 60000 };
+ let spawned = false;
+ env.deps.spawnDetachedServer = async () => {
+ spawned = true;
+ return { pid: 6666 };
+ };
+ env.deps.spawnLockPollDeadlineMs = 1000;
+ enableAttachProbe({ readServerLock: () => (spawned ? ownLock : null) });
+
+ const wm = new WindowManager(env.deps);
+ const ctx1 = await wm.createProjectWindow({ projectPath: '/tmp/dragon' });
+ expect(ctx1.port).toBe(60000);
+ expect(env.windows.length).toBe(1);
+
+ env.windows[0]?.fireClose();
+
+ const ctx2 = await wm.createProjectWindow({ projectPath: '/tmp/dragon' });
+ expect(killProbe).not.toHaveBeenCalled();
+ expect(ctx2.ownsServer).toBe(false); // attached to our own server
+ expect(ctx2.port).toBe(60000);
+ expect(env.utilities.length).toBe(0); // attached, did not reclaim-and-respawn
+ });
+
+ test('reclaim falls back to attaching when terminating the foreign server fails (eperm)', async () => {
+ env.deps.reclaimForeignServerInDev = true;
+ env.deps.killProbe = mock(() => {
+ const err = new Error('operation not permitted') as NodeJS.ErrnoException;
+ err.code = 'EPERM';
+ throw err;
+ });
+ enableAttachProbe();
+ const wm = new WindowManager(env.deps);
+ const ctx = await wm.createProjectWindow({ projectPath: '/tmp/dragon' });
+ expect(ctx.ownsServer).toBe(false);
+ expect(ctx.port).toBe(59534);
+ expect(env.utilities.length).toBe(0);
+ const w = env.windows[0];
+ if (!w) throw new Error('no window created');
+ w.fireDidFinishLoad();
+ const reclaimSends = (w.webContents.send as ReturnType<typeof mock>).mock.calls.filter(
+ (c: unknown[]) => c[0] === 'ok:server-reclaimed',
+ );
+ expect(reclaimSends.length).toBe(0);
+ });
+
test('stale lock (pid dead) falls through to spawn mode', async () => {
enableAttachProbe({ isProcessAlive: () => false });
const runClean = mock(() => Promise.resolve());