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.

32.7 KB
Raw Blame
/**
 * Which machine an agent is on, and getting a turn, a stop or an answer to it there: the turn router
 * across the owner's machines (docs/design/2026-10-03-harnessd.md, "Devices", step D0).
 *
 * It lived inside the dial's host (cable/cableHost.ts), so ⌘K and the window's voice route reached
 * another machine's agent only through the dial: with the dial off, ⌘K would have answered "no agent
 * list yet". It belongs to the fleet service now (services/fleet.ts), and ⌘K, the voice route and the
 * dial all send through one router, so who the person was just talking to (`lastRouted`) is one fact
 * for all three, as it was when the dial's host held it.
 *
 * Its own file, apart from the service that builds it, so the dial's host can build one over a bare
 * fleet (its tests, and a daemon whose fleet service is off) without loading the cloud socket and the
 * E2EE stores the service starts.
 */
import type { ForkResult, SendResult } from '../core/api.js'
import type { FleetRouting, ForkOutcome, SelectResult } from './fleet.js'
import { extendShortRecap } from '../lib/deviceRecap.js'
import { transcriptActivityAt } from '../lib/transcriptActivity.js'
import type { RegisteredSession } from '../lib/registry.js'
import type { RouterContinuity } from '../lib/voiceRouter.js'
import type { RecentTurn } from '../cable/cableHost.js'
import type { CableAgent, CableMachine, CableMachineSource } from '../cable/cableSession.js'
import { FleetError, type FleetMachine, type MachineFleet } from '../cable/machineFleet.js'
import type { AnswerReceipt, ReviewedAnswer } from '../cable/questionInbox.js'

export type { ForkResult, SendResult }

/**
 * This computer, as the router needs it: its identity, its agents, the window's tiles, and the doors a
 * turn, a stop or an answer for one of its own agents goes through. The dial's host fills it from its
 * wiring; the fleet service from the core (`CoreApi`).
 */
export interface FleetLocal {
  machineName(): string
  /** This computer's machineId, or '' when the daemon has never resolved one (signed out). */
  machineId(): string
  /** A stable id for this computer, used to name the local row when there is no machineId yet. */
  computerId(): string
  /** The live agents the apps are shown. */
  sessions(): RegisteredSession[]
  /** The name the apps show for an agent. */
  displayName(session: RegisteredSession): string
  /** The opaque runtime-v1 profile, which is where the dial's Model/Effort chips come from. */
  runtimeProfile?: (session: RegisteredSession) => string | null
  /** The window's tiles on its active tab, in tile order, as last reported. */
  desk(): string[]
  /** Deliver text into a local agent. The SAME path the web and the WiFi device use. */
  sendTurn: (agentId: string, text: string) => void
  stopTurn: (agentId: string) => void
  answer: (agentId: string, requestId: string, answers: Record<string, string>) => void
  answerReviewed?: (answer: ReviewedAnswer) => Promise<boolean>
  /** Recaps of a local agent's last `n` completed turns. */
  recent: (agentId: string, n: number) => RecentTurn[] | Promise<RecentTurn[]>
  /** The person's own last questions to a LOCAL agent, newest first. */
  recentAsks: (agentId: string) => string[] | Promise<string[]>
  /** Read this computer's agents again before a list is built from them: the devices in their own process
   *  keep a copy of them, asked of the core when the dial's tick or ⌘K needs it. */
  refresh?: () => Promise<void>
  updateAgent?: (agentId: string, model?: string, effort?: string) => void
  listModels?: (agentId: string) => Promise<Array<{ id: string }>>
  /** Fork a LOCAL agent — see lib/forkAgent.ts. Resolves to the new agent's id. */
  forkAgent?: (agentId: string) => Promise<ForkResult>
  log: (line: string) => void
}

