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.

86.4 KB
Raw Blame
// The devices (services/devices.ts): what the core tells them reaches the dial and the window bridges, what
// they say reaches the core through its API alone, and the fleet failing costs the dial nothing.
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { CableHostWiring } from '../cable/cableHost.js'
import { env } from '../config/env.js'
import { emptyPorts, ServiceUnavailableError, type CoreApi, type CorePorts, type DevicesPort } from '../core/api.js'
import type { FleetEvent } from '../cable/machineFleet.js'
import type { RegisteredSession } from '../lib/registry.js'
import { fakeCore } from '../testing/fakeCore.js'
import type { Fleet, FleetDeps } from './fleet.js'
import type { DevicesDeps } from './devices.js'

const seen = vi.hoisted(() => ({
  host: null as unknown as CableHostWiring,
  dial: null as unknown as { onDialStatus(status: unknown): void },
  cable: null as unknown as { args: unknown[]; calls: Array<[string, unknown[]]>; setSettings: (id: string, patch: unknown) => Promise<{ ok: boolean; error?: string }> },
  bridges: {} as Record<string, { wiring: Record<string, (...args: unknown[]) => unknown>; calls: Array<[string, unknown[]]> }>,
  fleet: null as null | { deps: FleetDeps; events: ((event: FleetEvent) => void) | null; fail: boolean },
  voice: { sessions: vi.fn(), connected: vi.fn(), shutdown: vi.fn() },
}))

vi.mock('../cable/cableHost.js', async (real) => {
  const actual = await real<typeof import('../cable/cableHost.js')>()
  return {
    ...actual,
    DaemonCableHost: class extends actual.DaemonCableHost {
      constructor(wiring: CableHostWiring) { super(wiring); seen.host = wiring; seen.dial = this }
    },
  }
})
vi.mock('../cable/cableFleet.js', async (real) => {
  const actual = await real<typeof import('../cable/cableFleet.js')>()
  const recorder = (name: string) => function (this: { calls: Array<[string, unknown[]]> }, ...args: unknown[]) { this.calls.push([name, args]); return Promise.resolve() }
  class FakeCable {
    calls: Array<[string, unknown[]]> = []
    args: unknown[]
    constructor(...args: unknown[]) { this.args = args; seen.cable = this as never }
    start = recorder('start')
    stop = recorder('stop')
    syncAgents = recorder('syncAgents')
    syncSwarms = recorder('syncSwarms')
    syncSwarmCards = recorder('syncSwarmCards')
    swarmCardRecap = recorder('swarmCardRecap')
    syncMachines = recorder('syncMachines')
    followApp = recorder('followApp')
    replaceNotifications = recorder('replaceNotifications')
    agentSeen = recorder('agentSeen')
    question = recorder('question')
    questionClose = recorder('questionClose')
    turnStarted = recorder('turnStarted')
    turnStep = recorder('turnStep')
    turnReply = recorder('turnReply')
    turnDone = recorder('turnDone')
    turnStats = recorder('turnStats')
    summary = recorder('summary')
    turnError = recorder('turnError')
    petsChanged = recorder('petsChanged')
    wants = true
    connected = true
    get isConnected() { return this.connected }
    wantsStats() { return this.wants }
    petDial = () => ({ supported: false, held: [] as string[], sending: null })
    setSettings = vi.fn(async (id: string, _patch: unknown) => (id === 'usb' ? { ok: true } : { ok: false, error: 'That device is not plugged into this computer.' }))
  }
  return { ...actual, CableFleet: FakeCable }
})
// The window bridges: their wiring is what the devices give them; their own behaviour has its own specs.
for (const [path, name] of [['../cable/windowSelection.js', 'WindowSelection'], ['../cable/windowVisit.js', 'WindowVisit'], ['../cable/windowForm.js', 'WindowForm']] as const) {
  vi.doMock(path, () => ({
    [name]: class {
      calls: Array<[string, unknown[]]> = []
      constructor(wiring: Record<string, (...args: unknown[]) => unknown>) { seen.bridges[name] = { wiring, calls: this.calls } }
      command(...args: unknown[]) { this.calls.push(['command', args]); return Promise.resolve({ ok: true }) }
      cancel(...args: unknown[]) { this.calls.push(['cancel', args]) }
      clear(...args: unknown[]) { this.calls.push(['clear', args]) }
      reply(...args: unknown[]) { this.calls.push(['reply', args]) }
      focusChanged(...args: unknown[]) { this.calls.push(['focusChanged', args]) }
      disconnected(...args: unknown[]) { this.calls.push(['disconnected', args]) }
    },
  }))
}
vi.mock('../cable/windowRoute.js', () => ({
  createWindowRouter: (wiring: Record<string, (...args: unknown[]) => unknown>) => {
    const calls: Array<[string, unknown[]]> = []
    seen.bridges.WindowRouter = { wiring, calls }
    return {
      ask: (...args: unknown[]) => { calls.push(['ask', args]); return Promise.resolve({ t: 'unavailable' }) },
      reply: (...args: unknown[]) => { calls.push(['reply', args]) },
    }
  },
}))
vi.mock('./fleet.js', async (real) => {
  const actual = await real<typeof import('./fleet.js')>()
  return {
    ...actual,
    startFleet: (_core: CoreApi, deps: FleetDeps) => {
      const state = { deps, events: null as ((event: FleetEvent) => void) | null, fail: false }
      seen.fleet = state
      const fleet = new Proxy({} as Fleet, {
        get: (_t, key) => {
          if (key === 'onEvent') return (listener: (event: FleetEvent) => void) => { state.events = listener; return () => {} }
          if (key === 'routeTask') return async (text: string) => ({ agentId: 'a1', machineId: 'm1', name: 'api', confidence: 1, reason: text, candidates: [], weighed: 1, machines: 1, via: 'model' })
          if (key === 'routeSend') return (agentId: string) => agentId === 'far' ? { ok: false, machine: 'mac-mini', reason: 'the last request to it did not come back' }
            : agentId === 'nameless' ? { ok: false, machine: '', reason: 'no such agent' } : { ok: true }
          if (key === 'knows') return () => { if (state.fail) throw new Error('lost'); return true }
          if (key === 'stop') return vi.fn()
          // Any other routing member: unanswered here, and failing once the test says the fleet fails.
          return () => { if (state.fail) throw new Error('lost') }
        },
      })
      return { fleet, router: null }
    },
  }
})
vi.mock('../lib/voiceRouter.js', () => ({
  setVoiceRouterSessions: seen.voice.sessions,
  setVoiceRouterDeviceConnected: seen.voice.connected,
  shutdownVoiceRouter: seen.voice.shutdown,
  routeVoiceTask: vi.fn(),
}))

const { startDevices } = await import('./devices.js')

let dataDir: string
let logs: string[]
beforeEach(() => {
  dataDir = mkdtempSync(join(tmpdir(), 'devices-'))
  logs = []
  seen.bridges = {}
  seen.fleet = null
  vi.clearAllMocks()
})
afterEach(() => {
  rmSync(dataDir, { recursive: true, force: true })
  vi.restoreAllMocks()
})

/** The account's machines: a Harness Team one (`team-mac`) and a computer of the person's own (`mac-mini`). */
const teamAccount = (core: CoreApi) => {
  vi.mocked(core.account.machines).mockResolvedValue({ status: 200, body: { success: true, data: { machines: [
    { machineId: 'team-mac', name: 'Diego’s Mac', sessionKind: 'team' },
    { machineId: 'mac-mini', name: 'Mac mini', sessionKind: 'computer' },
  ] } } })
  return seen.fleet!.deps.machines.refresh()
}

function start(over: { core?: CoreApi; faults?: string[]; cableDisabled?: boolean; testDialPort?: string; readUsage?: DevicesDeps['readUsage']; now?: () => number; decideTier?: DevicesDeps['decideTier'] | null } = {}) {
  const core = over.core ?? fakeCore({ dataDir })
  const ports: CorePorts = emptyPorts()
  const onExit = vi.fn()
  const reconnected: Array<() => void> = []
  const requests = startDevices(core, ports, {
    logsDir: join(dataDir, 'logs'),
    petsDir: join(dataDir, 'pets'),
    dialSerials: ['E2E'],
    testDialPort: over.testDialPort,
    cableDisabled: over.cableDisabled,
    readUsage: over.readUsage,
    now: over.now,
    decideTier: over.decideTier === null ? undefined : over.decideTier ?? (async () => ({ tier: 'alert', by: 'test', detail: '', ms: 0 })),
    faults: new Set(over.faults ?? []),
    log: (line) => { logs.push(line) },
    onExit,
    onCoreConnected: (run) => { reconnected.push(run) },
  })
  return { core, ports, port: ports.devices as DevicesPort, requests, onExit, reconnected }
}

const calls = (name: string) => seen.cable.calls.filter(([called]) => called === name).map(([, args]) => args)

describe('the devices, as the core starts them', () => {
  it('fill the devices port, start the dial, and stop the voice router\'s worker with the process', () => {
    const { ports, onExit } = start()
    expect(ports.devices).not.toBeNull()
    expect(calls('start')).toHaveLength(1)
    expect(seen.cable.args[2]).toBe(join(dataDir, 'logs'))
    expect(seen.cable.args[4]).toMatchObject({ serials: ['E2E'] })
    onExit.mock.calls[0][0]()
    expect(seen.voice.shutdown).toHaveBeenCalled()
  })

  it('keep the custom pets where petsDir says, and under HARNESS_DEVICES_DIR/pets by default', () => {
    const dir = join(dataDir, 'pets')
    mkdirSync(dir, { recursive: true })
    writeFileSync(join(dir, 'pets.json'), JSON.stringify({ all: 'a'.repeat(16), engines: {} }))
    start()
    expect(seen.host.pets!()!.mapping()).toEqual({ all: 'a'.repeat(16), engines: {} })
    // Without the option the store sits under env.HARNESS_DEVICES_DIR (never a path hard-coded in the service).
    const was = env.HARNESS_DEVICES_DIR
    ;(env as { HARNESS_DEVICES_DIR: string }).HARNESS_DEVICES_DIR = join(dataDir, 'home-devices')
    try {
      mkdirSync(join(dataDir, 'home-devices', 'pets'), { recursive: true })
      writeFileSync(join(dataDir, 'home-devices', 'pets', 'pets.json'), JSON.stringify({ all: 'b'.repeat(16), engines: {} }))
      startDevices(fakeCore({ dataDir }), emptyPorts(), { logsDir: join(dataDir, 'logs'), cableDisabled: true, log: () => {}, onExit: vi.fn() })
      expect(seen.host.pets!()!.mapping().all).toBe('b'.repeat(16))
    } finally {
      ;(env as { HARNESS_DEVICES_DIR: string }).HARNESS_DEVICES_DIR = was
    }
  })

  it('leave the serial ports alone when told to, and find the end-to-end suite\'s dial where it says', async () => {
    start({ cableDisabled: true, testDialPort: '/dev/ttys042' })
    expect(calls('start')).toHaveLength(0)
    expect(logs).toContain('[cable] disabled (CABLE_DISABLE=true) — the serial port is left alone')
    const options = seen.cable.args[4] as { discover: () => Promise<unknown[]> }
    expect(await options.discover()).toEqual([expect.objectContaining({ path: '/dev/ttys042' })])
  })

  it('cut an old dial log down to a pointer, and carry on when it cannot be written', () => {
    writeFileSync(join(dataDir, 'dial.log'), 'years of lines')
    start()
    expect(readFileSync(join(dataDir, 'dial.log'), 'utf8')).toBe(`moved to ${join(dataDir, 'logs', 'dial-YYYYMMDD.log')}\n`)
    rmSync(join(dataDir, 'dial.log'))
    mkdirSync(join(dataDir, 'dial.log'))
    expect(() => start()).not.toThrow()
  })

  it('log to the console by default, and register the worker\'s stop on the process\'s exit', () => {
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    const once = vi.spyOn(process, 'once').mockImplementation(() => process)
    startDevices(fakeCore({ dataDir }), emptyPorts(), { logsDir: dataDir, cableDisabled: true })
    expect(log).toHaveBeenCalledWith('[cable] disabled (CABLE_DISABLE=true) — the serial port is left alone')
    expect(once).toHaveBeenCalledWith('exit', expect.any(Function))
  })
})

