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.

27.9 KB
Raw Blame
import { describe, it, expect } from 'vitest'
import {
  runShare,
  classifyTerminals,
  securityNote,
  INSTALL_CANCELLED,
  INSTALL_REPROBE_ATTEMPTS,
  INSTALL_REPROBE_GAP_MS,
  BUSY_REFUSAL,
  CANVAS_CHANGED,
  otherHostRefusal,
  busyTerminals,
  type ShareCanvas,
  type ShareDeps,
  type ShareInput,
  type ShareNode
} from './shareSshTeam'

const READY = { ok: true, probe: { adoptCwd: '/home/alice/proj', teamExists: false } as never, plan: { kind: 'ready' }, paneCommands: { 'term-p': 'npm' } } as const
const BOOT = { ok: true, result: { hostId: 'H', projectId: 'project-9', projectName: 'proj', joinCode: 'nodeterm://join/CODE', hosting: 'up', created: { team: true, owner: true, project: true, share: true } } } as const

const TERMS: ShareNode[] = [
  { nodeId: 'term-a', title: 'Claude', agentId: 'claude', sessionId: 's-1', state: 'done' },
  { nodeId: 'term-p', title: 'dev server' },
  { nodeId: 'term-x', title: 'Work account', agentId: 'claude', sessionId: 's-2', accountId: 'acct' }
]
const canvasOf = (terminals: ShareNode[], extraNodeIds: string[] = []): ShareCanvas => ({
  terminals,
  nodeIds: [...terminals.map((n) => n.nodeId), ...extraNodeIds]
})

function setup(
  o: Partial<Record<'probe' | 'flush' | 'bootstrap' | 'kill' | 'resume', unknown>> & {
    confirm?: boolean
    install?: boolean
    terminals?: ShareNode[]
  } = {}
) {
  const log: string[] = []
  const terminals = o.terminals ?? TERMS
  const deps: ShareDeps = {
    canvas: () => canvasOf(terminals),
    api: {
      probe: async () => (log.push('probe'), (o.probe ?? READY) as never),
      install: async () => (log.push('install'), { ok: true, exitCode: 0 }),
      flushMirror: async () => (log.push('flush'), (o.flush ?? { ok: true, nodeIds: ['term-a', 'term-p', 'term-x'] }) as never),
      bootstrap: async () => (log.push('bootstrap'), (o.bootstrap ?? BOOT) as never),
      killSessions: async (_p, ids) => (log.push(`kill:${ids.join(',')}`), (o.kill ?? { ok: true, results: ids.map((nodeId) => ({ nodeId, state: 'gone' })) }) as never),
      resume: async (_p, sid, s) => (log.push(`resume:${sid}:${s.map((e) => e.nodeId).join(',')}`), (o.resume ?? { ok: true, results: s.map((e) => ({ nodeId: e.nodeId, status: 'resumed' })) }) as never),
      seedBookmark: async () => (log.push('seed'), { ok: true, hostId: 'H', label: 'box' })
    },
    confirm: async () => (log.push('confirm'), o.confirm ?? true),
    phase: (p) => log.push(`phase:${p}`),
    prepare: async () => void log.push('prepare'),
    markPending: async () => void log.push('mark'),
    release: async () => void log.push('release'),
    restore: async () => void log.push('restore'),
    markHandedOff: async (to) => void log.push(`handed:${to.hostId}:${to.projectId}`),
    join: (code, focus) => void log.push(`join:${focus}`),
    wait: async (ms) => void log.push(`wait:${ms}`)
  }
  return { deps, log }
}
const INPUT: ShareInput = { projectId: 'ssh-1', projectName: 'proj', host: 'box', user: 'alice', permissionMode: 'auto' }
/** A second resumable agent, for the cases that need more than one node in the resume request. */
const TERM_B: ShareNode = { nodeId: 'term-b', title: 'Codex', agentId: 'codex', sessionId: 's-3', state: 'done' }
const FLUSH_WITH_B = { ok: true, nodeIds: ['term-a', 'term-p', 'term-x', 'term-b'] }