/**
 * A placeholder id for a machine this daemon does not know the real id of.
 *
 * A BELT, not a mode. `harness start` refuses to run without an SSO session and awaits
 * `resolveComputerMachine()` before it spawns the daemon, so by the time anything here runs the machineId
 * is real. The guard exists because the alternative failure is silent: an empty id makes a row that
 * renders, is tappable, and can never be selected. `cable:` is deliberately not machineId-shaped, so
 * nothing downstream mistakes it for one and announces it to the backend.
 */
function placeholderId(computerId: string): string {
  return `cable:${computerId}`
}

/** How often another machine's agent list is re-asked. Far slower than the dial's one-second tick: the
 *  list changes when a person starts an agent, not continuously. */
const REMOTE_REFRESH_MS = 5_000
/** How long a machine's last good list survives failures before its tiles leave the carousel. */
const REMOTE_GRACE_MS = 30_000
/** How the lane says an agent list went unanswered (DeviceLink.rpc). Every other failure of a list the machine
 *  answered during is its answer: a refusal. */
const LIST_TIMED_OUT = 'agents_list timed out'

/** Each other machine's agents, as last read. `asked` throttles the round; `at` ages the answer; `refusedSince` is the
 *  machine's first refusal of a list since its last good one. */
interface RemoteList { agents: CableAgent[]; at: number; asked: number; refusedSince?: number }

/** A fleet row as the wire carries it. `authMode` does not travel: the dial has no use for the word, and
 *  `remote` is just `!local`, which the row already says. */
function toCableMachine(m: FleetMachine): CableMachine {
  return { id: m.machineId, name: m.name, state: m.state, local: false }
}

/** Split `runtime-v1:<sid>:<engine>:<model>@<effort>` back into the two words the dial's chips show. */
function chipsFromProfile(profile: string | null | undefined): { model?: string; effort?: string } {
  if (!profile || !profile.startsWith('runtime-v1:')) return {}
  const tail = profile.split(':').slice(3).join(':')
  if (!tail) return {}
  const [model, effort] = tail.split('@')
  return { model: model || undefined, effort: effort || undefined }
}

export class FleetRouter implements FleetRouting {
  /** The last turn this daemon delivered, for [lastRouted]. In memory only: a conversation that spans a
   *  daemon restart is not one the five-minute window would have carried anyway. */
  private lastTurn?: { agentId: string; at: number }

  /** Each other machine's agents, as last read (RemoteList). */
  private readonly remoteAgents = new Map<string, RemoteList>()
  /** Machines with a list RPC in flight, so a slow machine is asked once rather than every tick. */
  private readonly inFlight = new Set<string>()
  /** agentId → machineId, rebuilt from the snapshot last handed to the dial. */
  private agentMachine = new Map<string, string>()

  /**
   * Every agent this daemon has listed since it started, by id.
   *
   * Kept for ONE purpose: a tile open in the window must always be a tile on the dial. A machine can
   * leave the list for reasons that have nothing to do with its agents — the backend going quiet, the
   * machine going offline while its work stays on screen — and a desk with a hole in it makes a swipe
   * skip a tile and an agent chosen in the window have nowhere to land.
   */
  private readonly knownAgents = new Map<string, CableAgent>()

  /** Tiles currently held on the list from that memory, so it is logged once and not every tick. */
  private readonly deskHeld = new Set<string>()

  /** Size of the last flat list — see agentTotal. */
  private flatCount = 0

  /** agentId → machineId for agents heard from but not (yet) listed — see noteAgent. */
  private readonly seenOn = new Map<string, string>()
  /** machineId → name, from the last wheel read, for describe(). */
  private machineNames = new Map<string, string>()

  /** `fleet` undefined = no lane to any other machine exists; every agent is this computer's. */
  constructor(private readonly local: FleetLocal, readonly fleet?: MachineFleet) {}

  /** This computer's id, or the placeholder when it has none yet. */
  localId(): string {
    return this.local.machineId() || placeholderId(this.local.computerId())
  }

