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.

91.4 KB
Raw Blame
import { messageReceipt, productObservation, productUsageIntent, productUsageLaunch, productUsageRequest, productUsageSource } from './lib/productUsageSignals.js'
import type { MessageReceipt } from './lib/sessionInput.js'
import { isLocalOnly, withoutUpdate } from './lib/cardUpdate.js'
import { slimForRelay } from './lib/slimForRelay.js'
import type { PurgeAgentService } from './lib/purgeAgentService.js'
import { MESSAGES_REQUESTS, SHARE_REQUESTS, type Asker, type LocalWindows, type WindowSurface, type BackendNotice, type GatewayEvents, type GatewayPort, type ModelsPort, type RemoteAppPolicy, type RemoteClient, type RemoteRole, type RemoteTransport, type TabFrame } from './core/api.js'
import { ServiceUnavailableError } from './core/serviceHost.js'
import { countWindows } from './lib/windowSurfaces.js'
import type { ViewerStreams } from './core/viewerStreams.js'
import type { ActivityFrame } from './lib/turnActivity.js'
import { MonitorCompletions } from './lib/harnessMonitor.js'
import type { WifiCore } from './core/wifi.js'
/**
 * BackendSocket — the clients' hub and the request dispatch: the windows and tools on this computer
 * (localWsServer.ts), and the remote clients the gateway hands on (gateway/gateway.ts), each in its own
 * order, behind one gate until the daemon is ready.
 *
 * It holds no link and no key. The backend link, the E2EE sessions, the terminals' P2P channels and the
 * Wi-Fi device's direct links are the gateway's (the core boundary, step 10, R1:
 * docs/design/2026-10-06-core-boundary-next.md): a remote client's request reaches this socket opened,
 * with the role its session proved, and everything this socket has for a remote client leaves through
 * the gateway, which seals it.
 */

import { join } from 'path'
import { hostname } from 'os'
import { env } from './config/env.js'
import { registry, projectDisplayName, type RegisteredSession } from './lib/registry.js'
import type { CloseAgentService } from './lib/closeAgentService.js'
import { ENGINES, type AgentEngine } from './engines/types.js'
import { gridCliPresence } from './lib/gridBinary.js'
import { GRID_FLEET_PROTOCOL, GRID_FLEET_MAX_TIMEOUT_MS } from './lib/gridFleetProtocol.js'
import { isApiLaunch, parseGridLaunchOverride, type GridLaunchOverride } from './lib/gridLaunchWire.js'
import type { LaunchModel } from './lib/launchModel.js'
import type { ScmLaunchRecord } from './scm/types.js'
import type { StartedBy } from './lib/agentAttribution.js'
import { probeEngines } from './lib/engineProbe.js'
import { engineInstallLine, engineInstallRecipe } from './lib/engineInstall.js'
import { supportsFirstPrompt } from './lib/engineLaunch.js'
import { agentFrame, type AgentDshContext, type AgentFrame } from './lib/agentFrame.js'
import type { AgentTokenUsage } from './lib/agentUsageWire.js'
import { terminalHandoffRequest } from './lib/terminalHandoff.js'
import { OwnerCommands, ROUTE_COMMAND_TYPES } from './lib/ownerCommands.js'
import { VIEWER_DOWN_TYPES } from './lib/viewerFrames.js'
import type { TerminalStreamManager } from './lib/terminalStreamManager.js'
import { encodeTerminalLocal, TerminalBinaryKind, type TerminalBinaryClear } from './lib/terminalBinary.js'
import { BACKEND_ONLY_DOWN_TYPES, GATEWAY_REQUEST_TYPES, isLocalClientId, logSafeType, PAIR_REQUESTS, PLATE_REQUEST, rpcResultType, type DownTransport } from './lib/relayFrames.js'
import { sid, logFrame } from './lib/log.js'
import { spreadNotice } from './lib/spreadNotice.js'
import { eventAgentId, GUEST_REFUSALS, guestVerdict } from './core/guestPolicy.js'

export { isLocalClientId, type DownTransport }

/** Requests one local connection may queue before the daemon is ready (see `openRequests`). The app
 *  sends a handful on connect; hundreds is a client looping, not a person. */
const MAX_REQUESTS_BEFORE_READY = 256
/** The line Desktop shows before installing an engine here. */
const installRecipeLine = (engine: Parameters<typeof engineInstallRecipe>[0]): string | undefined => {
  const recipe = engineInstallRecipe(engine)
  return recipe && engineInstallLine(recipe)
}

/** Within how long this computer's windows hear an invitation given or taken back: the backend now answers the shares list in
 *  tens of milliseconds, and 10 s spreads every member's read of it over a hundred times that. */
const SHARES_NOTICE_SPREAD_MS = 10_000
/** A terminal stream's bookkeeping, handled as it arrives rather than in its connection's line — see `enqueueDown`. */
const TERMINAL_BOOKKEEPING_TYPES: ReadonlySet<string> = new Set(['terminal_ack', 'terminal_alive'])
/** An upload's control frames, which go in line with its chunks — see `enqueueDown`. */
const TERMINAL_UPLOAD_CONTROL_TYPES: ReadonlySet<string> = new Set(['terminal_chunked_upload_begin', 'terminal_chunked_upload_cancel'])
/** Agent Messages' requests, which the frame log leaves out: they carry what agents say to each other. */
const MESSAGE_REQUESTS: ReadonlySet<string> = new Set(MESSAGES_REQUESTS)
/** Share's requests, which the frame log leaves out as well: they carry who a harness is shared with. */
const SHARE_REQUEST_TYPES: ReadonlySet<string> = new Set(SHARE_REQUESTS)

export type Frame = Record<string, unknown>

export interface LocalClientSink {
  sendFrame: (frame: Frame) => boolean
  sendBinary: (frame: Uint8Array) => boolean
}

