Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

81.7 KB
Raw Blame
/** `harness super-tab route GROUP JSON`: any agent's routing step (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md).
 * Reads the tab, the model catalog and the account's machines; probes each machine once per engine with the same admission
 * `start` uses; leaves out what cannot run and lists the rest by machine with their facts and what else it knows as notes
 * (docs/plans/2026-10-30-project-instructions-design.md, Routing), ranking none and naming no pick (task #2901); and records
 * the decision in the tab. */
import { randomUUID } from 'node:crypto'
import { openDaemon, type Daemon, type Where } from '../agentClient/daemon.js'
import { requiredToolReason, startRequirements, USED_UP_WINDOW } from './capacity.js'
import { START_DEADLINE_MS, START_WINDOW_MS } from './reservations.js'
import { inspectCapacity, type ScopedRequest } from './start.js'
import { ENDED_WORK, object, within } from './wire.js'
import { withPmAccounts } from './pmAccounts.js'
import { accountOf, API_BUILDERS, bytes, machineBrief, catalogFrom, catalogRow, choose, decideByOrder, gridStrength, parseAssessment, OLD_RECORD_MAX, quotaBrief, quotaLine, quotaOf2, recentStartNotes, UNRATED, recordOf, repoMatch, repositoryKey, type Assessment, type Catalog, type CatalogModel, type RecordShape, type Commitment, type Excluded, type Shown, type HeldModel, type MemberFrame, type Probe, type TaskFolder } from './route.js'
import { pickByOrder } from './routePick.js'
import { firstMachines, machineRuleRefusal } from './machineRules.js'
import { makePlugins, ROUTE_PLUGIN_MAKERS, type PluginMaker } from './routePlugins.js'
import { CI_HOLD_OPENING, CI_RETRY_MINUTES, heavyOfStart, MACHINE_FIT_MAKER } from './machineFit.js'
import { stat } from 'node:fs/promises'
import { describeScmProject } from '../scm/scmProjects.js'

type Json = Record<string, unknown>
const ENGINES = ['claude', 'codex']
// Only these say the request never reached a decision; any other refusal (RATE_LIMITED, validation) is the answer and must
// reach the agent that routed.
const TRANSPORT = new Set(['AGENT_UNAVAILABLE', 'SUPER_TAB_UNAVAILABLE', 'BACKEND_UNAVAILABLE', 'BACKEND_TIMEOUT', 'BACKEND_UNREACHABLE'])
const MACHINES_UNREADABLE = "The account's machine list could not be read; only known machines were considered."
/** An unreadable catalog reads as an empty one (route.ts catalogFrom), which offers no new agent: said, never silent (final review). */
/** The project's machine rules could not be read (task #3964): the route applies none, so the PM still does. */
export const MACHINE_RULES_UNREAD = 'The project\'s machine rules could not be read: the instructions\' Machines rules still apply, and a pick that breaks one is not used.'
export const CATALOG_UNREADABLE = 'The model catalog could not be read, or lists no models: no new agent on Claude Code or Codex is offered, only agents already in the Swarm and models served on its grid.'
const DISK_UNVERIFIED = 'Project disk space could not be verified.'
const NO_PROJECT_FOLDER = 'This machine does not have the project folder. Add it to the Swarm so it can clone the project.'
export const OFFLINE = 'Machine is offline or unreachable.'
const UNKNOWN_QUOTA: Probe['quota'] = { known: false, leftPercent: null, resetsAt: null }
const UNKNOWN_LOAD: NonNullable<Probe['load']> = { agents: null, freeMemoryBytes: null, hasFolder: null }
/** Quota is information, not a gate: a used-up window is said on the candidate, which still runs (capacity.ts). */
const usedUp = (quota: Probe['quota']) => quota.leftPercent === 0 ? [USED_UP_WINDOW] : []
/** The operating systems a Swarm agent is not started on, compared with the OS every reading has (lib/machineHardware.ts
 *  names it `Windows`). Windows was here from 2026-10-26 (Scholes): grid's CLI did not run there, so WIN-DELL took starts
 *  that silently never ran — a held start ran grid's installer every 2 seconds instead. Lifted once grid 0.3.61 and CLI
 *  0.4.95 ran there: a Claude Code agent on a grid model started and answered on DESKTOP-0TFH0OJ (2026-10-28). */
export const NO_SWARM_AGENTS_ON: readonly string[] = []
const ENGINE_NAME: Record<string, string> = { claude: 'Claude Code', codex: 'Codex' }
const NO_PUSH = "This machine's git login cannot push to the project repository. Its owner can sign in to GitHub there (gh auth login, then gh auth setup-git)."
/** Said of a candidate on another machine than the task's requirement names: never which one, which the agent may not see.
 *  A note, not a filter: task requirements are not enforced (project instructions, Routing). */
export const ELSEWHERE = 'The task\'s requirement names another machine.'
const UNCHECKED_DEVICE = 'Its start did not have its machine check the device this task requires.'
const AVOIDED = 'Its account lost this task before (a model that kept failing, a limit or a stall).'
const WAITING = 'This task waits for the machine it requires; route it again once that machine can take it.'
/** What a group's task requires of where it runs (backend superTabs/model.ts TaskRequirement): the machines it runs on, null
 *  when it names none, and the devices every start for it asks its machine to check. An agent that does not see a required
 *  machine reads only that there is one, so the set may be empty and still require. */
export function taskRequirement(group: Json): { machines: Set<string> | null; devices: string[]; access: string[] } {
  const requires = object(object(group.task).requires)
  const strings = (value: unknown) => Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : []
  const unseen = finite(requires.unseenMachines) && requires.unseenMachines > 0
  return { machines: Array.isArray(requires.machines) || unseen ? new Set(strings(requires.machines)) : null, devices: strings(requires.devices),
    access: strings(requires.access) }
}

// ── What a machine can reach (backend superTabs/machineAccess.ts, task #3047) ───────────────────────────────────────────
const accessKey = (name: string): string => name.trim().replace(/\s+/g, ' ').toLowerCase()
const entryOf = (mac: Json | undefined, name: string, account: 'own' | 'team'): Json | undefined =>
  list(mac?.access).find(e => e.account === account && typeof e.name === 'string' && accessKey(e.name) === accessKey(name))
/** Whether every name [needed] is an own-account entry of the Mac [mac] its owner shared with teammates, ok: a teammate's task
 *  that needs them runs on the Mac, in the owner's account (backend sharedOwnAccess). */
export function sharedOwnAccess(mac: Json | undefined, needed: readonly string[]): boolean {
  if (!mac || typeof mac.hostMachineId === 'string' || !needed.length) return false
  return needed.every(name => { const e = entryOf(mac, name, 'own'); return !!e && e.state === 'ok' && e.teammates === true })
}
function editDistance(a: string, b: string): number {
  let row = Array.from({ length: b.length + 1 }, (_, i) => i)
  for (let i = 1; i <= a.length; i++) {
    const next = [i]
    for (let j = 1; j <= b.length; j++) next[j] = Math.min(row[j]! + 1, next[j - 1]! + 1, row[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1))
    row = next
  }
  return row[b.length]!
}
/** The name of [names] closest to [name], when one is close: one holds the other ("Desk lamp", "Lamp"), or a few letters differ. */
export function closestAccessName(name: string, names: readonly string[]): string | null {
  const key = accessKey(name)
  let best: { name: string; score: number } | null = null
  for (const other of new Set(names)) {
    const k = accessKey(other)
    if (k === key) continue
    const score = k.includes(key) || key.includes(k) ? Math.abs(k.length - key.length) : editDistance(k, key)
    const close = k.includes(key) || key.includes(k) || score <= Math.max(1, Math.floor(key.length / 4))
    if (close && (!best || score < best.score)) best = { name: other, score }
  }
  return best?.name ?? null
}
/**
 * Why work for a project owned by [projectOwner] that needs [needed] cannot run in [pool]'s account, one line each, as the
 * backend's start check says it (machineAccess.ts accessRefusal): the entries of that account only, ok, and an own-account
 * entry for a teammate's project only when shared or when its owner lets teammates' work run there. [pool] undefined: a
 * machine off the Machines list, which lists nothing. [names]: every name the Swarm's machines list, for "Did you mean".
 */
export function accessReasons(pool: Json | undefined, mac: Json | undefined, projectOwner: unknown, needed: readonly string[], people: Json[],
  names: readonly string[],
  /** Whether the task itself names every needed name: a shared own-account entry keeps a start on the Mac only then (backend
   *  teamMachineFor reads the task's access), so a route asked with needs.access alone never counts one. */
  taskNamed = true): string[] {
  const account = typeof pool?.hostMachineId === 'string' ? 'team' : 'own'
  const owner = (() => { const p = people.find(x => x.id === mac?.contributorId); return text(p?.name) ?? text(p?.username) ?? 'its owner' })()
  const teammate = projectOwner !== mac?.contributorId
  const ownAccountWork = typeof object(mac?.teamWork).ownAccount === 'string'
  const onlyNamed = (e: Json) => `${String(e.name)} is shared from ${owner}'s own account only with tasks that name it in their access.`
  return needed.flatMap(name => {
    const entry = pool && mac ? entryOf(mac, name, account) : undefined
    if (!entry) {
      const other = pool && mac ? entryOf(mac, name, account === 'own' ? 'team' : 'own') : undefined
      if (other && account === 'own') return [`${String(other.name)} is in the Harness Team account on ${String(mac!.name)}, which runs only teammates' work.`]
      if (other && teammate && other.teammates === true && other.state === 'ok' && !taskNamed) return [onlyNamed(other)]
      if (other && teammate) return [`${String(other.name)} is in ${owner}'s own account, not shared with teammates.`]
      const closest = closestAccessName(name, names)
      return [`No ${name} here.${closest ? ` Did you mean ${closest}?` : ''}`]
    }
    if (entry.state !== 'ok') return [`${String(entry.name)} on ${String(mac!.name)} is waiting for ${owner} to confirm.`]
    if (account === 'own' && teammate && !ownAccountWork && entry.teammates === true && !taskNamed) return [onlyNamed(entry)]
    if (account === 'own' && teammate && entry.teammates !== true && !ownAccountWork) return [`${String(entry.name)} is in ${owner}'s own account, not shared with teammates.`]
    return []
  })
}
/** What the route notes on a candidate whose account would use a production system: access is never permission (design section 4). */
export function productionNotes(pool: Json | undefined, mac: Json | undefined, needed: readonly string[]): string[] {
  const account = typeof pool?.hostMachineId === 'string' ? 'team' : 'own'
  return needed.map(name => entryOf(mac, name, account)).filter((e): e is Json => !!e && e.production === true)
    .map(e => `${String(e.name)} is a production system: writes still need a person's go.`)
}
/** A note on a new agent there, not a filter (project instructions, phase 4): the agent choosing may still try it. */
export const STALLED = 'Its last 2 starts on this machine started no agent (they failed or were never picked up); its owner can check the machine. This clears once a start there succeeds, its Harness is updated, or 30 minutes pass.'
/** How long a machine whose last 2 starts started nothing is noted as stalled. Before the note, nothing but a person's start
 *  by hand brought a machine back into routes, even after the Harness bug behind its failures was fixed and released (Mac
 *  Auto, Swarm autonomous-harness, 2026-10-29). A start that fails again notes it another window. */
