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.

69.4 KB
Raw Blame
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
import { initPlatform, resetPlatformForTests } from './platform'
import { fakePlatform, type FakePlatform } from './platform-fake'
import { IPC } from '../shared/ipc'
import { encodeArgs, parseRpcMessage } from '../shared/rpc'

/** One fake pty per spawn, recorded so a test can assert "exactly one spawn" and push output. */
interface FakePty {
  onDataCb?: (d: string) => void
  onExitCb?: (e: { exitCode: number }) => void
  writes: string[]
  resizes: Array<{ cols: number; rows: number }>
  paused: boolean
  killed: boolean
}
const spawned: FakePty[] = []
/** When set, the NEXT pty.spawn throws (simulates posix_spawn failing). */
let failNextSpawn = false

// Pin the persistence backend: `sessionHostSupported()` only asks whether
// out/session-host/host.cjs exists on disk, so whether this suite exercises the mocked
// `node-pty` spawn below or a real session-host shim depended on whether anyone had run
// `npm run build` (or `npm run host:build`). See src/core/__fixtures__/no-session-host.ts.
vi.mock('./session-host-backend', async () =>
  (await import('./__fixtures__/no-session-host')).noSessionHost()
)

vi.mock('node-pty', () => ({
  spawn: (_file: string, _args: string[], _opts: unknown) => {
    if (failNextSpawn) {
      failNextSpawn = false
      throw new Error('posix_spawnp failed.')
    }
    const p: FakePty = { writes: [], resizes: [], paused: false, killed: false }
    spawned.push(p)
    return {
      onData: (cb: (d: string) => void) => {
        p.onDataCb = cb
      },
      onExit: (cb: (e: { exitCode: number }) => void) => {
        p.onExitCb = cb
      },
      write: (d: string) => p.writes.push(d),
      resize: (cols: number, rows: number) => p.resizes.push({ cols, rows }),
      pause: () => {
        p.paused = true
      },
      resume: () => {
        p.paused = false
      },
      kill: () => {
        p.killed = true
      },
      pid: 1234
    }
  }
}))

const ALICE = 1
const BOB = 2
const CAROL = 3

/**
 * A machine with pty devices to spare, always.
 *
 * Without this the real probe runs a `readdir('/dev')` against the DEVELOPER's host, and
 * `spawnSession`'s pre-flight refuses every create once that host is within `PTY_DEVICE_HEADROOM`
 * of its own `kern.tty.ptmx_max` — which a machine running this app all day genuinely reaches (511
 * on macOS; this one sits in the 480s). Nothing below is about device pressure, so it is pinned
 * healthy rather than left to depend on who is running the suite and how many terminals they have
 * open. The pressure behaviour itself is tested in pty-spawn-preflight.test.ts.
 */
vi.mock('./pty-devices', async (importOriginal) => ({
  ...(await importOriginal<typeof import('./pty-devices')>()),
  readPtyDevices: () => ({ ceiling: 511, inUse: 8 })
}))