export class BackendSocket {
  /** This machine's name as Harness shows it (Machines), from the backend's `machine_meta`. Null
   *  until the first one arrives. */
  private machineDisplayName: string | null = null
  /** The relay and its E2EE (gateway/gateway.ts): the one way to a remote client. Null in a unit test
   *  that has none, which then serves this computer alone. */
  private gatewayPort: GatewayPort | null = null
  /** The core's stop has begun: nothing more is pushed. */
  private closed = false
  /** Signed out: no frame is handed to the gateway, which would only seal it for a link that never opens. */
  private thisComputerOnly = false
  /** Whether the backend link is up, as the gateway last said. */
  private linkUp = false
  private readonly downChains = new Map<string, Promise<void>>()
  /** A remote client's terminal bytes, per connection and stream — see `enqueueTerminalBinary`. */
  private readonly streamLanes = new Map<string, Promise<void>>()
  /**
   * Requests wait here until the daemon is ready (`openRequests`), each in its connection's own order.
   * The port answers long before start-up has wired every handler and confirmed the agents it
   * restored; a request answered in between met a handler that was not there yet — refused with
   * UNSUPPORTED_ON_REMOTE, or for `message` silently dropped — or a registry not yet reconciled.
   */
  private requestsOpen = true
  private openRequestGate: () => void = () => {}
  private requestGate: Promise<void> = Promise.resolve()
  /** Requests waiting at the gate, per connection: a client that floods a starting daemon is closed. */
  private readonly waitingAtGate = new Map<string, number>()
  private readonly localClients = new Map<string, LocalClientSink>()
  /** The remote clients the gateway holds a session with, by connection: what the core reads of them
   *  synchronously (the label a terminal is named by), as the gateway last said. */
  private readonly remoteClients = new Map<string, RemoteClient>()
  /** The last window found gone when a reply for it came: its queued replies come in a burst, said once. */
  private goneReplyConn = ''
  /**
   * Loopback clients that are TOOLS, not windows (`machine_select { tool: true }`): `harness pair`, the
   * `harnessd` MCP server. They get their RPC replies like any local client, but they are not a person at
   * this computer — not presence, not a window to push to, and never what wakes the pair brain.
   */
  private readonly toolClients = new Set<string>()
  /** The windows that are `harness tui`, not the desktop app: each surface is its own presence. */
  private readonly tuiClients = new Set<string>()
  private terminalStreams: TerminalStreamManager | null = null
  private onStatus: (connected: boolean) => void
  /** Cross-instance commander (device) client count, as the gateway reads it from the backend. */
  private commanderCount = 0
  /** Subset of commanderCount whose device is ACTIVELY rendering this machine (multi-attach). null = the
   *  backend doesn't send the signal (old build) → fall back to hasCommander so streaming isn't gated off. */
  private commanderActive: number | null = null
  /** Called when a commander attach is observed — cli.ts replays live state. */
  onCommanderJoin: (() => void) | null = null
  /** Called only when commander presence crosses zero; drives the disposable recap-worker grace. */
  onCommanderPresenceChanged: ((connected: boolean) => void) | null = null
  /** An app away from this desk (the phone, a browser) gained an E2EE session: it is told again what is still
   *  being asked (core/questions.ts), as a window on this computer is when it attaches (localWsServer.ts). */
  onRemoteAppJoined: (() => void) | null = null
  /** Cancels an agent's turn, for the orchestrator (cli.ts binds core/turns/cancel.ts). */
  onCancel: ((sessionId: string) => void) | null = null
  /** Takes a `cancel` frame, a turn interrupted with C-c (cli.ts binds core/turns/cancel.ts). */
  cancelProvider: ((payload: Record<string, unknown>) => void) | null = null
  /** Answers `agent_delete`, Stop Harness: the validated engine process signalled and the session
   *  forgotten, its recap and name kept (cli.ts binds core/agents/lifecycle.ts). Null answers UNSUPPORTED. */
  stopProvider: ((payload: Record<string, unknown>) => Promise<Record<string, unknown>>) | null = null
  /** The purge service: an agent being deleted takes no other lifecycle request meanwhile. */
  purgeAgentService: PurgeAgentService | null = null
  /** Answers `agent_purge` and `agent_worktree_delete` through its last argument, for the owner alone
   *  (cli.ts binds core/agents/lifecycle.ts). Null answers UNSUPPORTED. */
  purgeProvider: ((type: string, payload: Record<string, unknown>, asker: { local: boolean; owner: boolean },
    reply: (result: Record<string, unknown>) => void) => void) | null = null
  closeAgentService: CloseAgentService | null = null
  /** Answers `agent_close` through its last argument, once the agent is saved and closed or the close is
   *  refused (cli.ts binds core/agents/close.ts). Null answers UNSUPPORTED. */
  closeProvider: ((payload: Record<string, unknown>, reply: (result: Record<string, unknown>) => void) => void) | null = null
  /** Answers `agents_cleanup_preview` through its argument, once every hidden agent was looked at (cli.ts
   *  binds core/agents/close.ts). Null answers UNSUPPORTED. */
  cleanupPreviewProvider: ((reply: (result: Record<string, unknown>) => void) => void) | null = null
  /** Called on `agent_create` — cli.ts spawns a fresh tmux session running the requested engine in the
   *  requested folder and returns its process-agent. Session metadata may bind later through hooks. */
  onCreateAgent: ((input: {
    engine: AgentEngine
    cwd: string
    bypassPermission: boolean
    /** A grid to point this agent at instead of the engine's own login; null when none was chosen. */
    grid: GridLaunchOverride | null
    /** A Codex CODEX_HOME folder to launch this agent against instead of `~/.codex`; codex only. */
    codexHome: string | null
    /** A Claude CLAUDE_CONFIG_DIR folder (a profile) to launch this agent against; claude only. Absent for the default account. */
    claudeHome?: string | null
    /** The domain-specific harness to create this agent as (installed here, base engine = `engine`). */
    dsh: string | null
    /** The message the session opens with, already submitted (`FIRST_PROMPT_ARGS` in engineLaunch.ts);
     *  null when the pane opens on an empty input. Validated here — length, and that the engine has a
     *  contract for it — so cli.ts never sees one it cannot hand over. Never logged. */
    prompt: string | null
    /** Session-scoped built-in instructions for a newly launched Swarm agent: a coordinator, an agent or a Buddy. A launch an
     *  older CLI saved to finish later names it in the wire's values (lead, dev, review), which create.ts reads too. */
    swarmRole?: import('./lib/swarmSkills.js').SwarmRole
    /** With swarmRole `agent`: an older client's Reviewer, which keeps its swarm-review file. */
    swarmFallback?: 'review'
    /** The skills of the Swarm project it joins; absent from a start before modes, which launches on orchestration. */
    swarmSkillMode?: import('./lib/swarmSkills.js').SwarmSkillMode
    /** With swarmRole: git and gh use the Harness GitHub App's token for the agent's task (lib/swarmGitHub.ts). */
    swarmGitHub?: true
    /** The name the pane opens under, instead of the next `agent-N`; null to number it. */
    name: string | null
    /** The engine's named agent the pane opens AS (`NAMED_AGENT_ARGS` in engineLaunch.ts; opencode
     *  `--agent <name>`); null for a general session. Validated here — shape, and that the engine has
     *  a contract for it. Unlike `prompt`, kept on the row so a relaunch opens as it again. */
    agent: string | null
    /** A mode from `PERMISSION_MODES` for this engine; null when the client sent only
     *  `bypassPermission`, which then decides. Validated here (`INVALID_PERMISSION_MODE`). */
    permissionMode: string | null
    /** The model and effort to launch the engine with, for that session only (lib/launchModel.ts); absent when the
     *  engine should open on its own. Validated here, and only for an engine that declares the flags. */
    launchModel?: LaunchModel | null
    /** A conversation Harness did not start, to open this harness ON: the engine resumes it, in its own
     *  folder (lib/sessionSearch/external.ts). Null for a new conversation. Shape-checked here; cli.ts
     *  checks it is one it found, not open elsewhere, and not already a harness. */
    resumeSessionId?: string | null
    /** A conversation open in a terminal, taken over from it: `idle` stops that terminal's process
     *  only between turns, `now` whatever it is doing (then tells it to continue), `wait` when its
     *  turn ends. Absent, one open elsewhere is refused and the refusal says whether it is busy. */
    takeOver?: 'idle' | 'now' | 'wait' | null
    /** What the SCM that prepared `cwd` needs on every relaunch (registry `scmLaunch`). Present only
     *  when this create prepared a folder, and null when no SCM made it (a new folder, a clone). */
    scmLaunchRecord?: ScmLaunchRecord | null
    /** `agent` when another agent started it (`harness new` from its pane); absent for the person. Kept on the
     *  row: every launch of it adds a line to the pull requests it opens (lib/agentAttribution.ts). */
    startedBy?: StartedBy | null
    /** The harness here whose agent started it, when one in a Harness pane did (registry `parentAgentId`); only with
     *  `startedBy: 'agent'`. The windows open the new harness beside it and say who started it. */
    parentAgentId?: string | null
  }) =>
    Promise<{ ok: true; session: RegisteredSession } | { ok: false; error: string; detail?: string }>) | null = null
  /** Called on `remote_terminal_handoff` — cli.ts names the agent whose tile is that tmux pane, or null. */
  onTerminalHandoff: ((tmuxPane: string) => string | null) | null = null
  /** Share's observers, as the relay hands their frames over and drops them all with the link (services/sharing.ts,
   *  through its port). Null answers none, as a daemon without Share did. */
  observers: { receive(connId: string, type: string, payload: Record<string, unknown>): Promise<void> | void; closeAll(): void } | null = null
  /** What the daemon knows about an agent's DSH companions (viewer URL, verdict); null when nothing. */
  activityFrameProvider: ((session: RegisteredSession) => ActivityFrame | null) | null = null
  dshFrameProvider: ((session: RegisteredSession) => AgentDshContext | null) | null = null
  /** This machine's viewers, served to a client over its connection: the viewers' (core/viewerStreams.ts). */
  viewerStreams: ViewerStreams | null = null
  /** A viewer stream's frame to the one connection that opened it: false when it cannot reach it. */
  sendViewerFrame(connId: string, type: string, payload: Record<string, unknown>): boolean {
    if (this.localClients.has(connId)) { this.sendTo(connId, { type, payload }); return true }
    return this.throughGateway('viewer', (gateway) => gateway.target(connId, type, payload), false)
  }
  /** Injectable for queue-isolation tests; production uses the machine-local probe. */
  engineProbeProvider: typeof probeEngines = probeEngines
  readonly ownerCommands = new OwnerCommands()
  /** Takes back a delivered turn not yet being written (core/deliveries.ts, cli.ts binds core/input.ts). */
  onCancelOrchestratorMessage: ((deliveryId: string) => boolean) | null = null
  /** Every frame sent to the apps, as it is sent: the orchestrator reads its Directors' turns from them
   *  (services/orchestrator.ts, through its port). One that throws costs it that frame, never the apps. */
  onFrameSent: ((frame: Frame) => void) | null = null
  /** The account's notices the backend announces (`desk_changed`, …), for the experiments that hear them
   *  (Agent Messages reads its tabs again), as well as the windows here. */
  onAccountNotice: ((notice: BackendNotice) => void) | null = null
  /** An invitation given or taken back, which has the windows read the shares list (lib/spreadNotice.ts). */
  private readonly sharesNotice = spreadNotice(() => this.sendLocal({ type: 'machines_changed', payload: { reason: 'harness_shares' } }), SHARES_NOTICE_SPREAD_MS)
  /** What a shared tab's relay said (gateway/tabRelay.ts), for Agent Messages. */
  onTabFrame: ((event: TabFrame) => void) | null = null
  /**
   * Called on `agent_retarget` — cli.ts re-execs an EXISTING agent's pane against a different grid,
   * or, when `grid` is null, back onto its own login.
   *
   * Separate from `onCreateAgent` because it is a different promise: the pane, its id and its
   * scrollback survive, and only the process is replaced. A running process's environment cannot be
   * edited, so there is no gentler way to move an agent that is already up.
   *
   * Separate from a restart (core/agents/launches.ts) because that one puts the agent back exactly as it
   * was; this one puts it back somewhere else. They share the swap underneath and differ in what they
   * hand it.
   *
   * `fresh` (with a grid only): the relaunch starts a new conversation instead of resuming, and the one it
   * leaves on the own login is reopened by the move home (core/agents/retarget.ts).
   */
  onRetargetAgent: ((input: { agentId: string; grid: GridLaunchOverride | null; fresh?: boolean }) =>
    Promise<{ ok: true } | { ok: false; error: string; detail?: string }>) | null = null
  /** The requests that start an agent's process, answered through their last argument: `agent_create`,
   *  `agent_create_status`, `agent_resume` and `agent_restart`, and `agent_fork` (cli.ts binds
   *  core/agents/launches.ts). Null answers UNSUPPORTED_ON_REMOTE, or UNSUPPORTED for a status. */
  createProvider: ((payload: Record<string, unknown>, asker: Pick<Asker, 'local' | 'owner' | 'guest'>, reply: (result: Record<string, unknown>) => void) => Promise<void>) | null = null
  createStatusProvider: ((payload: Record<string, unknown>, asker: Pick<Asker, 'local' | 'guest'>, reply: (result: Record<string, unknown>) => void) => Promise<void>) | null = null
  cancelCreateProvider: ((payload: Record<string, unknown>, asker: Pick<Asker, 'local' | 'guest'>, reply: (result: Record<string, unknown>) => void) => Promise<void>) | null = null
  /** `asker.ownerApp`: the request is from the machine owner's own app (the Desktop, a paired app or browser), not a
   *  device, an agent's own CLI or a guest: only that one may change an agent's launch flags. */
  restartProvider: ((type: string, payload: Record<string, unknown>, reply: (result: Record<string, unknown>) => void, asker: { ownerApp: boolean }) => Promise<void>) | null = null
  forkProvider: ((payload: Record<string, unknown>, reply: (result: Record<string, unknown>) => void) => Promise<void>) | null = null
  /** Opens a NEW agent that starts with `agentId`'s whole history (lib/forkAgent.ts), exactly as
   *  `agent_create` does, for the fork requests and the cable. `level` says what the new agent actually
   *  got: the engine's own fork, or a handoff message. */
  onForkAgent: ((input: { agentId: string; name: string | null; prompt: string | null }) =>
    Promise<
      { ok: true; session: RegisteredSession; level: 'native' | 'handoff' }
      | { ok: false; error: string; detail?: string }
    >) | null = null
  /** Called when the web/device sends chat input to an agent terminal. */
  onMessage: ((sessionId: string, content: string, deliveryId?: string) => void) | null = null
  /** Takes a `message` frame: text a person typed for an agent, into its pane (cli.ts binds core/input.ts).
   *  Agent Messages and the orchestrator deliver through `onMessage` above. [receipt]: what became of it, for
   *  its request's measurement (lib/productUsageSignals.ts `messageReceipt`). */
  messageProvider: ((payload: Record<string, unknown>, receipt?: MessageReceipt) => void) | null = null
  /** Answers `agent_update` through its last argument, before the windows hear of the change: a rename, a
   *  model and effort, or an app opening the agent (cli.ts binds core/agents/update.ts). */
  agentUpdateProvider: ((payload: Record<string, unknown>, reply: (result: Record<string, unknown>) => void) => Promise<void>) | null = null
  /** Answers `question_response` through its last argument: a person's answer to an agent's question,
   *  keyed into the CLI's own dialog, since a remote machine has no programmatic answer channel the way
   *  the hosted runtime’s brain does (cli.ts binds core/questions.ts). Null answers nothing. */
  questionProvider: ((payload: Record<string, unknown>, reply: (result: Record<string, unknown>) => void) => void) | null = null
  /** Called when this machine was deleted/revoked (a `machine_revoked` down-frame, or a 401/403 on the
   *  upgrade) — CLI clears the saved SSO session and shuts down instead of retrying forever. */
  onRevoked: (() => void) | null = null
  /** Called with the machine's display name (`machine_meta` down-frame: seeded on connect, pushed on a
   *  web rename; null = unnamed) — cli mirrors it to a local file for `harness status`. */
  onMachineMeta: ((name: string | null) => void) | null = null
  /** Called when this machine is already connected from ANOTHER computer (HTTP 409 on the upgrade) — the
   *  SSO session is valid, so CLI keeps it and stops without a retry loop. */
  onBusy: (() => void) | null = null
  /** Answers `agent_recent` with the whole reply: an agent's last turn summaries and the person's last
   *  questions, for a device's tiles (cli.ts binds core/turns/recaps.ts). Null answers UNSUPPORTED. */
  agentRecentProvider: ((payload: Record<string, unknown>) => Record<string, unknown>) | null = null
  /** Answers `agents_list` through its last argument: every agent's frame, and its monitor readings when
   *  asked for (cli.ts binds core/agents/list.ts). The second argument reads the asker's paired role.
   *  Null answers UNSUPPORTED. */
  agentsProvider: ((payload: Record<string, unknown>, sessionRole: () => string | null,
    reply: (result: Record<string, unknown>) => void, guest?: string) => Promise<void>) | null = null
  /** The guest (email) an agent was started for, or null for the owner's own (registry `guest`): what a
   *  guest session may act on (core/guestPolicy.ts). Null treats every agent as the owner's. */
  agentGuest: ((agentId: string) => string | null) | null = null
  /** On a Harness Team daemon, what the account's own apps may ask and hear (core/api.ts RemoteAppPolicy): another person's
   *  Product Manager may run there, and the account is the Mac's owner's (#895). Null everywhere else. */
  remoteAppPolicy: RemoteAppPolicy | null = null