export const STALL_RETRY_MS = 30 * 60_000
/** A Harness Team account's refusal of a Codex start for a model its owner's ChatGPT account does not offer (start.ts, before
 *  anything launches): the request named the wrong model, the machine is fine, so it never counts toward [stalled]. Matched by
 *  the refusal's fixed opening, which the Lead reads as the start's raw reason. */
const MODEL_NOT_OFFERED = /^This machine's ChatGPT account \(.*\) does not offer \S+; /
/** What a machine says it cannot do for this task (#229 v1 routing): `all` keeps out its new agents, `engines` those of an
 *  engine. `push`, that its login cannot push, is a note on its new agents and members alike (project instructions, phase 4:
 *  whether the work pushes is the instructions' to say). Only a known failure is said; anything unknown says nothing. */
export interface Unready { all: string[]; engines: Record<string, string>; push: string | null }
const READY: Unready = { all: [], engines: {}, push: null }
/** Whether the Swarm's last 2 starts on [machineId] both started nothing: failed, or queued and never picked up. A start
 *  being created (dispatched, no agent yet) is not counted, nor is a machine with fewer than 2 starts. The failures stop
 *  counting once they say nothing about the machine as it is: its daemon now runs another CLI version than the newer one
 *  was dispatched to ([pool] `clientVersion`, the backend's record of its last connection), or the newer one is
 *  [STALL_RETRY_MS] old. A start from before either was recorded counts as before. */
/** What starts still starting on [machineId] hold of its memory and disk, as its host's reservations do (reservations.ts): one
 *  being created until a start's deadline, a launched one for its start window, a failed one nothing. 2026-11-03: 9 of 25 failed
 *  starts in 10 hours were refused for memory or disk set aside this way, which the route did not count. */
export function heldByStarts(starts: Json[], machineId: string, now = Date.now()) {
  const held = { memoryBytes: 0, diskBytes: 0, heavyMemoryBytes: 0, heavyDiskBytes: 0 }
  for (const start of starts) {
    const request = object(start.request)
    if (request.machineId !== machineId || start.error) continue
    // The host reserves when it is handed the start, which may be long after it was asked for (review).
    const launched = typeof start.harnessId === 'string'
    const times = [start.requestedAt, start.dispatchedAt].filter(finite)
    if (!times.length || now - Math.max(...times) >= (launched ? START_WINDOW_MS : START_DEADLINE_MS)) continue
    const wanted = object(request.requirements)
    const memory = finite(wanted.memoryBytes) ? wanted.memoryBytes : 0, disk = finite(wanted.diskBytes) ? wanted.diskBytes : 0
    held.memoryBytes += memory; held.diskBytes += disk
    if (heavyOfStart(start)) { held.heavyMemoryBytes += memory; held.heavyDiskBytes += disk }
  }
  return held
}

/** What a start's reason says when its machine could not use its own storage or clone the project (task #3861): the fixed openings
 *  this CLI writes (superTabs/start.ts, projectFolder.ts), which say a fault of the machine and not of the request. */
const MACHINE_FAULTS: Array<[RegExp, string]> = [
  [/^CREATION_STORAGE_FAILED: /, 'its creation folder cannot be used'],
  [/^This machine could not clone the project repository with the Harness GitHub App's token/, 'it could not clone the project repository'],
]
/** Why [machineId] takes no new agents after its last start failed on a fault of the machine itself, else null: one such failure
 *  is enough, since the next start would meet the same fault (River, 11-06: five re-routes in a day). It clears as [stalled] does:
 *  a later start that launched, its daemon on another version than the failure was dispatched to, or [STALL_RETRY_MS]. */
export function faulted(starts: Json[], machineId: string, pool: Json = {}, now = Date.now()): string | null {
  const newest = starts.filter(s => object(s.request).machineId === machineId && !MODEL_NOT_OFFERED.test(String(s.error ?? ''))).at(-1)
  if (!newest || newest.harnessId || typeof newest.error !== 'string') return null
  const fault = MACHINE_FAULTS.find(([pattern]) => pattern.test(newest.error as string))
  if (!fault) return null
  if (typeof pool.clientVersion === 'string' && typeof newest.dispatchedVersion === 'string' && newest.dispatchedVersion !== pool.clientVersion) return null
  const at = finite(newest.dispatchedAt) ? newest.dispatchedAt : finite(newest.requestedAt) ? newest.requestedAt : null
  if (at !== null && now - at >= STALL_RETRY_MS) return null
  return `Its last start on this machine failed: ${fault[1]}; its owner can check the machine. This clears once a start there succeeds, its Harness is updated, or 30 minutes pass.`
}
export function stalled(starts: Json[], machineId: string, pool: Json = {}, now = Date.now()): boolean {
  const last = starts.filter(s => object(s.request).machineId === machineId && !MODEL_NOT_OFFERED.test(String(s.error ?? ''))).slice(-2)
  if (last.length !== 2 || !last.every(s => !s.harnessId && (!!s.error || s.dispatched !== true))) return false
  const newest = last[1]!
  if (typeof pool.clientVersion === 'string' && typeof newest.dispatchedVersion === 'string' && newest.dispatchedVersion !== pool.clientVersion) return false
  const at = finite(newest.dispatchedAt) ? newest.dispatchedAt : finite(newest.requestedAt) ? newest.requestedAt : null
  return at === null || now - at < STALL_RETRY_MS
}
/** What a contributed machine's reading says it is not ready for, for work in [projectId]. Its own login's push access
 *  counts only when it is the one that pushes: not for a teammate's project where the server has the Harness GitHub App,
 *  whose token the agent pushes with (start.ts). */
export function unreadyPool(pool: Json, project: Json | undefined, projectId: string, githubApp: boolean, projectOwner: unknown): Unready {
  const observed = object(pool.observation), readiness = object(observed.readiness), repository = object(project?.repository)
  const engines: Record<string, string> = {}
  for (const e of list(readiness.engines)) {
    const name = ENGINE_NAME[String(e.engine)]
    if (!name) continue
    if (e.installed === false) engines[String(e.engine)] = `${name} is not installed on this machine.`
    // Worded as a subscription's, so a Builder on a local model, which runs through the grid without one, is not kept out.
    else if (e.signedIn === false) engines[String(e.engine)] = `${name} is not signed in to a subscription on this machine. Its owner can sign in there; the next reading clears this.`
  }
  // The server's own count of failed starts (backend superTabs/engineHealth.ts), with its words; a server before it sends none.
  for (const [engine, reason] of Object.entries(object(pool.suspendedEngines))) {
    if (ENGINE_NAME[engine] && typeof reason === 'string' && !engines[engine]) engines[engine] = reason
  }
  // Only a Swarm folder's own checkout of the project is read; the repository's machine runs it from the Lead's checkout.
  const checkout = pool.scope === 'swarm' && repository.machineId !== pool.machineId ? list(readiness.checkouts).find(c => c.folder === projectId) : undefined
  const wanted = typeof repository.repositoryUrl === 'string' ? repositoryKey(repository.repositoryUrl) : null
  const all = [
    ...(typeof pool.machineSuspended === 'string' ? [pool.machineSuspended] : []),
    ...(NO_SWARM_AGENTS_ON.includes(String(object(observed.resources).os)) ? [`Swarm agents do not run on ${String(object(observed.resources).os)} yet.`] : []),
    ...(checkout?.git === false ? ['The project folder on this machine is not a git checkout. Its owner can remove it, and the next start clones the project.'] : []),
    ...(checkout?.git === true && wanted && typeof checkout.repository === 'string' && checkout.repository !== wanted
      ? ['The project folder on this machine is a checkout of another repository. Its owner can remove it, and the next start clones the project.'] : []),
  ]
  const app = githubApp && projectOwner !== pool.contributorId
  return { all, engines, push: !app && checkout?.push === false ? NO_PUSH : null }
}
/** A running member keeps its engine and memory, but still needs a live terminal and the task's tools and devices. Its
 *  allowance is information ([usedUp]). */
function memberRefusals(running: boolean | null, closed: boolean, tools: string[], devices: string[], reportedTools: Json, reportedDevices: Json, toolProbeErrors: Json): string[] {
  return [
    // A session its machine's idle cleanup closed never comes back as this agent: the backend refuses to assign it (superTabs/
    // closedAgents.ts sessionClosed), so the reason says what to do (task #2744). One listed stopped alone may be a Change
    // agent before its rebind (review of #2953).
    ...(running === false ? [closed ? 'Its session was closed. Start a new agent.' : 'Its terminal is not running.'] : []),
    ...tools.map(tool => requiredToolReason(tool, reportedTools[tool], toolProbeErrors[tool])).filter((reason): reason is string => reason !== null),
    ...devices.filter(device => reportedDevices[device] !== true).map(device => `Required device unavailable: ${device}.`),
  ]
}
const active = (assignment: unknown) => { const a = object(assignment); return !!a.id && !ENDED_WORK.includes(String(a.status)) }
const list = (value: unknown) => Array.isArray(value) ? value.map(object) : []
/** The Lead's machine, for the task's folder; replaced in tests. */
interface FolderReader { describe: typeof describeScmProject; isDirectory: (path: string) => Promise<boolean> }
const FOLDER_READER: FolderReader = { describe: describeScmProject, isDirectory: path => stat(path).then(s => s.isDirectory(), (error: NodeJS.ErrnoException) => {
    // Only an absent folder is "not on this machine"; a refusal or a broken path says nothing, so the read fails and the folder is unknown.
    if (error.code === 'ENOENT') return false
    throw error
  }) }
async function readFolder(cwd: string, reader: FolderReader): Promise<TaskFolder> {
  const folder = { cwd, name: null, root: null, remote: null }
  // The SCM description only checks the path's form, so a folder this machine lacks must be found out first.
  if (!await reader.isDirectory(cwd)) return { ...folder, kind: 'missing' }
  const described = await reader.describe(cwd)
  if (!described) return { ...folder, kind: 'unknown' }
  return { cwd, kind: described.kind, name: described.kind === 'git' ? described.name : null, root: described.root, remote: described.remote }
}
const text = (value: unknown) => typeof value === 'string' ? value : null
/** A member started by `start` was launched with `--effort`, which Claude never reports back, so its configuration says
 * `auto` (manual run 2026-10-19). The tab's start record still holds what it was launched with; an effort the member
 * does report is kept. */
function withLaunchEffort(member: Json, starts: Json[]): Json {
  const configuration = object(member.configuration)
  const start = starts.find(s => s.harnessId === member.harnessId)
  // Launched on the engine's own model: rated by the catalog's `default` row, whatever slug it reports (route.ts catalogRow).
  const engineDefault = start && (object(start.request).model ?? 'default') === 'default' ? { engineDefault: true } : {}
  if (configuration.effort && configuration.effort !== 'auto') return { ...member, ...engineDefault }
  const launched = object(start?.request).effort
  return typeof launched === 'string' && launched !== 'default' ? { ...member, ...engineDefault, configuration: { ...configuration, effort: launched } } : { ...member, ...engineDefault }
}
const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)

