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.

81.0 KB
Raw Blame
import { mkdtempSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { BackendNotice, TurnDelivery } from '../core/api.js'
import type { RegisteredSession } from '../lib/registry.js'
import { fakeCore } from '../testing/fakeCore.js'
import { PaneInbox } from './inbox.js'
import { deliveryKey, FYI_REASON, MAX_BACKOFF_MS, PUMP_MS } from './mailbox.js'
import { header, LEADER_ROLE, LIMITS, LONG_TEXT, longAdvice, MessageError, parseMessage, RULES, WORKER_ROLE, type Message } from './model.js'
import type { Rpc } from './rpc.js'
import { HELD_OFF_REASON, HELD_OUTSIDE_MS, MESSAGES_OFF_TEXT, REMOTE_STATUS_MS, SETTING_FRESH_MS, startAgentMessages, SWEEP_AFTER_MS, TICK_MS, WHO_MS } from './service.js'
import { MessageStore } from './store.js'
import { Ledger, ledgerPath } from '../agentClient/ledger.js'
import { agentSettingsPath } from '../lib/agentSettings.js'
import { setAgentSettingsForTest, signedOutForTest } from '../testing/agentSettings.js'

let root: string
beforeEach(() => {
  root = mkdtempSync(join(tmpdir(), 'agent-messages-'))
  // The account has turned Agent Messages on: off by default (lib/agentSettings.ts), and these are about what they do
  // once on. A test of the default removes the file.
  setAgentSettingsForTest(root, { agentMessages: true })
})
afterEach(() => { vi.useRealTimers(); rmSync(root, { recursive: true, force: true }); signedOutForTest() })

const OWNER_LOCAL = { local: true, owner: true }
const OWNER_REMOTE = { local: false, owner: true }
const session = (agentId: string, pane: string, engine = 'claude', cwd = `/work/${agentId}`) =>
  ({ agentId, sessionId: `s-${agentId}`, engine, cwd, tmuxPane: pane, runtimes: [{ backend: 'tmux', paneId: pane }], active: true, title: agentId }) as unknown as RegisteredSession
/** A harness in a pty host pane: its `tmuxPane` is that pane's id, which a tmux pane may also have. */
const ptySession = (agentId: string, pane: string, engine = 'claude', instance = 'p1') =>
  ({ ...session(agentId, pane, engine), runtimes: [{ backend: 'ptyhost', instance, paneId: pane }] }) as unknown as RegisteredSession

interface Setup {
  tabs?: Array<{ id: string; name: string; panes: Array<{ machineId: string; agentId: string }>; leader?: { machineId: string; agentId: string } | null }>
  agents?: RegisteredSession[]
  rpc?: Rpc
  backendStatus?: number
  signedIn?: () => boolean
  /** What each harness is doing, as `core.agents.activity` says: idle when not named. Not given, it knows none. */
  activity?: Record<string, 'working' | 'idle' | 'unknown'>
  /** Whether a Buddy session holds its owner's live grant here (lib/buddyGuard.ts `buddyGrantLive`). */
  buddyGranted?: (session: RegisteredSession) => boolean
}

function setup(over: Setup = {}) {
  let clock = 1_000_000
  const agents = over.agents ?? [session('lead', '%1', 'codex'), session('api', '%2'), session('web', '%3')]
  const tabs = over.tabs ?? [{ id: 'app', name: 'app', panes: [{ machineId: 'm1', agentId: 'lead' }, { machineId: 'm1', agentId: 'api' }, { machineId: 'm2', agentId: 'phone' }] }]
  const directory = { revision: 4, machines: [{ machineId: 'm1', name: 'studio' }, { machineId: 'm2', name: 'laptop' }], tabs }
  const delivered: Array<[string, string, string]> = []
  const windows: Array<Record<string, unknown>> = []
  const deliveryListeners = new Set<(event: TurnDelivery) => void>()
  const noticeListeners = new Set<(notice: BackendNotice) => void>()
  const backend = vi.fn(async (_method: string, _path: string, _body?: unknown) => ({ status: over.backendStatus ?? 200, body: { success: true, data: directory } }))
  const rpcCalls: Array<[string, Record<string, unknown>]> = []
  const rpc: Rpc = over.rpc ?? (async (target, payload) => {
    rpcCalls.push([target.machineId, payload])
    if (payload.action === 'who') return { agents: [{ agentId: 'phone', name: 'phone', engine: 'claude', project: 'app' }] }
    if (payload.action === 'deliver') return { statuses: [{ messageId: (payload.message as { id: string }).id, agentId: 'phone', state: 'queued' }] }
    return { statuses: [] }
  })
  const changed = vi.fn()
  /** The watches on the setting's file, armed while Agent Messages are off (settingWatch.ts): heard at a write. */
  const watchers = new Set<() => void>()
  const core = fakeCore({
    dataDir: root,
    daemon: { machineId: () => 'm1', port: 18473 },
    agents: {
      live: () => agents,
      displayName: (s) => (s as unknown as { title: string }).title,
      terminalAvailable: () => true,
      ...(over.activity ? { activity: async (ids: string[]) => Object.fromEntries(ids.map((id) => [id, over.activity?.[id] ?? 'idle'])) } : {}),
    },
    turns: {
      deliver: (agentId, text, id) => { delivered.push([agentId, text, id]) },
      onDelivery: (listener) => { deliveryListeners.add(listener); return () => deliveryListeners.delete(listener) },
    },
    account: {
      backend,
      onNotice: (listener) => { noticeListeners.add(listener); return () => noticeListeners.delete(listener) },
      ...(over.signedIn ? { signedIn: over.signedIn } : {}),
    },
    clients: { windows: (frame) => { windows.push(frame) } },
  })
  const service = startAgentMessages(core, { stateDir: join(root, 'state'), inboxRoot: join(root, 'inbox-root'), rpc: over.rpc ? over.rpc : rpc, now: () => clock, changed,
    ...(over.buddyGranted ? { buddyGranted: over.buddyGranted } : {}),
    watchSetting: (_path, heard) => { watchers.add(heard); return () => { watchers.delete(heard) } } })
  const ask = (payload: Record<string, unknown>, asker = OWNER_LOCAL) => service.requests.agent_messages!(payload, asker)
  return {
    service, ask, delivered, windows, backend, rpcCalls, agents, tabs, directory, changed, watchers,
    inbox: new PaneInbox(join(root, 'inbox-root')),
    tick: (ms: number) => { clock += ms },
    /** The account's switch as this computer keeps it, as the person turns Agent Messages on or off: read at the
     *  service's next look, once what it read last is no longer fresh, and heard by the watch on its file while off. */
    setting: (on: boolean) => {
      setAgentSettingsForTest(root, { agentMessages: on })
      clock += SETTING_FRESH_MS
      for (const heard of [...watchers]) heard()
    },
    deliveryEvent: (event: TurnDelivery) => { for (const l of deliveryListeners) l(event) },
    notice: (notice: BackendNotice) => { for (const l of noticeListeners) l(notice) },
  }
}

describe('harness send', () => {
  it('sends from the pane\'s harness to a teammate on this machine, typed into it when idle, with the roster note first', async () => {
    const t = setup()
    const reply = await t.ask({ action: 'send', pane: '%1', to: ['api'], text: 'Is the cleanup fix in?' })
    expect(reply).toMatchObject({ tab: 'app', recipients: [{ name: 'api', state: 'queued' }] })
    const id = reply.id as string
    expect(id).toMatch(/^m[0-9a-z]{7}$/)
    expect(t.delivered).toHaveLength(1)
    const [agentId, text, deliveryId] = t.delivered[0]
    expect(agentId).toBe('api')
    expect(deliveryId).toBe(`team:msg:${deliveryKey(id, 'api')}:1`)
    expect(text).toContain('[Harness] Agent Messages are on in tab "app". Teammates:')
    expect(text).toContain('lead')
    expect(text).toContain('phone')
    expect(text).toContain(`[${id} from lead · Codex · studio]\nIs the cleanup fix in?`)
    expect(t.service.canWrite(deliveryId)).toBe(true)
    // The core typed it: delivered, and the windows hear of it.
    t.deliveryEvent({ deliveryId, sessionId: 'api', state: 'started' })
    const history = await t.ask({ action: 'history', tabId: 'app' })
    expect(history.messages).toEqual([expect.objectContaining({ id, statuses: expect.arrayContaining([
      expect.objectContaining({ machineId: 'm1', agentId: 'api', state: 'delivered', via: 'prompt' }),
    ]) })])
    expect(t.windows.at(-1)).toMatchObject({ type: 'messages_changed', payload: { tabId: 'app', messageId: id, to: [{ agentId: 'api', state: 'delivered' }] } })
    // The note rode with the message: the next one comes without it.
    const second = await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'thanks' })
    expect(t.delivered.at(-1)![1]).toBe(`[${second.id} from lead · Codex · studio]\nthanks`)
  })

  it('hands a teammate on another machine to that machine, and asks later what became of it', async () => {
    const t = setup()
    const reply = await t.ask({ action: 'send', pane: '%1', to: ['phone'], text: 'ping' })
    expect(reply.recipients).toEqual([{ name: 'phone', state: 'queued' }])
    expect(t.rpcCalls.map(([machine, p]) => [machine, p.action])).toEqual([['m2', 'who'], ['m2', 'deliver']])
    expect(t.rpcCalls[1][1].message).toMatchObject({ id: reply.id, from: { agentId: 'lead', machine: 'studio' }, to: [{ machineId: 'm2', agentId: 'phone', name: 'phone' }] })
    t.tick(REMOTE_STATUS_MS)
  })

  it('without a recipient lists who is here; and says plainly what is wrong with a send', async () => {
    const t = setup()
    const roster = await t.ask({ action: 'send', pane: '%1' })
    expect(roster.roster).toContain('Teammates:')
    expect(roster.roster).toMatch(/api\s+Claude Code · studio · api/)
    expect(roster.roster).toMatch(/phone\s+Claude Code · laptop · app/)
    // A tab no other account shares: the note as it was before shared tabs, to the byte (no account, branch or GitHub lines).
    expect(roster.roster).toBe(['[Harness] Agent Messages are on in tab "app". Teammates:', '  api    Claude Code · studio · api', '  phone  Claude Code · laptop · app', RULES].join('\n'))
    const fail = async (payload: Record<string, unknown>, asker = OWNER_LOCAL) => (await t.ask(payload, asker)).error
    expect(await fail({ action: 'send', pane: 'nope', to: 'api', text: 'x' })).toBe('NOT_A_HARNESS')
    expect(await fail({ action: 'send', pane: '%99', to: 'api', text: 'x' })).toBe('NOT_A_HARNESS')
    expect(await fail({ action: 'send', pane: '%1', text: 'x' })).toBe('USAGE')
    expect(await fail({ action: 'send', pane: '%1', to: 'api', text: '  ' })).toBe('USAGE')
    expect(await fail({ action: 'send', pane: '%1', to: 'api', text: 'x'.repeat(LIMITS.text + 1) })).toBe('TOO_LONG')
    expect(await fail({ action: 'send', pane: '%1', to: 'nobody', text: 'x' })).toBe('UNKNOWN_RECIPIENT')
    // A unique start of a name is enough.
    expect((await t.ask({ action: 'send', pane: '%1', to: 'ph', text: 'x' })).recipients).toEqual([{ name: 'phone', state: 'queued' }])
    expect(await fail({ action: 'send', pane: '%1', to: 'api', text: 'x' }, OWNER_REMOTE)).toBe('LOCAL_ONLY')
    expect(await fail({ action: 'send', pane: '%1', to: 'api', text: 'x' }, { local: true, owner: false })).toBe('OWNER_REQUIRED')
    expect(await fail({ action: 'nonsense' })).toBe('UNKNOWN_ACTION')
    // Sent to the same teammate twice in one message: once.
    const twice = await t.ask({ action: 'send', pane: '%1', to: 'api,API', text: 'once' })
    expect(twice.recipients).toHaveLength(1)
    // Its last messages come back with the roster, as the sender and as the recipient see them.
    const lead = await t.ask({ action: 'send', pane: '%1' })
    expect((lead.recent as Array<Record<string, unknown>>).at(-1)).toMatchObject({ id: twice.id, to: ['api'], text: 'once', state: 'queued' })
    const api = await t.ask({ action: 'send', pane: '%2' })
    expect((api.recent as Array<Record<string, unknown>>).at(-1)).toMatchObject({ id: twice.id, from: 'lead', state: 'queued' })
  })

  it('gives an agent that reads its messages itself every one still waiting, whole and once, then its last few', async () => {
    // A Codex lead running since before Agent Messages never ran the hook and, always working, was never typed to: it
    // read `harness send` alone, which gave only its last five, each still "queued" (2026-10-12).
    const t = setup()
    const ids: string[] = []
    for (let i = 1; i <= 7; i++) {
      const sent = await t.ask({ action: 'send', pane: '%1', to: 'api', text: `finding ${i}\nwith its details` })
      ids.push(String(sent.id))
      // api is working: each typed attempt goes back to the hook, which never runs.
      t.deliveryEvent({ deliveryId: t.delivered.at(-1)![2], sessionId: 'api', state: 'rejected', reason: 'team_waiting_idle' })
    }
    const first = (await t.ask({ action: 'send', pane: '%2' })).recent as Array<Record<string, unknown>>
    const unread = first.filter((m) => m.unread === true)
    expect(unread.map((m) => m.id)).toEqual(ids)
    expect(unread.every((m) => m.state === 'delivered' && m.text === `finding ${ids.indexOf(String(m.id)) + 1}\nwith its details`)).toBe(true)
    const history = await t.ask({ action: 'history', tabId: 'app' }) as { messages: Array<{ statuses: Array<Record<string, unknown>> }> }
    expect(history.messages.flatMap((m) => m.statuses).filter((s) => s.agentId === 'api').every((s) => s.state === 'delivered' && s.via === 'read')).toBe(true)
    // Read once: the next look gives nothing new, and its last five as before.
    const again = (await t.ask({ action: 'send', pane: '%2' })).recent as Array<Record<string, unknown>>
    expect(again.filter((m) => m.unread)).toEqual([])
    expect(again.map((m) => m.id)).toEqual(ids.slice(-5))
    // The sender sees them delivered.
    const lead = (await t.ask({ action: 'send', pane: '%1' })).recent as Array<Record<string, unknown>>
    expect(lead.every((m) => m.state === 'delivered')).toBe(true)
  })

  it('sends news that never starts a turn of an idle teammate, marked as news where it is read', async () => {
    const t = setup()
    const sent = await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'quiet window 04:19–04:22Z', fyi: true })
    expect(sent.recipients).toEqual([{ name: 'api', state: 'queued', reason: FYI_REASON }])
    expect(t.delivered).toEqual([])
    const read = (await t.ask({ action: 'send', pane: '%2' })).recent as Array<Record<string, unknown>>
    expect(read.find((m) => m.id === sent.id)).toMatchObject({ unread: true, state: 'delivered', text: 'quiet window 04:19–04:22Z' })
    const history = await t.ask({ action: 'history', tabId: 'app' }) as { messages: Array<Record<string, unknown>> }
    expect(history.messages.find((m) => m.id === sent.id)).toMatchObject({ fyi: true })
    expect(header({ ...(history.messages[0] as unknown as Message), fyi: true })).toMatch(/ · FYI\]$/)
    expect(header({ ...(history.messages[0] as unknown as Message), fyi: undefined })).not.toMatch(/FYI/)
    // Only `true` is news on the wire.
    expect(parseMessage({ ...history.messages[0], fyi: 'yes' })).not.toHaveProperty('fyi')
  })

  it('sends a long message, and tells its sender what it costs the teammates who read it', async () => {
    const t = setup()
    expect(await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'x'.repeat(LONG_TEXT) })).not.toHaveProperty('advice')
    const long = await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'x'.repeat(LONG_TEXT + 1) })
    expect(long.recipients).toHaveLength(1)
    expect(long.advice).toBe(longAdvice(LONG_TEXT + 1))
    expect(long.advice).toMatch(/leave the rest in the repo/)
  })

  it('tells two teammates with the same start apart only by more of the name', async () => {
    const t = setup({
      agents: [session('lead', '%1'), session('api-a', '%2'), session('api-b', '%3')],
      tabs: [{ id: 'app', name: 'app', panes: ['lead', 'api-a', 'api-b'].map((agentId) => ({ machineId: 'm1', agentId })) }],
    })
    expect((await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })).error).toBe('AMBIGUOUS_RECIPIENT')
    expect((await t.ask({ action: 'send', pane: '%1', to: 'api-b', text: 'x' })).recipients).toEqual([{ name: 'api-b', state: 'queued' }])
  })

  it('tells apart teammates that share a title, the sender included, by the start of their ids', async () => {
    // Two Codex agents titled themselves after the same task, and the roster named the teammate as the agent itself
    // (a fresh Mac, 2026-10-12).
    const titled = (agentId: string, pane: string) => ({ ...session(agentId, pane, 'codex'), title: 'Ask teammate to create notes' }) as unknown as RegisteredSession
    const t = setup({
      agents: [titled('efedc3c7-lead', '%1'), titled('07934321-one', '%2'), titled('11112222-two', '%3')],
      tabs: [{ id: 'app', name: 'app', panes: ['efedc3c7-lead', '07934321-one', '11112222-two'].map((agentId) => ({ machineId: 'm1', agentId })) }],
    })
    const roster = String((await t.ask({ action: 'send', pane: '%1' })).roster)
    expect(roster).toContain('Ask teammate to create notes (07934321)')
    expect(roster).toContain('Ask teammate to create notes (11112222)')
    expect((await t.ask({ action: 'send', pane: '%1', to: 'Ask teammate to create notes', text: 'x' })).error).toBe('AMBIGUOUS_RECIPIENT')
    expect((await t.ask({ action: 'send', pane: '%1', to: 'Ask teammate to create notes (07934321)', text: 'x' })).recipients)
      .toEqual([{ name: 'Ask teammate to create notes (07934321)', state: 'queued' }])
    expect((await t.ask({ action: 'send', pane: '%1', to: '11112222', text: 'x' })).recipients)
      .toEqual([{ name: 'Ask teammate to create notes (11112222)', state: 'queued' }])
    // Its header names the sender as its teammates' roster does, so a reply finds it.
    const history = await t.ask({ action: 'history' }) as { messages: Array<{ from: { name: string } }> }
    expect(history.messages.map((m) => m.from.name)).toEqual(['Ask teammate to create notes (efedc3c7)', 'Ask teammate to create notes (efedc3c7)'])
    // A title no one else has stays as it is.
    const plain = setup()
    expect(String((await plain.ask({ action: 'send', pane: '%1' })).roster)).toMatch(/^ {2}api {2}/m)
  })

  it('takes the whole name of a teammate whose engine cut its title short', async () => {
    // Codex titles its terminal with the folder cut to fit; an agent wrote the folder out and was told no one had
    // that name (a fresh Mac, 2026-10-12).
    const t = setup({
      agents: [session('lead', '%1'), { ...session('cx', '%2', 'codex'), title: 'claude-code-2026-10-1...' } as unknown as RegisteredSession,
        { ...session('dots', '%3', 'codex'), title: '...' } as unknown as RegisteredSession],
      tabs: [{ id: 'app', name: 'app', panes: ['lead', 'cx', 'dots'].map((agentId) => ({ machineId: 'm1', agentId })) }],
    })
    expect((await t.ask({ action: 'send', pane: '%1', to: 'claude-code-2026-10-12-02-15', text: 'x' })).recipients)
      .toEqual([{ name: 'claude-code-2026-10-1...', state: 'queued' }])
    expect((await t.ask({ action: 'send', pane: '%1', to: 'claude-code-2026-10-1…', text: 'x' })).recipients)
      .toEqual([{ name: 'claude-code-2026-10-1...', state: 'queued' }])
    // A title that is nothing but an ellipsis is no stem for every name.
    expect((await t.ask({ action: 'send', pane: '%1', to: 'zzz', text: 'x' })).error).toBe('UNKNOWN_RECIPIENT')
  })

  it('names in the note only a tab the person named; the windows label any other themselves', async () => {
    // The note said tab "New Tab" for a tab the window showed as "code" (a fresh Mac, 2026-10-12).
    const pair = [{ machineId: 'm1', agentId: 'lead' }, { machineId: 'm1', agentId: 'api' }]
    const roster = async (tabs: Array<Record<string, unknown>>) =>
      String((await setup({ tabs: tabs as unknown as Setup['tabs'] }).ask({ action: 'send', pane: '%1' })).roster).split('\n')[0]
    expect(await roster([{ id: 'a', name: 'claude-code-2026-10-12-02-15', named: false, panes: pair }]))
      .toBe('[Harness] Agent Messages are on in this tab. Teammates:')
    expect(await roster([{ id: 'a', name: 'app', named: true, panes: pair }])).toBe('[Harness] Agent Messages are on in tab "app". Teammates:')
    expect(await roster([{ id: 'a', name: 'app', named: true, panes: pair }, { id: 'b', name: 'web', named: true, panes: pair }]))
      .toBe('[Harness] Agent Messages are on in tabs "app", "web". Teammates:')
    expect(await roster([{ id: 'a', name: 'app', named: true, panes: pair }, { id: 'b', name: 'New Tab', named: false, panes: pair }]))
      .toBe('[Harness] Agent Messages are on in tab "app" and this one. Teammates:')
    // A backend from before `named`: only the window's own default name is no name.
    expect(await roster([{ id: 'a', name: 'New Tab', panes: pair }])).toBe('[Harness] Agent Messages are on in this tab. Teammates:')
    expect(await roster([{ id: 'a', name: 'app', panes: pair }])).toBe('[Harness] Agent Messages are on in tab "app". Teammates:')
  })

  it('refuses while Agent Messages are off on this computer, saying where to turn them on, and when the directory cannot be read', async () => {
    // One switch of the account replaced each tab's chat icon, which the owner hit by mistake (2026-10-12).
    // The agent asks the person, and turns it on only after their yes (lib/agentSettings.ts `askThePersonFirst`).
    const refused = { error: 'MESSAGES_OFF', detail: MESSAGES_OFF_TEXT }
    expect(MESSAGES_OFF_TEXT).toMatch(/^Agent Messages are off\. agent-messages is off\. Ask the person, .*"May agents in the same tab message each other\?" Only if they say yes, run `harness settings agent-messages on --person-said-yes`.* If they say no: work on without messaging your teammates\.$/)
    // An account that never said: off by default, so nothing is sent and no one is told of teammates.
    rmSync(agentSettingsPath(root))
    const fresh = setup()
    expect(await fresh.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })).toEqual(refused)
    expect(await fresh.ask({ action: 'send', pane: '%1' })).toEqual(refused)
    expect(fresh.delivered).toEqual([])
    const off = setup()
    off.setting(true)
    off.setting(false)
    expect(await off.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })).toEqual(refused)
    expect(MESSAGES_OFF_TEXT).toBe(refused.detail)
    // Nor does `harness send` alone list anyone.
    expect(await off.ask({ action: 'send', pane: '%1' })).toEqual(refused)
    expect(off.delivered).toEqual([])
    // Off is the person's word: said so even when the tabs cannot be read.
    const offAndDown = setup({ backendStatus: 500 })
    expect(await offAndDown.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })).toEqual(refused)
    // On again: it sends at the next look.
    off.setting(true)
    expect((await off.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })).recipients).toEqual([{ name: 'api', state: 'queued' }])
    const down = setup({ backendStatus: 500 })
    expect(await down.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })).toMatchObject({ error: 'DIRECTORY_UNAVAILABLE' })
  })

  it('says a harness alone in its tab, or in none, has no teammates, and still lists its last messages', async () => {
    const alone = setup({ tabs: [{ id: 'app', name: 'app', panes: [{ machineId: 'm1', agentId: 'lead' }] }, { id: 'web', name: 'web', panes: [{ machineId: 'm1', agentId: 'api' }] }] })
    const none = { error: 'NO_TEAMMATES', detail: 'No other harness is in this tab. The person puts harnesses in one tab for them to message each other.' }
    expect(await alone.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })).toEqual(none)
    expect(await alone.ask({ action: 'send', pane: '%1', text: 'x' })).toEqual(none)
    // web is in no tab at all.
    expect(await alone.ask({ action: 'send', pane: '%3', to: 'lead', text: 'x' })).toEqual(none)
    expect(await alone.ask({ action: 'send', pane: '%1' })).toEqual({ roster: 'No teammates in this tab yet.', recent: [] })
    expect(await alone.ask({ action: 'send', pane: '%3' })).toEqual({ roster: 'No teammates in this tab yet.', recent: [] })
    expect(alone.delivered).toEqual([])
  })

  /** A send that asks another machine for names, with [meanwhile] done while that machine is asked: the directory is
   *  read and every name learned first, then the names grow old, so only the send asks again. */
  const whileAsking = async (meanwhile: (t: ReturnType<typeof setup>) => Promise<void> | void) => {
    let t: ReturnType<typeof setup>
    let armed = false
    t = setup({ rpc: async (_target, payload) => {
      if (payload.action === 'who') {
        if (armed) await meanwhile(t)
        return { agents: [{ agentId: 'phone', name: 'phone', engine: 'claude' }] }
      }
      return { statuses: [] }
    } })
    expect(String((await t.ask({ action: 'send', pane: '%1' })).roster)).toContain('phone')
    t.tick(WHO_MS)
    armed = true
    return t
  }

  it('sends nothing when Agent Messages are turned off while it asks another machine for names', async () => {
    const t = await whileAsking((t) => t.setting(false))
    expect(await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })).toEqual({ error: 'MESSAGES_OFF', detail: `${MESSAGES_OFF_TEXT} Nothing was sent.` })
    expect(t.delivered).toEqual([])
    expect((await t.ask({ action: 'history' })).messages).toEqual([])
  })

  it('sends nothing when the teammate leaves the tab while it asks another machine for names', async () => {
    const t = await whileAsking(async (t) => {
      t.tabs[0].panes = t.tabs[0].panes.filter((p) => p.agentId !== 'api')
      t.notice({ type: 'desk_changed', revision: 5 })
      await new Promise((settle) => setTimeout(settle, 0))
    })
    expect(await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })).toEqual({ error: 'NOT_IN_TAB', detail: 'api is no longer in a tab with you. Nothing was sent.' })
    expect(t.delivered).toEqual([])
    expect((await t.ask({ action: 'history' })).messages).toEqual([])
  })

  it('limits how often one harness sends, and tells the windows', async () => {
    const t = setup()
    for (let i = 0; i < LIMITS.perSender; i++) await t.ask({ action: 'send', pane: '%1', to: 'api', text: `n${i}` })
    expect(await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'one more' })).toMatchObject({ error: 'RATE_LIMITED' })
    expect(t.windows.some((w) => (w.payload as Record<string, unknown>).limited)).toBe(true)
    t.tick(LIMITS.window)
    expect((await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'later' })).recipients).toBeDefined()
  })

  it('keeps a message for a machine that is away, and hands it over once it is back', async () => {
    vi.useFakeTimers()
    let away = true
    const calls: string[] = []
    const t = setup({ rpc: async (target, payload) => {
      calls.push(String(payload.action))
      if (payload.action === 'who') return { agents: [{ agentId: 'phone', name: 'phone', engine: 'claude' }] }
      if (away) throw new MessageError(payload.action === 'deliver' && calls.length > 4 ? 'NO_PEER_LINK' : 'DISCONNECTED', 'away')
      if (payload.action === 'deliver') return { statuses: [{ messageId: (payload.message as { id: string }).id, agentId: 'phone', state: 'delivered', via: 'hook' }] }
      return { statuses: [] }
    } })
    t.service.start()
    const reply = await t.ask({ action: 'send', pane: '%1', to: 'phone', text: 'when you are back' })
    expect(reply.recipients).toEqual([{ name: 'phone', state: 'queued', reason: 'that machine is away: it is handed over once it is back' }])
    away = false
    t.tick(60_000)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    const history = await t.ask({ action: 'history' })
    expect((history.messages as Array<{ statuses: unknown[] }>)[0].statuses).toEqual([expect.objectContaining({ machineId: 'm2', agentId: 'phone', state: 'delivered', via: 'hook' })])
    t.service.stop()
  })

  it('keeps how another machine\'s agent got a message, read with `harness send` too, and nothing else', async () => {
    vi.useFakeTimers()
    let via: unknown = 'read'
    const t = setup({ rpc: async (target, payload) => {
      if (payload.action === 'who') return { agents: [{ agentId: 'phone', name: 'phone', engine: 'claude' }] }
      if (payload.action === 'deliver') return { statuses: [{ messageId: (payload.message as { id: string }).id, agentId: 'phone', state: 'queued' }] }
      return { statuses: (payload.ids as string[]).map((messageId) => ({ messageId, agentId: 'phone', state: 'delivered', via })) }
    } })
    t.service.start()
    await t.ask({ action: 'send', pane: '%1', to: 'phone', text: 'when you have a minute' })
    t.tick(60_000)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    const statuses = async () => ((await t.ask({ action: 'history' })).messages as Array<{ statuses: unknown[] }>).at(-1)!.statuses
    expect(await statuses()).toEqual([expect.objectContaining({ machineId: 'm2', agentId: 'phone', state: 'delivered', via: 'read' })])
    via = 'typed'
    await t.ask({ action: 'send', pane: '%1', to: 'phone', text: 'and another' })
    t.tick(60_000)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    expect(await statuses()).toEqual([expect.not.objectContaining({ via: expect.anything() })])
    t.service.stop()
  })
})