  /** The policy over [connId] when it is one of the account's own apps away from this desk: not a window here, nor a guest,
   *  which has its own space (core/guestPolicy.ts). A remote connection with no client record fails closed: it is held. */
  private appPolicyFor(connId: string): RemoteAppPolicy | null {
    if (!this.remoteAppPolicy || !connId || this.localClients.has(connId) || isLocalClientId(connId)) return null
    return this.remoteClient(connId)?.guest !== undefined ? null : this.remoteAppPolicy
  }

  /** Whether [connId] is one of the account's own apps away from this desk, held to watching its terminals now. */
  appWatchOnly(connId: string): boolean {
    return this.appPolicyFor(connId)?.watchOnly() ?? false
  }

  /** Whether [agentId]'s terminal is closed to [connId] now: a confidential session, to the account's own apps. */
  appClosedTo(connId: string, agentId: string): boolean {
    return this.appPolicyFor(connId)?.isConfidential(agentId) ?? false
  }
  /** Answers `session_get` with the whole reply: a conversation's history, a page at a time (cli.ts binds
   *  core/transcripts/history.ts). Null answers UNSUPPORTED. */
  historyProvider: ((payload: Record<string, unknown>) => Promise<Record<string, unknown>>) | null = null
  /** Answers `sessions_list` with the whole reply: the conversation an agent holds and how many lines it
   *  has (cli.ts binds core/transcripts/history.ts). Null answers UNSUPPORTED. */
  sessionsProvider: ((payload: Record<string, unknown>) => Promise<Record<string, unknown>>) | null = null
  /** How each agent's last turn ended, from the turn frames this socket sends: the monitor's activity
   *  once a turn is over (`agents_list`, core/agents/list.ts). */
  readonly monitorCompletions = new MonitorCompletions()
  /** The windows on this computer that draw row state (`grid_models_list` with `rowState: true`) and so
   *  are pushed labels as `unavailable` rather than in the node text. Kept here, by connection: the
   *  models service answers the list, and a request reaches it without its connection. */
  private readonly rowStateWindows = new Set<string>()
  /** Answers `terminal_info` through its last argument, once tmux has: what a harness's pane runs and
   *  where (cli.ts binds core/terminals/requests.ts). Null answers UNSUPPORTED. */
  terminalInfoProvider: ((payload: Record<string, unknown>, reply: (result: Record<string, unknown>) => void) => void) | null = null
  /** Answers `theme_set` with the whole reply: the desktop's pane colours, to become this machine's tmux
   *  `window-style` (cli.ts binds core/terminals/requests.ts). Null answers UNSUPPORTED. */
  themeProvider: ((payload: Record<string, unknown>) => Record<string, unknown>) | null = null
  /** A page a program in a harness's pane opens, and the sign-in a phone brings back from it
   *  (core/terminals/browser.ts, bound by core/main.ts). Null answers UNSUPPORTED. */
  browserProvider: {
    open: (payload: Record<string, unknown>) => Record<string, unknown>
    callback: (payload: Record<string, unknown>, connId: string) => Promise<Record<string, unknown>>
  } | null = null
  tokenUsageProvider: ((session: RegisteredSession) => AgentTokenUsage | null) | null = null
  runtimeProfileProvider: ((session: RegisteredSession) => string | null) | null = null
  /** Backend-resolved machine id, persisted by the SSO login preflight. */
  readonly machineId: string

  /** True while at least one device (commander) client is connected — gates the LLM recap. */
  hasCommander(): boolean {
    return this.commanderCount > 0
  }

  /** True while at least one connected device is ACTIVELY rendering this machine — gates the full turn-card
   *  STREAM (processing/tool/todos). The recap still runs on hasCommander(), so a BACKGROUND machine gets its
   *  turn-done `summary` card (badge) without the live stream. Falls back to hasCommander() against a
   *  backend that doesn't emit the signal (commanderActive === null). */
  hasActiveCommander(): boolean {
    return this.commanderActive == null ? this.hasCommander() : this.commanderActive > 0
  }

  /** True while a desktop window on THIS computer is attached over loopback.
   *
   *  Separate from `hasCommander()` on purpose: a device and a window are different audiences that
   *  happen to want some of the same work done. The question watcher is the first thing to need it —
   *  polling a pane for a dialog is pointless with nobody rendering it, but "nobody" used to mean
   *  "no device", which left the window unable to learn that an agent was blocked. */
  hasLocalClient(): boolean {
    return this.localClients.size > this.toolClients.size
  }

  /** True after a paired device has completed the E2EE hello/welcome session (`/api/status`). */
  deviceE2eeConnected(): boolean {
    return [...this.remoteClients.values()].some((client) => client.role === 'device')
  }

  /** True while an app away from this desk (the phone, a browser) holds an E2EE session over the relay: someone
   *  who hears how loudly a turn ends, with no device in sight (services/recaps.ts). */
  hasRemoteApp(): boolean {
    return [...this.remoteClients.values()].some((client) => client.role === 'web')
  }

  /** Live backend link state (`/api/status`), as the gateway last said. */
  isConnected(): boolean {
    return this.linkUp
  }

  /** A remote client the gateway holds a session with: its role and the label it was paired under. */
  remoteClient(connId: string): RemoteClient | null {
    return this.remoteClients.get(connId) ?? null
  }

  constructor(machineId: string, onStatus: (connected: boolean) => void = () => {}) {
    this.onStatus = onStatus
    this.machineId = machineId
  }

  /** The gateway this socket's remote clients come and go through: in this process, or a link to its own. */
  useGateway(gateway: GatewayPort): void {
    this.gatewayPort = gateway
    if (!this.requestsOpen) gateway.holdRequests()
    if (this.thisComputerOnly) gateway.serveThisComputerOnly()
    gateway.localClients(this.localWindows())
  }

  get gateway(): GatewayPort | null { return this.gatewayPort }

  /**
   * What the gateway tells the core. Each member is the core's half of what the socket did itself while it
   * held the link: a remote client's request goes through the same gate and the same per-connection order as
   * a window's, and what the backend said about this machine lands where the socket used to keep it.
   */
  readonly fromGateway: GatewayEvents = {
    frame: (connId, frame, transport, role) => this.enqueueDown(frame, connId, transport, role),
    binary: (connId, clear) => this.enqueueTerminalBinary(connId, clear),
    client: (connId, client) => {
      this.wifi?.session(connId, client)
      if (client) {
        const joined = client.role === 'web' && this.remoteClients.get(connId)?.role !== 'web'
        this.remoteClients.set(connId, client)
        // The client is registered whatever its replay does: a re-announce that throws costs only itself.
        if (joined) {
          try { this.onRemoteAppJoined?.() } catch (error) {
            console.warn(`[backend] re-announcing to a remote app failed: ${error instanceof Error ? error.message : String(error)}`)
          }
        }
        return
      }
      if (!this.remoteClients.delete(connId)) return
      this.viewerStreams?.closed(connId); this.ownerCommands.closeConnection(connId); this.onConnectionClosed?.(connId)
    },
    disconnected: async (connId) => {
      this.wifi?.dropped(connId)
      this.remoteClients.delete(connId)
      this.viewerStreams?.closed(connId); this.ownerCommands.closeConnection(connId); this.onConnectionClosed?.(connId)
      await this.terminalStreams?.closeConnection(
        connId,
        'client connection closed',
        false,
      )
    },
    observer: async (connId, type, payload) => { await this.observers?.receive(connId, type, payload) },
    toLocal: (connId, frame) => {
      if (connId) { this.sendLocalTo(connId, frame); return }
      for (const [id, sink] of this.localClients) if (!sink.sendFrame(frame)) void this.unregisterLocalClient(id)
    },
    status: (connected) => {
      this.linkUp = connected
      this.onStatus(connected)
    },
    linkDown: () => {
      this.observers?.closeAll()
      this.viewerStreams?.closedAll(); this.ownerCommands.closeAll(); for (const connId of this.remoteClients.keys()) this.onConnectionClosed?.(connId)
      void this.terminalStreams?.closeConnectionsWhere(
        (connId) => !isLocalClientId(connId),
        'backend disconnected',
        false,
      )
    },
    commanders: (count, active, recheck = false) => {
      const hadCommander = this.commanderCount > 0
      this.commanderCount = count
      this.commanderActive = active
      if (recheck) this.onCommanderPresenceChanged?.(this.hasCommander())
      else if (hadCommander !== (count > 0)) this.onCommanderPresenceChanged?.(count > 0)
    },
    commanderJoined: () => this.onCommanderJoin?.(),
    meta: (meta) => {
      if ('gridName' in meta) this.harnessGridName = meta.gridName ?? null
      if ('name' in meta) this.machineDisplayName = meta.name ?? null
      this.onMachineMeta?.(meta.name ?? null)
    },
    notice: (notice: BackendNotice) => {
      this.onAccountNotice?.(notice)
      // Only the Swarm host acts on these (superTabs/host.ts): the windows have nothing to re-read.
      if (notice.type === 'super_tab_deliveries' || notice.type === 'swarm_host_changed' || notice.type === '__terminal_waiting' || notice.type === '__deliveries_lease') return
      if (notice.type === 'machines_changed' && notice.reason === 'harness_shares') { this.sharesNotice.tell(); return }
      // A Swarm changed: its id, time and parts, or nothing for the server's word that it pushes (desktop swarm_pushes.dart).
      if (notice.type === 'swarm_changed') {
        const { type, ...payload } = notice
        this.sendLocal({ type, payload })
        return
      }
      this.sendLocal(notice.type === 'machines_changed' ? { type: notice.type, payload: { reason: notice.reason } }
        : notice.type === 'device_keys_changed' ? { type: notice.type, payload: {} }
          : { type: notice.type, payload: { revision: notice.revision } })
    },
    revoked: () => this.onRevoked?.(),
    busy: () => this.onBusy?.(),
    device: (connId, frame, opened) => this.wifi?.request(connId, frame, opened),
    deviceRevoked: (identity) => this.wifi?.revoked(identity),
    toWindows: (frame) => this.sendLocal(frame),
    tabFrame: (event) => this.onTabFrame?.(event),
  }