  async listMachines(): Promise<{ machines: CableMachine[]; source: CableMachineSource }> {
    const local: CableMachine = {
      id: this.localId(),
      // The machine's own name. What makes this row recognisable as the cabled one is its second line,
      // which the dial writes — see machine_meta_line.
      name: this.local.machineName(),
      // Always ready: the cable IS the evidence. Nothing else on this list can say that about itself.
      state: 'ready',
      local: true,
    }
    if (!this.fleet) return { machines: [local], source: 'signed-out' }
    const { machines, source } = await this.fleet.list()
    const rows: CableMachine[] = [local]
    for (const m of machines) {
      // The backend list contains THIS computer too. Dropped rather than rendered: the same machine on
      // the wheel twice, under two names, with the ✓ able to mark only one of them. Its name is already
      // here anyway — MACHINE_NAME_FILE is mirrored from the backend on every connect.
      if (m.machineId === local.id) continue
      rows.push(toCableMachine(m))
    }
    return { machines: rows, source }
  }

  /** This computer's own agents, in the order every other surface reads them in. */
  private localAgents(): CableAgent[] {
    // `advertised()`, not `list()` — the SAME set `agents_list` answers the web and the desktop app with. They
    // read one registry and must not disagree about what is on it: a dead agent holding a tile on the dial
    // and nowhere else is a tile that cannot be driven and cannot be explained.
    // Terminals INCLUDED. A shell has no turn to watch and no model to switch, and the dial does not
    // pretend otherwise — it draws the tile and offers no Voice on it. What it does offer is the
    // thing that was missing: the tile can be reached. The window draws a shell as a tile like any
    // other, so a dial that skipped it disagreed with the app about what was on the desk, and a pane
    // the carousel cannot walk to is a pane the dial cannot explain either. A terminal that has
    // adopted an engine is that engine here, as everywhere.
    //
    // ⚠️ NOT the same question as `deviceAgentRow` in core/agents/list.ts, which keeps shells out of the
    // `agents_list` RPC a CLOUD device asks over the backend. This is the cable's own list, pulled by
    // `listAgents()` on the session's tick; the two surfaces answer separately and always did.
    const sessions = this.local.sessions()
    // Oldest → newest, and TOTAL: the id breaks a tie so the order cannot fall through to array position,
    // which is Map insertion order and differs between daemon runs. Both producers sort identically, so
    // the dial and the app cannot drift apart while reading the same registry.
    sessions.sort((a, b) => a.registeredAt - b.registeredAt || a.agentId.localeCompare(b.agentId))
    const machineId = this.localId()
    const machine = this.local.machineName()
    return sessions.map((s) => ({
      id: s.agentId,
      name: this.local.displayName(s),
      engine: s.engine ?? '',
      machineId,
      machine,
      ...chipsFromProfile(this.local.runtimeProfile?.(s)),
    }))
  }

  /**
   * Name, engine and machine of an agent this daemon has ever listed — for a `summary` or `question`
   * about one the dial no longer holds. The dial used to look these up in its own copy of the fleet;
   * with that copy gone, the frame has to say who it is about.
   */
  describe(agentId: string): { name: string; engine: string; machine: string } | undefined {
    const a = this.knownAgents.get(agentId) ?? this.localAgents().find((x) => x.id === agentId)
    if (a) return { name: a.name, engine: a.engine ?? '', machine: a.machine ?? '' }
    // A remote agent whose machine has spoken (a question, a card) before its list was ever read: no
    // name to give, but the machine's is better than nothing on a screen asking for a decision.
    const machineId = this.seenOn.get(agentId)
    const machine = machineId ? this.machineNames.get(machineId) ?? '' : ''
    return machineId ? { name: '', engine: '', machine } : undefined
  }

  /**
   * A card arrived from a machine for an agent. Remembered so a `question` or `summary` about an agent
   * this daemon has never LISTED — a remote machine's, before its list was read, or one on a tab the
   * window has not opened — can still be described and, when tapped, opened: `machineOf` falls back to
   * this, and without it the open was "ignored for unknown agent" and the tap did nothing.
   */
  noteAgent(machineId: string, agentId: string): void {
    if (machineId && agentId) this.seenOn.set(agentId, machineId)
  }