describe('runShare', () => {
  it('the whole flow, in order: no kill before bootstrap, no resume before the kill', async () => {
    const { deps, log } = setup()
    const out = await runShare(deps, INPUT)
    expect(out).toMatchObject({ kind: 'shared', joinCode: 'nodeterm://join/CODE', resumed: [{ nodeId: 'term-a' }] })
    const at = (s: string) => log.findIndex((l) => l.startsWith(s))
    expect(at('bootstrap')).toBeLessThan(at('kill:'))
    expect(at('kill:')).toBeLessThan(at('resume:'))
    expect(at('prepare')).toBeLessThan(at('mark'))
    expect(at('mark')).toBeLessThan(at('flush'))
    expect(at('flush')).toBeLessThan(at('release'))
    expect(at('release')).toBeLessThan(at('bootstrap'))
    expect(log).toContain('handed:H:project-9')
    expect(log).toContain('resume:project-9:term-a') // only the resumable agent; never the managed-account one
    expect(log).toContain('join:project-9')
    expect(log).not.toContain('restore')
  })
  it('refuses while an agent is working or blocked, before touching the host', async () => {
    const { deps, log } = setup({ terminals: [{ ...TERMS[0], state: 'working' }] })
    const out = await runShare(deps, INPUT)
    expect(out).toMatchObject({ kind: 'refused', busy: [{ nodeId: 'term-a' }] })
    expect(log).toEqual([])
  })
  it('refuses a blocked agent too', async () => {
    const { deps, log } = setup({ terminals: [{ ...TERMS[0], state: 'blocked' }, TERMS[1]] })
    const out = await runShare(deps, INPUT)
    expect(out).toEqual({
      kind: 'refused',
      reason: 'Wait for these agents to finish (or stop them), then share again.',
      busy: [{ ...TERMS[0], state: 'blocked' }]
    })
    expect(log).toEqual([])
  })
  it('refuses an agent waiting on a question or an approval (a Codex prompt, an AskUserQuestion)', async () => {
    const { deps, log } = setup({ terminals: [{ ...TERMS[0], state: 'waiting' }, TERMS[1]] })
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'refused', reason: BUSY_REFUSAL, busy: [{ ...TERMS[0], state: 'waiting' }] })
    expect(log).toEqual([])
  })
  it('refuses more terminals than one share handles, before touching the host', async () => {
    const terminals = Array.from({ length: 201 }, (_, i) => ({ nodeId: `t-${i}`, title: `T${i}` }))
    const { deps, log } = setup({ terminals })
    expect(await runShare(deps, INPUT)).toMatchObject({ kind: 'refused', reason: expect.stringContaining('more than 200') })
    expect(log).toEqual([])
  })
  it('refuses a terminal that runs on another host, naming it, before touching the host', async () => {
    const { deps, log } = setup({ terminals: [...TERMS, { nodeId: 'term-o', title: 'prod logs', otherHost: true }] })
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'refused', reason: otherHostRefusal(['prod logs']) })
    expect(otherHostRefusal(['prod logs', 'db'])).toBe(
      'These terminals run on another host: prod logs, db. Close them or move them out of this project, then share again.'
    )
    expect(log).toEqual([])
  })
  it('re-reads the canvas right before the mark: a turn that started during the install refuses, nothing changed', async () => {
    const { deps, log } = setup()
    let reads = 0
    deps.canvas = () => (reads++ === 0 ? canvasOf(TERMS) : canvasOf([{ ...TERMS[0], state: 'working' }, TERMS[1], TERMS[2]]))
    expect(await runShare(deps, INPUT)).toMatchObject({ kind: 'refused', reason: BUSY_REFUSAL, busy: [{ nodeId: 'term-a' }] })
    expect(log).toContain('prepare')
    expect(log.some((l) => /^(mark|flush|release|restore|bootstrap|kill)/.test(l))).toBe(false)
  })
  it('re-reads the canvas right before the mark: a terminal added (or removed) meanwhile refuses, nothing changed', async () => {
    for (const later of [[...TERMS, { nodeId: 'term-new', title: 'new' }], TERMS.slice(0, 2)]) {
      const { deps, log } = setup()
      let reads = 0
      deps.canvas = () => (reads++ === 0 ? canvasOf(TERMS) : canvasOf(later))
      expect(await runShare(deps, INPUT)).toEqual({ kind: 'refused', reason: CANVAS_CHANGED })
      expect(log.some((l) => /^(mark|flush|release|restore|bootstrap|kill)/.test(l))).toBe(false)
    }
    expect(CANVAS_CHANGED).toBe('The canvas changed while preparing the share. Nothing was changed; share again.')
  })
  it('resumes with the session id of the read right before the mark (a /clear during the install)', async () => {
    const { deps, log } = setup()
    const seen: string[] = []
    let reads = 0
    deps.canvas = () => (reads++ === 0 ? canvasOf(TERMS) : canvasOf([{ ...TERMS[0], sessionId: 's-new' }, TERMS[1], TERMS[2]]))
    deps.api.resume = async (_p, _sid, sessions) => (seen.push(...sessions.map((e) => e.sessionId)), { ok: true, results: sessions.map((e) => ({ nodeId: e.nodeId, status: 'resumed' as const })) })
    expect(await runShare(deps, INPUT)).toMatchObject({ kind: 'shared' })
    expect(seen).toEqual(['s-new'])
    expect(log).toContain('mark')
  })
  it('the flush check covers every node of the project, not only terminals', async () => {
    const { deps, log } = setup()
    deps.canvas = () => canvasOf(TERMS, ['sticky-1'])
    const out = await runShare(deps, INPUT)
    expect(out).toMatchObject({ kind: 'failed', step: 'releasing', error: expect.stringContaining('(1 node missing)') })
    expect(log).not.toContain('release')
    expect(log.indexOf('restore')).toBeGreaterThan(log.indexOf('flush'))
  })
  it('a probe failure fails at probing, and a refusing plan is a refusal; neither asks to confirm', async () => {
    const failed = setup({ probe: { ok: false, error: 'not connected' } })
    expect(await runShare(failed.deps, INPUT)).toEqual({ kind: 'failed', step: 'probing', error: 'not connected', reopened: false })
    const refused = setup({ probe: { ...READY, plan: { kind: 'refuse', reason: 'Linux only' } } })
    expect(await runShare(refused.deps, INPUT)).toEqual({ kind: 'refused', reason: 'Linux only' })
    expect([...failed.log, ...refused.log]).not.toContain('confirm')
  })
  it('cancel at the confirm changes nothing', async () => {
    const { deps, log } = setup({ confirm: false })
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'cancelled' })
    expect(log.some((l) => /^(prepare|mark|release|bootstrap|kill)/.test(l))).toBe(false)
  })
  it('a canvas missing on the host stops BEFORE release and clears the pending mark', async () => {
    const { deps, log } = setup({ flush: { ok: true, nodeIds: ['term-a'] } })
    const out = await runShare(deps, INPUT)
    expect(out).toMatchObject({ kind: 'failed', step: 'releasing', reopened: false, error: expect.stringContaining('2 nodes missing') })
    expect(log).not.toContain('release')
    expect(log).not.toContain('bootstrap')
    expect(log.indexOf('restore')).toBeGreaterThan(log.indexOf('mark'))
  })
  it('a failed flush stops BEFORE release and clears the pending mark', async () => {
    const { deps, log } = setup({ flush: { ok: false, error: 'ssh died' } })
    const out = await runShare(deps, INPUT)
    expect(out).toEqual({ kind: 'failed', step: 'releasing', error: 'ssh died', reopened: false })
    expect(log).not.toContain('release')
    expect(log).not.toContain('bootstrap')
    expect(log.indexOf('restore')).toBeGreaterThan(log.indexOf('flush'))
  })
  it('a failed save in prepare stops before anything is marked', async () => {
    const { deps, log } = setup()
    deps.prepare = async () => {
      throw new Error('save failed')
    }
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'releasing', error: 'save failed', reopened: false })
    expect(log.some((l) => /^(mark|flush|restore|release)/.test(l))).toBe(false)
  })
  it('a failed pending mark still clears itself, and nothing is flushed or released', async () => {
    const { deps, log } = setup()
    deps.markPending = async () => {
      throw new Error('disk full')
    }
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'releasing', error: 'disk full', reopened: false })
    expect(log).toContain('restore')
    expect(log.some((l) => /^(flush|release|bootstrap)/.test(l))).toBe(false)
  })
  it('a release that throws reopens the project and never bootstraps', async () => {
    const { deps, log } = setup()
    deps.release = async () => {
      throw new Error('close failed')
    }
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'releasing', error: 'close failed', reopened: true })
    expect(log).toContain('restore')
    expect(log).not.toContain('bootstrap')
  })
  it('a bootstrap failure reopens the SSH project and kills nothing', async () => {
    // The server's own sentence already says hosting could not start; it is shown as it came.
    const { deps, log } = setup({ bootstrap: { ok: false, code: 'E_HOSTING_OFF', error: 'Hosting could not start: refused (403)' } })
    const out = await runShare(deps, INPUT)
    expect(out).toEqual({ kind: 'failed', step: 'bootstrapping', reopened: true, error: 'Hosting could not start: refused (403)' })
    expect(log).toContain('restore')
    expect(log.some((l) => l.startsWith('kill:'))).toBe(false)
  })
  it('a restore that throws is reported: never "reopened", always restoreFailed, the original error kept', async () => {
    const { deps, log } = setup({ bootstrap: { ok: false, code: 'E_ADOPT_FAILED', error: 'boom' } })
    deps.restore = async () => {
      throw new Error('restore failed')
    }
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'bootstrapping', error: 'boom', reopened: false, restoreFailed: true })
    expect(log.some((l) => l.startsWith('kill:'))).toBe(false)
  })
  it('a release and a restore that both throw report neither a reopen nor the release as undone', async () => {
    const { deps } = setup()
    deps.release = async () => {
      throw new Error('close failed')
    }
    deps.restore = async () => {
      throw new Error('restore failed')
    }
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'releasing', error: 'close failed', reopened: false, restoreFailed: true })
  })
  it('a missing canvas whose restore throws does not claim nothing was changed', async () => {
    const { deps } = setup({ flush: { ok: true, nodeIds: ['term-a', 'term-p'] } })
    deps.restore = async () => {
      throw new Error('restore failed')
    }
    expect(await runShare(deps, INPUT)).toEqual({
      kind: 'failed',
      step: 'releasing',
      error: 'The canvas on the host is not up to date (1 node missing). Try again in a moment.',
      reopened: false,
      restoreFailed: true
    })
  })
  it('a bootstrap failure without a server code says the host may have finished; a throw counts as one', async () => {
    const uncoded = setup({ bootstrap: { ok: false, error: 'timed out' } })
    expect(await runShare(uncoded.deps, INPUT)).toEqual({
      kind: 'failed',
      step: 'bootstrapping',
      error: 'timed out The host may have finished setting up anyway; run Share with team again to complete it.',
      reopened: true
    })
    expect(uncoded.log).toContain('restore')
    const thrown = setup()
    thrown.deps.api.bootstrap = async () => {
      throw new Error('socket hang up')
    }
    expect(await runShare(thrown.deps, INPUT)).toMatchObject({
      kind: 'failed',
      step: 'bootstrapping',
      error: 'socket hang up The host may have finished setting up anyway; run Share with team again to complete it.',
      reopened: true
    })
  })
  it('a coded bootstrap failure other than hosting-off keeps its error as is', async () => {
    const { deps } = setup({ bootstrap: { ok: false, code: 'E_BAD_CWD', error: 'not a folder' } })
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'bootstrapping', error: 'not a folder', reopened: true })
  })
  it('markHandedOff is retried once, then given up without failing the share', async () => {
    const once = setup()
    let calls = 0
    once.deps.markHandedOff = async (to) => {
      calls++
      if (calls === 1) throw new Error('disk busy')
      once.log.push(`handed:${to.hostId}:${to.projectId}`)
    }
    expect(await runShare(once.deps, INPUT)).toMatchObject({ kind: 'shared' })
    expect(calls).toBe(2)
    expect(once.log).toContain('handed:H:project-9')
    const never = setup()
    let tries = 0
    never.deps.markHandedOff = async () => {
      tries++
      throw new Error('disk full')
    }
    expect(await runShare(never.deps, INPUT)).toMatchObject({ kind: 'shared', resumed: [{ nodeId: 'term-a' }] })
    expect(tries).toBe(2)
    expect(never.log).not.toContain('restore')
  })
  it('after a successful bootstrap a throwing phase or join never rejects, skips no step, and still answers shared', async () => {
    const { deps, log } = setup()
    deps.phase = (p) => {
      log.push(`phase:${p}`)
      if (p === 'handing-over' || p === 'joining') throw new Error('ui gone')
    }
    deps.join = () => {
      throw new Error('ui gone')
    }
    const out = await runShare(deps, INPUT)
    expect(out).toMatchObject({ kind: 'shared', joinCode: 'nodeterm://join/CODE', resumed: [{ nodeId: 'term-a' }] })
    expect(log.some((l) => l.startsWith('kill:'))).toBe(true)
    expect(log).toContain('resume:project-9:term-a')
    expect(log).toContain('seed')
    expect(log).not.toContain('restore')
  })
  it('a throwing phase before the bootstrap does not strand the project closed', async () => {
    const { deps, log } = setup()
    deps.phase = (p) => {
      log.push(`phase:${p}`)
      if (p === 'bootstrapping') throw new Error('ui gone')
    }
    expect(await runShare(deps, INPUT)).toMatchObject({ kind: 'shared' })
    expect(log).toContain('bootstrap')
  })
  it('after a successful bootstrap nothing ever reopens: a failed kill resumes nothing and reports every node still on SSH', async () => {
    const { deps, log } = setup({ kill: { ok: false, error: 'ssh died' } })
    const out = await runShare(deps, INPUT)
    expect(out).toMatchObject({ kind: 'shared', resumed: [] })
    expect((out as { stillOnSsh: unknown[] }).stillOnSsh).toHaveLength(3)
    expect(log).not.toContain('restore')
    expect(log.some((l) => l.startsWith('resume:'))).toBe(false)
  })
  it('a kill verdict of unknown is not gone: nothing is resumed and the node stays on SSH', async () => {
    const { deps, log } = setup({ kill: { ok: true, results: [{ nodeId: 'term-a', state: 'unknown' }, { nodeId: 'term-p', state: 'gone' }, { nodeId: 'term-x', state: 'gone' }] } })
    const out = await runShare(deps, INPUT)
    expect(log.some((l) => l.startsWith('resume:'))).toBe(false)
    expect(out).toMatchObject({ kind: 'shared', resumed: [], stillOnSsh: [{ nodeId: 'term-a' }] })
    expect((out as { notResumed: Array<{ node: { nodeId: string }; reason: string }> }).notResumed).toContainEqual({
      node: expect.objectContaining({ nodeId: 'term-a' }),
      reason: 'still running on SSH'
    })
  })
  it('a node the kill reply leaves out is not gone: nothing is resumed and the node stays on SSH', async () => {
    const { deps, log } = setup({ kill: { ok: true, results: [{ nodeId: 'term-p', state: 'gone' }, { nodeId: 'term-x', state: 'gone' }] } })
    const out = await runShare(deps, INPUT)
    expect(log.some((l) => l.startsWith('resume:'))).toBe(false)
    expect(out).toMatchObject({ kind: 'shared', resumed: [], stillOnSsh: [{ nodeId: 'term-a' }] })
  })
  it('only verified-gone agents are resumed; an alive one is reported, not resumed', async () => {
    const { deps, log } = setup({ kill: { ok: true, results: [{ nodeId: 'term-a', state: 'alive' }, { nodeId: 'term-p', state: 'gone' }, { nodeId: 'term-x', state: 'gone' }] } })
    const out = await runShare(deps, INPUT)
    expect(log.some((l) => l.startsWith('resume:'))).toBe(false)
    expect(out).toMatchObject({ kind: 'shared', stillOnSsh: [{ nodeId: 'term-a' }] })
  })
  it('already-running counts as resumed', async () => {
    const { deps } = setup({ resume: { ok: true, results: [{ nodeId: 'term-a', status: 'already-running' }] } })
    expect(await runShare(deps, INPUT)).toMatchObject({ kind: 'shared', resumed: [{ nodeId: 'term-a' }] })
  })
  it('a failed resume reply puts every sent node in notResumed with that error', async () => {
    const { deps } = setup({ flush: FLUSH_WITH_B, resume: { ok: false, error: 'server busy' }, terminals: [...TERMS, TERM_B] })
    const out = await runShare(deps, INPUT)
    expect(out).toMatchObject({
      kind: 'shared',
      resumed: [],
      notResumed: [
        { node: { nodeId: 'term-a' }, reason: 'server busy' },
        { node: { nodeId: 'term-b' }, reason: 'server busy' },
        { node: { nodeId: 'term-x' }, reason: 'runs under a managed account' }
      ]
    })
  })
  it('a node the resume reply leaves out is reported as unanswered, not resumed', async () => {
    const { deps } = setup({ flush: FLUSH_WITH_B, resume: { ok: true, results: [{ nodeId: 'term-a', status: 'resumed' }] }, terminals: [...TERMS, TERM_B] })
    const out = await runShare(deps, INPUT)
    expect(out).toMatchObject({ kind: 'shared', resumed: [{ nodeId: 'term-a' }] })
    expect((out as { notResumed: unknown[] }).notResumed).toContainEqual({
      node: expect.objectContaining({ nodeId: 'term-b' }),
      reason: 'the server did not answer for it'
    })
  })
  it('a refused resume is reported with its reason, beside the manual agents', async () => {
    const { deps } = setup({ resume: { ok: true, results: [{ nodeId: 'term-a', status: 'refused', reason: 'unknown agent' }] } })
    const out = await runShare(deps, INPUT)
    expect(out).toMatchObject({
      kind: 'shared',
      resumed: [],
      notResumed: [
        { node: { nodeId: 'term-a' }, reason: 'unknown agent' },
        { node: { nodeId: 'term-x' }, reason: 'runs under a managed account' }
      ],
      stillOnSsh: []
    })
  })
  it('install path: install, then re-probe must be ready, before anything is released', async () => {
    let n = 0
    const { deps, log } = setup()
    deps.api.probe = async () => (log.push('probe'), (n++ === 0 ? { ...READY, plan: { kind: 'install', reason: 'missing' } } : READY) as never)
    await runShare(deps, INPUT)
    expect(log.indexOf('install')).toBeGreaterThan(log.indexOf('confirm'))
    expect(log.lastIndexOf('probe')).toBeGreaterThan(log.indexOf('install'))
    expect(log.indexOf('release')).toBeGreaterThan(log.lastIndexOf('probe'))
  })
  it('bootstrap names no folder: main adopts the one its own latest probe resolved', async () => {
    const { deps } = setup()
    const seen: unknown[][] = []
    deps.api.bootstrap = async (...args: unknown[]) => (seen.push(args), BOOT as never)
    await runShare(deps, INPUT)
    expect(seen).toEqual([['ssh-1']])
  })
  it('says a shared install and re-probe failure once', async () => {
    const { deps } = setup()
    let n = 0
    deps.api.probe = async () => (n++ === 0 ? { ...READY, plan: { kind: 'install', reason: 'missing' } } : { ok: false, error: 'not connected' }) as never
    deps.api.install = async () => ({ ok: false, error: 'not connected' })
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'checking-install', error: 'not connected', reopened: false })
  })
  it('joins a re-probe failure that differs from the install message', async () => {
    const { deps } = setup()
    let n = 0
    deps.api.probe = async () => (n++ === 0 ? { ...READY, plan: { kind: 'install', reason: 'missing' } } : { ok: false, error: 'ssh died' }) as never
    expect(await runShare(deps, INPUT)).toEqual({
      kind: 'failed',
      step: 'checking-install',
      error: 'The install finished (exit 0) but nodeterm-server is not ready on the host. ssh died',
      reopened: false
    })
  })
  it('an install that does not leave a ready server fails without releasing anything', async () => {
    const { deps, log } = setup()
    deps.api.probe = async () => (log.push('probe'), { ...READY, plan: { kind: 'install', reason: 'missing' } }) as never
    expect(await runShare(deps, INPUT)).toMatchObject({ kind: 'failed', step: 'checking-install', reopened: false })
    expect(log).not.toContain('release')
    expect(log).not.toContain('mark')
    // The re-probe was given a few chances (the restarted service may not answer at once).
    expect(log.filter((l) => l === 'probe')).toHaveLength(1 + INSTALL_REPROBE_ATTEMPTS)
    expect(log.filter((l) => l.startsWith('wait:'))).toEqual(Array(INSTALL_REPROBE_ATTEMPTS - 1).fill(`wait:${INSTALL_REPROBE_GAP_MS}`))
  })
  it('a re-probe right after a completed install retries while the server is not ready yet, then shares', async () => {
    let n = 0
    const { deps, log } = setup()
    const notRunning = { ...READY, plan: { kind: 'install', reason: 'not-running' } }
    deps.api.probe = async () => (log.push('probe'), (n++ < 2 ? notRunning : READY) as never)
    expect(await runShare(deps, INPUT)).toMatchObject({ kind: 'shared' })
    expect(log.filter((l) => l === 'probe')).toHaveLength(3)
    expect(log.indexOf('wait:2000')).toBeGreaterThan(log.indexOf('install'))
  })
  it('an install that exited non-zero, or a refusing re-probe, is not retried', async () => {
    const failedInstall = setup()
    failedInstall.deps.api.install = async () => ({ ok: true, exitCode: 1 })
    failedInstall.deps.api.probe = async () => (failedInstall.log.push('probe'), { ...READY, plan: { kind: 'install', reason: 'missing' } }) as never
    // A non-zero exit is the install FAILING; saying it "finished" read as a success followed by a
    // readiness problem (device run, 2026-10-03).
    expect(await runShare(failedInstall.deps, INPUT)).toEqual({
      kind: 'failed',
      step: 'checking-install',
      error: 'The install failed (exit 1).',
      reopened: false
    })
    expect(failedInstall.log.filter((l) => l === 'probe')).toHaveLength(2)
    let n = 0
    const refusing = setup()
    refusing.deps.api.probe = async () =>
      (refusing.log.push('probe'), (n++ === 0 ? { ...READY, plan: { kind: 'install', reason: 'missing' } } : { ...READY, plan: { kind: 'refuse', reason: 'nope' } })) as never
    expect(await runShare(refusing.deps, INPUT)).toMatchObject({ kind: 'failed', step: 'checking-install' })
    expect(refusing.log.filter((l) => l === 'probe')).toHaveLength(2)
  })
  it('a cancelled install ends the share: no re-probe, nothing released, killed or bootstrapped', async () => {
    const { deps, log } = setup({ probe: { ...READY, plan: { kind: 'install', reason: 'missing' } } })
    deps.api.install = async () => (log.push('install'), { ok: false, code: 'E_CANCELLED', error: 'The install was cancelled.' })
    expect(await runShare(deps, INPUT)).toEqual({ kind: 'failed', step: 'installing', error: INSTALL_CANCELLED, reopened: false })
    expect(log.filter((l) => l === 'probe')).toHaveLength(1)
    expect(log.some((l) => /^(prepare|mark|flush|release|restore|bootstrap|kill|resume|seed|join)/.test(l))).toBe(false)
  })
})