  /** The Wi-Fi device's sessions and requests, as the gateway hands them on, for its service with the
   *  devices (core/wifi.ts, services/wifi.ts). */
  private wifi?: WifiCore['fromGateway']
  /** Off on a Harness Team daemon (core/main.ts): the device's frames are sealed before anything here could filter them,
   *  and its own doors (core/wifiAgents.ts) reach every agent, so it would reach a Swarm Product Manager there (security
   *  re-check 2 of #2089). Nothing of it is wired, and nothing is sent to it. */
  private wifiOff = false
  disableWifi(): void { this.wifiOff = true; this.wifi = undefined }
  useWifi(wifi: WifiCore['fromGateway']): void { if (!this.wifiOff) this.wifi = wifi }
  /** The Wi-Fi device's answers and events, sealed to one session; and which identity's app said hello on
   *  one. Through the gateway, guarded as every frame of the core's is. */
  deviceFrame(connId: string, type: string, payload: Record<string, unknown>): void {
    if (this.wifiOff) return
    this.throughGateway('device', (gateway) => gateway.device(connId, type, payload), false)
  }
  deviceClient(connId: string, identity: string | null): void { this.toGateway('device', (gateway) => gateway.deviceClient(connId, identity)) }

  setTerminalStreamManager(manager: TerminalStreamManager): void {
    this.terminalStreams = manager
  }

  /** The account's private harness grid name, as the backend last reported it. Null until the first
   *  `machine_meta` lands, or when this account has none yet. */
  private harnessGridName: string | null = null

  /**
   * What the socket asks of models (core/api.ts `ModelsPort`): an agent's grid note for its frame, the
   * lists it pushes the windows, and where a move onto a grid model goes. Read on each use, since models
   * can be switched off or run in a process of its own; set by core/main.ts. Unset (tests), it reads as
   * models being off.
   */
  models: (() => Pick<ModelsPort, 'annotation' | 'lists' | 'moveTarget' | 'moved' | 'apiTarget'>) | null = null

  /** Set the account's private grid name from the reconcile that just confirmed it, so the RPCs
   *  answer with it at once rather than waiting for the next `machine_meta` (`lib/gridAttach.ts`). */
  setHarnessGridName(name: string | null): void { this.harnessGridName = name }

  /** Which grid this machine's agents can be pointed at — for `harness status`, the models service, and a
   *  relaunch that names it. The backend's word only: working one out is the models service's. */
  gridName(): string | null { return this.harnessGridName }

  /** This machine's name as the Machines list shows it — what a model it serves is labelled with. */
  machineName(): string | null { return this.machineDisplayName }

  /** `grid_models_changed` to the windows on this computer: the same payload `grid_models_list` answers,
   *  as the models service builds it from its pictures as they stand, each window in the form it asked
   *  for. On the models service's word: a read it did not wait for changed the list, a local model started
   *  or stopped, grid was set up. */
  async pushGridModels(): Promise<void> {
    if (this.closed || this.localClients.size === 0 || !this.models) return
    try {
      const { plain, rowState } = await this.models().lists()
      const forPlain: Frame = { type: 'grid_models_changed', payload: plain }
      const forRowState: Frame = { type: 'grid_models_changed', payload: rowState }
      this.sendLocal((connId) => this.rowStateWindows.has(connId) ? forRowState : forPlain)
    } catch { /* the next ask answers the same thing */ }
  }

  /** Dial the backend, through the gateway: this daemon is signed in. */
  connect(): void {
    this.gatewayPort?.connect()
  }

  async stop(): Promise<void> {
    this.closed = true
    this.sharesNotice.stop()
    this.closeAgentService?.dispose()
    this.viewerStreams?.closedAll(); this.ownerCommands.closeAll()
    await this.terminalStreams?.stop()
    await this.gatewayPort?.stop()
  }

  /** What the gateway does with a frame of the core's, guarded: a throw there (sealing one, say) costs
   *  the remote clients that frame, and never the windows on this computer or the caller. Before the
   *  gateway was its own part, a throw in the group key's wrap went up through `send()` into the event
   *  funnel and cost every consumer after the app's that turn's events (docs/design/2026-10-06-core-boundary-next.md,
   *  "If it dies"). Said at most once a minute, with how many were not. */
  private toGateway(what: string, call: (gateway: GatewayPort) => void): void {
    this.throughGateway(what, (gateway) => { call(gateway); return true }, false)
  }
  /** The same, for a send whose caller learns whether it went: a throw is a send that did not (a terminal
   *  stream then closes, as it does for a connection with no session). */
  private throughGateway(what: string, call: (gateway: GatewayPort) => boolean, otherwise: boolean): boolean {
    const gateway = this.gatewayPort
    if (!gateway) return otherwise
    try {
      return call(gateway)
    } catch (error) {
      const at = Date.now()
      if (at - this.gatewayFailureSaidAt < 60_000) { this.gatewayFailuresUnsaid++; return otherwise }
      console.error(`[backend] the gateway could not take a ${what} frame · ${error instanceof Error ? error.message : String(error)}${this.gatewayFailuresUnsaid ? ` · ${this.gatewayFailuresUnsaid} more since` : ''}`)
      this.gatewayFailureSaidAt = at
      this.gatewayFailuresUnsaid = 0
      return otherwise
    }
  }
  private gatewayFailureSaidAt = -Infinity
  private gatewayFailuresUnsaid = 0

  /** Send an up-frame (event or RPC reply) to every window here and to the WEB audience: the gateway seals
   *  what carries content and queues it while the link is down. */
  send(frame: Frame): void {
    this.monitorCompletions.observe(frame)
    // The orchestrator's state it cannot read (a full disk: reading makes its folder) must not cost every
    // frame after it (e2e/diskfull.e2e.ts).
    try { this.onFrameSent?.(frame) } catch { /* the frame goes out regardless */ }
    if (env.LOG_FRAMES) logFrame('→', 'web', frame)
    for (const [connId, sink] of this.localClients) {
      if (!sink.sendFrame(frame)) void this.unregisterLocalClient(connId)
    }
    this.toRemoteApps(frame)
  }

  /** An up-frame for the owner's apps away from this desk alone — the relay's web audience, sealed by the
   *  gateway when it carries content — and never the windows here, which are told through `sendLocal`. An
   *  agent's question goes both ways (core/questions.ts): `send` would add the tool connections too. */
  sendRemote(frame: Frame): void {
    if (env.LOG_FRAMES) logFrame('→', 'web', frame)
    this.toRemoteApps(frame)
  }

  /** An up-frame as the account's apps and devices away from this desk may have it (`remoteAppPolicy`), or null to withhold
   *  it: every path to them asks, the paired devices' and the Wi-Fi device's too (security re-review of #2089). */
  private forApps(frame: Frame): Frame | null {
    return this.remoteAppPolicy ? this.remoteAppPolicy.event(frame) : frame
  }

  /** Apps away from this desk get transcript events slim (lib/slimForRelay.ts), cut before the frame crosses to the
   *  gateway's process: no tool output, thinking text or image goes up the relay. The windows here got the whole event. */
  private toRemoteApps(given: Frame): void {
    if (this.thisComputerOnly) return
    const frame = this.forApps(slimForRelay(given))
    if (!frame) return
    const guest = this.frameGuest(frame)
    this.toGateway('web', (gateway) => gateway.broadcast(frame, guest ?? undefined))
  }

  /** The guest whose harness a frame is about (registry `guest`, through `agentGuest`), or null for the
   *  owner's own and for a frame about no harness. Its sessions are sent it sealed for each (gateway.ts). */
  private frameGuest(frame: Frame): string | null {
    const id = this.agentGuest ? eventAgentId(frame) : null
    return id ? this.agentGuest!(id) : null
  }

  /** Signed out: the cloud link is never dialed in this process's life (a sign-in restarts it), so nothing
   *  is handed to the gateway to seal or queue for it: every frame, a text_delta's among them, was sealed
   *  and queued for a link that never opens, two thousand deep. */
  serveThisComputerOnly(): void { this.thisComputerOnly = true; this.gatewayPort?.serveThisComputerOnly() }

  /** Send an up-frame to the LOOPBACK clients only — never to the cloud.
   *
   *  For things that describe what is happening at THIS desk rather than what the machine is doing: the
   *  dial is a physical object on one table, and a finger moving on its glass is meaningful to the window
   *  in front of it and to nothing else. `send()` fans out to the web audience as well, which would scroll
   *  a window on a computer the user is not sitting at. */
  /** One frame to every window on this computer — or, given a function, each window its own. */
  sendLocal(frame: Frame | ((connId: string) => Frame)): void {
    for (const [connId, sink] of this.localClients) {
      if (this.toolClients.has(connId)) continue
      const sent = typeof frame === 'function' ? frame(connId) : frame
      if (env.LOG_FRAMES) logFrame('→', 'local', sent)
      if (!sink.sendFrame(sent)) void this.unregisterLocalClient(connId)
    }
  }

  /** One frame to ONE window on this computer, if it is one. Never queued, never to the cloud. */
  sendLocalTo(connId: string, frame: Frame): boolean {
    const sink = this.localClients.get(connId)
    if (!sink) return false
    if (env.LOG_FRAMES) logFrame('→', 'local', frame)
    if (sink.sendFrame(frame)) return true
    void this.unregisterLocalClient(connId)
    return false
  }

  /** Ask one local desktop to select focus, without opening panes in every window. */
  sendFirstLocal(frame: Frame): boolean {
    for (const [connId, sink] of this.localClients) {
      if (this.toolClients.has(connId)) continue
      if (sink.sendFrame(frame)) return true
      void this.unregisterLocalClient(connId)
    }
    return false
  }

  /** Share's frame to one observer: plaintext to the relay, through the gateway. Share seals its own. */
  sendObserver(connId: string, type: string, payload: Record<string, unknown>): boolean {
    return this.throughGateway('observer', (gateway) => gateway.observer(connId, type, payload), false)
  }

  /** A frame to a window on this computer. A remote client's frames go through the gateway, which seals them. */
  sendTo(connId: string, frame: Frame): void {
    const local = this.localClients.get(connId)
    if (!local) return
    if (!local.sendFrame(frame)) void this.unregisterLocalClient(connId)
  }