describe('terminal co-attach: one PTY, N subscribers', () => {
  let fake: FakePlatform

  beforeEach(() => {
    spawned.length = 0
    failNextSpawn = false
    fake = fakePlatform()
    initPlatform(fake)
    vi.useFakeTimers()
  })
  afterEach(() => {
    vi.useRealTimers()
    resetPlatformForTests()
  })

  async function manager() {
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    return m
  }
  const create = (clientId: number, cols = 80, rows = 24, persistKey = 'node-1') =>
    fake.handlers[IPC.ptyCreate](clientId, { cols, rows, persistKey }) as Promise<{
      sessionId: string
      fresh: boolean
      closed?: { by: number | null }
    }>
  // pty:kill is sender-aware (it unsubscribes ONE client), so it lands in senderListeners.
  const kill = (clientId: number, sessionId: string) =>
    fake.senderListeners[IPC.ptyKill](clientId, sessionId)
  // pty:flow is sender-aware too: a pause is OWED by the client whose xterm backlog overflowed,
  // so it can only be returned by that client (or by its departure).
  const flow = (clientId: number, sessionId: string, resume: boolean) =>
    fake.senderListeners[IPC.ptyFlow](clientId, sessionId, resume)
  // pty:write is sender-aware as well: with one pty and N subscribers, a keystroke has to carry WHO
  // typed it — that is what badges the node as "X is typing" (see pty-typing.test.ts).
  const write = (clientId: number, sessionId: string, data: string) =>
    fake.senderListeners[IPC.ptyWrite](clientId, sessionId, data)
  // pty:resize is sender-aware: the pty runs at the smallest SUBSCRIBER's grid.
  const resize = (clientId: number, sessionId: string, cols: number | null, rows: number | null) =>
    fake.senderListeners[IPC.ptyResize](clientId, sessionId, cols, rows)

  it('a second client on the same persistKey subscribes instead of spawning', async () => {
    await manager()
    const a = await create(ALICE)
    const b = await create(BOB)

    expect(spawned).toHaveLength(1) // ONE pty, ONE tmux client
    expect(b.sessionId).toBe(a.sessionId)
    expect(a.fresh).toBe(true) // Alice created it
    expect(b.fresh).toBe(false) // Bob joined a live session — no cold-restore replay
  })

  it('output fans out to every subscriber', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)

    spawned[0].onDataCb?.('hello')
    vi.advanceTimersByTime(20) // FLUSH_MS coalescing window

    const data = fake.sent.filter((s) => s.channel === IPC.ptyData(sessionId))
    expect(data.map((s) => s.to).sort()).toEqual([ALICE, BOB])
    expect(data.every((s) => s.args[0] === 'hello')).toBe(true)
  })

  it('exit fans out to every subscriber and clears the persistKey index', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)

    spawned[0].onExitCb?.({ exitCode: 7 })
    const exits = fake.sent.filter((s) => s.channel === IPC.ptyExit(sessionId))
    expect(exits.map((s) => s.to).sort()).toEqual([ALICE, BOB])
    expect(exits.every((s) => s.args[0] === 7)).toBe(true)

    // The session is gone, so a fresh create must spawn again (not hand out a dead sessionId).
    await create(ALICE)
    expect(spawned).toHaveLength(2)
  })

  it('kill unsubscribes ONE client; the pty survives while others watch', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)

    kill(ALICE, sessionId) // Alice closes her tab
    fake.sent.length = 0
    spawned[0].onDataCb?.('still here')
    vi.advanceTimersByTime(20)

    const data = fake.sent.filter((s) => s.channel === IPC.ptyData(sessionId))
    expect(data.map((s) => s.to)).toEqual([BOB]) // Bob still gets output
    expect(spawned[0].killed).toBe(false) // pty untouched

    // Bob leaves too → last subscriber out releases the pty.
    kill(BOB, sessionId)
    expect(spawned[0].killed).toBe(true)
  })

  it('the last subscriber leaving un-indexes the node, so the next create spawns', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    kill(ALICE, sessionId)

    const again = await create(ALICE)
    expect(spawned).toHaveLength(2)
    expect(again.sessionId).not.toBe(sessionId)
  })

  it('writes from any subscriber reach the one pty (no locking — they interleave)', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    write(ALICE, sessionId, 'a')
    write(BOB, sessionId, 'b')
    expect(spawned[0].writes).toEqual(['a', 'b'])
  })

  // Issue #1172: tmux's client handshake (DA1 `ESC[c`, DA2 `ESC[>c`) reaches EVERY subscriber's
  // xterm and every one answers. tmux consumes one answer; the rest used to be typed into the pane
  // (`1;2c0;276;0c` in front of an agent's launch line).
  it('only ONE viewer\'s answer to the client\'s DA handshake reaches the pty; keystrokes are untouched', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    spawned[0].onDataCb?.('\x1b[c\x1b[>c\x1b[>q\x1b]11;?\x1b\\')
    write(ALICE, sessionId, '\x1b[?1;2c')
    write(ALICE, sessionId, '\x1b[>0;276;0c')
    write(BOB, sessionId, '\x1b[?1;2c')
    write(BOB, sessionId, '\x1b[>0;276;0c')
    write(BOB, sessionId, '\x1b[1;2R') // Shift+F3, the same bytes as a cursor-position report
    write(ALICE, sessionId, 'claude\r')
    expect(spawned[0].writes).toEqual(['\x1b[?1;2c', '\x1b[>0;276;0c', '\x1b[1;2R', 'claude\r'])
  })

  it('a DA answer nobody asked for (or that arrives after the query expired) never reaches the pty', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    write(ALICE, sessionId, '\x1b[?1;2c')
    spawned[0].onDataCb?.('\x1b[>c')
    vi.advanceTimersByTime(60_000)
    write(ALICE, sessionId, '\x1b[>0;276;0c')
    expect(spawned[0].writes).toEqual([])
  })

  it('a destroyed node is never co-attached to, and never respawned (the × path un-indexes + tombstones it)', async () => {
    const m = await manager()
    await create(ALICE)
    await m.destroySession(ALICE, 'node-1') // user clicked ×: the tmux session is gone for good

    const second = await create(BOB)
    expect(second.sessionId).toBe('') // neither the dead session…
    expect(second.closed).toEqual({ by: ALICE }) // …nor a fresh one: the node is gone
    expect(spawned).toHaveLength(1)
  })

  // The agent-status mirror feeds the notch HUD, the phone's Live Activity and its Inbox. Deleting
  // a node used to tell it NOTHING — `clearNode` had no production caller — so those surfaces kept
  // rendering a node that no longer exists. It is wired at the one core chokepoint both shells
  // share (`endSession`), and gated on the DELETE intent: a RECYCLE keeps the node, so clearing
  // there would blank a live badge for a node still sitting on the canvas.
  it('a DELETE clears the node from the agent-status mirror; a RECYCLE keeps it', async () => {
    const mirror = await import('./agent-status-mirror')
    mirror._resetForTest()
    try {
      const m = await manager()
      await create(ALICE)
      mirror.recordAgentEvent({
        nodeId: 'node-1',
        agentId: 'claude',
        kind: 'state',
        state: 'working'
      } as never)
      expect(mirror._snapshot()['node-1']).toBeDefined()

      // A worktree move recycles the session; the node lives on, so its status must survive.
      await m.recycleSession(ALICE, 'node-1')
      expect(mirror._snapshot()['node-1']).toBeDefined()

      // The × is permanent — the entry goes with the node.
      await m.destroySession(ALICE, 'node-1')
      expect(mirror._snapshot()['node-1']).toBeUndefined()
    } finally {
      mirror._resetForTest()
    }
  })

  it('a relay-served (detached) pty is NOT indexed: it keeps its own session', async () => {
    const m = await manager()
    const chunks: string[] = []
    const detachedId = m.attachDetached('node-1', {
      onData: (d) => chunks.push(d),
      onExit: () => {}
    })
    // The host's detached pty must not be handed to a UI client asking for the same node.
    const ui = await create(ALICE)
    expect(ui.sessionId).not.toBe(detachedId)
    expect(spawned).toHaveLength(2)

    // The detached sink still receives its own session's output (relay path unchanged).
    spawned[0].onDataCb?.('host output')
    vi.advanceTimersByTime(20)
    expect(chunks).toEqual(['host output'])
  })

  it('the relay releases its detached pty via kill(null, …) even with no subscribers', async () => {
    const m = await manager()
    const id = m.attachDetached('node-1', { onData: () => {}, onExit: () => {} })
    m.kill(null, id)
    expect(spawned[0].killed).toBe(true)
  })

  // ── Flow control is OWED PER CLIENT (`pausedBy`) ─────────────────────────────────────────
  // Two invariants, and a single `paused` boolean per session can only ever satisfy one of them:
  //  (a) a pause owed by a client that LEFT is always returned  → nobody is frozen forever;
  //  (b) a pause owed by a client that is STILL HERE is never silently cancelled → its renderer's
  //      write queue cannot grow without bound (its flow control is EDGE-latched: once it has
  //      pumped `setFlow(false)` it will not re-pause, so a resume behind its back is permanent).
  it('a solo client pauses and resumes its own pty (single-user path unchanged)', async () => {
    await manager()
    const { sessionId } = await create(ALICE)

    flow(ALICE, sessionId, false)
    expect(spawned[0].paused).toBe(true)
    flow(ALICE, sessionId, true)
    expect(spawned[0].paused).toBe(false)
  })

  it('a client joining a session PAUSED by a client that left resumes the pty', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    flow(ALICE, sessionId, false) // Alice's xterm backlog crossed the high water mark
    expect(spawned[0].paused).toBe(true)

    // Alice's tab is gone; her renderer reloads (same client id) and re-creates the node. Her new
    // page has an empty backlog, so it will never send the resume her old page owed us.
    const again = await create(ALICE)
    expect(again.sessionId).toBe(sessionId)
    expect(spawned[0].paused).toBe(false)
  })

  it('a departing client cannot leave the pty paused for the subscribers that stay', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    flow(ALICE, sessionId, false)
    expect(spawned[0].paused).toBe(true)

    kill(ALICE, sessionId) // the client that paused it leaves
    expect(spawned[0].paused).toBe(false) // Bob's terminal keeps streaming
  })

  it('a DIFFERENT client joining does NOT cancel a pause the drowning client still owes', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    flow(ALICE, sessionId, false) // Alice is 1 MB behind a `yes`-grade flood
    expect(spawned[0].paused).toBe(true)

    await create(BOB) // Bob opens the same node — Alice is still drowning
    expect(spawned[0].paused).toBe(true) // resuming here would grow Alice's queue without bound

    flow(ALICE, sessionId, true) // Alice drains → the last owed resume lands
    expect(spawned[0].paused).toBe(false)
  })

  it('a DIFFERENT client leaving does NOT cancel a pause the drowning client still owes', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    flow(ALICE, sessionId, false)

    kill(BOB, sessionId) // Bob closes his tab; Alice is still behind
    expect(spawned[0].paused).toBe(true)
    expect(spawned[0].killed).toBe(false)
  })

  it('the pty resumes only when the LAST owed resume lands', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    flow(ALICE, sessionId, false)
    flow(BOB, sessionId, false)
    expect(spawned[0].paused).toBe(true)

    flow(ALICE, sessionId, true)
    expect(spawned[0].paused).toBe(true) // Bob is still behind
    flow(BOB, sessionId, true)
    expect(spawned[0].paused).toBe(false)
  })

  // ── One client, TWO pause owners (Server Edition) ────────────────────────────────────────
  // On the Server Edition a single uiId has two INDEPENDENT reasons to pause the same session:
  // its browser's own xterm backlog (`pty:flow` cast → owner 'renderer') and the server's WS
  // send-buffer backpressure (ServerPlatform → owner 'socket'). They drain at different times
  // (the socket empties as fast as the browser reads bytes; xterm parses them far slower), so a
  // ledger keyed by ClientId alone would let one hand back the other's pause — and the renderer's
  // flow control is EDGE-latched, so a resume behind its back is permanent (invariant (b)).
  it('a socket drain does NOT release the pause that client\'s RENDERER still owes', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE)

    flow(ALICE, sessionId, false) // Alice's xterm is 1 MB behind the flood
    m.setFlow(ALICE, sessionId, false, 'socket') // ...and her WS socket is backed up too
    expect(spawned[0].paused).toBe(true)

    m.setFlow(ALICE, sessionId, true, 'socket') // the socket drains into her browser
    expect(spawned[0].paused).toBe(true) // her xterm is STILL drowning — must stay paused

    flow(ALICE, sessionId, true) // her renderer finally drains
    expect(spawned[0].paused).toBe(false)
  })

  it('a socket-owed pause IS released when only the socket owed it', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE)

    m.setFlow(ALICE, sessionId, false, 'socket') // her renderer never paused (slow link, small xterm backlog)
    expect(spawned[0].paused).toBe(true)

    m.setFlow(ALICE, sessionId, true, 'socket')
    expect(spawned[0].paused).toBe(false)
  })

  it('a renderer resume does NOT release the pause that client\'s SOCKET still owes', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE)

    m.setFlow(ALICE, sessionId, false, 'socket')
    flow(ALICE, sessionId, true) // a stray/late renderer resume — the socket is still jammed
    expect(spawned[0].paused).toBe(true)
  })

  it('a client that disconnects owing BOTH kinds of pause returns both', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB) // Bob stays: the pty must keep streaming for him

    flow(ALICE, sessionId, false)
    m.setFlow(ALICE, sessionId, false, 'socket')
    expect(spawned[0].paused).toBe(true)

    m.dropClient(ALICE) // her tab vanished — neither pause can ever be returned by her
    expect(spawned[0].paused).toBe(false) // invariant (a): nobody is frozen forever
    expect(spawned[0].killed).toBe(false)
  })

  it('a client that KILLS a session while owing BOTH kinds of pause returns both', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)

    flow(ALICE, sessionId, false)
    m.setFlow(ALICE, sessionId, false, 'socket')
    kill(ALICE, sessionId) // Alice unmounts the node; she gets no more output for it
    expect(spawned[0].paused).toBe(false)
    expect(spawned[0].killed).toBe(false)
  })

  it('one client\'s socket drain leaves ANOTHER client\'s socket pause in place', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)

    m.setFlow(ALICE, sessionId, false, 'socket')
    m.setFlow(BOB, sessionId, false, 'socket')
    m.setFlow(ALICE, sessionId, true, 'socket')
    expect(spawned[0].paused).toBe(true) // Bob's socket is still jammed
    m.setFlow(BOB, sessionId, true, 'socket')
    expect(spawned[0].paused).toBe(false)
  })

  // ── Finding 2: a client that vanishes (WS close / destroyed webContents) is dropped ──────
  it('dropClient unsubscribes the client from EVERY session and releases the empty ones', async () => {
    const m = await manager()
    const shared = await create(ALICE, 80, 24, 'node-1')
    await create(BOB, 80, 24, 'node-1')
    const solo = await create(ALICE, 80, 24, 'node-2')

    m.dropClient(ALICE) // Alice's browser tab closed — no pty:kill ever arrives

    // node-1 still has Bob: the pty survives and keeps fanning out to him only.
    fake.sent.length = 0
    spawned[0].onDataCb?.('still here')
    vi.advanceTimersByTime(20)
    const data = fake.sent.filter((s) => s.channel === IPC.ptyData(shared.sessionId))
    expect(data.map((s) => s.to)).toEqual([BOB])
    expect(spawned[0].killed).toBe(false)

    // node-2 fell to zero subscribers: the pty client is released (the tmux session survives).
    expect(spawned[1].killed).toBe(true)
    const again = await create(BOB, 80, 24, 'node-2')
    expect(again.sessionId).not.toBe(solo.sessionId)
    expect(spawned).toHaveLength(3)
  })

  it('dropClient resumes a session the vanished client had paused', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    flow(ALICE, sessionId, false)

    m.dropClient(ALICE)
    expect(spawned[0].paused).toBe(false)
    expect(spawned[0].killed).toBe(false)
  })

  it('dropClient leaves a pause another (still present) client owes in place', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    flow(ALICE, sessionId, false)

    m.dropClient(BOB) // Bob's tab vanished; Alice is still drowning
    expect(spawned[0].paused).toBe(true)
  })

  it('dropClient leaves a relay-served (detached) pty alone', async () => {
    const m = await manager()
    const id = m.attachDetached('node-1', { onData: () => {}, onExit: () => {} })
    m.dropClient(ALICE)
    expect(spawned[0].killed).toBe(false)
    m.kill(null, id)
    expect(spawned[0].killed).toBe(true)
  })

  // ── Only a SUBSCRIBER may steer a shared session ─────────────────────────────────────────
  // Session ids are sequential and guessable (`pty-1`, `pty-2`, …) and every one of these casts
  // takes the id straight off the wire. Without a membership check, any authenticated client could
  // pause, clamp or type into a terminal it never opened — and since `dropClient` only ever swept
  // sessions the client was subscribed to, the pause/size it planted would outlive its tab and
  // freeze (or pin at 1x1) the shared pty for every real viewer, permanently.
  it('a non-subscriber cannot pause the shared pty', async () => {
    await manager()
    const { sessionId } = await create(ALICE)

    flow(BOB, sessionId, false) // Bob never opened this node
    expect(spawned[0].paused).toBe(false)
  })

  it('a non-subscriber cannot clamp the shared grid', async () => {
    await manager()
    const { sessionId } = await create(ALICE, 80, 24)
    fake.sent.length = 0

    resize(BOB, sessionId, 1, 1)
    expect(spawned[0].resizes).toEqual([]) // Alice's terminal keeps its size
    expect(fake.sent.filter((s) => s.channel === IPC.ptySize(sessionId))).toEqual([])
  })

  it('a non-subscriber cannot type into the shared pty', async () => {
    await manager()
    const { sessionId } = await create(ALICE)

    write(BOB, sessionId, 'rm -rf /\n')
    expect(spawned[0].writes).toEqual([])
  })

  it('a client that unsubscribed cannot keep steering the session it left', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    kill(BOB, sessionId)

    flow(BOB, sessionId, false)
    write(BOB, sessionId, 'x')
    resize(BOB, sessionId, 1, 1)
    expect(spawned[0].paused).toBe(false)
    expect(spawned[0].writes).toEqual([])
    expect(spawned[0].resizes).toEqual([])
  })

  // Belt and braces for the invariant the check above establishes: NOTHING a client left behind may
  // outlive it. dropClient sweeps every session, not just the ones it subscribes to, so even a
  // pause/size planted by some other (internal) path is returned when the client goes away.
  it('dropClient sweeps a pause the client owes on a session it never subscribed to', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE)
    m.setFlow(BOB, sessionId, false) // planted through the internal API, not the wire
    expect(spawned[0].paused).toBe(true)

    m.dropClient(BOB)
    expect(spawned[0].paused).toBe(false) // Alice's terminal is not frozen forever
  })

  it('dropClient sweeps a size the client owes on a session it never subscribed to', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE, 80, 24)
    m.resize(BOB, sessionId, 1, 1)
    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 1, rows: 1 })

    m.dropClient(BOB)
    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 80, rows: 24 }) // back to the real viewer
  })

  // ── Finding 3: the same-tick create race ────────────────────────────────────────────────
  // create() awaits a `tmux has-session` subprocess + the shell-PATH probe between the index
  // lookup and spawnSession's synchronous registration, so two clients opening the same node
  // in that window both used to spawn — and the second `tmux -A -D` kicked the first viewer off.
  it('two overlapping creates for the same node resolve to ONE spawn', async () => {
    await manager()
    const [a, b] = await Promise.all([create(ALICE), create(BOB)])

    expect(spawned).toHaveLength(1)
    expect(b.sessionId).toBe(a.sessionId)
    expect(a.fresh).toBe(true) // Alice's call did the spawn
    expect(b.fresh).toBe(false) // Bob joined it — no cold-restore replay
  })

  it('a failed spawn clears the in-flight entry, so the node stays openable', async () => {
    await manager()
    failNextSpawn = true
    await expect(create(ALICE)).rejects.toThrow(/Failed to spawn terminal/)

    const ok = await create(ALICE)
    expect(ok.sessionId).toBeTruthy()
    expect(spawned).toHaveLength(1)
  })

  it('a create racing a failed spawn still gets a live session', async () => {
    await manager()
    failNextSpawn = true
    const [a, b] = await Promise.allSettled([create(ALICE), create(BOB)])
    expect(a.status).toBe('rejected')
    expect(b.status).toBe('fulfilled')
    expect(spawned).toHaveLength(1) // Bob's create spawned after the failure cleared the entry
  })

  // TWO racers behind ONE failed spawn: the first survivor re-spawns, and the second must see
  // THAT spawn in `inflight` (the entry it awaited is long gone) instead of spawning again — a
  // second `tmux -A -D` would detach the first survivor's client, which is the very race the
  // in-flight guard exists to prevent.
  it('two creates racing a failed spawn resolve to ONE session, not two', async () => {
    await manager()
    failNextSpawn = true
    const [a, b, c] = await Promise.allSettled([create(ALICE), create(BOB), create(CAROL)])
    expect(a.status).toBe('rejected')
    expect(b.status).toBe('fulfilled')
    expect(c.status).toBe('fulfilled')
    expect(spawned).toHaveLength(1)
    const bId = b.status === 'fulfilled' ? b.value.sessionId : 'b'
    const cId = c.status === 'fulfilled' ? c.value.sessionId : 'c'
    expect(cId).toBe(bId)
  })
})