/** Work that ended in this Super Tab, oldest first, for each member's earlier work: the log's decisions, the group's
 * attempts and each group's last assignment, joined by assignment id. The log knows which agent a decision started; the
 * attempts are every earlier assignment of this group, also those `work.define` took out of the state (a person's
 * assignment has no decision); the state knows the agent of each group's last one. */
/** `group` is the group's title, for the printed note; `groupId` its id, which the pick compares with the routed task (routePick.ts). */
interface Ended { assignmentId: string; group: string; groupId: string; agentId: string | null; outcome: string }
function endedWork(conversations: Json[], decisions: Json[] | null, attempts: Json[] | null, attemptsGroup: string): Ended[] {
  const titleOf = (id: unknown) => String(conversations.find(c => c.id === id)?.title ?? 'another group')
  const ended: Ended[] = [...(decisions ?? [])].reverse().flatMap(d => {
    const final = object(d.final)
    return typeof d.assignmentId === 'string' && ENDED_WORK.includes(String(d.outcome)) && final.kind
      ? [{ assignmentId: d.assignmentId, group: titleOf(d.conversationId), groupId: String(d.conversationId), outcome: String(d.outcome), agentId: final.kind === 'member' ? String(final.agentId) : null }]
      : []
  })
  // The assignment's own record wins on the agent: a started agent is a member by then.
  const join = (assignment: Json, groupId: string) => {
    const known = ended.find(e => e.assignmentId === assignment.id)
    if (known) return Object.assign(known, { agentId: String(assignment.agentId) })
    const added: Ended = { assignmentId: String(assignment.id), group: titleOf(groupId), groupId, agentId: String(assignment.agentId), outcome: String(assignment.status) }
    ended.push(added)
    return added
  }
  // With the attempts read the group's own work is ordered by it: oldest first, then the current assignment. The log's
  // order alone puts a routed attempt before an earlier one a person assigned (it has no decision). Without the read
  // the log's order stays.
  const last = (e: Ended) => { if (attempts) ended.push(...ended.splice(ended.indexOf(e), 1)) }
  const time = (a: Json) => Date.parse(String(a.createdAt)) || 0
  for (const attempt of [...(attempts ?? [])].reverse().sort((x, y) => time(x) - time(y))) if (attempt.id) last(join(attempt, attemptsGroup))
  for (const c of conversations) {
    const current = object(c.assignment)
    if (current.id && !active(current)) last(join(current, String(c.id)))
  }
  return ended
}
/** How many of the task's attempts ended: its earlier assignments the route read and its own last one, once each; null when its
 *  attempts could not be read. The route steps small work up after the second (route.ts tierOf). */
function endedAttempts(group: Json, attempts: Json[] | null): number | null {
  if (!attempts) return null
  const ended = new Set(attempts.filter(a => typeof a.id === 'string' && !active(a)).map(a => a.id))
  const current = object(group.assignment)
  if (current.id && !active(current)) ended.add(current.id)
  return ended.size
}
/** The fields of a frame that say what the agent works on; an absent or malformed one says nothing. */
function frameOf(frame: Json): MemberFrame {
  const project = object(frame.project), updatedAt = Date.parse(String(frame.updatedAt))
  return { title: text(frame.title), project: text(project.name), cwd: text(project.cwd), root: text(project.root), remote: text(project.remote),
    branch: text(object(object(frame.gitContext).current).branch) ?? text(project.branch), updatedAt: Number.isFinite(updatedAt) ? updatedAt : null }
}

