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.

93.3 KB
Raw Blame
import { randomUUID } from 'node:crypto'
import { typedByPerson } from './typedInput.js'
import { inputContextIn, nativeSubmitKey } from './nativeTurnObservations.js'
import { unlink } from 'node:fs/promises'
import { deflateSync } from 'node:zlib'
import { ENGINES } from '../engines/types.js'
import { launchContract } from '../engines/launches.js'
import type { RegisteredSession } from './registry.js'
import { writeImageToOsClipboard } from './osClipboard.js'
import { sleptFor } from './sleepAware.js'
import { writePasteDropFile, writePasteImageFile } from './pasteDropFiles.js'
import type { TerminalBackendCoordinator } from './terminalBackendCoordinator.js'
import type { TerminalBackend } from './terminalBackend.js'
import { terminalPlacementKey, terminalRouteKey } from './terminalRuntime.js'
import {
  KEYFRAME_MAX_BYTES,
  terminalActionNotStarted,
  type TerminalActionResult,
  type TerminalRuntimeRef,
  type TerminalStreamHandle,
  type TerminalStreamSize,
} from './terminalTypes.js'
import type { MoveGate } from './hostMove/gate.js'
import {
  TerminalBinaryKind,
  TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES,
  TERMINAL_LOCAL_PASTE_FILE_MAX_PAYLOAD_BYTES,
  type TerminalBinaryClear,
} from './terminalBinary.js'

/** Ctrl+V as a literal byte (ASCII SUB, 0x16) — the same nudge a real Ctrl+V keystroke sends down
 *  the ordinary keystroke pipe. Written after the OS clipboard write below succeeds, so the engine
 *  attached to the pane reads its OWN OS clipboard exactly as it already does for a locally-driven
 *  session — see `pasteImage()`. */
const CTRL_V_BYTE = Uint8Array.of(0x16)

/** Per-chunk size for a chunked image/file upload — comfortably under the 512 KiB per-binary-message
 *  ceiling shared by the backend relay and the P2P data channel (with AEAD/framing overhead room to
 *  spare), and large enough that a 4 MB image is ~16 chunks / a 10 MB file ~40. Deliberately NOT a
 *  credit/window scheme like the firmware pusher's (cli/src/cable/fwPush.ts) — that exists because
 *  USB Serial/JTAG has no real backpressure; a WebSocket already backpressures at the socket layer,
 *  so the client just sends chunks back-to-back. Mirrors the Dart client's own chunk size — keep
 *  the two in step. */
export const UPLOAD_CHUNK_BYTES = 256 * 1024

interface PendingUpload {
  kind: TerminalBinaryKind.imagePaste | TerminalBinaryKind.pasteFile
  /** Only meaningful (and required) for a `pasteFile` upload. */
  filename?: string
  totalBytes: number
  expectedChunks: number
  /** Indexed by chunk seq; sparse until every chunk has arrived. */
  chunks: (Buffer | undefined)[]
  bytesReceived: number
}

type FramePayload = Record<string, unknown>

/**
 * Who a terminal client says it is, from `terminal_open`'s optional `client` — so the incumbent it
 * displaces can be told WHO took control ("Mac mini took control of this terminal") rather than
 * "another app". Self-declared and trusted as such: every client on a machine is the same account's,
 * and the daemon could not do better on its own (a local window is `local:<uuid>`, a relayed
 * desktop's E2EE label is the literal 'harness link', a phone's is 'browser'). `machineId` is the
 * desktop's own machine in the fleet, so the receiver can show that machine's CURRENT name.
 */
export interface TerminalClientDescriptor {
  kind: string
  name: string
  machineId?: string
}

const CLIENT_KIND_RE = /^[a-z]{1,16}$/
const CLIENT_MACHINE_ID_RE = /^[a-f0-9]{16,64}$/
const CLIENT_NAME_MAX = 64

/** The declared client, or undefined for a client that said nothing or said it badly — never an error. */
export function clientDescriptorFrom(raw: unknown): TerminalClientDescriptor | undefined {
  if (!raw || typeof raw !== 'object') return undefined
  const { kind, name, machineId } = raw as Record<string, unknown>
  if (typeof kind !== 'string' || !CLIENT_KIND_RE.test(kind)) return undefined
  if (typeof name !== 'string') return undefined
  // eslint-disable-next-line no-control-regex
  const cleanName = name.replace(/[\u0000-\u001f\u007f]/g, ' ').trim()
  if (!cleanName || cleanName.length > CLIENT_NAME_MAX) return undefined
  if (machineId !== undefined && (typeof machineId !== 'string' || !CLIENT_MACHINE_ID_RE.test(machineId))) return undefined
  return { kind, name: cleanName, ...(machineId ? { machineId } : {}) }
}

const PROTOCOL_VERSION = 3
const HEARTBEAT_TIMEOUT_MS = 30_000
const SYNC_INTERVAL_MS = 5_000
const EXPIRY_SWEEP_MS = 5_000
const OUTPUT_FLUSH_MS = 8
// The terminal the person is typing into on the loopback desktop gains nothing from the 8ms window:
// a frame across 127.0.0.1 costs tens of microseconds, and the app already folds every write between
// two vsyncs into one paint. What the window did cost it was a keystroke echo held up to 8ms whenever
// a TUI was redrawing — a quarter of them in the benchmark. Only the FOCUSED one, though: every frame
// costs the app a decode and a write, and four streaming tiles all on 2ms took its CPU from 15% to
// 18% for background tiles that repaint every 80ms anyway. Those, and the relay, keep 8ms.
const LOOPBACK_OUTPUT_FLUSH_MS = 2
const OUTPUT_CHUNK_BYTES = 32 * 1024
const INPUT_MAX_BYTES = 64 * 1024
/**
 * How long a keystroke that came ahead of the one before it waits for that one (`input`). A client moving a stream
 * from the relay onto its P2P channel sends key N over the relay and key N+1 over the channel, the faster wire by
 * ~150–250ms: N+1 came first and was refused, and the client's realignment lost N+1 and the key after it too
 * (2026-10-15). Within a single wire nothing comes out of order; this only bridges the switch.
 */
const INPUT_REORDER_WAIT_MS = 400
/** What may wait for the missing keystroke at most; past it the wait is given up at once. */
const INPUT_REORDER_MAX_FRAMES = 64
const INPUT_REORDER_MAX_BYTES = 256 * 1024
const PAUSE_HIGH_WATERMARK_BYTES = 384 * 1024
const RESUME_LOW_WATERMARK_BYTES = 128 * 1024
const RENDER_STALL_TIMEOUT_MS = 10_000
const MAX_TOTAL_BUFFERED_BYTES = 2 * 1024 * 1024
/**
 * How long after a keyframe for an open or a resize an engine's print may still begin as live output: its clear then
 * never reaches the viewer, and another keyframe waits for the print (facets/launch.ts `ScreenContract.resizeRepaint`).
 * Codex's came 78-82 ms after an idle resize; at work, late enough to miss a 150 ms wait (a phone, 2026-10-13).
 */
const REPAINT_GUARD_MS = 1_500
const TERMINAL_ENGINES: ReadonlySet<string> = new Set(ENGINES)

interface PendingOutput {
  seq: number
  bytes: number
}

interface ActiveStream {
  connId: string
  /** A local view can share its upstream connection with other independent terminal owners. */
  ownerId: string
  /** What the client declared on open, or what `describeClient` could tell; absent when neither knew. */
  client?: TerminalClientDescriptor
  /** Opaque input provenance only. It does not affect the control lease. */
  inputContext?: string
  streamId: string
  /** A stream opened as a WATCHER: it renders, but it never took the control lease and its input is
   *  refused. See the `takeover: false` branch of `open()`. */
  watching: boolean
  /** A watcher by its own ask (`watch: true` on open): a client with no person in front of it — hn
   *  with no terminal — reading the pane. It holds nothing, so no other open is answered as if it did. */
  watchOnly: boolean
  agentId: string
  engineId: string
  placementKey: string
  handle: TerminalStreamHandle
  /** Which of the stream's subscriptions `handle` is: 0 for the one it opened with, then one more for each
   *  `retarget`. A sink answers only while it is the current one, so a pane left behind can neither write
   *  to the stream nor close it. `subscriptions` is the last one handed out. */
  subscription: number
  subscriptions: number
  /** The size the stream last asked its pane for (open, then each resize): a retarget opens the new pane at it. */
  size: TerminalStreamSize
  compression: 'none' | 'zlib'
  /** Whether this stream serves the desktop on this computer (see `TerminalStreamManagerDeps.isLoopback`). */
  loopback: boolean
  /** The output coalescing window: LOOPBACK_OUTPUT_FLUSH_MS for the window's focused terminal on this
   *  computer, OUTPUT_FLUSH_MS for everything else. Follows `setFocusedAgent`. */
  flushMs: number
  expiresAt: number
  lastSyncAt: number
  nextSeq: number
  lastInputSeq: number
  /** Keystrokes that came ahead of one still on its way, by their seq — see `input`. */
  heldInput: Map<number, Uint8Array>
  heldInputBytes: number
  heldInputTimer: ReturnType<typeof setTimeout> | null
  /** When the oldest keystroke still waiting began to wait (traced only). */
  heldSince: number
  /** The last keystroke written, until the first output after it goes out (traced only). */
  echoProbe: { seq: number; at: number } | null
  /** A wait was given up and the client told what was expected: nothing waits again until exactly that
   *  keystroke arrives, so a frame the client numbered under its old count never lands among its new ones. */
  inputHoldOff: boolean
  lastResizeSeq: number
  pending: PendingOutput[]
  pendingBytes: number
  output: Buffer[]
  outputBytes: number
  flushTimer: ReturnType<typeof setTimeout> | null
  lastFlushAt: number
  /** Until when live output is watched for the engine's print after a resize, and the end of the last chunk read,
   *  which the next may complete the clear in. See REPAINT_GUARD_MS. */
  repaintWatchUntil: number
  repaintTail: Buffer
  snapshotting: boolean
  resyncing: boolean
  closing: boolean
  outputPaused: boolean
  stallTimer: ReturnType<typeof setTimeout> | null
  openedAt: number
  outputFrames: number
  outputPlainBytes: number
  keyframes: number
  syncFrames: number
  resyncs: number
  peakBufferedBytes: number
  pausedAt: number | null
  pausedMs: number
  pendingUpload: PendingUpload | null
}

