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.

45.6 KB
Raw Blame
// The hosted team relay, end to end, on a REAL `startServer` boot (headless, no hooks, temp data dir).
//
// Every piece below has its own unit suite; this one proves they COMPOSE: the admin socket's `team`
// verbs drive the same service the relay listeners belong to, the access policy sees the node and
// project ids the real workspace store answers, the relay peer's requests reach the real platform
// handlers, and a viewer's terminal is the owner's live one. The flow:
//   (the canvas is seeded through a WorkspaceStore before boot: a relay peer cannot save the host's
//   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 → 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.
// A second test starts from a server with no team at all and drives `team bootstrap`, the one verb
// the desktop's "Share with team" calls: it sets up the team, the owner, an adopted folder and its
// share → the owner joins with no SAS on either side → a re-run changes nothing and keeps the code →
// a second folder's share reaches the connected owner live (`relay:hosted:shared-changed`) → so does
// its `team unshare`.
//
// What is real and what is not:
//  - REAL: startServer and every core service it boots, the admin unix socket and its client, the
//    hosted service, the relay E2EE handshake and trust gates on both ends (core `connectRelayClient`
//    is the desktop joiner's own connector), the access policy, WorkspaceStore, PtyManager.
//  - FAKE: the relay server (an in-process transport pair per listener, `relayTestTransport`), the
//    host-token API (`relayTestFetch`), and `node-pty` (a recording fake — no process is spawned).
//    The server's terminals are plain shells here (settings.json `tmuxEnabled: false`), so the test
//    runs the same with or without tmux on the machine and leaves NO tmux session anywhere: there is
//    nothing to kill afterwards, and it never touches a tmux server (the vitest sandbox re-points
//    TMUX_TMPDIR regardless). A viewer's join is the in-process co-attach either way — the branch a
//    tmux-backed session takes too once its owner is attached.
//
// 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. 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 data dir per test. The per-process memos hosted-boot.test.ts warns about (the context-link
// dir, the hook endpoint file) are re-derived by every boot (`initContextLink`) and dropped by every
// close (`hookServer.stop()`), so a later test's boot does not write into an earlier test's removed
// dir. The first test's restart boots a second server on the SAME data dir.
import { describe, it, expect, vi, afterEach, afterAll } from 'vitest'
import { execFileSync } from 'node:child_process'
import fs from 'node:fs'
import os from 'node:os'
import path from 'node:path'
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'
import { decodeJoinCode, type JoinCode } from '../core/relay/join-code'
import { genKeyPair, publicKeyToB64, type KeyPair } from '../core/relay/e2ee'
import { createTestPopServer } from '../core/relay/relay-pop.test-server'
import type { RelayTransport } from '../core/relay/relay-socket'
import { IPC } from '../shared/ipc'
import { mutationKey } from '../shared/canvas-order'
import { seededColumnId } from '../shared/kanban-default-board'
import type { BootstrapResult } from '../shared/share-team'
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
// listeners would dial this dead loopback port instead of the real relay. The mint's twin is the
// global-fetch trap below.
const env = vi.hoisted(() => {
  const prev = process.env.NODETERM_RELAY_URL
  process.env.NODETERM_RELAY_URL = 'ws://127.0.0.1:9/hosted-e2e-seam-missing'
  return { prev }
})

/** One recorded fake pty per spawn (the pty-coattach.test.ts harness): "spawned nothing" is
 *  `spawned.length`, "the viewer never sized it" is `resizes`, and `onDataCb` pushes output. */
interface FakePty {
  file: string
  args: string[]
  onDataCb?: (d: string) => void
  resizes: Array<{ cols: number; rows: number }>
}
const spawned = vi.hoisted(() => [] as FakePty[])