/** `makers`: what makes the routing plug-ins this route ranks with (routePlugins.ts), in their order. */
export async function routeTask(input: { tabId: string; conversationId: string; assessment: unknown }, request: ScopedRequest, where: Where,
  open: typeof openDaemon = openDaemon, newId: () => string = randomUUID, reader: FolderReader = FOLDER_READER,
  makers: readonly PluginMaker[] = ROUTE_PLUGIN_MAKERS): Promise<Json> {
  // A lost connection is an answer here, never a throw: the agent must still get a decision or a reason.
  const scoped: ScopedRequest = async payload => {
    try { return await request(payload) } catch (error) {
      return { error: 'AGENT_UNAVAILABLE', detail: error instanceof Error ? error.message : 'The request to the machine failed.' }
    }
  }
  const parsed = parseAssessment(input.assessment)
  if (typeof parsed === 'string') return { error: 'INVALID_REQUEST', detail: parsed }
  let assessment = parsed
  const cwd = assessment.needs.cwd
  const context = await scoped({ action: 'routeContext' })
  if (context.error || context.ok !== true) return context
  const value = object(context.value), state = object(object(value.tab).state), effective = object(value.policy)
  // The catalog beside the default policy, or one read off the policy of a backend from before it (route.ts catalogFrom).
  const catalog = catalogFrom(effective)
  const conversations = list(state.conversations), agents = list(state.agents)
  const group = conversations.find(c => c.id === input.conversationId)
  if (!group) return { error: 'NOT_FOUND', detail: 'No such group in this Super Tab.' }
  // Any agent of the project routes its work (project instructions, phase 4): the status read holds only groups the agent may
  // read, and the server records a decision only for a group in the agent's project.
  const required = taskRequirement(group)
  if (required.devices.length) assessment = { ...assessment, needs: { ...assessment.needs, devices: [...new Set([...assessment.needs.devices, ...required.devices])] } }
  // What the task needs to reach joins what the Lead said it needs: the backend holds every start to the task's (machineAccess.ts).
  if (required.access.length) {
    const access = [...assessment.needs.access ?? []]
    for (const name of required.access) if (!access.some(a => accessKey(a) === accessKey(name))) access.push(name)
    assessment = { ...assessment, needs: { ...assessment.needs, access } }
  }
  const needed = assessment.needs.access ?? []
  // Only what the task itself names keeps a teammate's start in the owner's account (backend teamMachineFor).
  const taskNamed = needed.length > 0 && needed.every(n => required.access.some(r => accessKey(r) === accessKey(n)))
  const projectId = String(group.projectId ?? 'lead')
  const project = list(state.projects).find(p => p.id === projectId)
  // Every idle agent is a candidate, whatever its role: the coordinator, and an agent an older client started as a Reviewer.
  const busy = new Set(conversations.filter(c => active(c.assignment)).map(c => String(object(c.assignment).agentId)))
  // A Mac's Harness Team account is that Mac (One machine, below).
  const macOf = new Map(list(state.machines).filter(m => typeof m.hostMachineId === 'string').map(m => [String(m.machineId), String(m.hostMachineId)]))
  // A Buddy is a person's own, and is never assigned work (the backend refuses it too, backend buddies.ts).
  const members = agents.filter(a => !busy.has(String(a.id)) && !a.buddyOf
    && ENGINES.includes(String(object(a.configuration).engine))).map(a => withLaunchEffort(a, list(state.starts)))
  // A new agent starts only on a machine in the Swarm's Machines list (the backend refuses any other): a contributed machine, or
  // one an agent of the Swarm runs on. The routing agent runs here, so its own machine is always listed. Of the account's
  // machines only those count; the rest were never prepared with the project and would only be excluded for a missing folder
  // (production, 2026-10-21). A member may run on a machine only its collaborator can open; the route tries that machine
  // too, but a member there is unknown, never offline.
  const swarmMachines = new Set([where.machineId, ...list(state.machines).map(m => String(m.machineId)), ...agents.map(a => String(a.machineId))])
  const machines = new Map<string, { name: string; status: string; account: boolean; pool?: Json; folded?: boolean; unready?: Unready; stalled?: boolean; held?: ReturnType<typeof heldByStarts>; access?: string[]; accessNotes?: string[] }>()
  for (const m of list(value.machines)) if (swarmMachines.has(String(m.machineId))) machines.set(String(m.machineId), { name: String(m.name), status: String(m.status ?? 'unknown'), account: true })
  // The routing agent's own machine is the account's even when the list could not be read.
  if (!machines.has(where.machineId)) machines.set(where.machineId, { name: where.machineId, status: 'unknown', account: true })
  for (const m of members) if (!machines.has(String(m.machineId))) machines.set(String(m.machineId), { name: String(m.machineId), status: 'unknown', account: false })
  // A teammate's project runs only on Team machines: the backend says per machine whether it takes one now, and why not
  // (backend superTabs/machines.ts teamWorkRefusal). Its project owner's own machines take its work as before.
  const projectOwner = project?.ownerId ?? state.ownerId
  // A machine its owner keeps for some projects (backend machines.ts machine.projects, Tony 11-03): a Mac's Harness Team
  // account follows its Mac. Only public projects are named, as the backend's own sentence does: the route's exclusions reach
  // this project's readers.
  const keptFor = (m: Json) => {
    const mac = typeof m.hostMachineId === 'string' ? list(state.machines).find(x => x.machineId === m.hostMachineId && x.contributorId === m.contributorId) ?? m : m
    const ids: unknown[] | null = Array.isArray(mac.projects) ? mac.projects : null
    if (!ids || ids.includes(projectId)) return null
    const named = list(state.projects).filter(p => ids.includes(p.id) && p.visibility === 'public').map(p => String(p.name))
    return named.length ? `${String(mac.name)} runs only ${named.length > 1 ? `${named.slice(0, -1).join(', ')} and ${named.at(-1)}` : named[0]}.`
      : `${String(mac.name)} is kept by its owner for other projects.`
  }
  // A Mac's own entry holds both its accounts' lists (backend machineAccess.ts): a Team account's pool reads its Mac's.
  const macPoolOf = (m: Json): Json | undefined => typeof m.hostMachineId === 'string'
    ? list(state.machines).find(x => x.machineId === m.hostMachineId && x.contributorId === m.contributorId) : m
  const people = list(state.people), accessNames = list(state.machines).flatMap(m => list(m.access).map(e => String(e.name)))
  for (const original of list(state.machines)) {
    const repository = object(project?.repository)
    const teamWork = object(original.teamWork)
    // A teammate's task that needs only entries its owner shared runs on the Mac, in the owner's account: said, not refused.
    const shared = projectOwner !== original.contributorId && taskNamed && sharedOwnAccess(original, needed)
    const ownerName = (() => { const p = people.find(x => x.id === original.contributorId); return text(p?.name) ?? text(p?.username) ?? 'its owner' })()
    const pool: Json = { ...original,
      // Offline is said once, by the reading's own age below.
      ...(teamWork.allowed === false && teamWork.code !== 'MACHINE_OFFLINE' && typeof teamWork.reason === 'string' && !shared
        ? { teammatesRefused: teamWork.reason, projectOwnerId: projectOwner } : {}),
      ...(shared ? { ownAccount: `${String(original.name)} runs this task in ${ownerName}'s own account: ${needed.join(', ')} ${needed.length > 1 ? 'are' : 'is'} shared with teammates.`,
        projectOwnerId: projectOwner } : {}),
      // Its owner lets teammates' work run in their own account (backend machines.ts ownAccountWork, task #2806): the teammate
      // whose task lands there did not choose that, so the route says it (River, 11-04).
      ...(teamWork.allowed === true && typeof teamWork.ownAccount === 'string' ? { ownAccount: teamWork.ownAccount, projectOwnerId: projectOwner } : {}),
      ...(original.scope === 'swarm' ? { cwd: repository.machineId === original.machineId
        ? repository.cwd : `${String(original.cwd).replace(/\/+$/, '')}/${projectId}` } : {}),
      ...(original.scope !== 'swarm' && projectId !== 'lead' ? { projectUnavailable: true } : {}),
      ...(keptFor(original) ? { keptForOthers: keptFor(original) } : {}),
      ...(original.scope === 'swarm' && repository.machineId !== original.machineId && typeof repository.repositoryUrl !== 'string'
        ? { repositoryUnavailable: true } : {}),
    }
    machines.set(String(pool.machineId), { name: String(pool.name), status: 'contributed', account: false, pool,
      unready: unreadyPool(original, project, projectId, object(value.tab).githubApp === true, projectOwner) })
  }
  for (const [machineId, machine] of machines) {
    const listed = list(state.machines).find(m => m.machineId === machineId)
    if (needed.length) {
      machine.access = accessReasons(listed, listed && macPoolOf(listed), projectOwner, needed, people, accessNames, taskNamed)
      machine.accessNotes = productionNotes(listed, listed && macPoolOf(listed), needed)
    }
    machine.stalled = stalled(list(state.starts), machineId, list(state.machines).find(m => m.machineId === machineId))
    const fault = faulted(list(state.starts), machineId, list(state.machines).find(m => m.machineId === machineId))
    if (fault) machine.unready = { ...(machine.unready ?? READY), all: [...(machine.unready ?? READY).all, fault] }
    machine.held = heldByStarts(list(state.starts), machineId)
  }
  // One machine (docs/plans/2026-10-24-swarm-team-account.md): a Mac's Harness Team account is that Mac, under its name. A
  // teammate's project starts only in the team account and the Mac's owner's own projects only with the owner, so only one
  // of the two offers new agents here, and the other is not listed as unfit; agents already on either stay members.
  // Not when the Mac's owner runs teammates' work in their own account (backend machines.ts ownAccountWork, task #3060): a
  // teammate's work no Team agent wrote starts on the Mac, and the server refuses a start naming the Team account there.
  // Work a Team agent wrote stays in the Team account (backend teamWritten.ts teamWrittenTask): a step reads its task's mark,
  // an unknown task counts as written, and so does a task from before the mark whose assignee runs in a Team account.
  const task = group.reviewOf ? conversations.find(c => c.id === group.reviewOf) : group
  const assignee = task ? agents.find(a => a.id === object(task.assignment).agentId) : undefined
  const onTeam = (agent: Json) => agent.teamAccount === true || list(state.machines).some(m => m.machineId === agent.machineId
    && (typeof m.hostMachineId === 'string' || object(m.observation).sessionKind === 'team'))
  const teamWritten = group.teamWritten === true || !task || task.teamWritten === true || (!!assignee && onTeam(assignee))
  for (const [team, mac] of macOf) {
    const pool = machines.get(team)?.pool
    if (!pool || !machines.has(mac)) continue
    // Its owner runs teammates' work no Team agent wrote in their own account (#3060), or a teammate's task needs only what
    // the owner shared (backend teamMachineFor): either stays on the Mac, and its Team account folds.
    const ownAccount = typeof machines.get(mac)!.pool?.ownAccount === 'string' && !teamWritten
    const onMac = projectOwner === pool.contributorId || ownAccount || (taskNamed && sharedOwnAccess(list(state.machines).find(m => m.machineId === mac), needed))
    machines.get(onMac ? team : mac)!.folded = true
  }
  // Every row of the catalog is probed: one not offered by default is offered when a person names it (route.ts choose).
  const rows = catalog.models

  // The probes do not wait for the context reads: the machines, the task's folder and the group's talk and log are read
  // together, and each read that is only context gives up after three seconds. What needs several of them (whether a
  // member is in the task's repository, what it did before) is joined afterwards.
  // The plug-ins' makers start here too: each piece's outside read runs beside the probes, and they share the history read.
  const historyRead = within(scoped({ action: 'routeHistory', conversationId: input.conversationId }))
  const [probed, read, history, instructed, made, ruleRead] = await Promise.all([
    Promise.all([...machines].map(([machineId, machine]) =>
      probeMachine(machineId, machine, members.filter(m => m.machineId === machineId), rows, catalog, assessment, where, open))),
    cwd ? within(readFolder(cwd, reader)) : null,
    historyRead,
    // The project's instructions ride on the answer: the agent routes by them. A backend without them is an unreadable read.
    within(scoped({ action: 'instructions', projectId })),
    makePlugins(makers, { conversationId: input.conversationId, assessment, read: value, catalog, history: historyRead, request: scoped }),
    // The project's machine rules from its record (task #3964); unreadable, the route says the instructions' still apply.
    within(scoped({ action: 'machineRules', projectId })),
  ])
  const machineRules = ruleRead?.ok === true && Array.isArray(object(ruleRead.value).machines) ? list(object(ruleRead.value).machines) : null
  const written = object(instructed?.ok === true ? instructed.value : {})
  const instructions = typeof written.text === 'string' ? { revision: written.revision, text: written.text, notes: Array.isArray(written.notes) ? written.notes : [] } : null
  const folder: TaskFolder | null = !cwd ? null : read ?? { cwd, kind: 'unknown', name: null, root: null, remote: null }
  const past = object(history?.ok === true ? history.value : {})
  const decisions = Array.isArray(past.decisions) ? list(past.decisions) : null
  const attempts = Array.isArray(past.attempts) ? list(past.attempts) : null
  const ended = endedWork(conversations, decisions, attempts, input.conversationId)
  // What the route knows of a member beside the facts is a note on it, never a filter (project instructions, phase 4):
  // - its machine saw a usage-limit screen (superTabs/terminal.ts) until a reset, which the backend sets to an hour when the
  //   screen named none (spec/2026-10-23-lead-sees-agent-terminal.md): quota is information, and it resumes by itself then
  //   (superTabs/limitResume.ts);
  // - it lost its last task: it died, stalled or hit a limit (v1 liveness). The backend keeps that mark on the agent until it
  //   recovers or is assigned again (backend superTabs/model.ts lostTask), whoever assigns it.
  const limited = (agentId: string | undefined) => {
    const until = Date.parse(String(members.find(m => m.id === agentId)?.limitedUntil))
    return until > Date.now() ? [`Its screen showed a usage limit until ${new Date(until).toISOString()}.`] : []
  }
  const lostTask = (agentId: string | undefined) => {
    const marked = members.find(m => m.id === agentId)?.lostTask
    // The backend writes the mark with its loss's reason (backend superTabs/liveness.ts loseTask).
    return marked ? [`It lost its last task (${String(object(marked).reason)}).`] : []
  }
  const probes = probed.flat()
    .map(p => p.kind === 'member' ? { ...p, repo: repoMatch(folder, p.frame ?? null, p.machineId === where.machineId),
    notes: [...p.notes, ...limited(p.agentId), ...lostTask(p.agentId)],
    earlier: ended.filter(e => e.agentId === p.agentId).reverse().slice(0, 3).map(e => ({ group: e.group, groupId: e.groupId, outcome: e.outcome })) } : p)
  probes.push(...localProbes(state, catalog, probes))
  // The task's requirement is not enforced (project instructions, Routing): a candidate elsewhere, or a member whose start
  // did not have its machine check the required device, says so. A Mac's Harness Team account is that Mac.
  const outside = (machineId: string) => !!required.machines && !required.machines.has(machineId) && !required.machines.has(macOf.get(machineId) ?? '')
  const checked = (agentId: string | undefined) => {
    const member = members.find(m => m.id === agentId)
    const start = list(state.starts).find(s => s.harnessId === member?.harnessId && object(s.request).machineId === member?.machineId)
    const devices = object(object(start?.request).requirements).devices
    return required.devices.every(d => Array.isArray(devices) && devices.includes(d))
  }
  // Work this group last lost (a model that kept failing, a limit or a stall, v2) ran on an account the agent choosing may
  // want to avoid. The group keeps where that attempt ran (backend superTabs/liveness.ts loseTask), so this holds once its
  // agent is stopped and removed too; an attempt lost before that kept it is read from its agent, while that is still here.
  const lostAttempt = object(group.lostAttempt), lostBy = agents.find(a => a.id === lostAttempt.agentId)
  const failedOn = text(lostAttempt.machineId) ?? text(lostBy?.machineId), failedEngine = text(lostAttempt.engine) ?? text(object(lostBy?.configuration).engine)
  const avoid = new Set(failedOn && failedEngine ? [`${failedOn}:${failedEngine}`,
    ...probes.filter(p => p.machineId === failedOn && p.engine === failedEngine && !p.gridModel).map(accountOf)] : [])
  for (const [i, p] of probes.entries()) {
    const notes = [...(outside(p.machineId) ? [ELSEWHERE] : []), ...(p.kind === 'member' && !checked(p.agentId) ? [UNCHECKED_DEVICE] : []),
      ...(p.kind === 'new' ? recentStartNotes(list(state.starts), p.machineId, p.engine, Date.now()) : []),
      ...(avoid.has(accountOf(p)) ? [AVOIDED] : [])]
    if (notes.length) probes[i] = { ...p, notes: [...p.notes, ...notes] }
  }
  // Whose PM an account keeps running, any project's (pmAccounts.ts): the project's Routing guards that PM's week.
  probes.splice(0, probes.length, ...withPmAccounts(state, probes))
  // Picks started or assigned and still at work hold part of their account's quota; the log, and so this, is per Swarm.
  const working = (decisions ?? []).filter(d => d.final && d.outcome === null && typeof d.account === 'string')
    .map(d => ({ account: d.account, spend: object(d.spend), size: d.size, createdAt: Date.parse(String(d.createdAt)) }) as Commitment)
  // A model a host now offline served is left out with that reason, and a person naming it gets no stand-in (route.ts choose).
  const offline = offlineModels(state)
  const now = Date.now()
  // What the server refuses by the project's machine rules is left out with the rule's why, on the machine named or its Mac.
  const review = /(^|-)review(-|$)/.test(assessment.kind ?? '')
  for (const [i, p] of probes.entries()) {
    const why = [p.machineId, macOf.get(p.machineId)].flatMap(machineId => machineId ? [machineRuleRefusal(machineRules ?? [], { machineId, engine: p.engine, review }, now)] : [])
      .find(w => w !== null)
    if (why) probes[i] = { ...p, refusals: [...p.refusals, why] }
  }
  // A lane's work goes first to its machines: the task's own lane, or a step's task's.
  const ownTask = group.reviewOf ? conversations.find(c => c.id === group.reviewOf) : group
  const first = firstMachines(machineRules ?? [], text(group.handOutLane) ?? text(ownTask?.handOutLane) ?? null)
  const choice = choose(probes, catalog, { ...assessment, ended: endedAttempts(group, attempts) }, now, working, heldLocalModels(state), offline, made.plugins)
  const skipped = [...made.warnings, ...(choice.warnings ?? []), ...(machineRules ? [] : [MACHINE_RULES_UNREAD])]
  choice.excluded.push(...offline, ...(catalog.models.length ? [] : [{ title: 'New agents', reason: CATALOG_UNREADABLE }]))
  // The task stays in the agent's queue rather than going where it cannot be done.
  // Work that starts heavy CI while the account is at its limit waits, and says when to route it again (machineFit.ts), so the
  // Lead's route queue retries it without a person.
  const ciHeld = 'error' in choice ? choice.excluded.find(e => e.reason.startsWith(`${MACHINE_FIT_MAKER.name}: ${CI_HOLD_OPENING}`)) : undefined
  if ('error' in choice) return { ...choice, ...(skipped.length ? { warnings: skipped } : {}), leftOut: leftOut(choice.excluded, []),
    ...required.machines || required.devices.length ? { waiting: true, detail: WAITING } : {},
    ...ciHeld ? { waiting: true, retryAfterMinutes: CI_RETRY_MINUTES, detail: ciHeld.reason.slice(MACHINE_FIT_MAKER.name.length + 2) } : {} }
  // The pick by the project's Routing order (routePick.ts, task #3576): the recorded candidate that start or assignment follows.
  const verdict = decideByOrder(choice, pickByOrder({ shown: choice.shown, catalog, assessment: { ...assessment, ended: endedAttempts(group, attempts) }, now,
    conversationId: input.conversationId, ...first ? { first: { machines: new Set([...first.machines, ...[...macOf].filter(([, mac]) => first.machines.has(mac)).map(([id]) => id)]), why: first.why } } : {} }))
  const operationId = `route-${newId()}`
  // The rows recorded are the rows offered: the agent choosing assigns by a recorded candidate.
  let offered = choice.shown
  const record = (shape: RecordShape) => scoped({ action: 'command', operationId,
    command: { type: 'route.record', conversationId: input.conversationId, decision: recordOf({ ...choice, shown: offered }, verdict, assessment, shape) } })
  let recorded = await record('current')
  // A backend from before task #3163 refuses each candidate's weekly % left and reset: the same decision without them.
  if (recorded.error === 'VALIDATION_ERROR') recorded = await record('unquoted')
  // A backend from before task #2901 takes a record only with a pick: c0 stands in for one, so its decision log and the starts
  // linked to it still work (route.ts recordOf).
  if (recorded.error === 'VALIDATION_ERROR') recorded = await record('picked')
  // A backend from before every engine on every machine was shown keeps 12 candidates (Ken, 2026-11-03): the first 12 go.
  if (recorded.error === 'VALIDATION_ERROR' && offered.length > OLD_RECORD_MAX) { offered = offered.slice(0, OLD_RECORD_MAX); recorded = await record('picked') }
  // A backend from before kinds, or before phase 1, refuses the new fields as invalid; the decision is still worth keeping in
  // the shape it knows. A task with no kind has nothing to leave out at the first step.
  if (recorded.error === 'VALIDATION_ERROR' && assessment.kind) recorded = await record('unkinded')
  if (recorded.error === 'VALIDATION_ERROR') recorded = await record('v1')
  if (typeof recorded.error === 'string' && !TRANSPORT.has(recorded.error)) return recorded
  const routeDecisionId = recorded.ok === true ? object(object(recorded.value).result).routeDecisionId : undefined
  // What the agent choosing reads of a candidate: where it runs, and what the route knows of it beside its facts.
  // A new agent's row says what its machine has for a start and the folder it starts in; a member needs no new start, and a
  // paused machine, which offers no new agent, shows no reading (review of #2426).
  const cwdOn = (machineId: string) => text(machines.get(machineId)?.pool?.cwd) ?? assessment.needs.cwd ?? '/absolute/repo/on/that/machine'
  const publicOf = (s: Shown) => ({ id: s.id, kind: s.kind, ...(s.agentId ? { agentId: s.agentId } : {}), machineId: s.machineId,
    engine: s.engine, model: s.model, effort: s.effort, title: s.title, ...(s.gridModel ? { gridModel: s.gridModel, gridName: s.gridName } : {}),
    ...(s.unrated ? { unrated: true } : {}), quota: quotaBrief(s, now), ...(s.kind === 'new' ? { cwd: cwdOn(s.machineId) } : {}),
    ...(s.kind === 'new' && s.load?.room ? { machine: machineBrief(s.load.room) } : {}), ...(s.notes.length ? { notes: s.notes } : {}),
    machineName: s.machineName, ...(agentsOn.has(s.machineId) ? { agents: agentsOn.get(s.machineId) } : {}), line: lineOf(s) })
  // The agents on each machine, as any of its rows read them: a member's row may carry no reading of its machine.
  const agentsOn = new Map(offered.filter(s => typeof s.load?.agents === 'number').map(s => [s.machineId, s.load!.agents!]))
  // A candidate in one line for the agent choosing (task #3294), under its machine, which says its id, agents, folder and room
  // once (routeAnswer).
  const lineOf = (s: Shown) => [`${s.id} ${s.kind === 'new' ? 'new' : `${s.name ?? 'Member'} (agent ${s.agentId}, ${s.activity})`}`,
    s.gridModel ? `${s.engine} on the grid: gridModel ${s.gridModel}, gridName ${s.gridName}` : `${s.engine} ${s.model} ${s.effort}${s.unrated ? ' (unrated)' : ''}`,
    quotaLine(s, now), ...s.notes.filter(n => n !== UNRATED).map(noteClause)].join(' · ')
  // Every recorded row: the coordinator may reuse a particular member (the same Reviewer for its next round, Routing rule 3),
  // so none is hidden behind another on its account.
  const shownRows = offered
  return {
    ok: true, ...(typeof routeDecisionId === 'string' ? { routeDecisionId } : { unrecorded: true }),
    ...(verdict.pick ? { pick: { id: verdict.pick, title: shownRows.find(s => s.id === verdict.pick)?.title }, reasons: verdict.reasons } : {}),
    ...(instructions ? { instructions } : { instructionsUnreadable: true }),
    via: verdict.via, p: verdict.p, why: verdict.why,
    candidates: shownRows.map(publicOf),
    leftOut: leftOut(choice.excluded, choice.shown),
    warnings: [...(Array.isArray(effective.warnings) ? effective.warnings : []), ...(value.machinesUnreadable === true ? [MACHINES_UNREADABLE] : []),
      ...(catalog.models.length ? [] : [CATALOG_UNREADABLE]),
      ...(choice.shown.some(p => p.kind === 'member' && p.terminalUnverified) ? ["A member's terminal could not be verified from its machine's snapshot. Check it before assignment."] : []),
      ...(choice.short ? [choice.short] : []), ...skipped],
    next: nextOf(shownRows, input.conversationId, typeof routeDecisionId === 'string' ? routeDecisionId : undefined, !!instructions, assessment.needs, verdict.pick, !!machineRules),
  }
}