describe('size negotiation: smallest subscriber wins', () => {
  let fake: FakePlatform

  beforeEach(() => {
    spawned.length = 0
    failNextSpawn = false
    fake = fakePlatform()
    initPlatform(fake)
    vi.useFakeTimers()
  })
  afterEach(() => {
    vi.useRealTimers()
    resetPlatformForTests()
  })

  async function manager() {
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    return m
  }
  const create = (clientId: number, cols: number, rows: number, persistKey = 'node-1') =>
    fake.handlers[IPC.ptyCreate](clientId, { cols, rows, persistKey }) as Promise<{
      sessionId: string
      fresh: boolean
    }>
  // pty:resize is sender-aware now (a size must be attributed to the client that reported it).
  const resize = (
    clientId: number,
    sessionId: string,
    cols: number | null,
    rows: number | null
  ) => fake.senderListeners[IPC.ptyResize](clientId, sessionId, cols, rows)
  const kill = (clientId: number, sessionId: string) =>
    fake.senderListeners[IPC.ptyKill](clientId, sessionId)
  const sizes = (sessionId: string) =>
    fake.sent.filter((s) => s.channel === IPC.ptySize(sessionId))

  it('runs the pty at min(cols) x min(rows) and broadcasts it to every subscriber', async () => {
    await manager()
    const { sessionId } = await create(ALICE, 120, 40)
    fake.sent.length = 0
    await create(BOB, 80, 60) // narrower but taller

    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 80, rows: 40 })
    const sent = sizes(sessionId)
    expect(sent.map((s) => s.to).sort()).toEqual([ALICE, BOB])
    expect(sent.every((s) => s.args[0].cols === 80 && s.args[0].rows === 40)).toBe(true)
  })

  it('a joiner bigger than the pty is told the authoritative size (nothing is resized)', async () => {
    await manager()
    const { sessionId } = await create(ALICE, 80, 24)
    fake.sent.length = 0
    await create(BOB, 120, 40)

    // The pty already runs at 80x24 (Alice spawned it there) — do not make tmux redraw for nothing.
    expect(spawned[0].resizes).toEqual([])
    // Bob's xterm fitted itself to 120x40, so he MUST be told to render 80x24 and letterbox.
    const sent = sizes(sessionId)
    expect(sent.map((s) => s.to)).toEqual([BOB]) // Alice already renders 80x24 — no message for her
    expect(sent[0].args[0]).toEqual({ cols: 80, rows: 24 })
  })

  it('a subscriber growing its window does not grow the pty past the smaller peer', async () => {
    await manager()
    const { sessionId } = await create(ALICE, 80, 24)
    await create(BOB, 120, 40)
    fake.sent.length = 0
    resize(BOB, sessionId, 200, 80) // Bob maximizes

    expect(spawned[0].resizes.every((r) => r.cols <= 80 && r.rows <= 24)).toBe(true)
    // Bob's own fit is not authoritative: he is told (again) to render Alice's size.
    const sent = sizes(sessionId)
    expect(sent.map((s) => s.to)).toEqual([BOB])
    expect(sent[0].args[0]).toEqual({ cols: 80, rows: 24 })
  })

  it('when the smallest subscriber leaves, the pty grows back to the remaining one', async () => {
    await manager()
    const { sessionId } = await create(ALICE, 80, 24)
    await create(BOB, 120, 40)

    fake.sent.length = 0
    kill(ALICE, sessionId)
    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 120, rows: 40 })
    const sent = sizes(sessionId)
    expect(sent.map((s) => s.to)).toEqual([BOB])
    expect(sent[0].args[0]).toEqual({ cols: 120, rows: 40 })
  })

  // ── The single-user path must stay bit-for-bit identical ─────────────────────────────────
  it('a solo subscriber resizes the pty to its own size, with no pty:size traffic at all', async () => {
    await manager()
    const { sessionId } = await create(ALICE, 80, 24)
    fake.sent.length = 0

    resize(ALICE, sessionId, 100, 30)
    expect(spawned[0].resizes).toEqual([{ cols: 100, rows: 30 }]) // min(one) is Alice's own size
    // Alice already renders what she asked for: telling her would be pure round-trip noise.
    expect(sizes(sessionId)).toEqual([])

    // Same fit reported twice (a ResizeObserver tick that changed nothing) → no second ioctl.
    resize(ALICE, sessionId, 100, 30)
    expect(spawned[0].resizes).toHaveLength(1)
  })

  // ── A PARKED terminal is subscribed but not looking ──────────────────────────────────────
  // The renderer keeps a node's xterm+PTY alive for the park window after unmount (`settings.terminalParkMinutes`), so a
  // parked client stays a subscriber. Its (possibly tiny) last fit must NOT shrink the terminal
  // for the people still watching — it reports a null size instead: "listening, not viewing".
  it('a parked subscriber (null size) stops constraining the shared pty but keeps its output', async () => {
    await manager()
    const { sessionId } = await create(ALICE, 80, 24)
    await create(BOB, 120, 40)
    fake.sent.length = 0

    resize(ALICE, sessionId, null, null) // Alice's node unmounted → parked
    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 120, rows: 40 }) // Bob gets his full size back
    expect(sizes(sessionId).map((s) => s.to).sort()).toEqual([ALICE, BOB])

    // Parked ≠ gone: the parked xterm keeps consuming output (that is what makes re-adoption exact).
    fake.sent.length = 0
    spawned[0].onDataCb?.('still streaming')
    vi.advanceTimersByTime(20)
    const data = fake.sent.filter((s) => s.channel === IPC.ptyData(sessionId))
    expect(data.map((s) => s.to).sort()).toEqual([ALICE, BOB])

    // Un-parking (re-adopt → fresh fit) makes her constrain again.
    resize(ALICE, sessionId, 80, 24)
    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 80, rows: 24 })
  })

  it('a parked SOLO subscriber leaves the pty size alone (nobody is left to size it)', async () => {
    await manager()
    const { sessionId } = await create(ALICE, 80, 24)
    fake.sent.length = 0

    resize(ALICE, sessionId, null, null)
    expect(spawned[0].resizes).toEqual([]) // no viewers → keep the last size, never resize to 1x1
    expect(sizes(sessionId)).toEqual([])
  })

  // In the Server Edition the park signal does not arrive as a function call: the browser
  // JSON-serialises it, the server parses it with `parseRpcMessage` and dispatches it into THIS
  // handler. A decoder that rewrote every top-level `null` to `undefined` made the strict park
  // check miss, so `normalizeSize(undefined, undefined)` clamped to {1,1}: the parked client stayed
  // in the ledger claiming a 1×1 grid, and the min over subscribers collapsed the shared pty (and
  // its tmux pane) to 1 column × 1 row for EVERY co-attached viewer — permanently, because a parked
  // client never re-reports. So the wire itself is part of the contract.
  it('parks (never 1x1) when the park signal comes over the WS-RPC wire', async () => {
    await manager()
    const { sessionId } = await create(ALICE, 80, 24)
    await create(BOB, 120, 40)

    const frame = JSON.stringify({
      t: 'cast',
      method: IPC.ptyResize,
      ...encodeArgs([sessionId, null, null])
    })
    const m = parseRpcMessage(frame) as { method: string; args: unknown[] }
    expect(m.args).toEqual([sessionId, null, null]) // the nulls MEAN something — they survive
    fake.senderListeners[m.method](ALICE, ...m.args)

    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 120, rows: 40 }) // Bob's own size, not 1×1
    expect(spawned[0].resizes.some((r) => r.cols === 1 || r.rows === 1)).toBe(false)
  })

  // Belt and braces: should any future encoding path lose the `null` again, the park check is loose
  // (`== null`), so an `undefined` size degrades to PARK — the safe direction — instead of 1×1.
  it('treats an undefined size as park, not as a 1x1 grid', async () => {
    const m = await manager()
    const { sessionId } = await create(ALICE, 80, 24)
    await create(BOB, 120, 40)

    m.resize(ALICE, sessionId, undefined as unknown as null, undefined as unknown as null)
    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 120, rows: 40 })
    expect(spawned[0].resizes.some((r) => r.cols === 1 || r.rows === 1)).toBe(false)
  })
})