export interface TerminalStreamManagerDeps {
  /** An independent observer manager never acquires the owner control lease. */
  readOnly?: boolean
  /** A connection held to watching now, whatever it asks (core/api.ts RemoteAppPolicy `watchOnly`): the Mac owner's apps on a
   *  Harness Team daemon running a Swarm Product Manager (#895). Asked at each open and each frame, binary input included,
   *  so a stream opened before the hold began is held too. */
  watchOnly?: (connId: string) => boolean
  /** Whether [agentId]'s terminal is closed to [connId] now (core/api.ts RemoteAppPolicy): a session that turned confidential
   *  on a Harness Team daemon. Asked before anything more is sent on a stream, at each frame its client sends, and at open,
   *  so a stream opened before the mark closes (security review 2 of #2089). */
  closedTo?: (connId: string, agentId: string) => boolean
  terminals: TerminalBackendCoordinator
  resolveAgent: (agentId: string) => RegisteredSession | undefined
  sendTarget: (connId: string, type: string, payload: FramePayload) => boolean
  sendBinaryTarget: (connId: string, frame: TerminalBinaryClear) => boolean
  /** Whether this connection is the desktop app on THIS computer's loopback (never the cloud). */
  isLoopback?: (connId: string) => boolean
  /**
   * A name for a connection that declared none on `terminal_open` (an older client): the daemon's
   * own machine name for a loopback window, a paired peer's label when it is a real one. Null when
   * nothing better than "another app" is known.
   */
  describeClient?: (connId: string) => TerminalClientDescriptor | null
  streamingAvailable: boolean
  now?: () => number
  diagnostic?: (event: string, fields: Record<string, unknown>) => void
  /**
   * An agent's terminal just took input (a keystroke or a paste) from the stream that holds it — never
   * from a watcher, whose input is refused before it gets here. Called on every accepted frame, so it
   * must be cheap and must not throw; the daemon starts a sleeping grid from it (the keystroke prewarm,
   * grid-reads-without-waking issue 03), which is why it lives here, below every client that types. `typed`: the frame
   * holds what the person typed or pasted, not only what the terminal sends by itself (lib/typedInput.ts), which the
   * agent cleanup reads as the person joining a harness another agent started (services/agentCleanup.ts).
   * `from`: the stream's connection and what its client said it is on `terminal_open`, so a page a program in the
   * pane opens can go to the phone the person is typing on (core/terminals/browser.ts).
   */
  onInput?: (agentId: string, typed: boolean, from: { connId: string, kind: string | null; inputContext?: string; submitted?: boolean }) => void
  /** While an agent changes host, every write to its terminal waits here, and goes to the pane it ends on;
   *  its streams follow it through `retarget`. Absent: nothing is ever held. */
  moveGate?: MoveGate
  /** Set only while keystrokes are traced (`TYPING_TRACE`): one line per keystroke held, released, and echoed.
   *  Numbers and timings only, never the bytes. */
  typingTrace?: (line: string) => void
}

/** The row's primary pane, on whichever backend holds it (tmux or the PTY host). */
function primaryRuntimeOf(session: RegisteredSession): TerminalRuntimeRef | undefined {
  return session.runtimes.find((runtime) => terminalRouteKey(runtime) === session.primaryRuntimeKey) ?? session.runtimes[0]
}

/** [session] as the coordinator reads it, naming only [runtime]: the open path's own call, on that pane. */
function rowOn(session: RegisteredSession, runtime: TerminalRuntimeRef): RegisteredSession {
  return { ...session, runtimes: [runtime], primaryRuntimeKey: terminalRouteKey(runtime) }
}

function sizeFrom(payload: FramePayload): TerminalStreamSize | null {
  const cols = Number(payload.cols)
  const rows = Number(payload.rows)
  // Split TUI panes can be smaller than a desktop terminal. Preserve their actual size so
  // opening a third pane or shrinking the window does not reject the stream or crop its output.
  if (!Number.isSafeInteger(cols) || !Number.isSafeInteger(rows) || cols < 1 || cols > 300 || rows < 1 || rows > 120) return null
  return { cols, rows }
}

function encoded(bytes: Uint8Array, compression: 'none' | 'zlib'): { compressed: boolean; bytes: Uint8Array; plainBytes: number } {
  const raw = Buffer.from(bytes)
  if (compression === 'zlib' && raw.length > 1024) {
    const compressed = deflateSync(raw, { level: 1 })
    if (compressed.length < raw.length) return { compressed: true, bytes: compressed, plainBytes: raw.length }
  }
  return { compressed: false, bytes: raw, plainBytes: raw.length }
}

export function terminalEngineCapabilities(
  streamingAvailable: boolean,
  engines: readonly string[] = ENGINES,
): Array<{ id: string; terminalStreaming: boolean; unavailableReason?: string }> {
  return engines.map((id) => ({
    id,
    terminalStreaming: streamingAvailable,
    ...(!streamingAvailable ? { unavailableReason: 'tmux streaming backend unavailable' } : {}),
  }))
}

export class TerminalStreamManager {
  private readonly streams = new Map<string, ActiveStream>()
  private readonly controllerByAgent = new Map<string, string>()
  private readonly controllerByPlacement = new Map<string, string>()
  // Terminal opens from different backend connections can arrive concurrently. Serialize opens for
  // the same tmux placement so takeover is deterministic and never leaves two live controllers.
  private readonly leaseLocks = new Map<string, Promise<void>>()
  // The agent each loopback window last said it has focused (`app_focus`), null for none. A window that
  // never said is absent, and all its terminals keep the short window, as before focus was followed.
  private readonly focusByConn = new Map<string, string | null>()
  // The agents whose tiles each loopback window shows (`app_focus.visibleAgents`). A window that never
  // sent a list is absent, and counts as looking at everything it streams (older desktops).
  private readonly visibleByConn = new Map<string, ReadonlySet<string>>()
  private readonly now: () => number
  private readonly expiryTimer: ReturnType<typeof setInterval>
  private lastSweepAt: number

  constructor(private readonly deps: TerminalStreamManagerDeps) {
    this.now = deps.now ?? (() => Date.now())
    this.lastSweepAt = this.now()
    this.expiryTimer = setInterval(() => this.expireLeases(), EXPIRY_SWEEP_MS)
    this.expiryTimer.unref?.()
  }

  private async withLeaseLock<T>(key: string, operation: () => Promise<T>): Promise<T> {
    const previous = this.leaseLocks.get(key) ?? Promise.resolve()
    let release!: () => void
    const current = new Promise<void>((resolve) => { release = resolve })
    this.leaseLocks.set(key, current)
    await previous
    try {
      return await operation()
    } finally {
      release()
      if (this.leaseLocks.get(key) === current) this.leaseLocks.delete(key)
    }
  }

  /** The frames a stream that does not hold the terminal may still send: they read, ack or end it. */
  private static readonly WATCH_SAFE_TYPES = [
    'terminal_capabilities', 'terminal_open', 'terminal_alive', 'terminal_ack', 'terminal_resync', 'terminal_close',
  ]

  /** Whether this frame names a WATCHER's stream — one that renders without holding the terminal. */
  private isWatching(connId: string, payload: FramePayload): boolean {
    const streamId = typeof payload.streamId === 'string' ? payload.streamId : ''
    if (!streamId) return false
    const state = this.streams.get(streamId)
    return state?.connId === connId && state.watching
  }

  /** Closes [state] when its session is closed to its client now (`closedTo`), and says whether it did. */
  private closedNow(state: ActiveStream): boolean {
    if (state.closing) return true
    if (!this.deps.closedTo?.(state.connId, state.agentId)) return false
    void this.closeStream(state, 'session became confidential', true, 'SWARM_CONFIDENTIAL')
    return true
  }

  async handleFrame(connId: string, type: string, payload: FramePayload): Promise<boolean> {
    const named = typeof payload.streamId === 'string' ? this.streams.get(payload.streamId) : undefined
    if (named && named.connId === connId && this.closedNow(named)) return true
    if (this.deps.readOnly && !TerminalStreamManager.WATCH_SAFE_TYPES.includes(type)) {
      this.sendError(connId, 'VIEW_ONLY', { requestId: payload.requestId })
      return true
    }
    // ⚠️ **One gate, not one per write path.** A watcher shares every other code path with a real
    // controller, so anything that reaches tmux — input, resize, paste, scroll, an upload — has to
    // be stopped, and stopping them one by one is how the next write path added gets forgotten.
    // Same allow-list a read-only deployment uses, for the same reason.
    if (!TerminalStreamManager.WATCH_SAFE_TYPES.includes(type) && (this.isWatching(connId, payload) || this.deps.watchOnly?.(connId) === true)) {
      this.sendError(connId, 'VIEW_ONLY', {
        requestId: payload.requestId,
        streamId: typeof payload.streamId === 'string' ? payload.streamId : undefined,
      })
      return true
    }
    switch (type) {
      case 'terminal_capabilities':
        this.capabilities(connId, payload.requestId)
        return true
      case 'terminal_open':
        await this.open(connId, payload)
        return true
      case 'terminal_alive':
        this.alive(connId, payload)
        return true
      case 'terminal_ack':
        this.ack(connId, payload)
        return true
      case 'terminal_input':
        this.sendError(connId, 'TERMINAL_BINARY_REQUIRED', { streamId: typeof payload.streamId === 'string' ? payload.streamId : undefined })
        return true
      case 'terminal_resize':
        await this.resize(connId, payload)
        return true
      case 'terminal_paste':
      case 'terminal_paste_image':
      case 'terminal_paste_file':
        // Same reason as terminal_input: a paste is a binary frame (TerminalBinaryKind.paste /
        // .imagePaste / .pasteFile) so it rides the same AEAD channel every other terminal byte
        // does, which is what makes it safe to deliver over a relayed (E2EE) connection. Nothing
        // sends this as JSON.
        this.sendError(connId, 'TERMINAL_BINARY_REQUIRED', { streamId: typeof payload.streamId === 'string' ? payload.streamId : undefined })
        return true
      case 'terminal_chunked_upload_begin':
        this.beginChunkedUpload(connId, payload)
        return true
      case 'terminal_chunked_upload_cancel':
        this.cancelChunkedUpload(connId, payload)
        return true
      case 'terminal_scroll':
        await this.scroll(connId, payload)
        return true
      case 'terminal_resync':
        await this.resyncRequested(connId, payload)
        return true
      case 'terminal_close':
        await this.closeRequested(connId, payload)
        return true
      default:
        return false
    }
  }

  async handleBinary(connId: string, frame: TerminalBinaryClear): Promise<void> {
    if (this.deps.readOnly) return
    // Every binary kind below writes to the terminal, so a watcher's are dropped outright — see the
    // gate in `handleFrame`. Silent, like the other drops here: the client already knows it is
    // read-only (`terminal_ready`) and withholds input itself; this is the backstop.
    if (this.isWatching(connId, { streamId: frame.streamId }) || this.deps.watchOnly?.(connId) === true) return
    if (frame.kind !== TerminalBinaryKind.input && frame.kind !== TerminalBinaryKind.paste
      && frame.kind !== TerminalBinaryKind.imagePaste && frame.kind !== TerminalBinaryKind.pasteFile) return
    const state = this.streams.get(frame.streamId)
    if (!state || state.connId !== connId || this.closedNow(state)) return
    if (frame.kind === TerminalBinaryKind.imagePaste || frame.kind === TerminalBinaryKind.pasteFile) {
      await this.receiveUploadChunk(state, frame.kind, frame.seq, frame.bytes)
      return
    }
    if (frame.kind === TerminalBinaryKind.paste) {
      // A paste carries no number to wait in line by: it must not go ahead of keystrokes typed before it, so
      // any still waiting for a missing one are given up first, as they were before anything waited.
      if (state.heldInput.size > 0) this.giveUpHeldInput(state)
      await this.paste(state, frame.bytes)
      return
    }
    await this.input(state, frame.seq, frame.bytes)
  }