vi.mock('node-pty', () => ({
  spawn: (file: string, args: string[]) => {
    const p: FakePty = { file, args: [...(args ?? [])], resizes: [] }
    spawned.push(p)
    return {
      onData: (cb: (d: string) => void) => {
        p.onDataCb = cb
      },
      onExit: () => {},
      write: () => {},
      resize: (cols: number, rows: number) => p.resizes.push({ cols, rows }),
      pause: () => {},
      resume: () => {},
      kill: () => {},
      pid: 4242
    }
  }
}))
// Pin the plain-shell backend: a checkout that ran `npm run build` has the session-host bundle on
// disk (src/core/__fixtures__/no-session-host.ts says why a suite must SAY which backend it runs).
vi.mock('../core/session-host-backend', async () =>
  (await import('../core/__fixtures__/no-session-host')).noSessionHost()
)
// A machine with pty devices to spare, always: the spawn preflight reads the HOST's device count,
// and a busy host must not refuse the owner's terminal before our fake spawn is ever reached.
vi.mock('../core/pty-devices', async (importOriginal) => ({
  ...(await importOriginal<typeof import('../core/pty-devices')>()),
  readPtyDevices: () => ({ ceiling: 511, inUse: 8 })
}))

// A unix socket path is ~107 bytes at most: boot under a SHORT base so the admin socket fits.
const SHORT_BASE = fs.existsSync('/var/tmp') ? '/var/tmp' : os.tmpdir()
const STEP_MS = 20_000

