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.

58.6 KB
Raw Blame
/** Super Tab routing, the pure half (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md).
 * Since the project instructions (docs/plans/2026-10-30-project-instructions-design.md, Routing) the route is advice: it
 * leaves out only what cannot run (an offline or paused machine, an engine signed out, a model not served) and shows every
 * other candidate with its facts: strength, price, quota fit, weekly quota left and its reset, the agents on its machine.
 * Since task #2901 (Ken, 2026-11-04) it ranks nothing and names no pick: PMs took its top line, nearly always Opus or Astra,
 * against the instructions' Order and quota. Candidates come by machine name, then engine
 * (docs/plans/2026-11-04-route-no-ranking-plan.md), and the project's Routing instructions choose. What the route knows beside
 * the facts (a lost task, a stalled machine, a catalog note, a plug-in's finding) is a note on the candidate. */
import { isAbsolute } from 'node:path'
import { claudeAliasForModel } from '../engines/claude/runtimeProfile.js'

type Json = Record<string, unknown>
export type Level = 'low' | 'medium' | 'high'
export type Size = 'small' | 'medium' | 'large'
/** `kind` is a word the agent may give (`ui`, `docs`), recorded so attempts can be compared by the kind of job they were. */
/** `local`: a person asked for a local model by hand, so only models served on the Swarm's grid are considered
 * (docs/plans/2026-10-23-swarm-local-models.md). */
/** `model`: a model a person named, in their words ("deepseek 4.1 flash"); only candidates running it are considered,
 * whatever their strength (owner, 2026-10-23: a Builder on a named API model was ranked below Opus and never offered). */
/** `needs.heavy`: the work runs a heavy build or end-to-end tests on its machine, so it needs more free memory and disk than a
 * start (machineFit.ts). `needs.ci`: the CI jobs the work starts at once, and how many of them on macOS runners, held against
 * the account's running-jobs limit; a need above that limit counts as the limit and the route says so (machineFit.ts). Both are left out when not given, so a request without them answers as before. */
export type HeavyWork = 'build' | 'e2e'
/** `access`: what the work needs to reach, by the names machines list it under (backend superTabs/machineAccess.ts, task #3047). */
export interface Needs { tools: string[]; devices: string[]; access?: string[]; cwd?: string; heavy?: HeavyWork[]; ci?: { jobs: number; macos: number } }
/** `unsized`: the agent gave no size (one from before sizes), so the route keeps both models of each slot ([tierOf]). `ended`:
 *  how many of the task's attempts ended, as the route read them (routeCommand.ts endedAttempts), null when it could not. Both
 *  are the route's own: the record sends neither. */
export interface Assessment { difficulty: Level; risk: Level; size: Size; why: string; kind?: string; local?: boolean; model?: string; needs: Needs; unsized?: true
  ended?: number | null }
/** A model of the reviewed catalog (backend superTabs/catalog.ts): how strong it is, what it costs, and whether it is offered
 * when nobody names it. */
export interface CatalogModel { engine: 'claude' | 'codex'; model: string; effort: string; strength: number; cost: number; offered: boolean; engineDefault?: true; note?: string }
/** Why a Codex row at `default` model or effort is never offered. A backend from before task #2972 still serves one: it ran whatever
 *  the account's CLI defaulted to (gpt-6-luna on one owner's Mac), 67 of 71 Codex picks in a day, and no one rated that. */
export const CODEX_DEFAULT_NOT_OFFERED = 'Codex at its default model or effort is not offered: it runs whatever the account\'s CLI chooses. Start the catalog\'s named models.'
/** The catalog's models and how strong the models served on the Swarm's grid count: the first named row whose every word is
 * in a model's name, else `strength`. */
export interface Catalog { models: CatalogModel[]; grid: { strength: number; models: Array<{ model: string; strength: number }> } }
/** One usage window, named by the reader (`5-hour`, `weekly`); `leftPercent` is what remains of it. */
export interface QuotaWindow { name: string | null; leftPercent: number; resetsAt: number | null }
/** `leftPercent` and `resetsAt` are the tightest window's; `windows` is every window. `account` is the reading's hashed
 * account key, which models on one subscription share. `metered` is an engine on an API key or gateway: known, with no
 * usage window to run out. */
export interface Quota { known: boolean; leftPercent: number | null; resetsAt: number | null; windows?: QuotaWindow[]; account?: string; metered?: true
  /** Why an unknown allowance could not be read, as its machine said (cli superTabs/capacity.ts quotaUnknownReason). */
  why?: string }
/** The task's folder as the routing agent's machine sees it. `unknown` means it could not be read, `none` that it is not a
 * repository, `missing` that this machine has no such folder (a member elsewhere may). */
export interface TaskFolder { cwd: string; kind: 'git' | 'none' | 'missing' | 'unknown'; name: string | null; root: string | null; remote: string | null }
/** What a member's `agents_list` frame says it is working on; every field is null when the frame does not say. */
export interface MemberFrame { title: string | null; project: string | null; cwd: string | null; root: string | null; remote: string | null; branch: string | null; updatedAt: number | null }
/** What a machine offers an agent. Each field is null when it could not be read; `freeDiskBytes` (the project's disk) and
 * `cpuPercent` are absent where the probe did not read them. */
/** What a new start on a machine can use, as its host admits it: the Swarm's free agent slots there, and free memory and disk
 *  less what starts still starting hold (routeCommand.ts heldByStarts). */
export interface MachineRoom { slots: number | null; freeMemoryBytes: number | null; heldMemoryBytes: number; freeDiskBytes: number | null }
/** `freeMemoryBytes` and `freeDiskBytes` leave heavy starts in, which the machine fit holds itself (machineFit.ts
 *  placedHeavyWork); `room` is what a start can use. */
export interface MachineLoad { agents: number | null; freeMemoryBytes: number | null; hasFolder: boolean | null; freeDiskBytes?: number | null; cpuPercent?: number | null
  room?: MachineRoom }
export interface Probe {
  kind: 'member' | 'new'; agentId?: string; name?: string; machineId: string; machineName: string
  /** `quality` is the catalog's strength, 1 for a model it does not rate (`unrated`). */
  engine: 'claude' | 'codex'; model: string; effort: string; quality: number; cost: number
  quota: Quota; activity: string; known: boolean
  /** What makes it unable to run: it is left out with these. */
  refusals: string[]
  /** What the agent choosing should know of it (a lost task, a stalled machine, the catalog's note): shown, never a filter. */
  notes: string[]
  /** A model the catalog does not rate: a person named it, or a member runs it. */
  unrated?: true
  /** Members: the frame (null when it could not be read), whether the member is in the task's repository, and its earlier work in this Super Tab. */
  frame?: MemberFrame | null; repo?: 'same' | 'different' | 'unknown'; earlier?: Array<{ group: string; groupId?: string; outcome: string }>
  terminalUnverified?: boolean
  /** What the machine has: for new agents, and for members where their machine's reading is known. */
  load?: MachineLoad
  /** A new agent on a model served on the Swarm's grid: free, reached through the grid relay, `model`/`effort` `default`.
   *  [gridKind]: a member's engine (`local`), a member's API (`api`), or a model shared with this machine's owner. */
  gridModel?: string; gridName?: string; gridLabel?: string; gridKind?: 'local' | 'api' | 'shared'
}
export interface Attempt { agent: string; outcome: string; result?: string }
export interface RecentRoute { title: string; via?: string; outcome: string | null }
/** The latest start is already in the route's authorized snapshot. Say what kind of setup failed, never copy its reason:
 *  the coordinator may read paths/account details there that the route log's other readers must not learn. */
