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.

120 KB
Raw Blame
/**
 * Agent Messages (docs/design/2026-10-10-agent-messages.md): harnesses in one tab message each other with `harness
 * send`, while the account has Agent Messages on (Settings ▸ Experimental, off by default). This is the whole service,
 * on the core's API, in the core's process or in its own (services/messages.ts, services/messagesProcess.ts):
 * - `send`: from `harness send` in an agent's pane, over this machine's socket. The pane names the sender.
 * - `deliver`, `status`, `who`: from the owner's other machines, over the paired relay; and from another account's
 *   machine in a tab shared with this one, through the tab's relay (sharedTabs.ts `request`, answered by `answerTab`),
 *   each checked against the tab's roster this computer holds (tabDelivery.ts).
 * - `history`: the windows' log of a tab.
 * - `started`: another machine's record of a harness it started here, for the agent client's limits and depth
 *   (agentClient/ledger.ts). It lets no one message anyone: only sharing a tab does.
 * - `shares` and `share_*`: tabs shared with other accounts (sharedTabs.ts), from the owner's windows, only while it is
 *   awake; `tab_pub`, this machine's key for a shared tab's roster, from the owner's other machines; `tab_pin`, a
 *   shared tab's owner key and roster as this machine holds them, and `tab_pin_changed`, that another machine took one,
 *   from the owner's other machines, only while it is awake; `tab_keychange`, this machine's signature over another's
 *   key for a tab it shares, which that machine is taking (`share_move`), from the owner's other machines only.
 * Deliveries to this machine's agents are the mailbox's (mailbox.ts); a message for another machine's agent is
 * handed to that machine's daemon, which owns its delivery and is asked what became of it: a machine of this account
 * over the paired relay, another account's through the shared tab they are in (`route`).
 *
 * Off costs nothing. It runs in the edge host on every computer, and only while this computer is signed in and has
 * Agent Messages on does it read the account's tabs (every 15 s), look at its deliveries (every 2 s) and at its notes,
 * its outbox and other machines' deliveries (every 5 s). Turned off, it withdraws the notes, holds what waits here out
 * of the hook's reach and fails it once it has waited HELD_OUTSIDE_MS, as while on, and then runs nothing until it is
 * turned on again: the core tells it when its copy of the account's switch changes (`settingsChanged`, from
 * core/experiments.ts `createAgentSettingsSync`), and a watch on the setting's file hears the same write
 * (settingWatch.ts); what this computer sent that waits for another machine is
 * handed over once it is on again. Signed out it runs nothing: there is no account to read tabs from, and signing in
 * starts a new core, which it reconnects to (`reconnected`). Its requests are answered either way, and read the switch
 * again as they come.
 */
import { createHash } from 'node:crypto'
import { hostname } from 'node:os'
import { basename, join } from 'node:path'
import { SHARED_ACTIVITY_WINDOW_FRAME, SHARED_TABS_WINDOW_FRAME, type CoreApi, type ServiceRequests, type TabFrame, type TurnDelivery } from '../core/api.js'
import { env } from '../config/env.js'
import { agentProject } from '../lib/agentProject.js'
import { agentSettingsPath, askThePersonFirst, readAgentSettings } from '../lib/agentSettings.js'
import type { RegisteredSession } from '../lib/registry.js'
import { primaryRuntime, sessionForPaneId, terminalRouteKey } from '../lib/terminalRuntime.js'
import { type DirectoryTab, MessageDirectory, type Member } from './directory.js'
import { PaneInbox } from './inbox.js'
import { Mailbox, type MailboxAgent } from './mailbox.js'
import { type DeliveryStatus, LIMITS, LONG_TEXT, longAdvice, type Message, MessageError, messageId, note, parseMessage, type Recipient, rendered, type TabNote, type Teammate } from './model.js'
import { RELAYED_TAB, relayedText, relayRefusal, TOLD_TAB, tellRefusal, toldText, type RelayTarget } from './tell.js'
import { buddyGrantLive, buddyReadsOf } from '../lib/buddyGuard.js'
import { isTeamAccount } from '../team/config.js'
import { PERSON_AGENT_ID, REPLIED_TAB, replyRefusal } from './replyLocal.js'
import { messagesRpc, RefusedError, type Rpc } from './rpc.js'
import { RequestStore } from './requestStore.js'
import { cleanName, type Roster } from './roster.js'
import { consentKey, ConsentStore } from './consentStore.js'
import { NoticeStore } from './noticeStore.js'
import { RosterStore } from './rosterStore.js'
import { accountsIn, markerLabel, markerName, markerNameWithId, sharedTabsFor } from './sharedDirectory.js'
import { sharedTabIdOf } from './sharedTabsRoster.js'
import { SharedTabs } from './sharedTabs.js'
import { carries, checkHandedOver, cleanText, fitsRequest, RateCounter, statusCode, wireMessage, type TabContext } from './tabDelivery.js'
import { Ledger, ledgerPath, parseStarted } from '../agentClient/ledger.js'
import { watchSettingFile } from './settingWatch.js'
import { ActivityIn, ActivityOut, type ActivityNow, type ActivityState } from './tabActivity.js'
import { cleanSummary } from '../lib/activitySummary.js'
import { VERSION } from '../version.js'
import { createTaskReader, type TaskReader, type TaskResult } from './tasks.js'
import { MessageStore, type Entry, type LocalDelivery, type Outgoing } from './store.js'
import { PTY_HOST_INSTANCE_SOURCE } from '../lib/ptyHost/instance.js'

export interface MessagesOptions {
  /** Where its history and waiting deliveries are kept; an isolated fixture's own. */
  stateDir?: string
  /** The pane inboxes the messages hook reads (env.HARNESS_AGENT_MESSAGES_DIR); an isolated fixture's own. */
  inboxRoot?: string
  rpc?: Rpc
  /** The local socket's folder (`ADAPTER_DATA_DIR`) the other machines are reached through. */
  dataDir?: string
  /** Who started which harness (agentClient/ledger.ts), where another machine's `started` is kept; an isolated
   *  fixture's own. */
  ledgerFile?: string
  /** Something that decides whether a typed delivery may be written changed: the process tells the core. */
  changed?: () => void
  /** How it hears the setting's file change while Agent Messages are off (settingWatch.ts); a test's own. */
  watchSetting?: (path: string, changed: () => void) => () => void
  /** What shared tabs' relay said (`GatewayEvents.tabFrame`), for its shared tabs to listen to while they run: the
   *  process it runs in hands each on (services/messagesProcess.ts). Returns how to stop listening. */
  onTabFrame?: (listener: (event: TabFrame) => void) => () => void
  /** Its shared tabs' file was saved (a pin, a roster, a tab forgotten): Share derives the observers each tab wants for
   *  this computer's harnesses again (core/messagesLink.ts `observers`). Told, never waited on. */
  observers?: () => void
  /** The branch a folder is on (lib/agentProject.ts, which runs Git); a test's own. */
  project?: (cwd: string) => Promise<{ branch: string | null } | null>
  /** The shared tabs' tasks (tasks.ts, which runs `gh`); a test's own, so no test starts the real one. */
  tasks?: TaskReader
  /** Whether a Buddy session here holds its person's live grant (lib/buddyGuard.ts `buddyGrantLive`); a test's own. */
  buddyGranted?: (session: RegisteredSession) => boolean
  now?: () => number
}

export interface AgentMessages {
  requests: ServiceRequests
  /** Whether the core may write a typed delivery now: the mailbox's word, in line. */
  canWrite(deliveryId: string): boolean
  /** The service reached a core again, perhaps a new one: typed attempts in flight go back to the hook, and what
   *  runs follows whether this computer is signed in now. */
  reconnected?(): void
  /** The core's copy of the account's switch changed: it is read again, and it wakes if it is on now. */
  settingsChanged(): void
  start(): void
  stop(): void
}

/** How often the service looks at its notes, its outbox and other machines' deliveries. */
export const TICK_MS = 5_000
/** How often a tab id this desk does not list may make the desk be read again (`tabActivity`). */
export const MISSED_TAB_READ_MS = 15_000
/** How often a message waiting on another machine is asked about. */
export const REMOTE_STATUS_MS = 15_000
/** How long another machine's names for its agents are kept. */
export const WHO_MS = 60_000
/** How old an inbox file nothing here waits on must be before a start sweeps it away. */
export const SWEEP_AFTER_MS = 10 * 60_000
/** How long a delivery no tab carries (Agent Messages turned off, or the tab left) is held, given to no one, before
 *  it fails. */
export const HELD_OUTSIDE_MS = 5 * 60_000
export const HELD_OFF_REASON = 'Agent Messages are off on its computer: it waits 5 minutes for them to be on again, then fails'
export const HELD_LEFT_REASON = 'it is not in a tab with the sender: it waits 5 minutes for that to change, then fails'
/** Why a message for another account's harness failed once it had waited HELD_OUTSIDE_MS outside every shared tab. */
export const LEFT_TAB_REASON = 'it is no longer in a shared tab with the sender'
/** Why a message already handed over to another account's harness failed once that harness had been outside every
 *  shared tab for HELD_OUTSIDE_MS: its computer can no longer be asked what became of it. */
export const LEFT_AFTER_HANDOVER_REASON = 'no longer in a shared tab with the sender; whether it was read is not known'
/** What `harness send` says of a message too large for a shared tab's frame (tabDelivery.ts `fitsRequest`). */
export const TOO_LARGE_TEXT = 'This message is too large to send to another account\'s harness: shorten the message or send to fewer teammates.'
/** How long the Agent Messages setting, as this computer keeps it, is taken as read: the mailbox's pump asks
 *  every 2 s (mailbox.ts PUMP_MS), and a send or a hand-over asks too. */
export const SETTING_FRESH_MS = 2_000
/** How long another machine's key, as it reported it for a shared tab's roster, is taken as read. */
export const MACHINE_KEY_MS = 10 * 60_000
/** The requests about tabs shared with other accounts: answered only while it is awake. */
const ACTIVITY_STATES = new Set<ActivityState>(['working', 'idle', 'unknown'])
const SHARE_ACTIONS = ['shares', 'share_tab', 'share_invite', 'share_revoke', 'share_accept', 'share_add', 'share_remove',
  'share_leader', 'share_remove_member', 'share_leave', 'share_stop', 'share_retrust_check', 'share_retrust', 'share_move', 'share_tasks', 'share_who', 'share_notice_dismiss']
/** How long People waits for a machine of the tab to say its harnesses' repo and branch. */
export const WHO_WAIT_MS = 4_000
/** How long `harness send` alone waits for the tasks before it gives the roster without them. */
export const TASKS_WAIT_MS = 4_000
/** What `harness send` says while this computer has Agent Messages off: where the person turns them on again. */
export const MESSAGES_OFF_TEXT = `Agent Messages are off. ${askThePersonFirst('agent-messages', 'work on without messaging your teammates.')}`

/** How long the windows' `shared_tabs_changed` waits for more of the same change. */
export const SHARES_COALESCE_MS = 250
/** `harness send`'s pane: `$TMUX_PANE` (`%N`, a tmux pane only) or a pty host pane's `<instance>:%N` (`$HARNESS_PANE`). */
const PANE = new RegExp(`^(?:${PTY_HOST_INSTANCE_SOURCE}:)?%\\d{1,9}$`)
/** The most messages `harness send` alone gives an agent at once, unread ones first. */
const UNREAD_MAX = 20
/** Whether `wanted` is the whole of a name the engine cut short: Codex titles its terminal with the folder cut to fit
 *  ("claude-code-2026-10-1..."), and an agent that wrote the folder out in full was told no teammate had that name
 *  (a fresh Mac, 2026-10-12). Both arguments in lower case. */
const cutShort = (name: string, wanted: string): boolean => {
  const stem = name.replace(/\s*(?:\.{3}|…)$/u, '')
  return stem !== name && stem.length >= 3 && wanted.startsWith(stem)
}
const key = (m: Member): string => `${m.machineId}/${m.agentId}`
/** The start of an id, as a name or a suffix shows it. A shared tab's roster is another account's word, and its ids may
 *  hold any character: `\x1b[2J\x1b[H` fits in eight and would clear the terminal it is shown in (review of B1). */
const idStart = (id: string): string => cleanName(id).slice(0, 8) || '?'