/** How to act on the route: the candidates are in no order of merit (task #2901), so it names none. A member is assigned, a new
 *  agent started, each with the chosen row's own fields; RULE is the Routing rule that chose it, which the backend asks for
 *  with a decision that has no pick, and the start or assignment records the candidate it matches. */
function nextOf(rows: Shown[], conversationId: string, routeDecisionId: string | undefined, instructions: boolean, needs: Assessment['needs'], pick?: string,
  machineRulesRead = false): string {
  // Said once and short (task #3294): it rode on every route, 467 a day in one PM's context.
  const choose = pick
    ? `Use the pick (${pick}), chosen by the project's Routing order: start or assign it as listed, with no overrideReason. `
      // The pick applies the machine rules from the project's record (task #3964); unread, the instructions' still apply.
      + (machineRulesRead ? '' : 'The project\'s machine rules could not be read, so the pick does not apply them: the instructions\' Machines rules '
        + 'still apply, and a pick that breaks one is not used; choose another candidate and give that rule as overrideReason. ')
      + 'For another candidate, give the reason as overrideReason (urgency, context, a machine the work needs; "idle" is not one).'
    : 'Not ranked: listed by machine name. Choose one by the project\'s Routing instructions (Order and quota), and give the rule that chose it as overrideReason.'
  const decided = routeDecisionId ? pick ? { routeDecisionId } : { routeDecisionId, overrideReason: 'RULE' } : {}
  const assign = `Assign a member: command OPERATION_ID ${JSON.stringify({ type: 'work.assign', conversationId, agentId: 'AGENT', ...decided })}`
  // No fixed role name: NAME and ROLE are the agent's to fill from the project's instructions. A backend without instructions
  // takes no roleName (it came with them, phase 2).
  const start = `Start a new agent: start OPERATION_ID ${JSON.stringify({ conversationId, name: 'NAME', ...(instructions ? { roleName: 'ROLE' } : {}),
    cwd: 'CWD', worktree: true, requirements: startRequirements(needs), ...(needs.heavy ? { heavy: needs.heavy } : {}),
    machineId: 'MACHINE', engine: 'ENGINE', model: 'MODEL', effort: 'EFFORT', ...decided })}, then assign it${routeDecisionId ? ' with the same routeDecisionId' : ''}. `
    + 'MACHINE is its machine\'s machineId, CWD the cwd its machine names or else the answer\'s; ENGINE, MODEL and EFFORT its line\'s; a grid line takes its gridModel and gridName in place of model and effort. '
    + `NAME is the agent's name${instructions ? ', ROLE its role in the instructions' : ''}. It starts from the default branch, fetched first; add "branchRef":"refs/remotes/origin/BRANCH" for another.`
  const rule = routeDecisionId && !pick ? ' RULE: the Routing rule that chose it.' : ''
  return [choose, ...(rows.some(r => r.kind === 'member') ? [assign] : []), ...(rows.some(r => r.kind === 'new') ? [start] : [])].join(' ') + rule
}