  /**
   * EVERY agent in LIST order — this computer first, then each machine in wheel order — the fleet the
   * dial no longer holds.
   *
   * It is the order the desktop app's rail draws, and the two must not drift: ⌘K reads this to decide
   * which agents a typed task is weighed against, and a person looking at their rail while they type has
   * every right to expect "the first fifteen" to mean the first fifteen they can see. The dial's
   * `listAgents()` is its view of the same snapshot — the same agents, re-cut around the tiles the window
   * has open, which is a different question with a different right answer.
   *
   * Read from a CACHE, never from a live RPC. The dial calls this on the session's one-second tick, and a
   * naive implementation would fire one cloud round trip per machine per second — the dial would spend
   * its whole life waiting on the network to answer a question whose answer changes every few minutes.
   * `refreshRemotes()` does the asking, off to the side, on its own slower clock.
   */
  async listAgentsFlat(): Promise<CableAgent[]> {
    await this.local.refresh?.()
    const out = this.localAgents()
    const { machines } = await this.listMachines()
    this.machineNames = new Map(machines.map((m) => [m.id, m.name]))
    for (const m of machines) {
      if (m.local) continue
      const entry = this.remoteAgents.get(m.id)
      if (entry) for (const a of entry.agents) out.push({ ...a, machineId: m.id, machine: m.name })
    }
    this.refreshRemotes(machines)
    // Rebuilt from the SAME snapshot that is about to be pushed, so the map can never name a machine an
    // agent has already left. Every action the dial can take is routed through it.
    const next = new Map<string, string>()
    for (const a of out) if (a.machineId) next.set(a.id, a.machineId)
    this.agentMachine = next

    const byId = new Map(out.map((a) => [a.id, a]))

    for (const a of out) this.knownAgents.set(a.id, a)
    // A tile the window has open, whose agent has left the list. Put it back — under the name and
    // machine it was last seen with, so the dial's tile keeps saying what the window's tile says.
    //
    // Gated on being ON THE DESK, and only that: an agent that was deleted, or one simply never
    // opened, must not be resurrected by this memory. The window holding a tile is the whole warrant.
    const missing = this.local.desk().filter((id) => !byId.has(id))
    for (const id of missing) {
      const remembered = this.knownAgents.get(id)
      if (!remembered) continue
      // Appended, not slotted back where it was. When a machine drops out none of its agents are left
      // to sit beside, so the end of the list is the only honest place; the tab's list is drawn in TILE
      // order by the dial's listAgents, so where it sits here does not matter. Never routed by position
      // either — `agentMachine` below is what sends a turn home.
      out.push(remembered)
      byId.set(id, remembered)
      if (remembered.machineId) this.agentMachine.set(id, remembered.machineId)
      if (!this.deskHeld.has(id)) {
        this.deskHeld.add(id)
        this.local.log(`cable: holding ${id.slice(0, 8)} on the tab — the window has a tile for it`)
      }
    }
    for (const id of [...this.deskHeld]) if (!missing.includes(id)) this.deskHeld.delete(id)

    // The overview's number is AGENTS, and a shell is not one. The carousel carries shell tiles now —
    // they are panes the window has and the dial can reach — but "12 agents · all idle" is read as how
    // much work is in flight, and counting empty terminals in it would answer a question nobody asked.
    // Two different numbers about the same desk, each honest about what it counts.
    this.flatCount = out.filter((a) => a.engine !== 'terminal').length
    return out
  }

  /**
   * When each local agent last did something: its transcript's last event, else its last hook. Unlike
   * agentFrame's `lastActivityAt`, never its creation: the Pro's Recent lists agents that had a task, and one
   * that never did has no time here. Another machine's agents are not known here.
   */
  async activityTimes(): Promise<Map<string, number>> {
    const out = new Map<string, number>()
    await Promise.all(this.local.sessions().map(async (s) => {
      const at = await transcriptActivityAt(s.transcriptPath, s.engine) ?? s.lastHookAt
      if (at) out.set(s.agentId, at)
    }))
    return out
  }