describe('the dial\'s host, wired to the core', () => {
  it('reads the agents, this computer and the sign-in from the core, and reports a dial attached', async () => {
    const agent = { agentId: 'a1', engine: 'claude' } as RegisteredSession
    const core = fakeCore({ dataDir, agents: { advertised: vi.fn(() => [agent]), displayName: vi.fn(() => 'api'), activityText: vi.fn(async () => 'Reading'), runtimeProfile: vi.fn(() => 'p') } })
    start({ core })
    const w = seen.host
    expect(w.sessions()).toEqual([agent])
    expect(w.displayName(agent)).toBe('api')
    expect(await w.activityText!('a1')).toBe('Reading')
    expect(w.machineName()).toBe('This machine')
    expect(w.machineId()).toBe('machine-1')
    expect(w.computerId()).toBe('computer-1')
    expect(w.signedIn!()).toBe(true)
    expect(await w.accessToken!({ force: true })).toBe('token')
    expect(core.account.accessToken).toHaveBeenCalledWith({ force: true })
    expect(w.environment!()).toBe('prod')
    w.watching!(true)
    expect(core.clients.dialWatching).toHaveBeenCalledWith(true)
    expect(w.runtimeProfile!(agent)).toBe('p')
    w.log('cable: hello')
    expect(logs).toContain('[cable] cable: hello')
  })

  it('reaches an agent here through the core\'s own doors', async () => {
    const { core } = start()
    const w = seen.host
    w.sendTurn('a1', 'hello')
    w.stopTurn('a1')
    w.answer('a1', 'r1', { q: 'Coffee' })
    await w.answerReviewed!({ agentId: 'a1' } as never)
    w.recent('a1', 3)
    w.recentAsks('a1')
    w.updateAgent!('a1', 'opus', 'high')
    await w.listModels!('a1')
    await w.forkAgent!('a1')
    expect(core.turns.send).toHaveBeenCalledWith('a1', 'hello')
    expect(core.turns.stop).toHaveBeenCalledWith('a1')
    expect(core.questions.answer).toHaveBeenCalledWith('a1', 'r1', { q: 'Coffee' })
    expect(core.questions.answerReviewed).toHaveBeenCalledWith({ agentId: 'a1' })
    expect(core.turns.recent).toHaveBeenCalledWith('a1', 3)
    expect(core.turns.asks).toHaveBeenCalledWith('a1')
    expect(core.agents.setRuntime).toHaveBeenCalledWith('a1', 'opus', 'high')
    expect(core.agents.runtimeModels).toHaveBeenCalledWith('a1')
    expect(core.agents.fork).toHaveBeenCalledWith('a1')
    // A Super Tab wait is shown, never answered: nothing reaches the pane.
    w.answer('a1', 'supertab:as-1:needs_human', { q: 'Yes' })
    expect(await w.answerReviewed!({ agentId: 'a1', requestId: 'supertab:as-1:needs_human' } as never)).toBe(false)
    expect(core.questions.answer).toHaveBeenCalledTimes(1)
    expect(core.questions.answerReviewed).toHaveBeenCalledTimes(1)
  })

  it('tells the windows on this computer what a hand at this desk did, and the owner\'s apps the device status', () => {
    const { core } = start()
    const w = seen.host
    w.opened!('m1', 'a1')
    w.opened!('m1', 'a1', 'question')
    w.notificationRead!('m1', 'a1', 'tok')
    w.forked!('m1', 'a2', 'a1')
    w.focused!('m1', 'a1')
    w.swarmSelected!('t2')
    w.scrolled!('move', 4, 120)
    w.scrolled!('move', -6, 0, 'st1')
    w.dialStatus!({ attached: true, fw: '1.2.3' })
    w.dialStatus!({ attached: false })
    expect(vi.mocked(core.clients.sendLocal).mock.calls.map(([frame]) => frame)).toEqual([
      { type: 'dial_open', payload: { machineId: 'm1', agentId: 'a1' } },
      { type: 'dial_open', payload: { machineId: 'm1', agentId: 'a1', reason: 'question' } },
      { type: 'dial_notification_read', payload: { machineId: 'm1', agentId: 'a1', readToken: 'tok' } },
      { type: 'dial_forked', payload: { machineId: 'm1', agentId: 'a2', sourceAgentId: 'a1' } },
      { type: 'dial_focus', payload: { machineId: 'm1', agentId: 'a1' } },
      { type: 'dial_swarm', payload: { swarmId: 't2' } },
      { type: 'dial_scroll', payload: { phase: 'move', dy: 4, velocity: 120 } },
      { type: 'dial_scroll', payload: { phase: 'move', dy: -6, velocity: 0, superTabId: 'st1' } },
      { type: 'dial_status', payload: { attached: true, fw: '1.2.3' } },
      { type: 'dial_status', payload: { attached: false } },
    ])
    expect(vi.mocked(core.clients.devicesChanged).mock.calls).toEqual([
      [{ status: { attached: true, fw: '1.2.3' }, revision: 1 }],
      [{ status: { attached: false }, revision: 2 }],
    ])
  })

  it('speaks to the window through its bridges, and routes through the fleet', async () => {
    const { core } = start()
    const w = seen.host
    await w.routeInWindow!('fix it', 'review')
    await w.selectPassage!({ agentId: 'a1', op: 'begin' })
    w.clearSelection!()
    await w.visit!({ agentId: 'a1', op: 'open' } as never)
    w.clearVisit!()
    await w.form!({ op: 'open' } as never)
    w.clearForm!()
    expect(seen.bridges.WindowRouter.calls).toEqual([['ask', ['fix it', 'review']]])
    expect(seen.bridges.WindowSelection.calls.map(([name]) => name)).toEqual(['command', 'cancel'])
    expect(seen.bridges.WindowVisit.calls.map(([name]) => name)).toEqual(['command', 'cancel'])
    expect(seen.bridges.WindowForm.calls.map(([name]) => name)).toEqual(['command', 'clear'])
    expect(w.fleet!()).not.toBeNull()
    void core
  })
})

describe('the window bridges, wired to the core', () => {
  it('ask the window with the focus the core last gave, one window at a time', () => {
    const { core, port } = start()
    const { WindowSelection: selection, WindowVisit: visit, WindowForm: form, WindowRouter: router } = seen.bridges
    expect(selection.wiring.focus()).toBeUndefined()
    expect(visit.wiring.focus()).toBeUndefined()
    expect(form.wiring.focus()).toBeUndefined()
    expect(seen.host.appFocus!()).toBeUndefined()
    port.windowFocus({ voice: { machineId: 'm1', agentId: 'a1', connId: 'w1' }, form: { machineId: 'm1', connId: 'w1' } })
    expect(seen.host.appFocus!()).toMatchObject({ machineId: 'm1', agentId: 'a1' })
    expect(calls('followApp')).toEqual([['m1', 'a1']])
    expect(selection.wiring.focus()).toEqual({ machineId: 'm1', agentId: 'a1', connId: 'w1' })
    expect(visit.wiring.focus()).toEqual({ machineId: 'm1', agentId: 'a1', connId: 'w1' })
    expect(form.wiring.focus()).toEqual({ machineId: 'm1', connId: 'w1' })
    selection.wiring.send('w1', { op: 'begin' })
    visit.wiring.send('w1', { op: 'open' })
    form.wiring.send('w1', { op: 'open' })
    expect(vi.mocked(core.clients.sendToWindow).mock.calls).toEqual([
      ['w1', { type: 'dial_selection', payload: { op: 'begin' } }],
      ['w1', { type: 'dial_visit', payload: { op: 'open' } }],
      ['w1', { type: 'dial_form', payload: { op: 'open' } }],
    ])
    form.wiring.log('form: opened')
    router.wiring.log('route: asked')
    expect(logs).toEqual(expect.arrayContaining(['[cable] form: opened', '[cable] route: asked']))
    expect(router.wiring.hasWindow()).toBe(true)
    router.wiring.send('v1', 'fix it', undefined)
    router.wiring.send('v2', 'fix it', 'review')
    expect(vi.mocked(core.clients.sendLocal).mock.calls.map(([frame]) => frame)).toEqual([
      { type: 'voice_route_request', payload: { voiceId: 'v1', text: 'fix it' } },
      { type: 'voice_route_request', payload: { voiceId: 'v2', text: 'fix it', cmd: 'review' } },
    ])
    expect(logs).toContain('[route] voice → the window · 6 bytes · /review')
    port.windowFocus({ voice: null, form: null })
    expect(seen.host.appFocus!()).toBeUndefined()
    expect(calls('followApp')).toEqual([['m1', 'a1']])
  })

  it('hand each window\'s answer to its bridge, and tell them a window left', () => {
    const { port } = start()
    port.windowReply('selection', 'w1', 'm1', { a: 1 })
    port.windowReply('visit', 'w1', 'm1', { b: 2 })
    port.windowReply('form', 'w1', 'm1', { c: 3 })
    port.voiceReply('v1', { t: 'taken' })
    port.windowGone('w1')
    expect(seen.bridges.WindowSelection.calls).toEqual([['reply', ['w1', 'm1', { a: 1 }]], ['focusChanged', []]])
    expect(seen.bridges.WindowVisit.calls).toEqual([['reply', ['w1', 'm1', { b: 2 }]]])
    expect(seen.bridges.WindowForm.calls).toEqual([['reply', ['w1', 'm1', { c: 3 }]], ['disconnected', ['w1']]])
    expect(seen.bridges.WindowRouter.calls).toEqual([['reply', ['v1', { t: 'taken' }]]])
  })
})

