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.

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.ts
index 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 shared
const 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> | undefined
const 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, pinn
approved,
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, pinn
event(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 = 0
const 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 on
fs.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 on
resetPlatformForTests()
}
- 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 on
installHooks: 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 on
expect(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 on
spawned[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)