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
test(server): shared canvas edits persist on a headless hosted core
reviewcfb4f2bd8ff0
diff --git a/src/server/hosted-e2e.test.ts b/src/server/hosted-e2e.test.tsindex acf00630a..8605e0655 100644--- a/src/server/hosted-e2e.test.ts+++ b/src/server/hosted-e2e.test.ts@@ -8,7 +8,10 @@// workspace) team init → add-owner → share → the owner joins (auto-approved) and opens a terminal → a guest// knocks and waits → the owner approves it as a viewer → the viewer joins the owner's live// session, cannot start one, cannot write a file, cannot read the enclosing repository through git-// → `team status` lists it as a connected viewer → `team unshare` silences its terminal.+// → `team status` lists it as a connected viewer → the canvas authority (no browser attached):+// the owner's canvas ops are written to the shared project's file by this core, the viewer hears+// them and cannot cast one, an outside edit of the file reaches the owner as ops → `team unshare`+// silences the viewer's terminal → a restart on the same data dir keeps every edit.//// What is real and what is not:// - REAL: startServer and every core service it boots, the admin unix socket and its client, the@@ -24,9 +27,13 @@//// No sleeps: every step waits on an event it is owed (a transport the scheduler opened, a frame, an// approval, pty bytes). `step()` puts a deadline on each wait ONLY so that a hang fails with that-// step's name instead of the test timeout; nothing ever waits on the clock to succeed.+// step's name instead of the test timeout; nothing ever waits on the clock to succeed. The one wait+// that polls is the project file (`projectFileWhen`): the authority's flush is a disk write, and no+// client is sent an event for it. It polls every 100 ms under a step deadline.//-// ONE startServer per file (see hosted-boot.test.ts: some core paths are memoized per process).+// One data dir per file (see hosted-boot.test.ts: some core paths are memoized per process, so a+// boot on ANOTHER data dir would write into this one). The restart boots a second server on the+// SAME data dir, which is exactly where those memoized paths already point.import { describe, it, expect, vi, afterEach, afterAll } from 'vitest'import { execFileSync } from 'node:child_process'import fs from 'node:fs'@@ -36,6 +43,8 @@ import { startServer } from './index'import { initPlatform, resetPlatformForTests } from '../core/platform'import { fakePlatform } from '../core/platform-fake'import { WorkspaceStore } from '../core/workspace-store'+import { writeFileAtomic } from '../core/fs-atomic'+import type { ProjectFileV1 } from '../core/workspace-files'import { callTeamAdmin, type AdminInitResult, type AdminReply, type AdminStatusResult } from '../core/relay/team-admin'import { transportPair } from '../core/relay/transport-pair'import { connectRelayClient, type RelayClientSession } from '../core/relay/relay-client'@@ -43,7 +52,9 @@ import { decodeJoinCode, type JoinCode } from '../core/relay/join-code'import { genKeyPair, publicKeyToB64, type KeyPair } from '../core/relay/e2ee'import type { RelayTransport } from '../core/relay/relay-socket'import { IPC } from '../shared/ipc'-import type { CanvasNodeState, Project, PtyCreateResult, Workspace } from '../shared/types'+import { mutationKey } from '../shared/canvas-order'+import { seededColumnId } from '../shared/kanban-default-board'+import type { CanvasMutation, CanvasNodeState, Project, PtyCreateResult, Workspace } from '../shared/types'// A broken seam must fail HERE, never reach production. index.ts reads NODETERM_RELAY_URL at module// load (hoisted above the imports): if `relayTestTransport` ever stopped being plumbed through, the@@ -107,11 +118,12 @@ const SECRET = 'term-e2e-secret' // in a project that is not sharedconst pub = (k: KeyPair): string => publicKeyToB64(k.publicKey)-/** Fail with the step's NAME if its event never comes. A bound on a hang, never a success condition. */-function step<T>(name: string, p: Promise<T>): Promise<T> {+/** Fail with the step's NAME if its event never comes. A bound on a hang, never a success condition+ * (except where a caller passes a tighter `ms` because the bound IS the claim, e.g. a flush). */+function step<T>(name: string, p: Promise<T>, ms: number = STEP_MS): Promise<T> {let timer: ReturnType<typeof setTimeout> | undefinedconst deadline = new Promise<never>((_, reject) => {- timer = setTimeout(() => reject(new Error(`step "${name}" never completed`)), STEP_MS)+ timer = setTimeout(() => reject(new Error(`step "${name}" never completed`)), ms)})return Promise.race([p, deadline]).finally(() => clearTimeout(timer))}@@ -134,6 +146,24 @@ function fifo<T>() {type Frame = { t: string; id?: number; ok?: boolean; result?: unknown; error?: { code: string; message: string }; channel?: string; args?: unknown[] }+/** The canvas op a frame carries, when it is a `canvas:mut` event for `projectId` (args = [projectId, op]). */+function mutOf(f: Frame, projectId: string = SHARED): CanvasMutation | null {+ if (f.t !== 'ev' || f.channel !== IPC.canvasMut || f.args?.[0] !== projectId) return null+ const m = f.args[1]+ return m && typeof m === 'object' ? (m as CanvasMutation) : null+}++/** The order key of the canvas op a frame carries (`mutationKey`), or null for any other frame. */+const mutKeyOf = (f: Frame, projectId: string = SHARED): string | null => {+ const m = mutOf(f, projectId)+ return m ? mutationKey(m, projectId) : null+}++/** A fire-and-forget cast over the E2EE tunnel. A canvas op has no reply: its reflection is its ack. */+function cast(conn: RelayClientSession, method: string, args: unknown[]): boolean {+ return conn.send(JSON.stringify({ t: 'cast', method, args }))+}+/** A teammate's desktop, as far as the host can tell: core `connectRelayClient` (what the desktop* joiner runs) over one of the host's listeners. `pinned` = a bookmarked, already-approved host* (auto-confirm); otherwise the human compares the SAS and confirms at once. */@@ -189,6 +219,8 @@ function teammate(code: JoinCode, transport: RelayTransport, keys: KeyPair, pinnapproved,denied,received,+ /** Every frame received, in arrival order (one tunnel delivers in order). */+ frames: frames as readonly Frame[],/** One RPC round trip over the E2EE tunnel. */call(method: string, args: unknown[] = []): Promise<Frame> {const id = nextId++@@ -200,6 +232,14 @@ function teammate(code: JoinCode, transport: RelayTransport, keys: KeyPair, pinnevent(channel: string, match: (payload: Record<string, unknown>) => boolean = () => true): Promise<Frame> {return waitFrame((f) => f.t === 'ev' && f.channel === channel && match((f.args?.[0] ?? {}) as Record<string, unknown>))},+ /** The first reflected `canvas:mut` of the shared project whose op is `op` and whose order key+ * is `key` (`mutationKey`), and that passes `where` when given. One already received counts. */+ mut(op: CanvasMutation['op'], key: string, where: (m: CanvasMutation) => boolean = () => true): Promise<Frame> {+ return waitFrame((f) => {+ const m = mutOf(f)+ return !!m && m.op === op && mutationKey(m, SHARED) === key && where(m)+ })+ },/** The next terminal output for `sessionId`. */bytes(sessionId: string): Promise<string> {return new Promise((resolve) => byteWaiters.push({ sessionId, resolve }))@@ -254,6 +294,53 @@ function repoWithSecret(base: string): { repo: string; shared: string } {return { repo, shared: path.join(repo, 'shared') }}+/** A folder project's committed file. */+const projectFilePath = (cwd: string): string => path.join(cwd, '.nodeterm', 'project.json')++/** A folder project's committed file as it is on disk now, raw and parsed. Throws if unreadable. */+function readProjectFile(cwd: string): { raw: string; file: ProjectFileV1 } {+ const raw = fs.readFileSync(projectFilePath(cwd), 'utf8')+ return { raw, file: JSON.parse(raw) as ProjectFileV1 }+}++/**+ * Read a project file every 100 ms until `ready` holds, under a step deadline, and return that read.+ * The one polling wait in this file: the authority's flush is a disk write no client hears about.+ * A file that cannot be read or parsed yet (mid-rename) is simply not ready.+ */+async function projectFileWhen(+ name: string,+ cwd: string,+ ready: (raw: string, file: ProjectFileV1) => boolean,+ ms: number = STEP_MS+): Promise<ProjectFileV1> {+ let timer: ReturnType<typeof setInterval> | undefined+ const found = new Promise<ProjectFileV1>((resolve) => {+ const look = (): void => {+ let read: { raw: string; file: ProjectFileV1 }+ try {+ read = readProjectFile(cwd)+ } catch {+ return+ }+ if (!ready(read.raw, read.file)) return+ clearInterval(timer)+ resolve(read.file)+ }+ timer = setInterval(look, 100)+ look()+ })+ try {+ return await step(name, found, ms)+ } finally {+ clearInterval(timer)+ }+}++/** A node's position in a project file or a loaded project (undefined = no such node). */+const positionOf = (nodes: CanvasNodeState[] | undefined, id: string): CanvasNodeState['position'] | undefined =>+ nodes?.find((n) => n.id === id)?.position+async function admin<T>(dataDir: string, req: Parameters<typeof callTeamAdmin>[1]): Promise<T> {const r: AdminReply = await step(`team ${req.cmd}`, callTeamAdmin(dataDir, req))if (!r.ok) throw new Error(`team ${req.cmd} failed: ${r.error}`)@@ -281,7 +368,7 @@ afterAll(() => {// The admin channel is a unix socket, which Windows does not have (team-admin.ts refuses it by// name there), so no hosted team can be set up on that platform. Linux and macOS run it.describe.skipIf(process.platform === 'win32')('hosted team relay, end to end on a headless server', () => {- it('admin setup → owner auto-approved → guest waits → approved as viewer → watches the owner’s terminal, starts none, writes nothing', async () => {+ it('admin setup → owner auto-approved → guest waits → approved as viewer → watches the owner’s terminal, starts none, writes nothing → shared canvas edits persist with no browser attached and survive a restart', async () => {spawned.length = 0const dataDir = fs.mkdtempSync(path.join(SHORT_BASE, 'nthe-'))teardown.push(() => fs.rmSync(dataDir, { recursive: true, force: true }))@@ -289,8 +376,9 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end onfs.writeFileSync(path.join(dataDir, 'settings.json'), JSON.stringify({ tmuxEnabled: false }))// The relay: each listener the scheduler opens is one in-process transport pair, and its peer end- // is handed to whichever teammate connects next — the relay's pairing, minus the network.- const listeners = fifo<RelayTransport>()+ // is handed to whichever teammate connects next — the relay's pairing, minus the network. A fresh+ // queue per boot (step 9): the listeners a closed server opened are dead ends.+ let listeners = fifo<RelayTransport>()const relayTestTransport = (): RelayTransport => {const { hostT, peerT } = transportPair()listeners.push(peerT)@@ -329,7 +417,8 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end onresetPlatformForTests()}- const booting = startServer({+ // Both boots (step 9 restarts on the same data dir) take this config.+ const config: Parameters<typeof startServer>[0] = {port: 0,host: '127.0.0.1',dataDir,@@ -340,13 +429,17 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end oninstallHooks: false,relayTestTransport,relayTestFetch- })+ }+ const booting = startServer(config)// Registered BEFORE the boot is awaited: a boot that outlives its step deadline is still closed// once it lands, instead of leaking a server (and its admin socket) into the next test. The wait// is itself a step: a boot that never settles must not hang afterEach, or the teardowns- // registered before this one (the repository and data dirs) would never run.- teardown.push(() => step('server teardown', booting.catch(() => null).then((s) => s?.close())))- const srv = await step('server boot', booting)+ // registered before this one (the repository and data dirs) would never run. Closed ONCE: step 9+ // closes this server itself, and the teardown then only waits for that close.+ let closing: Promise<void> | undefined+ const closeFirstServer = (): Promise<void> => (closing ??= booting.catch(() => null).then((s) => s?.close()))+ teardown.push(() => step('server teardown', closeFirstServer()))+ await step('server boot', booting)// After the boot, so the log sink the server installs is what this spy calls through to.const warn = vi.spyOn(console, 'warn')teardown.push(() => warn.mockRestore())@@ -469,6 +562,103 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end onexpect(owner.denied).toEqual([])expect(guest.denied).toEqual([])+ // ---- 7a. The canvas authority, with no browser attached: this core is the one writer of the+ // shared project's content. The owner's edits travel as canvas ops, which the authority applies+ // in the reflector's order and writes into the project's own file.+ const column2 = seededColumnId(SHARED, 1)+ const moved: CanvasMutation = { op: 'upsert', node: terminalNode(LIVE, 321), src: 'owner-e2e' }+ const bridged: CanvasMutation = {+ op: 'edge-upsert',+ kind: 'bridge',+ edge: { id: 'bridge-e2e', source: LIVE, target: IDLE },+ src: 'owner-e2e'+ }+ const carded: CanvasMutation = { op: 'kb-card', assignment: { nodeId: LIVE, columnId: column2 }, src: 'owner-e2e' }+ const ownerOps = [moved, bridged, carded]+ for (const m of ownerOps) expect(cast(owner.c, IPC.canvasMut, [SHARED, m]), `${m.op} cast`).toBe(true)+ // Each op's reflection is its ack: the reflector stamped it, so the authority has applied it (the+ // reflector hands a stamped op to the authority synchronously, before it fans it out).+ for (const m of ownerOps) {+ const ack = mutOf(await step(`the owner’s ${m.op} is reflected`, owner.mut(m.op, mutationKey(m, SHARED))))+ expect(ack, m.op).toMatchObject({ ...m, seq: expect.any(Number) })+ }+ // The flush lands within its bound (1 s after the last op, 5 s at most) with nobody saving: read+ // the file until it holds the bridge.+ const flushed = await projectFileWhen(+ 'the authority writes the shared project',+ sharedCwd,+ (raw) => raw.includes('bridge-e2e'),+ 6_000+ )+ expect(positionOf(flushed.nodes, LIVE)).toEqual({ x: 321, y: 0 })+ expect(flushed.bridges).toContainEqual({ id: 'bridge-e2e', source: LIVE, target: IDLE })+ // The card, in the SECOND column of the project's lazy default board (seeded, so every client+ // and the authority name the same three columns).+ expect(flushed.kanban?.columns.map((c) => c.id)[1]).toBe(column2)+ expect(flushed.kanban?.assignments).toContainEqual(expect.objectContaining({ nodeId: LIVE, columnId: column2 }))+ // The viewer is a client of the same total order: it heard all three.+ for (const m of ownerOps) {+ await step(`the viewer receives the ${m.op}`, guest.mut(m.op, mutationKey(m, SHARED)))+ }++ // A viewer cannot write the canvas: its cast is refused before the reflector, so nobody (not the+ // viewer, not the owner, not the authority) ever hears of it.+ const viewerCard: CanvasMutation = {+ op: 'kb-card',+ assignment: { nodeId: IDLE, columnId: seededColumnId(SHARED, 0) },+ src: 'viewer-e2e'+ }+ const viewerKey = mutationKey(viewerCard, SHARED)+ expect(cast(guest.c, IPC.canvasMut, [SHARED, viewerCard])).toBe(true)+ // One round trip on the viewer's own tunnel: the host has handled everything the viewer sent+ // before this answer, the cast included (a cast is served synchronously, in arrival order).+ expect(await guest.call(IPC.relayHostedSelf)).toMatchObject({ ok: true, result: { role: 'viewer' } })+ // So a marker the owner casts NOW is stamped after the viewer's op would have been. Each tunnel+ // delivers in order, so a reflected viewer op would reach both peers before the marker does.+ const marker: CanvasMutation = { op: 'upsert', node: terminalNode(IDLE, 777), src: 'owner-e2e' }+ const markerKey = mutationKey(marker, SHARED)+ expect(cast(owner.c, IPC.canvasMut, [SHARED, marker])).toBe(true)+ const isMarker = (m: CanvasMutation): boolean => m.op === 'upsert' && m.node.position.x === 777+ for (const [who, peer] of [['owner', owner], ['viewer', guest]] as const) {+ const markerFrame = await step(`the ${who} receives the marker`, peer.mut('upsert', markerKey, isMarker))+ const before = peer.frames.slice(0, peer.frames.indexOf(markerFrame))+ expect(before.filter((f) => mutKeyOf(f) === viewerKey), `the ${who} heard the viewer’s card`).toEqual([])+ }+ // Nor does the file: once the NEXT flush has written the marker, the viewer's card is not there+ // (and the owner's card still is).+ const afterMarker = await projectFileWhen(+ 'the marker reaches the project file',+ sharedCwd,+ (_raw, file) => positionOf(file.nodes, IDLE)?.x === 777,+ 6_000+ )+ expect(afterMarker.kanban?.assignments.map((a) => a.nodeId)).not.toContain(IDLE)+ expect(afterMarker.kanban?.assignments).toContainEqual(expect.objectContaining({ nodeId: LIVE, columnId: column2 }))++ // An outside edit (what a `git pull` does to the file): the bridge is gone and `rev` moved on. The+ // authority adopts it and publishes the difference as canvas ops; the whole-project+ // `workspace:external-change` (and the conflict bar it raises on a dirty canvas) is NOT sent for+ // a governed project.+ const pulled: ProjectFileV1 = {+ ...afterMarker,+ rev: afterMarker.rev + 1,+ bridges: (afterMarker.bridges ?? []).filter((b) => b.id !== 'bridge-e2e')+ }+ const framesBeforePull = owner.frames.length+ await writeFileAtomic(projectFilePath(sharedCwd), `${JSON.stringify(pulled, null, 2)}\n`)+ const unbridged = mutationKey({ op: 'edge-remove', kind: 'bridge', id: 'bridge-e2e' }, SHARED)+ await step('the outside edit reaches the owner as an edge-remove', owner.mut('edge-remove', unbridged))+ // One round trip on the owner's tunnel: whatever the host sent the owner before this answer+ // (an external-change broadcast is sent synchronously, ahead of the adopted diff) has arrived.+ expect(await owner.call(IPC.relayHostedSelf)).toMatchObject({ ok: true, result: { role: 'owner' } })+ const duringPull = owner.frames.slice(framesBeforePull)+ const externalChanges = duringPull.filter(+ (f) => f.t === 'ev' && f.channel === IPC.workspaceExternalChange && (f.args?.[0] as { id?: unknown } | undefined)?.id === SHARED+ )+ expect(externalChanges).toEqual([])+ // The edit, and nothing but the edit: the authority's diff is exactly the removed bridge.+ expect(duringPull.map((f) => mutKeyOf(f)).filter((k) => k !== null)).toEqual([unbridged])+// ---- 7b. `team unshare`: the viewer stays connected, but the terminal it is already watching// goes quiet for it at once (R45); its owner keeps the output. The session's node is looked up// through the real PtyManager on every frame.@@ -497,6 +687,37 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end onspawned[0].onDataCb?.('still running\r\n')expect(await step('owner still receives output', stillThere)).toContain('still running')+ // ---- 9. A restart on the SAME data dir keeps every shared edit. The project is shared again+ // first (7b took it out of the team; a relay peer's workspace:load holds shared projects only).+ // Then one op is left unwritten on purpose: the close must write what the authority still owes.+ await admin(dataDir, { cmd: 'share', projectId: SHARED, on: true })+ const owed: CanvasMutation = { op: 'upsert', node: terminalNode(IDLE, 654), src: 'owner-e2e' }+ expect(cast(owner.c, IPC.canvasMut, [SHARED, owed])).toBe(true)+ await step(+ 'the owner’s last op is reflected',+ owner.mut('upsert', mutationKey(owed, SHARED), (m) => m.op === 'upsert' && m.node.position.x === 654)+ )+ await step('server close', closeFirstServer())+ // Written by the time close() resolves: a close that did not wait for the flush fails here.+ expect(positionOf(readProjectFile(sharedCwd).file.nodes, IDLE)).toEqual({ x: 654, y: 0 })++ listeners = fifo<RelayTransport>()+ const rebooting = startServer(config)+ teardown.push(() => step('second server teardown', rebooting.catch(() => null).then((s) => s?.close())))+ await step('server boot after the restart', rebooting)+ // The owner comes back the way a bookmarked, already-approved host is rejoined: pinned.+ const back = teammate(code, await step('listener after the restart', listeners.next()), ownerKeys, true)+ teardown.push(() => back.c.close())+ await step('owner approved after the restart', back.approved)+ const reloaded = await back.call(IPC.workspaceLoad)+ expect(reloaded).toMatchObject({ ok: true, result: { activeProjectId: SHARED } })+ const again = (reloaded.result as Workspace).projects.find((p) => p.id === SHARED)+ expect(positionOf(again?.nodes, LIVE)).toEqual({ x: 321, y: 0 })+ expect(positionOf(again?.nodes, IDLE)).toEqual({ x: 654, y: 0 })+ expect(again?.kanban?.assignments).toContainEqual(expect.objectContaining({ nodeId: LIVE, columnId: column2 }))+ // The bridge stays gone: the outside edit, not the owner's earlier op, is what was kept.+ expect((again?.bridges ?? []).map((b) => b.id)).not.toContain('bridge-e2e')+// Nothing ever went around the seams.expect(globalHostTokenCalls).toEqual([])}, 90_000)