// ── A node DELETED while somebody else is watching it ─────────────────────────────────────────
// The × button means "this terminal is gone for good" (tmux kill-session). With co-attach the
// node may have other viewers, and the one thing they must NOT do is quietly reopen it: a respawn
// would resurrect a session its owner deliberately destroyed — in a fresh shell, with none of the
// state, and leaving a stray tmux session behind. They are told WHO closed it instead, and land in
// a closed state (the renderer paints "closed by <name>" from the presence table — Tasks 9-10).
describe('node destroyed while co-viewed', () => {
  let fake: FakePlatform

  beforeEach(() => {
    spawned.length = 0
    failNextSpawn = false
    fake = fakePlatform()
    initPlatform(fake)
    vi.useFakeTimers()
  })
  afterEach(() => {
    vi.useRealTimers()
    resetPlatformForTests()
  })

  async function manager() {
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    return m
  }
  const create = (clientId: number, persistKey = 'node-1') =>
    fake.handlers[IPC.ptyCreate](clientId, { cols: 80, rows: 24, persistKey }) as Promise<{
      sessionId: string
      fresh: boolean
      closed?: { by: number | null }
    }>
  // pty:destroy is sender-aware: the closed event has to name WHO pressed ×.
  const destroy = (clientId: number, persistKey = 'node-1') =>
    fake.senderListeners[IPC.ptyDestroy](clientId, persistKey) as unknown as Promise<void>
  const flow = (clientId: number, sessionId: string, resume: boolean) =>
    fake.senderListeners[IPC.ptyFlow](clientId, sessionId, resume)
  const closed = (sessionId: string) =>
    fake.sent.filter((s) => s.channel === IPC.ptyClosed(sessionId))

  it('tells the OTHER subscribers who closed it, and does not respawn', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)

    fake.sent.length = 0
    await destroy(ALICE) // Alice hits the × on the node

    expect(closed(sessionId).map((s) => s.to)).toEqual([BOB]) // the closer does not need telling
    expect(closed(sessionId)[0].args[0]).toEqual({ by: ALICE })
    expect(spawned[0].killed).toBe(true) // the pty client is released with the session
    expect(spawned).toHaveLength(1) // …and nothing respawned it
  })

  // The `pty:closed` event only reaches SUBSCRIBERS. A co-viewer whose project is inactive/closed
  // has no mounted terminal, is not subscribed, and hears nothing — its canvas still has the node,
  // so opening that project later would `create` it and RESURRECT a terminal its owner deliberately
  // deleted, in a fresh shell. The tombstone is what makes that create refuse instead of spawn.
  it('a create by ANOTHER client after the destroy is refused — it never resurrects the node', async () => {
    await manager()
    await create(ALICE)
    await create(BOB)
    await destroy(ALICE)

    const again = await create(BOB)
    expect(again.closed).toEqual({ by: ALICE }) // "closed by Alice", not a brand-new shell
    expect(again.sessionId).toBe('')
    expect(spawned).toHaveLength(1) // …and nothing was spawned
  })

  it('a create by a client that never saw the destroy is refused too (unsubscribed co-viewer)', async () => {
    await manager()
    await create(ALICE)
    await destroy(ALICE) // Carol was not watching — she got no pty:closed

    const carol = await create(CAROL)
    expect(carol.closed).toEqual({ by: ALICE })
    expect(spawned).toHaveLength(1)
  })

  it('the client that DELETED the node may still respawn it (undo) — and that clears the tombstone', async () => {
    await manager()
    await create(ALICE)
    await destroy(ALICE)

    // ⌘Z restores the node on Alice's canvas: her own re-create must spawn, exactly as it always
    // did (the single-user delete→undo path is untouched by the tombstone).
    const undone = await create(ALICE)
    expect(undone.closed).toBeUndefined()
    expect(undone.fresh).toBe(true)
    expect(spawned).toHaveLength(2)
    // The node is alive again, so a co-viewer must be able to join it rather than stay tombstoned.
    const bob = await create(BOB)
    expect(bob.sessionId).toBe(undone.sessionId)
  })

  it('a RECYCLE (worktree move) leaves no tombstone — the node is not deleted', async () => {
    await manager()
    await create(ALICE)
    await create(BOB)
    await (fake.senderListeners[IPC.ptyRecycle](ALICE, 'node-1') as unknown as Promise<void>)

    const again = await create(ALICE) // the mover respawns in the new cwd
    expect(again.closed).toBeUndefined()
    const bob = await create(BOB) // and the co-viewer joins it
    expect(bob.sessionId).toBe(again.sessionId)
    expect(spawned).toHaveLength(2)
  })

  it('the destroyed session stops fanning out: no data, and no exit after the close', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    await destroy(ALICE)

    fake.sent.length = 0
    spawned[0].onDataCb?.('ghost output') // the pty client is being torn down
    vi.advanceTimersByTime(20)
    spawned[0].onExitCb?.({ exitCode: 1 }) // …and its exit lands after the close event
    expect(fake.sent.filter((s) => s.channel === IPC.ptyData(sessionId))).toEqual([])
    // "[process exited with code 1]" on top of "closed by Alice" would be noise at best: the
    // subscribers were told the truth already, and the session is off the books.
    expect(fake.sent.filter((s) => s.channel === IPC.ptyExit(sessionId))).toEqual([])
  })

  it('releases a session a subscriber had PAUSED (a dying pty must not keep its fd)', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    flow(BOB, sessionId, false) // Bob's xterm is drowning — the pty is paused for everyone
    expect(spawned[0].paused).toBe(true)

    await destroy(ALICE)
    // releasePty resumes before destroying: a paused pty never reads EOF, so it would otherwise
    // leak its master fd (see pty-release.ts). Bob owes a resume that will never come — the
    // session is gone, so the ledger goes with it.
    expect(spawned[0].paused).toBe(false)
    expect(spawned[0].killed).toBe(true)
    expect(closed(sessionId).map((s) => s.to)).toEqual([BOB])
  })

  it('a destroy with no live session still tells nobody and kills the tmux session', async () => {
    await manager()
    // Nothing was ever created for node-9 in this process (e.g. it is only running in tmux).
    await destroy(ALICE, 'node-9')
    expect(fake.sent).toEqual([])
    expect(spawned).toHaveLength(0)
  })
})