  private capabilities(connId: string, requestId: unknown): void {
    this.deps.sendTarget(connId, 'terminal_capabilities_result', {
      requestId,
      protocolVersion: PROTOCOL_VERSION,
      backend: 'tmux',
      available: this.deps.streamingAvailable,
      features: {
        rawInput: !this.deps.readOnly,
        resize: !this.deps.readOnly,
        mouse: !this.deps.readOnly,
        keyframe: true,
        sync: true,
        compression: ['none', 'zlib'],
        // A client old enough to predate `terminal_paste` must keep sending a direct terminal paste
        // through `terminal_input` — checked here rather than assumed, so it degrades instead of
        // silently going nowhere against a CLI that doesn't recognize the newer frame type.
        pasteRaw: !this.deps.readOnly,
        // A client old enough to predate `TerminalBinaryKind.imagePaste` must keep forwarding a bare
        // Ctrl+V and hoping the engine's own clipboard read finds something local — see
        // `pasteImage()` for the frame this unlocks.
        imagePaste: !this.deps.readOnly,
        // A client old enough to predate `TerminalBinaryKind.pasteFile` has no way to hand a
        // dropped non-image file to a REMOTE pane at all (a local pane needs no capability — it
        // pastes the file's own path directly, never touching the wire) — see `pasteFile()`.
        pasteFile: !this.deps.readOnly,
        // Bounded media reads through the already encrypted agent_read_file RPC.
        mediaPreview: !this.deps.readOnly,
        // `agent_create` understands `projectSource` — a folder this machine makes or clones for
        // itself — rather than only a `cwd` the client already knows. A client old enough to
        // predate `lib/projectFolder.ts` never sends it, and one NEWER than the machine has no way
        // to tell without this: the keys are simply ignored, `cwd` comes up missing, and the
        // refusal arrives as INVALID_CWD — "the project folder is unavailable", about a folder
        // nobody named. Advertised here, beside the other "what this CLI can do" answers, even
        // though creating an agent is not terminal streaming; this is the message a client already
        // asks every machine.
        projectFolder: !this.deps.readOnly,
        // `terminal_open` honours `takeover: false`: never close the incumbent. A terminal nobody
        // else holds opens as usual; one another client is driving opens READ-ONLY, so the asking
        // client renders it without taking it (`readOnly` on `terminal_ready`) — see `open()`. A
        // client has to see this before relying on it: a CLI that predates it ignores the key and
        // takes the terminal over like any other open, which is the one thing the key is for.
        noTakeover: !this.deps.readOnly,
        // `terminal_open` honours `watch: true`: always a watcher, even of a terminal nobody holds,
        // and never counted as holding it when another client opens politely. See `open()`.
        watchOnly: !this.deps.readOnly,
      },
      engines: terminalEngineCapabilities(this.deps.streamingAvailable),
    })
  }

  private sendError(
    connId: string,
    code: string,
    options: { streamId?: string; requestId?: unknown; message?: string; reason?: 'seq' | 'size' | 'empty'; expectedSeq?: number } = {},
  ): void {
    this.deps.sendTarget(connId, 'terminal_error', {
      protocolVersion: PROTOCOL_VERSION,
      code,
      ...options,
    })
  }

  private async open(connId: string, payload: FramePayload): Promise<void> {
    const requestId = payload.requestId
    if (payload.protocolVersion !== PROTOCOL_VERSION) {
      this.sendError(connId, 'TERMINAL_PROTOCOL_UNSUPPORTED', { requestId })
      return
    }
    const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
    const size = sizeFrom(payload)
    if (!agentId || !size) {
      this.sendError(connId, 'TERMINAL_OPEN_INVALID', { requestId })
      return
    }
    if (this.deps.closedTo?.(connId, agentId)) {
      this.sendError(connId, 'SWARM_CONFIDENTIAL', { requestId })
      return
    }
    if (!this.deps.streamingAvailable) {
      this.sendError(connId, 'TERMINAL_RUNTIME_UNAVAILABLE', { requestId })
      return
    }
    const session = this.deps.resolveAgent(agentId)
    if (!session) {
      this.sendError(connId, 'TERMINAL_AGENT_NOT_FOUND', { requestId })
      return
    }
    // An agent changing host is opened at once, on the pane its row names now (the old one is kept until its
    // streams are retargeted): waiting here would hold every later frame of this connection. The open counts
    // as someone using the agent.
    this.deps.moveGate?.touch(session.agentId)
    if (!TERMINAL_ENGINES.has(session.engine)) {
      this.sendError(connId, 'TERMINAL_ENGINE_UNSUPPORTED', { requestId })
      return
    }
    // The agent's primary pane: the coordinator opens the stream through the backend that holds it.
    const streamRuntime = primaryRuntimeOf(session)
    if (!streamRuntime) {
      this.sendError(connId, 'TERMINAL_RUNTIME_UNAVAILABLE', { requestId })
      return
    }
    const reservedPlacement = terminalPlacementKey(streamRuntime)
    // `takeover: false` is a client opening a terminal AHEAD of anyone looking at it — the phone's
    // pager attaching the agents a swipe away from the one on screen. That is a guess, and a guess
    // must not cost another client the terminal it is working in: refused while anyone else holds
    // it, and the client asks again, without the key, once a person actually lands there. Absent
    // (every older client) is the takeover it has always been.
    const takeover = payload.takeover !== false
    // `watch: true` is a client nobody sits at — hn with no terminal, holding the sessions a closed
    // window left — reading a pane for the commands it answers. It never takes the terminal, nor its
    // size: before this it opened like any other on every reconnect, and when it came first after a
    // daemon restart the agent was resized to its 80x24 layout and the window the person was looking
    // at could only watch until they typed (2026-10-14). A daemon that predates the key ignores it.
    const watchOnly = payload.watch === true
    // Older clients have one owner per connection. A pooled relay supplies a stable identity
    // for each attached view; this partitions leases, not authentication or stream access.
    const viewId = typeof payload.viewId === 'string' && payload.viewId.length > 0 && payload.viewId.length <= 128
      ? payload.viewId : null
    const ownerId = JSON.stringify([connId, viewId])
    // The fallback is read as strictly as a claim: a machine name the backend handed out is not
    // this module's to trust with the wire shape either.
    const client = clientDescriptorFrom(payload.client) ?? clientDescriptorFrom(this.deps.describeClient?.(connId))
    await this.withLeaseLock(reservedPlacement, async () => {
      const incumbents = this.incumbentsFor(session.agentId, reservedPlacement, ownerId)
      // Inside the lock, so the answer cannot go stale against an open racing this one for the
      // same placement.
      //
      // ⚠️ **Refusing would have been the wrong answer.** A client that asks not to take over still
      // wants to SEE the terminal — the phone swiping onto an agent the desktop is driving shows
      // its output, and only typing is withheld until a person asks for it. So the open succeeds as
      // a WATCHER: tmux attaches read-only (no control lease, no resize, no input), the incumbent
      // keeps the terminal, and the client is told which it got by `readOnly` on `terminal_ready`.
      //
      // A watch-only stream is not anyone holding it: a window reconnecting politely beside one is
      // answered as it would be alone, not made to watch a terminal nobody drives.
      const holders = incumbents.filter((state) => !state.watchOnly)
      const watching = !this.deps.readOnly && (watchOnly || this.deps.watchOnly?.(connId) === true || (!takeover && holders.length > 0))
      // Who a watcher is watching, named on its banner — "MacBook Pro is using this terminal" — as
      // `takenBy` names the winner on the incumbent's. Read now, before any stream below moves.
      const heldBy = watching ? this.holderOf(holders, reservedPlacement) : undefined
      // A terminal is single-controller. A later client explicitly wins the lease and the incumbent
      // receives a targeted close notification; it must not be broadcast to other clients. The
      // notification names the winner when it can (`takenBy`), so the incumbent's banner can too.
      if (!this.deps.readOnly && !watching) {
        await this.closeStreamsForTakeover(session.agentId, reservedPlacement, ownerId, client)
      }
      // Only THIS view's stream for THIS terminal, not every stream the connection holds.
      //
      // It used to be closeConnection(connId), i.e. "opening a terminal ends every other terminal
      // this client had". That was invisible while a client could only ever show one terminal at a
      // time. A client showing several — the desktop app's pane grid — opens a second agent on the
      // same connection, and the blanket close killed the FIRST agent's stream a few milliseconds
      // after handing it its opening keyframe. The pane kept rendering that stale keyframe and
      // looked alive, but its session never reached `controlling`, so every keystroke into it was
      // dropped in silence.
      await this.closeOwnStreamsFor(ownerId, session.agentId, reservedPlacement)
      // A watcher never becomes the controller — that is the whole point of it.
      if (!this.deps.readOnly && !watching) this.controllerByAgent.set(session.agentId, ownerId)
      if (!this.deps.readOnly && !watching) this.controllerByPlacement.set(reservedPlacement, ownerId)
      const streamId = randomUUID()
      const buffered: Buffer[] = []
      let state: ActiveStream | null = null
      let opened: Awaited<ReturnType<TerminalBackendCoordinator['openStream']>>
      try {
        opened = await this.deps.terminals.openStream(session, size, {
          // Subscription 0: once a retarget has moved the stream to another pane, this one is ignored.
          onData: (bytes) => {
            if (!state) buffered.push(Buffer.from(bytes))
            else if (state.subscription === 0) this.onOutput(state, bytes)
          },
          onClose: (reason) => {
            if (state?.subscription === 0) void this.closeStream(state, reason, true)
          },
        }, this.deps.readOnly || watching)
      } catch {
        if (this.controllerByAgent.get(session.agentId) === ownerId) this.controllerByAgent.delete(session.agentId)
        if (this.controllerByPlacement.get(reservedPlacement) === ownerId) this.controllerByPlacement.delete(reservedPlacement)
        this.sendError(connId, 'TERMINAL_OPEN_FAILED', { requestId })
        return
      }
      if (opened.state !== 'succeeded') {
        if (this.controllerByAgent.get(session.agentId) === ownerId) this.controllerByAgent.delete(session.agentId)
        if (this.controllerByPlacement.get(reservedPlacement) === ownerId) this.controllerByPlacement.delete(reservedPlacement)
        this.sendError(connId, opened.reason, { requestId })
        return
      }

      const placementKey = terminalPlacementKey(opened.value.runtime)
      const actualController = this.controllerByPlacement.get(placementKey)
      if (!this.deps.readOnly && !watching && actualController && actualController !== ownerId) {
        if (this.controllerByAgent.get(session.agentId) === ownerId) this.controllerByAgent.delete(session.agentId)
        if (this.controllerByPlacement.get(reservedPlacement) === ownerId) this.controllerByPlacement.delete(reservedPlacement)
        await opened.value.close().catch(() => { /* best effort */ })
        this.sendError(connId, 'CONTROL_LEASE_HELD', { requestId })
        return
      }
      if (reservedPlacement !== placementKey && this.controllerByPlacement.get(reservedPlacement) === ownerId) {
        this.controllerByPlacement.delete(reservedPlacement)
      }
      if (!this.deps.readOnly && !watching) this.controllerByPlacement.set(placementKey, ownerId)

      const requestedCompression = Array.isArray(payload.compression) ? payload.compression : []
      // Never compress for the loopback desktop, whatever it asks for: the bytes cross 127.0.0.1,
      // and the deflate here plus the inflate on the app's UI thread were a per-frame tax paid on
      // every TUI redraw for nothing. Decided here rather than in the app because the app cannot
      // tell this daemon's own machine from one it reaches through the relay — where the same
      // frames DO cross the internet and zlib still earns its keep.
      const loopback = this.deps.isLoopback?.(connId) ?? false
      const wantsZlib = requestedCompression.includes('zlib') && !loopback
      state = {
        connId,
        ownerId,
        ...(client ? { client } : {}),
        ...(inputContextIn(payload.inputContext) ? { inputContext: payload.inputContext as string } : {}),
        streamId,
        watching,
        watchOnly: watching && watchOnly,
        agentId: session.agentId,
        engineId: session.engine,
        placementKey,
        handle: opened.value,
        subscription: 0,
        subscriptions: 0,
        size,
        compression: wantsZlib ? 'zlib' : 'none',
        loopback,
        flushMs: this.flushWindow(connId, session.agentId, loopback),
        expiresAt: this.now() + HEARTBEAT_TIMEOUT_MS,
        lastSyncAt: this.now(),
        nextSeq: 0,
        lastInputSeq: -1,
        heldInput: new Map(),
        heldInputBytes: 0,
        heldInputTimer: null,
        heldSince: 0,
        echoProbe: null,
        inputHoldOff: false,
        lastResizeSeq: -1,
        pending: [],
        pendingBytes: 0,
        output: buffered,
        outputBytes: buffered.reduce((sum, chunk) => sum + chunk.length, 0),
        flushTimer: null,
        lastFlushAt: 0,
        repaintWatchUntil: 0,
        repaintTail: Buffer.alloc(0),
        snapshotting: false,
        resyncing: false,
        closing: false,
        outputPaused: false,
        stallTimer: null,
        openedAt: this.now(),
        outputFrames: 0,
        outputPlainBytes: 0,
        keyframes: 0,
        syncFrames: 0,
        resyncs: 0,
        peakBufferedBytes: 0,
        pausedAt: null,
        pausedMs: 0,
        pendingUpload: null,
      }
      this.streams.set(streamId, state)
      if (!this.deps.sendTarget(connId, 'terminal_ready', {
        requestId,
        protocolVersion: PROTOCOL_VERSION,
        streamId,
        agentId: session.agentId,
        engineId: session.engine,
        backend: 'tmux',
        // True for a watcher too: the client draws output and withholds input, exactly as it does
        // for an observer's stream. See the `takeover: false` branch above.
        readOnly: this.deps.readOnly === true || watching,
        ...(heldBy ? { heldBy } : {}),
      })) {
        await this.closeStream(state, 'backend disconnected', false)
        return
      }
      // Whether it holds the terminal: who resized an agent is read from here.
      this.diagnostic(state, 'opened', { cols: size.cols, rows: size.rows, compression: state.compression, watching, ...(watchOnly ? { watchOnly } : {}) })
      await this.sendKeyframe(state, 'open')
      // A move that swapped the row's pane while this open was in flight retargeted the streams it found, and
      // this one may not have been among them: it follows on its own.
      if (this.deps.moveGate) await this.followRow(state, streamRuntime)
    })
  }

