Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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; restartRejbridge: 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; restartRejrestartedCb = 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.tsindex 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.tsindex 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.tsindex 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): PonShareReceived: () => () => {},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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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());