/** Each machine none of whose candidates is offered, with why, for the Lead's answer: the decision kept the exclusions, but the
 *  answer showed none, so nobody saw why Tony's Mac was never offered for reviews (2026-10-30). In the order first left out;
 *  at most [MAX_LEFT_OUT] machines and [MAX_REASONS] distinct reasons each. */
export function leftOut(excluded: Excluded[], shown: Array<{ machineName: string }>): Array<{ machine: string; reasons: string[] }> {
  const offered = new Set(shown.map(s => s.machineName)), out = new Map<string, Set<string>>()
  for (const e of excluded) {
    if (!e.machine || offered.has(e.machine)) continue
    const reasons = out.get(e.machine) ?? out.set(e.machine, new Set()).get(e.machine)!
    if (reasons.size < MAX_REASONS) reasons.add(e.reason.length > 300 ? `${e.reason.slice(0, 299)}…` : e.reason)
  }
  return [...out].slice(0, MAX_LEFT_OUT).map(([machine, reasons]) => ({ machine, reasons: [...reasons] }))
}
const MAX_LEFT_OUT = 20, MAX_REASONS = 4


/** A reading this old says nothing is served (backend `MACHINE_FRESH_MS`). */
export const LOCAL_FRESH_MS = 45_000
/** Refusals about a subscription's allowance, which a local model does not spend. */
const SUBSCRIPTION = /subscription/i

/** A model served for the Swarm, by grid and model: its label, the machines that may run it (null: any) and the agents on it.
 *  [note]: why it may not drive a coding agent well (too small or too slow, lib/codingModel.ts), said with it, never a filter. */
export interface Served { grid: string; model: string; label: string; kind: 'local' | 'api' | 'shared'; machines: Set<string> | null; holders: string[]; note?: string }

/** The models served for the Swarm while the owner has the add-on on and a fresh reading lists them, by grid and model, each
 * with the agents on it: one started on a model, or starting on it, holds it until it leaves the Swarm. A model a fresh
 * reading reports too small or too slow for a coding agent (superTabs/machines.ts refusedOn) is served too, with that note,
 * unless another machine serves it as fit (project instructions, phase 4, decision 19). */
export function servedModels(state: Json, swarm: string, now: number): Map<string, Served> {
  const served = new Map<string, Served>()
  const fresh = list(state.machines).filter(machine => { const at = object(machine.observation).receivedAt; return finite(at) && now - at <= LOCAL_FRESH_MS })
  for (const machine of fresh) {
    for (const l of list(object(machine.observation).localModels)) {
      // A model still starting (the grid does not list it yet) is the panel's to show, not an agent's to run on.
      if (typeof l.grid !== 'string' || typeof l.model !== 'string' || l.starting === true) continue
      const key = `${l.grid}\0${l.model}`, anywhere = l.grid === swarm
      const kind = l.kind === 'api' || l.kind === 'shared' ? l.kind : anywhere ? 'local' : 'shared'
      const known = served.get(key) ?? { grid: l.grid, model: l.model, label: text(l.name) ?? l.model, kind, machines: anywhere ? null : new Set<string>(), holders: [] }
      known.machines?.add(String(machine.machineId))
      served.set(key, known)
    }
  }
  for (const machine of fresh) {
    for (const r of list(object(machine.observation).refusedModels)) {
      if (r.grid !== swarm || typeof r.model !== 'string' || typeof r.why !== 'string' || served.has(`${r.grid}\0${r.model}`)) continue
      served.set(`${r.grid}\0${r.model}`, { grid: r.grid, model: r.model, label: text(r.name) ?? r.model, kind: 'local', machines: null, holders: [], note: r.why })
    }
  }
  const agents = new Map(list(state.agents).map(agent => [String(agent.harnessId), text(agent.displayName) ?? text(agent.name) ?? 'an agent']))
  for (const start of list(state.starts)) {
    const request = object(start.request)
    if (typeof request.gridModel !== 'string' || start.error || (start.harnessId && !agents.has(String(start.harnessId)))) continue
    served.get(`${typeof request.gridName === 'string' ? request.gridName : swarm}\0${request.gridModel}`)?.holders
      .push(start.harnessId ? agents.get(String(start.harnessId))! : 'an agent that is starting')
  }
  return served
}

/** Whether [m] can take another agent: a local engine or a model shared with a member takes one, an API model up to [API_BUILDERS]. */
export const takesBuilder = (m: Served) => m.holders.length < (m.kind === 'api' ? API_BUILDERS : 1)

/** The Swarm's served models that take no more agents, and who is on them: what the route says when it offers none. */
export function heldLocalModels(state: Json, now: number = Date.now()): HeldModel[] {
  const addOn = object(state.localModels)
  if (addOn.enabled !== true || typeof addOn.grid !== 'string') return []
  return [...servedModels(state, addOn.grid, now).values()].filter(m => !takesBuilder(m))
    .map(({ model, label, kind, holders }) => ({ model, label, kind, holders }))
}

/** New agents on local models (docs/plans/2026-10-23-swarm-local-models.md), only while the owner has the add-on on and a
 * fresh reading lists the model. One served on the Swarm's grid, an engine of a member's or an API one shares, is reached
 * through the grid relay from any Swarm machine that can start Claude Code or Codex. One on another grid, shared with a
 * machine's owner, only from that machine (owner, 2026-10-23). One agent per local engine, since it answers one
 * conversation at a time; up to [API_BUILDERS] per API model (owner, 2026-10-24). Any task may take one, a review too
 * (project instructions, phase 4): its strength and its note say what it is. */
export function localProbes(state: Json, catalog: Catalog, probes: Probe[], now: number = Date.now()): Probe[] {
  const addOn = object(state.localModels)
  const swarm = addOn.enabled === true && typeof addOn.grid === 'string' ? addOn.grid : null
  if (!swarm) return []
  const served = new Map([...servedModels(state, swarm, now)].filter(([, m]) => takesBuilder(m)))
  if (!served.size) return []
  // One base per machine and engine: the first new-agent row probed there, which carries the machine's refusals and notes.
  const bases = new Map<string, Probe>()
  for (const p of probes) if (p.kind === 'new' && !p.gridModel && !bases.has(`${p.machineId}\0${p.engine}`)) bases.set(`${p.machineId}\0${p.engine}`, p)
  return [...bases.values()].flatMap(base => [...served.values()].filter(m => !m.machines || m.machines.has(base.machineId))
    .map((m): Probe => ({ ...base, model: 'default', effort: 'default', quality: gridStrength(catalog, m.model, m.label), cost: 1, quota: UNKNOWN_QUOTA, known: true,
      refusals: base.refusals.filter(r => !SUBSCRIPTION.test(r)), notes: [...base.notes.filter(n => !SUBSCRIPTION.test(n)), ...(m.note ? [m.note] : [])],
      gridModel: m.model, gridName: m.grid, gridLabel: m.label, gridKind: m.kind })))
}