  /** Retarget [state] to its row's primary pane when that is no longer [openedOn]. */
  private async followRow(state: ActiveStream, openedOn: TerminalRuntimeRef): Promise<void> {
    const row = this.deps.resolveAgent(state.agentId)
    const current = row ? primaryRuntimeOf(row) : undefined
    if (state.closing || !row || !current || terminalRouteKey(current) === terminalRouteKey(openedOn)) return
    await this.retargetStream(state, rowOn(row, current))
  }

  private streamFor(connId: string, payload: FramePayload): ActiveStream | null {
    const streamId = typeof payload.streamId === 'string' ? payload.streamId : ''
    const state = this.streams.get(streamId)
    return state?.connId === connId && !state.closing ? state : null
  }

  /** Existence/ownership check for connId+streamId — used by BackendSocket to validate a p2p-arrived
   *  terminal_resync (a live-migration promotion signal, not an actual resync request) actually names a
   *  live stream owned by this connection before trusting it, instead of leaking a routing entry for a
   *  stale/bogus streamId (e.g. the pane closed in the same instant the migration barrier was in flight). */
  hasStream(connId: string, streamId: string): boolean {
    const state = this.streams.get(streamId)
    return !!state && state.connId === connId && !state.closing
  }

  private alive(connId: string, payload: FramePayload): void {
    const state = this.streamFor(connId, payload)
    if (!state) { this.reportMissing(connId, payload); return }
    state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
  }

  /**
   * Tell a client that asked (`reportMissing`) that the stream it names is gone. A host that lost its
   * backend link closes its remote streams without notice, and the client used to learn it only after
   * 15 s of silence and three resyncs this manager ignored, then gave up on the pane (2026-10-16). Opt-in,
   * so an older client keeps the silence its own recovery was built around.
   */
  private reportMissing(connId: string, payload: FramePayload): void {
    if (payload.reportMissing !== true || typeof payload.streamId !== 'string') return
    this.sendError(connId, 'TERMINAL_STREAM_NOT_FOUND', { streamId: payload.streamId, message: 'no live terminal stream' })
  }

  private ack(connId: string, payload: FramePayload): void {
    const state = this.streamFor(connId, payload)
    if (!state) return
    const lastSeq = Number(payload.lastSeq)
    if (!Number.isSafeInteger(lastSeq) || lastSeq < -1 || lastSeq >= state.nextSeq) return
    let progressed = false
    while (state.pending.length && state.pending[0].seq <= lastSeq) {
      state.pendingBytes -= state.pending.shift()!.bytes
      progressed = true
    }
    if (!progressed) return
    if (state.outputPaused && state.pendingBytes < RESUME_LOW_WATERMARK_BYTES) void this.resumeOutput(state)
    else if (state.outputPaused) this.armStallTimer(state)
  }

  /**
   * One keystroke frame, written in its client's order. The next one expected is written at once, and with it any
   * that came ahead of it and waited. One that comes ahead waits for the missing one (INPUT_REORDER_WAIT_MS), bounded
   * by INPUT_REORDER_MAX_FRAMES/BYTES; when it does not come, everything waiting goes and the client is told, once,
   * what was expected. Anything else — a number already used, a frame that is malformed — is refused at once, and
   * what waited goes with it ([refuseInput]).
   */
  private async input(state: ActiveStream, inputSeq: number, bytes: Uint8Array): Promise<void> {
    // A seq that is not a safe integer at all is an ordering fault too, as far as the client is concerned.
    const malformed = !Number.isSafeInteger(inputSeq) ? 'seq' : bytes.length === 0 ? 'empty' : bytes.length > INPUT_MAX_BYTES ? 'size' : null
    if (malformed) { this.refuseInput(state, malformed, inputSeq, bytes.length); return }
    const expectedSeq = state.lastInputSeq + 1
    if (inputSeq === expectedSeq) {
      state.inputHoldOff = false
      this.writeInput(state, inputSeq, bytes)
      this.releaseHeldInput(state)
      return
    }
    // A second frame under a number already waiting: the first one stands, and nothing is said about it.
    if (inputSeq > expectedSeq && state.heldInput.has(inputSeq)) return
    if (inputSeq > expectedSeq && !state.inputHoldOff) {
      if (state.heldInput.size < INPUT_REORDER_MAX_FRAMES && state.heldInputBytes + bytes.length <= INPUT_REORDER_MAX_BYTES) {
        if (state.heldInput.size === 0) state.heldSince = this.now()
        this.deps.typingTrace?.(`stream=${state.streamId.slice(0, 8)} seq=${inputSeq} held: ${expectedSeq} has not come (${state.heldInput.size + 1} waiting)`)
        state.heldInput.set(inputSeq, bytes)
        state.heldInputBytes += bytes.length
        state.heldInputTimer ??= setTimeout(() => this.giveUpHeldInput(state), INPUT_REORDER_WAIT_MS)
        return
      }
      this.giveUpHeldInput(state)
      return
    }
    this.refuseInput(state, 'seq', inputSeq, bytes.length)
  }

  /**
   * Nothing here reached the pty, and `lastInputSeq` is deliberately left where it was. Say what WOULD have been
   * accepted: a client whose counter has drifted (a frame it dropped on its own side while resyncing, say) can
   * realign on `expectedSeq` and carry on, instead of having every later keystroke refused too and treating a fine
   * stream as a dead one.
   */
  private refuseInput(state: ActiveStream, reason: 'seq' | 'empty' | 'size', inputSeq: number, size: number): void {
    // The client numbers what it types next from `expectedSeq`, so keystrokes still held under its old numbering
    // would land among the new ones: they go, and until the expected one arrives nothing more waits. An oversized
    // frame refused with a later one held used to release that one after the client's realigned keys (review,
    // 2026-10-19).
    this.dropHeldInput(state)
    state.inputHoldOff = true
    const expectedSeq = state.lastInputSeq + 1
    this.sendError(state.connId, 'TERMINAL_INPUT_INVALID', {
      streamId: state.streamId,
      reason,
      expectedSeq,
      message: reason === 'seq'
        ? `input seq ${inputSeq} arrived, ${expectedSeq} expected`
        : reason === 'size' ? `input frame of ${size} bytes exceeds ${INPUT_MAX_BYTES}` : 'empty input frame',
    })
  }

  /** The keystrokes that waited for the one just written, as far as they now run on unbroken. */
  private releaseHeldInput(state: ActiveStream): void {
    if (state.heldInput.size === 0) return
    const from = state.lastInputSeq + 1
    for (let next = from, bytes = state.heldInput.get(next); bytes; next++, bytes = state.heldInput.get(next)) {
      state.heldInput.delete(next)
      state.heldInputBytes -= bytes.length
      this.writeInput(state, next, bytes)
    }
    if (state.lastInputSeq >= from) {
      this.deps.typingTrace?.(`stream=${state.streamId.slice(0, 8)} seq=${from}..${state.lastInputSeq} released after ${Math.round(this.now() - state.heldSince)}ms`)
      state.heldSince = this.now()
    }
    if (state.heldInputTimer) clearTimeout(state.heldInputTimer)
    // Another gap behind this one gets a full wait of its own.
    state.heldInputTimer = state.heldInput.size > 0 ? setTimeout(() => this.giveUpHeldInput(state), INPUT_REORDER_WAIT_MS) : null
  }

  /** The missing keystroke did not come: what waited for it goes, and the client hears once what is expected. */
  private giveUpHeldInput(state: ActiveStream): void {
    const waited = [...state.heldInput.keys()]
    this.dropHeldInput(state)
    if (state.closing || this.streams.get(state.streamId) !== state) return
    this.diagnostic(state, 'input_gap_given_up', { expectedSeq: state.lastInputSeq + 1, dropped: waited.length })
    this.refuseInput(state, 'seq', waited.length > 0 ? Math.min(...waited) : state.lastInputSeq + 1, 0)
  }

  private dropHeldInput(state: ActiveStream): void {
    if (state.heldInputTimer) clearTimeout(state.heldInputTimer)
    state.heldInputTimer = null
    state.heldInput.clear()
    state.heldInputBytes = 0
  }

  private writeInput(state: ActiveStream, inputSeq: number, bytes: Uint8Array): void {
    state.lastInputSeq = inputSeq
    if (this.deps.typingTrace) state.echoProbe = { seq: inputSeq, at: this.now() }
    state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
    this.tookInput(state, typedByPerson(bytes), nativeSubmitKey(bytes))
    // The agent is changing host: the pane this stream writes to is going away. The keystrokes wait, in order
    // with every other write to the agent, and are written once the move ends. The seq is spent either way.
    const gate = this.heldGate(state)
    if (gate) {
      const held = Uint8Array.from(bytes)
      gate.enqueue(state.agentId, () => this.reportInput(state, this.writeRawTo(state, held, true)))
      return
    }
    // Not awaited. `writeRaw` hands its `send-keys` to the control client's FIFO synchronously, so
    // keystroke order is already fixed by the time it returns its promise — and the seq above is
    // spent, so the next frame cannot race this one. Awaiting the reply held the whole local
    // socket (localWsServer.ts serialises every message behind this call) for one tmux round-trip
    // per keystroke; now the round-trips overlap, which is what ControlCommandQueue pipelines for.
    // The result still matters, only later: a failure is reported when tmux says so.
    void this.reportInput(state, state.handle.writeRaw(bytes))
  }