  /** How many agents the account has across every machine — the overview's number, sent beside the
   *  tab's list rather than as 70 rows the dial would hold for a digit. Read from the last flat list,
   *  minus the terminals in it: the list is every TILE, this is every AGENT. */
  agentTotal(): number {
    return this.flatCount
  }

  /**
   * Which machine an agent lives on, or '' if the dial named one this daemon has never listed.
   *
   * NEVER falls back to the selected machine. A wrong answer here does not fail — it delivers the user's
   * turn to a different computer, which is the worst outcome this whole feature can produce.
   */
  machineOf(agentId: string): string {
    return this.agentMachine.get(agentId) ?? this.seenOn.get(agentId) ?? ''
  }

  /** Whether this daemon's last list held that agent — see CableHost.knows. */
  knows(agentId: string): boolean {
    return this.agentMachine.has(agentId)
  }

  /** True when the agent belongs to this computer (or is unknown, which is handled at the call site). */
  isLocalAgent(agentId: string): boolean {
    const machineId = this.machineOf(agentId)
    return !machineId || machineId === this.localId()
  }

  /**
   * Fork an agent on its own machine: the same `agent_fork` the window sends. The new agent is noted on
   * that machine at once, so the open that follows lands before any list has named it. The outcome says
   * which machine was asked, and whether anyone was: a refusal before asking (an agent never listed, a
   * daemon or a fleet that cannot fork) is only an answer.
   */
  async forkAgent(agentId: string): Promise<ForkOutcome> {
    const machineId = this.machineOf(agentId)
    const refused = (result: ForkResult): ForkOutcome => ({ result, machineId, asked: false })
    if (!machineId) return refused({ ok: false, error: 'AGENT_NOT_FOUND', detail: 'The dial named an agent this daemon has never listed.' })
    let result: ForkResult
    if (this.isLocalAgent(agentId)) {
      if (!this.local.forkAgent) return refused({ ok: false, error: 'UNSUPPORTED', detail: 'This daemon cannot fork agents.' })
      result = await this.local.forkAgent(agentId)
    } else {
      if (!this.fleet?.forkAgent) return refused({ ok: false, error: 'UNSUPPORTED_ON_REMOTE' })
      try {
        result = { ok: true, agentId: await this.fleet.forkAgent(machineId, agentId) }
      } catch (err) {
        result = { ok: false, error: 'FORK_FAILED', detail: (err as Error).message }
      }
    }
    if (result.ok) this.seenOn.set(result.agentId, machineId)
    return { result, machineId, asked: true }
  }

  // ── the lane, held while a dial is plugged in ───────────────────────────────────────────────────

  hasLane(): boolean {
    return !!this.fleet
  }

  /** Come online for a dial — see MachineFleet.online. A lane that will not open is an answer: the dial
   *  says so in its log and carries on with this computer. */
  async online(): Promise<{ ok: true } | { ok: false; message: string; code?: string }> {
    try {
      await this.fleet!.online()
      return { ok: true }
    } catch (err) {
      // Why it failed, when the lane says (machineFleet.ts LANE_*): whether the dial tries again turns on it.
      const code = (err as { code?: unknown }).code
      return { ok: false, message: (err as Error).message, ...(typeof code === 'string' && code ? { code } : {}) }
    }
  }

  /** Attach to a machine, which is also how the backend learns where the dial is. A refusal comes back with
   *  the code the dial acts on and the words it shows; anything else unexpected reads as unreachable. */
  async select(machineId: string): Promise<SelectResult> {
    try {
      await this.fleet!.select(machineId)
      return { ok: true }
    } catch (err) {
      if (err instanceof FleetError) return { ok: false, code: err.code, message: err.message }
      return { ok: false, code: 'UNREACHABLE', message: (err as Error).message }
    }
  }