/** The models a machine served for the Swarm when it last reported, while it is offline now and no other machine serves them:
 *  left out with that reason, so no agent is sent to a dead host (Kimi K3 on a 4090 rig, offered 15 times and never run,
 *  2026-10-29). Only where [localProbes] would offer them. */
export function offlineModels(state: Json, now: number = Date.now()): Array<{ title: string; reason: string }> {
  const addOn = object(state.localModels)
  if (addOn.enabled !== true || typeof addOn.grid !== 'string') return []
  const served = servedModels(state, addOn.grid, now), out: Array<{ title: string; reason: string }> = []
  for (const machine of list(state.machines)) {
    const observed = object(machine.observation)
    if (finite(observed.receivedAt) && now - observed.receivedAt <= LOCAL_FRESH_MS) continue
    const host = text(machine.name)
    for (const l of list(observed.localModels)) {
      if (typeof l.grid !== 'string' || typeof l.model !== 'string' || l.starting === true || served.has(`${l.grid}\0${l.model}`)) continue
      const title = text(l.name) ?? l.model
      if (!out.some(o => o.title === title)) out.push({ title, reason: `Its host${host ? ` ${host}` : ', a machine of this Swarm,'} is offline, so an agent on it would never start.` })
    }
  }
  return out
}

/** What a machine reached directly has, from its capacity read. Its disk is the task folder's, or with none named the disk the
 *  read was asked about (`/`), which still says whether heavy work fits there; whether it has the folder only when one was named. */
function loadOf(resources: Json, agents: number | null, cwd: string | undefined): NonNullable<Probe['load']> {
  return { agents, freeMemoryBytes: finite(resources.memoryTotalBytes) && finite(resources.memoryUsedBytes) ? resources.memoryTotalBytes - resources.memoryUsedBytes : null,
    hasFolder: cwd ? finite(resources.projectDiskFreeBytes) : null, freeDiskBytes: finite(resources.projectDiskFreeBytes) ? resources.projectDiskFreeBytes : null,
    cpuPercent: finite(resources.cpuPercent) ? resources.cpuPercent : null }
}

async function probeMachine(machineId: string, { name: machineName, status, account, pool, folded, unready = READY, stalled: stuck = false, held = heldByStarts([], machineId), access: unreached = [], accessNotes: noted = [] }: { name: string; status: string; account: boolean; pool?: Json; folded?: boolean; unready?: Unready; stalled?: boolean; held?: ReturnType<typeof heldByStarts>; access?: string[]; accessNotes?: string[] },
  members: Json[], allModels: CatalogModel[], catalog: Catalog, a: Assessment, where: Where, open: typeof openDaemon): Promise<Probe[]> {
  const listedEngines = Array.isArray(pool?.engines) ? pool.engines.filter((engine): engine is string => typeof engine === 'string') : []
  const legacy = listedEngines.some(engine => !ENGINES.includes(engine))
  const installed = legacy ? list(object(pool?.observation).quotas).map(quota => quota.engine) : listedEngines
  // A Mac folded into its Harness Team account, or the other way round, offers no new agent of its own (routeTask).
  const models = folded ? [] : pool ? allModels.filter(m => installed.includes(m.engine)) : account ? allModels : []
  const engines = [...new Set([...models.map(m => m.engine), ...members.map(m => String(object(m.configuration).engine) as 'claude' | 'codex')])]
  // A member on a model the catalog does not rate is offered unrated, at strength 1.
  const memberProbe = (m: Json, refusals: string[] = [], quota = UNKNOWN_QUOTA, frame: MemberFrame | null = null, terminalUnverified = false, notes: string[] = []): Probe => {
    const c = object(m.configuration), engine = String(c.engine) as 'claude' | 'codex'
    const model = typeof c.model === 'string' ? c.model : null, effort = typeof c.effort === 'string' ? c.effort : null
    const row = catalogRow(catalog, engine, model, effort, m.engineDefault === true)
    return { kind: 'member', agentId: String(m.id), name: String(m.name ?? 'Member'), machineId, machineName, engine,
      model: model ?? 'default', effort: effort ?? 'default', quality: row?.strength ?? 1, cost: row?.cost ?? 1, ...(row ? {} : { unrated: true as const }),
      quota, activity: 'idle', known: quota.known, refusals, notes, frame, terminalUnverified }
  }
  const newProbe = (m: CatalogModel, refusals: string[], quota: Probe['quota'], known: boolean, load: Probe['load'] = UNKNOWN_LOAD, notes: string[] = []): Probe => ({
    kind: 'new', machineId, machineName, engine: m.engine, model: m.model, effort: m.effort, quality: m.strength, cost: m.cost,
    quota, activity: 'new agent', known, refusals, notes, load })
  const offline = () => models.map(m => newProbe(m, [OFFLINE, ...unreached], UNKNOWN_QUOTA, false))
  const needs = startRequirements(a.needs)
  if (pool) {
    const observed = object(pool.observation), resources = object(observed.resources)
    const fresh = finite(observed.receivedAt) && Date.now() - observed.receivedAt < 45_000
    const quotas = list(observed.quotas)
    const read = (q: Json, extra: { why?: string | null; account?: string } = {}) => quotaOf2({ known: q.known === true,
      windows: list(q.windows).filter(w => finite(w.usedPercent)).map(w => ({ usedPercent: w.usedPercent as number, resetsAt: w.resetsAt, name: text(w.name) ?? undefined })), ...extra })
    const quota = (engine: string): Probe['quota'] => {
      const q = quotas.find(q => q.engine === engine)
      if (!fresh || !q) return UNKNOWN_QUOTA
      return read(q, { why: text(object(observed.quotaReasons)[engine]) })
    }
    // What a new start can use, as its host admits it (reservations.ts): measured, less what starts still starting hold.
    const measuredMemory = finite(resources.memoryTotalBytes) && finite(resources.memoryUsedBytes) ? resources.memoryTotalBytes - resources.memoryUsedBytes : null
    const measuredDisk = finite(resources.projectDiskFreeBytes) ? resources.projectDiskFreeBytes : null
    const freeMemory = measuredMemory === null ? null : measuredMemory - held.memoryBytes, freeDisk = measuredDisk === null ? null : measuredDisk - held.diskBytes
    const setAside = (n: number) => n > 0 ? `, with ${bytes(n)} set aside for agents still starting` : ''
    const blocked = [...(!fresh ? [OFFLINE] : []), ...(pool.paused ? ['New work is paused on this machine.'] : [])]
    const tools = object(observed.tools)
    /** Work for a project its owner does not run here: a new agent runs under the contribution, a member under its own grant. */
    const teammates = (contributorId: unknown) => typeof pool.teammatesRefused === 'string' && contributorId !== pool.projectOwnerId ? [pool.teammatesRefused] : []
    const kept = typeof pool.keptForOthers === 'string' ? [pool.keptForOthers] : []
    /** A note, never a refusal: a teammate's work here runs in the machine owner's own account, whoever's grant an agent has. */
    const ownAccount = typeof pool.ownAccount === 'string' && pool.contributorId !== pool.projectOwnerId ? [pool.ownAccount] : []
    const newReasons = [...blocked, ...kept, ...teammates(pool.contributorId),
      ...(pool.projectUnavailable === true ? ['Its owner must add this machine to the swarm again to support other projects.'] : []),
      ...(pool.repositoryUnavailable === true ? ['Share a repository for this project before starting agents on this machine.'] : []),
      ...(pool.availableSlots === 0 ? ['This machine has no available agent slots.'] : []),
      ...(freeDisk === null || freeDisk < needs.diskBytes ? [`The project has insufficient measured free disk${setAside(held.diskBytes)}.`] : []),
      ...(freeMemory === null || freeMemory < needs.memoryBytes ? [`Insufficient measured free memory${setAside(held.memoryBytes)}.`] : []),
      ...needs.tools.map(t => requiredToolReason(t, tools[t], object(observed.toolProbeErrors)[t])).filter((reason): reason is string => reason !== null),
      ...(needs.devices.length ? ['Required devices have not been reported.'] : []),
      ...unready.all, ...unreached]
    const pushNote = unready.push ? [unready.push] : []
    // What the machine has, for new agents and members alike: heavy work runs on the machine whoever does it (machineFit.ts).
    const load: Probe['load'] = { agents: Array.isArray(observed.runningHarnessIds) ? observed.runningHarnessIds.length : null,
      // Heavy starts stay in: the machine fit holds heavy work placed there itself (machineFit.ts placedHeavyWork, review).
      freeMemoryBytes: measuredMemory === null ? null : measuredMemory - (held.memoryBytes - held.heavyMemoryBytes), hasFolder: finite(resources.projectDiskFreeBytes),
      freeDiskBytes: measuredDisk === null ? null : measuredDisk - (held.diskBytes - held.heavyDiskBytes),
      cpuPercent: finite(resources.cpuPercent) ? resources.cpuPercent : null,
      room: { slots: finite(pool.availableSlots) ? pool.availableSlots : null, freeMemoryBytes: freeMemory, heldMemoryBytes: held.memoryBytes, freeDiskBytes: freeDisk } }
    return [...members.map(m => {
      const engine = String(object(m.configuration).engine), allowance = quota(engine)
      const running = Array.isArray(observed.runningHarnessIds) ? observed.runningHarnessIds.includes(m.harnessId) : null
      const closed = Array.isArray(observed.closedHarnessIds) && observed.closedHarnessIds.includes(m.harnessId)
      return { ...memberProbe(m, fresh ? [...memberRefusals(running, closed, needs.tools, needs.devices, tools, object(observed.devices), object(observed.toolProbeErrors)),
        ...kept, ...teammates(m.contributorId), ...unreached] : [OFFLINE],
        allowance, null, fresh && running === null, [...pushNote, ...usedUp(allowance), ...ownAccount, ...noted]), ...(fresh ? { load } : {}) }
    }),
      ...models.map(m => ({ ...newProbe(m, [...newReasons, ...(unready.engines[m.engine] ? [unready.engines[m.engine]!] : [])], quota(m.engine), fresh && quota(m.engine).known,
        load, [...pushNote, ...(stuck ? [STALLED] : []), ...usedUp(quota(m.engine)), ...ownAccount, ...noted]) }))]
  }
  // The account says this machine is off, so nothing there can run or be asked.
  if (account && status === 'offline') return [...members.map(m => memberProbe(m, [OFFLINE])), ...offline()]
  let target: Daemon
  try { target = await open(where, machineId) } catch {
    // Not being able to open a machine says nothing about the agents already on it; only a new start needs it.
    return [...members.map(m => memberProbe(m, unreached)), ...offline()]
  }
  try {
    const listed = object(await target.request('agents_list', {}, 10_000).catch(() => ({})))
    const frames = list(listed.agents)
    const live = new Set(frames.filter(f => object(f.terminal).available !== false).map(f => String(f.id)))
    // Quota is not required to route: an unknown or used-up allowance only ranks a candidate lower and is said. The start's
    // own requirements are (the hint suggests exactly these).
    const byEngine = new Map<string, Awaited<ReturnType<typeof inspectCapacity>>>()
    for (const engine of engines) {
      byEngine.set(engine, await inspectCapacity(target, { engine, cwd: a.needs.cwd ?? '/', worktree: false,
        requirements: startRequirements(a.needs) }))
    }
    const probes: Probe[] = []
    for (const m of members) {
      const inspected = byEngine.get(String(object(m.configuration).engine))!
      const allowance = quotaOf2(inspected.quota)
      const capacity = object(inspected.capacity)
      const refusals = memberRefusals(live.has(String(m.harnessId)), false, needs.tools, needs.devices,
        object(capacity.tools), object(capacity.devices), object(capacity.toolProbeErrors))
      const frame = frames.find(f => f.id === m.harnessId)
      probes.push({ ...memberProbe(m, [...refusals, ...unreached], allowance, frame ? frameOf(frame) : null, false, usedUp(allowance)),
        load: loadOf(object(capacity.resources), Array.isArray(listed.agents) ? frames.length : null, a.needs.cwd) })
    }
    for (const m of models) {
      const inspected = byEngine.get(m.engine)!
      const resources = object(inspected.capacity.resources)
      // The capacity probe already measured the task's folder (its disk), so the answer is reused, not asked again.
      const load = loadOf(resources, Array.isArray(listed.agents) ? frames.length : null, a.needs.cwd)
      // A machine listed only because an agent runs there may never have cloned the project. When its capacity read succeeded but
      // could not measure the named folder's disk, a missing folder is the likely cause; a failed or unsupported read says nothing.
      const noFolder = !!a.needs.cwd && machineId !== where.machineId && object(inspected.capacity).ok === true && !finite(resources.projectDiskFreeBytes)
      const reasons = noFolder ? inspected.reasons.map(r => r === DISK_UNVERIFIED ? NO_PROJECT_FOLDER : r) : inspected.reasons
      // A machine reached directly says its OS in the same capacity read (lib/machineHardware.ts).
      const os = String(resources.os)
      const unfit = NO_SWARM_AGENTS_ON.includes(os) ? [`Swarm agents do not run on ${os} yet.`] : []
      const allowance = quotaOf2(inspected.quota)
      probes.push(newProbe(m, [...(inspected.allowed ? [] : reasons), ...unfit, ...unready.all, ...unreached], allowance, inspected.unknown.length === 0 && inspected.quota.known, load,
        [...(stuck ? [STALLED] : []), ...usedUp(allowance)]))
    }
    return probes
  } finally { target.close() }
}