export function startAgentMessages(core: CoreApi, options: MessagesOptions = {}): AgentMessages {
  const now = options.now ?? Date.now
  const rpc = options.rpc ?? messagesRpc
  const self = (): string => core.daemon.machineId()
  const at = (machineId: string) => ({ port: core.daemon.port, machineId, dataDir: options.dataDir ?? core.dataDir })
  const stateDir = options.stateDir ?? join(core.dataDir, 'agent-messages')
  const store = new MessageStore(stateDir)
  // Who started which harness is the agent client's (limits, depth, who may close what), never a way to message: a
  // harness started by another reaches it only through a tab they share, like any teammate (owner, 2026-10-11, on
  // finding agents messaging each other with no tab turned on). The one use beyond that is `harness tell` (tell.ts):
  // one way, from the starter, behind a switch of its own the person turns on.
  const lineage = new Ledger(options.ledgerFile ?? ledgerPath(core.dataDir))
  const inbox = new PaneInbox(options.inboxRoot ?? env.HARNESS_AGENT_MESSAGES_DIR)
  /** Other machines' names for their agents, with when they were asked; a branch only for a harness in a shared tab. */
  const who = new Map<string, { name: string; engine: string; project?: string; branch?: string; at: number }>()
  /**
   * The branch each folder here is on, with when it was read, kept WHO_MS as another machine's answer is. Read only for a
   * harness in a tab shared with other accounts, the one note that shows a branch: no Git runs for any other tab.
   */
  const branches = new Map<string, { at: number; read: Promise<void>; branch?: string }>()
  const project = options.project ?? agentProject
  const tasks = options.tasks ?? createTaskReader(undefined, now)
  /** When each other machine was last asked for names, answering or not. */
  const asked = new Map<string, number>()
  /** When each sender sent, for the rate limit. */
  const sent = new Map<string, number[]>()
  /** The shared tabs' limits (the spec's "Limits"): what this computer sent into each tab, and what it took from each
   *  tab and from each sender in one, through the tabs' relay. */
  const tabSent = new RateCounter()
  const tabTaken = new RateCounter()
  /** A shared tab's working state across accounts: what was last sent each tab's machines, and what they last said (tabActivity.ts). */
  const activityOut = new ActivityOut(), activityIn = new ActivityIn()
  const senderTaken = new RateCounter()
  /** Hand-overs under way: one a tick, an opened session and a send all reach is handed over once at a time. */
  const handing = new Set<Outgoing>()
  /** When the shared tabs stopped carrying each hand-over to another account's machine (`messageId machineId`). */
  const outboxOutside = new Map<string, number>()
  let timer: ReturnType<typeof setInterval> | null = null
  let lastRemoteStatus = -Infinity
  /**
   * What runs (`wake`): everything while this computer is signed in and has Agent Messages on (`awake`); while they are
   * off, only the mailbox's look until what waited has settled, and the watch on the setting's file; signed out,
   * nothing. Null before it starts and once it stops.
   */
  let mode: 'awake' | 'off' | 'signedOut' | null = null
  const asleep = (): boolean => mode === 'off' || mode === 'signedOut'
  let running = false
  let unwatch: (() => void) | null = null
  const settingsFile = agentSettingsPath(options.dataDir ?? core.dataDir)

  // The account's experiment, kept by the core in the data folder (lib/agentSettings.ts) as it changes: a small file,
  // read again at most every SETTING_FRESH_MS, so a switch turned off takes effect at the next look; while off,
  // nothing looks, and the core's word (`settingsChanged`) or the file's watch wakes it (settingWatch.ts).
  let setting = { on: true, hide: false, at: -Infinity }
  const readSetting = (): boolean => {
    const saved = readAgentSettings(options.dataDir ?? core.dataDir)
    setting = { on: saved.agentMessages, hide: saved.agentMessagesHideSummary, at: now() }
    return setting.on
  }
  const messagingOn = (): boolean => {
    if (now() - setting.at >= SETTING_FRESH_MS) {
      const was = setting.on
      // Turned on or off since the last look: what runs follows, once whatever asked has its answer.
      if (readSetting() !== was) later()
    }
    return setting.on
  }
  /** Whether the account keeps the one-line summary from other accounts (Settings ▸ Experimental), read as `messagingOn` is. */
  const summaryHidden = (): boolean => { messagingOn(); return setting.hide }
  /** Whether a harness's starter may tell it more work (`agents-tell-agents`): read at each use, as few as they are, so
   *  a switch turned off stops what still waits at the mailbox's next look. */
  const tellOn = (): boolean => readAgentSettings(options.dataDir ?? core.dataDir).agentsTellAgents
  /** Whether a program acting for the person may reply to a harness here (`programs-reply`): read at each use, as `tellOn`. */
  const replyOn = (): boolean => readAgentSettings(options.dataDir ?? core.dataDir).programsReply
  /** A person's Buddy here, by this machine's registry: a Swarm session of role buddy (#2626). */
  const isBuddy = (session: RegisteredSession | undefined): session is RegisteredSession => session?.swarmSkill?.role === 'buddy'
  /** Whether that Buddy's person is proven with it on this machine now: never on a Team account, which no person signs in to. */
  const buddyGranted = options.buddyGranted ?? ((session: RegisteredSession) => !!session.swarmSkill && !!session.cwd && !isTeamAccount()
    && buddyGrantLive(buddyReadsOf(session.swarmSkill.key), session.cwd, now()))
  /** What a Buddy would pass words to, from this machine's registry: every live harness, terminals included, so each is named. */
  const relayTarget = (buddy: RegisteredSession, agentId: string): RelayTarget | null => {
    const target = core.agents.live().find((s) => s.agentId === agentId)
    return target ? { swarm: !!target.swarmSkill, startedByAgent: target.startedBy === 'agent' || !!target.parentAgentId, guest: !!target.guest,
      terminal: target.engine === ('terminal' as string), self: target.agentId === buddy.agentId } : null
  }
  /** Why the Buddy [from] may not pass words to [agentId] here now, or null; at the request and at each delivery look. */
  const relayCheck = (from: RegisteredSession, agentId: string) => relayRefusal({ on: tellOn(), granted: buddyGranted(from), target: relayTarget(from, agentId) })
  let waking = false
  const later = (): void => {
    if (waking) return
    waking = true
    queueMicrotask(() => { waking = false; wake() })
  }

  const directory = new MessageDirectory({
    on: messagingOn,
    read: async () => {
      const response = await core.account.backend('GET', '/api/agent-messages')
      if (response.status !== 200 || response.body.success !== true) throw new Error('directory unavailable')
      return response.body.data
    },
    changed: () => { mailbox.refuseAll(); notesPump(); followLeaders(); options.changed?.() },
    // The shared tabs this computer holds, once it knows its account: which rosters are its own depends on it, and which
    // machines are its own, this one always (as sharedTabs.ts `checkOwn` takes them). This machine's harnesses are in
    // another account's tab only as it asked (`consent`).
    extra: (desk, machines) => (rosters && account
      ? sharedTabsFor(rosters.all(), { accountId: account.accountId, machineId: self(), machineIds: new Set([self(), ...machines.keys()]), consent: consent?.keys() ?? new Set() },
        (id) => shared?.deskTab(id) ?? null, desk)
      : desk),
    now,
  })

  const live = (): RegisteredSession[] => core.agents.live().filter((s) => s.engine !== ('terminal' as string))
  /** Where a harness's inbox is: its pane by route key (inbox.ts), so equal `%N` ids on two backends never share
   *  one. None while it has no pane. */
  const inboxPane = (session: RegisteredSession): string => session.runtimes.length ? terminalRouteKey(primaryRuntime(session)) : ''
  const localAgent = (agentId: string): RegisteredSession | undefined => live().find((s) => s.agentId === agentId)
  const machineName = (machineId: string): string => directory.machineName(machineId) ?? (machineId === self() ? hostname().replace(/\.local$/, '') : idStart(machineId))

  const mailbox: Mailbox = new Mailbox({
    store, inbox, now,
    agent: (agentId): MailboxAgent | null => {
      const session = localAgent(agentId)
      if (!session) return null
      // The hook delivers only to this conversation: a Codex sub-agent runs its hooks from its parent's pane, and
      // a pane number tmux gives out again is another's. A Claude Code sub-agent says so itself (`agent_id`).
      return { pane: inboxPane(session), session: session.sessionId ?? '', available: session.active && core.agents.terminalAvailable(agentId) }
    },
    deliver: (agentId, text, deliveryId) => { core.turns.deliver(agentId, text, deliveryId); options.changed?.() },
    refused: (delivery) => { const v = verdict(delivery); return v && 'refused' in v ? v.refused : null },
    held: (delivery) => { const v = verdict(delivery); return v && 'held' in v ? v.held : null },
    forbidden: (delivery) => forbidden(delivery),
    // Off, no tab carries a message, whatever the tabs say: known without reading them.
    ready: () => directory.current() !== null || !directory.on(),
    asleep,
    text: (delivery, message) => {
      // More work from its starter: no tab, so no roster note, which would invite it to message its teammates.
      if (message.tabId === TOLD_TAB) return toldText(message)
      if (message.tabId === RELAYED_TAB) return relayedText(message)
      // The person's words, as they would type them: no header, as `harness reply` to a cloud harness sends them.
      if (message.tabId === REPLIED_TAB) return message.text
      const roster = rosterOf(delivery.agentId)
      const text = rendered(message, account?.accountId)
      return roster && store.state.noted[delivery.agentId] !== roster.signature ? `${roster.text}\n\n${text}` : text
    },
    changed: (status, delivery) => localChanged(status, delivery),
    writable: () => options.changed?.(),
  })

  /**
   * Why a local delivery may never be made, whatever the tabs say, or null. Before 2026-10-11 a harness and one it
   * started messaged each other with no tab on, logged under `started`; only a tab carries a message, so what an
   * older version left waiting there is never delivered, even to two that share a tab now. Asked before
   * the directory is read too: the hook takes what waits in a pane's inbox without asking, and a directory that
   * cannot be read (signed out, the backend down) would otherwise leave it there to be taken.
   */
  function forbidden(delivery: LocalDelivery): string | null {
    return store.entry(delivery.messageId)?.message.tabId === 'started' ? 'it was sent outside any tab' : null
  }

  /** When the tabs stopped carrying each local delivery (`messageId agentId`), while they do not. */
  const outsideSince = new Map<string, number>()

  /**
   * Whether a local delivery may be made: null; held, given to no one, while no tab carries it (Agent Messages are
   * off here, or the two no longer share a tab), for HELD_OUTSIDE_MS; refused after that, or at once when it may never
   * be made. Only what may never be made is refused before the directory is read. A tab's switch turned off by a slip
   * of the mouse and on again a minute later failed the message waiting in it (owner, 2026-10-12): held, it goes on
   * once it is carried again.
   */
  function verdict(delivery: LocalDelivery): { refused: string } | { held: string } | null {
    const entry = store.entry(delivery.messageId)
    if (!entry) return { refused: 'the message is no longer kept' }
    const never = forbidden(delivery)
    if (never) return { refused: never }
    // Told by its starter: no tab carries it, so the tabs say nothing. The switch, and who started it as this machine
    // records it, are looked at again at each look: turned off meanwhile, it is refused at once. Whether the harness
    // runs was asked as it was told; a harness away for a moment (a restart) waits as a teammate's message does.
    if (entry.message.tabId === TOLD_TAB) {
      const refusal = tellRefusal({ on: tellOn(), lineage, self: self(), live: () => true }, entry.message.from, delivery.agentId)
      return refusal ? { refused: refusal.message } : null
    }
    // A Buddy's words for its person's harness: who it is from, whose the harness is and the grant, again at each look.
    if (entry.message.tabId === RELAYED_TAB) {
      const buddy = localAgent(entry.message.from.agentId)
      if (entry.message.from.machineId !== self() || !isBuddy(buddy)) return { refused: 'its Buddy no longer runs here' }
      const refusal = relayCheck(buddy, delivery.agentId)
      return refusal ? { refused: refusal.message } : null
    }
    // A program's reply for the person: the switch is looked at again at each look, as a tell's is.
    if (entry.message.tabId === REPLIED_TAB) return replyOn() ? null : { refused: 'programs-reply was turned off' }
    if (!directory.current() && directory.on()) return null
    const key = `${delivery.messageId} ${delivery.agentId}`
    const recipient = { machineId: self(), agentId: delivery.agentId }
    // Only a tab the two share carries a message, and none while Agent Messages are off here.
    if (directory.shared(entry.message.from, recipient)) { outsideSince.delete(key); return null }
    const off = !directory.on()
    const since = outsideSince.get(key) ?? now()
    if (now() - since < HELD_OUTSIDE_MS) {
      outsideSince.set(key, since)
      return { held: off ? HELD_OFF_REASON : HELD_LEFT_REASON }
    }
    outsideSince.delete(key)
    return { refused: off ? 'Agent Messages were turned off on its computer' : 'it is no longer in a tab with the sender' }
  }

  function localChanged(status: DeliveryStatus, delivery: LocalDelivery): void {
    const full = { ...status, machineId: self() }
    if (status.state === 'delivered') {
      const roster = rosterOf(delivery.agentId)
      // The note rode with this message: the agent has it.
      if (roster) { store.state.noted[delivery.agentId] = roster.signature; withdrawNote(delivery.agentId) }
    }
    if (store.status(full)) tellWindows(full.messageId)
    options.changed?.()
  }

  function tellWindows(id: string): void {
    const entry = store.entry(id)
    if (!entry) return
    core.clients.windows({ type: 'messages_changed', payload: {
      tabId: entry.message.tabId, messageId: id, at: entry.message.at,
      from: { machineId: entry.message.from.machineId, agentId: entry.message.from.agentId },
      to: entry.message.to.map((r) => {
        const status = entry.statuses.find((s) => s.machineId === r.machineId && s.agentId === r.agentId)
        return { machineId: r.machineId, agentId: r.agentId, state: status?.state ?? 'queued' }
      }),
    } })
  }

  // ── names and the roster note ────────────────────────────────────────────────────────────────────

  /** Whether a harness is another account's, in a tab shared with it: named by the tab's roster, and never asked about
   *  over this account's relay, which reaches only this account's machines. */
  const foreign = (member: Member): boolean => !!member.accountId && member.accountId !== account?.accountId

  /** A teammate as the note and the roster show them: from this machine's registry, another machine's word, or for
   *  another account's harness, its tab's roster (sharedDirectory.ts, which takes out what could redraw a terminal). */
  function teammate(member: Member): Teammate & { member: Member; known: boolean } {
    if (member.machineId === self()) {
      const session = localAgent(member.agentId)
      const branch = session?.cwd ? branches.get(session.cwd)?.branch : undefined
      return { member, known: !!session, name: session ? core.agents.displayName(session) || idStart(member.agentId) : idStart(member.agentId),
        engine: session?.engine ?? 'agent', machine: machineName(member.machineId), ...(session?.cwd ? { where: basename(session.cwd) } : {}), ...(branch ? { branch } : {}) }
    }
    if (foreign(member)) {
      // Named by its tab's roster; where it works, by its machine's answer (`learnNames`), which names nothing.
      const { project, branch } = who.get(key(member)) ?? {}
      return { member, known: true, name: member.name || idStart(member.agentId), engine: member.engine || 'agent', machine: machineName(member.machineId),
        ...(project ? { where: project } : {}), ...(branch ? { branch } : {}) }
    }
    const known = who.get(key(member))
    return { member, known: !!known, name: known?.name || idStart(member.agentId), engine: known?.engine ?? 'agent', machine: machineName(member.machineId),
      ...(known?.project ? { where: known.project } : {}), ...(known?.branch ? { branch: known.branch } : {}) }
  }

  /**
   * Teammates each with a name it can be told apart by, from `me`'s side. A name is a session's title, and two can
   * share one: two Codex agents in a tab both titled themselves after the task one gave the other, so the roster
   * named the teammate as the agent itself (a fresh Mac, 2026-10-12). In a tab shared across accounts, a name another
   * account's harness shares with a harness of any other account, this one's included, takes its account's prefix
   * (`bob/api`, the spec's "Messages across accounts"); a name still shared with anyone here, the sender included,
   * gets the start of its id, which `harness send` takes on its own. `qualified` and `bare`: another account's harness
   * by its name with its account's prefix and without, for a sender that writes one or the other. `harness`: the name
   * without the account's prefix, and `marker`: its account's label in a task marker, which `tabNote` names it by.
   */
  function distinct(me: Member, members: Member[]): Array<ReturnType<typeof teammate> & { qualified?: string; bare?: string; harness: string; marker?: string }> {
    const mates = members.map((m) => { const mate = teammate(m); return { ...mate, harness: mate.name } })
    const accounts = accountsIn(rosters?.all() ?? [])
    const accountOf = (m: Member): string => (foreign(m) ? m.accountId! : '')
    const holders = new Map<string, Set<string>>()
    for (const [name, holder] of [[teammate(me).name, ''], ...mates.map((m) => [m.name, accountOf(m.member)])]) {
      holders.set(name.toLowerCase(), (holders.get(name.toLowerCase()) ?? new Set<string>()).add(holder))
    }
    const prefixed = mates.map((m) => {
      if (!foreign(m.member)) return m
      const named = accounts.get(m.member.accountId!)
      const qualified = `${named?.label ?? idStart(m.member.accountId!)}/${m.name}`
      // A shared tab's note names its account (`Bob's account`), as a message's header does.
      return { ...m, name: holders.get(m.name.toLowerCase())!.size > 1 ? qualified : m.name, qualified: qualified.toLowerCase(), bare: m.name.toLowerCase(),
        account: named?.name ?? idStart(m.member.accountId!), marker: named?.marker ?? markerLabel(idStart(m.member.accountId!)) }
    })
    const counts = new Map<string, number>()
    for (const name of [teammate(me).name, ...prefixed.map((m) => m.name)]) counts.set(name.toLowerCase(), (counts.get(name.toLowerCase()) ?? 0) + 1)
    return prefixed.map((m) => (counts.get(m.name.toLowerCase()) ?? 0) > 1
      ? { ...m, name: `${m.name} (${idStart(m.member.agentId)})`, harness: `${m.harness} (${idStart(m.member.agentId)})` } : m)
  }

  /** This harness's own name as its teammates see it: with the start of its id when one of them shares it. Another
   *  account's harness of the same name is told apart by its account's prefix instead (`distinct`). */
  function ownName(me: Member, members: Member[]): string {
    const name = teammate(me).name
    return members.some((m) => !foreign(m) && teammate(m).name.toLowerCase() === name.toLowerCase()) ? `${name} (${idStart(me.agentId)})` : name
  }

  /**
   * Ask other machines for their agents' names, those not known or too old; a machine asked lately, answering or
   * not, is not asked again yet. The notes are looked at again only when a name changed: looked at on every
   * answer, a teammate no machine can name (a stopped harness here) asked again at once, without end.
   */
  async function learnNames(members: Member[], wait: boolean): Promise<void> {
    const byMachine = new Map<string, { agentIds: string[]; tab: string | null }>()
    for (const m of members) {
      if (m.machineId === self()) continue
      const known = who.get(key(m))
      if (known && now() - known.at < WHO_MS) continue
      // Another account's computer is never waited for: it may be away for hours, and its roster already names it.
      const theirs = foreign(m)
      if (now() - (asked.get(m.machineId) ?? -Infinity) < WHO_MS && (!wait || theirs)) continue
      const tab = theirs ? tabOf(m.machineId) : null
      if (theirs && !tab) continue
      byMachine.set(m.machineId, { agentIds: [...(byMachine.get(m.machineId)?.agentIds ?? []), m.agentId], tab })
    }
    if (!byMachine.size) return
    let learned = false
    const asks = [...byMachine].map(([machineId, { agentIds, tab }]) => ({ tab, asked: (async () => {
      asked.set(machineId, now())
      try {
        const payload = { action: 'who', agentIds }
        const answer = tab ? await askTab(tab, machineId, payload, 8_000) : await rpc(at(machineId), payload, 8_000)
        for (const a of Array.isArray(answer.agents) ? answer.agents as Record<string, unknown>[] : []) {
          if (typeof a.agentId !== 'string' || typeof a.name !== 'string' || (tab && !agentIds.includes(a.agentId))) continue
          const before = who.get(`${machineId}/${a.agentId}`)
          // Another account's word only for where its harness works, cleaned: its name and engine are its roster's.
          const project = tab ? cleanText(a.project, 200) || undefined : typeof a.project === 'string' ? a.project : undefined
          const branch = tab ? cleanText(a.branch, 200) || undefined : typeof a.branch === 'string' ? a.branch : undefined
          const next = { name: tab ? '' : a.name, engine: tab ? '' : typeof a.engine === 'string' ? a.engine : 'agent', ...(project ? { project } : {}),
            ...(branch ? { branch } : {}), at: now() }
          // A branch alone is no reason to look at the notes again: it is left out of their signature (`rosterOf`).
          if (!before || before.name !== next.name || before.engine !== next.engine || before.project !== next.project) learned = true
          who.set(`${machineId}/${a.agentId}`, next)
        }
      } catch { /* that machine is away: its agents keep the names they had */ }
    })() }))
    // The notes are looked at once this account's machines answered, and again once other accounts' did.
    const settled = (tab: boolean) => Promise.all(asks.filter((a) => !!a.tab === tab).map((a) => a.asked)).then(() => { if (learned) { learned = false; notesPump() } })
    const own = settled(false)
    void settled(true)
    if (wait) await own
  }

  /** The note a local agent should have read, or null when it shares no tab with a teammate, or Agent Messages are
   *  off here. */
  function rosterOf(agentId: string): { text: string; signature: string } | null {
    const me = { machineId: self(), agentId }
    const peers = directory.peers(me)
    if (!peers.length) return null
    const mates = distinct(me, peers)
    const tabs = directory.tabsOf(me)
    const about = tabNote(me, tabs, mates)
    const text = note(tabs, mates, about)
    // The signature, which decides whether the agent is given the note again, leaves the branches out: an agent switches
    // branches many times in a task, and each switch would otherwise put the whole note in every teammate's context
    // again. `harness send` alone prints the branches as they are now.
    const signed = about.sharedTabId ? note(tabs, mates.map(({ branch: _branch, ...mate }) => mate), about) : text
    return { text, signature: createHash('sha256').update(signed).digest('hex').slice(0, 12) }
  }

  /**
   * What a harness's note says of its tab: who leads it, by the name the harness reaches it by, and for a tab shared with
   * other accounts its id. A harness in a shared tab is told of the first one, as before tab leaders; any other of its
   * first tab. The leader is the account's tab setting, as the directory lists it, for every tab of this account's desk,
   * the one it shares included: that setting is the one source, and the roster only follows it. In a tab another account
   * shares, which lists no setting, it is the roster's. A leader the tab does not list (an owner's roster may name any
   * harness) is no one to defer to, and is not named.
   */
  function tabNote(me: Member, tabs: DirectoryTab[], mates: ReturnType<typeof distinct>): TabNote {
    const tab = tabs.find((t) => t.sharedTabId) ?? tabs[0]
    const sharedTabId = tab.sharedTabId
    // A backend from before tab leaders lists no setting for this account's tabs either: a shared one's roster names it.
    const lead = tab.leader !== undefined ? tab.leader : sharedTabId ? rosters?.current(sharedTabId)?.roster.leader ?? null : null
    const youLead = !!lead && lead.machineId === me.machineId && lead.agentId === me.agentId
    const leader = lead && mates.find((m) => m.member.machineId === lead.machineId && m.member.agentId === lead.agentId)?.name
    // An unshared tab's tasks carry the id it would get if shared (`tabKey`), so a task made before sharing stays the tab's.
    // Unknown until the account is (`signedInAs`), and the note then changes once.
    const tabKey = !sharedTabId && account ? sharedTabIdOf(account.accountId, tab.id) : undefined
    const label = account ? markerLabel(account.email) : undefined
    // Each harness by what the marker takes (final review I2): its name as said, made marker-safe, under its account's label.
    // Two harnesses of one account whose marker names are the same (titles that differ only in what a marker drops, or
    // that have no letter) would be one assignee, and the desktop would give the task to the first: each gets the start
    // of its id, where the marker name collides in the tab, not only where the display names do.
    const entries = label ? [{ account: label, display: ownName(me, mates.map((m) => m.member)), agentId: me.agentId, name: '', you: true },
      ...mates.map((m) => ({ account: m.marker ?? label, display: m.harness, agentId: m.member.agentId, name: m.name, you: false }))] : []
    const taken = new Map<string, number>()
    for (const e of entries) taken.set(`${e.account}/${markerName(e.display)}`, (taken.get(`${e.account}/${markerName(e.display)}`) ?? 0) + 1)
    const assignees = entries.map((e) => ({ name: e.name, marker: `${e.account}/${(taken.get(`${e.account}/${markerName(e.display)}`) ?? 0) > 1
      ? markerNameWithId(e.display, e.agentId) : markerName(e.display)}`, ...(e.you ? { you: true } : {}) }))
    return { ...(sharedTabId ? { sharedTabId } : tabKey ? { tabKey } : {}), ...(label ? { account: label, assignees } : {}), youLead, ...(leader ? { leader } : {}) }
  }

  /** A tab's tasks for a request or a note, only for a roster this computer holds: `gh` is never run for any other id. */
  function tasksOf(sharedTabId: string): Promise<TaskResult> {
    if (!/^[a-f0-9]{24}$/.test(sharedTabId) || !rosters?.current(sharedTabId)) return Promise.reject(new MessageError('NOT_SHARED', 'This computer holds no such shared tab.'))
    return tasks(sharedTabId)
  }

  /** The tasks of one of this account's desk tabs, shared or not, by the key shared tabs use (sharedTabs `sharedTabIdOf`):
   *  `gh` runs for it without a roster, since the key is derived and nothing another account sent is in it. A tab of another
   *  account's shared tab is not on this desk, and is refused. */
  async function tasksOfTab(tabId: string): Promise<TaskResult> {
    const me = await signedInAs()
    const key = sharedTabIdOf(me.accountId, tabId)
    // A tab of another account's has its share id for id, which is never the key derived from this account.
    const onDesk = (): boolean => !!directory.current()?.tabs.some((t) => t.id === tabId && (!t.sharedTabId || t.sharedTabId === key))
    // The listing at hand answers for a tab it has; only a tab it lacks may be new, and asks the backend again.
    if (!onDesk()) await directory.refresh()
    const tab = onDesk()
    if (!tab) throw new MessageError('NOT_A_TAB', 'That tab is not on your desk.')
    return tasks(key)
  }

  /** What `harness send` alone adds: its tab's tasks, or the reason they cannot be read now (no `gh`, signed out): the
   *  roster is still given whole. In a tab shared with other accounts, from its held roster; in any other, from the key
   *  the tab would be shared with. */
  async function tasksSection(me: Member): Promise<TaskResult | { error: string; detail: string } | null> {
    const tabs = directory.tabsOf(me)
    const tab = tabs.find((t) => t.sharedTabId) ?? tabs[0]
    if (!tab || mode !== 'awake') return null
    const sharedTabId = tab.sharedTabId
    // The roster and the messages are never held back for GitHub: gh may take 8 s a run and several runs a refresh, and the
    // client waits 30 s in all. A slow refresh goes on and fills the cache for the next look.
    let timer: ReturnType<typeof setTimeout> | undefined
    const late = new Promise<{ error: string; detail: string }>((resolve) => {
      timer = setTimeout(() => resolve({ error: 'LOADING', detail: 'still loading: ask again in a moment' }), TASKS_WAIT_MS)
      timer.unref?.()
    })
    return Promise.race([sharedTabId ? tasksOf(sharedTabId) : tasksOfTab(tab.id), late]).finally(() => clearTimeout(timer)).catch((error: unknown) => error instanceof MessageError
      ? { error: error.code, detail: error.message }
      : { error: 'TASKS_UNAVAILABLE', detail: 'The tasks could not be read right now.' })
  }

  /** Read again the branches of the folders here not read in WHO_MS: a read under way is waited for, not repeated. */
  function readBranches(cwds: readonly string[]): Promise<void> {
    return Promise.all([...new Set(cwds)].map((cwd) => {
      const known = branches.get(cwd)
      if (known && now() - known.at < WHO_MS) return known.read
      // The branch read before is kept until the new one is in.
      const entry: { at: number; read: Promise<void>; branch?: string } = { at: now(), read: Promise.resolve(), ...(known?.branch ? { branch: known.branch } : {}) }
      entry.read = project(cwd).then((found) => {
        if (found?.branch) entry.branch = found.branch
        else delete entry.branch
      }, () => { /* the folder cannot be read now: no branch is shown */ })
      branches.set(cwd, entry)
      return entry.read
    })).then(() => {})
  }

  const inSharedTab = (member: Member): boolean => directory.tabsOf(member).some((t) => !!t.sharedTabId)

  /** The branches of a harness here and its teammates here, for its note, when it is in a shared tab. */
  function branchesFor(me: Member): Promise<void> {
    if (!inSharedTab(me)) return Promise.resolve()
    const cwds = [me, ...directory.peers(me)].filter((m) => m.machineId === self()).map((m) => localAgent(m.agentId)?.cwd)
    return readBranches(cwds.filter((cwd): cwd is string => !!cwd))
  }

  /**
   * Another of the owner's machines started a harness here for one of its agents (`harness new --machine <this machine>`): kept
   * in this machine's record too, so the new harness's depth and this machine's limits count it.
   */
  function started(payload: Record<string, unknown>): Record<string, unknown> {
    const row = parseStarted(JSON.stringify(payload.row ?? null))
    if (!row || row.child.machineId !== self() || row.by.machineId === self()) throw new MessageError('INVALID_RECORD', 'That is not a harness another machine started here.')
    if (!core.agents.live().some((s) => s.agentId === row.child.agentId)) throw new MessageError('UNKNOWN_HARNESS', 'No such harness on this machine.')
    lineage.append(row)
    return { recorded: true }
  }

  /** When each starter told, for the rate limit: the same 30 in 10 minutes a `harness send` sender has. */
  const toldAt = new Map<string, number[]>()

  /**
   * `harness tell` (tell.ts): more work for a harness here from the harness that started it. From a pane on this
   * machine the starter is the pane's harness, never what the request says; from another of the owner's machines,
   * over the relay, it is that machine's word, as a hand-over's sender is (`deliver`). Either way this machine's own
   * record must say that starter started it. Queued in the mailbox, which types it once the harness's composer is
   * free, or gives it at its next tool call while it works.
   */
  async function tell(payload: Record<string, unknown>, local: boolean): Promise<Record<string, unknown>> {
    let from: Member
    let caller: RegisteredSession | undefined
    // `harness reply` from a pane: the words of the person, passed on by their Buddy (#2626); never another agent's.
    const reply = payload.reply === true
    if (local) {
      const pane = typeof payload.pane === 'string' ? payload.pane : ''
      caller = PANE.test(pane) ? sessionForPaneId(live(), pane) : undefined
      if (!caller) throw new MessageError('NOT_A_HARNESS', 'Run harness tell from the pane of the harness that started it.')
      from = { machineId: self(), agentId: caller.agentId }
    } else {
      const claimed = payload.from as Record<string, unknown> | null | undefined
      if (typeof claimed?.machineId !== 'string' || !claimed.machineId || typeof claimed.agentId !== 'string' || !claimed.agentId) {
        throw new MessageError('INVALID_REQUEST', 'Say which harness tells it.')
      }
      // This machine's own harnesses tell from their pane.
      if (claimed.machineId === self()) throw new MessageError('NOT_FROM_THERE', 'A harness on this machine tells from its pane, not over the relay.')
      from = { machineId: claimed.machineId, agentId: claimed.agentId }
    }
    const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
    const text = typeof payload.text === 'string' ? payload.text : ''
    if (!agentId) throw new MessageError('USAGE', 'Name the harness to tell.')
    if (!text.trim()) throw new MessageError('USAGE', 'Say what to do: harness tell <name> -- <work>')
    if (text.length > LIMITS.text) throw new MessageError('TOO_LONG', `A message holds at most ${LIMITS.text} characters.`)
    const refusal = tellRefusal({ on: tellOn(), lineage, self: self(), live: (id) => !!localAgent(id) }, from, agentId)
    // Not a harness it started: a Buddy here may still pass its person's words to their own (relay); nobody else may.
    if (refusal?.code === 'NOT_YOURS' && local && isBuddy(caller)) return relay(caller, agentId, text, payload, reply)
    if (refusal) throw new MessageError(refusal.code, refusal.message)
    if (reply) throw new MessageError('NOT_YOURS', 'Only the person replies to a harness: tell them what it asked. To give more work to one you started, use harness tell.')
    const key = `${from.machineId}/${from.agentId}`
    const times = (toldAt.get(key) ?? []).filter((t) => now() - t < LIMITS.window)
    if (times.length >= LIMITS.perSender) throw new MessageError('RATE_LIMITED', `You told your harnesses ${LIMITS.perSender} times in 10 minutes. Wait for their answers first.`)
    if (store.state.local.filter((d) => d.state === 'queued').length >= LIMITS.waiting) {
      throw new MessageError('MAILBOX_FULL', 'Too many messages are waiting on that machine. Try again once some are delivered.')
    }
    // Named as it was started: who started it is this machine's record, not the request's.
    const started = lineage.parentOf({ machineId: self(), agentId })!
    // The machine's name as the starter's CLI reads it (`machine-name`), as a start's header names it: Agent Messages'
    // directory knows names only while it is on, and without it this one was headed with the host's name
    // ("Macbooks-MacBook-Pro-5" for "Mac Auto", 2026-10-26).
    const machine = typeof payload.machine === 'string' && payload.machine.trim() ? payload.machine.trim().slice(0, 200) : machineName(from.machineId)
    const message: Message = {
      id: messageId(), tabId: TOLD_TAB, text, at: now(),
      to: [{ machineId: self(), agentId, name: started.child.name || agentId.slice(0, 8) }],
      from: { ...from, name: started.by.name || from.agentId.slice(0, 8), engine: started.by.engine || 'claude', machine },
    }
    toldAt.set(key, [...times, now()])
    store.record(message)
    store.status({ messageId: message.id, machineId: self(), agentId, state: 'queued', at: now() })
    mailbox.accept(message, agentId)
    // Asleep (Agent Messages off), the mailbox looks only while something waits: this does now.
    mailbox.resume()
    saveQuietly()
    const status = store.entry(message.id)?.statuses.find((s) => s.machineId === self() && s.agentId === agentId)
    return { id: message.id, state: status?.state ?? 'queued', ...(status?.reason ? { reason: status.reason } : {}) }
  }

  /**
   * A person's Buddy passing their words to their own harness here (tell.ts `relayRefusal`, #2626): checked from this
   * machine's registry, kept under `relayed`, queued in the mailbox as a tell is, at the same rate and limits. A reply goes
   * only to an idle harness, as a program's does: one that may wait on a question or a permission is the person's.
   */
  async function relay(buddy: RegisteredSession, agentId: string, text: string, payload: Record<string, unknown>, reply: boolean): Promise<Record<string, unknown>> {
    const refusal = relayCheck(buddy, agentId)
    if (refusal) throw new MessageError(refusal.code, refusal.message)
    if (reply) {
      const activity = (await core.agents.activity([agentId]))[agentId] ?? 'unknown'
      const busy = replyRefusal({ on: true, live: true, activity })
      if (busy) throw new MessageError(busy.code, busy.message)
    }
    const key = `${self()}/${buddy.agentId}`
    const times = (toldAt.get(key) ?? []).filter((t) => now() - t < LIMITS.window)
    if (times.length >= LIMITS.perSender) throw new MessageError('RATE_LIMITED', `You passed words to your owner's harnesses ${LIMITS.perSender} times in 10 minutes. Wait for them first.`)
    if (store.state.local.filter((d) => d.state === 'queued').length >= LIMITS.waiting) {
      throw new MessageError('MAILBOX_FULL', 'Too many messages are waiting on that machine. Try again once some are delivered.')
    }
    const target = localAgent(agentId)!
    const machine = typeof payload.machine === 'string' && payload.machine.trim() ? payload.machine.trim().slice(0, 200) : machineName(self())
    const message: Message = {
      id: messageId(), tabId: RELAYED_TAB, text, at: now(),
      to: [{ machineId: self(), agentId, name: core.agents.displayName(target) || agentId.slice(0, 8) }],
      from: { machineId: self(), agentId: buddy.agentId, name: core.agents.displayName(buddy) || buddy.agentId.slice(0, 8), engine: buddy.engine, machine },
    }
    toldAt.set(key, [...times, now()])
    store.record(message)
    store.status({ messageId: message.id, machineId: self(), agentId, state: 'queued', at: now() })
    mailbox.accept(message, agentId)
    mailbox.resume()
    saveQuietly()
    const status = store.entry(message.id)?.statuses.find((s) => s.machineId === self() && s.agentId === agentId)
    return { id: message.id, state: status?.state ?? 'queued', ...(status?.reason ? { reason: status.reason } : {}) }
  }

  /** When programs replied to harnesses here, for the rate limit: the same 30 in 10 minutes a `tell` has. */
  const repliedAt: number[] = []

  /**
   * `harness reply` to a harness in a pane here (replyLocal.ts), from a program acting for the person: a process of the
   * owner's on this machine, or another of the owner's machines over the relay. Only an idle harness, only with the
   * person's switch on; queued in the mailbox, which types it once the composer is free.
   */
  async function replyLocal(payload: Record<string, unknown>): Promise<Record<string, unknown>> {
    const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''
    const text = typeof payload.text === 'string' ? payload.text : ''
    if (!agentId) throw new MessageError('USAGE', 'Name the harness to reply to.')
    if (!text.trim()) throw new MessageError('USAGE', 'Give the words: harness reply <name> -- <words>')
    if (text.length > LIMITS.text) throw new MessageError('TOO_LONG', `A message holds at most ${LIMITS.text} characters.`)
    const session = localAgent(agentId)
    const activity = session ? (await core.agents.activity([agentId]))[agentId] ?? 'unknown' : 'unknown'
    const refusal = replyRefusal({ on: replyOn(), live: !!session, activity })
    if (refusal) throw new MessageError(refusal.code, refusal.message)
    while (repliedAt.length && now() - repliedAt[0] >= LIMITS.window) repliedAt.shift()
    if (repliedAt.length >= LIMITS.perSender) throw new MessageError('RATE_LIMITED', `Programs replied to your harnesses ${LIMITS.perSender} times in 10 minutes. Wait for their answers first.`)
    if (store.state.local.filter((d) => d.state === 'queued').length >= LIMITS.waiting) {
      throw new MessageError('MAILBOX_FULL', 'Too many messages are waiting on that machine. Try again once some are delivered.')
    }
    const machine = typeof payload.machine === 'string' && payload.machine.trim() ? payload.machine.trim().slice(0, 200) : machineName(self())
    const message: Message = {
      id: messageId(), tabId: REPLIED_TAB, text, at: now(),
      to: [{ machineId: self(), agentId, name: core.agents.displayName(session!) || agentId.slice(0, 8) }],
      from: { machineId: self(), agentId: PERSON_AGENT_ID, name: 'the person', engine: '', machine },
    }
    repliedAt.push(now())
    store.record(message)
    store.status({ messageId: message.id, machineId: self(), agentId, state: 'queued', at: now() })
    mailbox.accept(message, agentId)
    mailbox.resume()
    saveQuietly()
    const status = store.entry(message.id)?.statuses.find((s) => s.machineId === self() && s.agentId === agentId)
    return { id: message.id, state: status?.state ?? 'queued', ...(status?.reason ? { reason: status.reason } : {}) }
  }

  function withdrawNote(agentId: string): void {
    const pending = store.state.notes[agentId]
    if (!pending) return
    inbox.withdraw(pending.pane, pending.key)
    delete store.state.notes[agentId]
    saveQuietly()
  }

  /** Give each local agent the roster note it has not read: through its hook only, never typed. Off, take each back. */
  function notesPump(): void {
    if (!directory.current() && directory.on()) return
    const unknown: Member[] = []
    const alive = new Set(live().map((s) => s.agentId))
    // A note for a harness that is gone or stopped is withdrawn: its pane number may be another's next.
    for (const agentId of Object.keys(store.state.notes)) if (!alive.has(agentId)) withdrawNote(agentId)
    for (const session of live()) {
      const pending = store.state.notes[session.agentId]
      if (pending && inbox.claimed(pending.pane, pending.key)) {
        store.state.noted[session.agentId] = pending.signature
        delete store.state.notes[session.agentId]
        saveQuietly()
      }
      const roster = rosterOf(session.agentId)
      if (!roster) { withdrawNote(session.agentId); continue }
      // Read for the next look and for `harness send` alone: a branch never changes the note's signature.
      void branchesFor({ machineId: self(), agentId: session.agentId })
      // Only another machine can name its agents: a teammate here with no harness is stopped, and has no name to ask.
      unknown.push(...directory.peers({ machineId: self(), agentId: session.agentId }).filter((m) => m.machineId !== self() && !teammate(m).known))
      if (store.state.noted[session.agentId] === roster.signature) { withdrawNote(session.agentId); continue }
      const current = store.state.notes[session.agentId]
      const pane = inboxPane(session)
      if (current?.signature === roster.signature && current.pane === pane && inbox.waiting(current.pane, current.key)) continue
      withdrawNote(session.agentId)
      const noteKey = `0note-${roster.signature}`
      try {
        inbox.put(pane, noteKey, { session: session.sessionId ?? '', text: roster.text })
        store.state.notes[session.agentId] = { pane, key: noteKey, signature: roster.signature }
        saveQuietly()
      } catch { /* the next look puts it */ }
    }
    if (unknown.length) void learnNames(unknown, false)
  }

  // ── sending ──────────────────────────────────────────────────────────────────────────────────────

  async function send(payload: Record<string, unknown>): Promise<Record<string, unknown>> {
    const pane = typeof payload.pane === 'string' ? payload.pane : ''
    if (!PANE.test(pane)) throw new MessageError('NOT_A_HARNESS', 'Run harness send from a harness pane.')
    // A bare `%N` is `$TMUX_PANE`, a tmux pane only (`sessionForPaneId`).
    const session = sessionForPaneId(live(), pane)
    if (!session) throw new MessageError('NOT_A_HARNESS', 'This pane is not a harness Harness knows. Run harness send from an agent\'s pane.')
    // Off is the person's word, answered before the tabs are read: a backend that cannot be reached is not the reason.
    if (!directory.on()) throw new MessageError('MESSAGES_OFF', MESSAGES_OFF_TEXT)
    if (!await directory.refresh()) throw new MessageError('DIRECTORY_UNAVAILABLE', 'Harness could not read who is in which tab. Try again in a moment.')
    const me = { machineId: self(), agentId: session.agentId }
    const peers = directory.peers(me)
    await learnNames(peers, true)
    const mates = distinct(me, peers)
    const names = (Array.isArray(payload.to) ? payload.to : typeof payload.to === 'string' ? payload.to.split(',') : [])
      .map((n) => String(n).trim()).filter(Boolean)
    const text = typeof payload.text === 'string' ? payload.text : ''
    // No recipient and no text: who is here, the rules, and this agent's last messages. An agent whose context
    // was compacted asks this to learn again what it was told: seen on a real team, one rebuilt it from its team
    // history in five commands.
    if (!names.length && !text) {
      await branchesFor(me)
      const roster = rosterOf(session.agentId)?.text ?? 'No teammates in this tab yet.'
      const section = await tasksSection(me)
      return { roster, recent: recentFor(me), ...(section ? { tasks: section } : {}) }
    }
    // Alone in its tab, or in none: a name it gives can be no one's, and the person is the one who can change that.
    if (!peers.length) throw new MessageError('NO_TEAMMATES', 'No other harness is in this tab. The person puts harnesses in one tab for them to message each other.')
    if (!names.length) throw new MessageError('USAGE', 'Name who to message: harness send <name> "text"')
    if (!text.trim()) throw new MessageError('USAGE', 'Write the message: harness send <name> "text"')
    if (text.length > LIMITS.text) throw new MessageError('TOO_LONG', `A message holds at most ${LIMITS.text} characters.`)
    const recipients: Recipient[] = []
    for (const name of names) {
      const wanted = name.toLowerCase()
      // The name as listed first; then another account's harness by its name with its account's prefix (`bob/web` for
      // a `web` no one else has); then the start of a name as listed or of another account's harness's own name, together:
      // a bare `api` taken whole before the start of the others picked Bob's `api` over this account's `api (abcd1234)`,
      // where the sender meant either (review of B1), so a name both could be is AMBIGUOUS. Last, the start of a name
      // with its account's prefix (`carol/w`).
      const starts = (n: string | undefined): boolean => n !== undefined && (n.startsWith(wanted) || cutShort(n, wanted))
      const exact = mates.filter((m) => m.name.toLowerCase() === wanted)
      const qualified = exact.length ? exact : mates.filter((m) => m.qualified === wanted)
      const listed = qualified.length ? qualified : mates.filter((m) => starts(m.name.toLowerCase()) || starts(m.bare))
      const prefix = listed.length ? listed : mates.filter((m) => starts(m.qualified))
      // Or the start of its id: a name is the session's title until someone names it, and a title can hold a comma,
      // which the recipient list splits on.
      const found = prefix.length || wanted.length < 6 ? prefix : mates.filter((m) => m.member.agentId.toLowerCase().startsWith(wanted))
      const list = mates.map((m) => m.name).join(', ') || 'nobody yet'
      if (!found.length) throw new MessageError('UNKNOWN_RECIPIENT', `No teammate named "${name}" in this tab. Teammates: ${list}.`)
      if (found.length > 1) throw new MessageError('AMBIGUOUS_RECIPIENT', `"${name}" could be ${found.map((m) => m.name).join(' or ')}. Use more of the name.`)
      if (!recipients.some((r) => r.machineId === found[0].member.machineId && r.agentId === found[0].member.agentId)) {
        recipients.push({ ...found[0].member, name: found[0].name })
      }
    }
    if (recipients.length > LIMITS.recipients) throw new MessageError('TOO_MANY_RECIPIENTS', `A message goes to at most ${LIMITS.recipients} teammates.`)
    // The first recipient's tab names the message's log. The directory and the setting can change while other
    // machines are asked for names: Agent Messages turned off, or the tab left, meanwhile leaves none, and nothing is
    // sent.
    const tab = directory.shared(me, recipients[0])
    if (!tab && !directory.on()) throw new MessageError('MESSAGES_OFF', `${MESSAGES_OFF_TEXT} Nothing was sent.`)
    if (!tab) throw new MessageError('NOT_IN_TAB', `${recipients[0].name} is no longer in a tab with you. Nothing was sent.`)
    const times = (sent.get(session.agentId) ?? []).filter((t) => now() - t < LIMITS.window)
    if (times.length >= LIMITS.perSender) {
      core.clients.windows({ type: 'messages_changed', payload: { limited: { machineId: self(), agentId: session.agentId } } })
      throw new MessageError('RATE_LIMITED', `This harness sent ${LIMITS.perSender} messages in 10 minutes. Wait, or work on without its teammates for now.`)
    }
    if (store.state.local.filter((d) => d.state === 'queued').length >= LIMITS.waiting) {
      throw new MessageError('MAILBOX_FULL', 'Too many messages are waiting on this machine. Try again once some are delivered.')
    }
    const message: Message = {
      id: messageId(), tabId: tab.id, to: recipients, text, at: now(), ...(payload.fyi === true ? { fyi: true as const } : {}),
      from: { ...me, name: ownName(me, peers), engine: session.engine, machine: machineName(self()) },
    }
    // How each other machine is reached, decided now and kept with its hand-over: another account's machine only
    // through a shared tab whose roster carries the message, in one frame, within the tab's limit.
    const ways = new Map<string, string | undefined>()
    for (const machineId of new Set(recipients.filter((r) => r.machineId !== self()).map((r) => r.machineId))) {
      const way = route(machineId, message)
      if (way === null || way === 'relay') { ways.set(machineId, undefined); continue }
      const roster = way.tab ? rosters?.current(way.tab)?.roster : undefined
      if (!roster || !carries(roster, message, machineId, account!.accountId)) {
        throw new MessageError('NOT_IN_TAB', `${recipients.find((r) => r.machineId === machineId)!.name} is no longer in a tab with you. Nothing was sent.`)
      }
      if (!fitsRequest({ action: 'deliver', message: wireMessage(message, roster.sharedTabId) })) throw new MessageError('TOO_LARGE', `${TOO_LARGE_TEXT} Nothing was sent.`)
      ways.set(machineId, roster.sharedTabId)
    }
    const tabs = new Set([...ways.values()].filter((id): id is string => !!id))
    for (const id of tabs) {
      if (tabSent.room(id, LIMITS.perTab, LIMITS.window, now())) continue
      core.clients.windows({ type: 'messages_changed', payload: { limited: { machineId: self(), agentId: session.agentId, sharedTabId: id } } })
      throw new MessageError('RATE_LIMITED', `This computer sent ${LIMITS.perTab} messages into that shared tab in 10 minutes. Wait, or work on without those teammates for now.`)
    }
    sent.set(session.agentId, [...times, now()])
    for (const id of tabs) tabSent.take(id, LIMITS.perTab, LIMITS.window, now())
    store.record(message)
    for (const r of recipients) store.status({ messageId: message.id, machineId: r.machineId, agentId: r.agentId, state: 'queued', at: now() })
    for (const r of recipients.filter((r) => r.machineId === self())) mailbox.accept(message, r.agentId)
    for (const [machineId, sharedTabId] of ways) {
      store.state.outbox.push({ messageId: message.id, machineId, nextTryAt: now(), tries: 0, ...(sharedTabId ? { sharedTabId } : {}) })
    }
    saveQuietly()
    await handOver(message.id)
    tellWindows(message.id)
    const entry = store.entry(message.id)!
    return {
      id: message.id, tab: tab.name,
      recipients: recipients.map((r) => {
        const status = entry.statuses.find((s) => s.machineId === r.machineId && s.agentId === r.agentId)
        return { name: r.name, state: status?.state ?? 'queued', ...(status?.via ? { via: status.via } : {}), ...(status?.reason ? { reason: status.reason } : {}),
          ...(status?.code ? { code: status.code } : {}) }
      }),
      ...(text.length > LONG_TEXT ? { advice: longAdvice(text.length) } : {}),
    }
  }

  /**
   * What `harness send` alone gives an agent besides the roster: every message still waiting for it, which it has
   * now read, then its last few. An agent whose engine started before Agent Messages never runs the hook and, always
   * working, is never typed to: it read its messages this way, but only the last five, each still "queued", and a
   * restart would have given it all of them again (a Codex lead, 2026-10-12).
   */
  function recentFor(me: Member, count = 5): Array<Record<string, unknown>> {
    const mine = (m: Member) => m.machineId === me.machineId && m.agentId === me.agentId
    const involving = store.state.history.filter((e) => mine(e.message.from) || e.message.to.some(mine))
    const waiting = involving.filter((e) => !mine(e.message.from) && e.statuses.find((s) => mine(s))?.state === 'queued').slice(-UNREAD_MAX)
    const read = new Set(mailbox.read(me.agentId, waiting.map((e) => e.message.id)))
    const shown = [...new Set([...waiting, ...involving.slice(-count)])].sort((a, b) => a.message.at - b.message.at)
    return shown.map((e) => {
      const sent = mine(e.message.from)
      const status = sent ? e.statuses.find((s) => s.state !== 'delivered') ?? e.statuses[0] : e.statuses.find((s) => mine(s))
      return { id: e.message.id, at: e.message.at, ...(sent ? { to: e.message.to.map((r) => r.name) } : { from: e.message.from.name }),
        text: e.message.text, state: read.has(e.message.id) ? 'delivered' : status?.state ?? 'queued', ...(read.has(e.message.id) ? { unread: true } : {}) }
    })
  }

  // ── routes ───────────────────────────────────────────────────────────────────────────────────────

  /** Whether a machine is this account's: this one, or one its directory lists (the backend lists all of the account's). */
  const ownMachine = (machineId: string): boolean => machineId === self() || !!directory.current()?.machines.has(machineId)

  /** The held tabs that list a harness of another account's on a machine; none for a machine of this account's, which a
   *  roster of another account's may list under its own (sharedDirectory.ts takes it out the same way). */
  function tabsWith(machineId: string): Roster[] {
    const mine = account?.accountId
    if (!mine || ownMachine(machineId)) return []
    return (rosters?.all() ?? []).filter((r) => r.harnesses.some((h) => h.machineId === machineId && h.accountId !== mine))
  }
  const tabOf = (machineId: string): string | null => tabsWith(machineId)[0]?.sharedTabId ?? null

  /**
   * How a message reaches another machine: `'relay'`, this account's paired relay, as before shared tabs; `{ tab }`, the
   * shared tab whose relay carries it to another account's machine (one whose roster carries the message, when one
   * does), or `{ tab: null }` for another account's machine no held tab lists any more; null while it cannot be told
   * (the directory not read yet). `stored`: the tab chosen when it was sent, which stands. A message queued for another
   * account's harness before routes were kept (step 1b's B1) went to this account's relay, which only ever answered
   * that the machine was not paired, and was tried again for good: it goes through its tab now (review of B1).
   */
  function route(machineId: string, message: Message, stored?: string): 'relay' | { tab: string | null } | null {
    // Which machines are this account's is the directory's word: unread, nothing is decided, and nothing is sent.
    if (!directory.current()) return null
    // One of this account's machines goes over its own relay, whatever route was kept: a roster of another account's
    // listing it cannot pin it to a tab.
    if (ownMachine(machineId)) return 'relay'
    if (stored) return { tab: stored }
    const held = rosters?.all() ?? []
    if (held.length && !account) return null
    const tabs = tabsWith(machineId)
    if (tabs.length) return { tab: (tabs.find((r) => carries(r, message, machineId, account!.accountId)) ?? tabs[0]).sharedTabId }
    // Not one of the account's machines, nor in a held tab: another account's machine that left, or one a message was
    // queued for before routes were kept. Held, then failed, never tried for good over this account's relay.
    return { tab: null }
  }

  /** An Agent Messages request to another account's machine through a shared tab (sharedTabs.ts `request`): its answer;
   *  its refusal as a RefusedError, its words cleaned (they are another account's); a MessageError when it could not be
   *  asked. */
  async function askTab(sharedTabId: string, machineId: string, payload: Record<string, unknown>, timeoutMs: number): Promise<Record<string, unknown>> {
    if (!shared) throw new MessageError('PEER_AWAY', 'Shared tabs are not running on this computer right now.')
    const answer = await shared.request(sharedTabId, machineId, payload, timeoutMs)
    if (answer.error !== undefined) throw new RefusedError(statusCode(answer.error) ?? 'REFUSED', cleanText(answer.detail, 300) || 'refused')
    return answer
  }

  let missedTabAt = -Infinity
  /** An answer within `ms`, or null: a machine that did not answer, or refused, is not waited for longer. */
  async function within(asking: Promise<Record<string, unknown>>, ms: number): Promise<Record<string, unknown> | null> {
    let timer: ReturnType<typeof setTimeout> | undefined
    const late = new Promise<null>((done) => { timer = setTimeout(() => done(null), ms); timer.unref?.() })
    return Promise.race([asking.catch(() => null), late]).finally(() => clearTimeout(timer))
  }

  /**
   * Each harness of a held tab with its repo and branch, asked of its machine as a tab's note does (`who`). A machine is
   * asked only for the roster's harnesses on it, and only the answers for those are kept, so People never names more than
   * `who` already does; a machine that does not answer within WHO_WAIT_MS is left out, not waited for.
   */
  async function sharedWho(sharedTabId: string): Promise<Record<string, unknown>> {
    const roster = rosters?.current(sharedTabId)?.roster
    if (!roster) throw new MessageError('NOT_SHARED', 'This computer holds no shared tab with that id.')
    const me = await signedInAs()
    const byMachine = new Map<string, string[]>()
    for (const h of roster.harnesses) byMachine.set(h.machineId, [...(byMachine.get(h.machineId) ?? []), h.agentId])
    const answers = await Promise.all([...byMachine].map(async ([machineId, agentIds]) => {
      const payload = { action: 'who', agentIds }
      const own = roster.harnesses.some((h) => h.machineId === machineId && h.accountId === me.accountId)
      const asking = machineId === self() ? whoAre(payload, undefined, false) : own ? rpc(at(machineId), payload, WHO_WAIT_MS) : askTab(sharedTabId, machineId, payload, WHO_WAIT_MS)
      const answer = await within(asking, WHO_WAIT_MS)
      const agents = Array.isArray(answer?.agents) ? answer.agents as Record<string, unknown>[] : []
      return agents.filter((a) => typeof a.agentId === 'string' && agentIds.includes(a.agentId)).map((a) => ({ machineId, agentId: a.agentId as string,
        ...(typeof a.project === 'string' ? { project: cleanText(a.project, 120) } : {}), ...(typeof a.branch === 'string' ? { branch: cleanText(a.branch, 200) } : {}) }))
    }))
    return { harnesses: answers.flat() }
  }

  /** The name of the account another account's machine is in, as the rosters held here name it (`Bob`). */
  function accountName(machineId: string): string {
    const all = rosters?.all() ?? []
    const accountId = all.flatMap((r) => r.harnesses).find((h) => h.machineId === machineId && h.accountId !== account?.accountId)?.accountId
    return (accountId && accountsIn(all).get(accountId)?.name) || 'Its owner'
  }

  /** Why a hand-over through a shared tab waits, as the person reads it. */
  function tabReason(error: unknown, sharedTabId: string, machineId: string): string {
    if (error instanceof RefusedError) return `${accountName(machineId)}'s computer did not take it: ${error.message}. It is handed over again later`
    if (error instanceof MessageError && error.code === 'RELAY_TAKEN') {
      const roster = rosters?.current(sharedTabId)?.roster
      const owner = (roster && accountsIn([roster]).get(roster.owner.accountId)?.name) || 'The shared'
      return `${owner}'s tab is connected elsewhere on this computer: it is handed over once this computer has the tab again`
    }
    return `${accountName(machineId)}'s computer is away: handed over once it is back`
  }

  function setStatuses(entry: Entry, machineId: string, status: Pick<DeliveryStatus, 'state' | 'reason' | 'code'>): void {
    for (const r of entry.message.to.filter((r) => r.machineId === machineId)) {
      if (store.status({ messageId: entry.message.id, machineId, agentId: r.agentId, ...status, at: now() })) tellWindows(entry.message.id)
    }
  }

  /**
   * Whether a hand-over to another account's machine may go now: the shared tab's roster, as this computer holds it,
   * still carries it. One it no longer carries waits HELD_OUTSIDE_MS, as a delivery here does when its tab stops
   * carrying it (`verdict`), and then fails NOT_IN_TAB, never lingering: a member removed while a message to them waited
   * (the plan's Review Focus 2). False while this computer's account is not known: nothing is decided then.
   */
  function carriedNow(outgoing: Outgoing, entry: Entry, sharedTabId: string | null): boolean {
    if (sharedTabId && !account) return false
    const k = `${outgoing.messageId} ${outgoing.machineId}`
    const roster = sharedTabId ? rosters?.current(sharedTabId)?.roster : undefined
    if (roster && carries(roster, entry.message, outgoing.machineId, account!.accountId)) { outboxOutside.delete(k); return true }
    const since = outboxOutside.get(k) ?? now()
    if (now() - since < HELD_OUTSIDE_MS) {
      outboxOutside.set(k, since)
      outgoing.reason = HELD_LEFT_REASON
      setStatuses(entry, outgoing.machineId, { state: 'queued', reason: HELD_LEFT_REASON })
      return false
    }
    outboxOutside.delete(k)
    store.state.outbox = store.state.outbox.filter((o) => o !== outgoing)
    setStatuses(entry, outgoing.machineId, { state: 'failed', code: 'NOT_IN_TAB', reason: LEFT_TAB_REASON })
    saveQuietly()
    return false
  }

  /** Hand what waits in the outbox to its machines: now for one message (`onlyId`, as it is sent) or every one for one
   *  machine (`toMachine`, as a session with it opens), or else every one that is due. */
  async function handOver(onlyId?: string, toMachine?: string): Promise<void> {
    const forced = onlyId !== undefined || toMachine !== undefined
    const looked = store.state.outbox.filter((o) => !handing.has(o) && (onlyId ? o.messageId === onlyId : !toMachine || o.machineId === toMachine))
    let changed = false
    await Promise.all(looked.map(async (outgoing) => {
      const entry = store.entry(outgoing.messageId)
      if (!entry) { store.state.outbox = store.state.outbox.filter((o) => o !== outgoing); changed = true; return }
      const way = route(outgoing.machineId, entry.message, outgoing.sharedTabId)
      if (!way) return
      if (way !== 'relay') {
        if (way.tab && outgoing.sharedTabId !== way.tab) { outgoing.sharedTabId = way.tab; changed = true }
        if (!carriedNow(outgoing, entry, way.tab)) return
      }
      if (!forced && now() < outgoing.nextTryAt) return
      changed = true
      handing.add(outgoing)
      try {
        const answer = way === 'relay'
          ? await rpc(at(outgoing.machineId), { action: 'deliver', message: entry.message }, 10_000)
          : await askTab(way.tab!, outgoing.machineId, { action: 'deliver', message: wireMessage(entry.message, way.tab!) }, 10_000)
        store.state.outbox = store.state.outbox.filter((o) => o !== outgoing)
        applyRemote(outgoing.machineId, answer.statuses)
      } catch (error) {
        // A frame no relay carries is never sent again: it fails, as `harness send` refuses one now.
        if (error instanceof MessageError && error.code === 'TOO_LARGE') {
          store.state.outbox = store.state.outbox.filter((o) => o !== outgoing)
          setStatuses(entry, outgoing.machineId, { state: 'failed', code: 'TOO_LARGE', reason: TOO_LARGE_TEXT })
          return
        }
        outgoing.tries += 1
        outgoing.nextTryAt = now() + Math.min(5 * 60_000, 5_000 * 2 ** Math.min(outgoing.tries, 6))
        outgoing.reason = way !== 'relay' ? tabReason(error, way.tab!, outgoing.machineId)
          : error instanceof MessageError && error.code === 'NO_PEER_LINK' ? 'that machine is not paired with this one' : 'that machine is away: it is handed over once it is back'
        setStatuses(entry, outgoing.machineId, { state: 'queued', reason: outgoing.reason })
      } finally { handing.delete(outgoing) }
    }))
    if (changed) saveQuietly()
  }

  /**
   * What another machine said became of its agents' deliveries. Every way one arrives is kept: a message an agent
   * read with `harness send` came back as a bare "delivered" to the machine that sent it, so its sender never saw
   * that it was read (two machines, 2026-10-12). Only for a recipient of that message on that machine, and its words
   * cleaned: another account's machine answers through a shared tab, and a reason is shown to the person.
   */
  function applyRemote(machineId: string, statuses: unknown): void {
    for (const s of Array.isArray(statuses) ? statuses as Record<string, unknown>[] : []) {
      if (typeof s.messageId !== 'string' || typeof s.agentId !== 'string' || !['queued', 'delivered', 'failed'].includes(String(s.state))) continue
      if (!store.entry(s.messageId)?.message.to.some((r) => r.machineId === machineId && r.agentId === s.agentId)) continue
      const reason = cleanText(s.reason, 300), code = statusCode(s.code)
      const status: DeliveryStatus = { messageId: s.messageId, machineId, agentId: s.agentId, state: s.state as DeliveryStatus['state'],
        ...(s.via === 'hook' || s.via === 'prompt' || s.via === 'read' ? { via: s.via } : {}), ...(reason ? { reason } : {}), ...(code ? { code } : {}), at: now() }
      if (store.status(status)) tellWindows(status.messageId)
    }
  }

  /**
   * Ask other machines what became of this machine's messages still waiting there, each by its route. One waiting on
   * another account's machine that no held tab lists any more cannot be asked: once it has been so for
   * HELD_OUTSIDE_MS it fails NOT_IN_TAB, saying what is not known, rather than wait for good (review of B2).
   */
  async function remoteStatus(): Promise<void> {
    const waiting = new Map<string, { machineId: string; tab?: string; ids: string[] }>()
    let changed = false
    for (const entry of store.state.history) {
      if (entry.message.from.machineId !== self()) continue
      for (const s of [...entry.statuses]) {
        if (s.machineId === self() || s.state !== 'queued' || store.state.outbox.some((o) => o.messageId === entry.message.id && o.machineId === s.machineId)) continue
        const way = route(s.machineId, entry.message)
        if (!way) continue
        // The same key as the outbox's hold: a message is in the outbox or handed over, never both.
        const held = `${entry.message.id} ${s.machineId}`
        if (way !== 'relay' && !way.tab) {
          const since = outboxOutside.get(held) ?? now()
          if (now() - since < HELD_OUTSIDE_MS) { outboxOutside.set(held, since); continue }
          outboxOutside.delete(held)
          if (store.status({ ...s, state: 'failed', code: 'NOT_IN_TAB', reason: LEFT_AFTER_HANDOVER_REASON, at: now() })) { tellWindows(entry.message.id); changed = true }
          continue
        }
        outboxOutside.delete(held)
        const tab = way === 'relay' ? undefined : way.tab!
        const k = `${s.machineId} ${tab ?? ''}`
        const ask = waiting.get(k) ?? { machineId: s.machineId, ...(tab ? { tab } : {}), ids: [] }
        if (!ask.ids.includes(entry.message.id)) ask.ids.push(entry.message.id)
        waiting.set(k, ask)
      }
    }
    await Promise.all([...waiting.values()].map(async ({ machineId, tab, ids }) => {
      const payload = { action: 'status', ids: ids.slice(-200) }
      try { applyRemote(machineId, (tab ? await askTab(tab, machineId, payload, 10_000) : await rpc(at(machineId), payload, 10_000)).statuses) } catch { /* asked again later */ }
    }))
    if (waiting.size || changed) saveQuietly()
  }

  // ── another machine's requests ───────────────────────────────────────────────────────────────────

  /** A hand-over from another of the owner's machines, over the paired relay. */
  async function deliver(payload: Record<string, unknown>): Promise<Record<string, unknown>> {
    const parsed = parseMessage(payload.message)
    if (!parsed) throw new MessageError('INVALID_MESSAGE', 'That is not a message.')
    // This machine's own harnesses send through `send`, which names them by their pane: never as another's.
    if (parsed.from.machineId === self()) throw new MessageError('NOT_FROM_THERE', 'A message from this machine is sent here, not handed over.')
    // Another account's harness speaks only through its shared tab, where the roster says whose it is: over this
    // account's relay it would pass for one of this account's, its header naming whatever account it wrote.
    if (tabsWith(parsed.from.machineId).length) throw new MessageError('NOT_FROM_THERE', 'A message from another account\'s harness comes through its shared tab.')
    const { accountId: _id, account: _name, ...from } = parsed.from
    const message = { ...parsed, from }
    // Off here, it fails below whatever the tabs say: they are not read for it.
    if (directory.on() && !await directory.refresh()) throw new MessageError('DIRECTORY_UNAVAILABLE', 'Harness could not read who is in which tab. It is handed over again later.')
    return acceptHandedOver(message)
  }

  /**
   * A message another machine handed over, for this machine's agents, once its sender is known to be who it says
   * (`deliver`, `deliverFromTab`): each recipient here gets it once, while a tab carries it from the sender (`account`:
   * listed under that account, for another account's sender) and Agent Messages are on here; otherwise it fails at once.
   * Taken again after a lost reply, it is the same delivery, never a second.
   */
  function acceptHandedOver(message: Message, account?: string): Record<string, unknown> {
    if (store.state.local.filter((d) => d.state === 'queued').length >= LIMITS.waiting) {
      throw new MessageError('MAILBOX_FULL', 'Too many messages are waiting on that machine. It is handed over again later.')
    }
    const known = store.entry(message.id)
    if (!known) store.record(message)
    const statuses: DeliveryStatus[] = []
    for (const r of message.to.filter((r) => r.machineId === self())) {
      if (!known && !store.state.local.some((d) => d.messageId === message.id && d.agentId === r.agentId)) {
        // Off here, a hand-over fails at once, as one to an agent outside the sender's tabs does: only what already
        // waits here is held through a switch turned off and on again.
        if (!directory.shared(message.from, r, account)) {
          store.status({ messageId: message.id, machineId: self(), agentId: r.agentId, state: 'failed', reason: directory.on() ? 'it is not in a tab with the sender' : 'Agent Messages are off on its computer', at: now() })
        } else {
          store.status({ messageId: message.id, machineId: self(), agentId: r.agentId, state: 'queued', at: now() })
          mailbox.accept(message, r.agentId)
        }
      }
      const s = store.entry(message.id)!.statuses.find((x) => x.machineId === self() && x.agentId === r.agentId)
      if (s) statuses.push(s)
    }
    saveQuietly()
    tellWindows(message.id)
    return { statuses }
  }

  /**
   * Another account's machine's request, through a tab shared with this account (sharedTabs.ts `answer`): only
   * `deliver`, `status` and `who`, each against the tab's roster as this computer holds it and the relay's stamp.
   */
  async function answerTab(ctx: TabContext, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
    const roster = rosters?.current(ctx.sharedTabId)?.roster
    if (!roster) throw new MessageError('NOT_SHARED', 'This computer holds no such shared tab.')
    const me = await signedInAs()
    switch (payload.action) {
      case 'deliver': return deliverFromTab(ctx, roster, me.accountId, payload)
      // Only what that machine sent: what became of anyone else's messages is not its to know.
      case 'status': return statusOf(payload, ctx.from.machineId)
      // Only this machine's harnesses the tab lists under this account, and in another account's tab only those this
      // machine asked for (consentStore.ts): an unshared one, or one taken out, is never named to another account.
      // Another account's machine says its harnesses work, to the windows (tabActivity.ts): not a message, so never counted
      // toward the limits, and bounded by the pace `take` keeps.
      case 'activity': {
        const listed = (agentId: string) => roster.harnesses.some((h) => h.machineId === ctx.from.machineId && h.agentId === agentId)
        for (const a of activityIn.take(ctx.sharedTabId, ctx.from.machineId, payload.agents, listed, now())) {
          core.clients.windows({ type: SHARED_ACTIVITY_WINDOW_FRAME, payload: { ...a } })
        }
        return { ok: true }
      }
      case 'who': return whoAre(payload, (agentId) => roster.harnesses.some((h) => h.machineId === self() && h.agentId === agentId && h.accountId === me.accountId)
        && (roster.owner.accountId === me.accountId || consented(ctx.sharedTabId, agentId)), false)
      default: throw new MessageError('UNKNOWN_ACTION', 'Unknown Agent Messages request.')
    }
  }

  /**
   * A message another account's harness handed over through a shared tab. Refused before anything reaches a pane when
   * the roster does not list its sender under the account the relay stamped, or lists a recipient here under another
   * account (tabDelivery.ts `checkHandedOver`, the plan's Review Focus 3); over the tab's limits, failed RATE_LIMITED.
   * On the account that shares the tab, logged under the desk tab it is shared from, as its windows show it.
   */
  async function deliverFromTab(ctx: TabContext, roster: Roster, accountId: string, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
    const parsed = parseMessage(payload.message)
    if (!parsed) throw new MessageError('INVALID_MESSAGE', 'That is not a message.')
    const checked = checkHandedOver(roster, ctx, parsed, { accountId, machineId: self(), machineName, consented: (agentId) => consented(ctx.sharedTabId, agentId) })
    // A recipient this machine never put in the tab, or took out of it, is failed for good: the sender's roster may list
    // it for as long as the owner does, and tried again it would be refused every time.
    if ('refused' in checked) {
      if (checked.code) return failAll(parsed, checked.code, checked.refused)
      throw new MessageError('REFUSED', checked.refused)
    }
    let message = checked.message
    if (roster.owner.accountId === accountId) {
      const desk = shared?.deskTab(ctx.sharedTabId)
      if (!desk) throw new MessageError('DIRECTORY_UNAVAILABLE', 'Harness has not read which tab this is shared from yet. It is handed over again later.')
      message = { ...message, tabId: desk }
    }
    const known = store.entry(message.id)
    // An id another sender's message holds here is not this one's: answering would tell what became of that message.
    if (known && (known.message.from.machineId !== message.from.machineId || known.message.from.agentId !== message.from.agentId)) {
      throw new MessageError('REFUSED', 'that message id is another message\'s')
    }
    if (directory.on() && !await directory.refresh()) throw new MessageError('DIRECTORY_UNAVAILABLE', 'Harness could not read who is in which tab. It is handed over again later.')
    // Counted once per message, after the last wait: a hand-over repeated after a lost reply is not another message.
    if (!store.entry(message.id)) {
      const limited = overTabLimit(ctx, message)
      if (limited) return failAll(message, 'RATE_LIMITED', limited)
    }
    return acceptHandedOver(message, ctx.from.userId)
  }

  /** Why a message through a shared tab is over the tab's limits on this side, or null, counting it when it is not. */
  function overTabLimit(ctx: TabContext, message: Message): string | null {
    const sender = `${ctx.sharedTabId} ${message.from.machineId}/${message.from.agentId}`
    if (!senderTaken.room(sender, LIMITS.perSender, LIMITS.window, now())) return `its sender sent ${LIMITS.perSender} messages in 10 minutes`
    if (!tabTaken.room(ctx.sharedTabId, LIMITS.perTab, LIMITS.window, now())) return `its shared tab carried ${LIMITS.perTab} messages in 10 minutes`
    senderTaken.take(sender, LIMITS.perSender, LIMITS.window, now())
    tabTaken.take(ctx.sharedTabId, LIMITS.perTab, LIMITS.window, now())
    return null
  }

  /**
   * Every recipient here failed, as the answer, with nothing kept: a message over a limit is never written to the log
   * or the disk, or a listed member flooding the tab would push this computer's real history out of it (review of B2).
   * Handed over again, it is checked again.
   */
  function failAll(message: Message, code: string, reason: string): Record<string, unknown> {
    return { statuses: message.to.filter((r) => r.machineId === self()).map((r) => ({ messageId: message.id, machineId: self(), agentId: r.agentId, state: 'failed', code, reason, at: now() })) }
  }

  /** What became of messages here, for the machine that asks: with `from`, only the messages that machine sent. */
  function statusOf(payload: Record<string, unknown>, from?: string): Record<string, unknown> {
    const ids = Array.isArray(payload.ids) ? payload.ids.filter((id): id is string => typeof id === 'string').slice(0, 200) : []
    return { statuses: ids.flatMap((id) => {
      const entry = store.entry(id)
      return entry && (!from || entry.message.from.machineId === from) ? entry.statuses.filter((s) => s.machineId === self()) : []
    }) }
  }

  /** This machine's agents' names, for the machine that asks (`ownMachine`: one of the account's own, which is also told each
   *  harness's state and summary; another account's never is, it has `activity` for what it may know): with `listed`, only those it may name. A harness in a
   *  shared tab's branch too, for that tab's note on the asking machine; no Git runs for any other. */
  async function whoAre(payload: Record<string, unknown>, listed: (agentId: string) => boolean = () => true, ownMachine = true): Promise<Record<string, unknown>> {
    const ids = Array.isArray(payload.agentIds) ? payload.agentIds.filter((id): id is string => typeof id === 'string').slice(0, 64) : []
    const sessions = ids.filter(listed).flatMap((agentId) => { const session = localAgent(agentId); return session ? [session] : [] })
    const shared = new Set(sessions.filter((s) => s.cwd && inSharedTab({ machineId: self(), agentId: s.agentId })).map((s) => s.cwd!))
    const [, now] = await Promise.all([readBranches([...shared]), ownMachine ? activityNow(sessions.map((s) => s.agentId), true) : Promise.resolve<Record<string, ActivityNow>>({})])
    return { agents: sessions.map((session) => {
      const branch = session.cwd && shared.has(session.cwd) ? branches.get(session.cwd)?.branch : undefined
      return { agentId: session.agentId, name: core.agents.displayName(session) || session.agentId.slice(0, 8), engine: session.engine,
        ...(session.cwd ? { project: basename(session.cwd) } : {}), ...(branch ? { branch } : {}), ...(ownMachine ? now[session.agentId] ?? { state: 'unknown' } : {}) }
    }) }
  }

  /** What this machine's harnesses are doing now, as its core says: their state and, unless it is to be kept back, one
   *  line on what each does: only for the agents the core reports (it reports none that is not live). */
  async function activityNow(agentIds: string[], withSummary: boolean): Promise<Record<string, ActivityNow>> {
    if (!agentIds.length) return {}
    const [states, lines] = await Promise.all([core.agents.activity(agentIds), withSummary ? core.agents.summaries(agentIds) : Promise.resolve<Record<string, string>>({})])
    return Object.fromEntries(Object.entries(states).map(([agentId, state]) => [agentId, { state, ...(lines[agentId] ? { summary: lines[agentId] } : {}) }]))
  }

  /**
   * Every harness of one of this account's desk tabs, shared or not, with what it does now (`tab_activity`, the sidebar's
   * rows): this machine's from the core; the account's other machines' by `who`, which they answer with state and summary,
   * `away` for one that does not answer within WHO_WAIT_MS; other accounts' from what their machines told
   * (tabActivity.ts), for a tab shared with them. Nothing here needs shared tabs to be running.
   */
  async function tabActivity(tabId: string): Promise<Record<string, unknown>> {
    if (!messagingOn()) throw new MessageError('MESSAGES_OFF', MESSAGES_OFF_TEXT)
    const me = await signedInAs()
    const onDesk = (): DirectoryTab | undefined => directory.current()?.tabs.find((t) => t.id === tabId)
    // A tab it does not know may be new: the desk is read again for it, but not more than once in MISSED_TAB_READ_MS, so ids a window
    // makes up cannot drive reads of the backend.
    if (!onDesk() && now() - missedTabAt >= MISSED_TAB_READ_MS) { missedTabAt = now(); await directory.refresh() }
    const tab = onDesk()
    if (!tab) throw new MessageError('NOT_A_TAB', 'That tab is not on your desk.')
    const foreign = (m: Member): boolean => !!m.accountId && m.accountId !== me.accountId
    const byMachine = new Map<string, string[]>()
    for (const m of tab.panes.filter((p) => !foreign(p))) byMachine.set(m.machineId, [...(byMachine.get(m.machineId) ?? []), m.agentId])
    const known = new Map<string, ActivityNow & { away?: true }>()
    await Promise.all([...byMachine].map(async ([machineId, agentIds]) => {
      if (machineId === self()) {
        const now = await activityNow(agentIds, true)
        for (const agentId of agentIds) known.set(`${machineId} ${agentId}`, now[agentId] ?? { state: 'unknown' })
        return
      }
      const answer = await within(rpc(at(machineId), { action: 'who', agentIds }, WHO_WAIT_MS), WHO_WAIT_MS)
      // An answer that names no state is a daemon from before them: its harnesses are not away, only not known.
      const heard = new Map((Array.isArray(answer?.agents) ? answer.agents as Record<string, unknown>[] : []).map((a) => [a.agentId, a]))
      for (const agentId of agentIds) {
        const a = heard.get(agentId)
        const summary = cleanSummary(a?.summary)
        known.set(`${machineId} ${agentId}`, { state: ACTIVITY_STATES.has(a?.state as ActivityState) ? a!.state as ActivityState : 'unknown',
          ...(summary ? { summary } : {}), ...(answer ? {} : { away: true as const }) })
      }
    }))
    return { harnesses: tab.panes.map((m) => ({ machineId: m.machineId, agentId: m.agentId,
      ...(foreign(m) ? (tab.sharedTabId ? activityIn.of(tab.sharedTabId, m.machineId, m.agentId, now()) : undefined) ?? { state: 'unknown' }
        : known.get(`${m.machineId} ${m.agentId}`)) })) }
  }

  function history(payload: Record<string, unknown>): Record<string, unknown> {
    const tabId = typeof payload.tabId === 'string' ? payload.tabId : null
    const limit = typeof payload.limit === 'number' && payload.limit > 0 ? Math.min(payload.limit, LIMITS.history) : 200
    const entries = store.state.history.filter((e) => !tabId || e.message.tabId === tabId)
    return { messages: entries.slice(-limit).map((e) => ({ ...e.message, statuses: e.statuses })) }
  }

  /**
   * Inbox files nothing here is waiting to deliver, from a service that stopped or a daemon long gone (the inboxes
   * are every daemon's on this computer): removed once they are old enough not to be another live daemon's
   * delivery in the making, which that daemon puts back anyway.
   */
  function sweep(): void {
    const ours = new Set([
      ...store.state.local.filter((d) => d.state === 'queued' && d.pane).map((d) => `${d.pane}/${d.key}`),
      ...Object.values(store.state.notes).map((n) => `${n.pane}/${n.key}`),
    ])
    for (const entry of inbox.entries()) {
      if (!ours.has(`${entry.pane}/${entry.key}`) && now() - entry.at > SWEEP_AFTER_MS) inbox.withdraw(entry.pane, entry.key)
    }
  }

  function saveQuietly(): void {
    try { store.save() } catch { /* kept in memory; the next change saves again */ }
  }

  // ── tabs shared with other accounts ──────────────────────────────────────────────────────────────

  /** The shared tabs this computer holds, read from its file once it first wakes; null until then, or when the file
   *  cannot be read, which leaves shared tabs unavailable and Agent Messages as they were. */
  let rosters: RosterStore | null = null
  /** The harnesses this account asked to have in a shared tab, from this machine (consentStore.ts), which Share reads. */
  let consent: ConsentStore | null = null
  /** The notices the person has not dismissed (noticeStore.ts), kept across sleep with the same writer. */
  let notices: NoticeStore | null = null
  /** Whether this machine asked for one of its harnesses in a tab (consentStore.ts). */
  const consented = (sharedTabId: string, agentId: string): boolean => !!consent?.keys().has(consentKey(sharedTabId, self(), agentId))
  /** Shared tabs, while awake only: asleep, no relay socket stays open and nothing about them runs. */
  let shared: SharedTabs | null = null
  let sharesRev = 0
  let sharesTimer: ReturnType<typeof setTimeout> | null = null
  let stopFrames: (() => void) | null = null
  let account: { accountId: string; email: string } | null = null
  const machineKeys = new Map<string, { pub: string; at: number }>()

  /** The account signed in here, as the core says it (`core.account.identity`): a sign-in to another account starts a
   *  new daemon, so it is asked once. Never read from the backend here: in its process this service may call only the
   *  routes the core allows it (core/api.ts `MESSAGES_BACKEND_ROUTES`). */
  async function signedInAs(): Promise<{ machineId: string; accountId: string; email: string }> {
    account ??= await core.account.identity()
    if (!account) throw new MessageError('ACCOUNT_UNAVAILABLE', 'Harness could not read which account this computer is signed in to. Try again in a moment.')
    return { machineId: self(), accountId: account.accountId, email: account.email }
  }

  /** An `agent_messages` request to another machine of this account, over the paired relay (an authenticated
   *  channel): its answer; its refusal as `{ error: { code, message } }`, for the person to be told what that machine
   *  said; null when it cannot be asked. A forwarded add that machine refused was told as a machine away (review of
   *  A1, 2026-10-15). */
  async function askMachine(machineId: string, payload: Record<string, unknown>): Promise<Record<string, unknown> | null> {
    try { return await rpc(at(machineId), payload, 8_000) } catch (error) {
      return error instanceof RefusedError ? { error: { code: error.code, message: error.message } } : null
    }
  }

  /** A machine of this account's key for a shared tab's roster: this one's from the gateway, another's as that machine
   *  reports it (`tab_pub`); null when it cannot be asked. */
  async function machineKey(machineId: string): Promise<string | null> {
    if (machineId === self()) return core.account.tabKey.publicKey().catch(() => null)
    const known = machineKeys.get(machineId)
    if (known && now() - known.at < MACHINE_KEY_MS) return known.pub
    const answer = await askMachine(machineId, { action: 'tab_pub' })
    if (typeof answer?.pub !== 'string') return null
    machineKeys.set(machineId, { pub: answer.pub, at: now() })
    return answer.pub
  }

  /** This account's machines, as its directory lists them; null while it cannot be read. */
  async function ownMachines(): Promise<string[] | null> {
    const read = await directory.refresh()
    return read && [...read.machines.keys()]
  }

  /** The leader the account's tab setting names for a desk tab, as the directory lists it (null for none, or one that may
   *  lead it no more). Undefined before the tabs were first read (a failed read keeps the last good listing), from a
   *  backend that lists no setting, or for a tab the listing does not have: the roster this computer signs then keeps its
   *  own leader (sharedTabs.ts `ownLeader`). */
  async function ownLeader(tabId: string): Promise<{ machineId: string; agentId: string } | null | undefined> {
    return (await directory.refresh())?.tabs.find((t) => t.id === tabId)?.leader
  }

  /**
   * The directory changed: when it lists, for a tab this computer shares, another leader than the roster it holds names,
   * the shares are read again, and that signs the setting's leader (sharedTabs.ts `reshare`). The `desk_changed` the
   * setting's change causes does this already; this catches one this computer missed (its socket was down as it was
   * sent), at the next read of the tabs, so the members are not left with the old leader until something else changes.
   */
  function followLeaders(): void {
    if (!shared || !rosters) return
    const held = rosters
    const behind = (directory.current()?.tabs ?? []).some((t) => {
      const roster = t.sharedTabId && t.leader !== undefined ? held.current(t.sharedTabId)?.roster : undefined
      return !!roster && roster.owner.machineId === self()
        && (roster.leader?.machineId !== t.leader?.machineId || roster.leader?.agentId !== t.leader?.agentId)
    })
    if (behind) void shared.refresh().catch(() => {})
  }

  /** The owner's panes in a desk tab, named as its teammates see them; null while the tabs cannot be read. */
  async function ownPanes(tabId: string): Promise<Array<{ machineId: string; agentId: string; name: string; engine: string }> | null> {
    const tabs = await directory.refresh()
    if (!tabs) return null
    // Only the desk's own panes: the members' harnesses merged into the tab (sharedDirectory.ts) are theirs to add.
    const panes = (tabs.tabs.find((t) => t.id === tabId)?.panes ?? []).filter((p) => !p.accountId)
    await learnNames(panes, true)
    return panes.map((m) => { const t = teammate(m); return { machineId: m.machineId, agentId: m.agentId, name: t.name, engine: t.engine } })
  }

  /**
   * This computer's harnesses in each held tab, as working or not, to the tab's machines of other accounts; a peer
   * that does not know `activity` (a 1b daemon) is left alone for a while (tabActivity.ts).
   */
  async function shareActivity(): Promise<void> {
    if (!shared || !rosters) return
    const held = rosters.all()
    if (!held.length) return
    const me = await signedInAs().catch(() => null)
    if (!me) return
    for (const roster of held) {
      // The same harnesses `who` names: this account's here, and in another account's tab only those this machine asked for.
      const mine = roster.harnesses.filter((h) => h.machineId === self() && h.accountId === me.accountId
        && (roster.owner.accountId === me.accountId || consented(roster.sharedTabId, h.agentId)))
      const peers = [...new Set([...roster.harnesses.filter((h) => h.accountId !== me.accountId).map((h) => h.machineId),
        ...(roster.owner.accountId !== me.accountId ? [roster.owner.machineId] : [])])]
      if (!mine.length || !peers.length) continue
      // The account may keep the summary from other accounts: then it is not even read, and one sent before is replaced.
      const agents = activityOut.due(roster.sharedTabId, now(), await activityNow(mine.map((h) => h.agentId), !summaryHidden()))
      if (!agents.length) continue
      await Promise.all(peers.filter((m) => !activityOut.refusing(roster.sharedTabId, m, now())).map(async (machineId) => {
        try { await askTab(roster.sharedTabId, machineId, { action: 'activity', sharedTabId: roster.sharedTabId, agents }, 5_000) }
        catch (error) { if (error instanceof RefusedError && error.code === 'UNKNOWN_ACTION') activityOut.refused(roster.sharedTabId, machineId, now()) }
      }))
    }
  }

  /** The windows' `shared_tabs_changed`, once for a burst of changes: a refresh that takes a roster, alerts and announces
   *  sends one frame, not three. */
  function tellShares(): void {
    // Nothing is told while shared tabs are down: the rosters file outlives sleep, but the windows read `shares` as it wakes.
    if (!shared || sharesTimer) return
    sharesTimer = setTimeout(() => {
      sharesTimer = null
      core.clients.windows({ type: SHARED_TABS_WINDOW_FRAME, payload: { rev: ++sharesRev } })
    }, SHARES_COALESCE_MS)
    sharesTimer.unref?.()
  }

  function sharedUp(): void {
    if (shared) return
    // Each roster saved: the consent follows what the rosters list (a harness the owner took out needs asking again),
    // and Share derives its observers again from both. The consent changed, the directory is merged again: a harness
    // taken out leaves another account's tab here at once (sharedDirectory.ts), its note and its deliveries with it.
    try {
      // One writer for the file, kept across sleep: a closed SharedTabs that still adds a notice must not write a stale list over the new one's.
      notices ??= new NoticeStore(join(stateDir, 'shared-tabs-notices.json'), now)
      consent ??= new ConsentStore(join(stateDir, 'shared-tabs-consent.json'), now, () => { options.observers?.(); directory.rebuild() })
      rosters ??= new RosterStore(join(stateDir, 'shared-tabs.json'), now, (kind) => {
        if (kind === 'tabs') {
          if (rosters) consent?.reconcile((id) => rosters?.current(id)?.roster ?? null)
          // A tab left, removed or revoked takes what was sent and heard for it.
          const held = new Set((rosters?.all() ?? []).map((r) => r.sharedTabId))
          activityOut.prune(held)
          activityIn.prune(held)
          options.observers?.()
        }
        tellShares()
      })
    } catch { return }
    const tabs = new SharedTabs({ key: core.account.tabKey, relay: core.account.tabRelay, store: rosters,
      backend: (method, path, body) => core.account.backend(method, path, body), self: signedInAs, ownPanes, ownLeader, machineKey, askMachine, ownMachines, consent,
      requests: new RequestStore(join(stateDir, 'shared-tabs-requests.json'), now), changed: () => directory.rebuild(),
      ...(notices ? { notices } : {}), announce: tellShares, answer: answerTab,
      // A session with another account's machine opened: what waits for it goes now, not at its next try.
      opened: (_id, machineId) => { void handOver(undefined, machineId) }, now })
    shared = tabs
    stopFrames = options.onTabFrame?.((event) => { void tabs.onFrame(event).catch(() => {}) }) ?? null
    // Read once as it wakes, even holding no tab: a computer that was away when the person accepted a tab on another of
    // their computers missed that one's word (`tab_pin_changed`), and would otherwise take the pin only at the next
    // unrelated `desk_changed` (review of A2, 2026-10-15). One read, and no timer while nothing is held.
    void tabs.refresh().catch(() => {})
  }

  /** Read the shares again and open every held tab's relay, for a new core while awake. A computer that holds no tab
   *  reads nothing more for them: the next `desk_changed` would tell it. */
  function refreshShared(): void {
    if (shared && rosters?.all().length) void shared.refresh().catch(() => {})
  }

  function sharedDown(): void {
    // Down first: closing saves the rosters, and a save while asleep must not arm the windows' timer again.
    const tabs = shared
    shared = null
    if (sharesTimer) clearTimeout(sharesTimer)
    sharesTimer = null
    stopFrames?.()
    stopFrames = null
    tabs?.close()
  }

  /** Shared tabs, for a request: only while awake, and with their file read. */
  function awakeShares(): { shared: SharedTabs; rosters: RosterStore } {
    if (!messagingOn() || mode !== 'awake') throw new MessageError('MESSAGES_OFF', MESSAGES_OFF_TEXT)
    if (!shared || !rosters) throw new MessageError('SHARES_UNAVAILABLE', 'The shared tabs file on this computer could not be read.')
    return { shared, rosters }
  }

  async function shareAction(payload: Record<string, unknown>): Promise<Record<string, unknown>> {
    const { shared, rosters } = awakeShares()
    // The account first, for every action: each one acts as it, or reads what only it may (sharedTabs.ts `self`). Asked
    // first, a core from before shared tabs is told as the restart it needs (services/messagesProcess.ts), not as the
    // backend or a route that core refuses, which differ from one action to the next.
    await signedInAs()
    switch (payload.action) {
      case 'share_tab': return shared.share(String(payload.tabId), String(payload.name ?? ''))
      case 'share_invite': return shared.invite(String(payload.sharedTabId), payload.emails as string[], payload.days as 7 | 30 | 90)
      case 'share_revoke': return shared.revoke(String(payload.inviteId)).then(() => ({ ok: true }))
      case 'share_accept': return shared.accept(String(payload.inviteId), typeof payload.ownerPub === 'string' ? payload.ownerPub : undefined)
      case 'share_add': return shared.addHarness(String(payload.sharedTabId), payload.harness as { machineId: string; agentId: string; name: string; engine: string }, payload.forwarded === true)
      case 'share_remove': return shared.removeHarness(String(payload.sharedTabId), String(payload.machineId), String(payload.agentId), payload.forwarded === true)
      // Written to the owner's tab setting, from any computer of the account; the computer that shares the tab signs it.
      case 'share_leader': return shared.setLeader(String(payload.sharedTabId), (payload.leader ?? null) as { machineId: string; agentId: string } | null).then(() => ({ ok: true }))
      case 'share_remove_member': return shared.removeMember(String(payload.sharedTabId), String(payload.accountId)).then(() => ({ ok: true }))
      case 'share_notice_dismiss': {
        const id = String(payload.id ?? '')
        if (shared.dismissNotice(id) || rosters.dismiss(id)) return { ok: true }
        throw new MessageError('NOT_FOUND', 'That notice is already gone.')
      }
      case 'share_leave': return shared.leave(String(payload.sharedTabId)).then(() => ({ ok: true }))
      case 'share_stop': return shared.stop(String(payload.sharedTabId)).then(() => ({ ok: true }))
      // The tab's authority moves to this computer, with a key change the old one signs when it can be asked.
      case 'share_move': return shared.move(String(payload.sharedTabId))
      // Trust a tab's owner again without a new invitation: the check shows the fingerprint, the confirm pins that key.
      case 'share_retrust_check': return shared.retrustOffer(String(payload.sharedTabId))
      // The tasks of a tab this computer holds, found with this computer's own `gh` login (tasks.ts).
      // `tabId`: a desk tab of this account, shared or not (`tasksOfTab`); `sharedTabId`: a held one. Both: the shared tab's own
      // id wins, as the one a roster names; a desk id beside it is only the window's hint.
      case 'share_tasks': return (payload.sharedTabId === undefined && typeof payload.tabId === 'string' ? tasksOfTab(payload.tabId) : tasksOf(String(payload.sharedTabId))).then((result) => ({ ...result }))
      // Each harness of a held tab with its repo and branch, for People (sharedWho).
      case 'share_who': return sharedWho(String(payload.sharedTabId))
      case 'share_retrust': return shared.retrust(String(payload.sharedTabId), typeof payload.ownerPub === 'string' ? payload.ownerPub : '')
      default: /* shares */ {
        const me = await signedInAs()
        // `api: 2` tells a window this daemon sends `shared_tabs_changed`; `tabId` is the desk tab of a roster this account owns.
        const invites = await shared.invites(), untrusted = await shared.untrusted()
        // `pendingInvites` carries the ids that revoke an invitation, which only the owner's shares list.
        return { api: 2, version: VERSION, me: { accountId: me.accountId, email: me.email, machineId: me.machineId },
          rosters: shared.rosters().map((r) => {
            const own = r.owner.accountId === me.accountId
            return { ...r, tabId: own ? shared.deskTab(r.sharedTabId) : null, pendingInvites: own ? shared.pendingInvites(r.sharedTabId) : [] }
          }),
          invites, alerts: rosters.alerts(), pending: shared.pending(), notices: shared.notices(), untrusted, activity: activityIn.snapshot(now()) }
      }
    }
  }

  const stopHearing = core.turns.onDelivery((event: TurnDelivery) => mailbox.observe(event))
  // Asleep, a changed desk is read when it wakes, not now. Shared tabs read theirs after the desk, whose panes they take.
  // A machine created, renamed or deleted changes the panes and names the directory lists, as a changed desk does.
  const stopNotices = core.account.onNotice((notice) => {
    if ((notice.type === 'desk_changed' || notice.type === 'machines_changed') && !asleep()) {
      void directory.refresh(true).then(() => shared?.refresh()).catch(() => {})
    }
  })

  // Started only as it wakes, when it is stopped: never twice.
  const startTick = (): void => {
    timer = setInterval(() => {
      notesPump()
      void shareActivity().catch(() => {})
      void handOver()
      if (now() - lastRemoteStatus >= REMOTE_STATUS_MS) { lastRemoteStatus = now(); void remoteStatus() }
    }, TICK_MS)
    timer.unref?.()
  }
  const stopTick = (): void => {
    if (timer) clearInterval(timer)
    timer = null
  }

  /**
   * Run what this computer calls for now: everything while it is signed in with Agent Messages on; while they are off,
   * the notes withdrawn, what waits held and then failed by the mailbox's look, which stops once nothing waits, and
   * a watch on the setting's file to wake it; signed out, nothing. Every computer runs this service: one with it off,
   * or never signed in, paid a read of the account's tabs every 15 s and three timers for messages it could never
   * carry (2026-10-12).
   */
  function wake(): void {
    if (!running) return
    const next = !core.account.signedIn() ? 'signedOut' : readSetting() ? 'awake' : 'off'
    if (next === mode) return
    // The switch turned on or off here while this computer holds a shared tab: Share grants or takes back the tabs'
    // views at once (it reads the same switch), not at its next 30 s look. Never at start, nor without a tab: that
    // would start Share's process on every computer.
    const flipped = (mode === 'awake' && next === 'off') || (mode === 'off' && next === 'awake')
    const tellShare = (): void => { if (flipped && rosters?.all().length) options.observers?.() }
    mode = next
    if (next === 'awake') {
      unwatch?.()
      unwatch = null
      directory.start()
      // The account names an unshared tab's key in its agents' notes: they are looked at again once it is known.
      void signedInAs().then(() => notesPump(), () => {})
      mailbox.resume()
      startTick()
      sharedUp()
      tellShare()
      return
    }
    directory.stop()
    stopTick()
    sharedDown()
    tellShare()
    if (next === 'signedOut') {
      unwatch?.()
      unwatch = null
      mailbox.pause()
      return
    }
    // Never watching yet: it was awake, signed out or not running, and none of those watches.
    unwatch = (options.watchSetting ?? watchSettingFile)(settingsFile, later)
    mailbox.refuseAll()
    notesPump()
    // The mailbox looks on only while something here waits to be held and then failed; it stops itself after.
    if (mailbox.waiting()) mailbox.resume()
    else mailbox.pause()
  }

  return {
    requests: {
      agent_messages: (payload, asker) => Promise.resolve().then(async () => {
        if (!asker.owner) throw new MessageError('OWNER_REQUIRED', 'Agent Messages answer only the owner.')
        // A pane is only this machine's to name; a hand-over, its status and its names are another machine's
        // daemon's to ask, over the relay, never a process here's.
        const fromHere = ['send'].includes(String(payload.action))
        if (['send', 'deliver', 'status', 'who', 'started', 'tab_pub', 'tab_pin', 'tab_pin_changed', 'tab_keychange'].includes(String(payload.action)) && asker.local !== fromHere) {
          throw new MessageError(fromHere ? 'LOCAL_ONLY' : 'REMOTE_ONLY', fromHere ? 'harness send runs in a pane on this machine.' : 'Only another of your machines hands messages over.')
        }
        // The person's own windows, here or over the relay, manage shared tabs; another of the owner's machines asks
        // only `share_add` and `share_remove`, for a harness of this one, marked `forwarded` (sharedTabs.ts `addHarness`,
        // `removeHarness`).
        if (SHARE_ACTIONS.includes(String(payload.action))) return shareAction(payload)
        switch (payload.action) {
          case 'send': return send(payload)
          case 'deliver': return deliver(payload)
          case 'status': return statusOf(payload)
          case 'who': return whoAre(payload)
          case 'started': return started(payload)
          // From a pane here, or another of the owner's machines over the relay: `tell` tells them apart.
          case 'tell': return tell(payload, asker.local)
          // A program acting for the person, here or on another of the owner's machines (replyLocal.ts).
          case 'reply_local': return replyLocal(payload)
          case 'history': return history(payload)
          // The windows' sidebar: every harness of a desk tab, shared or not, with its state and one line on what it does.
          case 'tab_activity': return tabActivity(String(payload.tabId))
          case 'tab_pub': return { pub: await core.account.tabKey.publicKey() }
          // Only another machine of this account: the same trust as `tab_pub` (sharedTabs.ts `pull`).
          case 'tab_pin': return awakeShares().shared.pinOf(String(payload.sharedTabId))
          case 'tab_pin_changed': return awakeShares().shared.pinChanged(String(payload.sharedTabId)).then(() => ({ ok: true }))
          // Only another machine of this account, and answered only by the computer the tab is shared from: a window or a
          // process here never has this machine sign a key over to another (sharedTabs.ts `keyChange`).
          case 'tab_keychange': return awakeShares().shared.keyChange(String(payload.sharedTabId), payload.nextPub, payload.machineId)
          default: throw new MessageError('UNKNOWN_ACTION', 'Unknown Agent Messages request.')
        }
      }).catch((error: unknown) => (error instanceof MessageError
        ? { error: error.code, detail: error.message }
        : { error: 'MESSAGES_UNAVAILABLE', detail: 'Agent Messages are unavailable right now. Nothing was sent.' })),
    },
    canWrite: (deliveryId) => mailbox.canWrite(deliveryId),
    reconnected: () => {
      mailbox.takeBackAttempts()
      const was = mode
      wake()
      // The relay sockets were the old core's gateway's: a new one has none, and waking again (the mode unchanged)
      // would not open them. Waking from asleep has just done so.
      if (was === 'awake' && mode === 'awake') refreshShared()
    },
    settingsChanged: later,
    start: () => {
      running = true
      mailbox.start()
      sweep()
      wake()
    },
    stop: () => {
      running = false
      mode = null
      unwatch?.()
      unwatch = null
      stopTick()
      stopHearing()
      stopNotices()
      sharedDown()
      mailbox.stop()
      directory.stop()
    },
  }
}