describe('a harness and the harnesses it started', () => {
  // Agent Messages off means off (owner, 2026-10-11): being started by a harness is no way to message it. Since #1180
  // the two messaged each other with no tab at all, and the owner found agents talking before turning any tab on.
  const start = (by: string, child: string, childMachine = 'm1') => new Ledger(ledgerPath(root)).append({
    at: 1, depth: 1, by: { machineId: 'm1', agentId: by, name: by, engine: 'codex' }, child: { machineId: childMachine, agentId: child, name: child },
  })

  it('may not message each other while Agent Messages are off, nor without a tab they share, either way', async () => {
    const t = setup({ tabs: [{ id: 'app', name: 'app', panes: [{ machineId: 'm1', agentId: 'lead' }, { machineId: 'm1', agentId: 'web' }] }] })
    start('lead', 'web')
    t.setting(false)
    expect(await t.ask({ action: 'send', pane: '%1', to: 'web', text: 'Also check the footer.' })).toMatchObject({ error: 'MESSAGES_OFF' })
    expect(await t.ask({ action: 'send', pane: '%3', to: 'lead', text: 'Done: 3 fixes.' })).toMatchObject({ error: 'MESSAGES_OFF' })
    // Nor does `harness send` alone list them.
    expect(await t.ask({ action: 'send', pane: '%1' })).toMatchObject({ error: 'MESSAGES_OFF' })
    t.setting(true)
    const none = setup({ tabs: [] })
    expect(await none.ask({ action: 'send', pane: '%1', to: 'web', text: 'x' })).toMatchObject({ error: 'NO_TEAMMATES' })
    expect(await none.ask({ action: 'send', pane: '%3', to: 'lead', text: 'x' })).toMatchObject({ error: 'NO_TEAMMATES' })
    expect(String((await none.ask({ action: 'send', pane: '%1' })).roster)).not.toMatch(/\bweb\b/)
    expect(t.delivered).toEqual([])
    expect(none.delivered).toEqual([])
  })

  it('are refused as any other recipient outside the sender\'s tabs, and listed only as tab teammates', async () => {
    // lead and api share a tab; web, which lead started, is in none.
    const t = setup()
    start('lead', 'web')
    start('lead', 'api')
    const refused = await t.ask({ action: 'send', pane: '%1', to: 'web', text: 'x' })
    expect(refused).toEqual({ error: 'UNKNOWN_RECIPIENT', detail: 'No teammate named "web" in this tab. Teammates: api, phone.' })
    expect(await t.ask({ action: 'send', pane: '%3', to: 'lead', text: 'x' })).toMatchObject({ error: 'NO_TEAMMATES' })
    const roster = await t.ask({ action: 'send', pane: '%1' })
    expect(roster.roster).toContain('Teammates:')
    expect(roster.roster).not.toMatch(/\bweb\b/)
    expect(roster.roster).not.toContain('started you')
    // A child in the tab is a teammate like any other: reached through the tab, and logged there.
    const both = await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'sync' })
    expect(both).toMatchObject({ tab: 'app', recipients: [{ name: 'api', state: 'queued' }] })
    expect(t.delivered.map(([agentId]) => agentId)).toEqual(['api'])
  })

  it('a message an older version queued between them under no tab is never delivered, read directory or not', async () => {
    vi.useFakeTimers()
    // Queued by 0.3.75 under its `started` log: one waiting in web's inbox for its hook, and one to api, which shares
    // a tab with lead now.
    const store = new MessageStore(join(root, 'state'))
    const old = (id: string, to: string) => ({ id, tabId: 'started', at: 1, text: 'Also check the footer.',
      from: { machineId: 'm1', agentId: 'lead', name: 'lead', engine: 'codex', machine: 'studio' }, to: [{ machineId: 'm1', agentId: to, name: to }] })
    const queue = (id: string, to: string, pane: string) => {
      store.record(old(id, to))
      store.status({ messageId: id, machineId: 'm1', agentId: to, state: 'queued', at: 1 })
      store.state.local.push({ key: deliveryKey(id, to), messageId: id, agentId: to, pane, session: `s-${to}`, state: 'queued', tries: 0, nextTryAt: 0, at: 1 })
      new PaneInbox(join(root, 'inbox-root')).put(pane, deliveryKey(id, to), { session: `s-${to}`, text: 'Also check the footer.' })
    }
    queue('m0000old', 'web', '%3')
    queue('m0000ol2', 'api', '%2')
    store.save()
    start('lead', 'web')
    // The directory cannot be read: they are failed all the same, before a hook can take them.
    const t = setup({ backendStatus: 500 })
    expect(t.inbox.waiting('%3', deliveryKey('m0000old', 'web'))).toBe(true)
    t.service.start()
    expect(t.inbox.waiting('%3', deliveryKey('m0000old', 'web'))).toBe(false)
    expect(t.inbox.waiting('%2', deliveryKey('m0000ol2', 'api'))).toBe(false)
    await vi.advanceTimersByTimeAsync(TICK_MS * 2)
    expect(t.delivered).toEqual([])
    const history = await t.ask({ action: 'history', tabId: 'started' })
    expect((history.messages as Array<{ statuses: unknown[] }>).map((m) => m.statuses)).toEqual([
      [expect.objectContaining({ machineId: 'm1', agentId: 'web', state: 'failed', reason: 'it was sent outside any tab' })],
      [expect.objectContaining({ machineId: 'm1', agentId: 'api', state: 'failed', reason: 'it was sent outside any tab' })],
    ])
    t.service.stop()
  })

  it('a hand-over an older machine logged under `started` is failed even between two in one tab', async () => {
    const t = setup()
    const answer = await t.ask({ action: 'deliver', message: { id: 'm00000cc', tabId: 'started', text: 'hi', at: 5,
      from: { machineId: 'm2', agentId: 'phone', name: 'phone', engine: 'claude', machine: 'laptop' }, to: [{ machineId: 'm1', agentId: 'api', name: 'api' }] } }, OWNER_REMOTE)
    expect(answer.statuses).toEqual([expect.objectContaining({ agentId: 'api', state: 'failed', reason: 'it was sent outside any tab' })])
    expect(t.delivered).toEqual([])
  })

  it('reach a tab teammate by the start of its id, for a harness whose name is a sentence', async () => {
    const titled = { ...session('abcdef99-1', '%3'), title: 'so we have built it, then' } as unknown as RegisteredSession
    const t = setup({ agents: [session('lead', '%1', 'codex'), titled],
      tabs: [{ id: 'app', name: 'app', panes: [{ machineId: 'm1', agentId: 'lead' }, { machineId: 'm1', agentId: 'abcdef99-1' }] }] })
    expect((await t.ask({ action: 'send', pane: '%1', to: 'abcdef', text: 'x' })).recipients).toEqual([{ name: 'so we have built it, then', state: 'queued' }])
    // Too short to be an id's start.
    expect((await t.ask({ action: 'send', pane: '%1', to: 'abcde', text: 'x' })).error).toBe('UNKNOWN_RECIPIENT')
  })

  it('keep the record of a harness another machine started here, from that machine only', async () => {
    const t = setup()
    const row = { at: 5, depth: 2, by: { machineId: 'm2', agentId: 'phone', name: 'phone', engine: 'claude' }, child: { machineId: 'm1', agentId: 'web', name: 'web' } }
    expect(await t.ask({ action: 'started', row }, OWNER_REMOTE)).toEqual({ recorded: true })
    expect(new Ledger(ledgerPath(root)).parentOf({ machineId: 'm1', agentId: 'web' })).toMatchObject({ depth: 2, by: { machineId: 'm2' } })
    expect((await t.ask({ action: 'started', row }, OWNER_LOCAL)).error).toBe('REMOTE_ONLY')
    expect((await t.ask({ action: 'started', row: { ...row, child: { ...row.child, machineId: 'm3' } } }, OWNER_REMOTE)).error).toBe('INVALID_RECORD')
    expect((await t.ask({ action: 'started', row: { ...row, by: { ...row.by, machineId: 'm1' } } }, OWNER_REMOTE)).error).toBe('INVALID_RECORD')
    expect((await t.ask({ action: 'started' }, OWNER_REMOTE)).error).toBe('INVALID_RECORD')
    expect((await t.ask({ action: 'started', row: { ...row, child: { ...row.child, agentId: 'nobody' } } }, OWNER_REMOTE)).error).toBe('UNKNOWN_HARNESS')
    // The record lets neither message the other: phone is no teammate of web's.
    const delivered = await t.ask({ action: 'deliver', message: { id: 'm00000bb', tabId: 'started', text: 'hi', at: 5,
      from: { machineId: 'm2', agentId: 'phone', name: 'phone', engine: 'claude', machine: 'laptop' }, to: [{ machineId: 'm1', agentId: 'web', name: 'web' }] } }, OWNER_REMOTE)
    expect(delivered.statuses).toEqual([expect.objectContaining({ agentId: 'web', state: 'failed' })])
    expect(t.delivered).toEqual([])
  })

  it('stay apart across machines: another machine checks against its own tabs', async () => {
    const t = setup({ tabs: [] })
    start('lead', 'phone', 'm2')
    expect((await t.ask({ action: 'send', pane: '%1', to: 'phone', text: 'x' })).error).toBe('NO_TEAMMATES')
    // And while Agent Messages are off here, whatever the tabs say.
    t.tabs.push({ id: 'app', name: 'app', panes: [{ machineId: 'm1', agentId: 'lead' }, { machineId: 'm2', agentId: 'phone' }] })
    t.notice({ type: 'desk_changed', revision: 5 })
    t.setting(false)
    expect((await t.ask({ action: 'send', pane: '%1', to: 'phone', text: 'x' })).error).toBe('MESSAGES_OFF')
    expect(t.rpcCalls.filter(([, p]) => p.action === 'deliver')).toEqual([])
  })
})