  /** Let go of what `select` acquired; `immediate` when the dial is gone — see MachineFleet.release. */
  release(immediate?: boolean): void {
    this.fleet?.release(immediate)
  }

  /**
   * Refresh the other machines' agent lists, on their own clock.
   *
   * Only `ready` machines are asked. An offline one has nothing to say and an unlinked one cannot be
   * read at all (no pinned key), and asking either costs a 15-second RPC timeout per machine per round.
   *
   * A machine that fails keeps its LAST GOOD list for `REMOTE_GRACE_MS` and only then goes empty. A cloud
   * blip is the common case, and dropping every one of a machine's tiles off the carousel for a few
   * seconds — then putting them back — is a far worse lie than briefly showing a list that is a minute
   * old.
   *
   * A machine that answers under its own session is up, and how its list failed says why. Timed out: it is
   * slow, and its tiles stay however long that lasts (Diego, 10-30, #2381). Answered with an error: it is
   * refusing, and its tiles keep the same grace, counted from its first refusal since its last good list
   * (#2381's second review: without that, a machine that refuses every list kept its tiles for ever).
   *
   * A list still out when its machine goes offline, loses its link or leaves the list changes nothing when it
   * lands: the tiles that machine had are gone, and only a list asked after it is back brings them again.
   *
   * `unknown` is NOT a reason to drop anything, and reading it as one cost a morning. It means the
   * backend could not be asked — `MachineListCache.degrade()` sets every machine to it in one go when
   * the list cannot be refreshed, on the stated principle that the rows are "stale but not wrong". The
   * agents follow the rows: kept, with no timer, until the backend actually says offline. Measured on
   * the real dial, the old reading emptied a remote machine off the carousel mid-session with no log
   * line, while the window went on showing those agents — which is what made a swipe run out of agents
   * early, and an agent chosen in the window have no tile to move to.
   */
  private refreshRemotes(machines: CableMachine[]): void {
    if (!this.fleet) return
    const fleet = this.fleet
    const now = Date.now()
    // Gone from the list (unlinked, its access revoked, signed out): what it said is not kept for its return.
    const listed = new Set(machines.map((m) => m.id))
    for (const id of [...this.remoteAgents.keys()]) if (!listed.has(id)) this.remoteAgents.delete(id)
    for (const m of machines) {
      if (m.local) continue
      const entry = this.remoteAgents.get(m.id)
      if (m.state === 'offline' || m.state === 'needs-link') {
        // The machine ITSELF says it has nothing to offer, which is different from not being able to
        // ask it. No grace period, but never silently: an agent leaving the carousel is exactly the
        // event that is impossible to diagnose after the fact from its absence.
        // Replaced even when empty, so a list still out from before it went cannot fill it when it lands.
        if (entry) this.remoteAgents.set(m.id, { agents: [], at: now, asked: entry.asked })
        if (entry?.agents.length) {
          this.local.log(`cable: ${m.name} is ${m.state} — its ${entry.agents.length} agents left the carousel`)
        }
        continue
      }
      // Not ready and not refused: the backend could not be asked. Keep what it last said.
      if (m.state !== 'ready') continue
      if (entry && now - entry.asked < REMOTE_REFRESH_MS) continue
      if (this.inFlight.has(m.id)) continue
      this.inFlight.add(m.id)
      // This entry, replaced only when the machine goes offline, loses its link or leaves the list, is what its
      // answer may change: one that lands after is about tiles no longer shown.
      const asking: RemoteList = { agents: entry?.agents ?? [], at: entry?.at ?? 0, asked: now, refusedSince: entry?.refusedSince }
      this.remoteAgents.set(m.id, asking)
      void fleet.listAgents(m.id)
        .then((agents) => {
          if (this.remoteAgents.get(m.id) !== asking) return
          this.remoteAgents.set(m.id, { agents, at: Date.now(), asked: Date.now() })
          // One line per TRANSITION, not per round: this runs every few seconds forever, and a healthy
          // machine that logs each time buries everything else in the file.
          if (asking.agents.length !== agents.length) {
            this.local.log(`cable: ${m.name} → ${agents.length} agents`)
          }
        })
        .catch((err) => {
          if (this.remoteAgents.get(m.id) !== asking) return
          const failedAt = Date.now()
          const message = (err as Error).message
          let stale: boolean
          if (fleet.reachable?.(m.id)?.ok !== true) stale = failedAt - asking.at > REMOTE_GRACE_MS
          // Answered under its own session while this list was out, and the list timed out: slow, not gone (Diego,
          // 10-30: 15 carousel drops in a day of a Mac whose late replies kept arriving). Its last good list stays.
          else if (message === LIST_TIMED_OUT) stale = false
          else {
            asking.refusedSince ??= failedAt
            stale = failedAt - asking.refusedSince > REMOTE_GRACE_MS
          }
          if (stale) this.remoteAgents.set(m.id, { agents: [], at: failedAt, asked: failedAt })
          if (asking.agents.length && stale) {
            this.local.log(`cable: ${m.name} dropped off the carousel (${message})`)
          }
        })
        .finally(() => this.inFlight.delete(m.id))
    }
  }