describe('what the windows say, reaching the dial', () => {
  it('pushes a changed desk at once, and only a changed one, and says whether a tile is on screen', async () => {
    const { port } = start()
    port.desk(['a1', 'a2'], true)
    port.desk(['a1', 'a2'], true)
    port.desk(['a2', 'a1'], true)
    expect(calls('syncAgents')).toHaveLength(2)
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'done', recap: 'fixed it' } })
    port.desk(['a2', 'a1'], false)
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'done' } })
    port.card({ type: 'commander_event', agentId: 'a9', payload: { kind: 'summary', text: 'done', subagent: true } })
    await vi.waitFor(() => expect(calls('summary')).toHaveLength(3))
    // The one that asked the decider lands last: the other two never wait.
    expect(calls('summary')).toEqual([['a1', 'fixed it', 'done', 'silent', undefined, false], ['a9', 'done', 'done', 'silent', undefined, true], ['a1', 'done', 'done', 'alert', undefined, false]])
  })

  describe('a summary\'s tier', () => {
    it('decides a card without a tier by the fixed rules: a harness agent alerts, with no Jev call, and it is tallied', async () => {
      const backend = vi.fn()
      const { port } = start({ core: fakeCore({ dataDir, account: { backend } }), decideTier: null })
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'done', recap: 'The requested build is ready.' } })
      await vi.waitFor(() => expect(calls('summary')).toEqual([
        ['a1', 'The requested build is ready.', 'done', 'alert', undefined, false],
      ]))
      expect(backend).not.toHaveBeenCalled()
      expect(logs).toContainEqual(expect.stringMatching(/^\[cable\] notify · .* · alert · rule:turn · turn · \d+ms$/))
      expect(logs).toContainEqual(expect.stringMatching(/^\[cable\] notify · day \d{4}-\d\d-\d\d · alert 1 · list 0 · silent 0$/))
    })

    it.each(['lead', 'buddy', 'agent', 'coordinator'])('decides a local Swarm agent\'s card silent, whatever its role (%s)', async (role) => {
      const { port } = start({ core: fakeCore({ dataDir, agents: { byAgent: vi.fn(() => ({ agentId: 'a1', swarmSkill: { role, key: 'k' } }) as never) } }), decideTier: null })
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'done', recap: 'Built.' } })
      await vi.waitFor(() => expect(calls('summary')).toEqual([['a1', 'Built.', 'done', 'silent', undefined, false]]))
      expect(logs).toContainEqual(expect.stringMatching(/silent · rule:swarm · swarm/))
    })

    it('decides an agent on a Harness Team machine silent, and one on another computer of the person alert', async () => {
      const core = fakeCore({ dataDir })
      const { port } = start({ core, decideTier: null })
      await teamAccount(core)
      seen.fleet!.events!({ machineId: 'team-mac', kind: 'summary', agentId: 'reviewer', text: 'done', recap: 'Reviewed.' })
      seen.fleet!.events!({ machineId: 'mac-mini', kind: 'summary', agentId: 'far', text: 'done', recap: 'Done far.' })
      await vi.waitFor(() => expect(calls('summary')).toHaveLength(2))
      expect(calls('summary').map((c) => [c[0], c[3]])).toEqual([['reviewer', 'silent'], ['far', 'alert']])
      void port
    })

    // #2540's review (Orion): a card that carries a tier was followed before its machine was looked at, so a Team machine's
    // agent could alert. A Team machine runs Swarm work only.
    it('decides a Team machine\'s agent by the Team rule even when its card brings a tier, and follows any other card\'s', async () => {
      const core = fakeCore({ dataDir })
      const { port } = start({ core, decideTier: null })
      await teamAccount(core)
      const card = (event: FleetEvent) => seen.fleet!.events!(event)
      card({ machineId: 'team-mac', kind: 'summary', agentId: 'reviewer', text: 'done', recap: 'Reviewed.', tier: 'alert' })
      card({ machineId: 'mac-mini', kind: 'summary', agentId: 'far', text: 'done', recap: 'Done far.', tier: 'list' })
      await vi.waitFor(() => expect(calls('summary')).toHaveLength(2))
      // The one followed lands first; the one decided here waits for the decider.
      expect(new Map(calls('summary').map((c) => [c[0], c[3]]))).toEqual(new Map([['reviewer', 'silent'], ['far', 'list']]))
      expect(logs).toContainEqual(expect.stringMatching(/silent · rule:swarm · swarm/))
      void port
    })

    it('follows the tier another of the person\'s machines decided: a Swarm agent there is silent on this dial', async () => {
      const { port } = start({ decideTier: null })
      seen.fleet!.events!({ machineId: 'mac-mini', kind: 'summary', agentId: 'far-pm', text: 'done', recap: 'Planned.', tier: 'silent' })
      await vi.waitFor(() => expect(calls('summary')).toEqual([['far-pm', 'Planned.', 'done', 'silent', undefined, false]]))
      void port
    })

    it('still decides a remote card that came without a tier, and never throws', async () => {
      const { port } = start({ decideTier: null })
      expect(() => seen.fleet!.events!({ machineId: 'mac-mini', kind: 'summary', agentId: 'far', text: 'done', recap: '' })).not.toThrow()
      await vi.waitFor(() => expect(calls('summary')).toHaveLength(1))
      expect(calls('summary')[0][3]).toBe('alert') // a harness agent's, whatever machine it ran on
      void port
    })

    it('keeps a recap in the list when the decider rejects', async () => {
      const { port } = start({ decideTier: async () => { throw new Error('decision unavailable') } })
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'done', recap: 'The requested build is ready.', fullText: 'The full build report.' } })
      await vi.waitFor(() => expect(calls('summary')).toEqual([
        ['a1', 'The requested build is ready.', 'done', 'list', 'The full build report.', false],
      ]))
    })

    it('keeps the next turn behind a recap still waiting on the decider', async () => {
      vi.useFakeTimers()
      try {
        const decideTier = vi.fn(() => new Promise<{ tier: 'alert'; by: string; detail: string; ms: number }>((r) => setTimeout(() => r({ tier: 'alert', by: 't', detail: '', ms: 0 }), 500)))
        const { port } = start({ decideTier })
        port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'done', text: 'done' } })
        port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'done', recap: 'r' } })
        port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'processing', text: 'next' } })
        await vi.advanceTimersByTimeAsync(100)
        expect(seen.cable.calls.map(([n]) => n).filter((n) => n === 'summary' || n === 'turnStarted')).toEqual([])
        await vi.advanceTimersByTimeAsync(600)
        expect(seen.cable.calls.map(([n]) => n).filter((n) => n === 'summary' || n === 'turnStarted')).toEqual(['summary', 'turnStarted'])
      } finally { vi.useRealTimers() }
    })

    it('does not let a sub-agent\'s summary use up the main turn\'s numbers, and times a restarted turn afresh', async () => {
      const decideTier = vi.fn(async (_i: { durationS: number | null }) => ({ tier: 'alert' as const, by: 't', detail: '', ms: 0 }))
      const { port } = start({ decideTier })
      const card = (kind: string, extra = {}) => port.card({ type: 'commander_event', agentId: 'a1', payload: { kind, text: 'x', ...extra } })
      vi.useFakeTimers({ toFake: ['Date'] })
      try {
        vi.setSystemTime(0); card('processing')
        vi.setSystemTime(60_000); card('done')
        card('summary', { subagent: true })
        card('summary', { recap: 'first' })
        await vi.waitFor(() => expect(calls('summary')).toHaveLength(2))
        vi.setSystemTime(100_000); card('processing')
        await vi.waitFor(() => expect(calls('turnStarted')).toHaveLength(2))
        vi.setSystemTime(110_000); card('done')
        await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(2))
        card('summary', { recap: 'second' })
        await vi.waitFor(() => expect(decideTier).toHaveBeenCalledTimes(2))
      } finally { vi.useRealTimers() }
      expect(decideTier.mock.calls.map(([i]) => i.durationS)).toEqual([60, 10])
    })

    it('follows a tier the recaps already decided, asking nobody again, and still silences the agent on screen', () => {
      const decideTier = vi.fn()
      const { port } = start({ decideTier })
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'done', recap: 'Deployed', tier: 'list' } })
      expect(calls('summary')).toEqual([['a1', 'Deployed', 'done', 'list', undefined, false]])
      expect(decideTier).not.toHaveBeenCalled()
      expect(logs).toContainEqual(expect.stringMatching(/^\[cable\] notify · .* · list · recaps · decided upstream · 0ms$/))
      port.desk(['a2'], true)
      port.card({ type: 'commander_event', agentId: 'a2', payload: { kind: 'summary', text: 'done', tier: 'alert' } })
      expect(calls('summary').at(-1)).toEqual(['a2', 'done', 'done', 'silent', undefined, false])
      expect(decideTier).not.toHaveBeenCalled()
    })

    const summaryCalls = () => calls('summary')
    it('is silent without asking Jev when the agent is on screen or the turn was a sub-agent\'s', () => {
      const decideTier = vi.fn()
      const { port } = start({ decideTier })
      port.desk(['a1'], true)
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'done' } })
      port.card({ type: 'commander_event', agentId: 'a9', payload: { kind: 'summary', text: 'done', subagent: true } })
      expect(summaryCalls()).toEqual([['a1', 'done', 'done', 'silent', undefined, false], ['a9', 'done', 'done', 'silent', undefined, true]])
      expect(decideTier).not.toHaveBeenCalled()
    })

    it('never asks the decider while no device is connected, and still draws the tile', () => {
      const decideTier = vi.fn()
      const { port } = start({ decideTier })
      ;(seen.cable as unknown as { connected: boolean }).connected = false
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'done', recap: 'fixed it' } })
      expect(decideTier).not.toHaveBeenCalled()
      expect(summaryCalls()).toEqual([['a1', 'fixed it', 'done', 'silent', undefined, false]])
    })

    it('tells the decider a failed cloud summary failed, and logs rule decisions with the day\'s count', async () => {
      const decideTier = vi.fn(async () => ({ tier: 'alert' as const, by: 't', detail: '', ms: 0 }))
      const { port } = start({ decideTier })
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'x', recap: 'r', failed: true } })
      await vi.waitFor(() => expect(decideTier).toHaveBeenCalledWith(expect.objectContaining({ failed: true })))
      port.desk(['a2'], true)
      port.card({ type: 'commander_event', agentId: 'a2', payload: { kind: 'summary', text: 'x' } })
      port.card({ type: 'commander_event', agentId: 'a2', payload: { kind: 'error', text: 'boom' } })
      expect(logs.some((l) => /notify · .* · silent · rule:onScreen · onScreen · 0ms/.test(l))).toBe(true)
      expect(logs.some((l) => /notify · .* · alert · rule:failed/.test(l))).toBe(true)
      expect(logs.some((l) => /notify · day \d{4}-\d\d-\d\d · alert 1 · list 0 · silent 1/.test(l))).toBe(true)
    })

    it('is the decider\'s, asked with the duration and stats of the turn that just ended', async () => {
      const decideTier = vi.fn(async () => ({ tier: 'list' as const, by: 'test', detail: '', ms: 0 }))
      const { port } = start({ decideTier })
      vi.useFakeTimers()
      try {
        vi.setSystemTime(1_000_000)
        port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'processing', text: 'go' } })
        vi.setSystemTime(1_000_000 + 95_000)
        port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'done', text: 'done' } })
      } finally { vi.useRealTimers() }
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'done', recap: 'fixed it' } })
      await vi.waitFor(() => expect(summaryCalls()).toHaveLength(1))
      expect(decideTier).toHaveBeenCalledWith(expect.objectContaining({ recap: 'fixed it', durationS: 95, onScreen: false, subagent: false }))
      expect(summaryCalls()[0].slice(0, 4)).toEqual(['a1', 'fixed it', 'done', 'list'])
    })
  })

  it('passes the tabs, the unread rows, the window\'s focus and what it saw', () => {
    const { port } = start()
    port.swarms({ active: 't1', swarms: [], tiles: [] })
    port.unread([{ agentId: 'a1', machineId: 'm1', text: 'done', question: false }])
    port.appFocus('m1', 'a1')
    port.seen('a1', 'tok')
    expect(seen.cable.calls.map(([name]) => name)).toEqual(['start', 'syncSwarms', 'syncAgents', 'syncSwarmCards', 'replaceNotifications', 'followApp', 'agentSeen'])
    expect(calls('followApp')).toEqual([['m1', 'a1']])
    expect(calls('agentSeen')).toEqual([['a1', 'tok']])
  })

  describe('the Swarm cards for a Harness Pro', () => {
    const lead = { id: 'lead1', projectId: 'proj1', project: 'mobile', engine: 'claude', owner: '', local: '', state: 'work' as const, order: 0 }
    const cards = [{ id: 'st1', name: 'openharness', count: 1, leads: [lead] }]
    const withRequest = (superTabRequest?: CoreApi['superTabRequest']) => start({ core: { ...fakeCore({ dataDir }), ...(superTabRequest ? { superTabRequest } : {}) } as CoreApi })

    it('keeps the list for the cable and tells every device when it changes; a recap is passed on', () => {
      const { port } = start()
      port.swarmCards(cards)
      expect(seen.dial).toMatchObject({ cards })
      expect(calls('syncSwarmCards')).toEqual([[]])
      const recap = { tabId: 'st1', leadId: 'lead1', text: 'hi', at: 1, none: false }
      port.swarmCardRecap(recap)
      expect(calls('swarmCardRecap')).toEqual([[recap]])
    })

    it('asks the service for cards when the first capable device attaches and stops when the last leaves', () => {
      const superTabRequest = vi.fn(async () => ({ ok: true }))
      withRequest(superTabRequest)
      seen.host.swarmCardsWanted!(true)
      seen.host.swarmCardsWanted!(true)
      expect(superTabRequest.mock.calls).toEqual([[{ action: 'cardsWanted', on: true, include: [] }]])
      seen.host.swarmCardsWanted!(false)
      expect(superTabRequest).toHaveBeenCalledTimes(1)
      seen.host.swarmCardsWanted!(false)
      expect(superTabRequest.mock.calls[1]).toEqual([{ action: 'cardsWanted', on: false, include: [] }])
      // A stray "gone" never counts below none.
      seen.host.swarmCardsWanted!(false)
      seen.host.swarmCardsWanted!(true)
      expect(superTabRequest.mock.calls[2]).toEqual([{ action: 'cardsWanted', on: true, include: [] }])
    })

    it('sends the Swarms the desktop has tabs for with the wish, again when they change, and says it all again when the core reconnects', () => {
      const superTabRequest = vi.fn(async () => ({ ok: true }))
      const { port, reconnected } = withRequest(superTabRequest)
      const tabs = (...ids: string[]) => ({ active: 'a', tiles: [], swarms: [{ id: 'plain', name: 'plain', agentIds: [], panes: 0 }, ...ids.map((id) => ({ id: `tab-${id}`, name: id, agentIds: [], panes: 0, superTabId: id }))] })
      // Nobody wants cards yet: nothing is said, but the tabs are remembered.
      port.swarms(tabs('st1', 'st2', 'st1'))
      expect(superTabRequest).not.toHaveBeenCalled()
      seen.host.swarmCardsWanted!(true)
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardsWanted', on: true, include: ['st1', 'st2'] })
      port.swarms(tabs('st1', 'st2'))
      expect(superTabRequest).toHaveBeenCalledTimes(1)
      port.swarms(tabs('st2'))
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardsWanted', on: true, include: ['st2'] })
      // The window gone leaves no Swarm tab to read first.
      port.swarms(null)
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardsWanted', on: true, include: [] })
      port.swarms(tabs('st2'))
      // A core that connects anew has forgotten: the current count is said again, and nothing with no device.
      superTabRequest.mockClear()
      reconnected.forEach((run) => run())
      expect(superTabRequest.mock.calls).toEqual([[{ action: 'cardsWanted', on: true, include: ['st2'] }]])
      seen.host.swarmCardsWanted!(false)
      superTabRequest.mockClear()
      reconnected.forEach((run) => run())
      expect(superTabRequest).not.toHaveBeenCalled()
    })

    it('tells the cards the window\'s open Swarm conversation, again only when it changes', () => {
      const superTabRequest = vi.fn(async () => ({ ok: true }))
      const { port, reconnected } = withRequest(superTabRequest)
      const open = (active: string, conversationId?: string, threadRoot?: string) => ({ active, tiles: [], swarms: [
        { id: 'plain', name: 'plain', agentIds: [], panes: 0 },
        { id: 'tab-st1', name: 'st1', agentIds: [], panes: 0, superTabId: 'st1', projectId: 'p1', ...(conversationId ? { conversationId } : {}), ...(threadRoot ? { threadRoot } : {}) }] })
      port.swarms(open('tab-st1', 'pm1'))
      seen.host.swarmCardsWanted!(true)
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardsWanted', on: true, include: ['st1'], focus: { tabId: 'st1', conversationId: 'pm1' } })
      port.swarms(open('tab-st1', 'pm1'))
      expect(superTabRequest).toHaveBeenCalledTimes(1)
      port.swarms(open('tab-st1', 'g1'))
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardsWanted', on: true, include: ['st1'], focus: { tabId: 'st1', conversationId: 'g1' } })
      // Another tab active, or a Swarm tab that names no conversation: no focus, and the wish says none.
      port.swarms(open('plain', 'g1'))
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardsWanted', on: true, include: ['st1'] })
      port.swarms(open('tab-st1'))
      expect(superTabRequest).toHaveBeenCalledTimes(3)
      // Whether the window followed a device's own pick is no part of the focus any more.
      port.swarms({ ...open('tab-st1', 'g2'), fromDevice: true })
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardsWanted', on: true, include: ['st1'], focus: { tabId: 'st1', conversationId: 'g2' } })
      port.swarms(open('tab-st1', 'g1'))
      superTabRequest.mockClear()
      reconnected.forEach((run) => run())
      expect(superTabRequest.mock.calls).toEqual([[{ action: 'cardsWanted', on: true, include: ['st1'], focus: { tabId: 'st1', conversationId: 'g1' } }]])
      // A thread opened or closed beside it is no news to the cards.
      superTabRequest.mockClear()
      port.swarms(open('tab-st1', 'g1', 'm1'))
      port.swarms(open('tab-st1', 'g1'))
      expect(superTabRequest).not.toHaveBeenCalled()
      // Nobody wants cards: a focus change says nothing.
      seen.host.swarmCardsWanted!(false)
      superTabRequest.mockClear()
      port.swarms(open('tab-st1', 'pm1'))
      expect(superTabRequest).not.toHaveBeenCalled()
    })

    it('asks for the chat on the face for a swarmChat dial: recap, open and talk carry the flag, and a chat recap names its chat', async () => {
      const answers: Array<Record<string, unknown>> = [
        { ok: true, text: 'from the group', at: 3, none: false, chatId: 'g1' },
        { ok: true, text: 'no chat named', at: 3, none: false },
        { ok: true, text: 'bad chat', at: 3, none: false, chatId: 'bad id' },
        { ok: true, text: 'lead', at: 3, none: false, chatId: 'g1' },
        { ok: true, said: true },
      ]
      const superTabRequest = vi.fn(async (_payload: Record<string, unknown>) => answers.shift() ?? { ok: true })
      withRequest(superTabRequest)
      expect(await seen.host.swarmCardRecap!('st1', 'lead1', true)).toEqual({ tabId: 'st1', leadId: 'lead1', text: 'from the group', at: 3, none: false, chatId: 'g1' })
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardRecap', tabId: 'st1', leadId: 'lead1', chat: true })
      // A chat recap that does not name its chat by an id is no recap: the dial must not show it for another chat.
      expect(await seen.host.swarmCardRecap!('st1', 'lead1', true)).toBeNull()
      expect(await seen.host.swarmCardRecap!('st1', 'lead1', true)).toBeNull()
      // Without the flag, today's recap: no chat asked for, none passed on.
      expect(await seen.host.swarmCardRecap!('st1', 'lead1')).toEqual({ tabId: 'st1', leadId: 'lead1', text: 'lead', at: 3, none: false })
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardRecap', tabId: 'st1', leadId: 'lead1' })
      expect(await seen.host.swarmSay!('h1', 'ship it', true)).toEqual({ said: true })
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardSay', harnessId: 'h1', text: 'ship it', chat: true })
      seen.host.swarmCardOpen!('c1', 'st1', 'lead1', true)
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardOpen', session: 'c1', tabId: 'st1', leadId: 'lead1', chat: true })
      seen.host.swarmCardOpen!('c1', 'st1', null)
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardOpen', session: 'c1', tabId: 'st1', leadId: null })
    })

    // A refusal turned into null said nowhere why the dial's face stayed on the resting pet (Diego, 2026-11-03).
    it('fails a refused recap with the service\'s code, so the dial\'s log says why', async () => {
      withRequest(vi.fn(async () => ({ error: 'SERVICE_UNAVAILABLE' })))
      await expect(seen.host.swarmCardRecap!('st1', 'lead1', true)).rejects.toThrow('SERVICE_UNAVAILABLE')
    })

    it('asks for a swarmBuddy dial\'s face with the buddy flag, and says so on its recap', async () => {
      const answers: Array<Record<string, unknown>> = [
        { ok: true, text: 'from the Buddy', at: 3, none: false, chatId: 'b1', buddy: true },
        { ok: true, text: 'no chat named', at: 3, none: false, buddy: true },
        { ok: true, said: true },
      ]
      const superTabRequest = vi.fn(async (_payload: Record<string, unknown>) => answers.shift() ?? { ok: true })
      withRequest(superTabRequest)
      expect(await seen.host.swarmCardRecap!('st1', 'lead1', 'buddy')).toEqual({ tabId: 'st1', leadId: 'lead1', text: 'from the Buddy', at: 3, none: false, chatId: 'b1', buddy: true })
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardRecap', tabId: 'st1', leadId: 'lead1', chat: 'buddy' })
      expect(await seen.host.swarmCardRecap!('st1', 'lead1', 'buddy')).toBeNull()
      expect(await seen.host.swarmSay!('h1', 'ship it', 'buddy', 'pm1')).toEqual({ said: true })
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardSay', harnessId: 'h1', text: 'ship it', chat: 'buddy', chatId: 'pm1' })
      answers.unshift({ ok: true, said: true })
      expect(await seen.host.swarmSay!('h1', 'ship it', 'buddy', 'pm1', true)).toEqual({ said: true })
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardSay', harnessId: 'h1', text: 'ship it', chat: 'buddy', chatId: 'pm1', reviewed: true })
      seen.host.swarmCardOpen!('c1', 'st1', 'lead1', 'buddy')
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardOpen', session: 'c1', tabId: 'st1', leadId: 'lead1', chat: 'buddy' })
    })

    // Task #3908: a recap, a post and a pick carry no thread; the service's answers about one are not read.
    it('carries no thread on a recap or a post, whatever the service answers', async () => {
      const answers: Array<Record<string, unknown>> = [
        { ok: true, text: 'on it', at: 3, none: false, chatId: 'lead-c1', thread: 'm9' },
        { ok: true, said: true, thread: { tabId: 'st1', conversationId: 'lead-c1', root: 'm9' } },
        { ok: true, said: true },
      ]
      const superTabRequest = vi.fn(async (_payload: Record<string, unknown>) => answers.shift()!)
      const { core } = withRequest(superTabRequest)
      expect(await seen.host.swarmCardRecap!('st1', 'lead1', true)).toEqual({ tabId: 'st1', leadId: 'lead1', text: 'on it', at: 3, none: false, chatId: 'lead-c1' })
      expect(await seen.host.swarmSay!('h1', 'build it', true)).toEqual({ said: true })
      await seen.host.swarmSay!('h1', 'build it', true, 'lead-c1', true)
      expect(superTabRequest).toHaveBeenLastCalledWith({ action: 'cardSay', harnessId: 'h1', text: 'build it', chat: true, chatId: 'lead-c1', reviewed: true })
      // An ordinary pick is untouched.
      seen.host.superTabSelected!('st1', 'proj1', 'buddy')
      expect(vi.mocked(core.clients.sendLocal)).toHaveBeenLastCalledWith({ type: 'dial_super_tab', payload: { superTabId: 'st1', projectId: 'proj1', chat: 'buddy' } })
    })

    it('reads a recap through the service, cut to 1,500 bytes on a character; anything unusable is null', async () => {
      const answers: Array<Record<string, unknown> | 'throw'> = [
        { ok: true, tabId: 'st1', leadId: 'lead1', text: 'é'.repeat(1000), at: 1792560000, none: false },
        { ok: true, text: 'none', at: 0, none: true },
        { error: 'NOT_FOUND' }, { ok: true, text: 5, at: 1, none: false }, { ok: true, text: 'x', at: 1.5, none: false },
        { ok: true, text: 'x', at: -1, none: false }, { ok: true, text: 'x', at: 1, none: 'no' }, 'throw',
      ]
      const superTabRequest = vi.fn(async () => { const next = answers.shift()!; if (next === 'throw') throw new Error('gone'); return next })
      withRequest(superTabRequest)
      const got = await seen.host.swarmCardRecap!('st1', 'lead1')
      expect(superTabRequest).toHaveBeenCalledWith({ action: 'cardRecap', tabId: 'st1', leadId: 'lead1' })
      expect(got).toMatchObject({ tabId: 'st1', leadId: 'lead1', at: 1792560000, none: false })
      expect(got!.text).toBe('é'.repeat(750))
      expect(await seen.host.swarmCardRecap!('st1', 'lead2')).toEqual({ tabId: 'st1', leadId: 'lead2', text: 'none', at: 0, none: true })
      // A refusal fails with its code; anything else unusable is null.
      await expect(seen.host.swarmCardRecap!('st1', 'lead1')).rejects.toThrow('NOT_FOUND')
      for (let i = 0; i < 4; i++) expect(await seen.host.swarmCardRecap!('st1', 'lead1')).toBeNull()
      await expect(seen.host.swarmCardRecap!('st1', 'lead1')).rejects.toThrow('SERVICE_UNAVAILABLE')
    })

    it('posts words for a Lead through the service; anything but said: true sends the turn instead', async () => {
      const answers: Array<Record<string, unknown> | 'throw'> = [{ ok: true, said: true }, { ok: true, said: false }, { error: 'NOT_FOUND' }, 'throw']
      const superTabRequest = vi.fn(async () => { const next = answers.shift()!; if (next === 'throw') throw new Error('gone'); return next })
      withRequest(superTabRequest)
      expect(await seen.host.swarmSay!('h1', 'ship it')).toEqual({ said: true })
      expect(superTabRequest).toHaveBeenCalledWith({ action: 'cardSay', harnessId: 'h1', text: 'ship it' })
      for (let i = 0; i < 3; i++) expect(await seen.host.swarmSay!('h1', 'ship it')).toEqual({ said: false })
    })

    it('passes a refused post on, its message cut to what a dial shows; a malformed refusal is none', async () => {
      const answers: Array<Record<string, unknown>> = [
        { ok: true, said: false, refused: { code: 'PM_CHAT_READ_ONLY', message: 'Chat with PM is read-only.' } },
        { ok: true, said: false, refused: { code: 'BUDDY_FORBIDDEN', message: 'é'.repeat(400) } },
        { ok: true, said: false, refused: { code: 7, message: 'x' } }, { ok: true, said: false, refused: 'no' },
        { ok: true, said: true, refused: { code: 'X', message: 'x' } },
      ]
      withRequest(vi.fn(async () => answers.shift()!))
      expect(await seen.host.swarmSay!('h1', 'ship it')).toEqual({ said: false, refused: { code: 'PM_CHAT_READ_ONLY', message: 'Chat with PM is read-only.' } })
      expect(await seen.host.swarmSay!('h1', 'ship it')).toEqual({ said: false, refused: { code: 'BUDDY_FORBIDDEN', message: 'é'.repeat(150) } })
      expect(await seen.host.swarmSay!('h1', 'ship it')).toEqual({ said: false })
      expect(await seen.host.swarmSay!('h1', 'ship it')).toEqual({ said: false })
      expect(await seen.host.swarmSay!('h1', 'ship it')).toEqual({ said: true })
    })

    it('answers no recap when the core has no service to ask', async () => {
      start()
      await expect(seen.host.swarmCardRecap!('st1', 'lead1')).rejects.toThrow('SERVICE_UNAVAILABLE')
      seen.host.swarmCardOpen!('c1', 'st1', 'lead1')   // nothing to tell, and nothing thrown
    })

    it('tells the service which Lead is open, and opens a picked Lead on the desktop', () => {
      const superTabRequest = vi.fn(async () => ({ ok: true }))
      const { core } = withRequest(superTabRequest)
      seen.host.swarmCardOpen!('c1', 'st1', 'lead1')
      seen.host.swarmCardOpen!('c1', 'st1', null)
      expect(superTabRequest.mock.calls).toEqual([
        [{ action: 'cardOpen', session: 'c1', tabId: 'st1', leadId: 'lead1' }], [{ action: 'cardOpen', session: 'c1', tabId: 'st1', leadId: null }]])
      seen.host.superTabSelected!('st1', 'proj1')
      expect(vi.mocked(core.clients.sendLocal)).toHaveBeenCalledWith({ type: 'dial_super_tab', payload: { superTabId: 'st1', projectId: 'proj1' } })
      // A round dial's side rides along, so the window opens the Buddy chat or the Lead chat the dial shows.
      seen.host.superTabSelected!('st1', 'proj1', 'buddy')
      expect(vi.mocked(core.clients.sendLocal)).toHaveBeenLastCalledWith({ type: 'dial_super_tab', payload: { superTabId: 'st1', projectId: 'proj1', chat: 'buddy' } })
      seen.host.superTabSelected!('st1', 'proj1', 'pm')
      expect(vi.mocked(core.clients.sendLocal)).toHaveBeenLastCalledWith({ type: 'dial_super_tab', payload: { superTabId: 'st1', projectId: 'proj1', chat: 'pm' } })
    })
  })

  it('changes one device\'s settings, and logs a refusal', async () => {
    const { port } = start()
    port.settings('usb', { brightness: 3 })
    port.settings('', { brightness: 3 })
    port.settings('gone', { brightness: 3 })
    await vi.waitFor(() => expect(logs).toContain('[cable] settings for gone: That device is not plugged into this computer.'))
    expect(logs).toContain('[cable] settings for no device: That device is not plugged into this computer.')
  })

  it('translates every card for the devices into the dial\'s calls, and ignores the rest', () => {
    const { port } = start()
    const card = (kind: string) => port.card({ type: 'commander_event', agentId: 'a1', payload: { kind, text: kind } })
    card('processing'); card('done'); card('error'); card('tool')
    port.card({ type: 'commander_question', agentId: 'a1', payload: { requestId: 'r1', questions: [] } })
    port.card({ type: 'commander_question_close', agentId: 'a1', payload: { requestId: 'r1' } })
    port.card({ type: 'agent_deleted', payload: {} })
    expect(seen.cable.calls.map(([name]) => name)).toEqual(['start', 'turnStarted', 'turnDone', 'turnError', 'turnStep', 'question', 'questionClose'])
  })

  it('hands the dial a Super Tab wait with its tab and what it needs, as an alert', () => {
    const { port } = start()
    port.card({ type: 'commander_question', agentId: 'a1', payload: { requestId: 'supertab:as-1:blocked', questions: [{ q: 'Stuck: no key' }], superTab: 'Pilot', attention: 'stuck' } })
    port.card({ type: 'commander_question', agentId: 'a2', payload: { requestId: 'r2', questions: [], superTab: 'Pilot', attention: 'urgent' } })
    expect(calls('question')).toEqual([['a1', 'supertab:as-1:blocked', [{ q: 'Stuck: no key' }], { superTab: 'Pilot', attention: 'stuck' }],
      ['a2', 'r2', [], undefined]])
    expect(logs.some((l) => /notify · .* · alert · rule:super-tab · question/.test(l))).toBe(true)
  })

  it('hands the dial a tool card as a step, and a processing card\'s latest sentence beside the status', () => {
    const { port } = start()
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'tool', text: 'Read', recap: '/work/cli/src/cable/cableSession.ts' } })
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'processing', text: 'Working', update: 'Reading the spec' } })
    expect(seen.cable.calls.slice(1)).toEqual([['turnStep', ['a1', 'Read · cableSession.ts']], ['turnStarted', ['a1', 'Working', 'Reading the spec']]])
  })

  describe('the reply streaming to the dial', () => {
    const reply = (port: DevicesPort, update: string, agentId = 'a1') =>
      port.card({ type: 'commander_event', agentId, payload: { kind: 'reply_text', update } })
    beforeEach(() => { vi.useFakeTimers() })
    afterEach(() => { vi.useRealTimers() })

    it('sends at most once per 750 ms per agent, with a trailing send of the last text', async () => {
      const { port } = start()
      reply(port, 'one')                                   // t=0: sent at once
      await vi.advanceTimersByTimeAsync(100); reply(port, 'two')
      await vi.advanceTimersByTimeAsync(100); reply(port, 'three')
      expect(calls('turnReply')).toEqual([['a1', 'one']])
      await vi.advanceTimersByTimeAsync(550)               // t=750: the trailing send, with the 200 ms text
      expect(calls('turnReply')).toEqual([['a1', 'one'], ['a1', 'three']])
      await vi.advanceTimersByTimeAsync(150); reply(port, 'four')   // t=900
      await vi.advanceTimersByTimeAsync(599)
      expect(calls('turnReply')).toHaveLength(2)
      await vi.advanceTimersByTimeAsync(1)                 // t=1500
      expect(calls('turnReply')).toEqual([['a1', 'one'], ['a1', 'three'], ['a1', 'four']])
      await vi.advanceTimersByTimeAsync(5000)              // nothing piles up
      expect(calls('turnReply')).toHaveLength(3)
    })

    it('throttles each agent on its own', async () => {
      const { port } = start()
      reply(port, 'a', 'a1'); reply(port, 'b', 'a2')
      expect(calls('turnReply')).toEqual([['a1', 'a'], ['a2', 'b']])
    })

    it('flushes the last unsent text before the turn ends, and sends nothing after', async () => {
      const { port } = start()
      reply(port, 'one')
      await vi.advanceTimersByTimeAsync(500); reply(port, 'two')
      await vi.advanceTimersByTimeAsync(500)               // t=1000: the trailing send went at 750
      reply(port, 'three')
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'done', text: 'done' } })
      await vi.advanceTimersByTimeAsync(5000)
      expect(seen.cable.calls.slice(1).map(([name, args]) => [name, ...(name === 'turnReply' ? [args[1]] : [])]))
        .toEqual([['turnReply', 'one'], ['turnReply', 'two'], ['turnReply', 'three'], ['turnDone']])
    })

    it('ignores an empty update, ends quietly with nothing waiting, and forgets a deleted agent\'s pending text', async () => {
      const { port } = start()
      reply(port, '')
      reply(port, 'one')
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'done', text: 'done' } })   // nothing pending
      reply(port, 'two'); reply(port, 'three')
      port.card({ type: 'agent_deleted', payload: { agentId: 'a1' } })
      await vi.advanceTimersByTimeAsync(2000)
      expect(calls('turnReply')).toEqual([['a1', 'one'], ['a1', 'two']])
    })

    it('sends nothing after stop(), even with a send pending', async () => {
      const { port } = start()
      reply(port, 'one'); reply(port, 'two')
      await port.stop()
      await vi.advanceTimersByTimeAsync(5000)
      expect(calls('turnReply')).toEqual([['a1', 'one']])
    })

    it('throttles on the injected monotonic clock, not the wall clock', async () => {
      let mono = 1000
      const { port } = start({ now: () => mono })
      reply(port, 'one')
      vi.setSystemTime(Date.now() + 10 * 60_000)   // the wall clock jumps; the monotonic one does not
      reply(port, 'two')
      expect(calls('turnReply')).toEqual([['a1', 'one']])
      mono += 750; vi.setSystemTime(Date.now() - 20 * 60_000); reply(port, 'three')
      expect(calls('turnReply')).toEqual([['a1', 'one'], ['a1', 'three']])
    })

    it('drops a pending send when a new turn starts', async () => {
      const { port } = start()
      reply(port, 'one'); reply(port, 'two')
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'turn_started' } })
      await vi.advanceTimersByTimeAsync(2000)
      expect(calls('turnReply')).toEqual([['a1', 'one']])
    })

    it('keeps the streamed text for the working screen\'s first activity read', async () => {
      const { port } = start()
      reply(port, 'streamed so far')
      expect(await seen.host.activitySnapshot!('a1')).toEqual(null)
    })
  })

  it('sums a turn\'s shell results and tells the dial before the turn ends', () => {
    const { port } = start()
    const ran = (id: string, command: string, outputTail: string) =>
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'tool_end', id, tool: 'Bash', command, isError: false, outputTail } })
    ran('t1', 'git commit -m x', '[main abc] x')
    ran('t2', 'npm test', 'Tests: 44 passed')
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'tool_end' } })
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'tool_end', id: 't3', command: 'ls', isError: true } })
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'done', text: 'done' } })
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'done', text: 'done' } })
    expect(seen.cable.calls.slice(1).map(([name]) => name)).toEqual(['turnStats', 'turnDone', 'turnDone'])
    expect(calls('turnStats')).toEqual([['a1', { testsPassed: 44, testsFailed: 0, commits: 1 }]])
  })

  describe('a turn\'s tokens', () => {
    const ev = (port: DevicesPort, payload: object) => port.card({ type: 'commander_event', agentId: 'a1', payload })
    const readings = (...values: Array<{ input?: number; cached?: number; output?: number } | null>) => {
      const queue = [...values]
      return vi.fn(async (_id: string) => queue.shift() ?? null)
    }
    const turn = async (readUsage: DevicesDeps['readUsage'], tool = false) => {
      const { port } = start({ readUsage })
      ev(port, { kind: 'turn_started' })
      if (tool) {
        ev(port, { kind: 'tool_end', id: 't1', tool: 'Bash', command: 'git commit -m x', isError: false, outputTail: '[main abc] x' })
        ev(port, { kind: 'tool_end', id: 't2', tool: 'Bash', command: 'npm test', isError: false, outputTail: 'Tests: 44 passed' })
      }
      ev(port, { kind: 'done', text: 'done' })
      return port
    }
    const stats = () => calls('turnStats').map(([, f]) => f)

    it('sends the difference of the two readings before the turn ends, merged with tests and commits', async () => {
      const read = readings({ input: 1000, cached: 0, output: 200 }, { input: 43900, cached: 0, output: 18700 })
      await turn(read, true)
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
      expect(stats()).toEqual([{ testsPassed: 44, testsFailed: 0, commits: 1, tokensIn: 42900, tokensOut: 18500 }])
      expect(seen.cable.calls.slice(1).map(([name]) => name)).toEqual(['turnStats', 'turnDone'])
      expect(read).toHaveBeenCalledWith('a1')
    })

    it('counts input without cache reads: (input - cached) difference', async () => {
      await turn(readings({ input: 1_200_000, cached: 1_150_000, output: 1000 }, { input: 2_500_000, cached: 2_410_000, output: 6000 }))
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
      expect(stats()).toEqual([{ tokensIn: 40_000, tokensOut: 5000 }])
    })

    it('omits tokensIn, keeping tokensOut, when cached is unknown', async () => {
      await turn(readings({ input: 1_200_000, output: 10 }, { input: 2_500_000, cached: 2_410_000, output: 30 }))
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
      expect(stats()).toEqual([{ tokensOut: 20 }])
    })

    it.each([
      ['the start reading is missing', [null, { input: 5, cached: 0, output: 5 }]],
      ['the done reading is missing', [{ input: 5, cached: 0, output: 5 }, null]],
      ['a difference is negative', [{ input: 100, cached: 0, output: 100 }, { input: 50, cached: 0, output: 50 }]],
      ['a difference is over 50 000 000', [{ input: 0, cached: 0, output: 0 }, { input: 50_000_001, cached: 0, output: 50_000_001 }]],
    ] as const)('omits the fields when %s', async (_name, values) => {
      await turn(readings(...values))
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
      expect(stats()).toEqual([])
    })

    it('omits only the field whose difference is out of range', async () => {
      await turn(readings({ input: 0, cached: 0, output: 100 }, { input: 7, cached: 0, output: 50 }))
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
      expect(stats()).toEqual([{ tokensIn: 7 }])
    })

    it('reads the core\'s fresh usage by default, and none when the core has none', async () => {
      const usageFresh = vi.fn()
        .mockResolvedValueOnce({ inputTokens: 10, cachedTokens: 0, outputTokens: 1 })
        .mockResolvedValueOnce({ inputTokens: 30, cachedTokens: 0, outputTokens: 5 })
      const { port } = start({ core: { ...fakeCore({ dataDir }), usageFresh } })
      ev(port, { kind: 'turn_started' })
      ev(port, { kind: 'done', text: 'done' })
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
      expect(stats()).toEqual([{ tokensIn: 20, tokensOut: 4 }])
      const bare = start()
      ev(bare.port, { kind: 'turn_started' })
      ev(bare.port, { kind: 'done', text: 'done' })
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
      expect(stats()).toEqual([])  // a new dial session: its own calls
    })

    it('omits the fields when a reading throws, and still ends the turn', async () => {
      await turn(vi.fn(async () => { throw new Error('transcript gone') }))
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
      expect(stats()).toEqual([])
    })

    it('omits the fields for an agent whose usage is unknown or remote (null)', async () => {
      await turn(readings(null, null))
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
      expect(stats()).toEqual([])
    })

    it('does not hold the turn\'s end past 2 s for a slow done reading', async () => {
      vi.useFakeTimers()
      try {
        let n = 0
        const slow = vi.fn((_id: string) => (++n === 1 ? Promise.resolve({ input: 1, cached: 0, output: 1 }) : new Promise<{ input: number; cached: number; output: number }>((resolve) => setTimeout(() => resolve({ input: 9, cached: 0, output: 9 }), 2500))))
        await turn(slow, true)
        await vi.advanceTimersByTimeAsync(1999)
        expect(calls('turnDone')).toHaveLength(0)
        await vi.advanceTimersByTimeAsync(2)
        expect(calls('turnDone')).toHaveLength(1)
        expect(stats()).toEqual([{ testsPassed: 44, testsFailed: 0, commits: 1 }])
        await vi.advanceTimersByTimeAsync(1000)
        expect(calls('turnStats')).toHaveLength(1)
      } finally { vi.useRealTimers() }
    })

    it('drops the start reading when the turn errors, so the next turn starts clean', async () => {
      const read = readings({ input: 1, cached: 0, output: 1 }, { input: 9, cached: 0, output: 9 })
      const { port } = start({ readUsage: read })
      ev(port, { kind: 'turn_started' })
      ev(port, { kind: 'error', text: 'boom' })
      ev(port, { kind: 'done', text: 'done' })
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
      expect(stats()).toEqual([])
      expect(read).toHaveBeenCalledTimes(1)
    })

    it('keeps a card that follows a delayed done behind it', async () => {
      const { port } = start({ readUsage: readings({ input: 1, cached: 0, output: 1 }, { input: 2, cached: 0, output: 2 }) })
      ev(port, { kind: 'turn_started' })
      ev(port, { kind: 'done', text: 'done' })
      ev(port, { kind: 'processing', text: 'Working' })
      await vi.waitFor(() => expect(calls('turnStarted')).toHaveLength(1))
      expect(seen.cable.calls.slice(1).map(([name]) => name)).toEqual(['turnStats', 'turnDone', 'turnStarted'])
    })

    it('keeps a question, its close and a step behind a delayed done, in order', async () => {
      let finish!: (r: { input: number; cached: number; output: number }) => void
      let n = 0
      const slow = vi.fn((_id: string) => (++n === 1 ? Promise.resolve({ input: 1, cached: 0, output: 1 })
        : new Promise<{ input: number; cached: number; output: number }>((resolve) => { finish = resolve })))
      const { port } = start({ readUsage: slow })
      ev(port, { kind: 'turn_started' })
      ev(port, { kind: 'done', text: 'done' })
      port.card({ type: 'commander_question', agentId: 'a1', payload: { requestId: 'r1', questions: [] } })
      port.card({ type: 'commander_question_close', agentId: 'a1', payload: { requestId: 'r1' } })
      ev(port, { kind: 'tool', text: 'Read', recap: '/work/a.ts' })
      seen.fleet!.events!({ kind: 'question', agentId: 'a1', requestId: 'r2', questions: [] } as never)
      seen.fleet!.events!({ kind: 'questionClosed', agentId: 'a1', requestId: 'r2' } as never)
      port.card({ type: 'commander_question', agentId: 'other', payload: { requestId: 'r9', questions: [] } })
      expect(seen.cable.calls.slice(1).map(([name]) => name)).toEqual(['question'])  // another agent is not held
      finish({ input: 2, cached: 0, output: 2 })
      await vi.waitFor(() => expect(calls('questionClose')).toHaveLength(2))
      expect(seen.cable.calls.slice(1).map(([name]) => name)).toEqual(['question', 'turnStats', 'turnDone', 'question', 'questionClose', 'turnStep', 'question', 'questionClose'])
    })

    it('keeps the queue alive when a queued dispatch throws', async () => {
      const { port } = start({ readUsage: readings({ input: 1, cached: 0, output: 1 }, { input: 2, cached: 0, output: 2 }) })
      ev(port, { kind: 'turn_started' })
      ev(port, { kind: 'done', text: 'done' })
      const fake = seen.cable as unknown as Record<string, unknown>
      fake.turnStarted = () => { throw new Error('port gone') }
      ev(port, { kind: 'processing', text: 'Working' })
      await new Promise((resolve) => setTimeout(resolve, 20))
      fake.turnStarted = (...args: unknown[]) => { seen.cable.calls.push(['turnStarted', args]); return Promise.resolve() }
      ev(port, { kind: 'turn_started' })
      ev(port, { kind: 'done', text: 'again' })
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'processing', text: 'Next' } })
      await vi.waitFor(() => expect(calls('turnStarted')).toHaveLength(1))
    })

    it('reads no tokens, and sends done at once, when no connected dial asks for turn stats', () => {
      const read = readings({ input: 1, cached: 0, output: 1 }, { input: 2, cached: 0, output: 2 })
      const { port } = start({ readUsage: read })
      ;(seen.cable as unknown as { wants: boolean }).wants = false
      ev(port, { kind: 'turn_started' })
      ev(port, { kind: 'done', text: 'done' })
      expect(calls('turnDone')).toHaveLength(1)
      expect(read).not.toHaveBeenCalled()
    })
  })

  it('drops a turn\'s stats when it ends in an error, so the next turn starts clean', () => {
    const { port } = start()
    const ev = (payload: object) => port.card({ type: 'commander_event', agentId: 'a1', payload })
    ev({ kind: 'tool_end', id: 't1', tool: 'Bash', command: 'git commit -m x', isError: false, outputTail: '[main abc] x' })
    ev({ kind: 'error', text: 'boom' })
    ev({ kind: 'processing', text: 'Working' })
    ev({ kind: 'done', text: 'done' })
    expect(calls('turnStats')).toEqual([])
  })

  it('drops the stats a turn left behind when the next turn starts', async () => {
    const { port } = start()
    const ev = (payload: object) => port.card({ type: 'commander_event', agentId: 'a1', payload })
    ev({ kind: 'tool_end', id: 't1', tool: 'Bash', command: 'git commit -m x', isError: false, outputTail: '[main abc] x' })
    ev({ kind: 'turn_started' })
    ev({ kind: 'done', text: 'done' })
    await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(1))
    expect(calls('turnStats')).toEqual([])
  })

  it('hands the dial the whole answer a summary card carries', async () => {
    const { port } = start()
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'summary', text: 'b', recap: 'r', fullText: 'the whole answer' } })
    await vi.waitFor(() => expect(calls('summary')).toHaveLength(1))
    expect(seen.cable.calls.slice(1)).toEqual([['summary', ['a1', 'r', 'b', 'alert', 'the whole answer', false]]])
  })

  it('forgets an agent\'s latest sentence when its processing card has none, and when the agent goes', async () => {
    const { port, core } = start()
    vi.mocked(core.agents.activityText).mockResolvedValue('Working')
    const wired = () => seen.host.activitySnapshot!('a1')
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'processing', text: 'Working', update: 'First' } })
    expect(await wired()).toMatchObject({ action: 'First' })
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'processing', text: 'Working' } })
    expect(await wired()).not.toHaveProperty('action')
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'processing', text: 'Working', update: 'Second' } })
    port.card({ type: 'agent_deleted', payload: { agentId: 'a1' } })
    expect(await wired()).not.toHaveProperty('action')
  })

  it('prefers the core\'s activity snapshot, and has none when the core has nothing to say', async () => {
    const { core } = start()
    const wired = () => seen.host.activitySnapshot!('a1')
    vi.mocked(core.agents.activityText).mockResolvedValue(null as never)
    expect(await wired()).toBeNull()
    ;(core.agents as { activitySnapshot?: unknown }).activitySnapshot = vi.fn(async () => ({ text: 'Core', since: 5 }))
    expect(await wired()).toEqual({ text: 'Core', since: 5 })
  })

  it('says, with frame logging on, whether each card was teed to the dial', () => {
    const was = env.LOG_FRAMES
    ;(env as { LOG_FRAMES: boolean }).LOG_FRAMES = true
    try {
      const { port } = start()
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'done' } })
      port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'tool' } })
      port.card({ type: 'commander_event', agentId: 'a1' })
      expect(logs).toEqual(expect.arrayContaining(['[cable] tee done → sent', '[cable] tee tool → ignored', '[cable] tee ? → ignored']))
    } finally {
      ;(env as { LOG_FRAMES: boolean }).LOG_FRAMES = was
    }
  })

  it('logs a dial that throws on a card, and goes on', () => {
    const { port } = start({ faults: ['dial'] })
    port.card({ type: 'commander_event', agentId: 'a1', payload: { kind: 'done' } })
    port.desk(['a1'], true)
    expect(logs).toContain('[devices] dial failed · injected fault: dial')
    expect(calls('turnDone')).toEqual([])
  })
})