describe('harness tell: more work from the harness that started it', () => {
  // One way, from the starter, behind `agents-tell-agents` (tell.ts): not Agent Messages, which stay off means off.
  const start = (by: string, child: string, byMachine = 'm1', engine = 'codex') => new Ledger(ledgerPath(root)).append({
    at: 1, depth: 1, by: { machineId: byMachine, agentId: by, name: by, engine }, child: { machineId: 'm1', agentId: child, name: child },
  })
  /** Agent Messages off, as by default, and the person's say on telling. */
  const allow = (t: ReturnType<typeof setup>, on = true) => { t.setting(false); setAgentSettingsForTest(root, { agentsTellAgents: on }) }

  it('types more work into a harness it started, with Agent Messages off and no tab, saying who it is from', async () => {
    const t = setup({ tabs: [] })
    start('lead', 'web')
    allow(t)
    const reply = await t.ask({ action: 'tell', pane: '%1', machine: 'Mac Auto', agentId: 'web', text: 'Now add tests for the footer.' })
    expect(reply).toMatchObject({ state: 'queued' })
    const id = reply.id as string
    expect(t.delivered).toHaveLength(1)
    const [agentId, text, deliveryId] = t.delivered[0]
    expect(agentId).toBe('web')
    expect(deliveryId).toBe(`team:msg:${deliveryKey(id, 'web')}:1`)
    // Named as the starter's CLI names its machine, not by the host: Agent Messages' directory is not read while off.
    expect(text).toBe('[from lead · Codex · Mac Auto, the harness that started you: more work. It reads your answer itself.]\n\nNow add tests for the footer.')
    // No roster note: it has no teammates to message.
    expect(text).not.toContain('Agent Messages are on')
    t.deliveryEvent({ deliveryId, sessionId: 'web', state: 'started' })
    const history = await t.ask({ action: 'history', tabId: 'told' })
    expect(history.messages).toEqual([expect.objectContaining({ id, statuses: [expect.objectContaining({ agentId: 'web', state: 'delivered', via: 'prompt' })] })])
  })

  it('is refused until the person turns it on, and for any harness its caller did not start, either way', async () => {
    const t = setup({ tabs: [] })
    start('lead', 'web')
    start('lead', 'gone')
    t.setting(false)
    expect(await t.ask({ action: 'tell', pane: '%1', agentId: 'web', text: 'x' })).toMatchObject({ error: 'TELL_OFF', detail: expect.stringContaining('agents-tell-agents') })
    allow(t)
    // api was the person's; the started one may not tell its starter; a harness no longer running is said so.
    expect(await t.ask({ action: 'tell', pane: '%1', agentId: 'api', text: 'x' })).toMatchObject({ error: 'NOT_YOURS' })
    expect(await t.ask({ action: 'tell', pane: '%3', agentId: 'lead', text: 'x' })).toMatchObject({ error: 'NOT_YOURS' })
    expect(await t.ask({ action: 'tell', pane: '%1', agentId: 'gone', text: 'x' })).toMatchObject({ error: 'NOT_RUNNING' })
    expect(await t.ask({ action: 'tell', pane: '%9', agentId: 'web', text: 'x' })).toMatchObject({ error: 'NOT_A_HARNESS' })
    expect(await t.ask({ action: 'tell', agentId: 'web', text: 'x' })).toMatchObject({ error: 'NOT_A_HARNESS' })
    expect(await t.ask({ action: 'tell', pane: '%1', agentId: 'web', text: '  ' })).toMatchObject({ error: 'USAGE' })
    expect(await t.ask({ action: 'tell', pane: '%1', text: 'x' })).toMatchObject({ error: 'USAGE' })
    expect(await t.ask({ action: 'tell', pane: '%1', agentId: 'web', text: 'x'.repeat(LIMITS.text + 1) })).toMatchObject({ error: 'TOO_LONG' })
    // What a pane's request names as its sender is never read: it is the pane's harness.
    expect(await t.ask({ action: 'tell', pane: '%2', from: { machineId: 'm1', agentId: 'lead' }, agentId: 'web', text: 'x' })).toMatchObject({ error: 'NOT_YOURS' })
    expect(t.delivered).toEqual([])
  })

  it('from another of the owner\'s machines, is checked against this machine\'s own record of who started it', async () => {
    const t = setup({ tabs: [] })
    start('phone', 'web', 'm2', 'claude')
    allow(t)
    const from = { machineId: 'm2', agentId: 'phone' }
    expect(await t.ask({ action: 'tell', from, machine: 'laptop', agentId: 'web', text: 'Ship the fix.' }, OWNER_REMOTE)).toMatchObject({ state: 'queued' })
    expect(t.delivered[0][1]).toBe('[from phone · Claude Code · laptop, the harness that started you: more work. It reads your answer itself.]\n\nShip the fix.')
    // Another harness on that machine, or one claiming to be this machine's over the relay.
    expect(await t.ask({ action: 'tell', from: { machineId: 'm2', agentId: 'other' }, agentId: 'web', text: 'x' }, OWNER_REMOTE)).toMatchObject({ error: 'NOT_YOURS' })
    expect(await t.ask({ action: 'tell', from: { machineId: 'm1', agentId: 'lead' }, agentId: 'web', text: 'x' }, OWNER_REMOTE)).toMatchObject({ error: 'NOT_FROM_THERE' })
    expect(await t.ask({ action: 'tell', agentId: 'web', text: 'x' }, OWNER_REMOTE)).toMatchObject({ error: 'INVALID_REQUEST' })
    expect(t.delivered).toHaveLength(1)
  })

  it('waits while the harness is busy, and is refused at the next look once the person turns it off', async () => {
    vi.useFakeTimers()
    const t = setup({ tabs: [] })
    start('lead', 'web')
    allow(t)
    t.service.start()
    const reply = await t.ask({ action: 'tell', pane: '%1', agentId: 'web', text: 'More.' })
    t.deliveryEvent({ deliveryId: t.delivered.at(-1)![2], sessionId: 'web', state: 'rejected', reason: 'team_waiting_draft' })
    // Off sleeps Agent Messages; the mailbox still looks while this waits, and tries again once its wait is over.
    t.tick(MAX_BACKOFF_MS)
    await vi.advanceTimersByTimeAsync(PUMP_MS * 2)
    expect(t.delivered.length).toBeGreaterThan(1)
    setAgentSettingsForTest(root, { agentsTellAgents: false })
    t.deliveryEvent({ deliveryId: t.delivered.at(-1)![2], sessionId: 'web', state: 'rejected', reason: 'team_waiting_draft' })
    const tries = t.delivered.length
    t.tick(MAX_BACKOFF_MS)
    await vi.advanceTimersByTimeAsync(PUMP_MS * 2)
    expect(t.delivered).toHaveLength(tries)
    const history = await t.ask({ action: 'history', tabId: 'told' })
    expect(history.messages).toEqual([expect.objectContaining({ id: reply.id, statuses: [expect.objectContaining({ state: 'failed', reason: expect.stringContaining('agents-tell-agents') })] })])
    t.service.stop()
  })

  it('a hand-over under `told` from another machine is no way around the tabs', async () => {
    const t = setup({ tabs: [] })
    start('phone', 'web', 'm2', 'claude')
    allow(t)
    const answer = await t.ask({ action: 'deliver', message: { id: 'm00000dd', tabId: 'told', text: 'hi', at: 5,
      from: { machineId: 'm2', agentId: 'phone', name: 'phone', engine: 'claude', machine: 'laptop' }, to: [{ machineId: 'm1', agentId: 'web', name: 'web' }] } }, OWNER_REMOTE)
    expect(answer.statuses).toEqual([expect.objectContaining({ agentId: 'web', state: 'failed' })])
    expect(t.delivered).toEqual([])
  })
})