  /** A keystroke write's outcome, told to the client when it failed. */
  private reportInput(state: ActiveStream, write: Promise<TerminalActionResult>): Promise<void> {
    return write.then(
      (result) => {
        if (state.closing || result.state === 'succeeded') return
        this.sendError(state.connId, 'TERMINAL_INPUT_FAILED', { streamId: state.streamId, message: result.reason })
        if (result.dispatch === 'possibly_executed') void this.sendKeyframe(state, 'input')
      },
      (error: unknown) => {
        if (state.closing) return
        this.sendError(state.connId, 'TERMINAL_INPUT_FAILED', {
          streamId: state.streamId,
          message: error instanceof Error ? error.message : String(error),
        })
      },
    ).catch((error: unknown) => {
      // Nothing above is awaited by anyone, so a throw from the reporting itself would otherwise
      // surface only as a process-level unhandledRejection.
      this.diagnostic(state, 'input_report_failed', { reason: error instanceof Error ? error.message : String(error) })
    })
  }

  /** The gate, when [state]'s agent is changing host: then every write from the stream waits on it. */
  private heldGate(state: ActiveStream): MoveGate | null {
    const gate = this.deps.moveGate
    return gate?.holding(state.agentId) ? gate : null
  }

  /**
   * Raw bytes into [state]'s pane: the stream's own pane, retargeted to the row's by the time held input is
   * delivered. [held] input whose stream closed during the move goes to the row's pane through its backend:
   * the stream is gone, and the input is still the person's.
   */
  private writeRawTo(state: ActiveStream, bytes: Uint8Array, held = false): Promise<TerminalActionResult> {
    if (!held || !state.closing) return state.handle.writeRaw(bytes)
    return this.writeToRow(state, (backend, runtime) => backend.writeInput?.(runtime, bytes))
  }

  /** A paste into [state]'s pane, as `writeRawTo` writes raw bytes. */
  private pasteRawTo(state: ActiveStream, text: string, held = false): Promise<TerminalActionResult> {
    // Asked again as it lands (main's guard): a paste takes two tmux processes, and its stream may close meanwhile.
    if (!held || !state.closing) return state.handle.pasteRaw(text, () => !state.closing)
    return this.writeToRow(state, (backend, runtime) => backend.pasteInput?.(runtime, text))
  }

  private async writeToRow(
    state: ActiveStream,
    write: (backend: TerminalBackend, runtime: TerminalRuntimeRef) => Promise<TerminalActionResult> | undefined,
  ): Promise<TerminalActionResult> {
    const row = this.deps.resolveAgent(state.agentId)
    const runtime = row ? primaryRuntimeOf(row) : undefined
    const backend = runtime ? this.deps.terminals.backendFor(runtime) : undefined
    const result = runtime && backend ? write(backend, runtime) : undefined
    return result ?? terminalActionNotStarted('the agent has no pane to write to')
  }

  /** See `TerminalStreamManagerDeps.onInput`. A listener's failure is its own: input is never held by it. */
  private tookInput(state: ActiveStream, typed: boolean, submitted = false): void {
    try { this.deps.onInput?.(state.agentId, typed, { connId: state.connId, kind: state.client?.kind ?? null,
      ...(state.inputContext ? { inputContext: state.inputContext } : {}), ...(submitted ? { submitted: true } : {}) }) } catch (error) {
      this.diagnostic(state, 'input_listener_failed', { reason: error instanceof Error ? error.message : String(error) })
    }
  }

  private async resize(connId: string, payload: FramePayload): Promise<void> {
    const state = this.streamFor(connId, payload)
    if (!state) return
    const resizeSeq = Number(payload.resizeSeq)
    const size = sizeFrom(payload)
    if (!Number.isSafeInteger(resizeSeq) || resizeSeq <= state.lastResizeSeq || !size) return
    state.lastResizeSeq = resizeSeq
    state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
    // The size the client asked for, kept even when this pane refuses it: a retarget opens the new pane at it.
    state.size = size
    const result = await state.handle.resize(size)
    if (result.state !== 'succeeded') {
      this.sendError(connId, 'TERMINAL_RESIZE_FAILED', { streamId: state.streamId, message: result.reason })
      return
    }
    await this.sendKeyframe(state, 'resize')
  }

  /**
   * A clipboard paste made directly into the terminal (not the composer), delivered whole as a
   * `TerminalBinaryKind.paste` frame via `TerminalStreamHandle.pasteRaw` instead of the chunked
   * `writeRaw`/`send-keys -H` keystroke path — see `pasteRawIntoTmux` for why the two cannot share a
   * pipe. Binary, not JSON: this is what lets a paste travel over a relayed (E2EE) connection safely
   * — it rides the same AEAD-wrapped channel `input`/`output` already do, with no allowlist of its
   * own to keep in step with the pairwise-crypto "interop keystone" (e2ee/core.ts) three other
   * codebases also implement.
   *
   * No seq/ordering guard, unlike `input()`: a paste is one self-contained unit, not part of an
   * ordered keystroke stream. Size is already bounded by the wire format itself
   * (TERMINAL_*_PASTE_MAX_*_BYTES in terminalBinary.ts) — anything over that never decodes into a
   * frame at all, so there is nothing left to check here.
   */
  private async paste(state: ActiveStream, bytes: Uint8Array): Promise<void> {
    if (bytes.length === 0) return
    let text: string
    try {
      text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
    } catch {
      this.sendError(state.connId, 'TERMINAL_PASTE_INVALID', { streamId: state.streamId, message: 'paste was not valid UTF-8' })
      return
    }
    state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
    this.tookInput(state, true)
    // Held while the agent changes host, in order with its keystrokes (see `input`).
    const gate = this.heldGate(state)
    if (gate) {
      gate.enqueue(state.agentId, () => this.deliverPaste(state, text, true))
      return
    }
    await this.deliverPaste(state, text)
  }

  private async deliverPaste(state: ActiveStream, text: string, held = false): Promise<void> {
    const result = await this.pasteRawTo(state, text, held)
    if (state.closing) return
    if (result.state !== 'succeeded') {
      this.sendError(state.connId, 'TERMINAL_PASTE_FAILED', { streamId: state.streamId, message: result.reason })
      if (result.dispatch === 'possibly_executed') await this.sendKeyframe(state, 'input')
    }
  }

  /**
   * A clipboard IMAGE paste (raw PNG bytes, already fully assembled from a chunked upload — see
   * `receiveUploadChunk`) — writes the bytes into THIS machine's own OS clipboard (see
   * osClipboard.ts), then replays a literal Ctrl+V so whichever engine is attached to the pane
   * reads that clipboard exactly as it already does for a locally-driven session. Nothing here is
   * engine-specific: this only bridges the clipboard and the keystroke, the same way `paste()`
   * only bridges a clipboard string into the pty.
   *
   * When no native clipboard is reachable right now (the clipboard tool isn't installed, or this
   * is a genuinely headless Linux box with no X11/Wayland session at all), this does not fail —
   * it falls back to pasting the image's file PATH as plain text through the exact same
   * `pasteRaw` call `paste()` uses, so the user/engine can still get at the image, just not via
   * the OS clipboard. The client is told which happened (`terminal_paste_image_result`) so it can
   * show the right feedback instead of a silent difference in behavior.
   */
  private async pasteImage(state: ActiveStream, bytes: Uint8Array, held = false): Promise<void> {
    if (bytes.length === 0) return
    state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
    let path: string
    try {
      path = await writePasteImageFile(bytes)
    } catch (error) {
      this.sendError(state.connId, 'TERMINAL_PASTE_IMAGE_FAILED', {
        streamId: state.streamId,
        message: error instanceof Error ? error.message : 'could not save the pasted image',
      })
      return
    }
    const clipboard = await writeImageToOsClipboard(path, bytes)
    if (clipboard.state === 'written') {
      // The OS clipboard now owns the bytes — the file was only a hand-off.
      void unlink(path).catch(() => { /* best effort */ })
      const result = await this.writeRawTo(state, CTRL_V_BYTE, held)
      if (result.state !== 'succeeded') {
        this.sendError(state.connId, 'TERMINAL_PASTE_IMAGE_FAILED', { streamId: state.streamId, message: result.reason })
        if (result.dispatch === 'possibly_executed') await this.sendKeyframe(state, 'input')
        return
      }
      this.deps.sendTarget(state.connId, 'terminal_paste_image_result', {
        streamId: state.streamId,
        outcome: 'clipboard',
      })
      return
    }
    // 'failed' and 'unavailable' get the same treatment: whether the clipboard tool is missing
    // entirely or was found but couldn't actually reach a display (the exact case a Docker test rig
    // with a stale $DISPLAY and no X server hits — xclip is on PATH, so this lands in 'failed', not
    // 'unavailable', even though the outcome — no OS clipboard to write to — is identical), the user
    // still needs the image. Hard-failing here used to freeze the whole session over what is, from
    // the engine's perspective, just a degraded paste. Fall back to the file's path as ordinary
    // text, and keep the file: it has to keep resolving after this call returns.
    const result = await this.pasteRawTo(state, path, held)
    if (state.closing) return
    if (result.state !== 'succeeded') {
      this.sendError(state.connId, 'TERMINAL_PASTE_IMAGE_FAILED', { streamId: state.streamId, message: result.reason })
      if (result.dispatch === 'possibly_executed') await this.sendKeyframe(state, 'input')
      return
    }
    this.deps.sendTarget(state.connId, 'terminal_paste_image_result', {
      streamId: state.streamId,
      outcome: 'fallback_path',
      reason: clipboard.reason,
    })
  }

  /**
   * A dropped (non-image) FILE (bytes already fully assembled from a chunked upload — see
   * `receiveUploadChunk`) — writes it to disk on THIS machine (under its original name, see
   * `writePasteDropFile`) and pastes that path as plain text, the same `pasteRaw` call `paste()`
   * uses. Unlike `pasteImage()`, there is no OS-clipboard attempt and no Ctrl+V replay: the goal
   * here is only "the pane gets a valid path", not "the engine auto-attaches this" — a client only
   * sends this at all for a genuinely REMOTE pane (a local one pastes its own already-valid path
   * without ever reaching the wire), so there is no local/remote branch to make here either.
   */
  private async pasteFile(state: ActiveStream, filename: string, bytes: Uint8Array, held = false): Promise<void> {
    state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
    let path: string
    try {
      path = await writePasteDropFile(filename, bytes)
    } catch (error) {
      this.sendError(state.connId, 'TERMINAL_PASTE_FILE_FAILED', {
        streamId: state.streamId,
        message: error instanceof Error ? error.message : 'could not save the dropped file',
      })
      return
    }
    const result = await this.pasteRawTo(state, path, held)
    if (state.closing) return
    if (result.state !== 'succeeded') {
      this.sendError(state.connId, 'TERMINAL_PASTE_FILE_FAILED', { streamId: state.streamId, message: result.reason })
      if (result.dispatch === 'possibly_executed') await this.sendKeyframe(state, 'input')
      return
    }
    this.deps.sendTarget(state.connId, 'terminal_paste_file_result', { streamId: state.streamId, path })
  }