/** A note in a candidate's line: its first sentence, cut short. The record for Details keeps it whole. Long enough for the
 *  name or the cause a note carries (which PM an account runs, what a failed start was preparing; review of #3169). */
export function noteClause(note: string): string {
  const first = /^(.*?[^.])(?:\.\s|;\s|\.$|$)/.exec(note.trim())?.[1] ?? note
  return first.length <= NOTE_MAX ? first : `${first.slice(0, NOTE_MAX - 1)}…`
}
const NOTE_MAX = 72, LEFT_OUT_REASON_MAX = 120, WARNING_MAX = 240

/** The section of the instructions headed "Routing" (any level), up to the next heading of its level or higher, with its
 *  own subsections (Models, Machines, Order and quota); null when the instructions have none. */
export function routingSection(text: string): string | null {
  // Line by line, so a shell comment in a fenced block is not taken for a heading (review of #3169).
  const lines = text.split('\n')
  let fenced = false, start = -1, level = 0
  for (const [i, line] of lines.entries()) {
    if (/^\s*(```|~~~)/.test(line)) { fenced = !fenced; continue }
    const head = fenced ? null : /^(#{1,6})[ \t]+(.*?)[ \t]*$/.exec(line)
    if (!head) continue
    if (start >= 0 && head[1]!.length <= level) return lines.slice(start, i).join('\n').trimEnd()
    if (start < 0 && head[2] === 'Routing') { start = i; level = head[1]!.length }
  }
  return start < 0 ? null : lines.slice(start).join('\n').trimEnd()
}

/** What `harness super-tab route` prints of [answer] (task #3294, Ken 2026-11-05): each answer was ~45k characters, the
 *  whole instructions (~30k) and every candidate as an object (~15k), 467 a day in one PM's context. It prints the
 *  instructions' Routing section and revision (the whole text with [fullInstructions]; only the revision when the caller
 *  already read it, [instructionsRead]), each candidate in one line, each machine's id, start folder and room once, and one
 *  line per machine left out. The decision recorded for Details is the whole one ([routeTask]). */
export function routeAnswer(answer: Json, options: { fullInstructions?: boolean; instructionsRead?: number } = {}): Json {
  const { instructions, candidates, leftOut: out, excluded, warnings, p, why, ...rest } = answer
  // An unranked route's why is its next's first sentence; the record keeps it whole.
  const printed: Json = { ...rest, ...(p === null || p === undefined ? {} : { p }), ...(why === undefined || answer.via === 'instructions' || answer.via === 'order' ? {} : { why }) }
  const written = instructions && typeof instructions === 'object' ? object(instructions) : null
  if (written) {
    const notes = Array.isArray(written.notes) ? written.notes.map(n => String(object(n).text ?? n)) : []
    const text = String(written.text ?? ''), routing = routingSection(text)
    printed.instructions = options.fullInstructions || routing === null ? { revision: written.revision, text, notes }
      : options.instructionsRead === written.revision
        // Its notes still come: adding one does not change the revision (backend note.add), and they hold the short-lived
        // routing facts (a machine away today; review of #3169).
        ? { revision: written.revision, unchanged: `You read revision ${written.revision}; it is current. Route with --full-instructions to have it again.`, notes }
        : { revision: written.revision, routing, notes, more: 'The Routing section only: the whole text with the instructions command, or route with --full-instructions. '
          + `Route with --instructions-read ${written.revision} once you have read this revision.` }
  }
  if (Array.isArray(candidates)) {
    // By machine, in the list's order: the machine's id and agents once, then its candidates' lines. The folder a start takes
    // is said once, the one most machines share (a live route: 23 machines, one folder of 85 characters), and on a machine
    // only where it differs. Free slots, memory and disk stay in the record: the route already leaves out what cannot run.
    const rows = candidates.map(object)
    const folders = new Map<string, number>()
    for (const row of rows) if (row.kind === 'new' && typeof row.cwd === 'string') folders.set(row.cwd, (folders.get(row.cwd) ?? 0) + 1)
    const cwd = [...folders].sort((x, y) => y[1] - x[1])[0]?.[0]
    if (cwd) printed.cwd = cwd
    const machines = new Map<string, { machine: string; candidates: string[] }>()
    // By id: two machines of one name are told apart by the machineId their lines say.
    for (const row of rows) {
      const id = String(row.machineId), name = String(row.machineName ?? row.machineId)
      const at = machines.get(id) ?? machines.set(id, { machine: '', candidates: [] }).get(id)!
      if (!at.machine || row.kind === 'new' && row.cwd !== cwd && !at.machine.includes(' · cwd ')) {
        at.machine = [name, `machineId ${row.machineId}`, ...(typeof row.agents === 'number' ? [`${row.agents} agents`] : []),
          ...(row.kind === 'new' && row.cwd && row.cwd !== cwd ? [`cwd ${row.cwd}`] : [])].join(' · ')
      }
      at.candidates.push(String(row.line))
    }
    // Keyed by the machine's line: an object per machine cost 30 characters each (a live route: 21 machines).
    printed.candidates = Object.fromEntries([...machines.values()].map(m => [m.machine, m.candidates]))
  }
  if (Array.isArray(excluded)) {
    // Without a candidate: what is left out of no machine (a named model, the catalog) is said; each machine's is in leftOut.
    const general = excluded.map(object).filter(e => !e.machine).map(e => `${e.title}: ${cut(String(e.reason), LEFT_OUT_REASON_MAX)}`)
    if (general.length) printed.excluded = general
  }
  if (Array.isArray(out)) {
    // Machines left out for the same first reason share its line (a live route: five machines offline, five lines).
    const byReason = new Map<string, string[]>()
    for (const m of out.map(object)) {
      const reasons = Array.isArray(m.reasons) ? m.reasons.map(String) : []
      const reason = cut(reasons[0] ?? 'left out', LEFT_OUT_REASON_MAX)
      byReason.set(reason, [...byReason.get(reason) ?? [], `${m.machine}${reasons.length > 1 ? ` (+${reasons.length - 1} more reasons)` : ''}`])
    }
    printed.leftOut = [...byReason].map(([reason, machines]) => `${machines.join(', ')}: ${reason}`)
  }
  if (Array.isArray(warnings) && warnings.length) printed.warnings = warnings.map(w => cut(String(w), WARNING_MAX))
  return printed
}
const cut = (text: string, max: number) => text.length <= max ? text : `${text.slice(0, max - 1)}…`