  /** Pairwise terminal output is never queued across reconnect: the stream/lease is closed on link loss. */
  sendTerminalTo(connId: string, type: string, payload: Record<string, unknown>): boolean {
    const local = this.localClients.get(connId)
    if (local) return local.sendFrame({ type, payload })
    return this.throughGateway('terminal', (gateway) => gateway.terminal(connId, type, payload), false)
  }

  /** Binary terminal output/keyframe: in the clear to a window here, sealed by the gateway for anyone else. */
  sendTerminalBinaryTo(connId: string, clear: TerminalBinaryClear): boolean {
    const local = this.localClients.get(connId)
    if (local) {
      const frame = encodeTerminalLocal(clear)
      return frame ? local.sendBinary(frame) : false
    }
    return this.throughGateway('terminal', (gateway) => gateway.terminalBinary(connId, clear), false)
  }

  /** Send a user-level notification to every logged-in browser that owns this machine. */
  sendUser(frame: Frame): void {
    const shown = this.forApps(frame)
    if (shown) this.toGateway('user', (gateway) => gateway.user(shown))
  }

  /**
   * A tap on everything bound for a device, taken BEFORE E2EE wrapping.
   *
   * The dial on the USB cable is a second device audience, and it wants exactly what this one gets — the
   * same `commander_event` cards, in the same order, with the same recaps. Teeing here rather than adding
   * a parallel emit at each of the two dozen call sites is what keeps the two surfaces from drifting: a
   * new event kind reaches the cable the day it reaches the socket, without anyone remembering to add it.
   *
   * Plaintext on purpose: E2EE exists because the backend relays those frames. The cable relays nothing —
   * it is a wire the user physically owns, running to a process on their own computer.
   */
  onOutboundCommander?: (frame: Frame) => void

  /** Send a DEVICE-audience frame (commanderEligible, not web): the gateway seals user/data frames under
   *  the group key, so the backend relays only ciphertext; system/presence frames pass through. */
  sendCommander(frame: Frame): void {
    this.onOutboundCommander?.(frame)
    if (isLocalOnly(frame)) return
    const shown = this.forApps(frame)
    if (!shown) return
    if (env.LOG_FRAMES) logFrame('→', 'device', shown)
    // The sentence a processing card carries for the Pro's cable stays on this computer (onOutboundCommander).
    this.toGateway('device', (gateway) => gateway.commander(withoutUpdate(shown)))
  }

  /** Attach one authenticated loopback desktop client to the same RPC and event plane as cloud web. */
  registerLocalClient(connId: string, sink: LocalClientSink, opts: { tool?: boolean; surface?: WindowSurface } = {}): boolean {
    if (!isLocalClientId(connId) || this.localClients.has(connId)) return false
    const surface = opts.surface ?? 'desktop'
    // The app holds a connection per machine and dials again on every reconnect and link retry:
    // an open is its surface going from no window to one, not each connection (5,675 "desktop opens"
    // across 68 active installations on the first measured day).
    const firstOfSurface = !opts.tool && this.localWindows()[surface] === 0
    this.localClients.set(connId, sink)
    if (opts.tool) this.toolClients.add(connId)
    else if (opts.surface === 'tui') this.tuiClients.add(connId)
    this.gatewayPort?.localClients(this.localWindows())
    if (opts.tool) return true
    // The window is the person's session: the backend counts it, now or when the link next comes up.
    if (firstOfSurface) this.gatewayPort?.windowOpened(surface)
    this.onLocalClient?.(connId, true)
    return true
  }

  /** The windows attached now, per surface; tools are not windows. */
  private localWindows(): LocalWindows { return countWindows(this.localClients.size, this.toolClients.size, this.tuiClients.size) }

  /** A loopback client that said it is a tool (`harness pair`, the MCP server), not a window. */
  isToolClient(connId: string): boolean { return this.toolClients.has(connId) }

  /** The windows attached right now — for a listener that arrives after some of them did. */
  localClientIds(): string[] { return [...this.localClients.keys()].filter((connId) => !this.toolClients.has(connId)) }

  /** hn's own measurement of its flows (`product_observe`, consumed by localWsServer.ts): counted only
   *  for a connection that selected this computer as hn, into the gateway's product-usage queue, which
   *  counts nothing while it has none (signed out) or the account's choice is off. Never answered. */
  observeProduct(connId: string, payload: unknown): void {
    if (!this.tuiClients.has(connId)) return
    for (const metric of productObservation(payload)) this.toGateway('usage', (gateway) => gateway.usageCounter?.(metric))
  }

  /** Routes a request to the service that answers it, in its own process (core/serviceLinks.ts) or in
   *  this one (core/serviceHost.ts): false when none does and the socket answers it itself. */
  serviceRouter: ((type: string, payload: Record<string, unknown>, asker: Asker, reply: (result: Record<string, unknown>) => void) => boolean) | null = null
  /** A connection that asked the services something closed: they abort what it asked (`Asker.connection`). */
  onConnectionClosed: ((connId: string) => void) | null = null
  /** A window (or `hn`) on this computer attached or went away — the pair brain thinks only while one is here. */
  onLocalClient: ((connId: string, attached: boolean) => void) | null = null

  /** Release all connection-scoped state when the loopback WebSocket closes. */
  async unregisterLocalClient(connId: string): Promise<void> {
    if (!this.localClients.delete(connId)) return
    if (!this.toolClients.delete(connId)) this.onLocalClient?.(connId, false)
    this.tuiClients.delete(connId)
    this.rowStateWindows.delete(connId)
    this.viewerStreams?.closed(connId); this.ownerCommands.closeConnection(connId); this.onConnectionClosed?.(connId)
    // The last one leaving before any link could hear it attach: nothing happened, as far as the backend
    // is concerned, and the gateway does not tell a later link otherwise.
    this.gatewayPort?.localClients(this.localWindows())
    this.downChains.delete(connId)
    await this.terminalStreams?.closeConnection(connId, 'local client disconnected', false)
  }

  /** Route an authenticated local JSON frame through the existing per-client FIFO.
   *
   *  ⚠️ Tagged `'local'`, not left to default to `'relay'`. These frames come from a process on THIS
   *  machine over the local socket, and until they were tagged they arrived at `dispatchDown`
   *  indistinguishable from the backend's own — which let any local process send a frame only the
   *  backend is entitled to send. See the `machine_meta` branch there. */
  handleLocalFrame(connId: string, frame: Frame): void {
    if (!this.localClients.has(connId)) return
    this.enqueueDown(frame, connId, 'local')
  }

  /** The window's focused agent on this local connection — its terminal gets the short output window. */
  setLocalTerminalFocus(connId: string, agentId: string | null, visibleAgents?: readonly string[]): void {
    if (!this.localClients.has(connId)) return
    this.terminalStreams?.setFocusedAgent(connId, agentId)
    // Absent (an older desktop) stays null: that window keeps counting as looking.
    if (visibleAgents) this.terminalStreams?.setVisibleAgents(connId, visibleAgents)
  }

  /** Route an authenticated local terminal frame without applying cloud E2EE. */
  async handleLocalBinary(connId: string, frame: TerminalBinaryClear): Promise<void> {
    if (!this.localClients.has(connId)) return
    await this.terminalStreams?.handleBinary(connId, frame)
  }

  /** Hold requests at the gate until `openRequests`. The daemon calls this the moment it builds this
   *  socket, before anything can reach it; a socket built without it answers at once. */
  holdRequests(): void {
    if (!this.requestsOpen) return
    this.requestsOpen = false
    this.requestGate = new Promise<void>((resolve) => { this.openRequestGate = resolve })
    this.gatewayPort?.holdRequests()
  }

  /** Let requests through: every handler is wired and the agents the daemon restored are confirmed.
   *  Idempotent. Called once at the end of start-up — and by safe mode, so a daemon that could not
   *  start still answers rather than leaving its clients waiting. */
  openRequests(): void {
    if (this.requestsOpen) return
    this.requestsOpen = true
    this.waitingAtGate.clear()
    this.openRequestGate()
    this.gatewayPort?.openRequests()
  }

  /** A frame into its connection's order, behind the gate: a window's, or a remote client's the gateway
   *  opened, with the role its session proved. Resolves once it is handled. */
  private enqueueDown(frame: Frame, connId: string, transport: DownTransport, role: RemoteRole | null = null): Promise<void> {
    const key = connId || '__backend__'
    if (!this.requestsOpen) {
      const waiting = (this.waitingAtGate.get(key) ?? 0) + 1
      this.waitingAtGate.set(key, waiting)
      if (waiting > MAX_REQUESTS_BEFORE_READY && transport === 'local') {
        console.warn(`[backend] local client ${key} sent ${waiting} requests before the daemon was ready — closing it`)
        this.waitingAtGate.delete(key)
        void this.unregisterLocalClient(connId)
        return Promise.resolve()
      }
    }
    const type = frame.type
    // A stream's acknowledgements and heartbeats are bookkeeping that every other frame may be ordered
    // around (an ack for output a keyframe has since replaced is ignored), and one stuck behind a slow
    // request let unacknowledged output pile up to the pause mark (384 KiB): the screen stopped while the
    // connection waited on, say, `agents_list`.
    if (this.requestsOpen && typeof type === 'string' && TERMINAL_BOOKKEEPING_TYPES.has(type)) {
      return this.dispatchDown(frame, connId, transport, role).catch((err) => {
        console.error('[backend] down-frame dispatch failed:', err instanceof Error ? err.message : err)
      })
    }
    // An upload's begin and cancel go in line with its chunks, which ride the stream's input lane: a cancel
    // and a new begin let through while the old upload's chunks still waited there would have taken those
    // chunks into the new upload.
    const streamId = (frame.payload as { streamId?: unknown } | undefined)?.streamId
    if (transport !== 'local' && typeof type === 'string' && TERMINAL_UPLOAD_CONTROL_TYPES.has(type) && typeof streamId === 'string') {
      return this.inStreamLane(connId, streamId, () => this.dispatchDown(frame, connId, transport, role), 'down-frame')
    }
    const previous = this.downChains.get(key) ?? Promise.resolve()
    const next = previous
      .catch(() => { /* prior failure is already logged */ })
      .then(() => this.requestGate)
      .then(() => this.dispatchDown(frame, connId, transport, role))
      .catch((err) => {
        console.error('[backend] down-frame dispatch failed:', err instanceof Error ? err.message : err)
      })
      .finally(() => {
        if (this.downChains.get(key) === next) this.downChains.delete(key)
      })
    this.downChains.set(key, next)
    return next
  }