  /**
   * Announces a new chunked image/file upload for this stream — see UPLOAD_CHUNK_BYTES's doc for
   * why this is chunked at all (a per-binary-message ceiling shared by the backend relay and the
   * P2P data channel) rather than the single atomic frame `imagePaste`/`pasteFile` used to be.
   * Validated and either accepted or rejected up front, before any chunk is sent, so a client on a
   * slow link finds out immediately rather than after transferring several MB for nothing.
   */
  private beginChunkedUpload(connId: string, payload: FramePayload): void {
    // Unlike resize/scroll/ack (silently no-op on a bad lookup is harmless — the next real event
    // self-corrects), a paste that vanishes here leaves the client's progress overlay waiting on a
    // reply that will never come, with nothing to explain why: it looks exactly like a hang. Reply
    // even when this connection doesn't currently own a live stream for the streamId it named,
    // echoing that streamId back (not a `state`'s, which we don't have) so the client can still
    // match it against what it's waiting on.
    const claimedStreamId = typeof payload.streamId === 'string' ? payload.streamId : undefined
    const state = this.streamFor(connId, payload)
    if (!state) {
      this.deps.sendTarget(connId, 'terminal_chunked_upload_begin_result', {
        streamId: claimedStreamId,
        accepted: false,
        code: 'TERMINAL_STREAM_NOT_FOUND',
        reason: 'no live terminal stream for this pane (reopen it and try again)',
      })
      return
    }
    const streamId = state.streamId
    const reject = (reason: string): void => {
      this.diagnostic(state, 'chunked_upload_rejected', { reason })
      this.deps.sendTarget(connId, 'terminal_chunked_upload_begin_result', { streamId, accepted: false, reason })
    }
    const uploadKind = payload.uploadKind === 'image' ? TerminalBinaryKind.imagePaste
      : payload.uploadKind === 'file' ? TerminalBinaryKind.pasteFile
      : null
    const totalBytes = Number(payload.totalBytes)
    const filename = typeof payload.filename === 'string' ? payload.filename : undefined
    if (!uploadKind || !Number.isSafeInteger(totalBytes) || totalBytes <= 0
      || (uploadKind === TerminalBinaryKind.pasteFile && !filename)) {
      reject('malformed upload request')
      return
    }
    if (state.pendingUpload) {
      reject('an upload is already in progress on this pane')
      return
    }
    const ceiling = uploadKind === TerminalBinaryKind.imagePaste
      ? TERMINAL_LOCAL_IMAGE_PASTE_MAX_PAYLOAD_BYTES
      : TERMINAL_LOCAL_PASTE_FILE_MAX_PAYLOAD_BYTES
    if (totalBytes > ceiling) {
      reject(`exceeds the ${Math.floor(ceiling / (1024 * 1024))} MB limit`)
      return
    }
    state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
    state.pendingUpload = {
      kind: uploadKind,
      filename,
      totalBytes,
      expectedChunks: Math.ceil(totalBytes / UPLOAD_CHUNK_BYTES),
      chunks: [],
      bytesReceived: 0,
    }
    this.diagnostic(state, 'chunked_upload_begin', { uploadKind: payload.uploadKind, totalBytes, filename })
    this.deps.sendTarget(connId, 'terminal_chunked_upload_begin_result', { streamId, accepted: true })
  }

  /** The user's own Cancel — stop and discard whatever has arrived so far. Nothing has been
   *  written to disk yet at this point (chunks are only assembled and handed off once every one
   *  has arrived), so there is no partial file to clean up — just drop the in-memory buffer. */
  private cancelChunkedUpload(connId: string, payload: FramePayload): void {
    const state = this.streamFor(connId, payload)
    if (!state) return
    if (state.pendingUpload) this.diagnostic(state, 'chunked_upload_cancelled', {})
    state.pendingUpload = null
  }

  /**
   * One chunk of an in-flight upload announced by `beginChunkedUpload`. `seq` is the chunk index
   * (not an ordered keystroke sequence the way `input()`'s is) — stored by index rather than
   * assumed in-order, since nothing guarantees frame ordering survives a relay hop-by-hop, though
   * in practice it should. A stray chunk with no matching (or a kind-mismatched) `pendingUpload` is
   * ignored rather than errored: it most likely means a cancel or a previous upload's tail-end
   * arrived late.
   *
   * Progress is acked once per chunk, after it is durably held here — matching the firmware
   * pusher's philosophy (`fwPush.ts`'s `fw.progress`) of reporting confirmed receipt, not merely
   * "sent", which is what makes the client's percentage honest on a slow link. Once every expected
   * byte has arrived, this hands the assembled bytes to the SAME finishing logic `pasteImage`/
   * `pasteFile` already had before this feature existed — only how the bytes arrived changed.
   */
  private async receiveUploadChunk(
    state: ActiveStream,
    kind: TerminalBinaryKind.imagePaste | TerminalBinaryKind.pasteFile,
    seq: number,
    bytes: Uint8Array,
  ): Promise<void> {
    const pending = state.pendingUpload
    if (!pending) {
      this.diagnostic(state, 'chunked_upload_stray_chunk', { seq, kind })
      return
    }
    if (pending.kind !== kind) return
    if (!Number.isSafeInteger(seq) || seq < 0 || seq >= pending.expectedChunks
      || bytes.length === 0 || bytes.length > UPLOAD_CHUNK_BYTES) {
      this.diagnostic(state, 'chunked_upload_invalid_chunk', { seq, byteLength: bytes.length, expectedChunks: pending.expectedChunks })
      this.sendError(state.connId, 'TERMINAL_CHUNKED_UPLOAD_INVALID', { streamId: state.streamId, message: 'malformed upload chunk' })
      state.pendingUpload = null
      return
    }
    state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
    if (pending.chunks[seq] === undefined) {
      pending.chunks[seq] = Buffer.from(bytes)
      pending.bytesReceived += bytes.length
    }
    this.deps.sendTarget(state.connId, 'terminal_chunked_upload_progress', {
      streamId: state.streamId,
      bytesWritten: pending.bytesReceived,
      totalBytes: pending.totalBytes,
    })
    if (pending.bytesReceived < pending.totalBytes) return
    state.pendingUpload = null
    this.diagnostic(state, 'chunked_upload_assembled', { totalBytes: pending.totalBytes })
    // A plain Uint8Array, not a Buffer — pasteImage/pasteFile hand this to code (osClipboard,
    // pasteDropFiles) written against the same Uint8Array shape the old atomic frame's `bytes`
    // always was, and callers/tests comparing against a Uint8Array must not have to know this
    // path happens to assemble through Buffer internally.
    const assembled = new Uint8Array(Buffer.concat(pending.chunks.filter((chunk): chunk is Buffer => chunk !== undefined)))
    const deliver = (held: boolean): Promise<void> => kind === TerminalBinaryKind.imagePaste
      ? this.pasteImage(state, assembled, held)
      : this.pasteFile(state, pending.filename!, assembled, held)
    // Held while the agent changes host, in order with its keystrokes (see `input`).
    const gate = this.heldGate(state)
    if (gate) gate.enqueue(state.agentId, () => deliver(true))
    else await deliver(false)
  }

  /** Scroll gestures arrive stream-scoped, same as resize — no ordering/seq guard needed since,
   *  unlike input, an out-of-order or dropped scroll frame just means one gesture scrolled a little
   *  more or less than intended, never a corrupted stream. PageUp/PageDown are written into the
   *  pty, so the program's own redraw rides the live output stream (`sink.onData`) back to the
   *  client; no explicit keyframe push is needed here the way resize needs one. */
  private async scroll(connId: string, payload: FramePayload): Promise<void> {
    const state = this.streamFor(connId, payload)
    if (!state) return
    const direction = payload.direction
    const lines = Number(payload.lines)
    if ((direction !== 'up' && direction !== 'down') || !Number.isSafeInteger(lines) || lines <= 0) {
      this.sendError(connId, 'TERMINAL_SCROLL_INVALID', { streamId: state.streamId })
      return
    }
    state.expiresAt = this.now() + HEARTBEAT_TIMEOUT_MS
    const deliver = async (): Promise<void> => {
      // A scroll moves this view's pane only: one whose stream closed during a move has nothing to scroll.
      if (state.closing) return
      const result = await state.handle.scroll(direction, lines)
      if (result.state !== 'succeeded') {
        this.sendError(connId, 'TERMINAL_SCROLL_FAILED', { streamId: state.streamId, message: result.reason })
      }
    }
    // A scroll writes keys into the pane (PageUp/PageDown), so it waits with the agent's other writes.
    const gate = this.heldGate(state)
    if (gate) gate.enqueue(state.agentId, deliver)
    else await deliver()
  }

  private async resyncRequested(connId: string, payload: FramePayload): Promise<void> {
    const state = this.streamFor(connId, payload)
    if (!state) { this.reportMissing(connId, payload); return }
    state.resyncs++
    this.diagnostic(state, 'resync_requested', { attempt: payload.attempt })
    await this.sendKeyframe(state, 'resync')
  }

  private async closeRequested(connId: string, payload: FramePayload): Promise<void> {
    const state = this.streamFor(connId, payload)
    if (state) await this.closeStream(state, 'client closed', true)
  }

  private onOutput(state: ActiveStream, bytes: Uint8Array): void {
    if (state.closing || bytes.length === 0) return
    const nextBuffered = state.pendingBytes + state.outputBytes + bytes.length
    state.peakBufferedBytes = Math.max(state.peakBufferedBytes, nextBuffered)
    if (nextBuffered > MAX_TOTAL_BUFFERED_BYTES) {
      this.sendError(state.connId, 'TERMINAL_OUTPUT_OVERFLOW', { streamId: state.streamId })
      this.diagnostic(state, 'output_overflow', { bufferedBytes: nextBuffered })
      void this.closeStream(state, 'terminal output exceeded safe buffer limit', true)
      return
    }
    if (this.repaintBegan(state, bytes)) return
    state.output.push(Buffer.from(bytes))
    state.outputBytes += bytes.length
    if (state.snapshotting || state.outputPaused) return
    if (state.outputBytes >= OUTPUT_CHUNK_BYTES) {
      this.flushOutput(state)
      return
    }
    // Leading edge: the first output after a quiet gap goes out immediately, which is what a
    // keystroke echo is. Waiting the full window for it cost every echo the window for no benefit —
    // there was nothing else to coalesce it with. A burst still lands on the trailing timer
    // below, so the frame rate stays capped at one frame per `state.flushMs`.
    if (!state.flushTimer && this.now() - state.lastFlushAt >= state.flushMs) {
      this.flushOutput(state)
      return
    }
    state.flushTimer ??= setTimeout(() => this.flushOutput(state), state.flushMs)
  }

  /**
   * Whether `bytes` begin the engine's print after a resize, which a keyframe then stands in for: the chunk and what
   * waits unsent are dropped, never the cleared screen they would draw, and the keyframe waits for the print's end.
   */
  private repaintBegan(state: ActiveStream, bytes: Uint8Array): boolean {
    if (state.snapshotting || this.now() > state.repaintWatchUntil) return false
    const repaint = launchContract(state.engineId)?.screen?.resizeRepaint
    if (!repaint) return false
    const clears = Buffer.from(repaint.clears, 'utf8')
    const read = Buffer.concat([state.repaintTail, Buffer.from(bytes)])
    const at = read.indexOf(clears)
    if (at < 0) {
      state.repaintTail = read.subarray(Math.max(0, read.length - clears.length + 1))
      return false
    }
    state.repaintWatchUntil = 0
    state.repaintTail = Buffer.alloc(0)
    // A print that ended in the same chunk is on the screen already: nothing is left to wait for.
    void this.sendKeyframe(state, 'repaint', read.subarray(at + clears.length).includes(repaint.ends) ? 'ended' : 'printing')
    return true
  }