describe('the other machines\' cards', () => {
  it('reach the dial through the same calls as this computer\'s', async () => {
    start()
    const tell = seen.fleet!.events!
    tell({ machineId: 'm2', kind: 'state', state: 'ready' })
    tell({ machineId: 'm2', kind: 'questionClosed', agentId: 'b1', requestId: 'r1' })
    tell({ machineId: 'm2', kind: 'question', agentId: 'b1', requestId: 'r2', questions: [] })
    tell({ machineId: 'm2', kind: 'processing', agentId: 'b1', text: 'go', recap: '' })
    tell({ machineId: 'm2', kind: 'summary', agentId: 'b1', text: 'done', recap: 'fixed', subagent: true })
    tell({ machineId: 'm2', kind: 'summary', agentId: 'b1', text: 'done', recap: '' })
    await vi.waitFor(() => expect(calls('summary')).toHaveLength(2))
    expect(seen.cable.calls.map(([name]) => name)).toEqual(['start', 'syncMachines', 'questionClose', 'question', 'turnStarted', 'summary', 'summary'])
    expect(calls('summary')).toEqual([['b1', 'fixed', 'done', 'silent', undefined, true], ['b1', 'done', 'done', 'alert', undefined, false]])
  })
})

// A Swarm Reviewer on Diego's 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 report to their Lead, not to the person's dial.
describe('a failed turn of a Swarm worker', () => {
  const swarmAgents = (sessions: Array<Partial<RegisteredSession>>) => fakeCore({ dataDir, agents: {
    byAgent: vi.fn((id: string) => sessions.find((s) => s.agentId === id) as RegisteredSession | undefined),
  } })

  it('on a Harness Team account never reaches the dial as an error, and ends its tile quietly', async () => {
    const { core } = start()
    await teamAccount(core)
    seen.fleet!.events!({ machineId: 'team-mac', kind: 'processing', agentId: 'reviewer', text: 'go', recap: '' })
    seen.fleet!.events!({ machineId: 'team-mac', kind: 'error', agentId: 'reviewer', text: 'stream disconnected', recap: '' })
    await vi.waitFor(() => expect(calls('turnDone')).toEqual([['reviewer']]))
    expect(calls('turnError')).toEqual([])
  })

  it('the Swarm started on this computer, a Builder or a Reviewer, never reaches the dial as an error', async () => {
    const { port } = start({ core: swarmAgents([
      { agentId: 'builder', startedBy: 'agent', swarmSkill: { role: 'agent', key: 'k1' } },
      { agentId: 'reviewer', startedBy: 'agent', swarmSkill: { role: 'agent', fallback: 'review', key: 'k2' } },
    ]) })
    port.card({ type: 'commander_event', agentId: 'builder', payload: { kind: 'error', text: 'boom' } })
    port.card({ type: 'commander_event', agentId: 'reviewer', payload: { kind: 'error', text: 'boom' } })
    await vi.waitFor(() => expect(calls('turnDone')).toEqual([['builder'], ['reviewer']]))
    expect(calls('turnError')).toEqual([])
    expect(logs.some((l) => /notify · .* · silent · rule:swarm-worker/.test(l))).toBe(true)
  })

  it('the person has on a desk tab still reaches the dial as an error, as every desk agent\'s does', async () => {
    const { core, port } = start({ core: swarmAgents([
      { agentId: 'builder', startedBy: 'agent', swarmSkill: { role: 'agent', key: 'k1' } },
      { agentId: 'mine' },
    ]) })
    await teamAccount(core)
    port.swarms({ active: 't1', swarms: [
      { id: 't1', name: 'api', agentIds: ['mine'], panes: 1 },
      { id: 't2', name: 'Swarm', agentIds: ['builder'], panes: 1 },
    ], tiles: [] })
    port.desk(['reviewer'], false)
    port.card({ type: 'commander_event', agentId: 'mine', payload: { kind: 'error', text: 'mine broke' } })
    port.card({ type: 'commander_event', agentId: 'builder', payload: { kind: 'error', text: 'builder broke' } })
    seen.fleet!.events!({ machineId: 'team-mac', kind: 'error', agentId: 'reviewer', text: 'reviewer broke', recap: '' })
    // An agent on one of the person's own computers is the person's, whether or not it is on a tab.
    seen.fleet!.events!({ machineId: 'mac-mini', kind: 'error', agentId: 'far', text: 'far broke', recap: '' })
    await vi.waitFor(() => expect(calls('turnError')).toHaveLength(4))
    expect(calls('turnError')).toEqual([['mine', 'mine broke'], ['builder', 'builder broke'], ['reviewer', 'reviewer broke'], ['far', 'far broke']])
  })

  it('a person started by hand still reaches the dial as an error, even with a Builder\'s or Reviewer\'s role', async () => {
    const { port } = start({ core: swarmAgents([
      { agentId: 'builder', swarmSkill: { role: 'agent', key: 'k1' } },
      { agentId: 'reviewer', startedBy: undefined, swarmSkill: { role: 'agent', fallback: 'review', key: 'k2' } },
    ]) })
    port.card({ type: 'commander_event', agentId: 'builder', payload: { kind: 'error', text: 'builder broke' } })
    port.card({ type: 'commander_event', agentId: 'reviewer', payload: { kind: 'error', text: 'reviewer broke' } })
    await vi.waitFor(() => expect(calls('turnError')).toEqual([['builder', 'builder broke'], ['reviewer', 'reviewer broke']]))
    expect(calls('turnDone')).toEqual([])
  })

  describe('on another of the person\'s computers', () => {
    // The Swarm service says which agent on which machine is a worker, from the Swarms it read last (superTabs/cards.ts).
    const askedWorker = (workers: string[], fail = false, now?: () => number) => {
      const superTabRequest = vi.fn(async (payload: Record<string, unknown>) => {
        if (fail) throw new Error('service gone')
        return payload.action === 'cardWorker' ? { ok: true, worker: workers.includes(`${payload.machineId}/${payload.harnessId}`) } : { ok: true }
      })
      return { superTabRequest, ...start({ core: { ...fakeCore({ dataDir }), superTabRequest } as CoreApi, now }) }
    }
    const failed = (agentId: string, text = 'boom') => seen.fleet!.events!({ machineId: 'mac-mini', kind: 'error', agentId, text, recap: '' })
    const asks = (request: ReturnType<typeof vi.fn>) => request.mock.calls.filter(([p]) => (p as { action?: string }).action === 'cardWorker')

    it('keeps a Swarm worker\'s failure off the dial, asking once a minute at most', async () => {
      let clock = 0
      const { superTabRequest } = askedWorker(['mac-mini/builder'], false, () => clock)
      failed('builder')
      failed('builder')
      await vi.waitFor(() => expect(calls('turnDone')).toEqual([['builder'], ['builder']]))
      expect(calls('turnError')).toEqual([])
      expect(asks(superTabRequest)).toEqual([[{ action: 'cardWorker', machineId: 'mac-mini', harnessId: 'builder' }]])
      // A minute on, the Swarm may have changed: it is asked again.
      clock = 60_001
      failed('builder')
      await vi.waitFor(() => expect(calls('turnDone')).toHaveLength(3))
      expect(asks(superTabRequest)).toHaveLength(2)
    })

    it('shows the person\'s own agent\'s failure, and asks nothing for an agent on a tab', async () => {
      const { superTabRequest, port } = askedWorker(['mac-mini/builder'])
      port.swarms({ active: 't1', swarms: [{ id: 't1', name: 'api', agentIds: ['builder'], panes: 1 }], tiles: [] })
      failed('mine', 'mine broke')
      failed('builder', 'builder broke')
      // Each agent's cards keep their order; two agents' need not, and the one on a tab is not waited on.
      await vi.waitFor(() => expect(calls('turnError')).toHaveLength(2))
      expect(calls('turnError')).toEqual(expect.arrayContaining([['mine', 'mine broke'], ['builder', 'builder broke']]))
      expect(asks(superTabRequest)).toEqual([[{ action: 'cardWorker', machineId: 'mac-mini', harnessId: 'mine' }]])
    })

    it('forgets every answer once it holds 256, rather than grow with each agent that ever failed', async () => {
      const { superTabRequest } = askedWorker([])
      for (let n = 0; n < 256; n++) failed(`agent-${n}`)
      await vi.waitFor(() => expect(calls('turnError')).toHaveLength(256))
      failed('agent-0')
      failed('agent-256')
      await vi.waitFor(() => expect(calls('turnError')).toHaveLength(258))
      failed('agent-0')
      await vi.waitFor(() => expect(calls('turnError')).toHaveLength(259))
      // agent-0 was still held; agent-256 filled the store past 256, so agent-0 is asked again.
      expect(asks(superTabRequest).filter(([p]) => (p as { harnessId: string }).harnessId === 'agent-0')).toHaveLength(2)
    })

    it('waits 2 s at most for an answer, then shows the failure, so a hung service never leaves a tile working', async () => {
      vi.useFakeTimers()
      try {
        const superTabRequest = vi.fn((payload: Record<string, unknown>) =>
          payload.action === 'cardWorker' ? new Promise<Record<string, unknown>>(() => {}) : Promise.resolve({ ok: true }))
        start({ core: { ...fakeCore({ dataDir }), superTabRequest } as CoreApi })
        failed('builder', 'builder broke')
        await vi.advanceTimersByTimeAsync(1_999)
        expect(calls('turnError')).toEqual([])
        await vi.advanceTimersByTimeAsync(1)
        expect(calls('turnError')).toEqual([['builder', 'builder broke']])
        // Its next failure within the minute does not wait again.
        failed('builder', 'again')
        await vi.advanceTimersByTimeAsync(0)
        expect(calls('turnError')).toHaveLength(2)
        expect(asks(superTabRequest)).toHaveLength(1)
      } finally { vi.useRealTimers() }
    })

    it('shows the failure when the Swarm service cannot say', async () => {
      askedWorker([], true)
      failed('builder', 'builder broke')
      await vi.waitFor(() => expect(calls('turnError')).toEqual([['builder', 'builder broke']]))
    })
  })

  it('leaves a Lead\'s own failure as it was', async () => {
    const { port } = start({ core: swarmAgents([{ agentId: 'lead', swarmSkill: { role: 'coordinator', key: 'k' } }]) })
    port.card({ type: 'commander_event', agentId: 'lead', payload: { kind: 'error', text: 'lead broke' } })
    await vi.waitFor(() => expect(calls('turnError')).toEqual([['lead', 'lead broke']]))
    expect(calls('turnDone')).toEqual([])
  })

  it('on a machine once listed as a Harness Team account is the person\'s again once the list no longer says so', async () => {
    const { core } = start()
    await teamAccount(core)
    vi.mocked(core.account.machines).mockResolvedValue({ status: 401, body: {} })
    await seen.fleet!.deps.machines.refresh()
    seen.fleet!.events!({ machineId: 'team-mac', kind: 'error', agentId: 'reviewer', text: 'boom', recap: '' })
    await vi.waitFor(() => expect(calls('turnError')).toEqual([['reviewer', 'boom']]))
  })
})