  /**
   * A remote client's terminal bytes, opened by the gateway: in their stream's order, and in nothing else's
   * (not gated: a stream exists only once a request through the gate opened it). They used to share the
   * connection's line with its requests, so a keystroke waited for whatever came before it: an
   * `agents_list` (1–2s with ~250 agents), a `session_get` (up to 5s for a cold engine reader), another
   * pane's keyframe (Codex: ~200ms and ~166KB at the median, daemon log 2026-10-13..15). Its own pane's
   * keyframe still holds the echo, as it holds all of that pane's output, but no longer the keystroke. A
   * window on this computer never waited (its bytes go straight to the streams, `handleLocalBinary`); a
   * phone now does not either. A paste still holds the keystrokes typed after it, and an upload's chunks
   * stay in line with its begin and cancel.
   */
  private enqueueTerminalBinary(connId: string, clear: TerminalBinaryClear): Promise<void> {
    const traced = env.TYPING_TRACE && clear.kind === TerminalBinaryKind.input
    const queuedAt = traced ? performance.now() : 0
    return this.inStreamLane(connId, clear.streamId, async () => {
      if (traced) console.log(`[typing] lane conn=${sid(connId)} stream=${sid(clear.streamId)} seq=${clear.seq} waited ${Math.round(performance.now() - queuedAt)}ms`)
      await this.terminalStreams?.handleBinary(connId, clear)
    }, 'binary terminal')
  }

  private inStreamLane(connId: string, streamId: string, task: () => Promise<void>, what: string): Promise<void> {
    const key = `${connId || '__backend__'}\0${streamId}`
    const previous = this.streamLanes.get(key) ?? Promise.resolve()
    const next = previous
      .catch(() => { /* prior failure is already logged */ })
      .then(task)
      .catch((err) => {
        console.error(`[backend] ${what} dispatch failed:`, err instanceof Error ? err.message : err)
      })
      .finally(() => {
        if (this.streamLanes.get(key) === next) this.streamLanes.delete(key)
      })
    this.streamLanes.set(key, next)
    return next
  }

  // ── down-frame dispatch (the hosted runtime-role RPC switch) ────────────────────────────────────────────

  /** Emit an RPC reply: in the clear to a window on this computer that asked; through the gateway to a
   *  remote client, which seals it to that client alone, or answers a bare E2EE_REQUIRED when it cannot
   *  (`GatewayPort.reply`). */
  private emitReply(connId: string, type: string, requestId: unknown, payload: Record<string, unknown>): void {
    const resultType = rpcResultType(type)
    // Before the E2EE wrap: an RPC reply is only readable here.
    if (env.LOG_FRAMES && !MESSAGE_REQUESTS.has(type) && !ROUTE_COMMAND_TYPES.has(type) && !type.startsWith('viewer_') && type !== 'phone_pair' && type !== 'api_connections' && type !== 'connectors' && type !== 'os_device' && type !== 'machine_addon' && type !== 'browser_open' && type !== 'browser_callback' && type !== 'orchestrator' && !type.startsWith('grid_fleet_') && type !== 'agent_read_file' && type !== 'project_preview' && type !== 'git_project_info' && type !== 'scm_project_info' && type !== 'git_pull_request' && type !== 'git_pull_requests_status' && type !== 'agent_handoff_prepare' && !SHARE_REQUEST_TYPES.has(type) && !type.startsWith('pair')) logFrame('→', connId ? `conn:${sid(connId)}` : 'backend', { type: resultType, payload: { requestId, ...payload } })
    if (this.localClients.has(connId)) {
      this.sendTo(connId, { type: resultType, payload: { requestId, ...payload } })
      return
    }
    // A window on this computer that has gone: its reply goes nowhere. What a window asked before it
    // closed is still carried out, and the replies used to fall through to the paths below: a plaintext
    // one such as `terminal_info_result` went out through `send()` to every other window and, unsealed,
    // into the relay's queue; the rest were queued for the relay as errors (e2e/windows.e2e.ts). Said
    // once per window, in the daemon's diagnostic mode only (it has no debug level of its own): a window
    // closing with requests in flight is ordinary.
    if (isLocalClientId(connId)) {
      if (env.LOG_FRAMES && this.goneReplyConn !== connId) console.log(`[backend] conn:${sid(connId)} has gone · its ${resultType} and later replies dropped`)
      this.goneReplyConn = connId
      return
    }
    this.toGateway('reply', (gateway) => gateway.reply(connId, type, requestId, payload))
  }