  private flushOutput(state: ActiveStream): void {
    if (state.flushTimer) { clearTimeout(state.flushTimer); state.flushTimer = null }
    if (state.closing || state.snapshotting || state.outputBytes === 0 || this.closedNow(state)) return
    state.lastFlushAt = this.now()
    const all = Buffer.concat(state.output, state.outputBytes)
    state.output = []
    state.outputBytes = 0
    for (let offset = 0; offset < all.length; offset += OUTPUT_CHUNK_BYTES) {
      const chunk = all.subarray(offset, offset + OUTPUT_CHUNK_BYTES)
      const seq = state.nextSeq++
      const body = encoded(chunk, state.compression)
      if (!this.deps.sendBinaryTarget(state.connId, {
        kind: TerminalBinaryKind.output,
        streamId: state.streamId,
        seq,
        compressed: body.compressed,
        bytes: body.bytes,
      })) {
        void this.closeStream(state, 'backend disconnected', false)
        return
      }
      state.pending.push({ seq, bytes: body.plainBytes })
      state.pendingBytes += body.plainBytes
      state.outputFrames++
      const probe = state.echoProbe
      if (probe) {
        state.echoProbe = null
        this.deps.typingTrace?.(`stream=${state.streamId.slice(0, 8)} seq=${probe.seq} first output out +${Math.round(this.now() - probe.at)}ms after it was written`)
      }
      state.outputPlainBytes += body.plainBytes
    }
    if (state.pendingBytes > PAUSE_HIGH_WATERMARK_BYTES && !state.outputPaused) void this.pauseOutput(state)
  }

  private armStallTimer(state: ActiveStream): void {
    if (state.stallTimer) clearTimeout(state.stallTimer)
    state.stallTimer = setTimeout(() => {
      state.stallTimer = null
      if (!state.closing && state.outputPaused) {
        this.sendError(state.connId, 'TERMINAL_RENDER_STALLED', { streamId: state.streamId })
        void this.closeStream(state, 'renderer did not acknowledge terminal output', true)
      }
    }, RENDER_STALL_TIMEOUT_MS)
  }

  private async pauseOutput(state: ActiveStream): Promise<void> {
    if (state.closing || state.outputPaused) return
    state.outputPaused = true
    state.pausedAt = this.now()
    const result = await state.handle.pauseOutput()
    if (result.state !== 'succeeded') {
      this.sendError(state.connId, 'TERMINAL_BACKPRESSURE_FAILED', { streamId: state.streamId, message: result.reason })
      await this.closeStream(state, result.reason, true)
      return
    }
    this.diagnostic(state, 'output_paused', { pendingBytes: state.pendingBytes })
    this.armStallTimer(state)
  }

  private async resumeOutput(state: ActiveStream): Promise<void> {
    if (state.closing || !state.outputPaused) return
    state.outputPaused = false
    if (state.pausedAt != null) state.pausedMs += Math.max(0, this.now() - state.pausedAt)
    state.pausedAt = null
    if (state.stallTimer) clearTimeout(state.stallTimer)
    state.stallTimer = null
    const result = await state.handle.resumeOutput()
    if (result.state !== 'succeeded') {
      this.sendError(state.connId, 'TERMINAL_BACKPRESSURE_FAILED', { streamId: state.streamId, message: result.reason })
      await this.closeStream(state, result.reason, true)
      return
    }
    this.diagnostic(state, 'output_resumed', { pendingBytes: state.pendingBytes })
    this.flushOutput(state)
  }

  /**
   * `reason`: what asked for it, for the log — an open, a resize, a client's resync, input that may have run, or the
   * engine's print after a resize that began as live output; `print` says whether that print is still `printing`,
   * which the snapshot then waits out, or `ended`.
   */
  private async sendKeyframe(
    state: ActiveStream, reason: 'open' | 'resize' | 'resync' | 'input' | 'repaint' | 'retarget', print?: 'printing' | 'ended',
  ): Promise<void> {
    if (state.closing || state.resyncing) return
    const startedAt = this.now()
    // The pane this keyframe is taken from. A retarget while it is taken moves the stream to another pane: what
    // this one shows is then not the stream's, and the keyframe is taken again from the new one (`moved`).
    const handle = state.handle
    const moved = (): boolean => {
      if (state.handle === handle) return false
      handle.endSnapshot()
      state.snapshotting = false
      state.resyncing = false
      return true
    }
    state.resyncing = true
    state.snapshotting = true
    handle.beginSnapshot()
    state.output = []
    state.outputBytes = 0
    if (state.outputPaused) {
      state.outputPaused = false
      if (state.pausedAt != null) state.pausedMs += Math.max(0, this.now() - state.pausedAt)
      state.pausedAt = null
      if (state.stallTimer) clearTimeout(state.stallTimer)
      state.stallTimer = null
      const resumed = await handle.resumeOutput().catch(() => ({
        state: 'failed' as const,
        dispatch: 'not_started' as const,
        reason: 'resume failed',
      }))
      if (moved()) return this.sendKeyframe(state, 'retarget')
      if (resumed.state !== 'succeeded') {
        handle.endSnapshot()
        state.snapshotting = false
        state.resyncing = false
        this.sendError(state.connId, 'TERMINAL_BACKPRESSURE_FAILED', {
          streamId: state.streamId,
          message: resumed.reason,
        })
        await this.closeStream(state, resumed.reason, true)
        return
      }
    }
    if (state.flushTimer) { clearTimeout(state.flushTimer); state.flushTimer = null }
    let snapshot: Awaited<ReturnType<TerminalStreamHandle['snapshot']>> = {
      state: 'failed',
      reason: 'tmux snapshot did not run',
    }
    try {
      // An engine Harness keeps in the scrollback (facets/launch.ts `ScreenContract`) has its conversation there:
      // all of it is seeded, re-wrapped by word, since the pane's width changes with every takeover between a
      // desktop and a phone.
      // One that prints its transcript again on a resize has the keyframe after a resize wait for that print, and
      // its live output watched for a print that begins later still.
      const screen = launchContract(state.engineId)?.screen
      const repaint = screen?.resizeRepaint && print !== 'ended'
        ? { ...screen.resizeRepaint, ...(print === 'printing' ? { cleared: true } : {}) }
        : undefined
      if (repaint && (reason === 'open' || reason === 'resize')) {
        state.repaintWatchUntil = this.now() + REPAINT_GUARD_MS
        state.repaintTail = Buffer.alloc(0)
      }
      snapshot = await handle.snapshot(
        state.engineId === 'grok' ? { tuiOwnsScrollback: true }
          : screen ? { conversationHistory: true, ...(repaint ? { repaint } : {}) }
            : undefined,
      )
    } catch (error) {
      snapshot = { state: 'failed', reason: error instanceof Error ? error.message : 'tmux snapshot failed' }
    }
    if (moved()) return this.sendKeyframe(state, 'retarget')
    if (snapshot.state !== 'succeeded') {
      handle.endSnapshot()
      state.snapshotting = false
      state.resyncing = false
      this.diagnostic(state, 'snapshot_failed', { reason: snapshot.reason })
      this.sendError(state.connId, 'TERMINAL_SNAPSHOT_FAILED', { streamId: state.streamId, message: snapshot.reason })
      await this.closeStream(state, snapshot.reason, false)
      return
    }
    if (snapshot.value.bytes.length > KEYFRAME_MAX_BYTES) {
      handle.endSnapshot()
      state.snapshotting = false
      state.resyncing = false
      this.diagnostic(state, 'snapshot_too_large', { plainBytes: snapshot.value.bytes.length })
      this.sendError(state.connId, 'TERMINAL_SNAPSHOT_TOO_LARGE', { streamId: state.streamId })
      await this.closeStream(state, 'terminal snapshot exceeds safe envelope size', false)
      return
    }
    if (this.closedNow(state)) return
    const bytes = Buffer.from(snapshot.value.bytes)
    state.pending = []
    state.pendingBytes = 0
    const seq = state.nextSeq++
    const body = encoded(bytes, state.compression)
    const sent = this.deps.sendBinaryTarget(state.connId, {
      kind: TerminalBinaryKind.keyframe,
      streamId: state.streamId,
      seq,
      cols: snapshot.value.cols,
      rows: snapshot.value.rows,
      compressed: body.compressed,
      bytes: body.bytes,
    })
    if (!sent) {
      handle.endSnapshot()
      state.snapshotting = false
      state.resyncing = false
      await this.closeStream(state, 'backend disconnected', false)
      return
    }
    state.pending.push({ seq, bytes: body.plainBytes })
    state.pendingBytes = body.plainBytes
    state.keyframes++
    state.lastSyncAt = this.now()
    state.peakBufferedBytes = Math.max(state.peakBufferedBytes, state.pendingBytes)
    this.diagnostic(state, 'keyframe_sent', {
      reason,
      seq,
      plainBytes: body.plainBytes,
      compressedBytes: body.bytes.length,
      snapshotMs: Math.max(0, this.now() - startedAt),
    })
    const probe = state.echoProbe
    if (probe) {
      this.deps.typingTrace?.(`stream=${state.streamId.slice(0, 8)} seq=${probe.seq} keyframe (${reason}) out +${Math.round(this.now() - probe.at)}ms after it was written`)
      // Written before the keyframe began, its echo is in it, or in what the keyframe releases next.
      if (probe.at <= startedAt) state.echoProbe = null
    }
    // The output held behind the keyframe is released as live output, read for an engine's print as it is
    // (`repaintBegan`): Codex's clear came in it, after a keyframe taken before its print began, and went straight to
    // the viewer while the keyframe was still marked as being taken. The print's keyframe can begin from it here.
    state.snapshotting = false
    state.resyncing = false
    handle.endSnapshot()
    this.flushOutput(state)
    if (state.pendingBytes > PAUSE_HIGH_WATERMARK_BYTES && !state.outputPaused) void this.pauseOutput(state)
  }

  private sendSync(state: ActiveStream, now: number): void {
    if (state.closing || state.snapshotting || state.resyncing || state.outputPaused || this.closedNow(state)) return
    this.flushOutput(state)
    if (state.closing || state.outputPaused) return
    const seq = state.nextSeq++
    if (!this.deps.sendBinaryTarget(state.connId, {
      kind: TerminalBinaryKind.sync,
      streamId: state.streamId,
      seq,
      compressed: false,
      bytes: new Uint8Array(),
    })) {
      void this.closeStream(state, 'backend disconnected', false)
      return
    }
    state.pending.push({ seq, bytes: 0 })
    state.syncFrames++
    state.lastSyncAt = now
  }

  private expireLeases(): void {
    const now = this.now()
    // A sweep that arrives long after its period is the computer waking up, and the time asleep is
    // nobody's silence: the window slept too, and could not have sent `terminal_alive`. Every lease is
    // carried over the gap, so the window's first heartbeat after the wake finds its stream still
    // there. Closing them all here is what put every local terminal on "reconnecting" at each wake.
    const slept = sleptFor(now - this.lastSweepAt, EXPIRY_SWEEP_MS)
    this.lastSweepAt = now
    if (slept > 0) {
      for (const state of this.streams.values()) state.expiresAt += slept
    }
    for (const state of [...this.streams.values()]) {
      if (!state.closing && state.expiresAt <= now) void this.closeStream(state, 'heartbeat timeout', true)
      else if (!state.closing && now - state.lastSyncAt >= SYNC_INTERVAL_MS) this.sendSync(state, now)
    }
  }

  private diagnostic(state: ActiveStream, event: string, fields: Record<string, unknown> = {}): void {
    this.deps.diagnostic?.(event, {
      streamId: state.streamId.slice(0, 8),
      agentId: state.agentId.slice(0, 8),
      engineId: state.engineId,
      ...fields,
    })
  }