describe('⌘K, the Wi-Fi device\'s borrowed walk, the voice router and stopping', () => {
  it('route a typed task and its send through the fleet, saying why a send was refused', async () => {
    const { port } = start()
    expect(await port.routeTask('fix the parser')).toMatchObject({ agentId: 'a1', reason: 'fix the parser' })
    expect(await port.routeSend('a1', 'go')).toEqual({ ok: true })
    expect(await port.routeSend('far', 'go')).toMatchObject({ ok: false, machine: 'mac-mini' })
    expect(await port.routeSend('nameless', 'go')).toMatchObject({ ok: false, machine: '' })
    expect(logs).toEqual(expect.arrayContaining([
      '[route] ⌘K → a1 · bytes=2',
      '[route] ⌘K → far · bytes=2 · REFUSED: the last request to it did not come back (mac-mini)',
      '[route] ⌘K → nameless · bytes=2 · REFUSED: no such agent',
    ]))
  })

  it('answer ⌘K with no agent list when the fleet did not start, and the dial routes this computer itself', async () => {
    const { port } = start({ faults: ['fleet'] })
    expect(await port.routeTask('anything')).toMatchObject({ agentId: '', reason: 'no agent list yet', candidates: [] })
    expect(await port.routeSend('a1', 'go')).toEqual({ ok: false, machine: '', reason: 'no agent list yet' })
    expect(logs).toContain('[devices] fleet did not start · injected fault: fleet · the devices run without it')
    expect(seen.host.fleet!()).toBeNull()
    await port.stop()
    expect(calls('stop')).toHaveLength(1)
  })

  it('answer the dial\'s routing as unavailable once the fleet fails, so the dial routes by itself', () => {
    start()
    seen.fleet!.fail = true
    expect(() => seen.host.fleet!()!.knows('a1')).toThrow(ServiceUnavailableError)
  })

  it('lend the Wi-Fi device the dial\'s walk and stroke', async () => {
    const { core, port } = start()
    port.desk(['a1', 'a2'], true)
    port.swarms({ active: 't1', swarms: [{ id: 't1', name: 'Tab', agentIds: ['a1', 'a2'], panes: 2 }], tiles: [] })
    vi.mocked(core.agents.advertised).mockReturnValue([{ agentId: 'a1', registeredAt: 1, engine: 'claude' }, { agentId: 'a2', registeredAt: 2, engine: 'claude' }] as RegisteredSession[])
    // The fleet's router is a stand-in here, so the walk is the host's own over the core's agents.
    seen.fleet!.fail = true
    expect(await port.stepFocus('next', 'a1')).toEqual(expect.objectContaining({ agentId: 'a2' }))
    port.scroll('down', 0, 0)
    expect(vi.mocked(core.clients.sendLocal).mock.calls.map(([frame]) => frame.type)).toEqual(['dial_focus', 'dial_scroll'])
  })

  it('walk the cloud harnesses on the desk too, where the core offers them', async () => {
    const { core, port } = start()
    port.desk(['a1', 'cloud_1'], true)
    port.swarms({ active: 't1', swarms: [{ id: 't1', name: 'Tab', agentIds: ['a1', 'cloud_1'], panes: 2 }], tiles: [] })
    vi.mocked(core.agents.advertised).mockReturnValue([{ agentId: 'a1', registeredAt: 1, engine: 'claude' }] as RegisteredSession[])
    core.agents.cloud = () => [{ agentId: 'cloud_1', registeredAt: 2, engine: 'fo' }] as unknown as RegisteredSession[]
    seen.fleet!.fail = true
    expect(await port.stepFocus('next', 'a1')).toEqual(expect.objectContaining({ agentId: 'cloud_1' }))
  })

  it('tell the voice router the engines here and whether a device watches, and stop everything', async () => {
    const { port } = start()
    port.engines(['claude', 'codex'])
    port.commanders(true)
    expect(seen.voice.sessions).toHaveBeenCalledWith([{ engine: 'claude' }, { engine: 'codex' }])
    expect(seen.voice.connected).toHaveBeenCalledWith(true)
    await port.stop()
    expect(calls('stop')).toHaveLength(1)
    expect(seen.voice.shutdown).toHaveBeenCalled()
  })
})