describe('a Buddy passes its owner\'s words to their own harnesses here (#2626)', () => {
  // The owner's Buddy (a Swarm session of role buddy, started by the Swarm), proven present by its grant, on this Mac only,
  // to a harness the person started here: never a guest's, a Swarm agent, one an agent started, or itself.
  const buddy = { ...session('buddy', '%1'), swarmSkill: { role: 'buddy', key: 'k1' }, startedBy: 'agent' } as unknown as RegisteredSession
  const dev = { ...session('dev', '%4'), swarmSkill: { role: 'agent', key: 'k2' }, startedBy: 'agent' } as unknown as RegisteredSession
  const kid = { ...session('kid', '%5'), startedBy: 'agent', parentAgentId: 'web' } as unknown as RegisteredSession
  const guest = { ...session('guest', '%6'), guest: '[email protected]' } as unknown as RegisteredSession
  const term = session('term', '%7', 'terminal')
  const agents = [buddy, session('web', '%2'), session('api', '%3'), dev, kid, guest, term]
  let granted = true
  const scene = (activity: Record<string, 'working' | 'idle' | 'unknown'> = {}) => {
    granted = true
    const t = setup({ tabs: [], agents, activity, buddyGranted: (s) => s.agentId === 'buddy' && granted })
    t.setting(false)
    setAgentSettingsForTest(root, { agentsTellAgents: true })
    return t
  }

  it('tells, and replies to an idle one, headed as their Buddy, with Agent Messages off and no tab', async () => {
    const t = scene()
    const told = await t.ask({ action: 'tell', pane: '%1', machine: 'Mac Studio', agentId: 'web', text: 'Builders are done: run the verifier.' })
    expect(told).toMatchObject({ state: 'queued' })
    const replied = await t.ask({ action: 'tell', pane: '%1', machine: 'Mac Studio', agentId: 'api', text: 'Yes, go ahead.', reply: true })
    expect(replied).toMatchObject({ state: 'queued' })
    expect(t.delivered.map(([agentId, text]) => [agentId, text])).toEqual([
      ['web', '[from buddy · Mac Studio: passed on by your person\'s Buddy in Harness. It does not read your answer; your person does.]\n\nBuilders are done: run the verifier.'],
      ['api', '[from buddy · Mac Studio: passed on by your person\'s Buddy in Harness. It does not read your answer; your person does.]\n\nYes, go ahead.'],
    ])
    const history = await t.ask({ action: 'history', tabId: 'relayed' })
    expect((history.messages as unknown[]).length).toBe(2)
  })

  it('is refused for another person\'s harness, a Swarm agent, one an agent started, a terminal, itself and one not running, all alike', async () => {
    const t = scene()
    // One refusal for all of them: which kind a harness is, or that it exists, is no read a Buddy is given (security review 2).
    const answers = []
    for (const agentId of ['guest', 'dev', 'kid', 'term', 'buddy', 'gone']) {
      answers.push(await t.ask({ action: 'tell', pane: '%1', agentId, text: 'x' }), await t.ask({ action: 'tell', pane: '%1', agentId, text: 'x', reply: true }))
    }
    expect(new Set(answers.map((a) => JSON.stringify(a)))).toEqual(new Set([JSON.stringify({ error: 'NOT_YOURS',
      detail: 'That is not one of your owner\'s harnesses on this computer, or it no longer runs. Nothing was sent.' })]))
    expect(t.delivered).toEqual([])
  })

  it('is refused with the setting off, while its owner is not proven here, and over the relay', async () => {
    const t = scene()
    setAgentSettingsForTest(root, { agentsTellAgents: false })
    expect(await t.ask({ action: 'tell', pane: '%1', agentId: 'web', text: 'x' })).toMatchObject({ error: 'TELL_OFF', detail: expect.stringContaining('agents-tell-agents') })
    expect(await t.ask({ action: 'tell', pane: '%1', agentId: 'web', text: 'x', reply: true })).toMatchObject({ error: 'TELL_OFF' })
    setAgentSettingsForTest(root, { agentsTellAgents: true })
    granted = false
    expect(await t.ask({ action: 'tell', pane: '%1', agentId: 'web', text: 'x' })).toMatchObject({ error: 'OWNER_AWAY', detail: expect.stringContaining('in your chat') })
    granted = true
    // From another machine the Buddy is that machine's word: never taken (the same Mac only).
    expect(await t.ask({ action: 'tell', from: { machineId: 'm2', agentId: 'buddy' }, agentId: 'web', text: 'x' }, OWNER_REMOTE)).toMatchObject({ error: 'NOT_YOURS' })
    expect(t.delivered).toEqual([])
  })

  it('replies only to an idle harness: one at work, or that may wait for the person, is refused', async () => {
    const t = scene({ web: 'working', api: 'unknown' })
    expect(await t.ask({ action: 'tell', pane: '%1', agentId: 'web', text: 'x', reply: true })).toMatchObject({ error: 'NOT_IDLE', detail: expect.stringContaining('is working') })
    expect(await t.ask({ action: 'tell', pane: '%1', agentId: 'api', text: 'x', reply: true })).toMatchObject({ error: 'NOT_IDLE' })
    expect(t.delivered).toEqual([])
  })

  it('gives a harness that is not a Buddy nothing new: it tells only what it started, and replies to none', async () => {
    const t = scene()
    expect(await t.ask({ action: 'tell', pane: '%2', agentId: 'api', text: 'x' })).toMatchObject({ error: 'NOT_YOURS' })
    new Ledger(ledgerPath(root)).append({ at: 1, depth: 1, by: { machineId: 'm1', agentId: 'web', name: 'web', engine: 'claude' }, child: { machineId: 'm1', agentId: 'kid', name: 'kid' } })
    // Its starter may tell it, but `reply` is the person's: an agent's reply is refused.
    expect(await t.ask({ action: 'tell', pane: '%2', agentId: 'kid', text: 'x', reply: true })).toMatchObject({ error: 'NOT_YOURS' })
    expect(t.delivered).toEqual([])
  })

  it('refuses words still waiting once the setting is off or the owner\'s grant has lapsed', async () => {
    vi.useFakeTimers()
    const t = scene()
    t.service.start()
    const first = await t.ask({ action: 'tell', pane: '%1', agentId: 'web', text: 'One.' })
    const second = await t.ask({ action: 'tell', pane: '%1', agentId: 'api', text: 'Two.' })
    for (const [, , deliveryId] of t.delivered) t.deliveryEvent({ deliveryId, sessionId: deliveryId.includes('web') ? 'web' : 'api', state: 'rejected', reason: 'team_waiting_draft' })
    granted = false
    const tries = t.delivered.length
    t.tick(MAX_BACKOFF_MS)
    await vi.advanceTimersByTimeAsync(PUMP_MS * 2)
    expect(t.delivered).toHaveLength(tries)
    const history = await t.ask({ action: 'history', tabId: 'relayed' })
    const states = (history.messages as Array<{ id: string; statuses: Array<{ state: string; reason?: string }> }>).map((m) => [m.id, m.statuses[0]!.state])
    expect(states).toEqual(expect.arrayContaining([[first.id, 'failed'], [second.id, 'failed']]))
    t.service.stop()
  })
})