export function recentStartNotes(starts: Json[], machineId: string, engine: string, now: number): string[] {
  for (let i = starts.length - 1; i >= 0; i--) {
    const start = starts[i]!, request = object(start.request)
    if (request.machineId !== machineId || request.engine !== engine) continue
    const at = finite(start.dispatchedAt) ? start.dispatchedAt : start.requestedAt
    if (start.harnessId || typeof start.error !== 'string' || !finite(at) || now - at >= 30 * 60_000) return []
    const reason = start.error
    const category = /GitHub.*token|token.*GitHub/i.test(reason) ? 'GitHub access'
      : /clone|repository.*(?:unavailable|access)|access.*repository/i.test(reason) ? 'the repository'
        : /no commits?|commit.*(?:missing|not found|unknown)/i.test(reason) ? 'a missing commit'
          : /folder|directory|checkout/i.test(reason) ? 'the project folder'
            : /permission.*(?:flag|mode)/i.test(reason) ? 'permission flags'
              : /does not offer|model.*(?:unavailable|not supported)/i.test(reason) ? 'the requested model'
                : /(?:tool|spawn |command not found|not installed)/i.test(reason) ? 'a missing tool' : null
    return category ? [`Its last start failed while preparing ${category}. The start has the details; this does not suspend the engine.`] : []
  }
  return []
}
type Window = '5-hour' | 'weekly'
/** How a candidate's account would carry the task, as the decision log keeps it. */
export interface Fit { status: 'fits' | 'unknown' | 'short'; coverage: number | null; effectiveCost: number; expiring: number; spend: Record<Window, number>; account: string }
/** A pick still at work: it holds part of its account's quota until its run time is over. */
export interface Commitment { account: string; spend: Partial<Record<Window, number>>; size: Size; createdAt: number }
export interface Shown extends Probe { id: string; title: string; label: string; fit: Fit }
/** A candidate left out and why; [machine] names its machine, absent for a model that is not offered anywhere. */
export interface Excluded { title: string; reason: string; machine?: string }
/** `floor` and `belowFloor` are what the decision log still takes (backend routeRecord.ts): there is no floor, so 1 and false.
 *  `short` says when no candidate is expected to cover the task on its quota. `adjusted`: a plug-in noted a candidate or left
 *  one out ([RoutePlugin]). `warnings`: the plug-ins that failed and were left out of this route. */
export interface Choice { shown: Shown[]; excluded: Excluded[]; floor: 1; belowFloor: false; short?: string; adjusted?: true; warnings?: string[] }
export type NoCandidate = { error: 'NO_CANDIDATE'; excluded: Excluded[]; warnings?: string[] }

/** What a plug-in sees of the route it ranks: the task, the time, the catalog, and the picks still at work. */
export interface RouteContext { readonly assessment: Assessment; readonly now: number; readonly catalog: Catalog; readonly open: readonly Commitment[] }
/** A plug-in's word on one candidate. `strength` and `cost` say which way the plug-in's finding leans, in the catalog's units;
 *  since task #2901 they move nothing (the route ranks nothing), and its `reason` is what the agent choosing reads, on the
 *  candidate's notes as "name: reason". Neither changes what the candidate is shown and recorded as (its strength, cost and fit
 *  stay as measured). `refuse` leaves it out, only for a fact that it cannot run there. The reason holds only what every
 *  reader of the Swarm's route log may see: never one member's raw usage or anything private to a person or chat. */
export interface Adjustment { reason: string; strength?: number; cost?: number; refuse?: true }
/** One piece of the route that is not its own (Scholes's goals, pieces 3 to 6: measured cost and results, more model
 *  candidates, machine fit, window pull). Plug-ins run in their list's order: each `candidates` call sees the probes so far,
 *  earlier plug-ins' among them, and returns more, which every rule of [choose] then treats like the others; `adjust` judges
 *  each candidate that can run, after its quota fit is known. A plug-in must be pure and synchronous: what it needs from
 *  outside is read before the route and given to it when it is made. One that throws, or answers what cannot be ranked, is
 *  left out of the whole route, so it never judges some candidates and not others, and the answer names it. */
export interface RoutePlugin {
  readonly name: string
  candidates?(probes: readonly Probe[], context: RouteContext): Probe[]
  adjust?(candidate: Readonly<Probe & { fit: Fit }>, context: RouteContext): Adjustment | null
}
/** How long one plug-in may take over a route's candidates, per step. Plug-ins are pure and synchronous, so a route of a few
 *  dozen candidates takes them well under a millisecond; one over this is doing work it should have done before the route
 *  (Lead, 10-31: a plug-in that runs too long is skipped). A plug-in that never returns cannot be stopped from inside: that is
 *  why they must be synchronous and read nothing. */
export const PLUGIN_BUDGET_MS = 200
export const pluginSkipped = (name: string, why: string) => `The routing plug-in "${cut(name, 80)}" was skipped: ${why}. The route is shown without it.`
const FAILED = 'it failed', SLOW = `it took longer than ${PLUGIN_BUDGET_MS} ms`
/** Runs [step] for one plug-in, timed: its answer, or why it is skipped. Its error text is never kept, since it may hold
 *  anything (a path, a token). */
function timed<T>(step: () => T, valid: (answer: T) => boolean): { answer: T } | { why: string } {
  const started = performance.now()
  try {
    const answer = step()
    if (performance.now() - started > PLUGIN_BUDGET_MS) return { why: SLOW }
    return valid(answer) ? { answer } : { why: FAILED }
  } catch { return { why: FAILED } }
}
const isProbe = (p: unknown): p is Probe => {
  const v = object(p)
  return typeof v.machineId === 'string' && typeof v.machineName === 'string' && ENGINES.includes(String(v.engine)) && typeof v.model === 'string'
    && typeof v.effort === 'string' && finite(v.quality) && finite(v.cost) && Array.isArray(v.refusals) && Array.isArray(v.notes) && !!v.quota
}
const baseKey = (p: Pick<Probe, 'machineId' | 'engine'>) => `${p.machineId}\0${p.engine}`
/** A plug-in's candidate as the route may consider it: a new agent standing on a machine and engine the route probed itself
 *  ([bases]), with that probe's refusals, notes, load and quota reading (a model on the grid keeps its own quota, as
 *  routeCommand.ts localProbes does), so it can never bring back a choice the route rules out. Otherwise why it is left out. */
function anchored(added: Probe, bases: Map<string, Probe>, name: string): Probe | Excluded {
  const out = (reason: string): Excluded => ({ title: titleOf(added), reason: `${cut(name, 80)}: ${reason}`, machine: added.machineName })
  if (added.kind !== 'new') return out('a plug-in adds new agents only; it adjusts the agents the route found.')
  const base = bases.get(baseKey(added))
  if (!base) return out(`this route offers no new agent on ${ENGINE[added.engine]} on ${added.machineName}, so one added there is left out.`)
  const { agentId: _a, name: _n, frame: _f, repo: _r, earlier: _e, terminalUnverified: _t, ...own } = added
  const more = (theirs: string[], ours: string[]) => [...theirs, ...ours.filter(x => !theirs.includes(x))]
  return { ...own, kind: 'new', machineName: base.machineName, activity: base.activity, known: base.known, ...(base.load ? { load: base.load } : {}),
    quota: added.gridModel ? added.quota : base.quota, refusals: more(base.refusals, added.refusals), notes: more(base.notes, added.notes) }
}
/** The probes with each plug-in's added candidates ([anchored]), in the plug-ins' order, and those left out. A plug-in whose
 *  answer is not a list of probes, or that runs too long, adds nothing and is named in [warnings]. */