// ── The destroy path takes a node id straight off the wire ────────────────────────────────────
// `endSession('delete')` records a tombstone EVEN WHEN NO LIVE SESSION EXISTS, keyed by a string
// the client chose, in a map nothing ever prunes — and it runs an fs.rm + a `tmux kill-session`
// subprocess per call, on channels that (unlike the presence casts) had no rate limit at all.
describe('destroy/recycle: bounded, validated, rate-limited', () => {
  let fake: FakePlatform

  beforeEach(() => {
    spawned.length = 0
    failNextSpawn = false
    fake = fakePlatform()
    initPlatform(fake)
    vi.useFakeTimers()
  })
  afterEach(() => {
    vi.useRealTimers()
    resetPlatformForTests()
  })

  async function manager() {
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    return m
  }
  const create = (clientId: number, persistKey: string) =>
    fake.handlers[IPC.ptyCreate](clientId, { cols: 80, rows: 24, persistKey }) as Promise<{
      sessionId: string
      fresh: boolean
      closed?: { by: number | null }
    }>
  const destroy = (clientId: number, persistKey: string) =>
    fake.senderListeners[IPC.ptyDestroy](clientId, persistKey) as unknown as Promise<void>

  it('refuses a persistKey longer than REF_MAX_LEN (no tombstone, no subprocess)', async () => {
    const { REF_MAX_LEN } = await import('../shared/presence')
    const m = await manager()
    const huge = 'x'.repeat(REF_MAX_LEN + 1)

    await destroy(ALICE, huge)
    // Nothing was recorded, so this is not a node anyone can be locked out of. Read the map
    // DIRECTLY rather than probing with `create`: an over-long id is now refused at the create
    // choke point too (the node-id guard, added with the remote-injection fix), so a create's
    // outcome no longer distinguishes "no tombstone" from "refused for another reason".
    expect((m as unknown as { tombstones: Map<string, unknown> }).tombstones.size).toBe(0)
    // And the second layer, on the same value: it can never be spent on a spawn either.
    await expect(create(BOB, huge)).rejects.toThrow(/node id/i)
  })

  it('bounds the tombstone map: the oldest entries are evicted, the newest still refuse', async () => {
    const { TOMBSTONE_MAX } = await import('./pty-manager')
    const m = await manager()
    // Straight through the internal API: the bound must hold on its own, not because the rate limit
    // happens to run out first (the two are independent defences and their numbers may diverge).
    for (let i = 0; i < TOMBSTONE_MAX + 1; i++) await m.destroySession(ALICE, `node-${i}`)

    // The first delete has been evicted — the map is bounded, it cannot grow with client input.
    const evicted = await create(BOB, 'node-0')
    expect(evicted.closed).toBeUndefined()
    // …and the guard still does its job for everything still in it.
    const kept = await create(BOB, `node-${TOMBSTONE_MAX}`)
    expect(kept.closed).toEqual({ by: ALICE })
  })

  it('expires a tombstone after its TTL (the map cannot hold entries for the life of the core)', async () => {
    const { TOMBSTONE_TTL_MS } = await import('./pty-manager')
    await manager()
    await create(ALICE, 'node-1')
    await destroy(ALICE, 'node-1')
    expect((await create(BOB, 'node-1')).closed).toEqual({ by: ALICE })

    vi.advanceTimersByTime(TOMBSTONE_TTL_MS + 1)
    expect((await create(CAROL, 'node-1')).closed).toBeUndefined()
  })

  it('rate-limits the destroy cast, and the burst still covers a bulk delete', async () => {
    const { PTY_END_BUDGET } = await import('./pty-manager')
    await manager()
    // A real bulk delete (select N nodes → Delete) fires one cast per node in a single tick: every
    // one of them must land, or a solo user silently leaks tmux sessions.
    for (let i = 0; i < PTY_END_BUDGET.burst; i++) await destroy(ALICE, `node-${i}`)
    expect((await create(BOB, 'node-0')).closed).toEqual({ by: ALICE })

    // Past the burst the flood is dropped: no tombstone entry, no fs.rm, no tmux subprocess.
    await destroy(ALICE, 'flood-1')
    expect((await create(BOB, 'flood-1')).closed).toBeUndefined()
  })

  it('the SOLO delete → undo path is untouched', async () => {
    await manager()
    await create(ALICE, 'node-1')
    await destroy(ALICE, 'node-1')

    const undone = await create(ALICE, 'node-1') // ⌘Z
    expect(undone.closed).toBeUndefined()
    expect(undone.fresh).toBe(true)
  })
})