const SHARED = 'p-team'
const PRIVATE = 'p-private'
const LIVE = 'term-e2e-live' // the owner opens it
const IDLE = 'term-e2e-idle' // shared, but nobody runs it
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:
 *  a timing claim (the authority's 1 s / 5 s flush) is pinned by its unit tests on a manual clock,
 *  never by a wall-clock bound on a loaded CI machine (ruling R14). */
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`)), ms)
  })
  return Promise.race([p, deadline]).finally(() => clearTimeout(timer))
}

/** FIFO whose `next()` resolves as soon as an item is (or already was) pushed. */
function fifo<T>() {
  const items: T[] = []
  const waiters: Array<(v: T) => void> = []
  return {
    push(v: T): void {
      const w = waiters.shift()
      if (w) w(v)
      else items.push(v)
    },
    next(): Promise<T> {
      return items.length > 0 ? Promise.resolve(items.shift() as T) : new Promise<T>((r) => waiters.push(r))
    }
  }
}

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. */
function teammate(code: JoinCode, transport: RelayTransport, keys: KeyPair, pinned: boolean) {
  const frames: Frame[] = []
  const frameWaiters: Array<{ test: (f: Frame) => boolean; resolve: (f: Frame) => void }> = []
  const byteWaiters: Array<{ sessionId: string; resolve: (d: string) => void }> = []
  /** Every terminal chunk received, in order: "received nothing" is as much a result as a chunk. */
  const received: Array<[string, string]> = []
  const denied: string[] = []
  let approve!: () => void
  const approved = new Promise<void>((r) => {
    approve = r
  })
  const waitFrame = (test: (f: Frame) => boolean): Promise<Frame> => {
    const seen = frames.find(test)
    return seen ? Promise.resolve(seen) : new Promise((resolve) => frameWaiters.push({ test, resolve }))
  }
  const c: RelayClientSession = connectRelayClient({
    url: code.relayEndpoint,
    token: 'relay-token',
    hostKeyB64: code.hostPublicKeyB64,
    ourKeys: keys,
    transport,
    autoApprove: pinned,
    onSas: (s) => {
      if (!pinned) s.confirm()
    },
    onApproved: () => approve(),
    onFrame: (json) => {
      const f = JSON.parse(json) as Frame
      frames.push(f)
      for (const w of [...frameWaiters]) {
        if (!w.test(f)) continue
        frameWaiters.splice(frameWaiters.indexOf(w), 1)
        w.resolve(f)
      }
    },
    onPtyData: (sessionId, data) => {
      received.push([sessionId, data])
      for (const w of [...byteWaiters]) {
        if (w.sessionId !== sessionId) continue
        byteWaiters.splice(byteWaiters.indexOf(w), 1)
        w.resolve(data)
      }
    },
    onClose: () => {},
    onDenied: (r) => denied.push(r)
  })
  let nextId = 1
  return {
    c,
    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++
      const res = waitFrame((f) => f.t === 'res' && f.id === id)
      expect(c.send(JSON.stringify({ t: 'req', id, method, args })), `${method} sent`).toBe(true)
      return step(`${method} answered`, res)
    },
    /** The first event on `channel` whose payload passes `match` (one already received counts). */
    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 }))
    }
  }
}

const terminalNode = (id: string, x: number): CanvasNodeState => ({
  id,
  kind: 'terminal',
  position: { x, y: 0 },
  size: { width: 600, height: 400 },
  title: id,
  color: '#0a84ff',
  group: null
})
const project = (id: string, nodes: CanvasNodeState[]): Project => ({
  id,
  name: id,
  color: '#0a84ff',
  viewport: { x: 0, y: 0, zoom: 1 },
  nodes
})
/** The shared project is a FOLDER project: `cwd` is a subfolder of a real git repository (C1). */
const workspaceWith = (sharedCwd: string): Workspace => ({
  version: 2,
  activeProjectId: SHARED,
  projects: [
    { ...project(SHARED, [terminalNode(LIVE, 0), terminalNode(IDLE, 700)]), cwd: sharedCwd },
    project(PRIVATE, [terminalNode(SECRET, 0)])
  ]
})

/** A real repository with a committed secret OUTSIDE the shared subfolder: `repo/shared/` is what
 *  the team sees, `repo/secret/key.txt` is not. Outside the server's data dir on purpose (M7 would
 *  refuse a viewer anything in there for another reason). */
function repoWithSecret(base: string): { repo: string; shared: string } {
  const repo = path.join(base, 'repo')
  fs.mkdirSync(path.join(repo, 'shared'), { recursive: true })
  fs.mkdirSync(path.join(repo, 'secret'), { recursive: true })
  fs.writeFileSync(path.join(repo, 'shared', 'a.txt'), 'shared file\n')
  fs.writeFileSync(path.join(repo, 'secret', 'key.txt'), 'TOPSECRET\n')
  const git = (...args: string[]): void => {
    execFileSync('git', ['-c', 'user.name=e2e', '-c', '[email protected]', '-c', 'commit.gpgsign=false', ...args], {
      cwd: repo,
      stdio: 'ignore'
    })
  }
  git('init', '-q')
  git('add', '-A')
  git('commit', '-qm', 'init')
  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}`)
  return r.result as T
}

// Torn down whatever happened, a hang included: a test that times out never reaches its own finally.
const teardown: Array<() => void | Promise<void>> = []
// The hook outlives one step deadline, so a teardown that runs into it still lets the rest run.
afterEach(async () => {
  for (const f of teardown.splice(0).reverse()) {
    try {
      await f()
    } catch (err) {
      console.warn('[hosted-e2e] teardown step failed', err)
    }
  }
}, 2 * STEP_MS)
afterAll(() => {
  vi.unstubAllGlobals()
  if (env.prev === undefined) delete process.env.NODETERM_RELAY_URL
  else process.env.NODETERM_RELAY_URL = env.prev
})

/** A fresh data dir, removed after the test. Its terminals are plain shells, from the server's own
 *  settings file (see the header). */
function hostedDataDir(): string {
  const dataDir = fs.mkdtempSync(path.join(SHORT_BASE, 'nthe-'))
  teardown.push(() => fs.rmSync(dataDir, { recursive: true, force: true }))
  fs.writeFileSync(path.join(dataDir, 'settings.json'), JSON.stringify({ tmuxEnabled: false }))
  return dataDir
}