function withPluginCandidates(given: Probe[], plugins: readonly RoutePlugin[], context: RouteContext, warnings: string[]): { probes: Probe[]; out: Excluded[] } {
  const bases = new Map<string, Probe>()
  for (const p of given) if (p.kind === 'new' && !p.gridModel && !bases.has(baseKey(p))) bases.set(baseKey(p), p)
  let probes = given
  const out: Excluded[] = []
  for (const plugin of plugins) {
    if (!plugin.candidates) continue
    const run = timed(() => plugin.candidates!(probes, context) as unknown, added => Array.isArray(added) && added.every(isProbe))
    if ('why' in run) { warnings.push(pluginSkipped(plugin.name, run.why)); continue }
    const placed = (run.answer as Probe[]).map(p => anchored(p, bases, plugin.name))
    probes = [...probes, ...placed.filter((p): p is Probe => 'engine' in p)]
    out.push(...placed.filter((p): p is Excluded => !('engine' in p)))
  }
  return { probes, out }
}
const validAdjustment = (x: Adjustment | null): x is Adjustment | null => x === null || (typeof x === 'object' && typeof x.reason === 'string'
  && !!x.reason.trim() && (x.strength === undefined || finite(x.strength)) && (x.cost === undefined || finite(x.cost))
  && (x.refuse === undefined || x.refuse === true))
/** Every plug-in's adjustments of [ranked], plug-in by plug-in in the list's order: one that throws, runs too long or answers
 *  what cannot be ranked for any candidate is dropped for all of them and named in [warnings]. */
function pluginAdjustments<T extends Probe & { fit: Fit }>(ranked: T[], plugins: readonly RoutePlugin[], context: RouteContext,
  warnings: string[]): Array<Array<{ name: string; adjustment: Adjustment }>> {
  const each = ranked.map(() => [] as Array<{ name: string; adjustment: Adjustment }>)
  for (const plugin of plugins) {
    if (!plugin.adjust) continue
    const run = timed(() => ranked.map(p => plugin.adjust!(p, context)), answers => answers.every(validAdjustment))
    if ('why' in run) { warnings.push(pluginSkipped(plugin.name, run.why)); continue }
    run.answer.forEach((adjustment, i) => { if (adjustment) each[i]!.push({ name: plugin.name, adjustment }) })
  }
  return each
}
/** What the route says of its candidates: no pick (task #2901). `via` `instructions`: the project's Routing instructions choose;
 *  `only`: one candidate can run. */
/** `order`: the route's pick by the Routing order (routePick.ts, task #3576), with `pick` (a candidate's id) and `reasons`, one per step. */
export interface Verdict { via: 'instructions' | 'only' | 'order'; p: null; why: string; pick?: string; reasons?: string[] }

const LEVELS: Level[] = ['low', 'medium', 'high']
const HEAVY_WORK: unknown[] = ['build', 'e2e'] satisfies HeavyWork[]
/** Run time and spend per window by task size, for a catalog row of cost 2 (owner's table, 2026-10-21). */
export const SIZES: Record<Size, { minutes: number; spend: Record<Window, number> }> = {
  small: { minutes: 20, spend: { '5-hour': 10, weekly: 1 } },
  medium: { minutes: 60, spend: { '5-hour': 30, weekly: 4 } },
  large: { minutes: 180, spend: { '5-hour': 50, weekly: 8 } },
}
const WINDOWS: Window[] = ['5-hour', 'weekly']
const MAX_SHOWN = 12
/** The most rows a decision keeps (backend superTabs/routeRecord.ts), past [MAX_SHOWN] only for every engine on every machine; a
 *  backend from before them keeps [MAX_SHOWN] (routeCommand.ts routeTask). */
export const RECORD_MAX = 64
export const OLD_RECORD_MAX = MAX_SHOWN
const ENGINE = { claude: 'Claude', codex: 'Codex' } as const
const ENGINES = Object.keys(ENGINE)
const cut = (text: string, max: number) => text.length <= max ? text : `${text.slice(0, max - 1)}…`
const object = (v: unknown): Json => v && typeof v === 'object' && !Array.isArray(v) ? v as Json : {}
const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v)

/** The catalog the tab's routing read serves beside its policy (backend superTabs/catalog.ts catalogRead), or, from an older
 * backend that serves only the policy, the same models read off it: a row's quality is its strength and `enabled` whether it
 * is offered. A row of another engine (OpenCode, Kilo) or of no shape is dropped; nothing readable is an empty catalog. */
export function catalogFrom(effective: Json): Catalog {
  const catalog = object(effective.catalog), policy = object(effective.policy)
  const served = Array.isArray(catalog.models)
  const rows = (served ? catalog.models : Array.isArray(policy.models) ? policy.models : []) as unknown[]
  const models = rows.map(object).flatMap((m): CatalogModel[] => {
    const strength = served ? m.strength : m.quality, offered = served ? m.offered : m.enabled
    if (!ENGINES.includes(String(m.engine)) || typeof m.model !== 'string' || typeof m.effort !== 'string' || !finite(strength) || !finite(m.cost)) return []
    // A Codex row at `default` model or effort stays for rating a member launched on the engine's own model, but is never offered.
    const unnamed = m.engine === 'codex' && (m.model === 'default' || m.effort === 'default')
    return [{ engine: m.engine as CatalogModel['engine'], model: m.model, effort: m.effort, strength, cost: m.cost, offered: offered === true && !unnamed,
      ...(served && m.engineDefault === true ? { engineDefault: true as const } : {}),
      ...(unnamed ? { note: CODEX_DEFAULT_NOT_OFFERED } : served && typeof m.note === 'string' && m.note ? { note: m.note } : {}) }]
  })
  const grid = served ? object(catalog.grid) : object(policy.localModels)
  const gridRows = (Array.isArray(grid.models) ? grid.models : []) as unknown[]
  return { models, grid: { strength: finite(served ? grid.strength : grid.quality) ? (served ? grid.strength : grid.quality) as number : 1,
    models: gridRows.map(object).flatMap(r => { const s = served ? r.strength : r.quality; return typeof r.model === 'string' && finite(s) ? [{ model: r.model, strength: s }] : [] }) } }
}