describe('harness reply to a harness here: a program acting for the person', () => {
  // The person's words, behind `programs-reply` (replyLocal.ts), for an idle harness only: not agents' `tell`.
  const allow = (t: ReturnType<typeof setup>, on = true) => { t.setting(false); setAgentSettingsForTest(root, { programsReply: on }) }

  it('types the person\'s words into an idle harness, with no header, from here or another of the owner\'s machines', async () => {
    const t = setup({ tabs: [], activity: {} })
    allow(t)
    const reply = await t.ask({ action: 'reply_local', machine: 'lamp-75c9', agentId: 'web', text: 'The lamp\'s check refused skill.toml: name is missing.' })
    expect(reply).toMatchObject({ state: 'queued' })
    expect(t.delivered).toHaveLength(1)
    const [agentId, text, deliveryId] = t.delivered[0]
    expect(agentId).toBe('web')
    expect(text).toBe('The lamp\'s check refused skill.toml: name is missing.')
    t.deliveryEvent({ deliveryId, sessionId: 'web', state: 'started' })
    const history = await t.ask({ action: 'history', tabId: 'replied' })
    expect(history.messages).toEqual([expect.objectContaining({ id: reply.id, from: expect.objectContaining({ agentId: 'person', machine: 'lamp-75c9' }),
      statuses: [expect.objectContaining({ agentId: 'web', state: 'delivered' })] })])
    expect(await t.ask({ action: 'reply_local', machine: 'lamp-75c9', agentId: 'api', text: 'Fix it.' }, OWNER_REMOTE)).toMatchObject({ state: 'queued' })
    expect(t.delivered).toHaveLength(2)
  })

  it('is refused until the person turns it on, and for a harness that works, may wait for the person, or is gone', async () => {
    const t = setup({ tabs: [], activity: { api: 'working', lead: 'unknown' } })
    t.setting(false)
    expect(await t.ask({ action: 'reply_local', agentId: 'web', text: 'x' })).toMatchObject({ error: 'REPLY_OFF', detail: expect.stringContaining('programs-reply') })
    allow(t)
    expect(await t.ask({ action: 'reply_local', agentId: 'api', text: 'x' })).toMatchObject({ error: 'NOT_IDLE', detail: expect.stringContaining('is working') })
    expect(await t.ask({ action: 'reply_local', agentId: 'lead', text: 'x' })).toMatchObject({ error: 'NOT_IDLE', detail: expect.stringContaining('Only they answer that') })
    expect(await t.ask({ action: 'reply_local', agentId: 'gone', text: 'x' })).toMatchObject({ error: 'NOT_RUNNING' })
    expect(await t.ask({ action: 'reply_local', agentId: 'web', text: '  ' })).toMatchObject({ error: 'USAGE' })
    expect(await t.ask({ action: 'reply_local', text: 'x' })).toMatchObject({ error: 'USAGE' })
    expect(await t.ask({ action: 'reply_local', agentId: 'web', text: 'x'.repeat(LIMITS.text + 1) })).toMatchObject({ error: 'TOO_LONG' })
    // Not the owner: nothing at all.
    expect(await t.ask({ action: 'reply_local', agentId: 'web', text: 'x' }, { local: true, owner: false })).toMatchObject({ error: 'OWNER_REQUIRED' })
    expect(t.delivered).toEqual([])
  })

  it('keeps tell\'s rate: 30 in 10 minutes', async () => {
    const t = setup({ tabs: [], activity: {} })
    allow(t)
    for (let i = 0; i < LIMITS.perSender; i++) {
      const r = await t.ask({ action: 'reply_local', agentId: 'web', text: `x${i}` })
      t.deliveryEvent({ deliveryId: t.delivered.at(-1)![2], sessionId: 'web', state: 'started' })
      expect(r).toMatchObject({ state: expect.any(String) })
    }
    expect(await t.ask({ action: 'reply_local', agentId: 'web', text: 'one more' })).toMatchObject({ error: 'RATE_LIMITED' })
    t.tick(LIMITS.window)
    expect(await t.ask({ action: 'reply_local', agentId: 'web', text: 'later' })).not.toHaveProperty('error')
  })

  it('a hand-over under `replied` from another machine is no way around the idle check or the tabs', async () => {
    const t = setup({ tabs: [], activity: {} })
    allow(t)
    const answer = await t.ask({ action: 'deliver', message: { id: 'm00000ee', tabId: 'replied', text: 'hi', at: 5,
      from: { machineId: 'm2', agentId: 'person', name: 'the person', engine: 'claude', machine: 'laptop' }, to: [{ machineId: 'm1', agentId: 'web', name: 'web' }] } }, OWNER_REMOTE)
    expect(answer.statuses).toEqual([expect.objectContaining({ agentId: 'web', state: 'failed' })])
    expect(t.delivered).toEqual([])
  })
})