describe('busyTerminals', () => {
  it('working, blocked and waiting are busy; done and an unknown state are not', () => {
    const at = (state: ShareNode['state']): ShareNode => ({ nodeId: 'a', title: 'A', agentId: 'codex', state })
    expect(busyTerminals([at('working'), at('blocked'), at('waiting')])).toHaveLength(3)
    expect(busyTerminals([at('done'), at(undefined)])).toEqual([])
  })
  it('an agent known only to the status store (launched by hand) counts as busy; a plain terminal never does', () => {
    const hand: ShareNode = { nodeId: 'h', title: 'H', liveAgentId: 'claude', state: 'working' }
    expect(busyTerminals([hand])).toEqual([hand])
    expect(busyTerminals([{ nodeId: 'p', title: 'P', state: 'working' }])).toEqual([])
  })
})

describe('classifyTerminals', () => {
  it('sorts agents into resumable / manual and plain terminals into stopping (only a non-shell command)', () => {
    const r = classifyTerminals(
      [
        { nodeId: 'a', title: 'A', agentId: 'claude', sessionId: 's1' },
        { nodeId: 'b', title: 'B', agentId: 'claude' },
        { nodeId: 'c', title: 'C', agentId: 'claude', sessionId: 's3', accountId: 'x' },
        { nodeId: 'd', title: 'D', agentId: 'my-custom', sessionId: 's4' },
        { nodeId: 'e', title: 'E' },
        { nodeId: 'f', title: 'F' }
      ],
      { e: 'npm', f: 'zsh' }
    )
    expect(r.resumable.map((n) => n.nodeId)).toEqual(['a'])
    expect(r.manual.map((m) => m.node.nodeId)).toEqual(['b', 'c', 'd'])
    expect(r.stopping).toEqual([{ node: { nodeId: 'e', title: 'E' }, command: 'npm' }])
  })
  it('an agent known only to the status store is never resumed: its pane is a plain terminal that stops', () => {
    // A stale status agent must never make the server type `claude --resume` into a node created
    // as a plain terminal.
    const hand: ShareNode = { nodeId: 'h', title: 'H', liveAgentId: 'claude', sessionId: 's1', state: 'done' }
    const r = classifyTerminals([hand], { h: 'claude' })
    expect(r.resumable).toEqual([])
    expect(r.manual).toEqual([])
    expect(r.stopping).toEqual([{ node: hand, command: 'claude' }])
  })
})

it('securityNote is the exact sentence', () => {
  expect(securityNote('alice', 'box')).toBe('Editors get a shell as alice on box and can make themselves owners; Viewers cannot.')
})