  /// Replace this view's own stream for the same terminal.
  ///
  /// Reopening is routine — a resync, a relay that came back — and the old stream has to go or the
  /// agent would have two tmux clients on one window. Matched on agent AND placement so a client
  /// holding several different terminals keeps the ones it did not ask about. Notify even older
  /// pooled clients that omit viewId: a different view may still be using the old stream. Omit
  /// takenBy here, since older clients automatically watch a named taker using the same owner ID.
  private async closeOwnStreamsFor(ownerId: string, agentId: string, placementKey: string): Promise<void> {
    const own = [...this.streams.values()].filter((state) =>
      !state.closing && state.ownerId === ownerId
        && (state.agentId === agentId || state.placementKey === placementKey))
    await Promise.all(own.map((state) => this.closeStream(
      state, 'terminal reopened in another view', true, 'TERMINAL_TAKEN_OVER',
    )))
  }

  /// The live streams OTHER views hold on this terminal — exactly the ones a takeover would
  /// close, which is what makes it the right question for an open that must not take over.
  private incumbentsFor(agentId: string, placementKey: string, nextOwnerId: string): ActiveStream[] {
    return [...this.streams.values()].filter((state) =>
      !state.closing && state.ownerId !== nextOwnerId
        && (state.agentId === agentId || state.placementKey === placementKey))
  }

  /** The client driving a terminal a watcher opened onto: the placement's controller, or failing
   *  that the first incumbent that said who it is. Undefined when none did — the banner then says
   *  "another app", as it always has. */
  private holderOf(incumbents: ActiveStream[], placementKey: string): TerminalClientDescriptor | undefined {
    const controller = this.controllerByPlacement.get(placementKey)
    return (incumbents.find((state) => state.ownerId === controller && state.client)
      ?? incumbents.find((state) => state.client))?.client
  }

  private async closeStreamsForTakeover(
    agentId: string,
    placementKey: string,
    nextOwnerId: string,
    takenBy?: TerminalClientDescriptor,
  ): Promise<void> {
    const incumbents = this.incumbentsFor(agentId, placementKey, nextOwnerId)
    await Promise.all(incumbents.map((state) => this.closeStream(
      state,
      'another client connected',
      true,
      'TERMINAL_TAKEN_OVER',
      takenBy,
    )))
  }

  private async closeStream(
    state: ActiveStream,
    reason: string,
    notify: boolean,
    code?: string,
    takenBy?: TerminalClientDescriptor,
  ): Promise<void> {
    if (state.closing) return
    state.closing = true
    if (state.pausedAt != null) state.pausedMs += Math.max(0, this.now() - state.pausedAt)
    this.diagnostic(state, 'closed', {
      reason,
      ...(takenBy ? { takenBy: takenBy.name } : {}),
      lifetimeMs: Math.max(0, this.now() - state.openedAt),
      outputFrames: state.outputFrames,
      outputPlainBytes: state.outputPlainBytes,
      keyframes: state.keyframes,
      syncFrames: state.syncFrames,
      resyncs: state.resyncs,
      peakBufferedBytes: state.peakBufferedBytes,
      pausedMs: state.pausedMs,
    })
    if (state.flushTimer) clearTimeout(state.flushTimer)
    if (state.stallTimer) clearTimeout(state.stallTimer)
    if (state.heldInputTimer) clearTimeout(state.heldInputTimer)
    state.flushTimer = null
    state.stallTimer = null
    state.heldInputTimer = null
    // Keystrokes still waiting for a missing one go with the stream: nothing is written to a pane let go.
    state.heldInput.clear()
    state.heldInputBytes = 0
    this.streams.delete(state.streamId)
    const controlled = this.controllerByPlacement.get(state.placementKey) === state.ownerId
    if (this.controllerByAgent.get(state.agentId) === state.ownerId) this.controllerByAgent.delete(state.agentId)
    if (this.controllerByPlacement.get(state.placementKey) === state.ownerId) this.controllerByPlacement.delete(state.placementKey)
    if (state.outputPaused) await state.handle.resumeOutput().catch(() => { /* best effort */ })
    await state.handle.close().catch(() => { /* best effort */ })
    if (notify) this.deps.sendTarget(state.connId, 'terminal_closed', {
      protocolVersion: PROTOCOL_VERSION,
      streamId: state.streamId,
      reason,
      ...(code ? { code } : {}),
      ...(takenBy ? { takenBy } : {}),
    })
    // The controller left (a phone closed it, or went away) rather than handing it to another view:
    // the views watching it are told, so one on screen can take it back at its own size. Without
    // this the terminal kept the size of the one that left until someone typed in a watcher.
    if (controlled && code !== 'TERMINAL_TAKEN_OVER') this.notifyFree(state)
  }

  private notifyFree(closed: ActiveStream): void {
    for (const watcher of this.streams.values()) {
      if (watcher.closing || watcher.ownerId === closed.ownerId) continue
      if (watcher.agentId !== closed.agentId && watcher.placementKey !== closed.placementKey) continue
      this.deps.sendTarget(watcher.connId, 'terminal_free', {
        protocolVersion: PROTOCOL_VERSION,
        streamId: watcher.streamId,
      })
    }
  }

  /**
   * The loopback window on `connId` focused `agentId` (null: no terminal). That agent's terminal gets the
   * short output window and the window's other terminals go back to the long one. Applied to open
   * streams, so a focus move takes effect from the next flush rather than the next open; a batch already
   * waiting on the long window still waits it out, once.
   */
  setFocusedAgent(connId: string, agentId: string | null): void {
    this.focusByConn.set(connId, agentId)
    for (const state of this.streams.values()) {
      if (state.connId === connId) state.flushMs = this.flushWindow(connId, state.agentId, state.loopback)
    }
  }

  /**
   * The agents the loopback window on `connId` has on screen; null when it never sent a list (it then
   * counts as looking at all its streams). `[]` is a minimized or tray-hidden window.
   */
  setVisibleAgents(connId: string, agentIds: readonly string[] | null): void {
    if (agentIds === null) this.visibleByConn.delete(connId)
    else this.visibleByConn.set(connId, new Set(agentIds))
  }

  /**
   * Whether a person can see this agent's terminal right now. A `watch: true` stream never counts (no
   * person behind it). A phone or web stream does, including a `takeover: false` neighbour. A loopback
   * window counts when it lists the agent, or never listed anything.
   */
  isLookedAt(agentId: string): boolean {
    // A held agent someone typed into or opened is in use, whether or not a window lists it: the mover reads
    // this on its next tick, and stops before a swap it has not yet begun. The gate forgets it at release.
    if (this.deps.moveGate?.touched(agentId)) return true
    for (const state of this.streams.values()) {
      if (state.agentId !== agentId || state.closing || state.watchOnly) continue
      if (!state.loopback) return true
      const visible = this.visibleByConn.get(state.connId)
      if (!visible || visible.has(agentId)) return true
    }
    return false
  }

  /**
   * Move every open stream of [agentId], of any kind, to the pane [to]: the agent changed host. Each stream is
   * subscribed on `to` through the same coordinator call an open makes, at its own size and mode, and keeps its
   * connection, stream id, lease and seq. The client sees only frames it already knows: a keyframe of the new
   * pane in place of the old one, then the new pane's output. No close, and no new frame type. A stream that
   * cannot follow is closed as a stream whose pane went away is, and its client opens it again.
   */
  async retarget(agentId: string, to: TerminalRuntimeRef): Promise<void> {
    const streams = [...this.streams.values()].filter((state) => state.agentId === agentId && !state.closing)
    if (streams.length === 0) return
    const session = this.deps.resolveAgent(agentId)
    const target = session ? rowOn(session, to) : null
    await Promise.all(streams.map((state) => this.retargetStream(state, target)))
  }

  private async retargetStream(state: ActiveStream, target: RegisteredSession | null): Promise<void> {
    if (!target) {
      await this.closeStream(state, 'the agent is no longer registered', true)
      return
    }
    const subscription = ++state.subscriptions
    let opened: Awaited<ReturnType<TerminalBackendCoordinator['openStream']>>
    try {
      opened = await this.deps.terminals.openStream(target, state.size, {
        onData: (bytes) => { if (state.subscription === subscription) this.onOutput(state, bytes) },
        onClose: (reason) => { if (state.subscription === subscription) void this.closeStream(state, reason, true) },
      }, this.deps.readOnly === true || state.watching)
    } catch (error) {
      opened = { state: 'failed', reason: error instanceof Error ? error.message : String(error) }
    }
    // Closed while the new pane was being opened, or moved again past this one by a later retarget.
    if (state.closing || state.subscription > subscription) {
      if (opened.state === 'succeeded') await opened.value.close().catch(() => { /* best effort */ })
      return
    }
    if (opened.state !== 'succeeded') {
      this.diagnostic(state, 'retarget_failed', { reason: opened.reason })
      await this.closeStream(state, opened.reason, true)
      return
    }
    const previous = state.handle
    const previousPaused = state.outputPaused
    state.subscription = subscription
    state.handle = opened.value
    const placementKey = terminalPlacementKey(opened.value.runtime)
    if (placementKey !== state.placementKey) {
      if (this.controllerByPlacement.get(state.placementKey) === state.ownerId) {
        this.controllerByPlacement.delete(state.placementKey)
        this.controllerByPlacement.set(placementKey, state.ownerId)
      }
      state.placementKey = placementKey
    }
    // The new pane was never paused, and no print after a resize is awaited from it.
    if (state.outputPaused) {
      state.outputPaused = false
      if (state.pausedAt != null) state.pausedMs += Math.max(0, this.now() - state.pausedAt)
      state.pausedAt = null
      if (state.stallTimer) clearTimeout(state.stallTimer)
      state.stallTimer = null
    }
    state.repaintWatchUntil = 0
    state.repaintTail = Buffer.alloc(0)
    this.diagnostic(state, 'retargeted', { watching: state.watching })
    if (previousPaused) await previous.resumeOutput().catch(() => { /* best effort */ })
    await previous.close().catch(() => { /* best effort */ })
    // What the client shows is the old pane's: the keyframe replaces it, and the new pane's output follows it.
    await this.sendKeyframe(state, 'retarget')
  }

  private flushWindow(connId: string, agentId: string, loopback: boolean): number {
    if (!loopback) return OUTPUT_FLUSH_MS
    const focused = this.focusByConn.get(connId)
    return focused === undefined || focused === agentId ? LOOPBACK_OUTPUT_FLUSH_MS : OUTPUT_FLUSH_MS
  }

  async closeConnection(connId: string, reason = 'connection closed', notify = false): Promise<void> {
    this.focusByConn.delete(connId)
    this.visibleByConn.delete(connId)
    const states = [...this.streams.values()].filter((state) => state.connId === connId)
    await Promise.all(states.map((state) => this.closeStream(state, reason, notify)))
  }

  /** Close one transport class without disturbing streams owned by another transport. */
  async closeConnectionsWhere(
    predicate: (connId: string) => boolean,
    reason: string,
    notify = false,
  ): Promise<void> {
    const states = [...this.streams.values()].filter((state) => predicate(state.connId))
    await Promise.all(states.map((state) => this.closeStream(state, reason, notify)))
  }

  async closeAll(reason = 'backend disconnected'): Promise<void> {
    await Promise.all([...this.streams.values()].map((state) => this.closeStream(state, reason, false)))
  }

  async stop(): Promise<void> {
    clearInterval(this.expiryTimer)
    this.focusByConn.clear()
    this.visibleByConn.clear()
    await this.closeAll('terminal manager stopped')
  }
}