describe('from the owner\'s other machines', () => {
  const incoming =(to = 'api', from = { machineId: 'm2', agentId: 'phone' }) => ({
    id: 'm00000aa', tabId: 'app', text: 'from the phone', at: 5,
    from: { ...from, name: 'phone', engine: 'claude', machine: 'laptop' },
    to: [{ machineId: 'm1', agentId: to, name: to }],
  })

  it('delivers a message for one of this machine\'s agents that shares an on tab with the sender, once', async () => {
    const t = setup()
    const answer = await t.ask({ action: 'deliver', message: incoming() }, OWNER_REMOTE)
    expect(answer.statuses).toEqual([expect.objectContaining({ messageId: 'm00000aa', machineId: 'm1', agentId: 'api', state: 'queued' })])
    expect(t.delivered).toHaveLength(1)
    // Handed over again after a lost reply: the same delivery, not a second.
    await t.ask({ action: 'deliver', message: incoming() }, OWNER_REMOTE)
    expect(t.delivered).toHaveLength(1)
    t.deliveryEvent({ deliveryId: t.delivered[0][2], sessionId: 'api', state: 'delivered' })
    expect(await t.ask({ action: 'status', ids: ['m00000aa', 'unknown'] }, OWNER_REMOTE)).toEqual({ statuses: [expect.objectContaining({ state: 'delivered', via: 'prompt' })] })
  })

  it('takes a hand-over only from another machine, never naming this one as the sender, and not while the directory is unknown', async () => {
    const t = setup()
    expect(await t.ask({ action: 'deliver', message: incoming() }, OWNER_LOCAL)).toMatchObject({ error: 'REMOTE_ONLY' })
    expect(await t.ask({ action: 'status', ids: [] }, OWNER_LOCAL)).toMatchObject({ error: 'REMOTE_ONLY' })
    expect(await t.ask({ action: 'who', agentIds: [] }, OWNER_LOCAL)).toMatchObject({ error: 'REMOTE_ONLY' })
    expect(await t.ask({ action: 'deliver', message: incoming('api', { machineId: 'm1', agentId: 'lead' }) }, OWNER_REMOTE)).toMatchObject({ error: 'NOT_FROM_THERE' })
    expect(t.delivered).toHaveLength(0)
    const down = setup({ backendStatus: 500 })
    expect(await down.ask({ action: 'deliver', message: incoming() }, OWNER_REMOTE)).toMatchObject({ error: 'DIRECTORY_UNAVAILABLE' })
  })

  it('refuses a hand-over once too many messages wait on this machine', async () => {
    const t = setup()
    for (let i = 0; i < LIMITS.waiting; i++) {
      const m = { ...incoming(), id: `m${String(i).padStart(7, '0')}` }
      await t.ask({ action: 'deliver', message: m }, OWNER_REMOTE)
      t.deliveryEvent({ deliveryId: t.delivered.at(-1)![2], sessionId: 'api', state: 'rejected', reason: 'team_waiting_idle' })
    }
    expect(await t.ask({ action: 'deliver', message: { ...incoming(), id: 'mzzzzzzz' } }, OWNER_REMOTE)).toMatchObject({ error: 'MAILBOX_FULL' })
    // Five hundred deliveries, each saved to disk: about five seconds on a busy machine.
  }, 30_000)

  it('refuses a message for an agent outside the sender\'s tabs, and one that is not a message', async () => {
    const t = setup()
    const answer = await t.ask({ action: 'deliver', message: incoming('web') }, OWNER_REMOTE)
    expect(answer.statuses).toEqual([expect.objectContaining({ agentId: 'web', state: 'failed', reason: 'it is not in a tab with the sender' })])
    expect(t.delivered).toHaveLength(0)
    expect(await t.ask({ action: 'deliver', message: { id: 'x' } }, OWNER_REMOTE)).toMatchObject({ error: 'INVALID_MESSAGE' })
  })

  it('refuses a hand-over while this machine has Agent Messages off, whatever the sender\'s machine says', async () => {
    // Each computer has its own switch: the sender's had it on, and this one's person turned it off.
    const t = setup()
    t.setting(false)
    const answer = await t.ask({ action: 'deliver', message: incoming() }, OWNER_REMOTE)
    expect(answer.statuses).toEqual([expect.objectContaining({ agentId: 'api', state: 'failed', reason: 'Agent Messages are off on its computer' })])
    expect(t.delivered).toEqual([])
    expect(t.inbox.waiting('%2', deliveryKey('m00000aa', 'api'))).toBe(false)
  })

  it('names its agents for another machine, and only those it has', async () => {
    const t = setup()
    expect(await t.ask({ action: 'who', agentIds: ['api', 'ghost', 3] }, OWNER_REMOTE)).toEqual({ agents: [{ agentId: 'api', name: 'api', engine: 'claude', project: 'api', state: 'unknown' }] })
    expect(await t.ask({ action: 'who' }, OWNER_REMOTE)).toEqual({ agents: [] })
    expect(await t.ask({ action: 'status' }, OWNER_REMOTE)).toEqual({ statuses: [] })
  })
})

