Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(server): no browser save lands un-overlaid while the authority stops (N3)
review0103e2706341
diff --git a/docs/hosted-team-relay.md b/docs/hosted-team-relay.mdindex 6dc8da340..9365bbc6f 100644--- a/docs/hosted-team-relay.md+++ b/docs/hosted-team-relay.md@@ -369,6 +369,9 @@ bumps `rev` like a save, and the file is byte-identical to a save's apart from `A failed write keeps every op and retriesafter 1 s, 2 s, 4 s and so on, capped at 30 s. Both server shutdown paths write what is pendingbefore they exit, so a crash loses only what was not written yet: normally at most the last 5 s.+Before the authority stops, the shutdown ends the browser connections and waits for the saves+already queued (`WorkspaceStore.idle`): a save that ran after the authority was detached would be+written un-overlaid, over its final write.Viewers can watch a terminal an Editor opened once its node is written, because node membership isread from the saved canvas.diff --git a/src/core/workspace-store.content-authority.test.ts b/src/core/workspace-store.content-authority.test.tsindex 0956a0da1..1d03bcacd 100644--- a/src/core/workspace-store.content-authority.test.ts+++ b/src/core/workspace-store.content-authority.test.ts@@ -178,6 +178,45 @@ describe('the save overlay', () => {})})+// N3: the Server Edition's close stops the authority and detaches it. A browser save queued before+// that (still on `saveChain`, behind a slow write) would otherwise run AFTER the detach and write its+// stale content un-overlaid over the final flush. The shell awaits `idle()` first.+describe('idle', () => {+ it('resolves only once every write queued so far has landed, still overlaid', async () => {+ const store = new WorkspaceStore()+ let release!: () => void+ const held = new Promise<void>((r) => (release = r))+ store.setContentAuthority({+ overlaySave: async (w) => {+ await held+ return { ...w, projects: w.projects.map((p) => (p.id === 'P' ? { ...p, nodes: [node('b')] } : p)) }+ },+ overlayLoad: async (w) => w+ })+ const save = store.save(ws([project({ cwd: projRoot, nodes: [node('a')] })]))+ let idle = false+ const idled = store.idle().then(() => {+ idle = true+ })+ await new Promise((r) => setTimeout(r, 20))+ expect(idle).toBe(false)+ release()+ await idled+ // Detached only now, as the shell does once the authority has stopped: nothing queued is left+ // to be written un-overlaid.+ store.setContentAuthority(null)+ await save+ expect(ids((await readJson(projectFile())).nodes)).toEqual(['b'])+ })++ it('never rejects, even when a queued write failed', async () => {+ const store = new WorkspaceStore()+ store.setContentAuthority({ overlaySave: async () => { throw new Error('overlay down') }, overlayLoad: async (w) => w })+ await expect(store.save(ws([project({ cwd: projRoot })]))).rejects.toThrow('overlay down')+ await expect(store.idle()).resolves.toBeUndefined()+ })+})+describe('the load overlay', () => {it('rewrites the load result only; the file is untouched', async () => {const store = new WorkspaceStore()diff --git a/src/core/workspace-store.ts b/src/core/workspace-store.tsindex 3c9b0898e..6c2e6cf21 100644--- a/src/core/workspace-store.ts+++ b/src/core/workspace-store.ts@@ -1100,6 +1100,16 @@ export class WorkspaceStore {* save made every new agent node on an SSH project sit on QUEUED for seconds. It still runs on* the FIFO chain, so ordering against every other save is unchanged.*/+ /**+ * Resolves once every write queued on `saveChain` so far (saves, content writes, reconciles) has+ * finished, landed or failed; never rejects. The Server Edition's close awaits it BEFORE it stops+ * the content authority: a browser save still queued behind a slow write would otherwise run after+ * the authority was detached and write its stale content un-overlaid over the final flush.+ */+ idle(): Promise<void> {+ return this.saveChain.then(() => undefined)+ }+save(workspace: Workspace, opts: WorkspaceSaveOptions = {}): Promise<void> {const run = this.saveChain.then(() => this.saveNow(workspace, opts.localOnly === true))this.saveChain = run.catch(() => {})diff --git a/src/server/hosted-boot.test.ts b/src/server/hosted-boot.test.tsindex ebef53d28..6d7d1552b 100644--- a/src/server/hosted-boot.test.ts+++ b/src/server/hosted-boot.test.ts@@ -73,6 +73,20 @@ describe('hosted team boot wiring (source)', () => {expect(body.indexOf('workspaceStore.setContentAuthority(null)')).toBeGreaterThan(stop)}expect(src.match(/canvasAuthority\?\.stop\(\)/g)?.length).toBe(2)+ // N3: once the authority has stopped (and is detached), a save is written un-overlaid, so every+ // save must be in before it stops. Both closes wait for the saves already queued (`idle`); the+ // serving close ends its browser WebSockets first, so no new one can arrive.+ for (const at of closes) {+ const body = src.slice(at, src.indexOf('await ptyManager.killAll()', at))+ const idle = body.indexOf('await workspaceStore.idle()')+ expect(idle, 'await workspaceStore.idle()').toBeGreaterThan(-1)+ expect(idle).toBeLessThan(body.indexOf('await canvasAuthority?.stop()'))+ }+ const serving = src.slice(closes[1], src.indexOf('await canvasAuthority?.stop()', closes[1]))+ const terminate = serving.indexOf('for (const client of wsServer.clients) client.terminate()')+ expect(terminate, 'browser WebSockets end before the authority stops').toBeGreaterThan(-1)+ expect(terminate).toBeLessThan(serving.indexOf('await workspaceStore.idle()'))+ expect(src.match(/for \(const client of wsServer\.clients\) client\.terminate\(\)/g)?.length).toBe(1)})it('the canvas authority exists only where this process owns the team, and adopts at boot (R12a)', () => {diff --git a/src/server/index.ts b/src/server/index.tsindex aea9272c3..7205ad4a7 100644--- a/src/server/index.ts+++ b/src/server/index.ts@@ -1011,6 +1011,8 @@ export async function startServer(canvasControl?.stop()workspaceWatcher.dispose()await contextLink.stop()+ // Every save already queued lands while the authority still governs (see the serving close).+ await workspaceStore.idle()// Write what the canvas authority still owes, then detach it from the reflector and the store.await canvasAuthority?.stop()setReflectedListener(null)@@ -1066,6 +1068,13 @@ export async function startServer(// headless close() above).await teamAdmin.close()hosted.stop()+ // End the browser WebSockets next, BEFORE the canvas authority stops (N3). Once it has stopped+ // and been detached, a save from a still-attached tab is written un-overlaid, over its final+ // flush. Ending the sockets stops new saves; the `idle()` below lets the ones already queued+ // land while it still governs. (Upgraded WebSockets are not ordinary HTTP connections:+ // server.close() waits for them but does not end them, so this is also what keeps a client+ // close racing shutdown from hanging the Server Edition, or its tests.)+ for (const client of wsServer.clients) client.terminate()// Detach PTY clients — tmux sessions keep running (Phase 1 contract; never kill the server).sessionReaper.stop()pressure.stop()@@ -1073,6 +1082,8 @@ export async function startServer(canvasControl?.stop()workspaceWatcher.dispose()await contextLink.stop()+ // Every save already queued lands while the authority still governs, then it writes what it owes.+ await workspaceStore.idle()// Write what the canvas authority still owes (see the headless close() above).await canvasAuthority?.stop()setReflectedListener(null)@@ -1083,10 +1094,7 @@ export async function startServer(await speechService.shutdown()// Close the loopback hook-server listener (it would otherwise die with the process anyway).hookServer.stop()- // Upgraded WebSockets are not ordinary HTTP connections: server.close() waits for them but- // does not end them. Own the WS lifecycle explicitly so a client close racing shutdown- // cannot hang the Server Edition (or its tests) forever.- for (const client of wsServer.clients) client.terminate()+ // The WebSockets were ended at the top; close the WS server itself, then the HTTP server.await new Promise<void>((resolve) => wsServer.close(() => resolve()))await new Promise<void>((resolve, reject) => {server.close((err) => (err ? reject(err) : resolve()))