Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

109 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { ENGINES } from '../engines/types.js'
import type { RegisteredSession } from './registry.js'
import { TerminalStreamManager, clientDescriptorFrom, terminalEngineCapabilities, UPLOAD_CHUNK_BYTES } from './terminalStreamManager.js'
import {
  TERMINAL_ACTION_SUCCEEDED,
  terminalActionPossiblyExecuted,
  type TerminalActionResult,
  type TerminalStreamHandle,
  type TerminalStreamSink,
} from './terminalTypes.js'
import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'
import { TerminalBinaryKind, TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES, type TerminalBinaryClear } from './terminalBinary.js'
import { writeImageToOsClipboard, type OsClipboardImageResult } from './osClipboard.js'
import { writePasteDropFile, writePasteImageFile } from './pasteDropFiles.js'
import { MoveGate } from './hostMove/gate.js'

vi.mock('./osClipboard.js', () => ({ writeImageToOsClipboard: vi.fn() }))
vi.mock('./pasteDropFiles.js', () => ({ writePasteImageFile: vi.fn(), writePasteDropFile: vi.fn() }))

class FakeStream implements TerminalStreamHandle {
  readonly runtime = { backend: 'tmux' as const, paneId: '%1' }
  writes: Uint8Array[] = []
  pastes: string[] = []
  sizes: Array<{ cols: number; rows: number }> = []
  scrolls: Array<{ direction: 'up' | 'down'; lines: number }> = []
  closed = false
  snapshots = 0
  snapshotBytes = Buffer.from('\u001bcfixture')
  onSnapshot: ((count: number) => void) | null = null
  pauses = 0
  resumes = 0
  snapshotBegins = 0
  snapshotEnds = 0
  snapshotOptions: Array<{ tuiOwnsScrollback?: boolean } | undefined> = []
  onEndSnapshot: (() => void) | null = null

  beginSnapshot() { this.snapshotBegins++ }
  async snapshot(options?: { tuiOwnsScrollback?: boolean }): Promise<{ state: 'succeeded'; value: { bytes: Uint8Array; cols: number; rows: number } }> {
    this.snapshots++
    this.snapshotOptions.push(options)
    this.onSnapshot?.(this.snapshots)
    return { state: 'succeeded', value: { bytes: this.snapshotBytes, cols: 120, rows: 40 } }
  }
  endSnapshot() { this.snapshotEnds++; this.onEndSnapshot?.() }
  /** When set, every writeRaw parks on it instead of answering at once — a tmux that is slow to `%end`. */
  pendingWrites: Array<(result: TerminalActionResult) => void> = []
  holdWrites = false
  /** Every write and paste, in the order they reached the pane. */
  order: string[] = []
  async writeRaw(bytes: Uint8Array): Promise<TerminalActionResult> {
    this.writes.push(bytes)
    this.order.push(`raw:${Buffer.from(bytes).toString()}`)
    if (!this.holdWrites) return TERMINAL_ACTION_SUCCEEDED
    return new Promise((resolve) => { this.pendingWrites.push(resolve) })
  }
  /** When set, a paste waits on it, with the check the manager asked to be made as it lands. */
  pasteLands: ((allowed: (() => boolean) | undefined) => Promise<TerminalActionResult>) | null = null
  async pasteRaw(text: string, allowed?: () => boolean) {
    this.pastes.push(text)
    this.order.push(`paste:${text}`)
    return this.pasteLands ? this.pasteLands(allowed) : TERMINAL_ACTION_SUCCEEDED
  }
  async resize(size: { cols: number; rows: number }) { this.sizes.push(size); return TERMINAL_ACTION_SUCCEEDED }
  async scroll(direction: 'up' | 'down', lines: number) { this.scrolls.push({ direction, lines }); return TERMINAL_ACTION_SUCCEEDED }
  async pauseOutput() { this.pauses++; return TERMINAL_ACTION_SUCCEEDED }
  async resumeOutput() { this.resumes++; return TERMINAL_ACTION_SUCCEEDED }
  async close(): Promise<void> { this.closed = true }
}

function session(engine: string = 'codex', agentId = 'agent-1'): RegisteredSession {
  return {
    agentId, sessionId: `session-${agentId}`, engine, active: true,
    registeredAt: Date.now(), touchedAt: Date.now(), runtimes: [{ backend: 'tmux', paneId: '%1' }],
    primaryRuntimeKey: 'tmux:default:%1',
  } as unknown as RegisteredSession
}

