Skip to content

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.

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.md
index 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 retries
after 1 s, 2 s, 4 s and so on, capped at 30 s. Both server shutdown paths write what is pending
before 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 is
read from the saved canvas.
diff --git a/src/core/workspace-store.content-authority.test.ts b/src/core/workspace-store.content-authority.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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()))