/** The relay and the host-token API, faked in-process. */
function fakeRelay() {
  // The host-token API, proof of possession included: a byte-exact mirror of the backend issues
  // the challenge and refuses a mint whose proof does not verify, so a host that stopped proving it
  // holds its key (or proved the wrong thing) never gets a listener. A token good for an hour, so
  // no listener refresh lands mid-test.
  const popServer = createTestPopServer()
  const 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. Replace
     *  it for a fresh boot: the listeners a closed server opened are dead ends. */
    listeners: fifo<RelayTransport>(),
    /** Every host-token mint the host asked for, in order. */
    mints: [] as Array<{ url: string; body: Record<string, unknown> }>,
    relayTestTransport: (): RelayTransport => {
      const { hostT, peerT } = transportPair()
      relay.listeners.push(peerT)
      return hostT
    },
    relayTestFetch: (async (url: string | URL | Request, init?: RequestInit) => {
      const body = JSON.parse(String(init?.body ?? '{}')) as Record<string, unknown>
      const json = (status: number, payload: unknown) =>
        new Response(JSON.stringify(payload), { status, headers: { date: new Date().toUTCString() } })
      if (String(url).endsWith('/v1/relay/challenge')) {
        return json(200, popServer.issue(String(body.hostPublicKeyB64), body.purpose as 'host-token'))
      }
      relay.mints.push({ url: String(url), body })
      const proven = popServer.verify({
        hostPublicKeyB64: String(body.hostPublicKeyB64),
        purpose: 'host-token',
        subject: typeof body.deviceId === 'string' ? body.deviceId : '',
        popChallenge: body.popChallenge,
        popProof: body.popProof
      })
      if (!proven) return json(403, { error: 'pop_invalid' })
      return json(200, { pairingToken: 'relay-token', hostId: 'H', exp: Math.floor(Date.now() / 1000) + 3600 })
    }) as typeof fetch
  }
  return relay
}

/** The mint's production twin of the relay trap at the top: if `relayTestFetch` stopped being
 *  plumbed through, the mint would fall back to the global fetch — which refuses here instead of
 *  minting a host token against the real API. Returns the relay URLs that reached it. */
function trapGlobalFetch(): string[] {
  const calls: string[] = []
  vi.stubGlobal('fetch', (async (url: string | URL | Request) => {
    if (String(url).includes('/v1/relay/')) calls.push(String(url))
    throw new Error('hosted-e2e: the global fetch is not used in this test')
  }) as typeof fetch)
  return calls
}

/** A headless boot on `dataDir` that dials the fake relay. */
function hostedConfig(dataDir: string, relay: ReturnType<typeof fakeRelay>): Parameters<typeof startServer>[0] {
  return {
    port: 0,
    host: '127.0.0.1',
    dataDir,
    rendererDir: path.join(dataDir, 'no-renderer'),
    insecureHttp: false,
    headless: true,
    // Never touch the developer's real agent configs (see ServerConfig.installHooks).
    installHooks: false,
    relayTestTransport: relay.relayTestTransport,
    relayTestFetch: relay.relayTestFetch
  }
}