  /**
   * One frame, in its connection's order and past the gate: a window's or tool's on this computer
   * (`local`), or a remote client's, which the gateway admitted and opened (`relay`, `p2p`) with the role
   * of the session that sealed it. The relay's own rules (the backend's frames, default-deny, the E2EE
   * handshake) were the gateway's to apply before the frame got here (gateway/gateway.ts).
   */
  private async dispatchDown(frame: Frame, connId: string, transport: DownTransport = 'local', role: RemoteRole | null = null): Promise<void> {
    const type = frame.type as string | undefined
    if (!type) return
    // Whether this frame came from a process on THIS machine — the trust boundary the gates below
    // turn on. The membership half is a dispatch-time question about a connection that may already
    // be gone: frames run through a per-connId queue, so a local client that disconnects between
    // sending and being dispatched used to leave `localClients.has()` false, and its already-queued
    // frames were then read as the BACKEND's. The transport half closes that, because it is stamped
    // at enqueue by the caller that had just verified membership. Either one being true is local.
    // A local client is this OS user's: the Unix socket is 0600, and a TCP one showed the daemon's local
    // credential at the door (lib/localCredential.ts, hookServer.ts and localWsServer.ts).
    const local = transport === 'local' || this.localClients.has(connId)
    if (local) {
      // ⚠️ The backend's own instructions, refused from anywhere else. See BACKEND_ONLY_DOWN_TYPES.
      if (BACKEND_ONLY_DOWN_TYPES.has(type)) {
        console.warn(`[backend] ignoring ${type} from ${transport} (${connId}) — only the backend may send it`)
        return
      }
      // The backend hub's own control frames (`__clients`, `__client_disconnected`) are the gateway's to
      // hear, from the backend: a process on this computer was able to set how many devices watch it.
      if (type.startsWith('__')) {
        console.warn(`[backend] ignoring ${logSafeType(type)} from ${transport} (${connId}) — only the backend sends it`)
        return
      }
      // E2EE belongs to the relay: a window here speaks in the clear, and has no handshake to make.
      if (type.startsWith('e2e_')) {
        this.sendTo(connId, { type: 'local_protocol_error', payload: { error: 'LOCAL_E2EE_UNSUPPORTED' } })
        return
      }
      if (type === 'autonomous_device_request') return
    }
    if (type.startsWith('observer_')) return
    // Logged as opened (the gateway unwrapped a remote client's), so a down-frame reads as what the client
    // actually asked for rather than as an opaque __e2e envelope.
    // Terminal frames contain raw keystrokes, paste text and screen bytes after
    // unwrap. Never pass them to the frame logger, even in diagnostic mode.
    if (env.LOG_FRAMES && !MESSAGE_REQUESTS.has(type) && !ROUTE_COMMAND_TYPES.has(type) && !type.startsWith('terminal_') && !type.startsWith('viewer_') && !type.startsWith('grid_fleet_') && type !== 'agent_read_file' && type !== 'project_preview' && type !== 'git_project_info' && type !== 'scm_project_info' && type !== 'git_pull_request' && type !== 'git_pull_requests_status' && type !== 'agent_handoff_prepare' && type !== 'orchestrator' && type !== 'api_connections' && type !== 'connectors' && type !== 'os_device' && type !== 'machine_addon' && type !== 'browser_open' && type !== 'browser_callback' && type !== 'phone_pair' && !SHARE_REQUEST_TYPES.has(type) && !type.startsWith('pair')) {
      logFrame('←', connId ? `conn:${sid(connId)}` : 'backend', frame)
    }
    const launchMeasured = productUsageLaunch(type, (frame.payload as { creationId?: unknown } | undefined)?.creationId,
      signal => this.toGateway('usage', gateway => gateway.usageLaunch?.(signal)), (frame.payload as { engine?: unknown } | undefined)?.engine,
      (frame.payload as { startedBy?: unknown } | undefined)?.startedBy === 'agent')
    const usageSource = productUsageSource(local, !!connId && this.toolClients.has(connId), role, frame.payload)
    const measured = productUsageRequest(type, (metric) => this.toGateway('usage', (gateway) => gateway.usageCounter?.(metric)), Date.now, usageSource,
      (frame.payload as { userAction?: unknown } | undefined)?.userAction === true)
    productUsageIntent(type, (frame.payload as { usageIntent?: unknown } | undefined)?.usageIntent,
      (frame.payload as { agentId?: unknown } | undefined)?.agentId, usageSource,
      signal => this.toGateway('usage', gateway => gateway.usageLaunch?.(signal)))
    // A guest's own space is the guest policy's below; the account's own apps, away from this desk, answer to this one.
    const appPolicy = !local && connId && this.remoteClient(connId)?.guest === undefined ? this.remoteAppPolicy : null
    const reply = (t: string, rid: unknown, p: Record<string, unknown>): void => {
      if (t === type) {
        const failure = p.failure as { code?: unknown; reason?: unknown } | undefined
        measured(p.error ?? failure?.code, p.state, !!p.agent, p.ok, undefined, p.reason ?? failure?.reason)
        // The agent frame itself: a created launch's agent is watched until it starts (gateway/productUsage.ts).
        launchMeasured(p.error ?? (p.failure as { code?: unknown } | undefined)?.code, p.state, p.agent, (p.held as { service?: unknown } | undefined)?.service)
      }
      // The account's own apps see a reply as its policy shows it (`remoteAppPolicy`); a window here sees it whole.
      this.emitReply(connId, t, rid, appPolicy ? appPolicy.reply(t, p) : p)
    }
    // A guest: a session trusted only because this machine is shared with its account (gateway/gateway.ts).
    const guest = local ? undefined : this.remoteClient(connId)?.guest
    // Who may act as this machine's owner: a process here, or the owner's own paired app or browser, whose
    // session the gateway says is a `web` one. A device, an observer or a guest may not.
    const owner = local || (role === 'web' && guest === undefined)
    const lifecycleTarget = (frame.payload as { agentId?: unknown } | undefined)?.agentId
    if (typeof lifecycleTarget === 'string' && this.purgeAgentService?.busy(lifecycleTarget)
      && ['agent_close', 'agent_delete', 'agent_resume', 'agent_restart', 'agent_retarget', 'agent_update'].includes(type)) {
      reply(type, (frame.payload as { requestId?: unknown }).requestId, { error: 'DELETE_IN_PROGRESS' }); return
    }
    const payload = (frame.payload ?? {}) as Record<string, unknown>
    const requestId = payload.requestId
    const answer = (result: Record<string, unknown>): void => reply(type, requestId, result)

    // A guest gets its own space and nothing of the owner's: default-deny (core/guestPolicy.ts), before
    // anything else answers it — the services and the terminal streams included.
    if (guest !== undefined) {
      const verdict = guestVerdict(type, payload, guest, (agentId) => this.agentGuest?.(agentId) ?? null)
      if (!verdict.allow) {
        console.warn(`[guest] refused ${logSafeType(type)} from conn:${sid(connId)} — ${verdict.error}`)
        if (requestId !== undefined) reply(type, requestId, { error: verdict.error, message: GUEST_REFUSALS[verdict.error] })
        return
      }
    }
    if (appPolicy) {
      const refused = appPolicy.refuse(type, payload)
      if (refused) {
        console.warn(`[team] refused ${logSafeType(type)} from conn:${sid(connId)} — ${refused.error}`)
        if (requestId !== undefined) reply(type, requestId, refused)
        return
      }
    }

    // A paired owner can run the machine's orchestrator; observers and device sessions cannot.
    // Both requests and replies are encrypted, including project artifacts.
    if (ROUTE_COMMAND_TYPES.has(type)) {
      if (!owner) { reply(type, requestId, { error: 'OWNER_REQUIRED' }); return }
      void this.ownerCommands.request(connId, type, payload).then(result => reply(type, requestId, result))
      return
    }

    // Retired optional-feature requests remain reserved. Never reinterpret one as an
    // ordinary command or weaken its existing encryption / local transport boundary.
    if (PAIR_REQUESTS.has(type) || type === 'pair' || type === PLATE_REQUEST) {
      const error = type === 'pair' && !local ? 'LOCAL_ONLY'
        : type !== 'pair' && local ? 'REMOTE_ONLY' : 'UNSUPPORTED'
      reply(type, requestId, { error })
      return
    }

    if (type === 'viewer_surface') {
      if (!owner) return
      // Rendering and input never hold up terminal traffic on the ordered machine queue.
      void (this.viewerStreams?.surface(connId, payload) ?? Promise.reject(new Error('no viewers')))
        .then(result => reply(type, requestId, result))
        .catch(() => reply(type, requestId, { error: 'VIEWER_UNAVAILABLE' }))
      return
    }

    // Trust-group roster exchange: only over an E2EE session, from the identity that session proved, which
    // the gateway answers (gateway/gateway.ts). A window here has no identity to prove.
    if (type === 'group_sync') {
      reply(type, requestId, { error: 'UNSUPPORTED' })
      return
    }

    if (type.startsWith('viewer_')) {
      if (VIEWER_DOWN_TYPES.has(type) && owner) this.viewerStreams?.frame(connId, type, payload)
      return
    }

    // Which of a remote client's terminal streams ride its P2P channel is the gateway's, which noted this
    // frame's route as it opened it.
    if (type.startsWith('terminal_')) {
      const taken = this.terminalStreams ? await this.terminalStreams.handleFrame(connId, type, payload) : false
      // `terminal_info` (what a pane runs and where, which hn asks) is not a stream's: the streams pass
      // it over, and it is answered below. From hn's first release it stopped here unanswered
      // (e2e/compat.e2e.ts found it), and hn waited out its three seconds each time.
      if (taken || type !== 'terminal_info') return
    }

    // A request a service answers, in its own process or in this one: routed to it, or answered
    // SERVICE_UNAVAILABLE while it is off. Never waited on in line: the next frame is not held for it.
    // Who asked is established here, after the gates above, and the service trusts only that.
    const client = local ? null : this.remoteClient(connId)
    const asker: Asker = { local, owner, ...(!local ? { accountOwner: client?.accountOwner === true } : {}),
      ...(client?.machineId ? { machine: { machineId: client.machineId, label: client.label } } : {}),
      ...(guest !== undefined ? { guest } : {}),
      connection: connId, ...(typeof requestId === 'string' ? { requestId } : {}) }
    // A window that draws row state asks for the models list with `rowState`, and the list's changes are
    // pushed to it in that form (`pushGridModels`). Noted here, by connection: the models service answers
    // the list, and a request reaches it without its connection.
    if (type === 'grid_models_list' && payload.rowState === true && this.localClients.has(connId)) this.rowStateWindows.add(connId)
    if (this.serviceRouter?.(type, payload, asker, (result) => reply(type, requestId, result))) return

    try {
      switch (type) {
        // The Model Manager's grid commands' handshake (their protocol, longest timeout and thinking control),
        // answered here although the commands are the models service's (core/api.ts `MODELS_REQUESTS`): the
        // Grid harness sends `grid_fleet_run` only once it answers protocol 1 and reads anything else as
        // "update Harness", which a models service that is down must not make it say.
        case 'grid_fleet_capabilities':
          reply(type, requestId, { protocol: GRID_FLEET_PROTOCOL, gridCli: gridCliPresence(), maxTimeoutMs: GRID_FLEET_MAX_TIMEOUT_MS, thinkingControl: true })
          return
        // The pairings, which the gateway holds: a window here asks it through the core
        // (GATEWAY_REQUEST_TYPES), and a remote client's own requests never reach this switch.
        case 'device_e2ee_pair':
        case 'phone_pair':
        case 'e2ee_pairings_list':
        case 'e2ee_pairing_unpair':
        case 'e2ee_pairings_unpair_all':
          if (this.gatewayPort && GATEWAY_REQUEST_TYPES.has(type)) await this.gatewayPort.local(connId, frame)
          else if (requestId !== undefined) reply(type, requestId, { error: 'UNSUPPORTED' })
          return

        // The agents on this machine, live and, when asked, stopped (core/agents/list.ts, bound by cli.ts).
        case 'agents_list':
          if (this.agentsProvider) await this.agentsProvider(payload, () => (local ? null : role), answer, guest)
          else reply(type, requestId, { error: 'UNSUPPORTED' })
          return

        // The conversation an agent holds, and how long it is (core/transcripts/history.ts, bound by cli.ts).
        case 'sessions_list':
          reply(type, requestId, this.sessionsProvider ? await this.sessionsProvider(payload) : { error: 'UNSUPPORTED' })
          return

        // A conversation's history, a page at a time (core/transcripts/history.ts, bound by cli.ts).
        case 'session_get':
          reply(type, requestId, this.historyProvider ? await this.historyProvider(payload) : { error: 'UNSUPPORTED' })
          return

        case 'remote_terminal_handoff': {
          // `harness remote`, typed INSIDE one of this machine's terminal tiles, opened a terminal on
          // another machine and asks the window showing the tile to swap it over: the tile it was
          // typed in (named by its tmux pane, the one fact the shell has about itself) becomes the new
          // agent's, and the old shell is ended by the window. Asked over loopback only (the command
          // runs on this machine), but PUSHED to every audience: the window showing a tile of this
          // machine may be on another computer, reached through the relay — nothing in the payload
          // but ids, so it travels plain like dsh_install_status.
          if (!this.localClients.has(connId)) { reply(type, requestId, { error: 'UNSUPPORTED' }); return }
          const handoff = terminalHandoffRequest(payload)
          if (!handoff) { reply(type, requestId, { error: 'INVALID_HANDOFF', detail: 'remote_terminal_handoff needs tmuxPane (%N), machineId and agentId' }); return }
          const fromAgentId = this.onTerminalHandoff?.(handoff.tmuxPane) ?? null
          if (!fromAgentId) { reply(type, requestId, { error: 'NOT_A_HARNESS_PANE', detail: `${handoff.tmuxPane} is not a Harness terminal on this machine` }); return }
          // Who could hear it: other loopback clients (a window on this computer) and the web audience
          // (a window elsewhere, relayed). None means nobody is here to swap the tile.
          const windows = [...this.localClients.keys()].filter((id) => id !== connId).length + this.commanderCount
          this.send({ type: 'remote_terminal_handoff', payload: { fromAgentId, machineId: handoff.machineId, agentId: handoff.agentId } })
          reply(type, requestId, { ok: true, fromAgentId, windows })
          return
        }

        case 'engines_probe': {
          // Which engines this machine has, asked BEFORE a create rather than discovered by one
          // failing. Answered here — on the machine in question — because a Mac and the Docker rig
          // routinely hold different engines, and an availability list computed anywhere else is
          // wrong for exactly the remote case this request exists to serve.
          //
          // `engines` narrows the probe to what the caller is showing; an absent or malformed list
          // means "all of them", so an older app that sends nothing still gets a usable answer.
          const asked = Array.isArray(payload.engines)
            ? payload.engines.filter((id): id is AgentEngine =>
              typeof id === 'string' && (ENGINES as readonly string[]).includes(id))
            : undefined
          // A full probe starts interactive login shells and is intentionally detached from this
          // connection's ordered RPC chain. Request ids make its eventual reply safe to deliver out
          // of order; keeping it awaited here made a Create click sit behind an unrelated sweep.
          // A guest starts agents on its own sign-in, so it needs only which engines are installed: the
          // owner's sign-in and last use are never read for it (#4259, from #4216's security review).
          void this.engineProbeProvider(asked && asked.length > 0 ? asked : undefined, { accounts: guest === undefined })
            .then((availability) => reply(type, requestId, {
              engines: availability.map((entry) => ({
                engine: entry.engine,
                installed: entry.installed,
                command: entry.command,
                installable: entry.installable,
                installCommand: (entry.installable && installRecipeLine(entry.engine)) || null,
                ...(entry.signedIn !== undefined ? { signedIn: entry.signedIn, lastUsedAt: entry.lastUsedAt ?? null } : {}),
                // Static per-CLI-version capability, not a probe result: its mere presence is what
                // lets an older CLI (which never sends the field) keep reading as "unknown" rather
                // than "no", per the desktop app's `EngineAvailability.fromJson`.
                ...(entry.engine === 'codex' ? { supportsCodexHome: true } : {}),
                // Static too, and this machine's own: whether `harness new` here can hand the engine a
                // first prompt (engineLaunch.ts FIRST_PROMPT_ARGS), so a caller on another version reads
                // it from the machine that will start the agent (#1788).
                firstPrompt: supportsFirstPrompt(entry.engine),
                // Static too: a pane whose engine is still downloading beside Desktop Harness's setup
                // waits for that download (engineLaunch.ts `harness_wait_download`) rather than
                // installing it again, so the desktop may open the pane before the download ends.
                waitsForDownload: true,
              })),
            }))
            .catch(() => reply(type, requestId, { error: 'ENGINE_PROBE_FAILED' }))
          return
        }

        // An agent's last turn summaries and questions, for a device's tiles (core/turns/recaps.ts, bound by cli.ts).
        case 'agent_recent':
          reply(type, requestId, this.agentRecentProvider ? this.agentRecentProvider(payload) : { error: 'UNSUPPORTED' })
          return

        // A rename, a model and effort, or an app opening the agent (core/agents/update.ts, bound by cli.ts).
        case 'agent_update':
          if (this.agentUpdateProvider) await this.agentUpdateProvider(payload, answer)
          else answer({ error: 'UNSUPPORTED' })
          return

        // What became of a launch a creationId names (core/agents/launches.ts, bound by cli.ts).
        case 'agent_create_status':
          if (this.createStatusProvider) await this.createStatusProvider(payload, asker, answer)
          else answer({ error: 'UNSUPPORTED' })
          return

        case 'agent_create_cancel':
          if (this.cancelCreateProvider) await this.cancelCreateProvider(payload, asker, answer)
          else answer({ error: 'UNSUPPORTED' })
          return

        // A new agent (core/agents/launches.ts, bound by cli.ts).
        case 'agent_create':
          if (this.createProvider) await this.createProvider(payload, asker, answer)
          else answer({ error: 'UNSUPPORTED_ON_REMOTE' })
          return

        // Move a RUNNING agent onto a grid. The pane survives; its process is re-exec'd with the
        // engine's grid environment and, when one is bound, `--resume <session>` so the conversation
        // comes back. Refused rather than half-applied: see cli.ts for what it checks first.
        case 'agent_retarget': {
          const agentId = (payload.agentId as string | undefined) || (payload.sessionId as string | undefined)
          if (!agentId) { reply(type, requestId, { error: 'MISSING_AGENT_ID' }); return }
          if (!this.onRetargetAgent) { reply(type, requestId, { error: 'UNSUPPORTED_ON_REMOTE' }); return }
          const clear = payload.clearGrid === true
          // A new conversation is started on a grid or an API model; the own login reopens the one it left.
          const fresh = payload.fresh === true
          if (fresh && clear) {
            reply(type, requestId, { error: 'INVALID_GRID', detail: 'A fresh session starts on a grid or API model, not on the own login.' })
            return
          }
          // `gridModel` is the header picker's frame: a model id and nothing else. The endpoint and
          // the credential are resolved HERE, from this machine's own signed-in `grid`, so neither
          // ever crosses the relay and the app cannot be the source of truth for an address it does
          // not know. A client that sends the full `grid` object still works unchanged.
          const picked = typeof payload.gridModel === 'string' ? payload.gridModel : ''
          // `apiConnection` + `apiModel`: a model of an API saved on this machine. Same rule as a grid
          // model — the app names it, and the endpoint and key are read on this machine, from its store, by
          // the models service that keeps it (`ModelsPort.apiTarget`) — and only for whoever may manage those
          // APIs (`api_connections`): this machine's own app, or its owner's paired session. The key itself
          // never leaves this daemon either way.
          const api = typeof payload.apiConnection === 'string' ? payload.apiConnection : ''
          if (api && (picked || payload.grid !== undefined || clear)) {
            reply(type, requestId, { error: 'INVALID_GRID', detail: 'Choose an API model, a grid model or the own login, not several.' })
            return
          }
          if (api) {
            if (!owner) { reply(type, requestId, { error: 'OWNER_REQUIRED' }); return }
            const model = typeof payload.apiModel === 'string' ? payload.apiModel.trim() : ''
            const resolved = this.models ? await this.models().apiTarget({ connectionId: api, model }).catch(() => null) : null
            if (!resolved || !('target' in resolved)) {
              reply(type, requestId, {
                error: 'API_UNAVAILABLE',
                detail: resolved?.detail ?? 'The models service is not running, so this API cannot be used now. Try again in a moment.',
              })
              return
            }
            // An agent on it from now on reports that API's model, as when the socket read the store itself.
            payload.grid = resolved.target
          }
          if (picked && payload.grid === undefined && !clear) {
            // The grid the model was picked FROM, when the picker says (a shared grid's section); the
            // account's own grid otherwise. The models service sets grid up first and resolves the target.
            const named = typeof payload.gridName === 'string' && payload.gridName.trim() ? payload.gridName.trim() : null
            const moving = this.models ? await this.models().moveTarget({ gridName: named, model: picked }).catch(() => null) : null
            if (!moving || !('target' in moving)) {
              reply(type, requestId, { error: 'GRID_UNAVAILABLE', detail: moving?.detail ?? 'Models are unavailable. Try again.' })
              return
            }
            payload.grid = moving.target
          }
          const target = parseGridLaunchOverride(payload.grid)
          // Exactly one, and `clearGrid` is a separate field rather than `grid: null` on purpose:
          // parseGridLaunchOverride already answers `absent` for both undefined and null, so
          // overloading null would make "I forgot the field" and "I mean own login" the same frame.
          if (clear && target.state !== 'absent') {
            reply(type, requestId, { error: 'INVALID_GRID', detail: 'clearGrid and grid are mutually exclusive' })
            return
          }
          if (!clear && target.state !== 'ok') {
            reply(type, requestId, {
              error: 'INVALID_GRID',
              detail: target.state === 'invalid' ? target.reason : 'grid is required',
            })
            return
          }
          const override = target.state === 'ok' ? target.override : null
          const moved = await this.onRetargetAgent({ agentId, grid: override, ...(fresh ? { fresh: true } : {}) })
          if (!moved.ok) {
            reply(type, requestId, moved.detail ? { error: moved.error, detail: moved.detail } : { error: moved.error })
            return
          }
          reply(type, requestId, { retargeted: true })
          // The agent is on a grid model now and its pane is restarting: the models service starts that grid
          // meanwhile if it sleeps (issue 03). The move is done and answered. An API has no sleep to wake it
          // from, and is not a grid to look up.
          if (override && !isApiLaunch(override)) this.models?.().moved(override)
          return
        }

        // The agents no window shows, for a person to review before closing them (core/agents/close.ts).
        case 'agents_cleanup_preview':
          if (this.cleanupPreviewProvider) this.cleanupPreviewProvider(answer)
          else answer({ error: 'UNSUPPORTED' })
          return
        // A close now, once idle or after the task (core/agents/close.ts, bound by cli.ts).
        case 'agent_close':
          if (this.closeProvider) this.closeProvider(payload, answer)
          else answer({ error: 'UNSUPPORTED' })
          return
        // Permanent deletion, reviewed first (core/agents/lifecycle.ts, bound by cli.ts).
        case 'agent_worktree_delete':
        case 'agent_purge':
          if (this.purgeProvider) this.purgeProvider(type, payload, asker, answer)
          else answer({ error: 'UNSUPPORTED' })
          return
        // Stop Harness (core/agents/lifecycle.ts, bound by cli.ts).
        case 'agent_delete':
          answer(this.stopProvider ? await this.stopProvider(payload) : { error: 'UNSUPPORTED' })
          return

        // A saved conversation resumed, or a live process relaunched in its pane (core/agents/launches.ts).
        case 'agent_resume':
        case 'agent_restart':
          if (this.restartProvider) await this.restartProvider(type, payload, answer, { ownerApp: owner && !this.toolClients.has(connId) })
          else answer({ error: 'UNSUPPORTED_ON_REMOTE' })
          return

        // A second agent with the first one's history (core/agents/launches.ts, bound by cli.ts).
        case 'agent_fork':
          if (this.forkProvider) await this.forkProvider(payload, answer)
          else answer({ error: 'UNSUPPORTED_ON_REMOTE' })
          return

        // What a harness's pane runs and where (core/terminals/requests.ts, bound by cli.ts).
        // The `BROWSER` shim in a harness's pane, asking whether a phone takes the page. A process on this
        // computer only: from anywhere else it would be a way to put a page on someone's phone.
        case 'browser_open':
          if (!local) { answer({ error: 'LOCAL_ONLY' }); return }
          answer(this.browserProvider ? this.browserProvider.open(payload) : { handled: false })
          return

        // The redirect a phone caught for that page, replayed to the program waiting on this computer.
        case 'browser_callback':
          if (!owner) { answer({ error: 'OWNER_REQUIRED' }); return }
          if (!this.browserProvider) { answer({ error: 'UNSUPPORTED' }); return }
          answer(await this.browserProvider.callback(payload, connId))
          return

        case 'terminal_info':
          if (this.terminalInfoProvider) this.terminalInfoProvider(payload, answer)
          else reply(type, requestId, { error: 'UNSUPPORTED' })
          return

        case 'claude_login_status':
          // Legacy RPC name; report the selected agent's actual engine when one was supplied.
          {
            const target = (payload.agentId as string | undefined) || (payload.sessionId as string | undefined)
            reply(type, requestId, { loggedIn: true, engine: (target ? registry.resolve(target)?.engine : undefined) ?? 'claude', account: hostname() })
          }
          return

        // Text typed for an agent, into its pane (core/input.ts, bound by cli.ts).
        case 'message':
          if (this.messageProvider) this.messageProvider(payload, messageReceipt(measured))
          else console.warn('[backend] message handler is not wired; terminal input was not dispatched')
          return

        // A person interrupting an agent's turn (core/turns/cancel.ts, bound by cli.ts).
        case 'cancel': this.cancelProvider?.(payload); return

        // A person's answer to an agent's question, keyed into its dialog (core/questions.ts, bound by cli.ts).
        case 'question_response':
          this.questionProvider?.(payload, answer)
          return

        // The colours the desktop paints its panes with (core/terminals/requests.ts, bound by cli.ts).
        case 'theme_set':
          reply(type, requestId, this.themeProvider ? this.themeProvider(payload) : { error: 'UNSUPPORTED' })
          return

        default:
          // Unknown RPC with a requestId: reject fast so the web promise doesn't wait out its 20s.
          if (requestId !== undefined) reply(type, requestId, { error: 'UNSUPPORTED' })
          return
      }
    } catch (err) {
      // A service on the core boundary that failed or is off (core/serviceHost.ts): the host has logged
      // it, and the client may ask again — the service can be back after the daemon restarts.
      if (err instanceof ServiceUnavailableError) {
        console.warn(`[backend] ${type}: ${err.message}`)
        if (requestId !== undefined) reply(type, requestId, { error: 'SERVICE_UNAVAILABLE', service: err.service, retryable: true })
        return
      }
      console.error(`[backend] dispatch ${type} failed:`, err)
      if (requestId !== undefined) reply(type, requestId, { error: 'INTERNAL' })
    }
  }