describe('the roster note and the directory', () => {
  it('puts the note in each agent\'s inbox once the tab has a teammate, and takes it back when Agent Messages are turned off', async () => {
    vi.useFakeTimers()
    const t = setup()
    t.service.start()
    await vi.advanceTimersByTimeAsync(0)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    const waiting = (pane: string) => {
      const dir = t.inbox.paneDir(pane)!
      try { return require('node:fs').readdirSync(dir) as string[] } catch { return [] }
    }
    expect(waiting('%1').some((n) => n.startsWith('0note-'))).toBe(true)
    expect(waiting('%2').some((n) => n.startsWith('0note-'))).toBe(true)
    // Web shares no tab: nothing.
    expect(waiting('%3')).toEqual([])
    // The hook took lead's note: it is not put again.
    const note = waiting('%1').find((n) => n.startsWith('0note-'))!.replace(/\.json$/, '')
    require('node:fs').mkdirSync(join(root, 'inbox-root', 'claimed'), { recursive: true })
    require('node:fs').renameSync(join(t.inbox.paneDir('%1')!, `${note}.json`), join(root, 'inbox-root', 'claimed', `1-${note}.json`))
    await vi.advanceTimersByTimeAsync(TICK_MS)
    expect(waiting('%1')).toEqual([])
    // Turned off: the notes go at the next look, with no word from the backend.
    t.setting(false)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    expect(waiting('%2')).toEqual([])
    // On again: put back.
    t.setting(true)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    expect(waiting('%2').some((n) => n.startsWith('0note-'))).toBe(true)
    t.service.stop()
  })

  it('tells every harness of an unshared tab who leads it, as the tab setting lists it: the leader its role, the others theirs', async () => {
    vi.useFakeTimers()
    const tabs = [{ id: 'app', name: 'app', leader: { machineId: 'm1', agentId: 'lead' } as { machineId: string; agentId: string } | null,
      panes: [{ machineId: 'm1', agentId: 'lead' }, { machineId: 'm1', agentId: 'api' }, { machineId: 'm2', agentId: 'phone' }] }]
    const t = setup({ tabs })
    const roster = async (pane: string) => String((await t.ask({ action: 'send', pane })).roster)
    // The leader is told it leads; its teammates, on this machine, by the name they reach it by. No shared tab's lines.
    expect(await roster('%1')).toBe(['[Harness] Agent Messages are on in tab "app". Teammates:', '  api    Claude Code · studio · api',
      '  phone  Claude Code · laptop · app', RULES, LEADER_ROLE].join('\n'))
    expect(await roster('%2')).toBe(['[Harness] Agent Messages are on in tab "app". Teammates:', '  lead   Codex · studio · lead',
      '  phone  Claude Code · laptop · app', RULES, WORKER_ROLE('lead')].join('\n'))
    // The notes in each agent's inbox say it too.
    t.service.start()
    await vi.advanceTimersByTimeAsync(0)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    const notes = (pane: string) => {
      const dir = t.inbox.paneDir(pane)!
      return (require('node:fs').readdirSync(dir) as string[]).filter((n) => n.startsWith('0note-'))
        .map((n) => JSON.parse(require('node:fs').readFileSync(join(dir, n), 'utf8')).text as string)
    }
    expect(notes('%1')).toEqual([await roster('%1')])
    expect(notes('%2')).toEqual([await roster('%2')])
    // The leader's pane left the tab: the listing names no leader (the backend derives it), and at the next read every
    // note loses its role, given again once.
    tabs[0].leader = null
    t.notice({ type: 'desk_changed', revision: 5 })
    await vi.advanceTimersByTimeAsync(0)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    expect(notes('%1')).toEqual([expect.stringMatching(/Teammates:/)])
    expect(notes('%1')[0].endsWith(RULES)).toBe(true)
    expect(notes('%2')[0].endsWith(RULES)).toBe(true)
    t.service.stop()
  })

  it('names no leader that is no teammate of the harness, nor one a backend from before tab leaders never lists', async () => {
    const panes = [{ machineId: 'm1', agentId: 'lead' }, { machineId: 'm1', agentId: 'api' }]
    const elsewhere = setup({ tabs: [{ id: 'app', name: 'app', leader: { machineId: 'm9', agentId: 'gone' }, panes }] })
    expect(String((await elsewhere.ask({ action: 'send', pane: '%1' })).roster).endsWith(RULES)).toBe(true)
    const old = setup({ tabs: [{ id: 'app', name: 'app', panes }] })
    expect(String((await old.ask({ action: 'send', pane: '%1' })).roster).endsWith(RULES)).toBe(true)
    // A leader that is no harness at all is taken as none listed.
    const odd = setup({ tabs: [{ id: 'app', name: 'app', leader: { machineId: 7, agentId: 'lead' } as unknown as { machineId: string; agentId: string }, panes }] })
    expect(String((await odd.ask({ action: 'send', pane: '%1' })).roster).endsWith(RULES)).toBe(true)
  })

  it('reads the tabs when the desk or the machine list is pushed, and on its own only every five minutes', async () => {
    vi.useFakeTimers()
    const t = setup()
    t.service.start()
    await vi.advanceTimersByTimeAsync(0)
    const reads = () => t.backend.mock.calls.filter((c) => c[1] === '/api/agent-messages').length
    const first = reads()
    // Nothing pushed: no read for the 15 s the old poll waited, nor until just short of five minutes.
    await vi.advanceTimersByTimeAsync(15_000)
    expect(reads()).toBe(first)
    await vi.advanceTimersByTimeAsync(5 * 60_000 - 15_001)
    expect(reads()).toBe(first)
    // The safety net.
    await vi.advanceTimersByTimeAsync(1)
    expect(reads()).toBe(first + 1)
    // A machine renamed or deleted names the panes again, as a changed desk does.
    t.notice({ type: 'machines_changed', reason: 'renamed' })
    await vi.advanceTimersByTimeAsync(0)
    expect(reads()).toBe(first + 2)
    t.notice({ type: 'desk_changed', revision: 5 })
    await vi.advanceTimersByTimeAsync(0)
    expect(reads()).toBe(first + 3)
    // A read that fails is tried again 15 s later, as the old poll did, not a safety net later.
    t.backend.mockResolvedValueOnce({ status: 503, body: { success: false, data: t.directory } })
    await vi.advanceTimersByTimeAsync(5 * 60_000)
    expect(reads()).toBe(first + 4)
    await vi.advanceTimersByTimeAsync(15_000)
    expect(reads()).toBe(first + 5)
    await vi.advanceTimersByTimeAsync(15_000)
    expect(reads()).toBe(first + 5)
    t.service.stop()
  })

  it('counts Agent Messages turned on or off as a change of the directory, at its next read', async () => {
    // Deliveries and notes get another look at once, as for a tab changed (messages/directory.ts).
    vi.useFakeTimers()
    const t = setup()
    t.service.start()
    await vi.advanceTimersByTimeAsync(0)
    const reads = () => t.changed.mock.calls.length
    const first = reads()
    expect(first).toBeGreaterThan(0)
    // Read again with nothing changed: no change.
    t.notice({ type: 'desk_changed', revision: 4 })
    await vi.advanceTimersByTimeAsync(0)
    expect(reads()).toBe(first)
    t.setting(false)
    t.notice({ type: 'desk_changed', revision: 4 })
    await vi.advanceTimersByTimeAsync(0)
    expect(reads()).toBe(first + 1)
    t.notice({ type: 'desk_changed', revision: 4 })
    await vi.advanceTimersByTimeAsync(0)
    expect(reads()).toBe(first + 1)
    t.setting(true)
    t.notice({ type: 'desk_changed', revision: 4 })
    await vi.advanceTimersByTimeAsync(0)
    expect(reads()).toBe(first + 2)
    t.service.stop()
  })

  it('keys each harness\'s inbox by its backend: `%3` on tmux and `%3` on a pty host are two inboxes', async () => {
    vi.useFakeTimers()
    const tabs = [{ id: 'app', name: 'app', panes: [{ machineId: 'm1', agentId: 'lead' }, { machineId: 'm1', agentId: 'api' }, { machineId: 'm1', agentId: 'web' }] }]
    const t = setup({ tabs, agents: [session('lead', '%3', 'codex'), ptySession('api', '%3'), session('web', '%4')] })
    t.service.start()
    await vi.advanceTimersByTimeAsync(0)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    const fs = require('node:fs') as typeof import('node:fs')
    const state = JSON.parse(fs.readFileSync(join(root, 'state', 'state.json'), 'utf8'))
    expect(state.notes.lead.pane).toBe('tmux\u0000%3')
    expect(state.notes.api.pane).toBe('ptyhost\u0000p1\u0000%3')
    const notes = (pane: string) => (fs.readdirSync(t.inbox.paneDir(pane)!) as string[]).filter((n) => n.startsWith('0note-'))
    expect(notes('tmux\u0000%3')).toHaveLength(1)
    expect(notes('ptyhost\u0000p1\u0000%3')).toHaveLength(1)
    // `harness send` from tmux's `%3` is lead's, never the pty host pane's of the same id.
    const sent = await t.ask({ action: 'send', pane: '%3', to: 'api', text: 'over to you' })
    expect(sent.recipients).toEqual([{ name: 'api', state: 'queued' }])
    await vi.advanceTimersByTimeAsync(TICK_MS)
    const delivery = (JSON.parse(fs.readFileSync(join(root, 'state', 'state.json'), 'utf8')).local as Array<{ agentId: string; pane: string }>).find((d) => d.agentId === 'api')!
    expect(delivery.pane).toBe('ptyhost\u0000p1\u0000%3')
    t.service.stop()
  })

  it('a bare `%N` names a tmux pane only; a pty host pane is named by its own `<instance>:%N`', async () => {
    const tabs = [{ id: 'app', name: 'app', panes: [{ machineId: 'm1', agentId: 'a' }, { machineId: 'm1', agentId: 'b' }] }]
    const t = setup({ tabs, agents: [ptySession('a', '%5'), session('b', '%6')] })
    expect((await t.ask({ action: 'send', pane: '%5', to: 'b', text: 'hi' })).error).toBe('NOT_A_HARNESS')
    expect((await t.ask({ action: 'send', pane: 'p1:%5', to: 'b', text: 'hi' })).recipients).toEqual([{ name: 'b', state: 'queued' }])
    expect((await t.ask({ action: 'send', pane: 'p2:%5', to: 'b', text: 'hi' })).error).toBe('NOT_A_HARNESS')
  })

  it('names a versioned pty host\'s pane by its own instance: p2-0.4.21-dev.win1:%7 and p2-h0123456789ab:%7', async () => {
    const tabs = [{ id: 'app', name: 'app', panes: ['a', 'b', 'c'].map((agentId) => ({ machineId: 'm1', agentId })) }]
    const t = setup({ tabs, agents: [ptySession('a', '%7', 'claude', 'p2-0.4.21-dev.win1'), ptySession('b', '%7', 'claude', 'p2-h0123456789ab'), session('c', '%6')] })
    expect((await t.ask({ action: 'send', pane: 'p2-0.4.21-dev.win1:%7', to: 'c', text: 'hi' })).recipients).toEqual([{ name: 'c', state: 'queued' }])
    expect((await t.ask({ action: 'send', pane: 'p2-h0123456789ab:%7', to: 'c', text: 'hi' })).recipients).toEqual([{ name: 'c', state: 'queued' }])
    expect((await t.ask({ action: 'send', pane: 'p2-0.4.22:%7', to: 'c', text: 'hi' })).error).toBe('NOT_A_HARNESS')
  })

  it('keeps the notes it put in the store, withdraws a gone harness\'s, and sweeps old files nothing waits on', async () => {
    vi.useFakeTimers()
    const t = setup()
    t.service.start()
    await vi.advanceTimersByTimeAsync(0)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    const fs = require('node:fs') as typeof import('node:fs')
    const state = () => JSON.parse(fs.readFileSync(join(root, 'state', 'state.json'), 'utf8'))
    expect(Object.keys(state().notes).sort()).toEqual(['api', 'lead'])
    // api's harness is gone: its note goes with it.
    t.agents.splice(1, 1)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    expect(Object.keys(state().notes)).toEqual(['lead'])
    expect(t.inbox.paneDir('%2') && fs.existsSync(t.inbox.paneDir('%2')!)).toBe(false)
    t.service.stop()
    // A file nothing here waits on, from a service long gone: swept at the next start once it is old.
    t.inbox.put('%7', 'm0000999-aaaa', { session: 'gone', text: 'stale' })
    const old = (Date.now() - SWEEP_AFTER_MS - 1000) / 1000
    fs.utimesSync(join(t.inbox.paneDir('%7')!, 'm0000999-aaaa.json'), old, old)
    t.inbox.put('%8', 'fresh', { session: 'other daemon', text: 'fresh' })
    const again = startAgentMessages(fakeCore({ dataDir: root, daemon: { machineId: () => 'm1', port: 18473 }, agents: { live: () => t.agents, displayName: (s) => (s as unknown as { title: string }).title, terminalAvailable: () => true }, account: { backend: t.backend } }),
      { stateDir: join(root, 'state'), inboxRoot: join(root, 'inbox-root'), now: () => Date.now() })
    again.start()
    expect(t.inbox.waiting('%7', 'm0000999-aaaa')).toBe(false)
    expect(t.inbox.waiting('%8', 'fresh')).toBe(true)
    again.reconnected?.()
    again.stop()
  })

  it('holds a waiting delivery while Agent Messages are off, goes on once they are on again, and fails it later', async () => {
    // Turned off by a slip of the mouse and on again a minute later, a tab's switch failed the message waiting in it
    // (2026-10-12). The switch is the account's now (Settings ▸ Experimental), and a slip there must cost nothing either.
    vi.useFakeTimers()
    const t = setup()
    t.service.start()
    const reply = await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })
    t.deliveryEvent({ deliveryId: t.delivered[0][2], sessionId: 'api', state: 'rejected', reason: 'team_waiting_idle' })
    const key = deliveryKey(reply.id as string, 'api')
    const status = async () => ((await t.ask({ action: 'history', limit: 10 })).messages as Array<{ id: string; statuses: Array<{ state: string; reason?: string }> }>)
      .find((m) => m.id === reply.id)!.statuses[0]
    const turn = async (on: boolean) => {
      t.setting(on)
      t.notice({ type: 'desk_changed', revision: 6 })
      await vi.advanceTimersByTimeAsync(0)
    }
    await turn(false)
    expect(await status()).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })
    // Given to no one meanwhile: out of the hook's reach.
    expect(t.inbox.waiting('%2', key)).toBe(false)
    t.tick(HELD_OUTSIDE_MS - 1)
    await vi.advanceTimersByTimeAsync(PUMP_MS)
    expect(await status()).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })
    const attempts = t.delivered.length
    await turn(true)
    await vi.advanceTimersByTimeAsync(PUMP_MS)
    // Carried again: put back, and typed into the idle agent.
    expect(t.delivered.length).toBe(attempts + 1)
    expect(t.delivered.at(-1)![2]).toContain(key)
    expect((await status()).reason).not.toBe(HELD_OFF_REASON)
    t.deliveryEvent({ deliveryId: t.delivered.at(-1)![2], sessionId: 'api', state: 'rejected', reason: 'team_waiting_idle' })
    // Off for good: held a while again, then failed.
    await turn(false)
    expect(await status()).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })
    t.tick(HELD_OUTSIDE_MS)
    await vi.advanceTimersByTimeAsync(PUMP_MS)
    expect(await status()).toMatchObject({ state: 'failed', reason: 'Agent Messages were turned off on its computer' })
    expect(t.inbox.waiting('%2', key)).toBe(false)
    t.service.stop()
  })

  it('answers a failure it did not expect without saying more', async () => {
    const t = setup()
    const broken = startAgentMessages(fakeCore({ dataDir: root, agents: { live: () => { throw new Error('boom') } } }), { stateDir: join(root, 's2'), inboxRoot: join(root, 'i2') })
    expect(await broken.requests.agent_messages!({ action: 'send', pane: '%1', to: 'a', text: 'b' }, OWNER_LOCAL)).toEqual({ error: 'MESSAGES_UNAVAILABLE', detail: expect.any(String) })
    broken.stop()
    t.service.stop()
  })
})

