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.

45.0 KB
Raw Blame
/**
 * The devices: the dials on this computer's USB ports, the window bridges they speak through, the fleet's
 * router every turn goes through (⌘K's too), the voice router, and the Devices tab
 * (docs/design/2026-10-06-core-boundary-next.md, "Devices — its own process", step 9).
 *
 * They reach the core only through `CoreApi` and the core reaches them only through `ports.devices`
 * (core/api.ts `DevicesPort`), so that they can run in a process of their own: the serial ports are
 * hardware, a dial speaks whatever its firmware says, and one device failing must cost the devices, never
 * a session. Inside, each part answers for itself (services/devicesGuard.ts): a dial throwing on every
 * frame costs ⌘K nothing, and a fleet that cannot start costs the dial nothing.
 *
 * Where the core used to wire all this inside `runForeground` (before step 9) it now hands over what the
 * windows on this computer say, as it hears it, and every card it sends the devices; the window's desk,
 * tabs, unread rows and focus it keeps, and says again whenever the devices start.
 *
 * The Wi-Fi device is a service of its own beside these (services/wifi.ts), in the same process, on a link
 * of its own: it rides the gateway's sessions, and borrows the dial's walk and stroke through the core.
 */
import { existsSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { env } from '../config/env.js'
import { DEVICES_REQUESTS, SUPER_TAB_REQUEST_PREFIX, type CardChat, type CoreApi, type SaidOnCard, type CorePorts, type DevicesPort, type RouteAnswer, type SendResult, type ServiceRequests, type WindowFocus } from '../core/api.js'
import { CableFleet, testDialDiscovery, type CableFleetOptions } from '../cable/cableFleet.js'
import { isLocalOnly } from '../lib/cardUpdate.js'
import { TurnStats, type TurnStatsFields } from '../cable/turnStats.js'
import { cableEventFor, cableStepFor, cableQuestionCloseFor, cableQuestionFor, DaemonCableHost } from '../cable/cableHost.js'
import { CableSession } from '../cable/cableSession.js'
import { PetStore } from '../cable/pets/store.js'
import { DialLog } from '../cable/dialLog.js'
import { DialVerdicts } from '../cable/dialPortVerdicts.js'
import { WindowForm } from '../cable/windowForm.js'
import { createWindowRouter } from '../cable/windowRoute.js'
import { WindowSelection } from '../cable/windowSelection.js'
import { WindowVisit } from '../cable/windowVisit.js'
import { MachineListCache } from '../device/machineList.js'
import { harnessDevicesRequest } from '../lib/harnessDevices.js'
import { machineKindsOf } from '../lib/e2ee/machineKinds.js'
import { truncateUtf8 } from '../lib/deviceRecentTrim.js'
import { setVoiceRouterDeviceConnected, setVoiceRouterSessions, shutdownVoiceRouter } from '../lib/voiceRouter.js'
import { createTally, createTierDecider, type Tier, type TierDecision, type TierInput } from '../lib/notifyTier.js'
import { createPartGuard } from './devicesGuard.js'
import { FLEET_FALLBACKS, startFleet, type Fleet } from './fleet.js'

export { DEVICES_REQUESTS }

/** What the devices need that is not the core's to give. */
export interface DevicesDeps {
  /** Where each dial keeps its log, one file a day (cable/dialLog.ts). */
  logsDir: string
  /** Where custom pets are kept; `<HARNESS_DEVICES_DIR>/pets` when unset. */
  petsDir?: string
  /** The dials to look at, by serial number (`HARNESS_DIAL_SERIALS`); every one when empty. */
  dialSerials?: string[]
  /** The end-to-end suite's dial, a pseudo-terminal (`HARNESSD_TEST_DIAL_PORT`). */
  testDialPort?: string
  /** Leave the serial ports alone altogether (`CABLE_DISABLE`). */
  cableDisabled?: boolean
  /** `HARNESSD_TEST_FAULTS`: parts to fail, for the end-to-end suite. */
  faults?: ReadonlySet<string>
  log?: (line: string) => void
  /** How loudly a finished turn tells the devices. Defaults to the fixed rules (lib/notifyTier.ts). */
  decideTier?: (input: TierInput) => Promise<TierDecision>
  /** A monotonic clock in ms (default `performance.now`), for the reply throttle: a wall-clock step must not stall or burst it. */
  now?: () => number
  /** How the voice router's worker is stopped when the process exits: an engine process of its own. */
  onExit?: (run: () => void) => void
  /** Read this computer's agents again before a list is built from them: in their own process the devices
   *  keep a copy, asked of the core as the dial's tick or ⌘K needs it (services/devicesProcess.ts). */
  refresh?: () => Promise<void>
  /** Called with a function this part runs whenever it (re)connects to the core, which has forgotten what the devices
   *  told it (services/devicesProcess.ts): the cards wanted are said again. */
  onCoreConnected?: (run: () => void) => void
  /** An agent's conversation token totals, read fresh (not the 15 s cache); null when unknown or remote.
   *  Defaults to the core's `usageFresh`. */
  readUsage?: (agentId: string) => Promise<{ input?: number; cached?: number; output?: number } | null>
  /** For this service's tests: the dial's session, and how dials are found and opened. */
  Session?: ConstructorParameters<typeof CableFleet>[0]
  cable?: Partial<CableFleetOptions>
}

/** ⌘K's answer while the fleet is not running: it never started, so there is no list to weigh. */
const NO_AGENT_LIST = 'no agent list yet'
/** A Super Tab conversation id as the dials hold one (48 bytes with its NUL). */
const CHAT_ID = /^[A-Za-z0-9_-]{1,47}$/
/** A backend's refusal as a dial's voice error: a sentence or two, never a page. */
const VOICE_ERROR_BYTES = 300
const unrouted = (reason: string): RouteAnswer => ({ agentId: '', machineId: '', name: '', confidence: 0, reason, candidates: [], weighed: 0, machines: 0, via: '' })
const sid = (id: string): string => id.slice(0, 8)
/** A card for the dial, and the machine it came from when another machine sent it (services/fleet.ts). */
type DialEvent = NonNullable<ReturnType<typeof cableEventFor>> & { machineId?: string }

export function startDevices(core: CoreApi, ports: CorePorts, deps: DevicesDeps): ServiceRequests {
  const log = deps.log ?? ((line: string) => console.log(line))
  const monotonic = deps.now ?? (() => performance.now())
  const superTabWait = (requestId: unknown): boolean => typeof requestId === 'string' && requestId.startsWith(SUPER_TAB_REQUEST_PREFIX)
  const tally = createTally((line) => log(`[cable] ${line}`))
  const tierOf = deps.decideTier ?? createTierDecider({
    tally,
    log,
  })
  const part = createPartGuard({ log, faults: deps.faults })

  // What the windows on this computer last said: the desk the dial walks and whether it is in front, and
  // which window has the person's attention for a spoken selection, a visit or a form.
  let desk: string[] = []
  let foreground = true
  let onScreen = new Set<string>()
  let focus: WindowFocus = { voice: null, form: null }
  /**
   * Is this agent already in front of somebody at this desk?
   *
   * Both halves are needed and neither alone is enough: a tile on the tab says WHERE it is, the window
   * being in front says whether anyone can see it. The dial used to be told the first half only, so it
   * stayed quiet about a turn that finished while the window sat behind a browser — which is the one
   * case a notification exists for — and the window, which checks both (`_visibleOnTab`), spoke up.
   */
  const alreadyOnScreen = (agentId: string): boolean => foreground && onScreen.has(agentId)

  // ── the fleet: the owner's other machines, and the router every turn goes through ────────────────────
  //
  // The devices' own copy of the machine list, read through the core, which keeps the list the windows and
  // the trust group read; this copy writes no file of its own, so `machines.json` has one writer.
  const machines = new MachineListCache(() => core.account.machines(), () => core.machine.computerId(),
    (line) => log(`[cable] ${line}`), core.dataDir, () => null, false)
  // The account's Harness Team account machines, as each list read says (docs/plans/2026-10-24-swarm-team-account.md):
  // they run Swarm work only. Forgotten on a sign-out, which tells the list as null.
  let teamMachines = new Set<string>()
  machines.listen((body) => {
    teamMachines = new Set([...machineKindsOf(body) ?? []].filter(([, kind]) => kind === 'team').map(([id]) => id))
  })
  const fleet: Fleet | null = part.start('fleet', () => startFleet(core, { machines, desk: () => desk, refresh: deps.refresh }).fleet, FLEET_FALLBACKS)

  // ── the window bridges ─────────────────────────────────────────────────────────────────────────────
  //
  // Spoken tasks go to the WINDOW to be routed, not to the copy of the router in this process. See
  // cable/windowRoute.ts for the two-phase wait and why "no window" and "a person is still choosing" must
  // not be the same answer.
  const windowRouter = createWindowRouter({
    hasWindow: () => core.clients.hasWindow(),
    send: (voiceId, text, cmd) => {
      // To the windows on this computer, never the cloud: this asks the window in front of the dial to
      // open a palette, and fanning it out would pop one open on a computer nobody is sitting at.
      core.clients.sendLocal({ type: 'voice_route_request', payload: { voiceId, text, ...(cmd ? { cmd } : {}) } })
      log(`[route] voice → the window · ${Buffer.byteLength(text, 'utf8')} bytes${cmd ? ` · /${cmd}` : ''}`)
    },
    log: (line) => log(`[cable] ${line}`),
  })
  const windowSelection = new WindowSelection({
    focus: () => focus.voice ?? undefined,
    send: (connId, payload) => core.clients.sendToWindow(connId, { type: 'dial_selection', payload }),
  })
  const windowForm = new WindowForm({
    focus: () => focus.form ?? undefined,
    send: (connId, payload) => core.clients.sendToWindow(connId, { type: 'dial_form', payload }),
    log: (line) => log(`[cable] ${line}`),
  })
  const windowVisit = new WindowVisit({
    focus: () => focus.voice ?? undefined,
    send: (connId, payload) => core.clients.sendToWindow(connId, { type: 'dial_visit', payload }),
  })

  // ── the dial on the USB cable ──────────────────────────────────────────────────────────────────────
  //
  // A device surface served entirely over a wire the user physically owns: no backend, no pairing, no
  // E2EE, no credential on the device. Everything it can ask for is answered by the core through its API —
  // the same registry, the same delivery path — and by the fleet's router, because a second
  // implementation of any of those is a second set of bugs.
  let revision = 0
  // Built before the cable starts: a dial's first hello may read the mapping.
  const pets = new PetStore(deps.petsDir ?? join(env.HARNESS_DEVICES_DIR, 'pets'))
  // The assistant's latest paragraph per agent, as the processing cards carry it; gone when the turn ends.
  const latestUpdate = new Map<string, string>()
  // The Swarm cards' requests to the Super Tab service, through the core (core/devicesLink.ts). An error is an answer too.
  /** What became of words for a Lead, as the service answered: a refusal keeps its code and its message, cut to what a dial
   *  shows in a voice error. */
  const saidOf = (answer: Record<string, unknown>): SaidOnCard => {
    if (answer.said === true) return { said: true }
    const refused = answer.refused && typeof answer.refused === 'object' ? answer.refused as Record<string, unknown> : {}
    if (typeof refused.code !== 'string' || typeof refused.message !== 'string') return { said: false }
    return { said: false, refused: { code: refused.code, message: truncateUtf8(refused.message, VOICE_ERROR_BYTES) } }
  }
  /** A card request's chat, as the core passes it on: none for the Pro, whose requests stay as they were. */
  const chatFlag = (chat: CardChat | undefined): { chat?: true | 'buddy' } => chat ? { chat } : {}
  const askCards = async (payload: Record<string, unknown>): Promise<Record<string, unknown>> => {
    try { return await core.superTabRequest!(payload) } catch { return { error: 'SERVICE_UNAVAILABLE' } }
  }
  // How many attached devices asked for Swarm cards, and which Swarms the desktop has tabs for (read first). The core keeps
  // whether they are wanted (superTabs/inCore/cards.ts); this says it on a change and again when the core connects anew.
  let cardDevices = 0
  let cardInclude: string[] = []
  // The conversation the window has open in its active Swarm tab, which the round dial's face follows (design
  // 2026-10-28-round-dial-swarm-chat): said with the wish, and left out when there is none, as before.
  let cardFocus: { tabId: string; conversationId: string } | null = null
  const tellCards = (): void => {
    const on = cardDevices > 0
    void askCards({ action: 'cardsWanted', on, include: on ? cardInclude : [], ...(on && cardFocus ? { focus: cardFocus } : {}) })
  }
  deps.onCoreConnected?.(() => { if (cardDevices > 0) tellCards() })
  const cableHost = new DaemonCableHost({
    // The cloud harnesses too, where the core offers them: tiles on the desk the dial walks like any other.
    sessions: () => [...core.agents.advertised(), ...core.agents.cloud?.() ?? []],
    refresh: deps.refresh,
    displayName: (session) => core.agents.displayName(session),
    appFocus: () => focus.voice ?? undefined,
    activityText: (agentId) => core.agents.activityText(agentId),
    // The footer and its timer from the core; the agent's own latest sentence from the cards already seen here.
    activitySnapshot: async (agentId) => {
      const reading = core.agents.activitySnapshot
        ? await core.agents.activitySnapshot(agentId)
        : await core.agents.activityText(agentId).then((text) => text ? { text } : null)
      const action = latestUpdate.get(agentId)
      return reading && action ? { ...reading, action } : reading
    },
    machineName: () => core.machine.name(),
    machineId: () => core.machine.id(),
    computerId: () => core.machine.computerId(),
    signedIn: () => core.account.signedIn(),
    accessToken: (opts) => core.account.accessToken(opts),
    environment: () => core.account.environment(),
    watching: (on) => core.clients.dialWatching(on),
    // The core's own doors for a local agent. The fleet's router reaches them the same way; the dial uses
    // these only when it routes by itself, with the fleet off.
    sendTurn: (agentId, text) => core.turns.send(agentId, text),
    stopTurn: (agentId) => core.turns.stop(agentId),
    // A Super Tab wait is shown, never answered here: its id is no pane's, and nothing is typed for it.
    answer: (agentId, requestId, answers) => { if (!superTabWait(requestId)) core.questions.answer(agentId, requestId, answers) },
    answerReviewed: (answer) => superTabWait(answer.requestId) ? Promise.resolve(false) : core.questions.answerReviewed(answer),
    recent: (agentId, n) => core.turns.recent(agentId, n),
    recentAsks: (agentId) => core.turns.asks(agentId),
    runtimeProfile: (session) => core.agents.runtimeProfile(session),
    updateAgent: (agentId, model, effort) => core.agents.setRuntime(agentId, model, effort),
    listModels: (agentId) => core.agents.runtimeModels(agentId),
    // Each of these is for the windows on this computer alone: they describe a hand at this desk, not a
    // change in what the machine is doing, and the cloud web audience may be sitting at another computer.
    // A notification tap asks for a tile of its OWN (see CableHost.openAgent). `reason` rides along only
    // when the dial gave one ('question'): the window then brings the agent forward rather than opening a
    // tab, and an older window that does not know the field opens one as before.
    opened: (machineId, agentId, reason) =>
      core.clients.sendLocal({ type: 'dial_open', payload: { machineId, agentId, ...(reason ? { reason } : {}) } }),
    notificationRead: (machineId, agentId, readToken) =>
      core.clients.sendLocal({ type: 'dial_notification_read', payload: { machineId, agentId, readToken } }),
    forked: (machineId, agentId, sourceAgentId) => core.clients.sendLocal({ type: 'dial_forked', payload: { machineId, agentId, sourceAgentId } }),
    // The dial's Fork: the same path the window's `agent_fork` takes, then `forked` above lands on it.
    forkAgent: (agentId) => core.agents.fork(agentId),
    focused: (machineId, agentId) => core.clients.sendLocal({ type: 'dial_focus', payload: { machineId, agentId } }),
    swarmSelected: (swarmId) => core.clients.sendLocal({ type: 'dial_swarm', payload: { swarmId } }),
    swarmCardsWanted: (on) => {
      const before = cardDevices
      cardDevices = Math.max(0, cardDevices + (on ? 1 : -1))
      if ((before === 0) !== (cardDevices === 0)) tellCards()
    },
    // The text is the service's to read and not validated by the core: cut here, on a character, to what the Pro takes.
    // With `chat` (a round dial that speaks swarmChat, or 'buddy' for swarmBuddy), the chat on that dial's face's, which must
    // name that chat by an id: a dial never shows it for another one.
    swarmCardRecap: async (tabId, leadId, chat) => {
      const r = await askCards({ action: 'cardRecap', tabId, leadId, ...chatFlag(chat) })
      // A refusal fails with its code, which the dial's log names; null was silent (Diego, 2026-11-03).
      if (r.ok !== true && typeof r.error === 'string') throw new Error(r.error)
      if (r.ok !== true || typeof r.text !== 'string' || typeof r.at !== 'number' || !Number.isInteger(r.at) || r.at < 0 || typeof r.none !== 'boolean') return null
      if (chat && !(typeof r.chatId === 'string' && CHAT_ID.test(r.chatId))) return null
      return { tabId, leadId, text: truncateUtf8(r.text, 1500), at: r.at, none: r.none, ...(chat ? { chatId: r.chatId as string } : {}),
        ...(chat === 'buddy' ? { buddy: true as const } : {}) }
    },
    swarmCardOpen: (session, tabId, leadId, chat) => { void askCards({ action: 'cardOpen', session, tabId, leadId, ...chatFlag(chat) }) },
    // An error (no service, a refused post) is not `said`: the words go to the harness instead, never lost.
    swarmSay: async (harnessId, text, chat, chatId, reviewed) => saidOf(await askCards({ action: 'cardSay', harnessId, text, ...chatFlag(chat),
      ...(chatId ? { chatId, ...(reviewed ? { reviewed: true } : {}) } : {}) })),
    // The Pro picked a Lead: the window opens that Swarm tab and project. Harmless with no window. `chat`, from a round dial
    // that keeps sides: the Buddy chat or the Lead chat there; a window from before it opens the project's Lead chat.
    superTabSelected: (superTabId, projectId, chat) =>
      core.clients.sendLocal({ type: 'dial_super_tab', payload: { superTabId, projectId, ...(chat ? { chat } : {}) } }),
    scrolled: (phase, dy, velocity, superTabId) => core.clients.sendLocal({ type: 'dial_scroll', payload: { phase, dy, velocity, ...(superTabId ? { superTabId } : {}) } }),
    // Gestures stay at this desk. The device inventory and its settings also reach the owner's other
    // machines, through the encrypted device-management event.
    dialStatus: (status) => {
      revision++
      core.clients.sendLocal({ type: 'dial_status', payload: status as unknown as Record<string, unknown> })
      core.clients.devicesChanged({ status, revision })
    },
    // Words spoken on the overview belong to whichever agent the window's palette picks.
    routeInWindow: (text, cmd) => windowRouter.ask(text, cmd),
    selectPassage: (command) => windowSelection.command(command),
    clearSelection: () => windowSelection.cancel(),
    visit: (command) => windowVisit.command(command),
    clearVisit: () => windowVisit.cancel(),
    form: (command) => windowForm.command(command),
    clearForm: () => windowForm.clear(),
    log: (line) => log(`[cable] ${line}`),
    // Which machine an agent is on, and getting there: the fleet's router, guarded. Null when it never
    // started; a member that fails answers "unavailable", and the host routes this computer by itself.
    fleet: () => fleet,
    pets: () => pets,
  })
  // The dial's log lives with the app's, one file a day (dialLog.ts). The old unbounded `dial.log` in the
  // data folder is cut down to a pointer, for anyone with a bookmark.
  const legacyDialLog = join(core.dataDir, 'dial.log')
  if (existsSync(legacyDialLog)) {
    try { writeFileSync(legacyDialLog, `moved to ${join(deps.logsDir, 'dial-YYYYMMDD.log')}\n`) } catch { /* best effort */ }
  }
  const cable = new CableFleet(deps.Session ?? CableSession, cableHost, deps.logsDir, DialLog, {
    serials: deps.dialSerials,
    verdicts: new DialVerdicts(join(core.dataDir, 'dial-ports.json')),
    faults: deps.faults,
    ...testDialDiscovery(deps.testDialPort),
    ...deps.cable,
  })

  /** What the turn's shell results add up to (tests, commits), told to the dial just before the turn ends. */
  const stats = new TurnStats()

  const readUsage = deps.readUsage ?? (async (agentId: string) => {
    const usage = await core.usageFresh?.(agentId)
    return usage ? { input: usage.inputTokens, cached: usage.cachedTokens, output: usage.outputTokens } : null
  })
  type Reading = { input?: number; cached?: number; output?: number } | null
  /** Each agent's reading from when its turn started, until the turn ends. */
  const starts = new Map<string, Promise<Reading>>()
  /** When each agent's turn began (the first `processing`), for the summary's duration. */
  const began = new Map<string, number>()
  /** The turn that just ended, kept for the `summary` that follows its `done`. */
  const ended = new Map<string, { durationS: number | null; stats: TierInput['stats'] }>()
  const TOKENS_WAIT_MS = 2000
  const MAX_TOKENS = 50_000_000
  const settle = (p: Promise<Reading>): Promise<Reading> => p.catch(() => null)
  /** Input without cache reads (the usage cache's inputTokens includes them; cache creation stays, it is new
   *  input). Unknown when cached is, so an inflated number is never shown. */
  const fresh = (r: Reading): number | undefined =>
    typeof r?.input === 'number' && typeof r.cached === 'number' ? r.input - r.cached : undefined
  const diff = (a: number | undefined, b: number | undefined): number | undefined =>
    typeof a === 'number' && typeof b === 'number' && b - a >= 0 && b - a <= MAX_TOKENS ? b - a : undefined
  /** The tokens this turn used: the end reading minus the start one, or nothing when either is missing, the
   *  difference is out of range, or the fresh read takes over 2 s (the turn's end never waits longer). */
  const turnTokens = async (agentId: string, start: Promise<Reading>): Promise<Pick<TurnStatsFields, 'tokensIn' | 'tokensOut'>> => {
    let timer: ReturnType<typeof setTimeout> | undefined
    try {
      const [from, to] = await Promise.race([
        Promise.all([settle(start), settle(readUsage(agentId))]),
        new Promise<null>((resolve) => { timer = setTimeout(() => resolve(null), TOKENS_WAIT_MS) }),
      ]) ?? [null, null]
      const tokensIn = diff(fresh(from), fresh(to)), tokensOut = diff(from?.output, to?.output)
      return { ...(tokensIn === undefined ? {} : { tokensIn }), ...(tokensOut === undefined ? {} : { tokensOut }) }
    } finally { clearTimeout(timer) }
  }

  /** One card for the dial, in its four calls. A remote machine's and this computer's are the same calls,
   *  so a new kind of card lands on both the day it lands on either. */
  const dispatch = (event: DialEvent): void | Promise<void> => {
    if (event.kind !== 'processing') latestUpdate.delete(event.agentId)
    if (event.kind === 'processing') {
      if (event.update) latestUpdate.set(event.agentId, event.update)
      else latestUpdate.delete(event.agentId)
      if (!began.has(event.agentId)) began.set(event.agentId, Date.now())
      void cable.turnStarted(event.agentId, event.text, event.update)
    } else if (event.kind === 'done') {
      const fields = stats.take(event.agentId)
      const at = began.get(event.agentId)
      began.delete(event.agentId)
      ended.set(event.agentId, { durationS: at === undefined ? null : Math.round((Date.now() - at) / 1000),
        stats: { testsPassed: fields.testsPassed, testsFailed: fields.testsFailed, commits: fields.commits } })
      const start = starts.get(event.agentId)
      starts.delete(event.agentId)
      const finish = (tokens: Pick<TurnStatsFields, 'tokensIn' | 'tokensOut'>): void => {
        const all = { ...fields, ...tokens }
        if (Object.keys(all).length) void cable.turnStats(event.agentId, all)
        void cable.turnDone(event.agentId)
      }
      if (!start || !cable.wantsStats()) return finish({})
      return turnTokens(event.agentId, start).then(finish)
    }
    // On screen or a sub-agent's: silent, nobody is asked. Otherwise the tier decides how loudly the dial tells. The
    // tile still updates either way — the recap is what it draws.
    else if (event.kind === 'summary') {
      const { agentId } = event
      const recap = event.recap || event.text
      const onScreen = alreadyOnScreen(agentId)
      const noted = (tier: Tier, rule: string): void => tally(cableHost.describe(agentId)?.name ?? '', tier, `rule:${rule}`, rule, 0)
      if (onScreen || event.subagent) { noted('silent', event.subagent ? 'subagent' : 'onScreen'); void cable.summary(agentId, recap, event.text, 'silent', event.fullText, event.subagent); return }
      // No device attached (or the serial side disabled): nobody to tell, so the recap never leaves the machine.
      if (!cable.isConnected) { ended.delete(agentId); void cable.summary(agentId, recap, event.text, 'silent', event.fullText, false); return }
      const turn = ended.get(agentId) // a sub-agent's summary leaves the main turn's numbers alone
      ended.delete(agentId)
      const who = cableHost.describe(agentId)
      // Decided once already, by the recaps (services/recaps.ts), for the phone as well: the dial follows it and
      // nobody is asked again. A card without one (a cloud agent's, a recaps from before) is decided here, and so is
      // a Team machine's, whatever its card says: it runs Swarm work only (#2540's review: its own tier alerted).
      if (event.tier && !onTeamMachine(event)) {
        tally(who?.name ?? '', event.tier, 'recaps', 'decided upstream', 0)
        void cable.summary(agentId, recap, event.text, event.tier, event.fullText, false)
        return
      }
      // Returned, so the agent's next card waits behind this one (inOrder): a late recap must not follow turn.started.
      return tierOf({ agent: who?.name ?? '', engine: who?.engine ?? '', recap, durationS: turn?.durationS ?? null,
        stats: turn?.stats ?? {}, subagent: false, onScreen: false, failed: event.failed === true, swarm: swarmAgent(event) })
        .then((d) => d.tier, () => 'list' as const)
        .then((tier) => { void cable.summary(agentId, recap, event.text, tier, event.fullText, false) })
    }
    else {
      began.delete(event.agentId); ended.delete(event.agentId)
      stats.take(event.agentId) // a failed turn's sums must not leak into the next turn
      starts.delete(event.agentId)
      // A Swarm Reviewer on a Mac's Harness Team account failed every turn in 1-2 s (2026-10-28), and each failure took over
      // the round dial with the engine's raw error for 8 s. A Swarm's workers answer to their Lead, who hears of it in the
      // Swarm: one the person has not put on a tab ends its tile quietly, as a finished turn does, and never stays Working.
      const quiet = (): void => {
        tally(cableHost.describe(event.agentId)?.name ?? '', 'silent', 'rule:swarm-worker', 'turn.error', 0)
        void cable.turnDone(event.agentId)
      }
      const shown = (): void => {
        tally(cableHost.describe(event.agentId)?.name ?? '', 'alert', 'rule:failed', 'turn.error', 0)
        void cable.turnError(event.agentId, event.text)
      }
      if (onDesk(event.agentId)) return shown()
      if (swarmWorker(event)) return quiet()
      // Another of the person's computers says nothing of the Swarm in its card: the Swarm service is asked, and returned so
      // the agent's next card waits behind the answer. No answer (an older computer, the service down) shows it, as before.
      if (!event.machineId) return shown()
      return remoteWorker(event.machineId, event.agentId).then((worker) => worker ? quiet() : shown())
    }
  }
  /** An agent the Swarm started here, a Builder or Reviewer as it was (its record's Swarm role, and an agent started it, as
   *  every Swarm start is), or any agent on a Harness Team account. The coordinator is the person's own agent leading the
   *  Swarm, and one the person started by hand is theirs whatever its role: their failures reach the dial as before. */
  const swarmWorker = (event: DialEvent): boolean => {
    const session = event.machineId ? undefined : core.agents.byAgent(event.agentId)
    const role = session?.startedBy === 'agent' ? session.swarmSkill?.role : undefined
    return role === 'agent' || onTeamMachine(event)
  }
  /** An agent on one of the account's Harness Team machines, which run Swarm work only. */
  const onTeamMachine = (event: DialEvent): boolean => !!event.machineId && teamMachines.has(event.machineId)
  /** Any Swarm agent, whatever its role (PM, Buddy, Builder, Reviewer, Tester): its registry row carries `swarmSkill`, or it runs
   *  on a Harness Team account. Its news reaches the dial through the Swarm's cards, so its finished turn is silent. */
  const swarmAgent = (event: DialEvent): boolean =>
    (!event.machineId && !!core.agents.byAgent(event.agentId)?.swarmSkill) || onTeamMachine(event)
  /** Whether an agent on another machine is a Swarm's Builder or Reviewer, as the Swarm service read it last
   *  (superTabs/cards.ts `worker`). Asked once a minute at most per agent: a failing worker fails every 1-2 s. */
  const WORKER_ANSWER_MS = 60_000
  /** How long a failure waits for the answer before it shows as before: a hung service must not leave the tile working. */
  const WORKER_WAIT_MS = 2_000
  const workerAnswers = new Map<string, { worker: boolean; at: number }>()
  const remoteWorker = async (machineId: string, agentId: string): Promise<boolean> => {
    const key = `${machineId}/${agentId}`
    const held = workerAnswers.get(key)
    if (held && monotonic() - held.at < WORKER_ANSWER_MS) return held.worker
    let timer: ReturnType<typeof setTimeout> | undefined
    // No answer in time is held as "not a worker" like any other, so the next failures in the minute do not wait again.
    const worker = await Promise.race([
      askCards({ action: 'cardWorker', machineId, harnessId: agentId }).then((answer) => answer.worker === true),
      new Promise<false>((resolve) => { timer = setTimeout(() => resolve(false), WORKER_WAIT_MS) }),
    ]).finally(() => clearTimeout(timer))
    // Each key is an agent that failed off the desk; a long-lived process forgets them all rather than grow.
    if (workerAnswers.size >= 256) workerAnswers.clear()
    workerAnswers.set(key, { worker, at: monotonic() })
    return worker
  }
  /** On any of the window's tabs, or the desk the dial walks: the person put it there, so its failure is theirs to see. */
  const onDesk = (agentId: string): boolean =>
    desk.includes(agentId) || cableHost.listSwarms().swarms.some((tab) => tab.agentIds?.includes(agentId))
  /**
   * The reply as it streams: a `steps-v1` device shows the agent's latest paragraph, but a text delta arrives every
   * few tokens and the link is lossy. So at most one send per 750 ms per agent, a trailing send of the last text
   * when the window closes, and a flush when the turn ends. Each send is the whole paragraph (clipped by the
   * session), so a lost one is replaced by the next, and the state is one slot per agent: nothing piles up.
   */
  const REPLY_EVERY_MS = 750
  const replies = new Map<string, { sentAt: number; pending: string | null; timer: ReturnType<typeof setTimeout> | null }>()
  const sendReply = (agentId: string, text: string): void => {
    const slot = replies.get(agentId) ?? { sentAt: 0, pending: null, timer: null }
    replies.set(agentId, slot)
    slot.sentAt = monotonic(); slot.pending = null
    inOrder(agentId, () => { void cable.turnReply(agentId, text) })
  }
  const replyText = (agentId: string, text: string): void => {
    const slot = replies.get(agentId)
    const wait = slot ? slot.sentAt + REPLY_EVERY_MS - monotonic() : 0
    if (!slot || wait <= 0) { sendReply(agentId, text); return }
    slot.pending = text
    if (!slot.timer) {
      slot.timer = setTimeout(() => {
        slot.timer = null
        sendReply(agentId, slot.pending as string) // the timer is cleared whenever pending is, so it is set here
      }, wait)
      slot.timer.unref()
    }
  }
  /** The turn ends or restarts, or the agent goes: send what is waiting (when asked to) and forget the window. */
  const endReplies = (agentId: string, flush: boolean): void => {
    const slot = replies.get(agentId)
    if (!slot) return
    if (slot.timer) clearTimeout(slot.timer)
    if (flush && slot.pending !== null) inOrder(agentId, () => { void cable.turnReply(agentId, slot.pending as string) })
    replies.delete(agentId)
  }
  /** A card for an agent whose delayed `done` is still being sent waits behind it, so the dial sees them in order. */
  const queued = new Map<string, Promise<void>>()
  /** Every per-agent send goes through here, so a question or a step of the next turn never overtakes a delayed done. */
  const inOrder = (agentId: string, run: () => void | Promise<void>): void => {
    const behind = queued.get(agentId)
    const next = behind ? behind.then(run, run) : run()
    if (!next) return
    const tail = next.then(undefined, () => {}) // a throwing send must not break the agent's queue for good
    queued.set(agentId, tail)
    void tail.then(() => { if (queued.get(agentId) === tail) queued.delete(agentId) })
  }
  const toDial = (event: DialEvent): void => {
    // The last streamed text goes out before the turn's end, in the same per-agent order.
    if (event.kind !== 'processing') endReplies(event.agentId, true)
    inOrder(event.agentId, () => dispatch(event))
  }

  // A remote machine's cards reach the dial through the same calls. The fleet has already noted which
  // machine the agent is on (services/fleet.ts), so a question from it can be named and, tapped, opened.
  fleet?.onEvent((event) => part.call('dial', () => {
    // A `state` event is about the WHEEL, not about a turn — live machine presence, which matters whichever
    // machine is selected. No selection guard on the rest: every machine's agents are on the carousel at
    // once, and dropping a card from one the wheel is not pointed at is what a tile that never leaves
    // "Working…" looks like from the outside.
    if (event.kind === 'state') { void cable.syncMachines(); return }
    if (event.kind === 'questionClosed') { inOrder(event.agentId, () => { void cable.questionClose(event.agentId, event.requestId) }); return }
    if (event.kind === 'question') { tally(cableHost.describe(event.agentId)?.name ?? '', 'alert', 'rule:question', 'question', 0); inOrder(event.agentId, () => { void cable.question(event.agentId, event.requestId, event.questions) }); return }
    toDial({ ...event, subagent: event.subagent === true })
  }))

  if (deps.cableDisabled) log('[cable] disabled (CABLE_DISABLE=true) — the serial port is left alone')
  else cable.start()
  ;(deps.onExit ?? ((run) => { process.once('exit', run) }))(() => shutdownVoiceRouter())

  const port: DevicesPort = {
    // Every card bound for the Wi-Fi devices goes down the cable too, translated once: a new kind of card
    // reaches the dial the day it reaches the backend's devices.
    card: (frame) => part.call('dial', () => {
      const close = cableQuestionCloseFor(frame as Parameters<typeof cableQuestionCloseFor>[0])
      if (close) { inOrder(close.agentId, () => { void cable.questionClose(close.agentId, close.requestId) }); return }
      const question = cableQuestionFor(frame as Parameters<typeof cableQuestionFor>[0])
      // A Super Tab member waiting on a person (superTabs/inCore/attention.ts) is an alert as any question is.
      if (question) { tally(cableHost.describe(question.agentId)?.name ?? '', 'alert', question.superTab ? 'rule:super-tab' : 'rule:question', 'question', 0); inOrder(question.agentId, () => { void cable.question(question.agentId, question.requestId, question.questions, question.superTab) }); return }
      // A shell result is only the stats' input: the dial is told the sums when the turn ends.
      const ran = frame as { type?: string; agentId?: string; payload?: { kind?: string; id?: string; command?: string; isError?: boolean; outputTail?: string } }
      if (ran.payload?.kind === 'reply_text' && ran.agentId) {
        const update = (ran.payload as { update?: unknown }).update
        if (typeof update === 'string' && update) { latestUpdate.set(ran.agentId, update); replyText(ran.agentId, update) }
        return
      }
      if (ran.payload?.kind === 'turn_started' && ran.agentId) {
        endReplies(ran.agentId, false)
        stats.take(ran.agentId)
        if (cable.wantsStats()) starts.set(ran.agentId, settle(readUsage(ran.agentId)))
        return
      }
      if (isLocalOnly(frame) && ran.agentId && ran.payload?.id) {
        stats.toolResult(ran.agentId, ran.payload.command, ran.payload.isError === true, ran.payload.outputTail ?? '')
        return
      }
      // A tool card is a step for a `steps-v1` device and nothing for any other: the session drops it.
      const gone = (frame as { type?: string; payload?: { agentId?: unknown } })
      if (gone.type === 'agent_deleted' && typeof gone.payload?.agentId === 'string') { latestUpdate.delete(gone.payload.agentId); began.delete(gone.payload.agentId); ended.delete(gone.payload.agentId); endReplies(gone.payload.agentId, false) }
      const step = cableStepFor(frame as Parameters<typeof cableStepFor>[0])
      if (step) { inOrder(step.agentId, () => { void cable.turnStep(step.agentId, step.step) }); return }
      const event = cableEventFor(frame as Parameters<typeof cableEventFor>[0])
      // Logged at the fork, not at the send: this answers "did the daemon even decide to tell the dial",
      // a different question from "did the wire carry it", and the one nobody could answer when a tile
      // stayed idle through a whole turn.
      if (env.LOG_FRAMES && frame.type === 'commander_event') {
        log(`[cable] tee ${(frame as { payload?: { kind?: string } }).payload?.kind ?? '?'} → ${event ? 'sent' : 'ignored'}`)
      }
      if (event) toDial(event)
    }),
    desk: (agentIds, front) => {
      // ORDER matters, not just membership: the dial's carousel is the tiles, in tile order, so the thumb
      // walks the grid the eyes are on, and a change is a new ring, pushed at once. Left to the next tick,
      // a click on an agent with no tile yet (which changes the desk, then focuses) reached the dial before
      // its ring had a column for it, and the dial dropped the focus.
      const changed = agentIds.length !== desk.length || agentIds.some((id, at) => id !== desk[at])
      desk = [...agentIds]
      foreground = front
      onScreen = new Set(agentIds)
      part.call('dial', () => cableHost.setDesk(agentIds))
      if (changed) part.call('dial', () => cable.syncAgents())
    },
    // Null is the window gone: an empty desk with a window behind it is an empty tab, with none a shut app.
    swarms: (swarms) => part.call('dial', () => {
      cableHost.setSwarms(swarms)
      // The Swarms the window has tabs for are read first; said again to the core only when they change.
      const include = [...new Set((swarms?.swarms ?? []).map((s) => s.superTabId).filter((id): id is string => !!id))].slice(0, 16)
      const open = cableHost.activeSwarmProject()
      const focus = open?.conversationId
        ? { tabId: open.superTabId, conversationId: open.conversationId } : null
      const refocused = `${focus?.tabId}/${focus?.conversationId}` !== `${cardFocus?.tabId}/${cardFocus?.conversationId}`
      if (include.join(',') !== cardInclude.join(',') || refocused) { cardInclude = include; cardFocus = focus; if (cardDevices > 0) tellCards() }
      void cable.syncSwarms()
      void cable.syncAgents()
      // The Swarm cards link to their desk tab and follow its open project.
      void cable.syncSwarmCards()
    }),
    // The Swarms' cards and a Lead's recap for the Harness Pro: the cable carries them once it speaks the frames.
    swarmCards: (items) => part.call('dial', () => {
      cableHost.setSwarmCards(items)
      void cable.syncSwarmCards()
    }),
    swarmCardRecap: (recap) => part.call('dial', () => { void cable.swarmCardRecap(recap) }),
    // Held rather than acted on: the dial is handed it when it attaches, the one moment its drawer is known
    // to be empty.
    unread: (items) => part.call('dial', () => {
      cableHost.setUnread(items)
      void cable.replaceNotifications(items)
    }),
    appFocus: (machineId, agentId) => part.call('dial', () => cable.followApp(machineId, agentId)),
    // The window looked at a harness: the dial's drawer row for it is stale.
    seen: (agentId, readToken) => part.call('dial', () => cable.agentSeen(agentId, readToken)),
    // Addressed to one device by the fleet's id: a preference belongs to the glass it was set on. Nothing is
    // answered here; the device's own `settings.state` reaches the windows as an ordinary `dial_status`.
    settings: (id, patch) => part.call('dial', () => cable.setSettings(id, patch as Parameters<CableFleet['setSettings']>[1])
      .then((result) => { if (!result.ok) log(`[cable] settings for ${id || 'no device'}: ${result.error}`) })),
    windowFocus: (next) => {
      focus = next
      // State replay after a service restart carries windowFocus, without another appFocus event.
      const selected = next.voice
      if (selected) part.call('dial', () => cable.followApp(selected.machineId, selected.agentId))
      part.call('window', () => windowSelection.focusChanged())
    },
    windowReply: (kind, connId, machineId, payload) => part.call('window', () =>
      (kind === 'form' ? windowForm : kind === 'visit' ? windowVisit : windowSelection).reply(connId, machineId, payload)),
    voiceReply: (voiceId, reply) => part.call('window', () => windowRouter.reply(voiceId, reply)),
    windowGone: (connId) => part.call('window', () => {
      windowForm.disconnected(connId)
      windowSelection.focusChanged()
    }),
    // ⌘K in the window: a typed task, and which agent it belongs to, on any of the owner's machines.
    routeTask: async (text) => fleet ? fleet.routeTask(text) : unrouted(NO_AGENT_LIST),
    // Committed, through the fleet's router — the dial's own dispatch — so a remote agent is reached on its
    // own machine instead of being looked for in this computer's registry.
    routeSend: async (agentId, text): Promise<SendResult> => {
      const sent = fleet?.routeSend(agentId, text) ?? { ok: false as const, machine: '', reason: NO_AGENT_LIST }
      log(`[route] ⌘K → ${sid(agentId)} · bytes=${Buffer.byteLength(text, 'utf8')}`
        + (sent.ok ? '' : ` · REFUSED: ${sent.reason}${sent.machine ? ` (${sent.machine})` : ''}`))
      return sent
    },
    // The Wi-Fi device borrows the dial's walk along the desk and its stroke, until it is one of the devices.
    stepFocus: (direction, currentAgentId) => cableHost.stepFocus(direction, currentAgentId),
    scroll: (phase, dy, velocity) => cableHost.scrolled(phase, dy, velocity),
    // The voice router warms a worker on an engine the machine runs, while a device is watching.
    engines: (engines) => setVoiceRouterSessions(engines.map((engine) => ({ engine }))),
    commanders: (connected) => setVoiceRouterDeviceConnected(connected),
    // The serial ports first: a port left held makes esptool fail in a way that reads like dead hardware.
    stop: async () => {
      for (const agentId of [...replies.keys()]) endReplies(agentId, false)   // no timer may fire into a stopped cable
      await cable.stop()
      fleet?.stop()
      shutdownVoiceRouter()
    },
  }
  ports.devices = port

  // The Devices tab: physical devices belong to this machine, and only its owner may manage them.
  const tab = {
    status: () => cableHost.currentDialStatus(),
    revision: () => revision,
    set: (id: string, patch: Parameters<CableFleet['setSettings']>[1]) => cable.setSettings(id, patch),
    pets: () => pets,
    // The first attached dial's state; a changed mapping is sent to every live dial.
    petDial: () => cable.petDial(),
    petsChanged: () => { void cable.petsChanged() },
  }
  const answer = (type: string) => (payload: Record<string, unknown>, asker: { local?: boolean; owner: boolean }) =>
    asker.owner ? harnessDevicesRequest(tab, type, payload) : { error: 'OWNER_REQUIRED' }
  // Pets name files on this computer by path, so they are answered to a process here only, never the owner's relayed app.
  const local = (type: string) => (payload: Record<string, unknown>, asker: { local?: boolean; owner: boolean }) =>
    !asker.owner ? { error: 'OWNER_REQUIRED' } : asker.local ? harnessDevicesRequest(tab, type, payload) : { error: 'LOCAL_ONLY' }
  return {
    harness_devices_list: answer('harness_devices_list'), harness_device_settings: answer('harness_device_settings'),
    pet_preview: local('pet_preview'), pet_apply: local('pet_apply'), pet_reset: local('pet_reset'), pet_status: local('pet_status'),
  }
}