// ── A node RECYCLED (moved into a worktree) while somebody else is watching it ────────────────
// "Move into worktree" ends the node's tmux session so the SAME node id respawns in the new cwd.
// The node never leaves anybody's canvas and it keeps working — so a co-viewer must NOT be told
// "closed by <name>" (which is permanent and un-respawnable). They are told the session RESTARTED,
// and only once the replacement session exists: notify them any earlier and their own re-create
// could win the race and spawn the tmux session in their STALE cwd, silently undoing the move.
describe('node recycled (worktree move) while co-viewed', () => {
  let fake: FakePlatform

  beforeEach(() => {
    spawned.length = 0
    failNextSpawn = false
    fake = fakePlatform()
    initPlatform(fake)
    vi.useFakeTimers()
  })
  afterEach(() => {
    vi.useRealTimers()
    resetPlatformForTests()
  })

  async function manager() {
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    return m
  }
  const create = (clientId: number, persistKey = 'node-1') =>
    fake.handlers[IPC.ptyCreate](clientId, { cols: 80, rows: 24, persistKey }) as Promise<{
      sessionId: string
      fresh: boolean
    }>
  // pty:recycle is sender-aware: the client that recycled drives its OWN respawn, so it must be
  // excluded from the restart notice (it would otherwise respawn twice).
  const recycle = (clientId: number, persistKey = 'node-1') =>
    fake.senderListeners[IPC.ptyRecycle](clientId, persistKey) as unknown as Promise<void>
  const closed = (sessionId: string) =>
    fake.sent.filter((s) => s.channel === IPC.ptyClosed(sessionId))
  const recycled = (sessionId: string) =>
    fake.sent.filter((s) => s.channel === IPC.ptyRecycled(sessionId))

  it('never tells a co-viewer the node was CLOSED — it is still on their canvas', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)

    fake.sent.length = 0
    await recycle(ALICE)
    expect(closed(sessionId)).toEqual([]) // the un-respawnable "closed by <name>" state must NOT fire
    expect(spawned[0].killed).toBe(true) // the old pty is still released with its session
  })

  it('holds the restart notice until the replacement session exists, then joins the co-viewer to it', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)

    fake.sent.length = 0
    await recycle(ALICE)
    // Nothing yet: notifying Bob here would let his re-create spawn `nt-node-1` in his stale cwd.
    expect(recycled(sessionId)).toEqual([])

    const fresh = await create(ALICE) // Alice respawns the node in the worktree cwd
    expect(spawned).toHaveLength(2)
    expect(fresh.sessionId).not.toBe(sessionId)
    expect(recycled(sessionId).map((s) => s.to)).toEqual([BOB]) // only now is Bob told
    // `ready` is what makes Bob's restart safe: there IS a session to co-attach to.
    expect(recycled(sessionId)[0].args[0]).toEqual({ ready: true })

    const bob = await create(BOB) // Bob's terminal restarts…
    expect(bob.sessionId).toBe(fresh.sessionId) // …onto the LIVE new session
    expect(bob.fresh).toBe(false) // a co-attach, not a resurrection
    expect(spawned).toHaveLength(2) // and nothing extra was spawned
  })

  it('never sends the restart notice to the client that recycled', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)
    await recycle(ALICE)
    await create(ALICE)
    expect(recycled(sessionId).map((s) => s.to)).not.toContain(ALICE)
  })

  it('a co-viewer is never left on a dead pty: the notice fires even if nobody respawns', async () => {
    await manager()
    const { sessionId } = await create(ALICE)
    await create(BOB)

    fake.sent.length = 0
    await recycle(ALICE)
    expect(recycled(sessionId)).toEqual([])
    // Alice's app quit / crashed mid-move: no replacement session is ever registered. Bob still
    // has to be released from the dead session, so the notice fires on a timeout.
    vi.advanceTimersByTime(15_000)
    expect(recycled(sessionId).map((s) => s.to)).toEqual([BOB])
    // …but it says there is NOTHING to restart onto. Bob must not spawn `nt-node-1` himself: his
    // options still carry the node's OLD cwd, so his session would silently undo the move (and
    // Alice's app, on its return, would `new-session -A` straight back into that stale-cwd
    // session). He shows "session ended — reopen to restart" instead.
    expect(recycled(sessionId)[0].args[0]).toEqual({ ready: false })
  })

  it('a recycle with no other subscriber notifies nobody (the solo path is untouched)', async () => {
    await manager()
    await create(ALICE)
    fake.sent.length = 0
    await recycle(ALICE)
    await create(ALICE)
    vi.advanceTimersByTime(15_000)
    expect(fake.sent.filter((s) => s.channel.startsWith('pty:recycled:'))).toEqual([])
    expect(fake.sent.filter((s) => s.channel.startsWith('pty:closed:'))).toEqual([])
  })
})

// ── A joiner's screen has to be PAINTED ───────────────────────────────────────────────────────
// A co-attaching client gets `fresh:false` (no cold-restore replay) and joins an existing tmux
// client, so the ONLY thing that could paint its empty xterm is a tmux redraw — and tmux only
// redraws on SIGWINCH, i.e. when the join actually RESIZES the pty. A joiner whose grid is EQUAL
// (the expected case: same persisted node geometry, same font) or LARGER resizes nothing, so it
// would stare at a blank-but-live terminal until the next byte of output. The join therefore
// carries the CURRENT SCREEN, captured from tmux — the same bytes the drop-and-redraw path uses.
describe('a joiner is painted from the current screen', () => {
  let fake: FakePlatform

  beforeEach(() => {
    spawned.length = 0
    failNextSpawn = false
    fake = fakePlatform()
    initPlatform(fake)
    vi.useFakeTimers()
  })
  afterEach(() => {
    vi.useRealTimers()
    resetPlatformForTests()
  })

  async function manager() {
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    return m
  }
  const create = (clientId: number, cols = 80, rows = 24, persistKey = 'node-1') =>
    fake.handlers[IPC.ptyCreate](clientId, { cols, rows, persistKey }) as Promise<{
      sessionId: string
      fresh: boolean
      screen?: string
    }>

  it('paints a joiner whose grid EQUALS the pty (nothing is resized, so tmux never redraws)', async () => {
    const m = await manager()
    const capture = vi.spyOn(m, 'captureForResync').mockResolvedValue('$ ls\r\nREADME.md')
    const a = await create(ALICE, 80, 24)

    const b = await create(BOB, 80, 24)
    expect(b.sessionId).toBe(a.sessionId)
    expect(spawned[0].resizes).toEqual([]) // equal grids → no SIGWINCH → no tmux redraw
    expect(capture).toHaveBeenCalledWith(a.sessionId)
    expect(b.screen).toBe('$ ls\r\nREADME.md') // …so the screen rides the create result instead
  })

  it('paints a joiner BIGGER than the pty (it letterboxes; the pty is not resized)', async () => {
    const m = await manager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    await create(ALICE, 80, 24)

    const b = await create(BOB, 120, 40)
    expect(spawned[0].resizes).toEqual([])
    expect(b.screen).toBe('current screen')
  })

  it('does NOT paint a joiner that shrinks the pty — tmux redraws it, and two paints would splice', async () => {
    const m = await manager()
    const capture = vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    await create(ALICE, 120, 40)

    const b = await create(BOB, 80, 24) // strictly smaller → the pty resizes → tmux redraws
    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 80, rows: 24 })
    expect(capture).not.toHaveBeenCalled()
    expect(b.screen).toBeUndefined()
  })

  it('never paints a SOLO user: a fresh spawn has nothing to paint, and a reattach gets tmux own redraw', async () => {
    const m = await manager()
    const capture = vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    const a = await create(ALICE, 80, 24)
    expect(a.screen).toBeUndefined()
    expect(capture).not.toHaveBeenCalled()
  })

  it('omits the screen when the capture comes back empty (plain shell / tmux unavailable)', async () => {
    const m = await manager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('')
    await create(ALICE, 80, 24)

    const b = await create(BOB, 80, 24)
    expect(b.screen).toBeUndefined() // never an empty payload — the renderer would reset for nothing
    expect(b.fresh).toBe(false)
  })
})