export function parseAssessment(value: unknown): Assessment | string {
  const v = (value && typeof value === 'object' ? value : {}) as Record<string, unknown>
  if (!LEVELS.includes(v.difficulty as Level)) return 'Set difficulty to low, medium or high.'
  if (!LEVELS.includes(v.risk as Level)) return 'Set risk to low, medium or high.'
  // Agents from before sizes send none; their tasks are taken for medium.
  const size = v.size ?? 'medium'
  if (!Object.hasOwn(SIZES, String(size))) return 'Set size to small, medium or large.'
  const why = typeof v.why === 'string' ? v.why.trim() : ''
  if (!why || why.length > 300) return 'Give why in 1 to 300 characters.'
  const needs = (v.needs && typeof v.needs === 'object' ? v.needs : {}) as Record<string, unknown>
  const list = (x: unknown) => Array.isArray(x) && x.every(i => typeof i === 'string') ? x as string[] : []
  const cwd = needs.cwd
  if (cwd !== undefined && (typeof cwd !== 'string' || !isAbsolute(cwd))) return 'needs.cwd must be an absolute path.'
  if (v.kind !== undefined && (typeof v.kind !== 'string' || !/^[a-z][a-z0-9-]{0,39}$/.test(v.kind))) return 'Set kind to one lowercase word, such as ui or docs.'
  if (v.local !== undefined && typeof v.local !== 'boolean') return 'Set local to true only when a person asked for a local model.'
  if (v.model !== undefined && (typeof v.model !== 'string' || !words(v.model).length || v.model.length > 200)) return 'Set model to the model a person named, in their words.'
  const access = needs.access === undefined ? [] : Array.isArray(needs.access) && needs.access.every(n => typeof n === 'string' && n.trim() && n.trim().length <= 60)
    ? [...new Set((needs.access as string[]).map(n => n.trim().replace(/\s+/g, ' ')))] : null
  if (!access) return 'Set needs.access to a list of names of up to 60 characters, such as ["Lamp"].'
  const heavy = needs.heavy
  if (heavy !== undefined && (!Array.isArray(heavy) || !heavy.every(h => HEAVY_WORK.includes(h)))) return 'Set needs.heavy to a list of build and e2e.'
  const ci = needs.ci === undefined ? undefined : object(needs.ci)
  const count = (n: unknown, max: number) => Number.isInteger(n) && (n as number) >= 0 && (n as number) <= max
  if (ci && (!count(ci.jobs, 100) || (ci.jobs as number) < 1 || (ci.macos !== undefined && !count(ci.macos, ci.jobs as number)))) {
    return 'Set needs.ci to the CI jobs the work starts, as {"jobs": 1 to 100, "macos": how many of them run on macOS}.'
  }
  return { difficulty: v.difficulty as Level, risk: v.risk as Level, size: size as Size, why, ...(v.size === undefined ? { unsized: true as const } : {}),
    ...(v.kind ? { kind: v.kind as string } : {}),
    ...(v.local === true ? { local: true } : {}), ...(typeof v.model === 'string' ? { model: v.model.trim() } : {}),
    needs: { tools: list(needs.tools), devices: list(needs.devices), ...(access.length ? { access } : {}), ...(cwd ? { cwd } : {}),
      ...(Array.isArray(heavy) && heavy.length ? { heavy: [...new Set(heavy as HeavyWork[])] } : {}),
      ...(ci ? { ci: { jobs: ci.jobs as number, macos: (ci.macos as number | undefined) ?? 0 } } : {}) } }
}

/** Claude sends ISO strings, Codex epoch seconds; anything above 1e10 is already milliseconds. */
function resetMs(value: unknown): number | null {
  if (typeof value === 'number' && Number.isFinite(value)) return value > 1e10 ? value : value * 1000
  if (typeof value === 'string') { const ms = Date.parse(value); return Number.isFinite(ms) ? ms : null }
  return null
}
export function quotaOf2(q: { known: boolean; windows: Array<{ usedPercent: number; resetsAt: unknown; name?: string }>; account?: string | null; why?: string | null }): Quota {
  const account = q.account ? { account: q.account } : {}
  if (!q.known) return { known: false, leftPercent: null, resetsAt: null, ...account, ...(q.why ? { why: q.why } : {}) }
  if (!q.windows.length) return { known: true, leftPercent: null, resetsAt: null, metered: true, ...account }
  const tightest = q.windows.reduce((x, y) => y.usedPercent > x.usedPercent ? y : x)
  return { known: true, leftPercent: Math.max(0, 100 - tightest.usedPercent), resetsAt: resetMs(tightest.resetsAt),
    windows: q.windows.map(w => ({ name: w.name ?? null, leftPercent: Math.max(0, 100 - w.usedPercent), resetsAt: resetMs(w.resetsAt) })), ...account }
}

/** Whether a member's checkout is the task's repository: the same remote wherever it lives, else the same root on one
 * machine. Paths on two machines say nothing without a remote. Undefined when no folder was named. */
export function repoMatch(folder: TaskFolder | null, frame: MemberFrame | null, sameMachine: boolean): Probe['repo'] | undefined {
  if (!folder) return undefined
  if (!frame || folder.kind === 'unknown') return 'unknown'
  if (folder.remote && frame.remote) return folder.remote === frame.remote ? 'same' : 'different'
  const theirs = frame.root ?? frame.cwd
  // A frame that names no checkout says nothing. The folder named is a path on the machine that will run the task, so a
  // member standing in exactly it is in it, wherever the routing agent is.
  if (!theirs) return 'unknown'
  if (theirs === folder.cwd || frame.cwd === folder.cwd) return 'same'
  // Other paths on two machines say nothing without a remote.
  if (!sameMachine) return 'unknown'
  return (folder.root ?? folder.cwd) === theirs ? 'same' : 'different'
}

/** A repository's name for comparing two addresses of it: host and path, lowercase, without credentials, port or `.git`,
 * the same over HTTPS and SSH. Null for a folder on disk or an address it cannot read. A machine reports its checkouts'
 * origins this way (machines.ts readCheckouts), so no credential in an origin leaves it. */