describe('off costs nothing', () => {
  // It runs in the edge host on every computer (2026-10-12). Off, or signed out, a read of the account's tabs every
  // 15 s and three timers carried messages it never could.
  const waitingFromBefore = (id = 'm0000w01') => {
    const store = new MessageStore(join(root, 'state'))
    store.record({ id, tabId: 'app', at: 1, text: 'from before',
      from: { machineId: 'm2', agentId: 'phone', name: 'phone', engine: 'claude', machine: 'laptop' }, to: [{ machineId: 'm1', agentId: 'api', name: 'api' }] })
    store.status({ messageId: id, machineId: 'm1', agentId: 'api', state: 'queued', at: 1 })
    store.state.local.push({ key: deliveryKey(id, 'api'), messageId: id, agentId: 'api', pane: '%2', session: 's-api', state: 'queued', tries: 0, nextTryAt: 0, at: 1 })
    new PaneInbox(join(root, 'inbox-root')).put('%2', deliveryKey(id, 'api'), { session: 's-api', text: 'from before' })
    store.save()
    return deliveryKey(id, 'api')
  }
  const statusOf = async (t: ReturnType<typeof setup>, id: string) =>
    ((await t.ask({ action: 'history' })).messages as Array<{ id: string; statuses: Array<{ state: string; reason?: string }> }>).find((m) => m.id === id)!.statuses[0]

  it('off from the start: reads no tabs and puts no note; holds what waits, fails it later, then runs no timer; on, it wakes', async () => {
    vi.useFakeTimers()
    const key = waitingFromBefore()
    const t = setup()
    t.setting(false)
    t.service.start()
    await vi.advanceTimersByTimeAsync(0)
    // Held out of the hook's reach at once, the tabs unread: off, no tab carries a message, whatever they say.
    expect(t.inbox.waiting('%2', key)).toBe(false)
    expect(await statusOf(t, 'm0000w01')).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })
    t.notice({ type: 'desk_changed', revision: 9 })
    t.notice({ type: 'machines_changed', reason: 'renamed' })
    await vi.advanceTimersByTimeAsync(PUMP_MS)
    expect(await statusOf(t, 'm0000w01')).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })
    t.tick(HELD_OUTSIDE_MS)
    await vi.advanceTimersByTimeAsync(PUMP_MS)
    expect(await statusOf(t, 'm0000w01')).toMatchObject({ state: 'failed', reason: 'Agent Messages were turned off on its computer' })
    // Settled: nothing runs, and a minute goes by with no read and no note.
    await vi.advanceTimersByTimeAsync(PUMP_MS)
    expect(vi.getTimerCount()).toBe(0)
    await vi.advanceTimersByTimeAsync(60_000)
    expect(t.backend).not.toHaveBeenCalled()
    expect(t.inbox.waiting('%1', 'anything')).toBe(false)
    expect(t.watchers.size).toBe(1)
    // The file is heard more than once before it is read: read once.
    for (const heard of [...t.watchers]) { heard(); heard() }
    await vi.advanceTimersByTimeAsync(0)
    expect(t.backend).not.toHaveBeenCalled()
    // Turned on for the account and kept here: the watch wakes it, and the notes go out at its next look.
    t.setting(true)
    await vi.advanceTimersByTimeAsync(0)
    // Its tabs, and once the shared tabs too (service.ts `sharedUp`).
    expect(t.backend.mock.calls.map((c) => c[1]).sort()).toEqual(['/api/agent-messages', '/api/agent-messages/shares'])
    expect(t.watchers.size).toBe(0)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    const notes = (pane: string) => (require('node:fs').readdirSync(t.inbox.paneDir(pane)!) as string[]).filter((n) => n.startsWith('0note-'))
    expect(notes('%1')).toHaveLength(1)
    expect(notes('%2')).toHaveLength(1)
    // Its tabs every 15 s, its deliveries every 2 s, its notes and outbox every 5 s.
    expect(vi.getTimerCount()).toBe(3)
    t.service.stop()
    expect(vi.getTimerCount()).toBe(0)
    expect(t.watchers.size).toBe(0)
  })

  it('signed out: reads no tabs, runs no timer and watches nothing; signed in at its next core, it wakes', async () => {
    vi.useFakeTimers()
    let signedIn = false
    const t = setup({ signedIn: () => signedIn })
    t.service.start()
    await vi.advanceTimersByTimeAsync(TICK_MS * 4)
    expect(t.backend).not.toHaveBeenCalled()
    expect(t.watchers.size).toBe(0)
    expect(vi.getTimerCount()).toBe(0)
    // Its requests are answered all the same.
    expect(await t.ask({ action: 'history' })).toEqual({ messages: [] })
    signedIn = true
    t.service.reconnected!()
    await vi.advanceTimersByTimeAsync(0)
    // Its tabs, and once the shared tabs too (service.ts `sharedUp`).
    expect(t.backend.mock.calls.map((c) => c[1]).sort()).toEqual(['/api/agent-messages', '/api/agent-messages/shares'])
    expect(vi.getTimerCount()).toBe(3)
    // Turned off at its next look, then signed out: the watch goes with the rest.
    t.setting(false)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    expect(t.watchers.size).toBe(1)
    signedIn = false
    t.service.reconnected!()
    expect(t.watchers.size).toBe(0)
    expect(vi.getTimerCount()).toBe(0)
    t.service.stop()
  })

  it('hands over what it sent another machine once it is on again, not while it is off', async () => {
    vi.useFakeTimers()
    let away = true
    const handed: string[] = []
    const t = setup({ rpc: async (_target, payload) => {
      if (payload.action === 'who') return { agents: [{ agentId: 'phone', name: 'phone', engine: 'claude' }] }
      if (payload.action === 'deliver') {
        handed.push((payload.message as { id: string }).id)
        if (away) throw new MessageError('DISCONNECTED', 'away')
        return { statuses: [{ messageId: (payload.message as { id: string }).id, agentId: 'phone', state: 'queued' }] }
      }
      return { statuses: [] }
    } })
    t.service.start()
    const reply = await t.ask({ action: 'send', pane: '%1', to: 'phone', text: 'when you are back' })
    expect(handed).toEqual([reply.id])
    t.setting(false)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    away = false
    t.tick(10 * 60_000)
    await vi.advanceTimersByTimeAsync(TICK_MS * 3)
    expect(handed).toEqual([reply.id])
    t.setting(true)
    await vi.advanceTimersByTimeAsync(TICK_MS)
    expect(handed).toEqual([reply.id, reply.id])
    t.service.stop()
  })

  it('wakes when the core tells it its switch changed, with no file to hear', async () => {
    // A computer whose switches are all at their defaults has no file to watch: the daemon's write tells it.
    vi.useFakeTimers()
    const t = setup()
    t.setting(false)
    t.service.start()
    await vi.advanceTimersByTimeAsync(0)
    t.service.settingsChanged()
    await vi.advanceTimersByTimeAsync(0)
    expect(t.backend).not.toHaveBeenCalled()
    // Written on, with no watch to hear it: told, it reads its switch again and wakes.
    setAgentSettingsForTest(root, { agentMessages: true })
    t.service.settingsChanged()
    await vi.advanceTimersByTimeAsync(0)
    // Its tabs, and once the shared tabs too (service.ts `sharedUp`).
    expect(t.backend.mock.calls.map((c) => c[1]).sort()).toEqual(['/api/agent-messages', '/api/agent-messages/shares'])
    expect(vi.getTimerCount()).toBe(3)
    t.service.stop()
  })

  it('hears its setting\'s own file while off, with no watch given', async () => {
    setAgentSettingsForTest(root, { agentMessages: false })
    const backend = vi.fn(async () => ({ status: 503, body: {} }))
    const real = startAgentMessages(fakeCore({ dataDir: root, account: { backend } }), { stateDir: join(root, 's3'), inboxRoot: join(root, 'i3') })
    real.start()
    setAgentSettingsForTest(root, { agentMessages: true })
    for (let i = 0; i < 250 && !backend.mock.calls.length; i++) await new Promise((settle) => setTimeout(settle, 20))
    expect(backend).toHaveBeenCalled()
    real.stop()
  })
})