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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/** `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)}…`