// ── A joiner must be told tmux's mouse tracking is ON ─────────────────────────────────────────
// tmux emits the mouse-enable DECSET sequences (?1000h/?1002h/?1006h) to a client ONLY at its own
// attach. A co-attach subscriber (kanban card modal, second window) joins mid-stream and never
// sees them; neither the `screen` capture (capture-pane carries no private modes) nor a SIGWINCH
// redraw re-emits them. So the joiner's xterm reports no mouse events and the wheel can't scroll
// tmux history until a keystroke wakes it. `coAttachMouse` tells the renderer to enable it — set on
// EVERY tmux-backed join (both the screen-painted and the resized branch), never on a plain-shell
// join (no tmux ⇒ no tmux mouse) nor on the solo spawn.
describe('a tmux-backed joiner is told to enable mouse tracking', () => {
  let fake: FakePlatform

  beforeEach(() => {
    spawned.length = 0
    failNextSpawn = false
    fake = fakePlatform()
    initPlatform(fake)
    vi.useFakeTimers()
  })
  afterEach(() => {
    vi.useRealTimers()
    resetPlatformForTests()
  })

  // A manager whose sessions are tmux-BACKED: force the tmux path (init()/tmuxStatus() aren't run
  // in unit tests) and stub the has-session probe so no real tmux socket is touched.
  async function tmuxManager() {
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    ;(m as unknown as { tmuxPath: string }).tmuxPath = '/usr/bin/tmux'
    vi.spyOn(m as unknown as { tmuxSessionExists: (k: string) => Promise<boolean> }, 'tmuxSessionExists').mockResolvedValue(false)
    return m
  }
  const create = (clientId: number, cols = 80, rows = 24, persistKey = 'node-1') =>
    fake.handlers[IPC.ptyCreate](clientId, { cols, rows, persistKey }) as Promise<{
      sessionId: string
      fresh: boolean
      screen?: string
      coAttachMouse?: boolean
      coAttachAltScreen?: boolean
      tmuxClient?: boolean
    }>

  it('sets coAttachMouse on a joiner whose grid EQUALS the pty (the screen-painted branch)', async () => {
    const m = await tmuxManager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    await create(ALICE, 80, 24)

    const b = await create(BOB, 80, 24)
    expect(b.screen).toBe('current screen') // equal grid → painted from the capture…
    expect(b.coAttachMouse).toBe(true) // …which carries no mouse modes, so enable them explicitly
  })

  it('sets coAttachMouse on a joiner that SHRINKS the pty too (a SIGWINCH redraw re-emits no mouse modes)', async () => {
    const m = await tmuxManager()
    const capture = vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    await create(ALICE, 120, 40)

    const b = await create(BOB, 80, 24) // strictly smaller → the pty resizes, tmux redraws
    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 80, rows: 24 })
    expect(capture).not.toHaveBeenCalled() // tmux paints it; no screen rides the result…
    expect(b.screen).toBeUndefined()
    expect(b.coAttachMouse).toBe(true) // …but the redraw does NOT re-send mouse modes, so still enable
  })

  it('never sets coAttachMouse on the SOLO spawn (that client got its modes from its own tmux attach)', async () => {
    await tmuxManager()
    const a = await create(ALICE, 80, 24)
    expect(a.coAttachMouse).toBeUndefined()
  })

  it('never sets coAttachMouse on a PLAIN-SHELL join (no tmux ⇒ no tmux mouse to enable)', async () => {
    // The default manager has no tmux path, so the session is not persisted (persistKey unset).
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    await create(ALICE, 80, 24)

    const b = await create(BOB, 80, 24)
    expect(b.fresh).toBe(false) // it did join the live session…
    expect(b.coAttachMouse).toBeUndefined() // …but a plain shell has no tmux mouse to turn on
  })

  // A joiner also missed tmux's attach-time `\e[?1049h`, so its xterm stays on the NORMAL buffer
  // (scrollback piles up; every output frame forces a layout). `coAttachAltScreen` tells it to
  // enter the alternate buffer — tmux-backed only: a plain shell's normal-buffer scrollback is the
  // only history it has.
  it('sets coAttachAltScreen on a tmux-backed joiner whose grid EQUALS the pty (the screen-painted branch)', async () => {
    const m = await tmuxManager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    await create(ALICE, 80, 24)

    const b = await create(BOB, 80, 24)
    expect(b.screen).toBe('current screen')
    expect(b.coAttachAltScreen).toBe(true)
  })

  it('sets coAttachAltScreen on a joiner that SHRINKS the pty too', async () => {
    const m = await tmuxManager()
    const capture = vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    await create(ALICE, 120, 40)

    const b = await create(BOB, 80, 24)
    expect(capture).not.toHaveBeenCalled()
    expect(b.screen).toBeUndefined()
    expect(b.coAttachAltScreen).toBe(true)
  })

  it('never sets coAttachAltScreen on the SOLO spawn', async () => {
    await tmuxManager()
    const a = await create(ALICE, 80, 24)
    expect(a.coAttachAltScreen).toBeUndefined()
  })

  // A resync's `term.reset()` drops ANY tmux client (the solo spawn too, not only a joiner) out of
  // the alternate buffer and clears its mouse tracking. `tmuxClient` tells the renderer to put
  // both back — so it rides EVERY tmux-backed create, never a plain shell's.
  it('sets tmuxClient on the SOLO tmux spawn and on a tmux join', async () => {
    const m = await tmuxManager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    const a = await create(ALICE, 80, 24)
    expect(a.tmuxClient).toBe(true)
    const b = await create(BOB, 80, 24)
    expect(b.tmuxClient).toBe(true)
  })

  it('never sets tmuxClient for a plain shell (spawn or join)', async () => {
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    const a = await create(ALICE, 80, 24)
    expect(a.tmuxClient).toBeUndefined()
    const b = await create(BOB, 80, 24)
    expect(b.fresh).toBe(false)
    expect(b.tmuxClient).toBeUndefined()
  })

  it('does NOT set coAttachAltScreen on a plain-shell join (its scrollback is the only history)', async () => {
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    await create(ALICE, 80, 24)

    const b = await create(BOB, 80, 24)
    expect(b.fresh).toBe(false)
    expect(b.coAttachAltScreen).toBeUndefined()
  })
})

describe('tmuxAttachFlags', () => {
  it("keeps -D for the app's own client: exactly ONE tmux client per session", async () => {
    const { tmuxAttachFlags } = await import('./pty-manager')
    // Co-attach adds subscribers to OUR session — it never adds a tmux client, so -D stays.
    expect(tmuxAttachFlags(false)).toEqual(['-A', '-D'])
    // A relay-served (detached) pty mirrors the host's own client → must NOT detach it.
    expect(tmuxAttachFlags(true)).toEqual(['-A'])
  })
})