  async publishStoppedAgent(s: RegisteredSession): Promise<void> {
    this.send({ type: 'agent_synced', payload: { agent: await this.toStoppedProject(s) } })
    this.sendCommander({ type: 'agent_deleted', payload: { agentId: s.agentId } })
  }

  /** A stopped agent's frame: no pane, no terminal, nothing to fork. */
  async toStoppedProject(s: RegisteredSession): Promise<AgentFrame> {
    const frame = await agentFrame(s, { selectedModel: s.model, terminalAvailable: false, dsh: this.dshFrameProvider?.(s) ?? null,
      tokenUsage: this.tokenUsageProvider?.(s) ?? null, gridAnnotation: this.gridAnnotation })
    return {
      ...frame,
      status: 'stopped',
      tmuxPane: null,
      terminal: { available: false, primary: '', runtimes: [] },
      viewerUrl: null,
      forkable: false,
    }
  }

  /** Map a registered tmux session onto the web's Project shape (tabs in ProjectTabs). */
  toProject(s: RegisteredSession): Promise<AgentFrame> {
    return agentFrame(s, {
      tokenUsage: this.tokenUsageProvider?.(s) ?? null,
      selectedModel: this.runtimeProfileProvider?.(s) ?? null,
      terminalAvailable: registry.terminalAvailable(s.agentId),
      dsh: this.dshFrameProvider?.(s) ?? null,
      activity: () => this.activityFrameProvider?.(s) ?? null,
      gridAnnotation: this.gridAnnotation,
    })
  }

  /** What an agent's frame says of the grid it is on: the models service's word, from memory. */
  private readonly gridAnnotation = (grid: Parameters<ModelsPort['annotation']>[0]): ReturnType<ModelsPort['annotation']> =>
    this.models?.().annotation(grid) ?? null
}