describe('TerminalStreamManager', () => {
  let sink: TerminalStreamSink | null
  let stream: FakeStream
  let sent: Array<{ connId: string; type: string; payload: Record<string, unknown> }>
  let binarySent: Array<{ connId: string; frame: TerminalBinaryClear }>
  let manager: TerminalStreamManager
  let agents: Map<string, RegisteredSession>
  let outputBeforeOpen: Uint8Array | null
  let terminals: TerminalBackendCoordinator

  const newManager = (extra: Partial<ConstructorParameters<typeof TerminalStreamManager>[0]> = {}): TerminalStreamManager =>
    new TerminalStreamManager({
      terminals,
      resolveAgent: (id) => agents.get(id),
      sendTarget: (connId, type, payload) => { sent.push({ connId, type, payload }); return true },
      sendBinaryTarget: (connId, frame) => { binarySent.push({ connId, frame }); return true },
      streamingAvailable: true,
      now: () => Date.now(),
      ...extra,
    })

  beforeEach(() => {
    vi.useFakeTimers()
    sink = null
    stream = new FakeStream()
    sent = []
    binarySent = []
    outputBeforeOpen = null
    agents = new Map([['agent-1', session()]])
    terminals = {
      openStream: async (_session: RegisteredSession, _size: unknown, nextSink: TerminalStreamSink) => {
        sink = nextSink
        if (outputBeforeOpen) nextSink.onData(outputBeforeOpen)
        return { state: 'succeeded' as const, value: stream }
      },
    } as unknown as TerminalBackendCoordinator
    manager = newManager()
    vi.mocked(writePasteImageFile).mockReset().mockResolvedValue('/fake/paste-images/fake.png')
    vi.mocked(writePasteDropFile).mockReset().mockImplementation(async (filename: string) => `/fake/paste-drops/id-${filename}`)
    vi.mocked(writeImageToOsClipboard).mockReset().mockResolvedValue({ state: 'written' })
  })

  afterEach(async () => {
    await manager.stop()
    vi.useRealTimers()
  })

  it('publishes the complete engine catalog without a client whitelist', async () => {
    await manager.handleFrame('web-1', 'terminal_capabilities', { requestId: 'r1' })
    const result = sent.at(-1)!
    expect(result.type).toBe('terminal_capabilities_result')
    expect((result.payload.engines as Array<{ id: string }>).map((row) => row.id)).toEqual([...ENGINES])
  })

  it('asks no window for the tab its input came from, and still writes input from an older one that names it', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'scoped', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    const ready = sent.findLast(f => f.type === 'terminal_ready')!.payload
    expect(ready).not.toHaveProperty('swarmInput')
    const frame = { kind: TerminalBinaryKind.input, streamId: String(ready.streamId), seq: 0,
      bytes: Buffer.from('hello\r'), compressed: false, tabId: 'swarm-a' }
    await manager.handleBinary('web-1', frame)
    expect(stream.writes).toEqual([frame.bytes])
  })

  it('streams an agent on the PTY host as one on tmux', async () => {
    agents.set('agent-pty', {
      ...session('codex', 'agent-pty'),
      runtimes: [{ backend: 'ptyhost', instance: 'p1', paneId: '%3' }],
      primaryRuntimeKey: 'ptyhost:p1:%3',
    } as unknown as RegisteredSession)
    agents.set('agent-none', { ...session('codex', 'agent-none'), runtimes: [], primaryRuntimeKey: '' } as unknown as RegisteredSession)
    await manager.handleFrame('web-1', 'terminal_open', { requestId: 'pty', protocolVersion: 3, agentId: 'agent-pty', cols: 100, rows: 30 })
    expect(sent.findLast(f => f.payload.requestId === 'pty')?.type).toBe('terminal_ready')
    await manager.handleFrame('web-1', 'terminal_open', { requestId: 'none', protocolVersion: 3, agentId: 'agent-none', cols: 100, rows: 30 })
    expect(sent.findLast(f => f.payload.requestId === 'none')).toMatchObject({ type: 'terminal_error', payload: { code: 'TERMINAL_RUNTIME_UNAVAILABLE' } })
  })

  it('uses the same generic path for every current engine', async () => {
    for (const [index, engine] of ENGINES.entries()) {
      const agentId = `agent-generic-${index}`
      agents.set(agentId, session(engine, agentId))
      await manager.handleFrame('web-1', 'terminal_open', {
        requestId: `open-${index}`, protocolVersion: 3, agentId, cols: 100, rows: 30,
      })
      const ready = sent.findLast((frame) => frame.type === 'terminal_ready')
      expect(ready?.payload.agentId).toBe(agentId)
      expect(ready?.payload.engineId).toBe(engine)
    }
  })

  it('automatically publishes a future engine once the source catalog contains it', () => {
    const futureCatalog = [...ENGINES, 'future-engine-added-later']
    expect(terminalEngineCapabilities(true, futureCatalog).map((row) => row.id)).toEqual(futureCatalog)
  })

  it('fails closed for an engine that is not in the current source catalog', async () => {
    const unsafe = session('claude') as unknown as { engine: string }
    unsafe.engine = 'hostile-unregistered-engine'
    agents.set('agent-1', unsafe as unknown as RegisteredSession)
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'unsupported', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    expect(sent.at(-1)?.payload.code).toBe('TERMINAL_ENGINE_UNSUPPORTED')
  })

  it('rejects an unknown agent without opening a stream', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'missing', protocolVersion: 3, agentId: 'does-not-exist', cols: 100, rows: 30,
    })
    expect(sent.at(-1)?.payload.code).toBe('TERMINAL_AGENT_NOT_FOUND')
  })

  // Codex prints its transcript again after a resize, its clear first; at work it began after the keyframe had been
  // taken, and a phone drew the cleared screen (2026-10-13). Its clear never goes out as output.
  it('stands a keyframe in for an engine\'s print that begins as live output after a resize', async () => {
    const repaint = { clears: '\u001b[3J', ends: '\u001b[?2026l', withinMs: 250 }
    const output = () => binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.output)
      .map(({ frame }) => Buffer.from(frame.bytes).toString('latin1')).join('')
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
    })
    const streamId = sent[0].payload.streamId as string
    await manager.handleFrame('web-1', 'terminal_resize', { streamId, resizeSeq: 0, cols: 120, rows: 30 })
    const taken = stream.snapshots

    // Begun in one chunk and ended in another: the keyframe waits for the end.
    sink!.onData(Buffer.from('\u001b[?2026l\u001b[H\u001b[2J\u001b[3J\u001b[H\u001b[?2026h'))
    await vi.advanceTimersByTimeAsync(8)
    expect(stream.snapshots).toBe(taken + 1)
    expect(stream.snapshotOptions.at(-1)).toEqual({ conversationHistory: true, repaint: { ...repaint, cleared: true } })
    expect(output()).not.toContain('\u001b[3J')

    // Begun and ended in one chunk: the keyframe is taken at once.
    await manager.handleFrame('web-1', 'terminal_resize', { streamId, resizeSeq: 1, cols: 120, rows: 40 })
    sink!.onData(Buffer.from('\u001b[2J\u001b[3J\u001b[?2026htranscript\u001b[?2026l'))
    await vi.advanceTimersByTimeAsync(8)
    expect(stream.snapshotOptions.at(-1)).toEqual({ conversationHistory: true })
    expect(output()).not.toContain('\u001b[3J')

    // Long after a resize a clear is the engine's own business, and goes out like any output.
    await vi.advanceTimersByTimeAsync(2_000)
    const before = stream.snapshots
    sink!.onData(Buffer.from('\u001b[3J'))
    await vi.advanceTimersByTimeAsync(8)
    expect(stream.snapshots).toBe(before)
    expect(output()).toContain('\u001b[3J')
  })

  // The keyframe after a resize was taken before Codex's print began, and the clear came in the output held behind it.
  // Released while the keyframe was still marked as being taken, it went to the viewer unread (review of #1310).
  it('reads the output a keyframe held back for an engine\'s print, as it reads live output', async () => {
    const repaint = { clears: '\u001b[3J', ends: '\u001b[?2026l', withinMs: 250 }
    const output = () => binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.output)
      .map(({ frame }) => Buffer.from(frame.bytes).toString('latin1')).join('')
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
    })
    const streamId = sent[0].payload.streamId as string
    stream.onEndSnapshot = () => {
      stream.onEndSnapshot = null
      sink!.onData(Buffer.from('\u001b[?2026hworking\u001b[?2026l'))
      sink!.onData(Buffer.from('\u001b[H\u001b[2J\u001b[3J\u001b[H\u001b[?2026h'))
    }
    const taken = stream.snapshots
    await manager.handleFrame('web-1', 'terminal_resize', { streamId, resizeSeq: 0, cols: 120, rows: 30 })
    await vi.advanceTimersByTimeAsync(8)

    // The resize's keyframe, then the print's, which waits for its end.
    expect(stream.snapshots).toBe(taken + 2)
    expect(stream.snapshotOptions.at(-1)).toEqual({ conversationHistory: true, repaint: { ...repaint, cleared: true } })
    expect(stream.snapshotBegins).toBe(stream.snapshotEnds)
    expect(output()).not.toContain('\u001b[3J')
    expect(binarySent.at(-1)!.frame.kind).toBe(TerminalBinaryKind.keyframe)
  })

  it('tells a Grok snapshot not to seed tmux history, an engine kept in the scrollback to seed all of it, and leaves other engines alone', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-codex', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
    })
    // Codex prints its transcript again on a resize, which a keyframe after one waits for.
    expect(stream.snapshotOptions.at(-1)).toEqual({
      conversationHistory: true, repaint: { clears: '\u001b[3J', ends: '\u001b[?2026l', withinMs: 250 },
    })

    agents.set('claude-1', session('claude', 'claude-1'))
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-claude', protocolVersion: 3, agentId: 'claude-1', cols: 120, rows: 40,
    })
    // Claude Code runs as the person set it up: its history is sent as any pane's.
    expect(stream.snapshotOptions.at(-1)).toBeUndefined()

    agents.set('opencode-1', session('opencode', 'opencode-1'))
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-opencode', protocolVersion: 3, agentId: 'opencode-1', cols: 120, rows: 40,
    })
    expect(stream.snapshotOptions.at(-1)).toBeUndefined()

    agents.set('grok-1', session('grok', 'grok-1'))
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-grok', protocolVersion: 3, agentId: 'grok-1', cols: 120, rows: 40,
    })
    expect(stream.snapshotOptions.at(-1)).toEqual({ tuiOwnsScrollback: true })
  })

  it('tells the daemon an agent took input from its controller — never from a watcher, never for input it refused', async () => {
    // The keystroke prewarm (grid-reads-without-waking issue 03) hangs off this: typing into a pane whose
    // agent runs on a sleeping grid starts that grid. A read-only watcher's input reaches no pty, so it
    // must start nothing either.
    const typed: string[] = []
    const person: boolean[] = []
    const from: Array<{ connId: string, kind: string | null }> = []
    await manager.stop()
    manager = newManager({ onInput: (agentId, byPerson, source) => { typed.push(agentId); person.push(byPerson); from.push(source) } })
    await manager.handleFrame('web-1', 'terminal_open', { requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40 })
    const controller = sent.find((frame) => frame.type === 'terminal_ready' && frame.connId === 'web-1')!.payload.streamId as string
    await manager.handleFrame('web-2', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40, takeover: false,
    })
    const watcher = sent.find((frame) => frame.type === 'terminal_ready' && frame.connId === 'web-2')!
    expect(watcher.payload.readOnly).toBe(true)

    await manager.handleBinary('web-2', {
      kind: TerminalBinaryKind.input, streamId: watcher.payload.streamId as string, seq: 0, compressed: false, bytes: Buffer.from('x'),
    })
    await manager.handleBinary('web-1', {
      kind: TerminalBinaryKind.input, streamId: controller, seq: 5, compressed: false, bytes: Buffer.from('out of order'),
    })
    expect(typed).toEqual([])

    await manager.handleBinary('web-1', { kind: TerminalBinaryKind.input, streamId: controller, seq: 0, compressed: false, bytes: Buffer.from('x') })
    await manager.handleBinary('web-1', { kind: TerminalBinaryKind.paste, streamId: controller, seq: 0, compressed: false, bytes: Buffer.from('hello') })
    // What the window's terminal answers by itself (focus, its attributes) is input too, but not the person's: every
    // harness another agent starts opens as a pane beside its starter, and its reports made each one the person's.
    await manager.handleBinary('web-1', { kind: TerminalBinaryKind.input, streamId: controller, seq: 1, compressed: false, bytes: Buffer.from('\x1b[I\x1b[?1;2c') })
    expect(typed).toEqual(['agent-1', 'agent-1', 'agent-1'])
    expect(person).toEqual([true, true, false])
    // Who typed: the controller's connection (core/terminals/browser.ts sends a page to the phone typing).
    expect(from[0]?.connId).toBe('web-1')
  })

  it('opens with a keyframe, streams coalesced output, and writes ordered raw input', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib'],
    })
    expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready'])
    expect(binarySent.map(({ frame }) => frame.kind)).toEqual([TerminalBinaryKind.keyframe])
    const streamId = sent[0].payload.streamId as string

    sink!.onData(Buffer.from('hello'))
    await vi.advanceTimersByTimeAsync(8)
    expect(binarySent.at(-1)?.frame.kind).toBe(TerminalBinaryKind.output)
    expect(binarySent.at(-1)?.frame.seq).toBe(1)

    await manager.handleBinary('web-1', {
      kind: TerminalBinaryKind.input, streamId, seq: 0, compressed: false, bytes: Buffer.from('abc'),
    })
    expect(Buffer.from(stream.writes[0]).toString()).toBe('abc')
    // Ahead of seq 1, which may still be on its way over the slower wire: it waits for it, and nothing is said.
    await manager.handleBinary('web-1', {
      kind: TerminalBinaryKind.input, streamId, seq: 2, compressed: false, bytes: Buffer.from('out-of-order'),
    })
    expect(stream.writes).toHaveLength(1)
    expect(sent.map((frame) => frame.payload.code)).not.toContain('TERMINAL_INPUT_INVALID')

    // An oversized frame is refused at once, with the counter untouched: the next accepted seq is still 1. The client
    // numbers its next keys from there, so the one waiting under its old numbering goes: released after them, it
    // would land after keys typed later than it.
    await manager.handleBinary('web-1', {
      kind: TerminalBinaryKind.input, streamId, seq: 1, compressed: false, bytes: Buffer.alloc(64 * 1024 + 1, 0x61),
    })
    expect(stream.writes).toHaveLength(1)
    expect(sent.at(-1)?.payload).toMatchObject({ code: 'TERMINAL_INPUT_INVALID', reason: 'size', expectedSeq: 1 })

    // The realigned keys: seq 1, then 2, each written in turn.
    const mouse = Buffer.from('\u001b[<0;12;8M')
    await manager.handleBinary('web-1', {
      kind: TerminalBinaryKind.input, streamId, seq: 1, compressed: false, bytes: mouse,
    })
    await manager.handleBinary('web-1', {
      kind: TerminalBinaryKind.input, streamId, seq: 2, compressed: false, bytes: Buffer.from('typed after'),
    })
    expect(stream.writes.map((bytes) => Buffer.from(bytes).toString())).toEqual(['abc', mouse.toString(), 'typed after'])
    await vi.advanceTimersByTimeAsync(1_000)
    expect(sent.filter((frame) => frame.payload.code === 'TERMINAL_INPUT_INVALID')).toHaveLength(1)

    await manager.handleFrame('web-1', 'terminal_resize', {
      streamId, resizeSeq: 0, cols: 140, rows: 50,
    })
    expect(stream.sizes.at(-1)).toEqual({ cols: 140, rows: 50 })
  })

  it('carries an opaque native input context without letting it grant terminal control', async () => {
    const onInput = vi.fn(), inputContext = 'fixture-native-input-context'
    manager = newManager({ onInput })
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'context', protocolVersion: 3, agentId: 'agent-1', cols: 80, rows: 24, inputContext,
    })
    const streamId = sent.find(frame => frame.type === 'terminal_ready' && frame.connId === 'web-1')!.payload.streamId as string
    await manager.handleFrame('web-2', 'terminal_open', {
      requestId: 'watch-context', protocolVersion: 3, agentId: 'agent-1', cols: 80, rows: 24, watch: true, inputContext,
    })
    const watchId = sent.find(frame => frame.type === 'terminal_ready' && frame.connId === 'web-2')!.payload.streamId as string
    await manager.handleBinary('web-2', { kind: TerminalBinaryKind.input, streamId: watchId, seq: 0, compressed: false, bytes: Buffer.from('\r') })
    expect(onInput).not.toHaveBeenCalled()
    await manager.handleBinary('web-1', { kind: TerminalBinaryKind.input, streamId, seq: 0, compressed: false, bytes: Buffer.from('hello') })
    expect(onInput).toHaveBeenLastCalledWith('agent-1', true, { connId: 'web-1', kind: null, inputContext })
    await manager.handleBinary('web-1', { kind: TerminalBinaryKind.input, streamId, seq: 1, compressed: false, bytes: Buffer.from('\r') })
    expect(onInput).toHaveBeenLastCalledWith('agent-1', true, { connId: 'web-1', kind: null, inputContext, submitted: true })
    await manager.handleFrame('web-3', 'terminal_open', {
      requestId: 'invalid-context', protocolVersion: 3, agentId: 'agent-1', cols: 80, rows: 24, inputContext: { userId: 'do-not-trust' },
    })
    const other = sent.find(frame => frame.type === 'terminal_ready' && frame.connId === 'web-3')!.payload.streamId as string
    await manager.handleBinary('web-3', { kind: TerminalBinaryKind.input, streamId: other, seq: 0, compressed: false, bytes: Buffer.from('hello') })
    expect(onInput).toHaveBeenLastCalledWith('agent-1', true, { connId: 'web-3', kind: null })
  })

  it.each([[1, 1], [30, 30], [80, 8], [300, 120]])(
    'opens and resizes a terminal at its actual %i×%i pane size', async (cols, rows) => {
      const open = vi.spyOn(terminals, 'openStream')
      await manager.handleFrame('web-1', 'terminal_open', {
        requestId: 'small', protocolVersion: 3, agentId: 'agent-1', cols, rows,
      })
      expect(sent[0].type).toBe('terminal_ready')
      expect(open.mock.calls[0][1]).toEqual({ cols, rows })
      const streamId = sent[0].payload.streamId
      await manager.handleFrame('web-1', 'terminal_resize', {
        streamId, resizeSeq: 0, cols: 120, rows: 40,
      })
      await manager.handleFrame('web-1', 'terminal_resize', {
        streamId, resizeSeq: 1, cols, rows,
      })
      expect(stream.sizes).toEqual([{ cols: 120, rows: 40 }, { cols, rows }])
    },
  )

  it.each([[0, 20], [80, 0], [-1, 20], [80, -1], [1.5, 20], [80, 1.5], [301, 20], [80, 121]])(
    'rejects invalid %i×%i dimensions on open and resize', async (cols, rows) => {
      await manager.handleFrame('web-1', 'terminal_open', {
        requestId: 'invalid', protocolVersion: 3, agentId: 'agent-1', cols, rows,
      })
      expect(sent.at(-1)?.payload.code).toBe('TERMINAL_OPEN_INVALID')
      await manager.handleFrame('web-1', 'terminal_open', {
        requestId: 'valid', protocolVersion: 3, agentId: 'agent-1', cols: 80, rows: 24,
      })
      const streamId = sent.at(-1)!.payload.streamId
      await manager.handleFrame('web-1', 'terminal_resize', { streamId, resizeSeq: 0, cols, rows })
      expect(stream.sizes).toEqual([])
      // A bad size must not consume the sequence number or prevent a later valid resize.
      await manager.handleFrame('web-1', 'terminal_resize', { streamId, resizeSeq: 0, cols: 80, rows: 24 })
      expect(stream.sizes).toEqual([{ cols: 80, rows: 24 }])
    },
  )

  it('routes terminal_scroll to the stream handle, and rejects a malformed one', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-scroll', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
    })
    const streamId = sent[0].payload.streamId as string

    await manager.handleFrame('web-1', 'terminal_scroll', { streamId, direction: 'up', lines: 3 })
    expect(stream.scrolls.at(-1)).toEqual({ direction: 'up', lines: 3 })

    await manager.handleFrame('web-1', 'terminal_scroll', { streamId, direction: 'sideways', lines: 3 })
    expect(stream.scrolls).toHaveLength(1)
    expect(sent.at(-1)?.payload.code).toBe('TERMINAL_SCROLL_INVALID')

    await manager.handleFrame('web-1', 'terminal_scroll', { streamId, direction: 'down', lines: 0 })
    expect(stream.scrolls).toHaveLength(1)
    expect(sent.at(-1)?.payload.code).toBe('TERMINAL_SCROLL_INVALID')
  })

  it('pipelines keystrokes to tmux instead of waiting for each %end, and still reports a late failure', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-pipeline', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
    })
    const streamId = sent[0].payload.streamId as string
    stream.holdWrites = true

    const input = (seq: number, text: string): TerminalBinaryClear => ({
      kind: TerminalBinaryKind.input, streamId, seq, compressed: false, bytes: Buffer.from(text),
    })
    // Neither handleBinary resolves against tmux's reply: the second keystroke reaches the control
    // client while the first is still unanswered. Before, the local socket's dispatch chain sat on
    // that reply for every character typed.
    await manager.handleBinary('web-1', input(0, 'a'))
    await manager.handleBinary('web-1', input(1, 'b'))
    expect(stream.writes.map((bytes) => Buffer.from(bytes).toString())).toEqual(['a', 'b'])
    expect(stream.pendingWrites).toHaveLength(2)
    expect(sent.filter((frame) => frame.type === 'terminal_error')).toHaveLength(0)

    // A reply that arrives after the fact still carries its consequence: an uncertain write gets a
    // keyframe so the client can see what tmux actually did.
    const keyframesBefore = binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.keyframe).length
    stream.pendingWrites[0](TERMINAL_ACTION_SUCCEEDED)
    stream.pendingWrites[1](terminalActionPossiblyExecuted('tmux raw input stopped after a partial write'))
    await vi.advanceTimersByTimeAsync(50)
    const errors = sent.filter((frame) => frame.type === 'terminal_error')
    expect(errors).toHaveLength(1)
    expect(errors[0].payload).toMatchObject({ code: 'TERMINAL_INPUT_FAILED', streamId })
    expect(binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toHaveLength(keyframesBefore + 1)
  })

  it('never compresses output for a loopback client, whatever it asked for', async () => {
    const big = Buffer.alloc(8 * 1024, 0x61)   // well over the 1 KiB floor, and trivially compressible

    await manager.stop()
    manager = newManager({ isLoopback: (connId) => connId.startsWith('local:') })
    await manager.handleFrame('local:desktop', 'terminal_open', {
      requestId: 'open-local', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib', 'none'],
    })
    sink!.onData(big)
    await vi.advanceTimersByTimeAsync(8)
    const local = binarySent.at(-1)!.frame
    expect(local.kind).toBe(TerminalBinaryKind.output)
    expect(local.compressed).toBe(false)
    expect(local.bytes).toHaveLength(big.length)

    // The same request from anything that is NOT loopback keeps zlib: those frames cross the
    // internet through the relay, where it still pays.
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-web', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40, compression: ['zlib', 'none'],
    })
    sink!.onData(big)
    await vi.advanceTimersByTimeAsync(8)
    const remote = binarySent.at(-1)!.frame
    expect(remote.kind).toBe(TerminalBinaryKind.output)
    expect(remote.compressed).toBe(true)
    expect(remote.bytes.length).toBeLessThan(big.length)
  })

  describe('keystrokes that come ahead of a missing one', () => {
    // A client moving a stream from the relay onto its P2P channel sends key N over the relay and N+1 over the
    // faster channel: N+1 came first, was refused, and the client's realignment lost two keys (2026-10-15).
    const open = async () => {
      await manager.handleFrame('web-1', 'terminal_open', { requestId: 'open-order', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40 })
      const streamId = sent[0].payload.streamId as string
      const key = (seq: number, text: string | Buffer = `k${seq}`) => manager.handleBinary('web-1', {
        kind: TerminalBinaryKind.input, streamId, seq, compressed: false, bytes: typeof text === 'string' ? Buffer.from(text) : text,
      })
      const written = () => stream.writes.map((bytes) => Buffer.from(bytes).toString())
      const refusals = () => sent.filter((frame) => frame.payload.code === 'TERMINAL_INPUT_INVALID').map((frame) => frame.payload)
      return { streamId, key, written, refusals }
    }

    it('are written, in their order, as soon as the missing one arrives', async () => {
      const { key, written, refusals } = await open()
      await key(1)
      await key(2)
      expect(written()).toEqual([])
      await key(0)
      expect(written()).toEqual(['k0', 'k1', 'k2'])
      await vi.advanceTimersByTimeAsync(1_000)
      expect(refusals()).toEqual([])
    })

    it('go when the missing one does not come in time, and the client is told once what is expected', async () => {
      const { streamId, key, written, refusals } = await open()
      await key(0)
      await key(2)
      await key(3)
      await vi.advanceTimersByTimeAsync(399)
      expect(refusals()).toEqual([])
      await vi.advanceTimersByTimeAsync(1)
      expect(written()).toEqual(['k0'])
      expect(refusals()).toEqual([expect.objectContaining({ streamId, reason: 'seq', expectedSeq: 1 })])
    })

    it('are refused at once after a wait was given up, until the expected one arrives', async () => {
      // The client realigns on the refusal and numbers its next keys from there: a frame it numbered under the
      // old count must not wait to land among them.
      const { key, written, refusals } = await open()
      await key(0)
      await key(2)
      await vi.advanceTimersByTimeAsync(400)
      await key(5)
      expect(refusals()).toHaveLength(2)
      expect(refusals()[1]).toMatchObject({ expectedSeq: 1 })
      await key(1, 'realigned')
      await key(3)
      expect(refusals()).toHaveLength(2)
      await key(2, 'next')
      expect(written()).toEqual(['k0', 'realigned', 'next', 'k3'])
    })

    it('give each gap a full wait of its own', async () => {
      const { key, written, refusals } = await open()
      await key(0)
      await key(2)
      await key(4)
      await vi.advanceTimersByTimeAsync(300)
      await key(1)
      expect(written()).toEqual(['k0', 'k1', 'k2'])
      await vi.advanceTimersByTimeAsync(399)
      expect(refusals()).toEqual([])
      await vi.advanceTimersByTimeAsync(1)
      expect(refusals()).toEqual([expect.objectContaining({ expectedSeq: 3 })])
      expect(written()).toEqual(['k0', 'k1', 'k2'])
    })

    it('are given up at once when more bytes wait than may be held', async () => {
      const { key, written, refusals } = await open()
      for (let seq = 1; seq <= 4; seq++) await key(seq, Buffer.alloc(64 * 1024, 0x61))
      expect(refusals()).toEqual([])
      await key(5, Buffer.alloc(1, 0x61))
      expect(refusals()).toEqual([expect.objectContaining({ expectedSeq: 0 })])
      await key(0)
      expect(written()).toEqual(['k0'])
    })

    it('are given up at once when more frames wait than may be held', async () => {
      const { key, written, refusals } = await open()
      for (let seq = 1; seq <= 64; seq++) await key(seq)
      expect(refusals()).toEqual([])
      await key(65)
      expect(refusals()).toEqual([expect.objectContaining({ expectedSeq: 0 })])
      await key(0)
      expect(written()).toEqual(['k0'])
    })

    it('go with any refusal, since the client numbers its next keys from what it is told', async () => {
      // A number already written comes while one waits: the refusal realigns the client, and the key held under
      // its old numbering would land among the new ones.
      const { key, written, refusals } = await open()
      await key(0)
      await key(2)
      await key(0, 'again')
      expect(refusals()).toEqual([expect.objectContaining({ expectedSeq: 1 })])
      await key(1, 'realigned')
      await key(2, 'next')
      expect(written()).toEqual(['k0', 'realigned', 'next'])
      await vi.advanceTimersByTimeAsync(1_000)
      expect(refusals()).toHaveLength(1)
    })

    it('keep the first of two frames under one number', async () => {
      const { key, written, refusals } = await open()
      await key(1, 'first')
      await key(1, 'second')
      await key(0)
      expect(written()).toEqual(['k0', 'first'])
      expect(refusals()).toEqual([])
    })

    it('are never written into a pane whose stream closed while they waited', async () => {
      const { streamId, key, written, refusals } = await open()
      await key(1)
      await manager.handleFrame('web-1', 'terminal_close', { streamId })
      await vi.advanceTimersByTimeAsync(1_000)
      expect(written()).toEqual([])
      expect(refusals()).toEqual([])
    })

    it('are traced, while tracing is on, by number and time and never by what was typed', async () => {
      const lines: string[] = []
      await manager.stop()
      manager = newManager({ typingTrace: (line) => lines.push(line) })
      const { streamId, key } = await open()
      const short = streamId.slice(0, 8)
      await key(1, 'secret-1')
      await vi.advanceTimersByTimeAsync(30)
      await key(0, 'secret-0')
      sink!.onData(Buffer.from('echo'))
      expect(lines).toEqual([
        `stream=${short} seq=1 held: 0 has not come (1 waiting)`,
        `stream=${short} seq=1..1 released after 30ms`,
        `stream=${short} seq=1 first output out +0ms after it was written`,
      ])
      // A keystroke whose next screen goes out as a keyframe is said so.
      await key(2, 'secret-2')
      await manager.handleFrame('web-1', 'terminal_resize', { streamId, resizeSeq: 0, cols: 100, rows: 30 })
      expect(lines.at(-1)).toBe(`stream=${short} seq=2 keyframe (resize) out +0ms after it was written`)
      expect(lines.join('\n')).not.toContain('secret')
    })

    it('are given up before a paste, which never goes ahead of keys typed before it', async () => {
      const { streamId, key, written, refusals } = await open()
      await key(1)
      await manager.handleBinary('web-1', { kind: TerminalBinaryKind.paste, streamId, seq: 0, compressed: false, bytes: Buffer.from('pasted') })
      expect(refusals()).toEqual([expect.objectContaining({ expectedSeq: 0 })])
      expect(stream.pastes).toEqual(['pasted'])
      await vi.advanceTimersByTimeAsync(1_000)
      expect(written()).toEqual([])
    })
  })

  it('keeps a paste out of a pane whose stream closed while the paste was on its way, and says nothing', async () => {
    // A stream's close no longer waits in line behind its paste (backendSocket.ts `enqueueTerminalBinary`):
    // the paste must ask again as it lands, or it lands in a pane its client has let go.
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-paste-close', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
    })
    const streamId = sent[0].payload.streamId as string
    let land!: () => void
    let askedAsItLanded: boolean | undefined
    stream.pasteLands = (allowed) => new Promise((resolve) => {
      land = () => {
        askedAsItLanded = allowed?.()
        resolve(askedAsItLanded ? TERMINAL_ACTION_SUCCEEDED : { state: 'failed', dispatch: 'not_started', reason: 'tmux paste-buffer could not be sent' })
      }
    })
    const pasting = manager.handleBinary('web-1', { kind: TerminalBinaryKind.paste, streamId, seq: 0, compressed: false, bytes: new TextEncoder().encode('rm -rf build') })
    await vi.waitFor(() => expect(stream.pastes).toEqual(['rm -rf build']))
    await manager.handleFrame('web-1', 'terminal_close', { streamId })
    const before = sent.length
    land()
    await pasting
    expect(askedAsItLanded).toBe(false)
    expect(sent.slice(before).map((frame) => frame.payload.code)).not.toContain('TERMINAL_PASTE_FAILED')
  })

  it('routes a binary paste kind to pasteRaw as one unit, never through writeRaw', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-paste', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
    })
    const streamId = sent[0].payload.streamId as string
    const paste = (text: string): TerminalBinaryClear => ({
      kind: TerminalBinaryKind.paste, streamId, seq: 0, compressed: false,
      bytes: new TextEncoder().encode(text),
    })

    // JSON is refused outright — a paste must ride the binary/AEAD channel, same reason terminal_input
    // does — so a stray legacy JSON paste never silently goes nowhere.
    await manager.handleFrame('web-1', 'terminal_paste', { streamId })
    expect(sent.at(-1)?.payload.code).toBe('TERMINAL_BINARY_REQUIRED')
    expect(stream.pastes).toHaveLength(0)

    const longPaste = Array.from({ length: 200 }, (_, i) => `line ${i}`).join('\n')
    await manager.handleBinary('web-1', paste(longPaste))
    expect(stream.pastes).toEqual([longPaste])
    expect(stream.writes).toHaveLength(0)

    // Forwarded verbatim, same as input() — no filtering of its own.
    await manager.handleBinary('web-1', paste('a\x03b'))
    expect(stream.pastes.at(-1)).toBe('a\x03b')

    await manager.handleBinary('web-1', paste(''))
    expect(stream.pastes).toHaveLength(2)

    // A real paste of ordinary code (tens/hundreds of KB) must not bounce off a limit sized for one
    // keystroke chunk — this is the exact regression that froze a real terminal over a normal paste.
    const ordinaryLargePaste = 'x'.repeat(200 * 1024)
    await manager.handleBinary('web-1', paste(ordinaryLargePaste))
    expect(stream.pastes.at(-1)).toBe(ordinaryLargePaste)
    expect(stream.pastes).toHaveLength(3)
  })

  describe('chunked image/file upload', () => {
    const pngBytes = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)
    const fileContent = Uint8Array.of(0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x34)

    async function openStream(requestId = 'open'): Promise<string> {
      await manager.handleFrame('web-1', 'terminal_open', {
        requestId, protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
      })
      return sent.findLast((f) => f.type === 'terminal_ready')!.payload.streamId as string
    }

    function begin(streamId: string, fields: Record<string, unknown>): Promise<boolean> {
      return manager.handleFrame('web-1', 'terminal_chunked_upload_begin', { streamId, ...fields })
    }

    function chunk(streamId: string, kind: TerminalBinaryKind.imagePaste | TerminalBinaryKind.pasteFile, seq: number, bytes: Uint8Array): Promise<void> {
      return manager.handleBinary('web-1', { kind, streamId, seq, compressed: false, bytes })
    }

    function lastResult(): { connId: string; type: string; payload: Record<string, unknown> } {
      return sent.at(-1)!
    }

    it('advertises imagePaste and pasteFile in terminal_capabilities', async () => {
      await manager.handleFrame('web-1', 'terminal_capabilities', { requestId: 'r1' })
      const features = sent.at(-1)?.payload.features as Record<string, unknown>
      expect(features.imagePaste).toBe(true)
      expect(features.pasteFile).toBe(true)
      expect(features.mediaPreview).toBe(true)
    })

    it('rejects legacy JSON terminal_paste_image/terminal_paste_file the same way as terminal_paste', async () => {
      const streamId = await openStream()
      await manager.handleFrame('web-1', 'terminal_paste_image', { streamId })
      expect(lastResult().payload.code).toBe('TERMINAL_BINARY_REQUIRED')
      await manager.handleFrame('web-1', 'terminal_paste_file', { streamId })
      expect(lastResult().payload.code).toBe('TERMINAL_BINARY_REQUIRED')
    })

    it('accepts a begin, reports progress per chunk, and finishes an image via the clipboard', async () => {
      const streamId = await openStream()
      await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length })
      expect(lastResult()).toMatchObject({ type: 'terminal_chunked_upload_begin_result', payload: { streamId, accepted: true } })

      await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes)

      const progress = sent.filter((f) => f.type === 'terminal_chunked_upload_progress')
      expect(progress).toHaveLength(1)
      expect(progress[0].payload).toMatchObject({ streamId, bytesWritten: pngBytes.length, totalBytes: pngBytes.length })

      expect(vi.mocked(writeImageToOsClipboard)).toHaveBeenCalledWith('/fake/paste-images/fake.png', pngBytes)
      expect(stream.writes).toHaveLength(1)
      expect(Buffer.from(stream.writes[0])).toEqual(Buffer.from([0x16])) // literal Ctrl+V
      const result = sent.findLast((f) => f.type === 'terminal_paste_image_result')!
      expect(result.payload).toMatchObject({ streamId, outcome: 'clipboard' })
    })

    // Real chunk boundaries, not arbitrary test-only slicing: every chunk but the last is exactly
    // UPLOAD_CHUNK_BYTES, matching how a real client actually splits an upload — the daemon's own
    // per-chunk validation rejects a seq beyond `ceil(totalBytes / UPLOAD_CHUNK_BYTES)`.
    const CHUNK = UPLOAD_CHUNK_BYTES

    it('assembles multiple chunks in order across several progress events', async () => {
      const streamId = await openStream()
      const big = new Uint8Array(CHUNK * 2 + 100).fill(0xab)
      await begin(streamId, { uploadKind: 'image', totalBytes: big.length })

      await chunk(streamId, TerminalBinaryKind.imagePaste, 0, big.subarray(0, CHUNK))
      await chunk(streamId, TerminalBinaryKind.imagePaste, 1, big.subarray(CHUNK, CHUNK * 2))
      await chunk(streamId, TerminalBinaryKind.imagePaste, 2, big.subarray(CHUNK * 2, big.length))

      const progress = sent.filter((f) => f.type === 'terminal_chunked_upload_progress')
      expect(progress.map((f) => f.payload.bytesWritten)).toEqual([CHUNK, CHUNK * 2, big.length])
      expect(vi.mocked(writeImageToOsClipboard)).toHaveBeenCalledWith('/fake/paste-images/fake.png', big)
    })

    it('tolerates chunks arriving out of order', async () => {
      const streamId = await openStream()
      const big = new Uint8Array(CHUNK * 2 + 50).fill(0xcd)
      await begin(streamId, { uploadKind: 'image', totalBytes: big.length })

      await chunk(streamId, TerminalBinaryKind.imagePaste, 1, big.subarray(CHUNK, CHUNK * 2))
      await chunk(streamId, TerminalBinaryKind.imagePaste, 0, big.subarray(0, CHUNK))
      await chunk(streamId, TerminalBinaryKind.imagePaste, 2, big.subarray(CHUNK * 2, big.length))

      expect(vi.mocked(writeImageToOsClipboard)).toHaveBeenCalledWith('/fake/paste-images/fake.png', big)
    })

    it('ignores a re-sent chunk (same seq) rather than double-counting its bytes', async () => {
      const streamId = await openStream()
      await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length * 2 })
      await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes)
      await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes) // duplicate

      const progress = sent.filter((f) => f.type === 'terminal_chunked_upload_progress')
      expect(progress.every((f) => f.payload.bytesWritten === pngBytes.length)).toBe(true)
      expect(vi.mocked(writeImageToOsClipboard)).not.toHaveBeenCalled() // still short of totalBytes
    })

    it('finishes a file upload by writing it under its original name and pasting the path — never the clipboard', async () => {
      const streamId = await openStream()
      await begin(streamId, { uploadKind: 'file', filename: 'report.pdf', totalBytes: fileContent.length })
      await chunk(streamId, TerminalBinaryKind.pasteFile, 0, fileContent)

      expect(vi.mocked(writePasteDropFile)).toHaveBeenCalledWith('report.pdf', fileContent)
      expect(vi.mocked(writeImageToOsClipboard)).not.toHaveBeenCalled()
      expect(stream.writes).toHaveLength(0) // no Ctrl+V replay for a file
      expect(stream.pastes).toEqual(['/fake/paste-drops/id-report.pdf'])
      const result = sent.findLast((f) => f.type === 'terminal_paste_file_result')!
      expect(result.payload).toMatchObject({ streamId, path: '/fake/paste-drops/id-report.pdf' })
    })

    it('rejects a begin with no filename for a file upload', async () => {
      const streamId = await openStream()
      await begin(streamId, { uploadKind: 'file', totalBytes: fileContent.length })
      expect(lastResult().payload).toMatchObject({ streamId, accepted: false })
    })

    it('rejects a begin over the per-kind size ceiling before any chunk is sent', async () => {
      const streamId = await openStream()
      await begin(streamId, { uploadKind: 'image', totalBytes: TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES + 1 })
      expect(lastResult().payload).toMatchObject({ streamId, accepted: false })
      expect(sent.some((f) => f.type === 'terminal_chunked_upload_progress')).toBe(false)
    })

    // Regression: previously a `begin` naming a streamId this connection has no live ActiveStream for
    // (e.g. after a reconnect/resync raced the client) was silently dropped — no reply at all — which
    // left the client's begin-accepted promise hanging until its own client-side timeout, indistinguishable
    // from a genuine hang. It must always answer, echoing the streamId the client named.
    it('replies accepted:false, echoing the streamId, when no live stream matches the begin', async () => {
      await manager.handleFrame('web-1', 'terminal_chunked_upload_begin', {
        streamId: 'stream-does-not-exist', uploadKind: 'image', totalBytes: pngBytes.length,
      })
      expect(lastResult()).toMatchObject({
        type: 'terminal_chunked_upload_begin_result',
        payload: { streamId: 'stream-does-not-exist', accepted: false, code: 'TERMINAL_STREAM_NOT_FOUND' },
      })
    })

    it('rejects a second begin while one upload is already in progress on the same pane', async () => {
      const streamId = await openStream()
      await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length })
      await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length })
      expect(lastResult().payload).toMatchObject({ streamId, accepted: false })
    })

    it('falls back to pasting the file path as text when no native clipboard is reachable', async () => {
      vi.mocked(writeImageToOsClipboard).mockResolvedValue(
        { state: 'unavailable', reason: 'no X11 or Wayland display on this machine' } satisfies OsClipboardImageResult,
      )
      const streamId = await openStream()
      await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length })
      await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes)

      expect(stream.writes).toHaveLength(0) // no Ctrl+V — nothing was put on a clipboard
      expect(stream.pastes).toEqual(['/fake/paste-images/fake.png'])
      const result = sent.findLast((f) => f.type === 'terminal_paste_image_result')!
      expect(result.payload).toMatchObject({
        streamId, outcome: 'fallback_path', reason: 'no X11 or Wayland display on this machine',
      })
    })

    // A clipboard tool that's ON PATH but can't actually reach a display (a stale $DISPLAY with no
    // X server behind it — exactly what a headless Docker rig hits) lands in 'failed', not
    // 'unavailable', even though the outcome is identical: no OS clipboard to write to. This used to
    // freeze the whole session; it must degrade to the same file-path fallback 'unavailable' gets.
    it('falls back to pasting the file path when the clipboard tool is present but unreachable', async () => {
      vi.mocked(writeImageToOsClipboard).mockResolvedValue(
        { state: 'failed', reason: 'xclip exited with code 1' } satisfies OsClipboardImageResult,
      )
      const streamId = await openStream()
      await begin(streamId, { uploadKind: 'image', totalBytes: pngBytes.length })
      await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes)

      expect(stream.writes).toHaveLength(0) // no Ctrl+V — nothing was put on a clipboard
      expect(stream.pastes).toEqual(['/fake/paste-images/fake.png'])
      expect(sent.some((f) => f.type === 'terminal_error')).toBe(false)
      const result = sent.findLast((f) => f.type === 'terminal_paste_image_result')!
      expect(result.payload).toMatchObject({
        streamId, outcome: 'fallback_path', reason: 'xclip exited with code 1',
      })
    })

    it('reports a genuine file write failure as an error', async () => {
      vi.mocked(writePasteDropFile).mockRejectedValue(new Error('disk full'))
      const streamId = await openStream()
      await begin(streamId, { uploadKind: 'file', filename: 'report.pdf', totalBytes: fileContent.length })
      await chunk(streamId, TerminalBinaryKind.pasteFile, 0, fileContent)

      expect(stream.pastes).toHaveLength(0)
      expect(sent.findLast((f) => f.type === 'terminal_error')?.payload).toMatchObject({
        code: 'TERMINAL_PASTE_FILE_FAILED', streamId, message: 'disk full',
      })
    })

    it('ignores a chunk with no matching begin', async () => {
      const streamId = await openStream()
      await chunk(streamId, TerminalBinaryKind.imagePaste, 0, pngBytes)
      expect(vi.mocked(writeImageToOsClipboard)).not.toHaveBeenCalled()
      expect(sent.some((f) => f.type === 'terminal_chunked_upload_progress')).toBe(false)
    })

    it('cancel discards the in-flight upload without writing or pasting anything', async () => {
      const streamId = await openStream()
      await begin(streamId, { uploadKind: 'file', filename: 'report.pdf', totalBytes: fileContent.length * 2 })
      await chunk(streamId, TerminalBinaryKind.pasteFile, 0, fileContent)
      await manager.handleFrame('web-1', 'terminal_chunked_upload_cancel', { streamId })
      // A late-arriving second chunk after cancel must not resurrect the upload.
      await chunk(streamId, TerminalBinaryKind.pasteFile, 1, fileContent)

      expect(vi.mocked(writePasteDropFile)).not.toHaveBeenCalled()
      expect(stream.pastes).toHaveLength(0)

      // And a fresh begin afterwards works normally — cancel actually cleared the slot.
      await begin(streamId, { uploadKind: 'file', filename: 'retry.pdf', totalBytes: fileContent.length })
      expect(lastResult().payload).toMatchObject({ streamId, accepted: true })
    })
  })

  it('does not replay pre-snapshot repaint bytes after the authoritative keyframe', async () => {
    outputBeforeOpen = Buffer.from('\u001b[2Jstale repaint')
    stream.snapshotBytes = Buffer.from('\u001bcnew prompt text')

    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-snapshot', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
    })
    await vi.advanceTimersByTimeAsync(20)

    expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready'])
    expect(binarySent.map(({ frame }) => frame.kind)).toEqual([TerminalBinaryKind.keyframe])
    expect(binarySent[0].frame.seq).toBe(0)
  })

  it('takes one ordered snapshot and releases its output gate after the keyframe', async () => {
    stream.snapshotBytes = Buffer.from('\u001bcnew prompt text')

    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-racing-snapshot', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
    })
    await vi.advanceTimersByTimeAsync(20)

    expect(stream.snapshots).toBe(1)
    expect(stream.snapshotBegins).toBe(1)
    expect(stream.snapshotEnds).toBe(1)
    expect(sent.map((frame) => frame.type)).toEqual(['terminal_ready'])
    expect(binarySent.map(({ frame }) => frame.kind)).toEqual([TerminalBinaryKind.keyframe])
    expect(binarySent[0].frame.seq).toBe(0)
  })

  it('takes over the first controller and expires the replacement lease after heartbeat timeout', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    const firstStream = stream
    const firstStreamId = sent.findLast((frame) => frame.type === 'terminal_ready')?.payload.streamId as string
    await manager.handleFrame('web-2', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    expect(firstStream.closed).toBe(true)
    expect(sent.some((frame) => frame.connId === 'web-1'
      && frame.type === 'terminal_closed'
      && frame.payload.code === 'TERMINAL_TAKEN_OVER')).toBe(true)
    expect(sent.findLast((frame) => frame.type === 'terminal_ready')?.connId).toBe('web-2')
    await manager.handleBinary('web-1', {
      kind: TerminalBinaryKind.input,
      streamId: firstStreamId,
      seq: 0,
      compressed: false,
      bytes: Buffer.from('stale input'),
    })
    expect(stream.writes).toHaveLength(0)

    await vi.advanceTimersByTimeAsync(30_000)
    expect(stream.closed).toBe(true)
    expect(sent.some((frame) => frame.connId === 'web-2'
      && frame.type === 'terminal_closed'
      && frame.payload.reason === 'heartbeat timeout')).toBe(true)
  })

  // A host that lost its backend link closes its remote streams without telling anyone; the client
  // only found out after 15 s of silence and three ignored resyncs, then gave up (2026-10-16). A
  // client that asks is now told at its next heartbeat.
  describe('a heartbeat or resync for a stream this connection does not hold', () => {
    const errors = () => sent.filter((frame) => frame.type === 'terminal_error')

    it('is answered with TERMINAL_STREAM_NOT_FOUND when the client asks', async () => {
      await manager.handleFrame('web-1', 'terminal_alive', { streamId: 'gone-1', reportMissing: true })
      await manager.handleFrame('web-1', 'terminal_resync', { streamId: 'gone-2', attempt: 1, reportMissing: true })
      expect(errors().map((frame) => [frame.connId, frame.payload.code, frame.payload.streamId])).toEqual([
        ['web-1', 'TERMINAL_STREAM_NOT_FOUND', 'gone-1'],
        ['web-1', 'TERMINAL_STREAM_NOT_FOUND', 'gone-2'],
      ])
    })

    it('stays silent for a client that does not ask, as every older client', async () => {
      await manager.handleFrame('web-1', 'terminal_alive', { streamId: 'gone-1' })
      await manager.handleFrame('web-1', 'terminal_resync', { streamId: 'gone-1', attempt: 1 })
      expect(errors()).toEqual([])
    })

    it('counts a stream held by another connection as missing for this one, and leaves it alone', async () => {
      await manager.handleFrame('web-1', 'terminal_open', {
        requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
      })
      const streamId = sent.findLast((frame) => frame.type === 'terminal_ready')?.payload.streamId as string
      await manager.handleFrame('web-2', 'terminal_alive', { streamId, reportMissing: true })
      expect(errors().at(-1)).toMatchObject({
        connId: 'web-2',
        payload: { code: 'TERMINAL_STREAM_NOT_FOUND', streamId },
      })
      expect(stream.closed).toBe(false)
    })
  })

  // Node's clock keeps running while a Mac sleeps, so a lid closed for forty minutes reached the next
  // sweep as forty minutes without `terminal_alive` and closed every stream at the wake — measured
  // 2026-09-28 as `[terminal-stream] closed` on every local terminal the moment the lid opened.
  it('carries a lease over the time the computer slept, and still expires it on awake silence', async () => {
    let asleepMs = 0
    await manager.stop()
    manager = newManager({ now: () => Date.now() + asleepMs })
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    await vi.advanceTimersByTimeAsync(20_000)
    asleepMs += 2_280_000 // the lid closes; no timer runs until it opens again
    await vi.advanceTimersByTimeAsync(5_000)
    expect(stream.closed).toBe(false)
    expect(sent.some((frame) => frame.type === 'terminal_closed')).toBe(false)

    // Awake and still silent: the lease runs out on awake time, as before.
    await vi.advanceTimersByTimeAsync(30_000)
    expect(stream.closed).toBe(true)
    expect(sent.some((frame) => frame.type === 'terminal_closed'
      && frame.payload.reason === 'heartbeat timeout')).toBe(true)
  })

  // A sweep read as a sleep carries each lease by `slept`, which `sleptFor` defines as the gap MINUS
  // one period — so every sweep still charges one EXPIRY_SWEEP_MS of silence however late it ran, and
  // a throttled machine cannot hold a dead client's lease open. Guards against "carry the whole gap",
  // which would never expire.
  it('still expires a lease when every sweep is late enough to read as a sleep', async () => {
    let asleepMs = 0
    await manager.stop()
    manager = newManager({ now: () => Date.now() + asleepMs })
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    // Twelve sweeps, each landing 15s late (gap 20s > 2 x 5s, so every one is read as a sleep) and no
    // `terminal_alive` in any of them. Six periods of charged silence is the 30s timeout.
    for (let i = 0; i < 12; i++) {
      asleepMs += 15_000
      await vi.advanceTimersByTimeAsync(5_000)
    }
    expect(stream.closed).toBe(true)
    expect(sent.some((frame) => frame.type === 'terminal_closed'
      && frame.payload.reason === 'heartbeat timeout')).toBe(true)
  })

  // The incumbent's banner says WHO took over, so the close it gets carries what the winner
  // declared on open — verbatim through a relay, since the daemon never learns a peer's name.
  it('names the taker on the close when the winner introduced itself', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    await manager.handleFrame('web-2', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
      client: { kind: 'desktop', name: '  Mac mini ', machineId: 'ab12ab12ab12ab12' },
    })
    const closed = sent.find((frame) => frame.connId === 'web-1' && frame.type === 'terminal_closed')
    expect(closed?.payload).toMatchObject({
      code: 'TERMINAL_TAKEN_OVER',
      takenBy: { kind: 'desktop', name: 'Mac mini', machineId: 'ab12ab12ab12ab12' },
    })
  })

  // The phone opens politely (`takeover: false`) and watches a terminal the desktop is driving. Its
  // banner says WHO has it — the desktop names a taker the same way — so the ready carries the
  // holder's own introduction, and nothing when the holder never gave one.
  it('names the holder on a watcher\'s ready', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
      client: { kind: 'desktop', name: 'MacBookPro2021.local', machineId: 'ab12ab12ab12ab12' },
    })
    await manager.handleFrame('phone-1', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30, takeover: false,
      client: { kind: 'phone', name: 'iPhone' },
    })
    const ready = sent.find((frame) => frame.connId === 'phone-1' && frame.type === 'terminal_ready')
    expect(ready?.payload).toMatchObject({
      readOnly: true,
      heldBy: { kind: 'desktop', name: 'MacBookPro2021.local', machineId: 'ab12ab12ab12ab12' },
    })
    // The holder keeps the terminal, and a controller's own ready never names anybody.
    expect(sent.some((frame) => frame.connId === 'web-1' && frame.type === 'terminal_closed')).toBe(false)
    expect(sent.find((frame) => frame.connId === 'web-1' && frame.type === 'terminal_ready')?.payload)
      .not.toHaveProperty('heldBy')
  })

  it('says nothing about a holder that never introduced itself', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    await manager.handleFrame('phone-1', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30, takeover: false,
    })
    const ready = sent.find((frame) => frame.connId === 'phone-1' && frame.type === 'terminal_ready')
    expect(ready?.payload.readOnly).toBe(true)
    expect(ready?.payload).not.toHaveProperty('heldBy')
  })

  // A phone set a Harness OS computer up and opened its OpenCode, taking it at the phone's size; the
  // computer's screen watched. When the phone left, nothing told the screen, and OpenCode stayed
  // phone-sized in a corner of the screen until someone typed there (2026-10-18).
  it('tells the watchers when the controller leaves, not when it hands over', async () => {
    await manager.handleFrame('screen-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 211, rows: 57,
    })
    await manager.handleFrame('phone-1', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 45, rows: 30,
    })
    await manager.handleFrame('screen-1', 'terminal_open', {
      requestId: 'open-3', protocolVersion: 3, agentId: 'agent-1', cols: 211, rows: 57, takeover: false,
    })
    const ready = (connId: string) => sent.findLast((frame) => frame.connId === connId && frame.type === 'terminal_ready')
    const watching = ready('screen-1')?.payload.streamId
    expect(ready('screen-1')?.payload.readOnly).toBe(true)
    const free = () => sent.filter((frame) => frame.type === 'terminal_free')
    expect(free()).toHaveLength(0)

    await manager.handleFrame('phone-1', 'terminal_close', { streamId: ready('phone-1')?.payload.streamId })
    expect(free().map((frame) => [frame.connId, frame.payload.streamId])).toEqual([['screen-1', watching]])

    // Taken by another view instead: that one has it, and nobody is told it is free.
    sent.length = 0
    await manager.handleFrame('phone-1', 'terminal_open', {
      requestId: 'open-4', protocolVersion: 3, agentId: 'agent-1', cols: 45, rows: 30,
    })
    await manager.handleFrame('tablet-1', 'terminal_open', {
      requestId: 'open-5', protocolVersion: 3, agentId: 'agent-1', cols: 90, rows: 40,
    })
    expect(free()).toHaveLength(0)
  })

  // hn with no terminal (its server, kept for the sessions a closed window left) reads every pane of the desk. On
  // 2026-10-14 it reopened first after each daemon restart, took the terminals at its 80x24 layout and left the
  // window the person was using watching a shrunken agent until they typed. It opens with `watch: true` now.
  // A Harness Team daemon running a Swarm Product Manager (#895, superTabs/inCore/teamApps.ts): the Mac owner's apps only
  // watch, and keystrokes arrive as binary frames that no request gate sees (security review 1 of #2089).
  describe('a connection held to watching', () => {
    let held: boolean
    beforeEach(() => {
      held = true
      manager = newManager({ watchOnly: (connId) => held && connId === 'owner-app' })
    })
    const ready = (connId: string) => sent.findLast((frame) => frame.connId === connId && frame.type === 'terminal_ready')!
    const type = (streamId: string, text: string) => manager.handleBinary('owner-app', { kind: TerminalBinaryKind.input, streamId, seq: 0,
      bytes: Buffer.from(text), compressed: false })

    it('opens as a watcher though it asks to take the terminal, and its keystrokes, pastes and resizes reach nothing', async () => {
      await manager.handleFrame('owner-app', 'terminal_open', { requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 80, rows: 24 })
      expect(ready('owner-app').payload.readOnly).toBe(true)
      const streamId = ready('owner-app').payload.streamId as string
      await type(streamId, 'cat ~/.claude/projects/*\r')
      await manager.handleBinary('owner-app', { kind: TerminalBinaryKind.paste, streamId, seq: 0, bytes: Buffer.from('ls'), compressed: false })
      await manager.handleFrame('owner-app', 'terminal_resize', { streamId, resizeSeq: 1, cols: 30, rows: 10 })
      expect(sent.at(-1)?.payload.code).toBe('VIEW_ONLY')
      expect([stream.writes, stream.sizes]).toEqual([[], []])
    })

    it('drops the input of a stream it opened before it was held, from then on', async () => {
      held = false
      await manager.handleFrame('owner-app', 'terminal_open', { requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 80, rows: 24 })
      expect(ready('owner-app').payload.readOnly).toBe(false)
      const streamId = ready('owner-app').payload.streamId as string
      await type(streamId, 'a')
      await vi.waitFor(() => expect(stream.writes).toHaveLength(1))
      held = true
      await type(streamId, 'b')
      await manager.handleFrame('owner-app', 'terminal_resize', { streamId, resizeSeq: 1, cols: 30, rows: 10 })
      expect(sent.at(-1)?.payload.code).toBe('VIEW_ONLY')
      expect(stream.writes).toHaveLength(1)
      expect(stream.sizes).toEqual([])
    })

    it('leaves every other connection as it was', async () => {
      await manager.handleFrame('desktop-1', 'terminal_open', { requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 80, rows: 24 })
      expect(ready('desktop-1').payload.readOnly).toBe(false)
    })
  })

  // Security review 2 of #2089: a session that turned confidential (a Swarm Product Manager, superTabs/inCore/teamApps.ts)
  // after the Mac owner's app opened it went on streaming people's chats to that app.
  describe('a stream on a session that turned confidential', () => {
    let closed: boolean
    beforeEach(() => {
      closed = false
      manager = newManager({ closedTo: (connId, agentId) => closed && connId === 'owner-app' && agentId === 'agent-1' })
    })
    const output = () => binarySent.filter(({ connId, frame }) => connId === 'owner-app' && frame.kind === TerminalBinaryKind.output)

    it('opened before, is closed and sent nothing more, its resync included', async () => {
      await manager.handleFrame('owner-app', 'terminal_open', { requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 80, rows: 24 })
      const streamId = sent.findLast(f => f.type === 'terminal_ready')!.payload.streamId as string
      sink!.onData(Buffer.from('before'))
      await vi.advanceTimersByTimeAsync(8)
      const before = output().length
      expect(before).toBeGreaterThan(0)
      closed = true
      sink!.onData(Buffer.from('Only for the PM: the launch slips a week.'))
      await vi.advanceTimersByTimeAsync(2_000)
      expect(output()).toHaveLength(before)
      expect(sent.find(f => f.connId === 'owner-app' && f.type === 'terminal_closed')?.payload).toMatchObject({ code: 'SWARM_CONFIDENTIAL', streamId })
      const sentBefore = binarySent.length
      await manager.handleFrame('owner-app', 'terminal_resync', { streamId })
      await vi.advanceTimersByTimeAsync(100)
      expect(binarySent).toHaveLength(sentBefore)
    })

    it('is not opened again', async () => {
      closed = true
      await manager.handleFrame('owner-app', 'terminal_open', { requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 80, rows: 24 })
      expect(sent.at(-1)).toMatchObject({ connId: 'owner-app', payload: expect.objectContaining({ code: 'SWARM_CONFIDENTIAL' }) })
      expect(sent.some(f => f.type === 'terminal_ready')).toBe(false)
    })
  })

  describe('a watch-only open', () => {
    let readOnlyOpens: boolean[]
    beforeEach(() => {
      readOnlyOpens = []
      terminals = {
        openStream: async (_session: RegisteredSession, _size: unknown, nextSink: TerminalStreamSink, readOnly?: boolean) => {
          sink = nextSink
          readOnlyOpens.push(readOnly === true)
          return { state: 'succeeded' as const, value: stream }
        },
      } as unknown as TerminalBackendCoordinator
      manager = newManager()
    })

    const ready = (connId: string) => sent.findLast((frame) => frame.connId === connId && frame.type === 'terminal_ready')!

    it('watches a terminal nobody holds: tmux attaches read-only, so the agent keeps its size, and nothing is typed', async () => {
      await manager.handleFrame('hn-headless', 'terminal_open', {
        requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 37, rows: 22, takeover: false, watch: true,
        client: { kind: 'tui', name: 'Mac Auto terminal' },
      })
      expect(ready('hn-headless').payload.readOnly).toBe(true)
      expect(ready('hn-headless').payload).not.toHaveProperty('heldBy')
      expect(readOnlyOpens).toEqual([true])
      const streamId = ready('hn-headless').payload.streamId as string
      await manager.handleFrame('hn-headless', 'terminal_resize', { streamId, resizeSeq: 1, cols: 30, rows: 10 })
      expect(sent.at(-1)?.payload.code).toBe('VIEW_ONLY')
      expect(stream.sizes).toEqual([])
    })

    it('is not anyone holding it: a window that reconnects politely beside it takes the terminal, and is told of no holder', async () => {
      // After a daemon restart, each in turn: hn with no terminal is back first, then a window with a person in it
      // (hn's, the desktop's, the phone's) reconnects the way it always does after its first open, without the key.
      for (const [connId, kind] of [['hn-window', 'tui'], ['desktop-1', 'desktop'], ['phone-1', 'phone']] as const) {
        await manager.closeConnection('hn-headless')
        await manager.handleFrame('hn-headless', 'terminal_open', {
          requestId: 'open-headless', protocolVersion: 3, agentId: 'agent-1', cols: 37, rows: 22, takeover: false, watch: true,
          client: { kind: 'tui', name: 'Mac Auto terminal' },
        })
        expect(ready('hn-headless').payload.readOnly).toBe(true)
        sent.length = 0
        readOnlyOpens.length = 0
        await manager.handleFrame(connId, 'terminal_open', {
          requestId: `open-${connId}`, protocolVersion: 3, agentId: 'agent-1', cols: 99, rows: 55, takeover: false,
          client: { kind, name: connId },
        })
        expect(ready(connId).payload.readOnly).toBe(false)
        expect(ready(connId).payload).not.toHaveProperty('heldBy')
        // tmux attaches it as the controller, at its own size.
        expect(readOnlyOpens).toEqual([false])
        // The watcher goes as any does when a terminal changes hands, and opens again on the new size.
        expect(sent.find((frame) => frame.connId === 'hn-headless' && frame.type === 'terminal_closed')?.payload)
          .toMatchObject({ code: 'TERMINAL_TAKEN_OVER', takenBy: { kind, name: connId } })
        await manager.closeConnection(connId)
      }
    })

    it('leaves the window beside it typing and resizing', async () => {
      await manager.handleFrame('hn-headless', 'terminal_open', {
        requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 37, rows: 22, takeover: false, watch: true,
      })
      await manager.handleFrame('desktop-1', 'terminal_open', {
        requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40, takeover: false,
      })
      const streamId = ready('desktop-1').payload.streamId as string
      await manager.handleFrame('desktop-1', 'terminal_resize', { streamId, resizeSeq: 1, cols: 100, rows: 30 })
      expect(stream.sizes).toEqual([{ cols: 100, rows: 30 }])
      await manager.handleBinary('desktop-1', { kind: TerminalBinaryKind.input, streamId, seq: 0, compressed: false, bytes: Buffer.from('ok') })
      expect(Buffer.from(stream.writes[0]).toString()).toBe('ok')
    })

    it('leaves a client already driving the terminal alone, and a polite open beside both still watches that client', async () => {
      await manager.handleFrame('desktop-1', 'terminal_open', {
        requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 120, rows: 40,
        client: { kind: 'desktop', name: 'MacBookPro2021.local' },
      })
      await manager.handleFrame('hn-headless', 'terminal_open', {
        requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 37, rows: 22, takeover: false, watch: true,
        client: { kind: 'tui', name: 'Mac Auto terminal' },
      })
      expect(sent.some((frame) => frame.connId === 'desktop-1' && frame.type === 'terminal_closed')).toBe(false)
      expect(ready('hn-headless').payload).toMatchObject({ readOnly: true, heldBy: { kind: 'desktop', name: 'MacBookPro2021.local' } })
      // The phone's pager guess, beside the desktop and the watch-only stream: the desktop's, named as it.
      await manager.handleFrame('phone-1', 'terminal_open', {
        requestId: 'open-3', protocolVersion: 3, agentId: 'agent-1', cols: 40, rows: 20, takeover: false,
        client: { kind: 'phone', name: 'iPhone 15' },
      })
      expect(ready('phone-1').payload).toMatchObject({ readOnly: true, heldBy: { kind: 'desktop', name: 'MacBookPro2021.local' } })
      expect(readOnlyOpens).toEqual([false, true, true])
    })

    it('is closed by a takeover like any watcher, so it opens again on the size the new holder gave the pane', async () => {
      await manager.handleFrame('hn-headless', 'terminal_open', {
        requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 37, rows: 22, takeover: false, watch: true,
      })
      await manager.handleFrame('phone-1', 'terminal_open', {
        requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 40, rows: 20,
        client: { kind: 'phone', name: 'iPhone 15' },
      })
      expect(sent.find((frame) => frame.connId === 'hn-headless' && frame.type === 'terminal_closed')?.payload)
        .toMatchObject({ code: 'TERMINAL_TAKEN_OVER', takenBy: { kind: 'phone', name: 'iPhone 15' } })
      expect(ready('phone-1').payload.readOnly).toBe(false)
    })

    it('is advertised, so a client can tell a daemon that would ignore the key', async () => {
      await manager.handleFrame('web-1', 'terminal_capabilities', { requestId: 'r1' })
      expect((sent.at(-1)?.payload.features as Record<string, unknown>).watchOnly).toBe(true)
    })
  })

  it('falls back to what the daemon can say about a silent winner, and says nothing over a bad claim', async () => {
    manager = newManager({
      describeClient: (connId) => connId === 'local-2' ? { kind: 'desktop', name: 'This Mac' } : null,
    })
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    await manager.handleFrame('local-2', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    expect(sent.find((frame) => frame.connId === 'web-1' && frame.type === 'terminal_closed')?.payload.takenBy)
      .toEqual({ kind: 'desktop', name: 'This Mac' })
    // A claim the daemon will not repeat: a kind with spaces, or a name that is not a name.
    await manager.handleFrame('web-3', 'terminal_open', {
      requestId: 'open-3', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
      client: { kind: 'not a kind', name: 'x'.repeat(500) },
    })
    const closed = sent.find((frame) => frame.connId === 'local-2' && frame.type === 'terminal_closed')
    expect(closed?.payload.code).toBe('TERMINAL_TAKEN_OVER')
    expect(closed?.payload).not.toHaveProperty('takenBy')
    expect(sent.findLast((frame) => frame.type === 'terminal_ready')?.connId).toBe('web-3')
  })

  it('reads a client descriptor strictly', () => {
    expect(clientDescriptorFrom({ kind: 'phone', name: 'Hieu\u2019s iPhone' })).toEqual({ kind: 'phone', name: 'Hieu\u2019s iPhone' })
    expect(clientDescriptorFrom({ kind: 'desktop', name: 'a\u0000b', machineId: 'ab12ab12ab12ab12' }))
      .toEqual({ kind: 'desktop', name: 'a b', machineId: 'ab12ab12ab12ab12' })
    expect(clientDescriptorFrom({ kind: 'desktop', name: 'Mac', machineId: '../etc' })).toBeUndefined()
    expect(clientDescriptorFrom({ kind: 'Desktop', name: 'Mac' })).toBeUndefined()
    expect(clientDescriptorFrom({ kind: 'desktop', name: '   ' })).toBeUndefined()
    expect(clientDescriptorFrom('Mac')).toBeUndefined()
    expect(clientDescriptorFrom(undefined)).toBeUndefined()
  })

  it('takes over a second agent alias that resolves to the same tmux pane', async () => {
    agents.set('agent-alias', session('claude', 'agent-alias'))
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    await manager.handleFrame('web-2', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-alias', cols: 100, rows: 30,
    })
    expect(sent.some((frame) => frame.connId === 'web-1'
      && frame.type === 'terminal_closed'
      && frame.payload.code === 'TERMINAL_TAKEN_OVER')).toBe(true)
    expect(sent.findLast((frame) => frame.type === 'terminal_ready')?.connId).toBe('web-2')
  })

  it('keeps a client\'s other terminals alive when it opens another one', async () => {
    // The desktop app's pane grid: one connection, several agents, each its own tmux window.
    agents.set('agent-2', {
      ...session('claude', 'agent-2'),
      runtimes: [{ backend: 'tmux', paneId: '%2' }],
      primaryRuntimeKey: 'tmux:default:%2',
    } as unknown as RegisteredSession)

    await manager.handleFrame('app-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    const first = sent.find((frame) => frame.type === 'terminal_ready')?.payload.streamId as string

    await manager.handleFrame('app-1', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-2', cols: 100, rows: 30,
    })

    expect(sent.some((frame) => frame.type === 'terminal_closed')).toBe(false)
    // The other pane still accepts operations on its original stream.
    const before = stream.sizes.length
    await manager.handleFrame('app-1', 'terminal_resize', {
      streamId: first, resizeSeq: 1, cols: 90, rows: 25,
    })
    expect(stream.sizes.length).toBe(before + 1)
  })

  it('notifies legacy views when a shared connection reopens the same terminal', async () => {
    await manager.handleFrame('app-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    const first = sent.find((frame) => frame.type === 'terminal_ready')?.payload.streamId as string

    await manager.handleFrame('app-1', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
      client: { kind: 'desktop', name: 'Other window' },
    })

    expect(sent.filter((frame) => frame.type === 'terminal_closed')).toEqual([{
      connId: 'app-1',
      type: 'terminal_closed',
      payload: {
        protocolVersion: 3,
        streamId: first,
        reason: 'terminal reopened in another view',
        code: 'TERMINAL_TAKEN_OVER',
      },
    }])
    expect(sent.at(-1)).toMatchObject({ type: 'terminal_ready', payload: { requestId: 'open-2' } })
    const replacement = sent.at(-1)!.payload.streamId as string
    expect(replacement).not.toBe(first)
    await manager.handleBinary('app-1', {
      kind: TerminalBinaryKind.input, streamId: replacement, seq: 0, compressed: false, bytes: Buffer.from('new input'),
    })
    expect(Buffer.from(stream.writes.at(-1)!).toString()).toBe('new input')

    // Two tmux clients on one window is the thing this must never allow.
    const before = stream.sizes.length
    await manager.handleFrame('app-1', 'terminal_resize', {
      streamId: first, resizeSeq: 1, cols: 90, rows: 25,
    })
    expect(stream.sizes.length).toBe(before)
  })

  it.each(['agent-1', 'agent-alias'])('keeps relay views independent when watching and taking over %s', async (secondAgent) => {
    agents.set('agent-alias', session('codex', 'agent-alias'))
    const handles: FakeStream[] = []
    terminals.openStream = vi.fn(async () => {
      const handle = new FakeStream()
      handles.push(handle)
      return { state: 'succeeded' as const, value: handle }
    })
    const open = async (viewId: string, takeover: boolean, agentId = 'agent-1') => {
      await manager.handleFrame('shared-relay', 'terminal_open', {
        requestId: `${viewId}-${handles.length}`, protocolVersion: 3, agentId,
        cols: 100, rows: 30, viewId, takeover, client: { kind: 'desktop', name: viewId },
      })
      return sent.findLast((frame) => frame.type === 'terminal_ready')!.payload
    }
    const type = (streamId: unknown, text: string, seq = 0) => manager.handleBinary('shared-relay', {
      kind: TerminalBinaryKind.input, streamId: streamId as string, seq,
      compressed: false, bytes: Buffer.from(text),
    })

    const controller = await open('view-a', true)
    const watcher = await open('view-b', false, secondAgent)
    expect(watcher).toMatchObject({ readOnly: true, heldBy: { name: 'view-a' } })
    expect(handles[0].closed).toBe(false)
    expect(sent.filter((frame) => frame.type === 'terminal_closed')).toEqual([])
    await type(controller.streamId, 'still typing')
    await type(watcher.streamId, 'ignored')
    expect(Buffer.from(handles[0].writes[0]).toString()).toBe('still typing')
    expect(handles[1].writes).toEqual([])

    // Reopening the watcher only replaces that view's own stream.
    const watchingAgain = await open('view-b', false, secondAgent)
    expect(watchingAgain.readOnly).toBe(true)
    expect(handles[0].closed).toBe(false)
    expect(handles[1].closed).toBe(true)
    expect(sent.filter((frame) => frame.type === 'terminal_closed').map((frame) => frame.payload.streamId))
      .toEqual([watcher.streamId])

    const nextController = await open('view-b', true, secondAgent)
    expect(nextController.readOnly).toBe(false)
    expect(sent.find((frame) => frame.type === 'terminal_closed' && frame.payload.streamId === controller.streamId)?.payload)
      .toMatchObject({ code: 'TERMINAL_TAKEN_OVER', takenBy: { name: 'view-b' } })
    expect(handles[0].closed).toBe(true)

    // A displaced client (including the TUI's automatic watch) must never take control back.
    const displacedWatcher = await open('view-a', false)
    expect(displacedWatcher).toMatchObject({ readOnly: true, heldBy: { name: 'view-b' } })
    expect(handles[3].closed).toBe(false)
    await type(nextController.streamId, 'new owner')
    await type(displacedWatcher.streamId, 'ignored')
    expect(Buffer.from(handles[3].writes[0]).toString()).toBe('new owner')
    expect(handles[4].writes).toEqual([])
    await manager.handleFrame('shared-relay', 'terminal_close', { streamId: displacedWatcher.streamId })
    expect((await open('view-c', false)).heldBy).toEqual({ kind: 'desktop', name: 'view-b' })
    expect(handles[3].closed).toBe(false)
  })

  it('scopes identical view IDs to their authenticated connection', async () => {
    for (const connId of ['first', 'second']) {
      await manager.handleFrame(connId, 'terminal_open', {
        requestId: connId, protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
        viewId: 'same-view-id', takeover: false,
      })
    }
    expect(sent.filter((frame) => frame.type === 'terminal_ready').map((frame) => frame.payload.readOnly))
      .toEqual([false, true])
    expect(sent.filter((frame) => frame.type === 'terminal_closed')).toEqual([])
  })

  it('uses frequent ACKs rather than the five-second heartbeat for output backpressure', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    const streamId = sent[0].payload.streamId as string
    await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })
    for (let i = 0; i < 40; i++) {
      sink!.onData(Buffer.alloc(32 * 1024, i))
      const output = binarySent.at(-1)!.frame
      expect(output.kind).toBe(TerminalBinaryKind.output)
      await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: output.seq })
    }
    expect(binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toHaveLength(1)
    expect(stream.pauses).toBe(0)
  })

  it('emits an ordered sync frame every five seconds while idle', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-sync', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    await vi.advanceTimersByTimeAsync(5_000)
    expect(binarySent.map(({ frame }) => frame.kind)).toEqual([
      TerminalBinaryKind.keyframe,
      TerminalBinaryKind.sync,
    ])
    expect(binarySent[1].frame.seq).toBe(1)
    expect(binarySent[1].frame.bytes).toHaveLength(0)
    expect(binarySent[1].frame.compressed).toBe(false)
  })

  it('fails closed when pending plus queued output exceeds two MiB', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-overflow', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    sink!.onData(Buffer.alloc(2 * 1024 * 1024))
    await vi.advanceTimersByTimeAsync(1)
    expect(sent.findLast((frame) => frame.type === 'terminal_error')?.payload.code)
      .toBe('TERMINAL_OUTPUT_OVERFLOW')
    expect(stream.closed).toBe(true)
  })

  it('forwards only output released after the ordered snapshot cut', async () => {
    stream.onEndSnapshot = () => sink!.onData(Buffer.from('post-cut'))
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-cut', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    await vi.advanceTimersByTimeAsync(8)
    expect(binarySent.map(({ frame }) => frame.kind)).toEqual([
      TerminalBinaryKind.keyframe,
      TerminalBinaryKind.output,
    ])
    expect(Buffer.from(binarySent[1].frame.bytes).toString()).toBe('post-cut')
  })

  it('pauses PTY output above the high watermark and resumes below the low watermark', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    const streamId = sent[0].payload.streamId as string
    await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })
    for (let i = 0; i < 13; i++) sink!.onData(Buffer.alloc(32 * 1024, i))
    await vi.advanceTimersByTimeAsync(1)
    expect(stream.pauses).toBe(1)
    expect(stream.resumes).toBe(0)
    sink!.onData(Buffer.from('buffered-while-renderer-paused'))
    const outputs = binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.output)
    await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: outputs[9].frame.seq })
    await vi.advanceTimersByTimeAsync(8)
    expect(stream.resumes).toBe(1)
    expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('buffered-while-renderer-paused')
    expect(binarySent.filter(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toHaveLength(1)
  })

  it('closes a stream whose renderer stays stalled after tmux is paused', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-stall', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    const streamId = sent[0].payload.streamId as string
    await manager.handleFrame('web-1', 'terminal_ack', { streamId, lastSeq: binarySent[0].frame.seq })
    for (let i = 0; i < 13; i++) sink!.onData(Buffer.alloc(32 * 1024, i))
    expect(stream.pauses).toBe(1)

    await vi.advanceTimersByTimeAsync(10_000)

    expect(sent.findLast((frame) => frame.type === 'terminal_error')?.payload.code)
      .toBe('TERMINAL_RENDER_STALLED')
    expect(stream.closed).toBe(true)
  })

  it('fails closed instead of emitting an oversized binary keyframe', async () => {
    stream.snapshotBytes = Buffer.alloc(481 * 1024, 0x61)
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'oversized', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    expect(stream.snapshots).toBe(1)
    expect(binarySent.some(({ frame }) => frame.kind === TerminalBinaryKind.keyframe)).toBe(false)
    expect(sent.findLast((frame) => frame.type === 'terminal_error')?.payload.code)
      .toBe('TERMINAL_SNAPSHOT_TOO_LARGE')
    expect(stream.closed).toBe(true)
  })

  it('disconnect cleanup closes the stream and releases the controller', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-1', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    await manager.closeConnection('web-1')
    expect(stream.closed).toBe(true)
    const replacement = new FakeStream()
    stream = replacement
    await manager.handleFrame('web-2', 'terminal_open', {
      requestId: 'open-2', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    expect(sent.at(-1)?.type).toBe('terminal_ready')
    expect(binarySent.at(-1)?.frame.kind).toBe(TerminalBinaryKind.keyframe)
  })
  it('sends the first output after a quiet gap without waiting for the coalescing window', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-echo', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    const before = binarySent.length

    // A keystroke echo: no timers advanced at all.
    sink!.onData(Buffer.from('a'))
    expect(binarySent.length).toBe(before + 1)
    expect(binarySent.at(-1)?.frame.kind).toBe(TerminalBinaryKind.output)
    expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('a')
  })

  it('still coalesces a burst onto the trailing window', async () => {
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-burst', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    sink!.onData(Buffer.from('lead'))
    const afterLeadingEdge = binarySent.length

    // Everything arriving inside the window rides one frame, not one frame each.
    sink!.onData(Buffer.from('one'))
    sink!.onData(Buffer.from('two'))
    sink!.onData(Buffer.from('three'))
    expect(binarySent.length).toBe(afterLeadingEdge)

    await vi.advanceTimersByTimeAsync(8)
    expect(binarySent.length).toBe(afterLeadingEdge + 1)
    expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('onetwothree')
  })

  it('coalesces a loopback burst on a 2ms window while the relay keeps 8ms', async () => {
    await manager.stop()
    manager = newManager({ isLoopback: (connId) => connId.startsWith('local:') })

    const burst = async (connId: string, requestId: string): Promise<number> => {
      await manager.handleFrame(connId, 'terminal_open', {
        requestId, protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
      })
      await vi.advanceTimersByTimeAsync(20)   // a quiet gap, so 'lead' takes the leading edge
      sink!.onData(Buffer.from('lead'))
      const afterLeadingEdge = binarySent.length
      sink!.onData(Buffer.from('one'))
      sink!.onData(Buffer.from('two'))
      sink!.onData(Buffer.from('three'))
      expect(binarySent.length).toBe(afterLeadingEdge)
      return afterLeadingEdge
    }

    // The desktop on this computer: the burst goes out after 2ms, as one frame.
    let afterLeadingEdge = await burst('local:desktop', 'open-local-burst')
    await vi.advanceTimersByTimeAsync(2)
    expect(binarySent.length).toBe(afterLeadingEdge + 1)
    expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('onetwothree')

    // Anything else still waits the full 8ms window.
    afterLeadingEdge = await burst('web-1', 'open-web-burst')
    await vi.advanceTimersByTimeAsync(2)
    expect(binarySent.length).toBe(afterLeadingEdge)
    await vi.advanceTimersByTimeAsync(6)
    expect(binarySent.length).toBe(afterLeadingEdge + 1)
    expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('onetwothree')
  })

  it('gives the short window only to the terminal the loopback window has focused', async () => {
    await manager.stop()
    manager = newManager({ isLoopback: (connId) => connId.startsWith('local:') })

    // A burst after a quiet gap; returns how long its trailing frame took to go out.
    const trailingWindow = async (): Promise<number> => {
      await vi.advanceTimersByTimeAsync(20)
      sink!.onData(Buffer.from('lead'))
      const afterLeadingEdge = binarySent.length
      sink!.onData(Buffer.from('one'))
      sink!.onData(Buffer.from('two'))
      for (let ms = 1; ms <= 8; ms++) {
        await vi.advanceTimersByTimeAsync(1)
        if (binarySent.length > afterLeadingEdge) {
          expect(Buffer.from(binarySent.at(-1)!.frame.bytes).toString()).toBe('onetwo')
          return ms
        }
      }
      throw new Error('burst never flushed')
    }

    // Focus elsewhere before the open: this terminal is a background tile.
    manager.setFocusedAgent('local:desktop', 'agent-other')
    await manager.handleFrame('local:desktop', 'terminal_open', {
      requestId: 'open-focus', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    expect(await trailingWindow()).toBe(8)

    // Focus moves onto it: the open stream follows, no reopen needed.
    manager.setFocusedAgent('local:desktop', 'agent-1')
    expect(await trailingWindow()).toBe(2)

    // No terminal focused at all.
    manager.setFocusedAgent('local:desktop', null)
    expect(await trailingWindow()).toBe(8)

    // Focus is a loopback matter: anything else keeps 8ms whatever it is told.
    await manager.handleFrame('web-1', 'terminal_open', {
      requestId: 'open-web-focus', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    manager.setFocusedAgent('web-1', 'agent-1')
    expect(await trailingWindow()).toBe(8)
  })

  it('forgets a loopback window\'s focus when it disconnects', async () => {
    await manager.stop()
    manager = newManager({ isLoopback: (connId) => connId.startsWith('local:') })
    manager.setFocusedAgent('local:desktop', 'agent-other')
    await manager.closeConnection('local:desktop')

    // Reconnected under the same id and silent about focus: back to the short window.
    await manager.handleFrame('local:desktop', 'terminal_open', {
      requestId: 'open-after-close', protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30,
    })
    await vi.advanceTimersByTimeAsync(20)
    sink!.onData(Buffer.from('lead'))
    const afterLeadingEdge = binarySent.length
    sink!.onData(Buffer.from('tail'))
    await vi.advanceTimersByTimeAsync(2)
    expect(binarySent.length).toBe(afterLeadingEdge + 1)
  })

  describe('who is looking', () => {
    const open = (connId: string, extra: Record<string, unknown> = {}) =>
      manager.handleFrame(connId, 'terminal_open', {
        requestId: `open-${connId}`, protocolVersion: 3, agentId: 'agent-1', cols: 100, rows: 30, ...extra,
      })
    beforeEach(async () => {
      await manager.stop()
      manager = newManager({ isLoopback: (connId) => connId.startsWith('local:') })
    })

    it('a loopback stream whose window lists other agents is not looked at', async () => {
      await open('local:desktop')
      manager.setVisibleAgents('local:desktop', ['agent-other'])
      expect(manager.isLookedAt('agent-1')).toBe(false)
      manager.setVisibleAgents('local:desktop', ['agent-1'])
      expect(manager.isLookedAt('agent-1')).toBe(true)
    })

    it('a loopback stream whose window never sent a list is looked at', async () => {
      await open('local:desktop')
      expect(manager.isLookedAt('agent-1')).toBe(true)
      manager.setVisibleAgents('local:desktop', null)
      expect(manager.isLookedAt('agent-1')).toBe(true)
    })

    it('a mobile or web stream is looked at, a takeover:false one included', async () => {
      await open('web-1')
      await open('web-2', { takeover: false })
      expect(manager.isLookedAt('agent-1')).toBe(true)
      await manager.closeConnection('web-1')
      expect(manager.isLookedAt('agent-1')).toBe(true)
      await manager.closeConnection('web-2')
      expect(manager.isLookedAt('agent-1')).toBe(false)
    })

    it('a watch:true stream is never looked at', async () => {
      await open('web-1', { watch: true })
      await open('local:desktop', { watch: true })
      expect(manager.isLookedAt('agent-1')).toBe(false)
    })

    it('a Share observer on a read-only manager counts even when it asks for watch:true', async () => {
      await manager.stop()
      manager = newManager({ readOnly: true })
      await open('observer:ken', { watch: true })
      expect(manager.isLookedAt('agent-1')).toBe(true)
    })

    it('a minimized window\'s empty list frees its agents', async () => {
      await open('local:desktop')
      manager.setVisibleAgents('local:desktop', [])
      expect(manager.isLookedAt('agent-1')).toBe(false)
    })

    it('closing the connection forgets its list', async () => {
      await open('local:desktop')
      manager.setVisibleAgents('local:desktop', [])
      await manager.closeConnection('local:desktop')
      await open('local:desktop')
      expect(manager.isLookedAt('agent-1')).toBe(true)
    })
  })

  describe('while an agent changes host', () => {
    const oldPane = { backend: 'ptyhost' as const, instance: 'p2', paneId: '%1' }
    const newPane = { backend: 'ptyhost' as const, instance: 'p2-0.5.0', paneId: '%7' }
    let gate: MoveGate
    let opens: Array<{ runtimes: unknown; size: unknown; readOnly: boolean; sink: TerminalStreamSink; stream: FakeStream }>
    let rawWrites: Array<{ runtime: unknown; bytes: string }>
    let duringOpen: (() => void) | null
    const paste = (connId: string, streamId: string, text: string) => manager.handleBinary(connId, {
      kind: TerminalBinaryKind.paste, streamId, seq: 0, bytes: Buffer.from(text), compressed: false,
    })
    /** What the mover does at the swap: the row names the new pane, and the agent's streams follow it. */
    const swap = async () => {
      agents.set('agent-1', row('agent-1', newPane))
      await manager.retarget('agent-1', newPane)
    }
    const row = (agentId: string, runtime: typeof oldPane) => ({
      ...session('codex', agentId), runtimes: [runtime], primaryRuntimeKey: `ptyhost:${runtime.instance}:${runtime.paneId}`,
    } as unknown as RegisteredSession)
    const openFrame = (connId: string, agentId = 'agent-1') => manager.handleFrame(connId, 'terminal_open', {
      requestId: `open-${connId}`, protocolVersion: 3, agentId, cols: 100, rows: 30,
    })
    const readyFor = (connId: string) => String(sent.findLast((f) => f.connId === connId && f.type === 'terminal_ready')!.payload.streamId)
    const input = (connId: string, streamId: string, seq: number, text: string) => manager.handleBinary(connId, {
      kind: TerminalBinaryKind.input, streamId, seq, bytes: Buffer.from(text), compressed: false,
    })

    beforeEach(async () => {
      await manager.stop()
      gate = new MoveGate()
      opens = []
      rawWrites = []
      agents = new Map([['agent-1', row('agent-1', oldPane)], ['agent-2', row('agent-2', { ...oldPane, paneId: '%2' })]])
      duringOpen = null
      terminals = {
        openStream: async (opened: RegisteredSession, size: unknown, nextSink: TerminalStreamSink, readOnly = false) => {
          const next = new FakeStream()
          opens.push({ runtimes: opened.runtimes, size, readOnly, sink: nextSink, stream: next })
          duringOpen?.()
          return { state: 'succeeded' as const, value: next }
        },
        backendFor: () => ({
          writeInput: async (runtime: unknown, bytes: Uint8Array) => {
            rawWrites.push({ runtime, bytes: Buffer.from(bytes).toString() })
            return TERMINAL_ACTION_SUCCEEDED
          },
          pasteInput: async (runtime: unknown, text: string) => {
            rawWrites.push({ runtime, bytes: `paste:${text}` })
            return TERMINAL_ACTION_SUCCEEDED
          },
        }),
      } as unknown as TerminalBackendCoordinator
      manager = newManager({ moveGate: gate, isLoopback: (connId) => connId.startsWith('local:') })
    })

    it('input during a hold is delivered once, in order, after release', async () => {
      const onInput = vi.fn()
      await manager.stop()
      manager = newManager({ moveGate: gate, onInput })
      await openFrame('web-1')
      const streamId = readyFor('web-1')
      gate.hold('agent-1')
      await input('web-1', streamId, 0, 'a')
      await input('web-1', streamId, 1, 'b')
      await input('web-1', streamId, 2, 'c')
      // Taken as input at once (the prewarm, the quiet clock), but nothing reaches a pane yet.
      expect(onInput).toHaveBeenCalledTimes(3)
      expect(opens[0].stream.writes).toEqual([])
      await swap()
      expect(opens[1].stream.writes).toEqual([])
      await gate.release('agent-1')
      // Through the retargeted stream, onto the new pane; never the old one.
      expect(opens[1].stream.order).toEqual(['raw:a', 'raw:b', 'raw:c'])
      expect(opens[0].stream.writes).toEqual([])
      expect(rawWrites).toEqual([])
      expect(sent.filter((f) => f.type === 'terminal_error')).toEqual([])
    })

    it('held input whose stream closed during the move still reaches the row\'s pane', async () => {
      await openFrame('web-1')
      const streamId = readyFor('web-1')
      gate.hold('agent-1')
      await input('web-1', streamId, 0, 'a')
      await paste('web-1', streamId, 'P')
      await manager.closeConnection('web-1')
      agents.set('agent-1', row('agent-1', newPane))
      await gate.release('agent-1')
      expect(rawWrites).toEqual([{ runtime: newPane, bytes: 'a' }, { runtime: newPane, bytes: 'paste:P' }])
      expect(opens[0].stream.writes).toEqual([])
    })

    it('a paste during a hold is delivered after release, in order with keystrokes', async () => {
      await openFrame('web-1')
      const streamId = readyFor('web-1')
      gate.hold('agent-1')
      await input('web-1', streamId, 0, 'a')
      await paste('web-1', streamId, 'P')
      await input('web-1', streamId, 1, 'b')
      expect(opens[0].stream.order).toEqual([])
      await swap()
      await gate.release('agent-1')
      expect(opens[1].stream.order).toEqual(['raw:a', 'paste:P', 'raw:b'])
      expect(opens[0].stream.order).toEqual([])
    })

    it('an image paste during a hold is delivered after release, in order with keystrokes', async () => {
      await openFrame('web-1')
      const streamId = readyFor('web-1')
      gate.hold('agent-1')
      const png = Uint8Array.of(0x89, 0x50, 0x4e, 0x47)
      await input('web-1', streamId, 0, 'a')
      await manager.handleFrame('web-1', 'terminal_chunked_upload_begin', { streamId, uploadKind: 'image', totalBytes: png.length })
      await manager.handleBinary('web-1', { kind: TerminalBinaryKind.imagePaste, streamId, seq: 0, compressed: false, bytes: png })
      await input('web-1', streamId, 1, 'b')
      expect(writeImageToOsClipboard).not.toHaveBeenCalled()
      expect(opens[0].stream.order).toEqual([])
      await swap()
      await gate.release('agent-1')
      expect(writeImageToOsClipboard).toHaveBeenCalledTimes(1)
      expect(opens[1].stream.order).toEqual(['raw:a', 'raw:\u0016', 'raw:b'])
      expect(sent.findLast((f) => f.type === 'terminal_paste_image_result')?.payload).toMatchObject({ streamId, outcome: 'clipboard' })
    })

    it('a held agent counts as looked at from the moment input or an open arrives, until it is let go', async () => {
      await openFrame('local:desktop')
      manager.setVisibleAgents('local:desktop', ['agent-other'])
      gate.hold('agent-1')
      expect(manager.isLookedAt('agent-1')).toBe(false)
      await input('local:desktop', readyFor('local:desktop'), 0, 'x')
      expect(manager.isLookedAt('agent-1')).toBe(true)
      await gate.release('agent-1')
      expect(manager.isLookedAt('agent-1')).toBe(false)
      // The next hold starts untouched.
      gate.hold('agent-1')
      expect(manager.isLookedAt('agent-1')).toBe(false)
      await gate.release('agent-1')

      manager.setVisibleAgents('local:other', ['agent-other'])
      gate.hold('agent-2')
      await openFrame('local:other', 'agent-2')
      expect(manager.isLookedAt('agent-2')).toBe(true)
      await gate.release('agent-2')
      expect(manager.isLookedAt('agent-2')).toBe(false)
    })

    it('an open during a hold returns at once on the current runtime, and is moved by the retarget at swap', async () => {
      gate.hold('agent-1')
      await openFrame('web-1')
      const streamId = readyFor('web-1')
      expect(opens.map((o) => o.runtimes)).toEqual([[oldPane]])
      await swap()
      expect(opens.map((o) => o.runtimes)).toEqual([[oldPane], [newPane]])
      expect(opens[0].stream.closed).toBe(true)
      await gate.release('agent-1')
      expect(sent.filter((f) => f.type === 'terminal_closed' || f.type === 'terminal_error')).toEqual([])
      await input('web-1', streamId, 0, 'typed')
      expect(opens[1].stream.order).toEqual(['raw:typed'])
    })

    it('an open the swap overtook follows the row on its own', async () => {
      gate.hold('agent-1')
      // The mover switches the row and retargets while this open is still reaching the old pane: the
      // retarget finds no stream to move, so the open has to notice.
      duringOpen = () => {
        duringOpen = null
        agents.set('agent-1', row('agent-1', newPane))
        void manager.retarget('agent-1', newPane)
      }
      await openFrame('web-1')
      expect(opens.map((o) => o.runtimes)).toEqual([[oldPane], [newPane]])
      expect(opens[0].stream.closed).toBe(true)
      expect(sent.filter((f) => f.type === 'terminal_closed' || f.type === 'terminal_error')).toEqual([])
      await gate.release('agent-1')
    })

    it('a retarget opens the new pane at the size the client last asked for, even one the old pane refused', async () => {
      await openFrame('web-1')
      const streamId = readyFor('web-1')
      opens[0].stream.resize = async () => ({ state: 'failed', dispatch: 'rejected', reason: 'no' })
      await manager.handleFrame('web-1', 'terminal_resize', { streamId, resizeSeq: 1, cols: 90, rows: 20 })
      await swap()
      expect(opens[1].size).toEqual({ cols: 90, rows: 20 })
    })

    it('an open stream follows a retarget with no close, and gets the new pane\'s output', async () => {
      await openFrame('web-1')
      await openFrame('web-2')
      const watcherOpen = manager.handleFrame('web-3', 'terminal_open', {
        requestId: 'watch', protocolVersion: 3, agentId: 'agent-1', cols: 80, rows: 24, watch: true,
      })
      await watcherOpen
      const streamId = readyFor('web-2')
      await manager.handleFrame('web-2', 'terminal_resize', { streamId, resizeSeq: 1, cols: 120, rows: 40 })
      const [, before, watcher] = opens
      before.stream.snapshotBytes = Buffer.from('old pane')
      const framesBefore = binarySent.length
      sent = []

      await manager.retarget('agent-1', newPane)

      // Every open stream of the agent was re-subscribed on the new pane, at its own size and mode.
      expect(opens.slice(3).map((o) => [o.runtimes, o.size, o.readOnly])).toEqual([
        [[newPane], { cols: 120, rows: 40 }, false],
        [[newPane], { cols: 80, rows: 24 }, true],
      ])
      expect(before.stream.closed).toBe(true)
      expect(watcher.stream.closed).toBe(true)
      expect(sent.filter((f) => f.type === 'terminal_closed' || f.type === 'terminal_error')).toEqual([])
      const after = opens[3]
      // The client's screen is reset through the keyframe it already knows, on its own stream id.
      expect(after.stream.snapshots).toBe(1)
      const keyframe = binarySent.slice(framesBefore).find((f) => f.connId === 'web-2' && f.frame.kind === TerminalBinaryKind.keyframe)
      expect(keyframe?.frame.streamId).toBe(streamId)

      // The old pane's late output is dropped; the new pane's reaches the same stream.
      const sentNow = binarySent.length
      before.sink.onData(Buffer.from('late old output'))
      before.sink.onClose('old pane gone')
      after.sink.onData(Buffer.from('new pane output'))
      await vi.advanceTimersByTimeAsync(20)
      const outputs = binarySent.slice(sentNow).filter((f) => f.connId === 'web-2' && f.frame.kind === TerminalBinaryKind.output)
      expect(outputs.map((f) => [f.frame.streamId, Buffer.from(f.frame.bytes).toString()])).toEqual([[streamId, 'new pane output']])
      expect(sent.filter((f) => f.type === 'terminal_closed')).toEqual([])

      // Input on the same stream now goes to the new pane.
      await input('web-2', streamId, 0, 'typed')
      expect(after.stream.writes.map((b) => Buffer.from(b).toString())).toEqual(['typed'])
      expect(before.stream.writes).toEqual([])
    })

    it('a keyframe being taken of the old pane when the stream moves is taken again of the new one', async () => {
      await openFrame('web-1')
      const streamId = readyFor('web-1')
      const before = opens[0].stream
      let finishOld!: () => void
      before.snapshot = () => new Promise((resolve) => {
        finishOld = () => resolve({ state: 'succeeded', value: { bytes: Buffer.from('old pane'), cols: 100, rows: 30 } })
      })
      const resync = manager.handleFrame('web-1', 'terminal_resync', { streamId })
      await vi.advanceTimersByTimeAsync(0)
      const framesBefore = binarySent.length
      await manager.retarget('agent-1', newPane)
      const after = opens[1].stream
      after.snapshotBytes = Buffer.from('new pane')
      finishOld()
      await resync
      const keyframes = binarySent.slice(framesBefore).filter((f) => f.frame.kind === TerminalBinaryKind.keyframe)
      expect(keyframes.map((f) => [f.frame.streamId, Buffer.from(f.frame.bytes).toString()])).toEqual([[streamId, 'new pane']])
      expect(after.snapshotBegins).toBe(after.snapshotEnds)
      expect(sent.filter((f) => f.type === 'terminal_closed' || f.type === 'terminal_error')).toEqual([])
    })

    it('nothing is held for other agents', async () => {
      await openFrame('web-1', 'agent-2')
      const streamId = readyFor('web-1')
      gate.hold('agent-1')
      await input('web-1', streamId, 0, 'free')
      expect(opens[0].stream.writes.map((b) => Buffer.from(b).toString())).toEqual(['free'])
      await openFrame('web-2', 'agent-2')
      expect(opens).toHaveLength(2)
      expect(rawWrites).toEqual([])
    })
  })
})