describe('the devices\' own copy of the machine list', () => {
  it('is read through the core, and writes no file of its own', async () => {
    const machines = vi.fn(async (): Promise<{ status: number; body: Record<string, unknown> }> => ({ status: 200, body: { success: true, data: { machines: [{ machineId: 'm1', computerId: 'computer-1', name: 'Mine', status: 'running' }] } } }))
    start({ core: fakeCore({ dataDir, account: { machines } }) })
    const list = seen.fleet!.deps.machines
    await list.refresh()
    expect(list.list()).toEqual({ source: 'backend', machines: [expect.objectContaining({ machineId: 'm1', local: true })] })
    expect(existsSync(join(dataDir, 'machines.json'))).toBe(false)
    machines.mockResolvedValueOnce({ status: 500, body: {} })
    await list.refresh()
    expect(logs).toContain('[cable] machines: HTTP 500 — showing the last known list')
    expect(seen.fleet!.deps.desk()).toEqual([])
  })
})

describe('the Devices tab', () => {
  it('answers the owner alone: the devices here, and one device\'s settings', async () => {
    const { requests } = start()
    // The dial's own status, as its session reports it to the host, which tells the windows (revision 1).
    seen.dial.onDialStatus({ attached: true, devices: [{ id: 'usb', attached: true, settings: { brightness: 80 } }] })
    const owner = { local: true, owner: true }
    expect(await requests.harness_devices_list({}, { local: false, owner: false })).toEqual({ error: 'OWNER_REQUIRED' })
    expect(await requests.harness_devices_list({}, owner)).toMatchObject({ protocol: 1, revision: 1, status: { attached: true } })
    expect(await requests.harness_device_settings({ id: 'usb', patch: { brightness: 35 } }, owner)).toMatchObject({ ok: true, revision: 1 })
    expect(seen.cable.setSettings).toHaveBeenCalledWith('usb', { brightness: 35 })
  })
  it('answers the pet requests to the owner on this computer only', async () => {
    const { requests } = start()
    for (const type of ['pet_preview', 'pet_apply', 'pet_reset', 'pet_status'] as const) {
      expect(await requests[type]({}, { local: false, owner: false })).toEqual({ error: 'OWNER_REQUIRED' })
      expect(await requests[type]({}, { local: true, owner: false })).toEqual({ error: 'OWNER_REQUIRED' })
      expect(await requests[type]({}, { local: false, owner: true })).toEqual({ error: 'LOCAL_ONLY' })
    }
    expect(await requests.pet_status({}, { local: true, owner: true })).toEqual({
      mapping: { all: null, engines: {} }, dial: { supported: false, held: [], sending: null }, pets: {},
    })
    expect(await requests.pet_apply({ target: 'all', id: '0123456789abcdef' }, { local: true, owner: true })).toMatchObject({ error: 'UNKNOWN_PET' })
    expect(calls('petsChanged')).toEqual([])
    // A changed mapping reaches every live dial.
    expect(await requests.pet_reset({ target: 'all' }, { local: true, owner: true })).toMatchObject({ ok: true })
    expect(calls('petsChanged')).toEqual([[]])
  })
})