export function repositoryKey(url: string): string | null {
  const text = url.trim()
  // Only the host and the path are kept: userinfo, a port, a query and a fragment can all carry what is not the repository's
  // name, a token among them (review of #1743).
  const scp = /^[\w.-]+@([\w.-]+):(?!\/)([^?#]+)/.exec(text)
  let host: string | undefined, path: string | undefined
  if (scp) [, host, path] = scp
  else {
    try {
      const parsed = new URL(text)
      if (['http:', 'https:', 'ssh:', 'git:'].includes(parsed.protocol)) [host, path] = [parsed.hostname, decodeURIComponent(parsed.pathname)]
    } catch { /* Not an address: a folder on disk, or nothing readable. */ }
  }
  const clean = path?.replace(/^\/+|\/+$/g, '').replace(/\.git$/i, '')
  return host && clean ? `${host}/${clean}`.toLowerCase() : null
}

/** A member's model is what its engine reported after work: Claude's full id (`claude-opus-4-7`, `claude-sonnet-4-5[1m]`),
 * Codex's slug (`gpt-5.5`). The catalog names Claude families and Codex's default model, so the id is reduced to its family
 * first. Its row: the exact one, else the model's at another effort, else the engine's named default when the agent was
 * launched on the engine's own model ([engineDefault]) and is no small variant; otherwise none, so a small Codex variant is
 * never taken for a strong one (review of #2137). */
export function catalogRow(c: Catalog, engine: string, model: string | null, effort: string | null, engineDefault = false): CatalogModel | null {
  const name = engine === 'claude' && model ? claudeAliasForModel(model.replace(/\[1m\]$/i, '')) ?? model : model ?? 'default'
  // The engine's own model is the catalog's named default (`engineDefault`), else a `default` row of an older backend.
  const rowOf = (named: string) => named === 'default' ? c.models.find(m => m.engine === engine && m.engineDefault) ?? c.models.find(m => m.engine === engine && m.model === 'default')
    : c.models.find(m => m.engine === engine && m.model === named && m.effort === (effort ?? 'default'))
    ?? c.models.find(m => m.engine === engine && m.model === named)
  // A small model it reports is never promoted by its launch (review of ee4ee6c9a).
  return rowOf(name) ?? (engineDefault && !SMALL.test(model ?? '') ? rowOf('default') : undefined) ?? null
}
/** How strong the catalog rates a model ([catalogRow]), or null when it does not. */
export const strengthOf = (c: Catalog, engine: string, model: string | null, effort: string | null, engineDefault = false): number | null =>
  catalogRow(c, engine, model, effort, engineDefault)?.strength ?? null
/** A small variant by its name: a mini or a nano (backend superTabs/rules.ts). */
const SMALL = /(^|[^a-z0-9])(mini|nano)([^a-z0-9]|$)/i

export const KIND_WORD = { local: 'local', api: 'API', shared: 'shared' } as const
const runs = (p: Probe) => p.gridModel ? `${ENGINE[p.engine]} on ${p.gridLabel ?? p.gridModel} (${KIND_WORD[p.gridKind ?? 'local']})` : `${ENGINE[p.engine]} ${p.model} ${p.effort}`
/** A name's words for matching: lowercase letters and digits, "4.1" read as "41". */
const words = (text: string) => text.toLowerCase().split(/[^a-z0-9.]+/).map(w => w.replace(/\./g, '')).filter(Boolean)
/** How strong a grid model counts: the first of the catalog's named grid rows whose every word is in its id or label (Kimi K3
 *  and DeepSeek v4.1 at 2), else the grid's own strength. */
export function gridStrength(c: Catalog, model: string, label = ''): number {
  const name = words(`${model} ${label}`).join('')
  return c.grid.models.find(row => words(row.model).every(w => name.includes(w)))?.strength ?? c.grid.strength
}
/** Whether [p] runs the model a person named: every word of theirs is in its model's name. */
function runsNamed(p: Pick<Probe, 'engine' | 'model' | 'gridModel' | 'gridLabel'>, named: string): boolean {
  const name = words([p.gridModel ?? p.model, p.gridLabel ?? '', ENGINE[p.engine]].join(' ')).join('')
  return words(named).every(w => name.includes(w))
}
const NAMED_NONE = (named: string) => `No candidate runs "${named}". Share it with the Swarm (Your models), or check its name.`
/** Whether a person's words name [model]: every word of theirs is in its name, or every word of its name is in theirs
 *  ("Kimi" and "moonshotai/kimi-k3" both name the grid row "kimi k3"). */
function names(model: string, named: string): boolean {
  const ours = words(model), theirs = words(named)
  return !!ours.length && (theirs.every(w => ours.join('').includes(w)) || ours.every(w => theirs.join('').includes(w)))
}
/** A named model the catalog does not list is offered unrated, on Claude Code when its name says Claude, else on Codex
 *  (project instructions, phase 4, decision 15). A third-party model behind Claude Code gets Codex; it can still be started
 *  by hand. */
const CLAUDE_NAMES = /claude|opus|sonnet|haiku|fable/i
export const UNRATED = 'The catalog does not rate this model.'

/** How many agents may run on one API model a member shares: the share answers four requests at once
 * (cli/src/lib/swarmApiShares.ts CONCURRENCY), unlike a local engine, which answers one conversation at a time. */
export const API_BUILDERS = 4

/** A model served for the Swarm that takes no more agents, and who is on it (routeCommand.ts heldLocalModels). */
export interface HeldModel { model: string; label: string; kind: 'local' | 'api' | 'shared'; holders: string[] }

/** Why a held model is not offered, and what frees it: a model in use reads as unshared otherwise (owner, 2026-10-24). */
function heldReason(m: HeldModel): string {
  const who = m.holders.length === 1 ? `${m.holders[0]} is on it` : `${m.holders.slice(0, -1).join(', ')} and ${m.holders.at(-1)} are on it`
  const limit = m.kind === 'api' ? `an API model takes ${API_BUILDERS} agents at a time` : 'a local model serves one agent at a time'
  return `"${m.label}" is shared with the Swarm, but ${who}: ${limit}. Assign the work to ${m.holders.length === 1 ? 'that agent once it is free, or stop it' : 'one of them once it is free, or stop one'} to free the model.`
}
const titleOf = (p: Probe) => cut(`${p.kind === 'member' ? p.name ?? 'Member' : 'New agent'} · ${runs(p)} · ${p.machineName}`, 160)
/** A reset or a last activity is told as how far away it is, which reads the same whenever the log is opened. */
function span(ms: number): string {
  if (ms < 3_600_000) return `${Math.max(1, Math.round(ms / 60_000))}m`
  // Under ten hours, half an hour decides whether a task fits before the reset, so it keeps its minutes (4h30).
  if (ms < 10 * 3_600_000) {
    const tens = Math.round(ms / 600_000), h = Math.floor(tens / 6), m = tens % 6
    return m ? `${h}h${m}0` : `${h}h`
  }
  if (ms < 48 * 3_600_000) return `${Math.round(ms / 3_600_000)}h`
  return `${Math.round(ms / 86_400_000)} days`
}
const resetsIn = (resetsAt: number, now: number) => span(Math.max(0, resetsAt - now))
/** When a weekly window resets, to the hour past two days ("6d13h"): the PM paces its own account by the day since its reset
 *  (project instructions, 2026-11-03), and "7 days", a whole day either way, left it half a day off. */
function weeklyResetsIn(resetsAt: number, now: number): string {
  const ms = Math.max(0, resetsAt - now)
  if (ms < 48 * 3_600_000) return span(ms)
  const hours = Math.round(ms / 3_600_000), days = Math.floor(hours / 24)
  return hours % 24 ? `${days}d${hours % 24}h` : `${days}d`
}
function quotaText(q: Quota, now: number): string {
  if (q.metered) return 'quota metered'
  if (!q.known || q.leftPercent === null) return q.why ? `quota unknown (${q.why})` : 'quota unknown'
  if (q.windows?.length) {
    return `quota ${q.windows.map(w => `${w.name ?? 'window'} ${Math.round(w.leftPercent)}% left${w.resetsAt === null ? '' : ` (resets in ${resetsIn(w.resetsAt, now)})`}`).join(', ')}`
  }
  if (q.resetsAt === null) return `quota ${Math.round(q.leftPercent)}% left`
  return `quota ${Math.round(q.leftPercent)}% left, resets in ${resetsIn(q.resetsAt, now)}`
}
export const bytes = (n: number) => n >= 1e9 ? `${(n / 1e9).toFixed(1)} GB` : `${Math.round(n / 1e6)} MB`
/** What a member is doing and has done, or one phrase saying it is not known. */
function memberText(p: Probe, now: number): string[] {
  const f = p.frame
  const repo = p.repo ? [p.repo === 'unknown' ? 'repo unknown' : `${p.repo} repo`] : []
  if (!f) return [...repo, 'activity unknown']
  const where = [f.project && cut(f.project, 40), f.branch && `branch ${cut(f.branch, 40)}`].filter(Boolean).join(', ')
  return [...repo, ...(f.title ? [`on "${cut(f.title, 80)}"`] : []), ...(where ? [f.project ? `in ${where}` : where] : []),
    f.updatedAt === null ? 'last active unknown' : `last active ${span(Math.max(0, now - f.updatedAt))} ago`]
}
function machineText(load: MachineLoad): string[] {
  return [...(load.hasFolder === null ? [] : [load.hasFolder ? 'has the task folder' : 'no task folder']),
    load.agents === null ? 'agents running unknown' : `${load.agents} ${load.agents === 1 ? 'agent' : 'agents'} running`,
    load.freeMemoryBytes === null ? 'free memory unknown' : `${bytes(load.freeMemoryBytes)} memory free`]
}
/** The most telling parts come first and the least last, because the log's limit cuts the end. The notes come right after
 *  the fit: they are what a ranking alone does not say. */
const labelOf = (p: Probe & Sized, now: number) => cut([
  p.kind === 'member' ? `Member ${cut(p.name ?? '', 40)}`.trim() : 'New agent', runs(p), `${p.unrated ? 'unrated' : `strength ${p.quality}`}, cost ${p.cost}`,
  p.text, ...p.notes.map(n => cut(n, 200)), cut(p.machineName, 40), p.activity, ...(p.kind === 'member' ? memberText(p, now) : p.load ? machineText(p.load) : []),
  ...(p.earlier?.length ? [`earlier here: ${p.earlier.slice(0, 3).map(e => `${cut(e.group, 40)} ${e.outcome}`).join('; ')}`] : []), quotaText(p.quota, now),
].join(' · '), 640)

interface Measured { name: Window; usable: number; needed: number; resetsIn: number | null }
/** A probe's fit, its tightest window (the one that runs out first) and the sentence the log keeps. */
interface Sized { fit: Fit; tight: Measured | null; text: string }
const pct = (n: number) => `${Math.round(n)}%`
const round = (n: number) => Math.round(n * 100) / 100

/** The account a probe's work spends: a local model's node, its quota reading's account, else its machine's engine. */
export function accountOf(p: Probe): string {
  return p.gridModel ? `local:${p.gridName ?? ''}:${p.gridModel}` : p.quota.account ?? `${p.machineId}:${p.engine}`
}

/** A member builds in its own worktree, so one in another repository would build there (Diego, 2026-10-30, #2377). Both
 *  checkouts are compared as host and path (repoMatch), so the same repository over SSH and HTTPS is not "different". */
export const OTHER_REPOSITORY = 'It works in another repository, so it would build this in that repository\'s worktree. A new agent starts in this one.'

/** How the probe's account would carry a task of this size (phase 1 §2–3). Nothing is held in reserve: quota is
 *  information, so all that is left counts. */
function sizeUp(p: Probe, a: Assessment, now: number, open: Commitment[]): Sized {
  // A local model spends no subscription: it always fits, at its catalog cost, and its node is its account.
  if (p.gridModel) {
    return { fit: { status: 'fits', coverage: null, effectiveCost: p.cost, expiring: 0, spend: { '5-hour': 0, weekly: 0 },
      account: accountOf(p) }, tight: null, text: 'fits: a local model on the Swarm\'s grid uses no subscription' }
  }
  const { minutes, spend: base } = SIZES[a.size], runMs = minutes * 60_000
  const account = accountOf(p)
  const spend = { '5-hour': base['5-hour'] * p.cost / 2, weekly: base.weekly * p.cost / 2 }
  if (p.quota.metered) return { fit: { status: 'fits', coverage: null, effectiveCost: p.cost, expiring: 0, spend, account }, tight: null, text: 'fits: metered, no usage window to run out' }
  // Picks still at work hold what they were expected to spend, less the part of their run time already over.
  const committed = (name: Window) => open.filter(c => c.account === account)
    .reduce((sum, c) => sum + (c.spend[name] ?? 0) * Math.max(0, 1 - (now - c.createdAt) / (SIZES[c.size].minutes * 60_000)), 0)
  const windows = WINDOWS.flatMap((name): Measured[] => {
    const w = p.quota.windows?.find(w => w.name === name)
    if (!w) return []
    const resetsIn = w.resetsAt === null ? null : Math.max(60_000, w.resetsAt - now)
    // A window that refills mid-task carries only the part of the task before its reset.
    return [{ name, usable: w.leftPercent - committed(name), resetsIn,
      needed: resetsIn !== null && resetsIn < runMs ? spend[name] * resetsIn / runMs : spend[name] }]
  })
  // A weekly reading is complete on either engine: the 5-hour window is never what runs out (Ken, 2026-11-03), and a Team
  // account's Claude, whose host relays no 5-hour window, read as unknown and ranked behind every Codex that fit. A 5-hour
  // window that is read still counts when it is short.
  const five = windows.find(w => w.name === '5-hour'), week = windows.find(w => w.name === 'weekly')
  const status = windows.some(w => w.usable < w.needed) ? 'short' : week ? 'fits' : 'unknown'
  const tight = windows.length ? windows.reduce((x, y) => y.usable / y.needed < x.usable / x.needed ? y : x) : null
  // A 5-hour window that resets before the task ends, or soon after, loses what is left of it: spending it costs nothing.
  const expiring = five && five.resetsIn !== null && five.resetsIn <= runMs + 3_600_000 ? Math.min(1, Math.max(0, five.usable) / five.needed) : 0
  let effectiveCost = p.cost * (1 - expiring)
  // The weekly window has to last until it resets, so work that is not hard pays for taking more than a day's share of it.
  const dayBudget = week ? week.usable / Math.max(1, (week.resetsIn ?? 0) / 86_400_000) : 0
  if (week && a.difficulty !== 'high' && dayBudget > 0 && week.needed > dayBudget) effectiveCost += p.cost * week.needed / dayBudget
  const text = `${status}: ${five ? `needs about ${pct(five.needed)} of the 5-hour window (${pct(five.usable)} left${five.resetsIn === null ? '' : `, resets in ${span(five.resetsIn)}`}${expiring ? ', otherwise unused' : ''})` : '5-hour window unknown'}`
    + `; weekly ${week ? `${pct(week.needed)} of ${pct(week.usable)}` : 'unknown'}`
  return { fit: { status, coverage: tight && round(tight.usable / tight.needed), effectiveCost: round(effectiveCost), expiring: round(expiring), spend, account }, tight, text }
}
export const LOCAL_NONE = 'No local model is being served on this Swarm\'s grid. Ask a member to run one or share an API (Your models, in the Swarm\'s sidebar).'

/** The neutral order (task #2901): machine name, then engine (a machine's grid models after its engines), then title, so the
 *  same candidates come in the same order whatever the machines answered first. Nothing in it is strength, price, quota fit or
 *  a plug-in's finding: the PM took the top line of the old order, by strength then price, against the project's Routing
 *  instructions (Ken, 2026-11-04). A member in another repository comes after the others on its machine and engine, with
 *  OTHER_REPOSITORY as a note (choose): it would build in that repository's worktree (Diego, 2026-10-30, #2377). */
function compare(x: Probe, y: Probe): number {
  const grid = (p: Probe) => p.gridModel ? 1 : 0
  const elsewhere = (p: Probe) => p.kind === 'member' && p.repo === 'different' ? 1 : 0
  return x.machineName.localeCompare(y.machineName) || x.machineId.localeCompare(y.machineId)
    || grid(x) - grid(y) || x.engine.localeCompare(y.engine)
    || elsewhere(x) - elsewhere(y)
    || titleOf(x).localeCompare(titleOf(y))
    || (x.agentId ?? '').localeCompare(y.agentId ?? '')
}

/** An engine on a machine, or the machine's local models, as a new agent or an idle member: what the project's order picks
 *  between (an account, then whether to reuse an agent on it). */
export const slotOf = (p: Pick<Probe, 'machineId' | 'engine' | 'gridModel' | 'kind'>) => `${p.machineId}\0${p.gridModel ? 'grid' : p.engine}\0${p.kind}`

/** The work a slot offers a model for, by the project's Routing rules (Models): `strong` for big, hard or risky work, security
 *  or a review, and for any work whose second attempt ended (small work steps up to Opus or Astra after a second failed
 *  review); `standard` for small, low or medium work; null, both, for a task with no size or whose attempts could not be read
 *  that nothing makes strong. */
export type Tier = 'standard' | 'strong'
export function tierOf(a: Assessment): Tier | null {
  if (a.size === 'large' || a.difficulty === 'high' || a.risk === 'high' || /(^|-)(security|review)(-|$)/.test(a.kind ?? '')
    || (a.ended ?? 0) >= 2) return 'strong'
  return a.unsized || a.ended === null ? null : 'standard'
}
/** Each tier's model on each engine, as the Routing rules name them. */
const TIER_MODELS: Record<Tier, Record<CatalogModel['engine'], { model: string; effort: string }>> = {
  standard: { claude: { model: 'sonnet', effort: 'high' }, codex: { model: 'gpt-6.1-sol', effort: 'high' } },
  strong: { claude: { model: 'opus', effort: 'high' }, codex: { model: 'gpt-6-astra', effort: 'xhigh' } },
}
const TIERS = Object.keys(TIER_MODELS) as Tier[]
/** The tier whose model a candidate runs, at any effort: a member's reported model read through the catalog ([catalogRow]),
 *  so `claude-opus-4-7` is Opus. Null for a grid model or a model no tier names. */
function modelTier(p: Probe, catalog: Catalog): Tier | null {
  if (p.gridModel) return null
  const model = p.kind === 'member' ? catalogRow(catalog, p.engine, p.model, p.effort)?.model ?? p.model : p.model
  return TIERS.find(t => TIER_MODELS[t][p.engine].model === model) ?? null
}
/** How well a candidate fits [tier]: 0 on the tier's model and effort, 1 on neither tier's model or the tier's at another
 *  effort, 2 on the other tier's model. */
export function fitRank(p: Probe, catalog: Catalog, tier: Tier): 0 | 1 | 2 {
  const runs = modelTier(p, catalog)
  if (runs === null) return 1
  if (runs !== tier) return 2
  return p.effort === TIER_MODELS[tier][p.engine].effort ? 0 : 1
}

/** The rows shown: for every engine on every machine, as a new agent and as an idle member, the candidate that fits the task's
 *  tier best ([fitRank]), ties by the neutral order, up to [RECORD_MAX]; then more up to 12, none fitting worse than its slot's.
 *  With no tier, each slot keeps its first row of each tier's model, so both are offered. All come in the neutral order. The
 *  agent choosing picks between accounts by the project's order; one row a machine, cut at 12, hid a Claude account with 99%
 *  left behind its machine's used-up Codex (Ken, 2026-11-03). The first row of a slot by title offered Opus and Astra for
 *  small work 4,366 times against Sonnet and Sol 194 (Ken, 2026-11-05, task #3163). */
function withEveryAccount<T extends Probe>(ranked: T[], catalog: Catalog, a: Assessment): T[] {
  const tier = tierOf(a)
  const rank = (p: T) => tier ? fitRank(p, catalog, tier) : 0
  const slot = (p: T) => tier ? slotOf(p) : `${slotOf(p)}\0${modelTier(p, catalog) ?? ''}`
  const best = new Map<string, T>()
  for (const p of ranked) {
    const held = best.get(slot(p))
    if (!held ? best.size < RECORD_MAX : rank(p) < rank(held)) best.set(slot(p), p)
  }
  const keep = new Set<T>(best.values())
  for (const p of ranked) if (keep.size < MAX_SHOWN && rank(p) <= rank(best.get(slot(p))!)) keep.add(p)
  return ranked.filter(p => keep.has(p))
}

/** What the agent choosing reads of a row's machine: whether a start there would be admitted (River, 2026-11-03: starts
 *  failed on slots, memory and disk the rows did not show). */
export function machineBrief(room: MachineRoom): string {
  const slots = room.slots === null ? [] : [`${room.slots} ${room.slots === 1 ? 'slot' : 'slots'} free`]
  const memory = room.freeMemoryBytes === null ? 'free memory unknown'
    : `${bytes(Math.max(0, room.freeMemoryBytes))} memory free${room.heldMemoryBytes ? ` (${bytes(room.heldMemoryBytes)} held by starts)` : ''}`
  const disk = room.freeDiskBytes === null ? [] : [`${bytes(Math.max(0, room.freeDiskBytes))} disk free`]
  return [...slots, memory, ...disk].join(' · ')
}

/** A quota's weekly window, the one the project's order compares: its percent left and reset, or a reading with no windows
 *  named as one; null left when it was not read. */
export function weekly(q: Quota): { left: number | null; resetsAt: number | null } {
  const week = q.windows?.find(w => w.name === 'weekly')
  const left = !q.known ? null : week ? week.leftPercent : q.windows?.length ? null : q.leftPercent
  return { left, resetsAt: week ? week.resetsAt : q.resetsAt }
}

/** What the agent choosing reads of a row's quota: its fit and its weekly window, the one the project's order compares. */
export function quotaBrief(p: Pick<Probe, 'quota' | 'gridModel'> & { fit: Pick<Fit, 'status'> }, now: number): string {
  if (p.gridModel) return 'local model, no subscription'
  if (p.quota.metered) return 'metered'
  const { left, resetsAt } = weekly(p.quota)
  // Why it is unknown says what would make it known (River, 2026-11-03): a Team account's reading its owner's machine relays.
  if (left === null) return `${p.fit.status}: ${p.quota.why ? cut(p.quota.why, 200) : 'weekly unknown'}`
  return `${p.fit.status}: weekly ${Math.round(left)}% left${resetsAt === null ? '' : `, resets in ${weeklyResetsIn(resetsAt, now)}`}`
}

/** [quotaBrief] in a candidate's one line (task #3294): "fits 62% · resets 5d", the weekly window the project's order compares. */
export function quotaLine(p: Pick<Probe, 'quota' | 'gridModel'> & { fit: Pick<Fit, 'status'> }, now: number): string {
  if (p.gridModel) return 'free (grid)'
  if (p.quota.metered) return 'metered'
  const { left, resetsAt } = weekly(p.quota)
  if (left === null) return `${p.fit.status === 'unknown' ? '' : `${p.fit.status}, `}weekly unknown${p.quota.why ? ` (${cut(p.quota.why, 40)})` : ''}`
  return `${p.fit.status} ${Math.round(left)}%${resetsAt === null ? '' : ` · resets ${weeklyResetsIn(resetsAt, now)}`}`
}

/** One unrated new agent per machine of the named model's engine, on that machine's first row of the engine, which carries
 *  its facts and its quota ([CLAUDE_NAMES]). The person's words are the model's id, in lowercase with no spaces. */
function unratedProbes(probes: Probe[], named: string): Probe[] {
  const engine = CLAUDE_NAMES.test(named) ? 'claude' : 'codex', model = named.trim().toLowerCase().replace(/\s+/g, '-')
  const bases = new Map<string, Probe>()
  for (const p of probes) if (p.kind === 'new' && !p.gridModel && p.engine === engine && !bases.has(p.machineId)) bases.set(p.machineId, p)
  return [...bases.values()].map(base => ({ ...base, model, effort: 'default', quality: 1, cost: 1, unrated: true as const, notes: [...base.notes, UNRATED] }))
}

/** The candidates that can run the task, in the neutral order ([compare]), and those that cannot, with why. A catalog row not offered by
 *  default (Sonnet, Haiku) is offered when a person names it; its note goes with it, and with a member already on it.
 *  `held`: models served for the Swarm that take no more agents, to say who holds a named or local model none offers.
 *  `offline`: models a host now offline served (routeCommand.ts offlineModels), by name. `plugins`: [RoutePlugin]; with none
 *  the answer is exactly what it was before plug-ins existed (route.spec.ts, route answers without plug-ins). */
export function choose(given: Probe[], catalog: Catalog, a: Assessment, now: number = Date.now(), open: Commitment[] = [], held: HeldModel[] = [],
  offline: Array<{ title: string; reason: string }> = [], plugins: readonly RoutePlugin[] = []): Choice | NoCandidate {
  const named = a.model
  const context: RouteContext = { assessment: a, now, catalog, open }, warnings: string[] = []
  const { probes, out: addedOut } = withPluginCandidates(given, plugins, context, warnings)
  const warned = () => warnings.length ? { warnings } : {}
  const noted = probes.flatMap(p => {
    const row = p.gridModel ? null : p.kind === 'new' ? catalog.models.find(m => m.engine === p.engine && m.model === p.model && m.effort === p.effort) ?? null
      : catalogRow(catalog, p.engine, p.model, p.effort)
    if (row && !row.offered && p.kind === 'new' && !(named && runsNamed(p, named))) return []
    const rated = row?.note && !p.notes.includes(row.note) ? { ...p, notes: [...p.notes, row.note] } : p
    if (p.kind !== 'member' || p.repo !== 'different') return [rated]
    // The task names a repository this member does not work in: it cannot run there, a fact, so it is left out with why.
    if (a.needs.cwd) return [{ ...rated, refusals: [...rated.refusals, OTHER_REPOSITORY] }]
    // No repository named: the coordinator knows whether the task needs a worktree, so it is ranked last with a note.
    return [{ ...rated, notes: [...rated.notes, OTHER_REPOSITORY] }]
  })
  // A person asking for a local model considers local models alone, whatever their strength.
  let considered = a.local ? noted.filter(p => p.gridModel) : noted
  // A person naming a model considers that model alone; one the catalog does not list is offered unrated.
  const heldNamed = named ? held.filter(m => words(named).every(w => words(`${m.model} ${m.label}`).join('').includes(w))) : []
  if (named) considered = considered.filter(p => runsNamed(p, named))
  // A model of the grid (a catalog grid row, or one a host now offline served) is no unknown model to try on Codex: nothing
  // serves it now, which the answer says, rather than "Codex kimi-k3" unrated (final review).
  const ofGrid = !!named && (catalog.grid.models.some(row => names(row.model, named)) || offline.some(m => names(m.title, named)))
  if (named && !considered.length && !heldNamed.length && !a.local && !ofGrid) considered = unratedProbes(probes, named)
  const excluded: Excluded[] = [...considered.filter(p => p.refusals.length).map(p => ({ title: titleOf(p), reason: p.refusals.join(' '), machine: p.machineName })), ...addedOut]
  const viable = considered.filter(p => !p.refusals.length)
  // Nothing offered: a model that is served but taken says who has it, rather than reading as unshared.
  if (named && !considered.length) {
    if (heldNamed.length) excluded.push(...heldNamed.map(m => ({ title: 'Named model', reason: heldReason(m) })))
    else excluded.push({ title: 'Named model', reason: NAMED_NONE(named) })
  } else if (a.local && !considered.length) {
    if (held.length) excluded.push(...held.map(m => ({ title: 'Local models', reason: heldReason(m) })))
    else excluded.push({ title: 'Local models', reason: LOCAL_NONE })
  }
  if (!viable.length) return { error: 'NO_CANDIDATE', excluded, ...warned() }
  const sized = viable.map(p => ({ ...p, ...sizeUp(p, a, now, open) }))
  const adjustments = pluginAdjustments(sized, plugins, context, warnings)
  const adjusted = adjustments.some(list => list.length)
  // A plug-in's refusal leaves its candidate out; its strength or cost is a note and moves nothing (task #2901).
  const listed = sized.flatMap((p, i) => {
    const mine = adjustments[i]!
    if (!mine.length) return [p]
    const reasons = mine.map(({ name, adjustment }) => `${name}: ${adjustment.reason.trim()}`)
    if (mine.some(m => m.adjustment.refuse)) {
      excluded.push({ title: titleOf(p), reason: reasons.filter((_, j) => mine[j]!.adjustment.refuse).join(' '), machine: p.machineName })
      return []
    }
    return [{ ...p, notes: [...p.notes, ...reasons] }]
  }).sort(compare)
  if (!listed.length) return { error: 'NO_CANDIDATE', excluded, ...warned() }
  const shown = withEveryAccount(listed, catalog, a).map(({ tight, text, ...p }, i) => ({ ...p, id: `c${i}`, title: titleOf(p), label: labelOf({ ...p, tight, text }, now) }))
  // With nothing first, only one thing is worth saying of quota beside each row's fit: that none of them covers the task.
  const none = listed.every(p => p.fit.status === 'short')
  return { shown, excluded, floor: 1, belowFloor: false, ...(none ? { short: NONE_COVERS } : {}),
    ...(adjusted ? { adjusted: true as const } : {}), ...warned() }
}
export const NONE_COVERS = 'No candidate is expected to cover this task on its quota.'

/** What the route says of its candidates (task #2901): it names no pick, and its why sends the agent choosing to the project's
 *  Routing instructions, since a list's first row read as the route's choice (River, 2026-11-04: PMs started the machine the
 *  route listed first). */
export const CHOOSE_BY_INSTRUCTIONS = 'Not ranked: candidates are listed by machine name, then engine. Choose one by the project\'s Routing instructions '
  + '(Order and quota), and give the rule that chose it as overrideReason when you start or assign it.'
export function decide(choice: Choice): Verdict {
  return choice.shown.length === 1 ? { via: 'only', p: null, why: 'Only candidate that can run this task.' }
    : { via: 'instructions', p: null, why: choice.adjusted ? `${CHOOSE_BY_INSTRUCTIONS} Plug-ins' findings are in each candidate's notes.` : CHOOSE_BY_INSTRUCTIONS }
}

/** The verdict with the route's pick (task #3576, anh Dee 11-06): the candidate [picked] names, by the Routing order, with its reasons.
 *  With no pick (nothing has the quota the work needs) or one candidate, the verdict is [decide]'s, as before. */
export function decideByOrder(choice: Choice, picked: { id: string; reasons: string[] } | null): Verdict {
  if (!picked || choice.shown.length === 1) return decide(choice)
  return { via: 'order', p: null, why: cut(picked.reasons.join(' '), 300), pick: picked.id, reasons: picked.reasons }
}

/** The record in the shape a backend takes: `current` with the job's kind (what attempts are compared by, backend costs/read.ts),
 *  no pick (task #2901) and each candidate's weekly % left and reset in its fit (task #3163: without them quota at route time
 *  could not be measured); `unquoted` the same without them, for a backend from before them; `picked` for a backend from before
 *  task #2901, which takes a record only with a pick, so `c0` stands in for one by the old `order`; `unkinded` for a backend
 *  from before kinds too, and `v1` without size and fit as well, for one from before phase 1. Each refuses the newer fields with its strict schema. There is no floor and no policy notes: `floor` 1,
 *  `belowFloor` and `notes` false. The server stamps the instructions' revision the decision relied on (phase 4, decision 12). */
export type RecordShape = 'current' | 'unquoted' | 'picked' | 'unkinded' | 'v1'
export function recordOf(choice: Choice, verdict: Verdict, a: Assessment, shape: RecordShape = 'current'): Record<string, unknown> {
  const v1 = shape === 'v1', kinded = shape !== 'unkinded' && !v1, pickless = shape === 'current' || shape === 'unquoted'
  const fitOf = (s: Shown) => shape === 'current' ? { ...s.fit, ...weekly(s.quota) } : s.fit
  return {
    assessment: { difficulty: a.difficulty, risk: a.risk, why: a.why, ...(v1 ? {} : { size: a.size }), ...(kinded && a.kind ? { kind: a.kind } : {}),
      ...(kinded && a.local ? { local: true } : {}), ...(kinded && a.model ? { model: a.model } : {}) },
    candidates: choice.shown.map(s => ({ id: s.id, kind: s.kind, ...(s.agentId ? { agentId: s.agentId } : {}), machineId: s.machineId,
      engine: s.engine, model: s.model, effort: s.effort, quality: s.quality, cost: s.cost, title: s.title, label: s.label, ...(v1 ? {} : { fit: fitOf(s) }),
      ...(s.gridModel && s.gridName ? { gridModel: s.gridModel, gridName: s.gridName } : {}) })),
    excluded: choice.excluded.slice(0, 200).map(e => ({ title: e.title, reason: cut(e.reason, 500) })),
    floor: 1, notes: false,
    ...(verdict.pick && choice.shown.some(c => c.id === verdict.pick) ? { pick: verdict.pick, via: 'order' }
      : pickless ? { via: verdict.via } : { pick: choice.shown[0]!.id, via: verdict.via === 'only' ? 'only' : 'order' }),
    p: verdict.p, belowFloor: false, why: cut(verdict.why, 300),
  }
}