  /**
   * Deliver a turn, and SAY whether it could be.
   *
   * The remote leg is fire-and-forget by protocol — `message` frames carry no ack — so a machine that
   * has stopped answering takes the turn and nothing comes back. Measured: the fleet's own `agents_list`
   * was timing out every twenty seconds while a ⌘K route was handed to an agent on that machine, and
   * every side stayed silent about it. The E2EE session still said `ready`, because it handshook while
   * the machine was alive; the backend's list still called it online.
   *
   * So the check is the one thing that actually knows: did the LAST request to that machine come back.
   * Never asked (null) is not a refusal — a cold start must not read as a failure.
   *
   * Callers that do not care may ignore the result; nothing here changes for them.
   */
  sendTurn(agentId: string, text: string): SendResult {
    if (!this.isLocalAgent(agentId)) {
      const machineId = this.machineOf(agentId)
      const machine = this.knownAgents.get(agentId)?.machine || machineId.slice(0, 8)
      const seen = this.fleet?.reachable?.(machineId)
      if (seen && !seen.ok) {
        const ago = Math.round((Date.now() - seen.at) / 1000)
        this.local.log(`cable: refused a turn for ${agentId.slice(0, 8)} — ${machine} last failed ${ago}s ago`)
        return { ok: false, machine, reason: 'the last request to it did not come back' }
      }
      this.fleet!.sendTurn(machineId, agentId, text)
      this.spokeTo(agentId)
      return { ok: true }
    }
    this.local.sendTurn(agentId, text)
    this.spokeTo(agentId)
    return { ok: true }
  }

  /**
   * Remember who this person is talking to.
   *
   * Recorded HERE because every path that actually delivers a turn passes through sendTurn — the
   * window's palette, the dial naming a tile, and the router's own fallback — so there is one fact and
   * one place it is written. Recorded only on a delivery that was accepted: a turn refused because its
   * machine went deaf is not a conversation anybody is in the middle of.
   */
  private spokeTo(agentId: string): void {
    if (agentId) this.lastTurn = { agentId, at: Date.now() }
  }

  /** Who the last delivered turn went to, and how long ago — the router's continuity signal. */
  lastRouted(): RouterContinuity | undefined {
    if (!this.lastTurn) return undefined
    return { agentId: this.lastTurn.agentId, agoMs: Date.now() - this.lastTurn.at }
  }

  stopTurn(agentId: string): void {
    if (!this.isLocalAgent(agentId)) { this.fleet!.stopTurn(this.machineOf(agentId), agentId); return }
    this.local.stopTurn(agentId)
  }