// 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 → shared canvas edits persist with no browser attached and survive a restart', async () => {
    spawned.length = 0
    const dataDir = hostedDataDir()
    const relay = fakeRelay()
    const globalHostTokenCalls = trapGlobalFetch()

    // The shared project's folder: a subfolder of a real repository, in its own temp dir.
    const repoBase = fs.mkdtempSync(path.join(SHORT_BASE, 'nther-'))
    teardown.push(() => fs.rmSync(repoBase, { recursive: true, force: true }))
    const { shared: sharedCwd } = repoWithSecret(repoBase)

    // The canvas is on this core before it boots: written through a WorkspaceStore on the SAME data
    // dir (the index, and the shared project's own .nodeterm/project.json). A relay peer can no longer
    // put it there — a hosted team never saves the host's workspace (step 2 checks the refusal).
    initPlatform(fakePlatform({ userDataDir: dataDir }))
    try {
      await step('seed the workspace', new WorkspaceStore().save(workspaceWith(sharedCwd)))
    } finally {
      resetPlatformForTests()
    }

    // Both boots (step 9 restarts on the same data dir) take this config.
    const config = hostedConfig(dataDir, relay)
    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. 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())

    // ---- 1. The admin socket sets the team up, and hosting starts.
    const init = await admin<AdminInitResult>(dataDir, { cmd: 'init' })
    expect(init).toMatchObject({ created: true, start: 'started' })
    // What a teammate is given: a code that decodes, whose host id derives from its host key.
    const code = decodeJoinCode(init.joinCode ?? '')
    expect(code).not.toBeNull()
    if (!code) return
    expect(code.hostPublicKeyB64).toBe(init.info?.hostPublicKeyB64)

    const ownerKeys = genKeyPair()
    await admin(dataDir, { cmd: 'add-owner', pubkey: pub(ownerKeys), label: 'Owner' })
    await admin(dataDir, { cmd: 'share', projectId: SHARED, on: true })

    // ---- 2. The owner connects: a team member, so the host approves it without a human.
    const owner = teammate(code, await step('first listener', relay.listeners.next()), ownerKeys, true)
    teardown.push(() => owner.c.close())
    await step('owner approved', owner.approved)
    // The host minted that listener's token for THIS host key, through the seam, proving it holds it.
    expect(relay.mints[0]).toMatchObject({
      url: expect.stringMatching(/\/v1\/relay\/host-token$/),
      body: {
        hostPublicKeyB64: code.hostPublicKeyB64,
        deviceId: code.hostDeviceId,
        popChallenge: expect.any(String),
        popProof: expect.any(String)
      }
    })

    // Even the owner cannot save the host's workspace over the relay: shared content travels as
    // canvas ops, which the host's canvas authority writes (docs/hosted-team-relay.md).
    expect(await owner.call(IPC.workspaceSave, [workspaceWith(sharedCwd)])).toMatchObject({
      ok: false,
      error: { code: 'E_ROLE', message: expect.stringMatching(/cannot save the host's workspace over the relay/) }
    })
    // The owner opens one terminal of the seeded canvas: that session is now live.
    const opened = await owner.call(IPC.ptyCreate, [{ cols: 120, rows: 40, persistKey: LIVE }])
    expect(opened).toMatchObject({ ok: true, result: { fresh: true } })
    const ownerSessionId = (opened.result as PtyCreateResult).sessionId
    expect(ownerSessionId).not.toBe('')
    expect(spawned).toHaveLength(1)
    // A plain shell, never a tmux client: there is no tmux session to clean up after this test.
    expect(path.basename(spawned[0].file)).not.toBe('tmux')
    expect(spawned[0].args).not.toContain('new-session')

    // ---- 3. A guest knocks. It waits; only the owner hears of it, with the SAS the guest sees.
    const guestKeys = genKeyPair()
    const knock = owner.event(IPC.relayHostedPeerPending)
    const guest = teammate(code, await step('second listener', relay.listeners.next()), guestKeys, false)
    teardown.push(() => guest.c.close())
    const pending = (await step('owner told of the guest', knock)).args?.[0] as { pendingId: string; sas: string; peerKeyB64: string }
    expect(pending.peerKeyB64).toBe(pub(guestKeys))
    expect(pending.sas).toBe(guest.c.sas())
    expect(guest.c.isOpen()).toBe(false)
    const waiting = await admin<AdminStatusResult>(dataDir, { cmd: 'status' })
    expect(waiting.pending.map((p) => p.pendingId)).toEqual([pending.pendingId])
    expect(waiting.peers).toEqual([{ label: 'Owner', role: 'owner', connected: true }])

    // ---- 4. The owner approves the guest as a VIEWER.
    expect(await owner.call(IPC.relayHostedApprove, [pending.pendingId, 'viewer'])).toMatchObject({ ok: true, result: true })
    await step('guest approved', guest.approved)

    // ---- 5. The viewer watches the owner's live terminal: the same session, not a new one.
    const joined = await guest.call(IPC.ptyCreate, [{ cols: 80, rows: 24, persistKey: LIVE }])
    expect(joined).toMatchObject({ ok: true, result: { sessionId: ownerSessionId, fresh: false } })
    expect((joined.result as PtyCreateResult).unavailable).toBeUndefined()
    expect(spawned).toHaveLength(1)
    // Joined as a non-voting view: the viewer's smaller window never resized the shared pty.
    expect(spawned[0].resizes).toEqual([])
    // …and the owner's session output reaches it.
    const out = guest.bytes(ownerSessionId)
    spawned[0].onDataCb?.('hello from the owner\r\n')
    expect(await step('viewer receives the owner’s output', out)).toContain('hello from the owner')

    // It can watch a running terminal but never start one: the idle node is refused, nothing spawns.
    expect(await guest.call(IPC.ptyCreate, [{ cols: 80, rows: 24, persistKey: IDLE }])).toMatchObject({
      ok: true,
      result: { sessionId: '', unavailable: 'join-only' }
    })
    expect(spawned).toHaveLength(1)
    // A terminal in a project nobody shared is not reachable at all, and the refusal is the access
    // policy's own sentence (not some other E_ROLE).
    expect(await guest.call(IPC.ptyCreate, [{ cols: 80, rows: 24, persistKey: SECRET }])).toMatchObject({
      ok: false,
      error: { code: 'E_ROLE', message: 'Viewers can only watch terminals in a shared project that are already running.' }
    })
    expect(spawned).toHaveLength(1)
    // Its workspace is the shared project only.
    const ws = await guest.call(IPC.workspaceLoad)
    expect(ws).toMatchObject({ ok: true, result: { activeProjectId: SHARED } })
    expect((ws.result as Workspace).projects.map((p) => p.id)).toEqual([SHARED])

    // ---- 6. A viewer cannot write a file.
    const target = path.join(dataDir, 'written-by-a-viewer.txt')
    expect(await guest.call(IPC.fsWrite, [target, 'x'])).toMatchObject({
      ok: false,
      error: { code: 'E_ROLE', message: "Viewers can't do that here. Ask an owner for Editor access." }
    })
    expect(fs.existsSync(target)).toBe(false)

    // ---- 6b. Git (C1): the shared folder is a SUBFOLDER of a repository. `git show HEAD:<path>`
    // resolves the path against the repository's top level, so the real handler hands the owner the
    // secret outside the shared folder — which is exactly why a viewer is refused git there. Its
    // files are still readable.
    const showSecret = [sharedCwd, 'HEAD', 'secret/key.txt']
    expect(await owner.call(IPC.gitShowFile, showSecret)).toMatchObject({ ok: true, result: 'TOPSECRET' })
    const gitRefusal =
      'Git is available to viewers only in a project that is the top folder of its own repository, never in a subfolder of a larger one.'
    expect(await guest.call(IPC.gitShowFile, showSecret)).toMatchObject({ ok: false, error: { code: 'E_ROLE', message: gitRefusal } })
    expect(await guest.call(IPC.gitStatus, [sharedCwd])).toMatchObject({ ok: false, error: { code: 'E_ROLE', message: gitRefusal } })
    expect(await guest.call(IPC.fsRead, [path.join(sharedCwd, 'a.txt')])).toMatchObject({ ok: true })
    // Its own view of itself says so.
    expect(await guest.call(IPC.relayHostedSelf)).toMatchObject({ ok: true, result: { role: 'viewer' } })

    // ---- 7. `team status`: the guest is a connected viewer; nothing is waiting.
    const status = await admin<AdminStatusResult>(dataDir, { cmd: 'status' })
    expect(status).toMatchObject({ enabled: true, off: null, pending: [] })
    expect(status.peers).toEqual([
      { label: 'Owner', role: 'owner', connected: true },
      { label: '', role: 'viewer', connected: true }
    ])
    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 authority writes it with nobody saving (its 1 s / 5 s bounds are pinned on a manual clock
    // in canvas-authority.test.ts): read the file until it holds ALL THREE ops, parsed — a raw
    // substring would also match a half-applied write.
    const flushed = await projectFileWhen(
      'the authority writes the shared project',
      sharedCwd,
      (_raw, file) =>
        !!file.bridges?.some((b) => b.id === 'bridge-e2e') &&
        positionOf(file.nodes, LIVE)?.x === 321 &&
        !!file.kanban?.assignments.some((a) => a.nodeId === LIVE && a.columnId === column2),
      STEP_MS
    )
    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,
      STEP_MS
    )
    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.
    await admin(dataDir, { cmd: 'share', projectId: SHARED, on: false })
    const ownerAfterUnshare = owner.bytes(ownerSessionId)
    spawned[0].onDataCb?.('after the unshare\r\n')
    expect(await step('owner receives output after the unshare', ownerAfterUnshare)).toContain('after the unshare')
    // One round trip on the viewer's own tunnel: anything sent to it before this answer has arrived.
    expect(await guest.call(IPC.relayHostedSelf)).toMatchObject({ ok: true, result: { role: 'viewer' } })
    expect(guest.received.map(([, d]) => d).join('')).toContain('hello from the owner')
    expect(guest.received.map(([, d]) => d).join('')).not.toContain('after the unshare')

    // ---- 8. The viewer's desktop goes away: its membership stays, its connection does not, and the
    // owner's terminal keeps running for the owner.
    const left = owner.event(IPC.presencePeer, (d) => d.op === 'leave')
    guest.c.close()
    await step('owner told the viewer left', left)
    const after = await admin<AdminStatusResult>(dataDir, { cmd: 'status' })
    expect(after.peers).toEqual([
      { label: 'Owner', role: 'owner', connected: true },
      { label: '', role: 'viewer', connected: false }
    ])
    // An ordinary disconnect is not a dead socket: no send to the leaver was counted as a failure.
    expect(warn.mock.calls.filter((c) => String(c[0]).startsWith('[ui-sink]'))).toEqual([])
    const stillThere = owner.bytes(ownerSessionId)
    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())
    // On disk once close() resolves. Timing-dependent in the GREEN direction only: the authority's
    // own 1 s flush may already have written the op before close() began, so a pass does not prove
    // that close() waited for the flush; a failure does prove the op was lost. That close() awaits
    // the authority's stop (which writes what is owed) is pinned in hosted-boot.test.ts.
    expect(positionOf(readProjectFile(sharedCwd).file.nodes, IDLE)).toEqual({ x: 654, y: 0 })

    relay.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', relay.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)

  it('team bootstrap sets up the team, the owner and a shared project; a second share appears live; unshare goes', async () => {
    const dataDir = hostedDataDir()
    const relay = fakeRelay()
    const globalHostTokenCalls = trapGlobalFetch()
    // The folders bootstrap adopts: real directories on this host. Registered before the server's
    // teardown, so they are removed after it closes (the canvas authority may still write into them).
    const folderA = fs.mkdtempSync(path.join(SHORT_BASE, 'nte-a-'))
    teardown.push(() => fs.rmSync(folderA, { recursive: true, force: true }))
    const folderB = fs.mkdtempSync(path.join(SHORT_BASE, 'nte-b-'))
    teardown.push(() => fs.rmSync(folderB, { recursive: true, force: true }))

    // No seeded workspace and no `team init`: the server boots with no team at all.
    const booting = startServer(hostedConfig(dataDir, relay))
    teardown.push(() => step('server teardown', booting.catch(() => null).then((s) => s?.close())))
    await step('server boot', booting)

    // ---- 1. One admin call: the team and its host key, hosting, the owner, the adopted folder and
    // its share.
    const ownerKeys = genKeyPair()
    const bootstrap = (adoptCwd: string): Promise<BootstrapResult> =>
      admin<BootstrapResult>(dataDir, { cmd: 'bootstrap', ownerKey: pub(ownerKeys), ownerLabel: 'Owner', adoptCwd })
    const a = await bootstrap(folderA)
    expect(a.created).toEqual({ team: true, owner: true, project: true, share: true })
    // `starting` is still a success: no relay verdict within the wait, and a join retries.
    expect(['up', 'starting']).toContain(a.hosting)
    // What the desktop is handed: a code that decodes and names this host.
    const code = decodeJoinCode(a.joinCode)
    expect(code).not.toBeNull()
    if (!code) return
    expect(code.hostId).toBe(a.hostId)

    // ---- 2. The owner joins as the desktop's share flow does: its key is a team owner and the host
    // is pinned on its side, so neither end asks a human to compare a SAS.
    const owner = teammate(code, await step('first listener', relay.listeners.next()), ownerKeys, true)
    teardown.push(() => owner.c.close())
    await step('owner approved', owner.approved)
    const status = await admin<AdminStatusResult>(dataDir, { cmd: 'status' })
    expect(status.peers).toEqual([{ label: 'Owner', role: 'owner', connected: true }])
    expect(status.pending).toEqual([])
    const ws1 = await owner.call(IPC.workspaceLoad)
    expect(ws1).toMatchObject({ ok: true })
    expect((ws1.result as Workspace).projects.map((p) => p.id)).toEqual([a.projectId])

    // ---- 3. A re-run is a no-op with the same code: nothing created, nothing re-shared.
    const again = await bootstrap(folderA)
    expect(again.created).toEqual({ team: false, owner: false, project: false, share: false })
    expect(again.joinCode).toBe(a.joinCode)
    expect(again.projectId).toBe(a.projectId)
    // One round trip on the owner's tunnel: anything the host sent it before this answer has arrived.
    expect(await owner.call(IPC.relayHostedSelf)).toMatchObject({ ok: true, result: { role: 'owner' } })
    const sharedChanges = (): Frame[] =>
      owner.frames.filter((f) => f.t === 'ev' && f.channel === IPC.relayHostedSharedChanged)
    expect(sharedChanges()).toEqual([])

    // ---- 4. A second folder on the same host joins the same team, and the connected owner hears
    // of it live: the whole shared set, in the team file's order.
    const projectIdsOf = (f: Frame): unknown => (f.args?.[0] as { projectIds?: unknown } | undefined)?.projectIds
    const changed = owner.event(IPC.relayHostedSharedChanged, (p) => Array.isArray(p.projectIds) && p.projectIds.length === 2)
    const b = await bootstrap(folderB)
    expect(b.created).toEqual({ team: false, owner: false, project: true, share: true })
    expect(b.joinCode).toBe(a.joinCode)
    expect(projectIdsOf(await step('shared-changed (2)', changed))).toEqual([a.projectId, b.projectId])
    const ws2 = await owner.call(IPC.workspaceLoad)
    expect(ws2).toMatchObject({ ok: true })
    expect((ws2.result as Workspace).projects.map((p) => p.id).sort()).toEqual([a.projectId, b.projectId].sort())

    // ---- 5. `team unshare` of the second: the owner hears the set shrink.
    const gone = owner.event(IPC.relayHostedSharedChanged, (p) => Array.isArray(p.projectIds) && p.projectIds.length === 1)
    await admin(dataDir, { cmd: 'share', projectId: b.projectId, on: false })
    expect(projectIdsOf(await step('shared-changed (1)', gone))).toEqual([a.projectId])

    expect(owner.denied).toEqual([])
    // Nothing ever went around the seams.
    expect(globalHostTokenCalls).toEqual([])
  }, 90_000)
})