// ── Viewer identity: one connection holds MANY independently-detachable views ──────────────────
// The kanban card modal opens a SECOND terminal view of a node's tmux session INSIDE the same
// desktop renderer. Both views present the SAME ClientId (one webContents), so the subscriber
// ledger keys on the composite (ClientId, viewerId ?? PRIMARY): the modal is a real second
// subscriber, its size votes independently, and closing it detaches ONLY it — the canvas node's
// client (and everyone else's) is untouched. An absent viewerId is the PRIMARY view (the canvas
// node), and every legacy call omits it, so it maps bit-for-bit to today's single-subscriber path.
describe('viewer identity: multiple views per connection', () => {
  let fake: FakePlatform

  beforeEach(() => {
    spawned.length = 0
    failNextSpawn = false
    fake = fakePlatform()
    initPlatform(fake)
    vi.useFakeTimers()
  })
  afterEach(() => {
    vi.useRealTimers()
    resetPlatformForTests()
  })

  async function manager() {
    const { PtyManager } = await import('./pty-manager')
    const m = new PtyManager()
    m.registerIpc()
    return m
  }
  // create carries an optional viewerId in its options; kill/resize carry it as a TRAILING arg.
  const createV = (
    clientId: number,
    viewerId: string | undefined,
    cols = 80,
    rows = 24,
    persistKey = 'node-1'
  ) =>
    fake.handlers[IPC.ptyCreate](clientId, { cols, rows, persistKey, viewerId }) as Promise<{
      sessionId: string
      fresh: boolean
      screen?: string
    }>
  const killV = (clientId: number, sessionId: string, viewerId?: string) =>
    fake.senderListeners[IPC.ptyKill](clientId, sessionId, viewerId)
  const resizeV = (
    clientId: number,
    sessionId: string,
    cols: number | null,
    rows: number | null,
    viewerId?: string
  ) => fake.senderListeners[IPC.ptyResize](clientId, sessionId, cols, rows, viewerId)
  const write = (clientId: number, sessionId: string, data: string) =>
    fake.senderListeners[IPC.ptyWrite](clientId, sessionId, data)

  it('a second VIEW in the same client joins the session (same id, painted, both subscribed)', async () => {
    const m = await manager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('current screen')
    const a = await createV(ALICE, undefined) // the canvas node (PRIMARY)
    const b = await createV(ALICE, 'modal') // the kanban card modal, SAME renderer

    expect(spawned).toHaveLength(1) // ONE pty, ONE tmux client
    expect(b.sessionId).toBe(a.sessionId) // the modal JOINED the live session
    expect(b.fresh).toBe(false) // …so no cold-restore replay
    expect(b.screen).toBe('current screen') // …and its empty xterm is painted from the screen

    // Data fans out to the shared renderer ONCE — both views listen on the same per-client channel,
    // so a second send would double every byte in both xterms.
    spawned[0].onDataCb?.('hi')
    vi.advanceTimersByTime(20)
    const data = fake.sent.filter((s) => s.channel === IPC.ptyData(a.sessionId))
    expect(data.map((s) => s.to)).toEqual([ALICE])

    // Two independent subscribers now share the client: the pty is released only when BOTH leave.
    killV(ALICE, a.sessionId, 'modal')
    expect(spawned[0].killed).toBe(false)
    killV(ALICE, a.sessionId) // the PRIMARY view (no viewerId)
    expect(spawned[0].killed).toBe(true)
  })

  it('killing the modal view detaches ONLY it — the primary keeps the session and still steers it', async () => {
    const m = await manager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('x')
    const { sessionId } = await createV(ALICE, undefined)
    await createV(ALICE, 'modal')

    killV(ALICE, sessionId, 'modal') // close the card modal
    expect(spawned[0].killed).toBe(false) // pty untouched — the canvas node still watches

    write(ALICE, sessionId, 'ls\n') // the client still has a view, so it may still write
    expect(spawned[0].writes).toEqual(['ls\n'])
  })

  it('a modal view resizing smaller shrinks the shared pty; closing it restores the primary size', async () => {
    const m = await manager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('x')
    const { sessionId } = await createV(ALICE, undefined, 120, 40) // primary 120x40
    await createV(ALICE, 'modal', 120, 40) // modal joins at the same grid

    resizeV(ALICE, sessionId, 80, 24, 'modal') // the card modal is a smaller pane
    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 80, rows: 24 }) // min shrinks the pty

    killV(ALICE, sessionId, 'modal') // close the modal → its size vote is withdrawn
    expect(spawned[0].resizes.at(-1)).toEqual({ cols: 120, rows: 40 }) // back to the primary's size
    expect(spawned[0].killed).toBe(false) // …and the pty stays alive for the canvas node
  })

  it('killing the PRIMARY (no viewerId) leaves the modal view holding the session alive', async () => {
    const m = await manager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('x')
    const { sessionId } = await createV(ALICE, undefined)
    await createV(ALICE, 'modal')

    killV(ALICE, sessionId) // the canvas node unmounts (PRIMARY) — but the modal is still open
    expect(spawned[0].killed).toBe(false) // the modal keeps the session alive: NO releasePty

    write(ALICE, sessionId, 'x') // the client is still a subscriber (via the modal), so it may steer
    expect(spawned[0].writes).toEqual(['x'])

    killV(ALICE, sessionId, 'modal') // the last view closes
    expect(spawned[0].killed).toBe(true) // …only now is the pty released
  })

  // ── The Server Edition's per-CONNECTION socket pause outlives a single view's departure ──────
  // A browser's WS send-buffer backpressure (`setFlow(uiId, …, 'socket')`) is owned by the whole
  // CONNECTION, not by one xterm — it rides the PRIMARY view by convention (the socket forwards no
  // viewerId). So when the canvas node (PRIMARY) unmounts while the kanban modal is still open on the
  // SAME connection, that one shared socket may still be jammed: a `kill` that returned EVERY owner's
  // ticket for the departing view — as a full departure does — would hand back the socket's pause too
  // and permanently un-pause a drowning connection, because the renderer's flow control is
  // edge-latched and will never re-pause (invariant (b) on `pausedBy`). The socket ticket must
  // survive until the client's LAST view leaves; only THIS view's own renderer pause is unreturnable.
  it("a PRIMARY-view kill keeps the client's per-connection SOCKET pause while a modal view stays", async () => {
    const m = await manager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('x')
    const { sessionId } = await createV(ALICE, undefined) // the canvas node (PRIMARY)
    await createV(ALICE, 'modal') // the kanban card modal, SAME connection

    m.setFlow(ALICE, sessionId, false, 'socket') // ALICE's WS socket is backed up (per-connection)
    expect(spawned[0].paused).toBe(true)

    killV(ALICE, sessionId) // the canvas node unmounts (PRIMARY) — the modal stays open
    expect(spawned[0].paused).toBe(true) // the connection is still jammed; the pty must STAY paused
    expect(spawned[0].killed).toBe(false) // …and the modal keeps it alive

    m.setFlow(ALICE, sessionId, true, 'socket') // the socket finally drains into the browser
    expect(spawned[0].paused).toBe(false) // only now does the pty resume

    killV(ALICE, sessionId, 'modal') // the last view closes → the pty is released
    expect(spawned[0].killed).toBe(true)
  })

  // Belt-and-braces: if the socket is STILL jammed when the client's last view leaves, the departure
  // sweep must return the socket ticket (which rides the PRIMARY view, not the departing modal's
  // key), or a released pty would be left holding an un-returnable pause on a session that is gone.
  it("the client's last view leaving sweeps a still-held socket pause (no leaked ticket)", async () => {
    const m = await manager()
    vi.spyOn(m, 'captureForResync').mockResolvedValue('x')
    const { sessionId } = await createV(ALICE, undefined)
    await createV(ALICE, 'modal')
    await createV(BOB, undefined) // a second CONNECTION keeps the pty alive after ALICE fully leaves

    m.setFlow(ALICE, sessionId, false, 'socket')
    killV(ALICE, sessionId) // PRIMARY view goes; ALICE's socket pause stays (modal still open)
    expect(spawned[0].paused).toBe(true)

    killV(ALICE, sessionId, 'modal') // ALICE's LAST view leaves without ever resuming the socket
    expect(spawned[0].paused).toBe(false) // the departure sweep returns the leftover socket ticket
    expect(spawned[0].killed).toBe(false) // BOB still watches, so the pty is not released
  })
})