  canSpeakQuestion(agentId: string): boolean {
    // Remote receiver capabilities are not negotiated yet; no free-text fallback.
    return this.knows(agentId) && this.isLocalAgent(agentId) && !!this.local.answerReviewed
  }

  async answerReviewed(answer: ReviewedAnswer): Promise<AnswerReceipt> {
    if (answer.freeTextKeys?.length && !this.canSpeakQuestion(answer.agentId))
      return { ok: false, error: 'Use the terminal to type this answer.' }
    if (!this.isLocalAgent(answer.agentId)) {
      const machineId = this.machineOf(answer.agentId)
      if (!this.fleet || this.fleet.reachable?.(machineId)?.ok === false) {
        return { ok: false, error: 'That machine is unavailable. Check its connection.' }
      }
      // Older remote drivers split multi-select labels on commas. Do not lose
      // a selected label when that receiver cannot prove support for exact arrays.
      if (answer.questions.some(q => q.multi && answer.selections[q.key]?.some(label => label.includes(',')))) {
        return { ok: false, error: 'Use the terminal for this multi-select answer.' }
      }
      if (this.fleet.answerReviewed) this.fleet.answerReviewed(machineId, answer)
      else this.fleet.answer(machineId, answer.agentId, answer.requestId, answer.answers)
      return { ok: true, pending: true } // Handoff only; the dialog's close is authoritative.
    }
    if (!this.local.answerReviewed) return { ok: false, error: 'Update Harness to answer this question.' }
    const ok = await this.local.answerReviewed(answer)
    return ok ? { ok: true } : { ok: false, error: 'Could not confirm the answer. Check the terminal.' }
  }

  answer(agentId: string, requestId: string, answers: Record<string, string>): void {
    if (!this.isLocalAgent(agentId)) { this.fleet!.answer(this.machineOf(agentId), agentId, requestId, answers); return }
    this.local.answer(agentId, requestId, answers)
  }

  updateAgent(agentId: string, model?: string, effort?: string): void {
    if (!this.isLocalAgent(agentId)) { this.fleet!.updateAgent(this.machineOf(agentId), agentId, model, effort); return }
    this.local.updateAgent?.(agentId, model, effort)
  }

  /** The last few turns, newest first, in the shape the dial's tile draws: a headline and a body. */
  async recentSummaries(agentId: string): Promise<Array<{ recap: string; text: string; ask: string; fullText?: string }>> {
    const raw = this.isLocalAgent(agentId)
      ? await this.local.recent(agentId, 3)
      : await this.fleet!.recentSummaries(this.machineOf(agentId), agentId)
    return raw
      .map((r) => ({ recap: extendShortRecap(r?.recap ?? '', r?.text ?? ''), text: r?.text ?? '', ask: r?.ask ?? '', ...(r?.fullText ? { fullText: r.fullText } : {}) }))
      .filter((s) => s.recap || s.text || s.ask)
  }

  /**
   * The person's own last questions to an agent, newest first — what the router ranks on.
   *
   * Its own trip rather than a field on [recentSummaries]: a question is recorded when it is asked and
   * a recap when the answer is summarised, so the two lists are different lengths on any machine where
   * a turn ended without one. Folding them together is what left the newest question — the one that
   * says where the next one belongs — off the end.
   */
  async recentAsks(agentId: string): Promise<string[]> {
    const raw = this.isLocalAgent(agentId)
      ? await this.local.recentAsks(agentId)
      : await this.fleet!.recentAsks(this.machineOf(agentId), agentId)
    return raw.map((a) => (a || '').replace(/\s+/g, ' ').trim()).filter(Boolean)
  }

  async listModels(agentId: string): Promise<string[]> {
    if (!this.isLocalAgent(agentId)) return this.fleet!.listModels(this.machineOf(agentId), agentId)

    const models = (await this.local.listModels?.(agentId)) ?? []
    return models.map((m) => m.id).filter(Boolean)
  }
}