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.

Route stops ranking candidates; the project's Routing instructions choose (#2901) (#3010)

harness-for-autonomous[bot]e0009db4c763
diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.ts
index 3499c2986..0c601bc4c 100644
--- a/backend/src/superTabs/commands.test.ts
+++ b/backend/src/superTabs/commands.test.ts
@@ -949,6 +949,11 @@ const candidate = (id: string, patch: Record<string, unknown> = {}) => ({ id, ki
const record = (patch: Record<string, unknown> = {}) => ({ assessment: { difficulty: 'high', risk: 'low', why: 'Schema change.' },
candidates: [candidate('c0'), candidate('c1', { model: 'sonnet', quality: 2, cost: 2 })], excluded: [], floor: 3, notes: false,
pick: 'c0', via: 'jev', p: 0.82, belowFloor: false, why: 'Highest quality within quota.', ...patch })
+/** The route since task #2901 (Ken, 2026-11-04): it names no pick, and the project's Routing instructions choose. */
+const pickless = (patch: Record<string, unknown> = {}) => {
+ const { pick: _pick, ...rest } = record({ via: 'instructions', p: null, floor: 1, why: 'No ranking: the project\'s Routing instructions choose.', ...patch })
+ return rest
+}
/** What an agent passes to start or assign: a routing decision of `conversationId`. Its pick differs from the call, so it carries a reason. */
const via = { routeDecisionId: 'd1', overrideReason: 'Test.' }
const decisionIn = (conversationId = 'lead', patch: Record<string, unknown> = {}) => ({ routeDecision: { id: 'd1', conversationId, record: record(patch), final: null, override: null, assignmentId: null, outcome: null } as unknown as RouteDecision })
@@ -1319,6 +1324,134 @@ describe('decisions linked to work', () => {
})
})
+// Task #2901 (Ken, 2026-11-04): PMs took the route's top line, nearly always Opus or Astra, against the Routing instructions'
+// order and quota. The route names no pick now; the coordinator chooses by the instructions, and its start or assignment
+// records which candidate it chose and the rule that chose it.
+describe('a route that names no pick', () => {
+ const open = (patch: Record<string, unknown> = {}) => ({ id: 'd1', conversationId: 'lead', record: pickless(), final: null, override: null, assignmentId: null,
+ outcome: null, ...patch }) as unknown as RouteDecision
+ const request = (patch: Record<string, unknown> = {}) => ({ conversationId: 'lead', machineId: 'machine', engine: 'claude', model: 'sonnet', effort: 'high',
+ name: 'Builder', cwd: '/repo', worktree: false, requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false },
+ ...patch }) as Extract<Command, { type: 'agent.start' }>['request']
+ const rule = 'Rule 3: the account resetting soonest.'
+
+ it('is recorded with its id and no chat row, as the coordinator\'s route, whichever candidates it lists', () => {
+ const f = routed(), group = f.group()
+ const buddy = f.add('buddy')
+ f.state.agents.find(a => a.id === buddy)!.buddyOf = { personId: 'owner', generation: 'tab' }
+ const decision = pickless({ candidates: [candidate('c0', { kind: 'member', agentId: buddy }), candidate('c1', { model: 'sonnet' })] })
+ const effects = f.run({ type: 'route.record', conversationId: group, decision } as Command, f.leadActor, { now: 2000 })
+ expect(effects.result.routeDecisionId).toEqual(expect.any(String))
+ expect(effects.routeDecisions).toEqual([{ op: 'create', id: effects.result.routeDecisionId, conversationId: group,
+ record: expect.objectContaining({ via: 'instructions', candidates: decision.candidates }) }])
+ expect((effects.routeDecisions[0] as { record: object }).record).not.toHaveProperty('pick')
+ expect(effects.messages).toEqual([])
+ expect(f.state.conversations.find(c => c.id === group)!.leadAction).toEqual({ kind: 'route', at: 2000 })
+ })
+
+ it('refuses a start or an assignment without the Routing rule that chose it, and says what to send', () => {
+ const f = routed(), task = f.group()
+ f.define(task)
+ for (const run of [
+ () => f.run({ type: 'agent.start', request: request({ conversationId: task }), routeDecisionId: 'd1' }, f.leadActor, { routeDecision: open({ conversationId: task }), contribution: f.contribution }),
+ () => f.run({ type: 'work.assign', conversationId: task, agentId: f.worker, routeDecisionId: 'd1' }, f.leadActor, { routeDecision: open({ conversationId: task }) }),
+ ]) {
+ expect(run).toThrow(expect.objectContaining({ code: 'ROUTE_REASON_REQUIRED', message: expect.stringContaining('overrideReason') }))
+ expect(run).toThrow(expect.objectContaining({ message: expect.stringContaining('Routing rule') }))
+ }
+ })
+
+ // The only candidate that can run needs no rule to choose it: the start gives none and the row says so.
+ it('takes a start of the only candidate without a reason, and says it was the only one', () => {
+ const f = routed(), task = f.group()
+ const only = open({ conversationId: task, record: pickless({ via: 'only', candidates: [candidate('c1', { model: 'sonnet' })] }) })
+ const effects = f.run({ type: 'agent.start', request: request({ conversationId: task }), routeDecisionId: 'd1' }, f.leadActor, { routeDecision: only, contribution: f.contribution })
+ expect(effects.routeDecisions).toEqual([expect.objectContaining({ op: 'final', final: expect.objectContaining({ candidateId: 'c1' }) })])
+ expect(effects.messages.filter(m => m.source?.kind === 'route')).toEqual([expect.objectContaining({
+ source: expect.objectContaining({ via: 'only', why: 'Only candidate that can run this task.', pick: { id: 'c1', title: expect.any(String) } }) })])
+ })
+
+ // Review of #3010: "only candidate" is a reason only for the candidate it names; a start elsewhere still says why.
+ it('refuses a start that matches none of the only-candidate route\'s candidates without a reason', () => {
+ const f = routed(), task = f.group()
+ const only = open({ conversationId: task, record: pickless({ via: 'only', candidates: [candidate('c1', { model: 'opus' })] }) })
+ expect(() => f.run({ type: 'agent.start', request: request({ conversationId: task }), routeDecisionId: 'd1' }, f.leadActor, { routeDecision: only, contribution: f.contribution }))
+ .toThrow(expect.objectContaining({ code: 'ROUTE_REASON_REQUIRED' }))
+ })
+
+ it('records the candidate a start matches, and posts the route row naming it and the rule', () => {
+ const f = routed(), task = f.group()
+ const effects = f.run({ type: 'agent.start', request: request({ conversationId: task }), routeDecisionId: 'd1', overrideReason: rule }, f.leadActor,
+ { routeDecision: open({ conversationId: task }), contribution: f.contribution })
+ expect(effects.routeDecisions).toEqual([{ op: 'final', id: 'd1', final: { kind: 'new', startId: effects.result.startId, machineId: 'machine', engine: 'claude',
+ model: 'sonnet', effort: 'high', candidateId: 'c1' } }])
+ // Released Desktop and phone apps draw a route card from source.pick, so the row carries the candidate chosen as its pick.
+ expect(effects.messages.filter(m => m.source?.kind === 'route')).toEqual([expect.objectContaining({
+ text: `Routed to Title c1 — by the project's Routing instructions · "${rule}"`,
+ source: { kind: 'route', decisionId: 'd1', via: 'instructions', p: null, belowFloor: false, why: rule, pick: { id: 'c1', title: 'Title c1' },
+ alternatives: [{ id: 'c0', title: 'Title c0' }] } })])
+ expect(effects.messages.some(m => m.source?.kind === 'route-override')).toBe(false)
+ })
+
+ it('records a start that matches none of the candidates as the coordinator\'s override, with its reason', () => {
+ const f = routed(), task = f.group()
+ const effects = f.run({ type: 'agent.start', request: request({ conversationId: task, effort: 'xhigh' }), routeDecisionId: 'd1', overrideReason: 'Xhigh is needed here.' },
+ f.leadActor, { routeDecision: open({ conversationId: task }), contribution: f.contribution })
+ expect(effects.routeDecisions).toEqual([{ op: 'final', id: 'd1', final: { kind: 'new', startId: effects.result.startId, machineId: 'machine', engine: 'claude',
+ model: 'sonnet', effort: 'xhigh' }, override: { by: 'lead', actorKey: `agent:${f.lead}`, reason: 'Xhigh is needed here.' } }])
+ expect(effects.messages.filter(m => m.source?.kind?.toString().startsWith('route'))).toEqual([expect.objectContaining({
+ text: 'lead started Builder, which is none of the route\'s candidates. Reason: Xhigh is needed here.',
+ source: { kind: 'route-override', decisionId: 'd1', by: 'lead' } })])
+ })
+
+ it('records the member an assignment matches with the route row, and one that matches none as an override', () => {
+ const f = routed(), task = f.group(), name = f.state.agents.find(a => a.id === f.worker)!.name
+ f.define(task)
+ const members = pickless({ candidates: [candidate('c0'), candidate('c1', { kind: 'member', agentId: f.worker })] })
+ const assigned = f.run({ type: 'work.assign', conversationId: task, agentId: f.worker, routeDecisionId: 'd1', overrideReason: rule }, f.leadActor,
+ { routeDecision: open({ conversationId: task, record: members }) })
+ expect(assigned.routeDecisions).toEqual([{ op: 'final', id: 'd1', final: { kind: 'member', agentId: f.worker, machineId: expect.any(String), candidateId: 'c1' },
+ assignmentId: assigned.result.assignmentId }])
+ expect(assigned.messages.filter(m => m.source?.kind === 'route')).toEqual([expect.objectContaining({
+ text: `Routed to Title c1 — by the project's Routing instructions · "${rule}"`, source: expect.objectContaining({ pick: { id: 'c1', title: 'Title c1' } }) })])
+ f.state.conversations.find(c => c.id === task)!.assignment = null
+ const other = f.run({ type: 'work.assign', conversationId: task, agentId: f.worker, routeDecisionId: 'd1', overrideReason: 'It knows the code.' }, f.leadActor,
+ { routeDecision: open({ conversationId: task }) })
+ expect(other.routeDecisions[0]).toMatchObject({ op: 'final', override: { by: 'lead', reason: 'It knows the code.' } })
+ expect(other.routeDecisions[0]).not.toHaveProperty('final.candidateId')
+ expect(other.messages.filter(m => m.source?.kind?.toString().startsWith('route')).map(m => m.text))
+ .toEqual([`lead assigned ${name}, which is none of the route's candidates. Reason: It knows the code.`])
+ })
+
+ it('links the assignment of the agent its start chose with no reason again and no second route row', () => {
+ const f = routed(), task = f.group()
+ f.define(task)
+ const final = { kind: 'new', startId: f.startedFor(f.worker), machineId: 'machine', engine: 'claude', model: 'sonnet', effort: 'high', candidateId: 'c1' }
+ const effects = f.run({ type: 'work.assign', conversationId: task, agentId: f.worker, routeDecisionId: 'd1' }, f.leadActor, { routeDecision: open({ conversationId: task, final }) })
+ expect(effects.routeDecisions).toEqual([{ op: 'final', id: 'd1', final, assignmentId: effects.result.assignmentId }])
+ expect(effects.messages.some(m => m.source?.kind?.toString().startsWith('route'))).toBe(false)
+ })
+
+ it('takes a person\'s choice with no earlier one as "chose", and refuses choosing the candidate a start already chose', () => {
+ const f = routed()
+ const command = { type: 'route.override', decisionId: 'd1', candidateId: 'c0', reason: 'Opus for the schema.' } as const
+ const effects = f.run(command, undefined, { routeDecision: open() })
+ expect(effects.routeDecisions).toEqual([{ op: 'override', id: 'd1', override: expect.objectContaining({ by: 'person', candidateId: 'c0' }) }])
+ expect(effects.messages[0]!.text).toBe('[email protected] chose Title c0. Reason: Opus for the schema.')
+ const started = open({ final: { kind: 'new', startId: 's', machineId: 'machine', engine: 'claude', model: 'sonnet', effort: 'high', candidateId: 'c1' } })
+ expect(() => f.run({ ...command, candidateId: 'c1' }, undefined, { routeDecision: started })).toThrow(expect.objectContaining({ code: 'ALREADY_CHOSEN' }))
+ expect(f.run(command, undefined, { routeDecision: started }).messages[0]!.text).toBe('[email protected] chose Title c0 instead of Title c1. Reason: Opus for the schema.')
+ })
+
+ it('links a start to the candidate a person chose, as before, keeping that candidate in the final', () => {
+ const f = routed(), task = f.group()
+ const chosen = open({ conversationId: task, override: { by: 'person', actorKey: 'person:owner', candidateId: 'c1', reason: 'Sonnet will do.' } })
+ const effects = f.run({ type: 'agent.start', request: request({ conversationId: task }), routeDecisionId: 'd1' }, f.leadActor, { routeDecision: chosen, contribution: f.contribution })
+ expect(effects.routeDecisions).toEqual([{ op: 'final', id: 'd1', final: expect.objectContaining({ model: 'sonnet', candidateId: 'c1' }) }])
+ expect(effects.messages.some(m => m.source?.kind?.toString().startsWith('route'))).toBe(false)
+ })
+})
+
// The route is advice (project instructions, phase 4): the server refuses no start, assignment or route for its model, its
// machine, the owner's old rules, a task's requirement or quota; only facts and access. A route decision is optional, and
// following another candidate needs no reason (it is still recorded).
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index d0a68b439..76dd95122 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -61,6 +61,8 @@ import { placeAfter, queueSiblings } from './taskQueue.js'
const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)
/** A route override's reason when its agent gave none: following another candidate needs none (project instructions). */
const NO_REASON = 'No reason given.'
+/** What a pick-less route's only candidate is chosen for, when its start gives no reason (task #2901). */
+const ONLY_CANDIDATE = 'Only candidate that can run this task.'
/** What an older client's policy, skill-set, role or rule-removal save answers: accepted, kept nowhere (project instructions,
* phase 4, decision 3). The old rules, policy rows and role texts stay in place, unread. */
export const IGNORED_NOTE = 'Routing and roles live in each project\'s instructions now. Update Harness to edit them there.'
@@ -1112,7 +1114,10 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
return decision
}
/** The candidate a start or assignment should match, and whether it does. Following another needs no reason (project
- * instructions, phase 4: the route is advice); it is still recorded as an override, with the reason when one is given. */
+ * instructions, phase 4: the route is advice); it is still recorded as an override, with the reason when one is given.
+ * A route that names no pick (task #2901, Ken 2026-11-04) leaves the choice to the coordinator, by the project's Routing
+ * instructions: until a person or an earlier start chose, the start or assignment gives the rule that chose it, and the
+ * candidate it matches, any of them, is recorded and said in the route row the released apps draw. */
const linkDecision = (conversationId: string, matches: (c: KeptCandidate, d: RouteDecision) => boolean,
finalOf: (d: RouteDecision) => RouteFinal, reasonText: string | undefined, assignmentId?: string) => {
const decision = openDecision()
@@ -1121,13 +1126,31 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
if (decision.assignmentId && state.conversations.some(c => c.assignment?.id === decision.assignmentId && activeWork(c))) {
fail('ROUTE_LINKED', 'This routing decision already has running work. Stop it before handing the task over.')
}
- const expected = decision.record.candidates.find(c => c.id === (decision.override?.candidateId ?? decision.record.pick))!
+ const final = (patch: Pick<RouteFinal, 'candidateId'>, override?: RouteOverride) => effects.routeDecisions.push({ op: 'final', id: decision.id,
+ final: { ...finalOf(decision), ...patch }, ...(override ? { override } : {}), ...(assignmentId ? { assignmentId } : {}) })
+ const chosenId = decision.override?.candidateId ?? decision.final?.candidateId ?? decision.record.pick
+ if (chosenId === undefined) {
+ const chosen = decision.record.candidates.find(c => matches(c, decision))
+ // The only candidate that can run needs no rule to choose it; a start of anything else still says why (review of #3010).
+ const only = decision.record.via === 'only' && chosen ? ONLY_CANDIDATE : undefined
+ const reason = reasonText ?? only ?? fail('ROUTE_REASON_REQUIRED',
+ 'This route names no pick: send, as overrideReason, the project\'s Routing rule that chose this candidate.')
+ const override: RouteOverride | undefined = chosen ? undefined : { by: 'lead', actorKey: actorKey(actor), reason }
+ final(chosen ? { candidateId: chosen.id } : {}, override)
+ const instead = (done: string) => `${who} ${done}, which is none of the route's candidates. Reason: ${reason}`
+ const routed = chosen && { text: `Routed to ${chosen.title} — ${only && !reasonText ? 'only candidate' : 'by the project\'s Routing instructions'} · "${reason}"`, source: { kind: 'route',
+ decisionId: decision.id, via: only && !reasonText ? 'only' : 'instructions', p: null, belowFloor: false, why: reason, pick: { id: chosen.id, title: chosen.title },
+ alternatives: decision.record.candidates.filter(c => c.id !== chosen.id).map(c => ({ id: c.id, title: c.title })) } }
+ return { decision, override, instead, routed }
+ }
+ const expected = decision.record.candidates.find(c => c.id === chosenId)!
const matched = matches(expected, decision)
const override: RouteOverride | undefined = matched ? undefined : { by: 'lead', actorKey: actorKey(actor), reason: reasonText ?? NO_REASON }
- effects.routeDecisions.push({ op: 'final', id: decision.id, final: finalOf(decision), ...(override ? { override } : {}), ...(assignmentId ? { assignmentId } : {}) })
+ // A record with a pick keeps it as the choice; one without keeps the candidate chosen in the final, for the route history.
+ final(matched && decision.record.pick === undefined ? { candidateId: chosenId } : {}, override)
// The chat line: who chose what instead of the route's pick, and why when they said.
const instead = (done: string) => `${who} ${done} instead of ${expected.title}.${reasonText ? ` Reason: ${reasonText}` : ''}`
- return { decision, expected, override, instead }
+ return { decision, override, instead, routed: undefined }
}
/** Why a route candidate cannot take a teammate's work in [conversationId], or null (machines.ts teamWorkCheck). A
* member runs under its own contributor's grant; a new agent under the contribution's, or off the Machines list under
@@ -2364,13 +2387,14 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
// The pick names the machine the Lead named: the Mac, when the start then went to its team account.
const r = command.request
const model = r.model ?? 'default', effort = r.effort ?? 'default'
- const { decision, override, instead } = linkDecision(r.conversationId,
+ const { decision, override, instead, routed } = linkDecision(r.conversationId,
c => c.kind === 'new' && c.machineId === r.machineId && c.engine === r.engine && c.model === model && c.effort === effort
&& (c.gridModel ?? null) === (r.gridModel ?? null) && (c.gridName ?? null) === (r.gridName ?? null),
() => ({ kind: 'new', startId: operationId, machineId: r.machineId, engine: r.engine, model, effort,
...(r.gridModel && r.gridName ? { gridModel: r.gridModel, gridName: r.gridName } : {}) }), command.overrideReason)
if (override) message(r.conversationId, instead(`started ${r.name}`), [], null,
bookkeeping(r.conversationId, { kind: 'route-override', decisionId: decision.id, by: 'lead' }))
+ if (routed) message(r.conversationId, routed.text, [], null, bookkeeping(r.conversationId, routed.source))
}
break
}
@@ -3262,14 +3286,18 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
const refusal = candidateRefusal(c, command.conversationId, starter)
return refusal ? [[c.id, refusal] as const] : []
}))
- const pickRefusal = refusals.get(command.decision.pick)
+ const pickRefusal = command.decision.pick === undefined ? undefined : refusals.get(command.decision.pick)
if (pickRefusal) failTeamWork(pickRefusal, ' Route again.')
+ // A route that names no pick (task #2901) is refused only once it has no candidate left to choose.
+ const [firstRefusal] = refusals.values()
+ if (firstRefusal && refusals.size === command.decision.candidates.length) failTeamWork(firstRefusal, ' Route again.')
const decision = !refusals.size ? command.decision : { ...command.decision,
candidates: command.decision.candidates.filter(c => !refusals.has(c.id)),
excluded: [...command.decision.candidates.flatMap(c => refusals.has(c.id) ? [{ title: c.title, reason: refusals.get(c.id)!.reason }] : []),
...command.decision.excluded].slice(0, 200) }
- const chosen = decision.candidates.find(c => c.id === decision.pick)!
- const member = chosen.kind === 'member' ? state.agents.find(a => a.id === chosen.agentId) : undefined
+ // With no pick the coordinator chooses at the start or assignment, which checks its agent then.
+ const chosen = decision.pick === undefined ? undefined : decision.candidates.find(c => c.id === decision.pick)!
+ const member = chosen?.kind === 'member' ? state.agents.find(a => a.id === chosen.agentId) : undefined
if (member) assignable(member)
// An archived task is routed no more.
const routedGroup = open(state, command.conversationId)
@@ -3289,9 +3317,10 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
const stepUp = step ? { stepUp: { attempt: Math.min(3, step.attempt), reason: step.reason.slice(0, 200) } } : {}
effects.routeDecisions.push({ op: 'create', id: operationId, conversationId: command.conversationId, record: { ...made, ...stepUp, jobKind, instructionsRevision } })
result.routeDecisionId = operationId
- // The row quotes the Lead's reason for the task; the verdict's own text stays in the decision record.
+ // The row quotes the Lead's reason for the task; the verdict's own text stays in the decision record. A route that names no
+ // pick posts none: its start or assignment posts the row naming the candidate chosen (linkDecision).
const reason = decision.assessment.why
- message(command.conversationId, `Routed to ${chosen.title} — ${via} · "${reason}"`, [], null, bookkeeping(command.conversationId, {
+ if (chosen) message(command.conversationId, `Routed to ${chosen.title} — ${via} · "${reason}"`, [], null, bookkeeping(command.conversationId, {
kind: 'route', decisionId: operationId, via: decision.via, p: decision.p, belowFloor: decision.belowFloor, why: reason,
...(decision.via === 'order' && decision.fallback ? { fallback: decision.fallback } : {}),
pick: { id: chosen.id, title: chosen.title },
@@ -3316,9 +3345,10 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
if (actor.kind !== 'person') fail('HUMAN_REQUIRED', 'A person changes a routing decision; the lead overrides when it starts or assigns.', 403)
const decision = openDecision()
open(state, decision.conversationId)
- const current = decision.override?.candidateId ?? decision.record.pick
+ // A route that names no pick (task #2901) has no choice until a person or a start makes one.
+ const current = decision.override?.candidateId ?? decision.final?.candidateId ?? decision.record.pick
const chosen = decision.record.candidates.find(c => c.id === command.candidateId) ?? fail('NOT_FOUND', 'Choose one of this decision’s candidates.', 404)
- if (chosen.id === current) fail('ALREADY_CHOSEN', 'That candidate is already the choice.')
+ if (current !== undefined && chosen.id === current) fail('ALREADY_CHOSEN', 'That candidate is already the choice.')
if (chosen.kind === 'member' && !state.agents.some(a => a.id === chosen.agentId)) fail('CANDIDATE_UNAVAILABLE', 'That agent left this Super Tab. Choose another.')
// Its machine may have stopped showing its privacy since the route; the group's Lead is who would start it.
const leadId = conversation(state, decision.conversationId).leadId
@@ -3327,7 +3357,7 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
effects.routeDecisions.push({ op: 'override', id: decision.id, override: { by: 'person', actorKey: actorKey(actor), candidateId: chosen.id, reason: command.reason } })
const lead = conversation(state, decision.conversationId).leadId
message(decision.conversationId,
- `${sender.name} chose ${chosen.title} instead of ${routeTitle(decision, current)}. Reason: ${command.reason}`,
+ `${sender.name} chose ${chosen.title}${current === undefined ? '' : ` instead of ${routeTitle(decision, current)}`}. Reason: ${command.reason}`,
lead ? [lead] : [], null, { kind: 'route-override', decisionId: decision.id, by: 'person' })
break
}
@@ -3412,16 +3442,18 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
replyTo: null, recipients: [], source: { kind: 'others-work-notice', machineId: others.machineId }, text: others.text })
group.checks.forEach(c => { c.evidence = null; c.passedBy = null; delete c.verdicts })
result.assignmentId = operationId
- let routeNote: { decisionId: string; text: string } | null = null
+ let routeNote: { id: string; text: string; source: Record<string, unknown> } | null = null
if (command.routeDecisionId) {
const started = (d: RouteDecision) => d.final?.kind === 'new' &&
!!state.starts?.some(s => s.id === (d.final as { startId: string }).startId && s.harnessId === worker.harnessId && s.request.machineId === worker.machineId)
// An agent started from this decision keeps the final that records its model and effort; only the assignment is added.
- const { decision, override, instead } = linkDecision(group.id,
+ const { decision, override, instead, routed } = linkDecision(group.id,
(c, d) => (c.kind === 'member' && c.agentId === worker.id) || (c.kind === 'new' && started(d) && d.final?.kind === 'new' &&
startedAs(c, d.final)),
d => started(d) ? d.final! : { kind: 'member', agentId: worker.id, machineId: worker.machineId }, command.overrideReason, operationId)
- if (override) routeNote = { decisionId: decision.id, text: instead(`assigned ${worker.name}`) }
+ if (override) routeNote = { id: stableId(operationId, 'route-override'), text: instead(`assigned ${worker.name}`),
+ source: { kind: 'route-override', decisionId: decision.id, by: 'lead' } }
+ else if (routed) routeNote = { id: stableId(operationId, 'route'), ...routed }
}
// The brief (a task with none: its title), and its acceptance checks when it has some: checks are information. Then
// whom this task's pull requests are for, from its own requester (projects.ts requestedByLine).
@@ -3431,8 +3463,8 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
...requestedBy ? [requestedBy] : []].join('\n\n'), [worker.id], null, SYSTEM_ROW)
const news = assignedNotice(state, group, sender, operationId)
if (news) effects.messages.push(news)
- if (routeNote) effects.messages.push({ id: stableId(operationId, 'route-override'), conversationId: group.id, author: sender,
- text: routeNote.text, replyTo: null, recipients: [], source: bookkeeping(group.id, { kind: 'route-override', decisionId: routeNote.decisionId, by: 'lead' }) })
+ if (routeNote) effects.messages.push({ id: routeNote.id, conversationId: group.id, author: sender,
+ text: routeNote.text, replyTo: null, recipients: [], source: bookkeeping(group.id, routeNote.source) })
break
}
case 'work.status': {
diff --git a/backend/src/superTabs/instructions.test.ts b/backend/src/superTabs/instructions.test.ts
index b25f99d90..34fe3f5a1 100644
--- a/backend/src/superTabs/instructions.test.ts
+++ b/backend/src/superTabs/instructions.test.ts
@@ -134,7 +134,7 @@ describe('the built-in template', () => {
expect(routing).toContain('weekly quota left above the share of its week left (with 5 of 7 days to go, above 71%)')
expect(routing).toContain('Every other account is used while it has weekly quota left: the one resetting soonest first')
expect(routing).toContain('An idle agent is reused only between candidates equal so far')
- expect(routing).toContain('"Idle" is not a reason.')
+ expect(routing).toContain('"Idle" or "first in the list" is not a reason.')
expect(routing).toContain('hands its pushed branch to an agent on another account.')
expect(routing).toContain('Urgent work (production down, security) ignores quota.')
for (const gone of ['share per day', '5-hour', 'Engineers move to the next model', 'Max 20x']) expect(routing).not.toContain(gone)
@@ -148,9 +148,18 @@ describe('the built-in template', () => {
// Ken, 2026-11-03: the route's rows now carry each account's quota, and no account is cut from them.
const routing = INSTRUCTIONS_TEMPLATE.slice(INSTRUCTIONS_TEMPLATE.indexOf('## Routing')).replace(/\n +/g, ' ')
expect(routing).toContain('- The route lists the best new agent and the best idle agent of every engine on every machine, each with its quota: '
- + 'fits or short, weekly quota left and reset time. Its order does not rank by quota: the PM applies this order itself.')
+ + 'fits or short, weekly quota left and reset time.')
expect(routing).not.toContain('The route\'s lines show')
})
+ it('says the route ranks nothing and picks nothing, and every start from it gives the rule that chose it', () => {
+ // Task #2901 (Ken, 2026-11-04): PMs took the route's first line, nearly always Opus or Astra, against this order and quota.
+ // The route now lists by machine name and names no pick; the reason goes with the start or assignment.
+ const routing = INSTRUCTIONS_TEMPLATE.slice(INSTRUCTIONS_TEMPLATE.indexOf('## Routing')).replace(/\n +/g, ' ')
+ expect(routing).toContain('It lists them by machine name, with no ranking and no pick: the PM applies this order itself.')
+ expect(routing).toContain('Every start or assignment from a route gives as its reason the rule above that chose it: urgency, context or a '
+ + 'machine the work needs where it departs from the order. "Idle" or "first in the list" is not a reason.')
+ for (const gone of ['Its order does not rank by quota', 'Picking against it needs a reason in the route\'s override']) expect(routing).not.toContain(gone)
+ })
})
describe('role names', () => {
diff --git a/backend/src/superTabs/instructionsTemplate.ts b/backend/src/superTabs/instructionsTemplate.ts
index 15cb8132a..ff0a146da 100644
--- a/backend/src/superTabs/instructionsTemplate.ts
+++ b/backend/src/superTabs/instructionsTemplate.ts
@@ -111,9 +111,10 @@ export const TEMPLATE_ROUTING = `## Routing
5. Between equals, the machine with fewer agents working. Then price.
- When no other account has weekly quota left, the PM's account takes work as any other account does.
- The route lists the best new agent and the best idle agent of every engine on every machine, each with its quota:
- fits or short, weekly quota left and reset time. Its order does not rank by quota: the PM applies this order itself.
- Picking against it needs a reason in the route's override: urgency, context, or a machine the work needs. "Idle" is
- not a reason.
+ fits or short, weekly quota left and reset time. It lists them by machine name, with no ranking and no pick: the PM
+ applies this order itself. Every start or assignment from a route gives as its reason the rule above that chose it:
+ urgency, context or a machine the work needs where it departs from the order. "Idle" or "first in the list" is not a
+ reason.
- An agent whose account runs out of weekly quota mid-task, or whose account is the PM's and falls below its line,
hands its pushed branch to an agent on another account.
- Urgent work (production down, security) ignores quota.`
diff --git a/backend/src/superTabs/routeRecord.test.ts b/backend/src/superTabs/routeRecord.test.ts
index b4257827b..a7f991971 100644
--- a/backend/src/superTabs/routeRecord.test.ts
+++ b/backend/src/superTabs/routeRecord.test.ts
@@ -4,9 +4,15 @@ import { finalMatches, readRecord, routeRecordSchema, storedRecord, type RouteRe
const candidate = (i: number) => ({ id: `c${i}`, kind: 'new', machineId: `m${i}`, engine: 'claude', model: 'opus', effort: 'high', quality: 3, cost: 3,
title: `New agent · Claude opus high · m${i}`, label: `New agent · Claude opus high · m${i}` })
+/** An older CLI's record, still taken as before: its pick, first by strength (before task #2901). */
const record = (count: number) => ({ assessment: { difficulty: 'medium', risk: 'low', why: 'Endpoint.' },
candidates: Array.from({ length: count }, (_, i) => candidate(i)), excluded: [], floor: 1, notes: false, pick: 'c0', via: 'order', p: null,
belowFloor: false, why: 'First by strength, then price and quota fit.' })
+/** The route since task #2901 (Ken, 2026-11-04): no pick and no ranking; the project's Routing instructions choose. */
+const pickless = (count: number) => {
+ const { pick: _pick, ...rest } = record(count)
+ return { ...rest, via: count === 1 ? 'only' : 'instructions', why: 'No ranking: the project\'s Routing instructions choose.' }
+}
describe('route.record', () => {
// The route shows every engine on every machine (Ken, 2026-11-03): a Swarm of a dozen Macs with two engines, a new agent and an
@@ -15,6 +21,15 @@ describe('route.record', () => {
expect(routeRecordSchema.safeParse(record(64)).success).toBe(true)
expect(routeRecordSchema.safeParse(record(65)).success).toBe(false)
})
+ // Task #2901 (Ken, 2026-11-04): the route names no pick, so PMs stop taking its top line against the Routing instructions. An
+ // older CLI still sends its pick, and that record is held to its candidates as before.
+ it('takes a record that names no pick, chosen by the instructions or the only candidate, and an older one with its pick', () => {
+ expect(routeRecordSchema.safeParse(pickless(42)).success).toBe(true)
+ expect(routeRecordSchema.safeParse(pickless(1)).success).toBe(true)
+ expect(routeRecordSchema.safeParse(record(3)).success).toBe(true)
+ expect(routeRecordSchema.safeParse({ ...record(3), pick: 'c9' }).success).toBe(false)
+ expect(routeRecordSchema.safeParse({ ...pickless(3), via: 'ranked' }).success).toBe(false)
+ })
})
describe('a route decision as stored (task #2488: ~20 KB a row since every engine on every machine)', () => {
@@ -103,6 +118,36 @@ describe('a route decision of every engine on every machine, as stored (task #27
}
})
+ // Task #2901: with no pick, nobody knows which candidate runs until the start, and the route history needs that one's account
+ // and spend (cli service.ts routeHistory). So every candidate keeps those two of its fit, and nothing else of it.
+ const pickless = (): RouteRecord => {
+ const { pick: _pick, ...rest } = routed()
+ return { ...rest, via: 'instructions', why: 'No ranking: the project\'s Routing instructions choose.' } as RouteRecord
+ }
+
+ // Measured 11-04: 14,568 bytes, of which the 42 slim fits are 5,376 (128 bytes a candidate, its 64-character account most of it).
+ it('stores a record that names no pick, 42 candidates each with its account and spend, in under 15 KB (measured 14,568 bytes)', () => {
+ expect(size(storedRecord(pickless()))).toBeLessThan(15_000)
+ })
+
+ it('keeps of every candidate of a record that names no pick who and where it is, its title and its account and spend', () => {
+ const r = pickless(), back = readRecord(storedRecord(r))
+ for (const [i, c] of r.candidates.entries()) {
+ const kept = back.candidates[i]!
+ expect(kept).toEqual({ id: c.id, kind: c.kind, ...c.agentId ? { agentId: c.agentId } : {}, machineId: c.machineId, engine: c.engine, model: c.model,
+ effort: c.effort, title: c.title, fit: { account: c.fit!.account, spend: c.fit!.spend } })
+ }
+ })
+
+ it('keeps no fit of a candidate that had none, and no account of one that had none', () => {
+ const r = pickless()
+ delete r.candidates[0]!.fit
+ delete r.candidates[1]!.fit!.account
+ const [first, second] = storedRecord(r).candidates
+ expect(first).not.toHaveProperty('fit')
+ expect(second!.fit).toEqual({ spend: { '5-hour': 2.5, weekly: 1 } })
+ })
+
it('keeps a grid model on a candidate that runs one', () => {
const r = routed()
r.candidates[5] = { ...r.candidates[5]!, kind: 'new', agentId: undefined, model: 'default', effort: 'default', gridModel: 'kimi-k3', gridName: 'Kimi K3' }
diff --git a/backend/src/superTabs/routeRecord.ts b/backend/src/superTabs/routeRecord.ts
index 784730591..818b1fc46 100644
--- a/backend/src/superTabs/routeRecord.ts
+++ b/backend/src/superTabs/routeRecord.ts
@@ -50,8 +50,11 @@ export const routeRecordSchema = z.object({
excluded: z.array(z.object({ title: z.string().trim().min(1).max(160), reason: z.string().trim().min(1).max(500) }).strict()).max(200),
floor: z.number().int().min(1).max(3),
notes: z.boolean(),
- pick: candidateId,
- via: z.enum(['jev', 'order', 'only']),
+ /** The candidate an older CLI ranked first. The route names none since task #2901 (Ken, 2026-11-04): the project's Routing
+ * instructions choose, and the start or assignment records which candidate it was (RouteFinal.candidateId). */
+ pick: candidateId.optional(),
+ /** `instructions`: no pick, the coordinator chooses by the Routing instructions (task #2901). `only` comes with or without one. */
+ via: z.enum(['jev', 'order', 'only', 'instructions']),
/** Why the policy order decided, when it did: Jev answered without enough confidence, or could not be asked. */
fallback: z.enum(['unsure', 'unavailable']).optional(),
p: z.number().min(0).max(1).nullable(),
@@ -70,11 +73,15 @@ export const routeRecordSchema = z.object({
/** The project instructions' revision the route relied on (`project.instructionsRevision ?? 0` when it was recorded), written
* by the server, never taken from the route. Absent from records before project instructions. */
instructionsRevision: z.number().int().nonnegative().optional(),
-}).strict().refine(d => d.candidates.some(c => c.id === d.pick), 'The pick must be one of the candidates.')
+}).strict().refine(d => d.pick === undefined || d.candidates.some(c => c.id === d.pick), 'The pick must be one of the candidates.')
.refine(d => new Set(d.candidates.map(c => c.id)).size === d.candidates.length, 'Candidate ids must be unique.')
-/** A candidate as a decision keeps it: the pick whole; any other only who and where it is and its title (storedRecord). */
-export type KeptCandidate = Omit<RouteCandidate, 'quality' | 'cost' | 'label' | 'fit'> & Partial<Pick<RouteCandidate, 'quality' | 'cost' | 'label' | 'fit'>>
+/** The part of a quota fit every candidate of a record without a pick keeps: what the route history reads of the one that ran. */
+export type KeptFit = Pick<z.infer<typeof fit>, 'account' | 'spend'>
+/** A candidate as a decision keeps it: the pick whole; any other only who and where it is and its title, and with no pick its
+ * account and spend too (storedRecord). */
+export type KeptCandidate = Omit<RouteCandidate, 'quality' | 'cost' | 'label' | 'fit'> & Partial<Pick<RouteCandidate, 'quality' | 'cost' | 'label'>>
+ & { fit?: RouteCandidate['fit'] | KeptFit }
/** A record as its readers get it back (readRecord): its candidates as kept. */
export type ReadRouteRecord = Omit<RouteRecord, 'candidates'> & { candidates: KeptCandidate[] }
@@ -91,11 +98,13 @@ export interface StoredRouteRecord extends Omit<ReadRouteRecord, 'excluded'> {
* and where it is (a start or assignment matching it, startedAs; a person choosing it, route.override; its Team-work check) and
* its title (the chat lines, Desktop's Details). Its label, strength, cost and quota fit are read of the pick only: the route
* showed the others when it ran, and the route history takes the account and spend of the pick (cli service.ts routeHistory).
- * Each exclusion reason is kept once, with its titles in order. */
+ * A record with no pick (task #2901) keeps every candidate's account and spend instead, as any of them may be the one that
+ * runs and nobody knows which until the start. Each exclusion reason is kept once, with its titles in order. */
export function storedRecord(record: RouteRecord): StoredRouteRecord {
const { excluded, ...rest } = record
- const candidates = record.candidates.map(({ label: _label, quality: _quality, cost: _cost, fit: _fit, ...c }, i) =>
- c.id === record.pick ? record.candidates[i]! : c)
+ const candidates = record.candidates.map(({ label: _label, quality: _quality, cost: _cost, fit, ...c }, i): KeptCandidate =>
+ record.pick === undefined ? { ...c, ...fit ? { fit: { ...fit.account ? { account: fit.account } : {}, spend: fit.spend } } : {} }
+ : c.id === record.pick ? record.candidates[i]! : c)
const byReason = new Map<string, string[]>()
for (const { title, reason } of excluded) byReason.set(reason, [...byReason.get(reason) ?? [], title])
return { ...rest, candidates, ...byReason.size ? { unavailable: [...byReason].map(([reason, titles]) => ({ reason, titles })) } : { excluded: [] } }
@@ -125,11 +134,13 @@ export const finalMatches = (candidate: KeptCandidate, final: RouteFinal | null)
export type RouteCandidate = z.infer<typeof routeCandidateSchema>
export type RouteRecord = z.infer<typeof routeRecordSchema>
+/** `candidateId` names the candidate the start or assignment matched when the record has no pick (task #2901): the
+ * coordinator's own choice by the Routing instructions, which the route history reads back. */
export type RouteFinal =
- | { kind: 'member'; agentId: string; machineId: string }
+ | { kind: 'member'; agentId: string; machineId: string; candidateId?: string }
/** After a failed model switch, `model` and `effort` are what ran and `requested` is what routing asked for. */
| { kind: 'new'; startId: string; machineId: string; engine: string; model: string; effort: string; requested?: { model: string; effort: string };
- gridModel?: string; gridName?: string }
+ gridModel?: string; gridName?: string; candidateId?: string }
export interface RouteOverride { by: 'lead' | 'person'; actorKey: string; candidateId?: string; reason: string }
export interface RouteDecision {
id: string; conversationId: string; record: ReadRouteRecord
diff --git a/backend/src/superTabs/teamRouting.test.ts b/backend/src/superTabs/teamRouting.test.ts
index 6ca8bceec..2d5f7736b 100644
--- a/backend/src/superTabs/teamRouting.test.ts
+++ b/backend/src/superTabs/teamRouting.test.ts
@@ -305,6 +305,21 @@ describe('routing a teammate\'s work', () => {
message: 'MacBook Pro has no Harness Team account yet, so it runs only its owner\'s projects. Route again.' })
})
+ // Task #2901 (Ken, 2026-11-04): a route names no pick, so no single refusal decides it; it is refused once no candidate is left.
+ it('leaves out of a route that names no pick what cannot take it, and refuses it once nothing is left', () => {
+ const f = routed()
+ const pickless = (candidates: unknown[]) => {
+ const { pick: _pick, ...rest } = record(candidates)
+ return { ...rest, via: 'instructions', floor: 1, why: 'No ranking: the project\'s Routing instructions choose.' }
+ }
+ const effects = f.run({ type: 'route.record', conversationId: f.group, decision: pickless([candidate('c0', 'mate-mac'), candidate('c1', 'mate-team')]) } as Command,
+ f.leadActor, {})
+ expect(effects.routeDecisions[0]).toMatchObject({ op: 'create', record: { candidates: [{ id: 'c1' }],
+ excluded: [{ title: 'c0 on mate-mac', reason: 'MacBook Pro has no Harness Team account yet, so it runs only its owner\'s projects.' }, { title: 'Owner Mac · claude' }] } })
+ expect(refusal(() => f.run({ type: 'route.record', conversationId: f.group, decision: pickless([candidate('c0', 'mate-mac')]) } as Command, f.leadActor, {})))
+ .toMatchObject({ code: 'TEAM_ACCOUNT_REQUIRED', message: 'MacBook Pro has no Harness Team account yet, so it runs only its owner\'s projects. Route again.' })
+ })
+
it('refuses a person\'s reroute to a candidate whose machine can no longer take it', () => {
const f = routed()
const decision = { id: 'd1', conversationId: f.group, record: record([candidate('c0', 'owner-mac'), candidate('c1', 'mate-team')]),
diff --git a/cli/src/lib/swarmTools.spec.ts b/cli/src/lib/swarmTools.spec.ts
index 56483a98a..a5ab01578 100644
--- a/cli/src/lib/swarmTools.spec.ts
+++ b/cli/src/lib/swarmTools.spec.ts
@@ -23,6 +23,13 @@ describe('SWARM_TOOLS_SKILL', () => {
for (const part of ['Team account', 'nobody types in it', 'none of the owner\'s tools', 'in their own session', 'handoff',
'## GitHub', 'GitHub App', 'pull requests', 'where the repository\'s installation of the App granted it', 'Never ask a person to sudo', 'Never ask for a token']) expect(section).toContain(part)
})
+ // Task #2901 (Ken, 2026-11-04): PMs took the route's top line against the project's Routing instructions.
+ it('says the route ranks nothing and names no pick, and that a start gives the Routing rule that chose it', () => {
+ expect(SWARM_TOOLS_SKILL).toContain('It ranks nothing and names no pick: the rest come by machine name, then engine')
+ expect(SWARM_TOOLS_SKILL).toContain('choose by your project\'s Routing instructions')
+ expect(SWARM_TOOLS_SKILL).toContain('`routeDecisionId` and `overrideReason`: the Routing rule that chose it')
+ expect(SWARM_TOOLS_SKILL).not.toMatch(/ranks the rest|by strength, then price|choose by strength|A pick on|ranks who could/)
+ })
it('describes the commands the server accepts now', () => {
expect(SWARM_TOOLS_SKILL).not.toMatch(/Refused to some agents|route first|hard rules|rated 3|rule\.set|project\.skills/)
for (const part of ['post GROUP', '--to AGENT', 'instructions', 'instructions.save']) expect(SWARM_TOOLS_SKILL).toContain(part)
diff --git a/cli/src/lib/swarmTools.ts b/cli/src/lib/swarmTools.ts
index 904314d8e..e259fc387 100644
--- a/cli/src/lib/swarmTools.ts
+++ b/cli/src/lib/swarmTools.ts
@@ -82,14 +82,14 @@ Swarm and machine settings (each refused unless you may change that setting; a p
- Remove a note: \`{"type":"note.remove","projectId":"PROJECT","noteId":"NOTE"}\` (each note's id is in the \`instructions\` output): the coordinator, or a person who reads the project. An expired note is already gone.
## Route and start
-- \`route GROUP JSON\` ranks who could do a group's work, before you start an agent or assign it. Work you do yourself is not routed. JSON: \`{"difficulty":"low|medium|high","risk":"low|medium|high","size":"small|medium|large","why":"one sentence","kind":"${ROUTE_KIND_HELP}","local":true,"model":"optional","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}\`.
+- \`route GROUP JSON\` lists who could do a group's work, before you start an agent or assign it. Work you do yourself is not routed. JSON: \`{"difficulty":"low|medium|high","risk":"low|medium|high","size":"small|medium|large","why":"one sentence","kind":"${ROUTE_KIND_HELP}","local":true,"model":"optional","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}\`.
- size is how long the work runs: small about 20 minutes, medium about an hour, large about three hours.
- \`local\` only when a person asked for a local model. When a person names a model, set \`model\` to their words ("deepseek 4.1 flash"): the route then offers that model alone, unrated when the catalog does not list it.
- It leaves out what cannot run (a machine offline, paused or full, an engine signed out or suspended, tools or devices the work needs, a machine that cannot take a teammate's project), and says why.
- ${CHEAP_FIRST_HELP}
- - It ranks the rest by strength, then price and quota fit, then an idle agent before a new one. What else it knows is a note on the candidate: a used-up quota, a lost task, a machine whose last starts failed, a task requirement naming another machine, a model not offered by default. Your instructions say how to choose; where they say nothing, choose by strength, quota and price.
- - A pick on a model served on the Swarm's grid starts with the \`gridModel\` and \`gridName\` the route gives, in place of model and effort.
-- Start or assign any candidate with the decision's \`routeDecisionId\`; a reason for choosing another (\`overrideReason\`) is optional.
+ - It ranks nothing and names no pick: the rest come by machine name, then engine, each with its facts (model, effort, the catalog's strength and price, quota fit with weekly % left and reset time, the agents on its machine, idle or new). What else it knows is a note on the candidate: a used-up quota, a lost task, a machine whose last starts failed, a task requirement naming another machine, a model not offered by default, a plug-in's finding. The first row is first by its machine's name, not by merit: choose by your project's Routing instructions.
+ - A candidate on a model served on the Swarm's grid starts with the \`gridModel\` and \`gridName\` its row gives, in place of model and effort.
+- Start or assign the candidate you chose with the decision's \`routeDecisionId\` and \`overrideReason\`: the Routing rule that chose it, in one sentence. The decision records the candidate the start or assignment matches.
- \`plan [JSON]\` places all open groups at once on machines and models (needs Python 3 and OR-Tools; without them it says how to install). JSON optional: \`{"groups":{"GROUP":{"difficulty":"...","risk":"...","size":"...","kind":"optional","after":["GROUP"]}}}\`. It records nothing: route each group, then start the plan's pick with the route's \`routeDecisionId\`.
- \`capacity MACHINE_ID JSON\` inspects a machine's, engine's and quota headroom (JSON: the start fields). Unknown allowances are not reported as free tokens.
- \`start OPERATION_ID JSON\` creates one agent in a conversation on a machine in the Swarm's Machines list; it does not assign work. JSON:
diff --git a/cli/src/superTabs/__snapshots__/route.answers.json b/cli/src/superTabs/__snapshots__/route.answers.json
index 8db128353..a50061c9f 100644
--- a/cli/src/superTabs/__snapshots__/route.answers.json
+++ b/cli/src/superTabs/__snapshots__/route.answers.json
@@ -4,14 +4,14 @@
"choice": {
"shown": [
{
- "kind": "new",
+ "kind": "member",
"machineId": "a",
"machineName": "a",
"engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
+ "model": "sonnet",
+ "effort": "medium",
+ "quality": 2,
+ "cost": 2,
"quota": {
"known": true,
"leftPercent": 80,
@@ -30,34 +30,52 @@
],
"account": "a"
},
- "activity": "new",
+ "activity": "idle",
"known": true,
"refusals": [],
"notes": [],
+ "agentId": "m1",
+ "name": "Multiply",
+ "repo": "same",
+ "frame": {
+ "title": "Fix the dial",
+ "project": "openharness",
+ "cwd": "/r",
+ "root": "/r",
+ "remote": "github.com/o/r",
+ "branch": "fix/dial",
+ "updatedAt": 998800000
+ },
+ "earlier": [
+ {
+ "group": "Dial fix",
+ "outcome": "merged"
+ }
+ ],
"fit": {
"status": "fits",
- "coverage": 1.78,
- "effectiveCost": 3,
+ "coverage": 2.67,
+ "effectiveCost": 2,
"expiring": 0,
"spend": {
- "5-hour": 45,
- "weekly": 6
+ "5-hour": 30,
+ "weekly": 4
},
"account": "a"
},
"id": "c0",
- "title": "New agent · Claude opus high · a",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (80% left, resets in 3h); weekly 6% of 90% · a · new · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "Multiply · Claude sonnet medium · a",
+ "label": "Member Multiply · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (80% left, resets in 3h); weekly 4% of 90% · a · idle · same repo · on \"Fix the dial\" · in openharness, branch fix/dial · last active 20m ago · earlier here: Dial fix merged · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
- "kind": "member",
+ "kind": "new",
"machineId": "a",
"machineName": "a",
"engine": "claude",
- "model": "sonnet",
- "effort": "medium",
- "quality": 2,
- "cost": 2,
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
"quota": {
"known": true,
"leftPercent": 80,
@@ -76,42 +94,24 @@
],
"account": "a"
},
- "activity": "idle",
+ "activity": "new",
"known": true,
"refusals": [],
"notes": [],
- "agentId": "m1",
- "name": "Multiply",
- "repo": "same",
- "frame": {
- "title": "Fix the dial",
- "project": "openharness",
- "cwd": "/r",
- "root": "/r",
- "remote": "github.com/o/r",
- "branch": "fix/dial",
- "updatedAt": 998800000
- },
- "earlier": [
- {
- "group": "Dial fix",
- "outcome": "merged"
- }
- ],
"fit": {
"status": "fits",
- "coverage": 2.67,
- "effectiveCost": 2,
+ "coverage": 1.78,
+ "effectiveCost": 3,
"expiring": 0,
"spend": {
- "5-hour": 30,
- "weekly": 4
+ "5-hour": 45,
+ "weekly": 6
},
"account": "a"
},
"id": "c1",
- "title": "Multiply · Claude sonnet medium · a",
- "label": "Member Multiply · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (80% left, resets in 3h); weekly 4% of 90% · a · idle · same repo · on \"Fix the dial\" · in openharness, branch fix/dial · last active 20m ago · earlier here: Dial fix merged · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude opus high · a",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (80% left, resets in 3h); weekly 6% of 90% · a · new · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
@@ -263,55 +263,9 @@
"belowFloor": false
},
"verdict": {
- "pick": {
- "kind": "new",
- "machineId": "a",
- "machineName": "a",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "quota": {
- "known": true,
- "leftPercent": 80,
- "resetsAt": null,
- "windows": [
- {
- "name": "5-hour",
- "leftPercent": 80,
- "resetsAt": 1010800000
- },
- {
- "name": "weekly",
- "leftPercent": 90,
- "resetsAt": 1432000000
- }
- ],
- "account": "a"
- },
- "activity": "new",
- "known": true,
- "refusals": [],
- "notes": [],
- "fit": {
- "status": "fits",
- "coverage": 1.78,
- "effectiveCost": 3,
- "expiring": 0,
- "spend": {
- "5-hour": 45,
- "weekly": 6
- },
- "account": "a"
- },
- "id": "c0",
- "title": "New agent · Claude opus high · a",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (80% left, resets in 3h); weekly 6% of 90% · a · new · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
- },
- "via": "order",
+ "via": "instructions",
"p": null,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
},
"record": {
"assessment": {
@@ -323,29 +277,6 @@
"candidates": [
{
"id": "c0",
- "kind": "new",
- "machineId": "a",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "title": "New agent · Claude opus high · a",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (80% left, resets in 3h); weekly 6% of 90% · a · new · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)",
- "fit": {
- "status": "fits",
- "coverage": 1.78,
- "effectiveCost": 3,
- "expiring": 0,
- "spend": {
- "5-hour": 45,
- "weekly": 6
- },
- "account": "a"
- }
- },
- {
- "id": "c1",
"kind": "member",
"agentId": "m1",
"machineId": "a",
@@ -368,6 +299,29 @@
"account": "a"
}
},
+ {
+ "id": "c1",
+ "kind": "new",
+ "machineId": "a",
+ "engine": "claude",
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
+ "title": "New agent · Claude opus high · a",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (80% left, resets in 3h); weekly 6% of 90% · a · new · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "fit": {
+ "status": "fits",
+ "coverage": 1.78,
+ "effectiveCost": 3,
+ "expiring": 0,
+ "spend": {
+ "5-hour": 45,
+ "weekly": 6
+ },
+ "account": "a"
+ }
+ },
{
"id": "c2",
"kind": "new",
@@ -442,43 +396,42 @@
"excluded": [],
"floor": 1,
"notes": false,
- "pick": "c0",
- "via": "order",
+ "via": "instructions",
"p": null,
"belowFloor": false,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
}
},
{
- "name": "high, large: strong pick short, weaker one fits",
+ "name": "high, large: a strong candidate short, a weaker one fits",
"choice": {
"shown": [
{
"kind": "new",
- "machineId": "b",
- "machineName": "b",
- "engine": "codex",
- "model": "default",
- "effort": "default",
+ "machineId": "a",
+ "machineName": "a",
+ "engine": "claude",
+ "model": "opus",
+ "effort": "high",
"quality": 3,
- "cost": 2,
+ "cost": 3,
"quota": {
"known": true,
- "leftPercent": 5,
+ "leftPercent": 20,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 5,
+ "leftPercent": 20,
"resetsAt": 1014400000
},
{
"name": "weekly",
- "leftPercent": 60,
- "resetsAt": 1259200000
+ "leftPercent": 50,
+ "resetsAt": 1432000000
}
],
- "account": "B"
+ "account": "A"
},
"activity": "new",
"known": true,
@@ -486,45 +439,45 @@
"notes": [],
"fit": {
"status": "short",
- "coverage": 0.1,
- "effectiveCost": 1.8,
- "expiring": 0.1,
+ "coverage": 0.27,
+ "effectiveCost": 2.2,
+ "expiring": 0.27,
"spend": {
- "5-hour": 50,
- "weekly": 8
+ "5-hour": 75,
+ "weekly": 12
},
- "account": "B"
+ "account": "A"
},
"id": "c0",
- "title": "New agent · Codex default default · b",
- "label": "New agent · Codex default default · strength 3, cost 2 · short: needs about 50% of the 5-hour window (5% left, resets in 4h, otherwise unused); weekly 8% of 60% · b · new · quota 5-hour 5% left (resets in 4h), weekly 60% left (resets in 3 days)"
+ "title": "New agent · Claude opus high · a",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 75% of the 5-hour window (20% left, resets in 4h, otherwise unused); weekly 12% of 50% · a · new · quota 5-hour 20% left (resets in 4h), weekly 50% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "a",
- "machineName": "a",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
+ "machineId": "b",
+ "machineName": "b",
+ "engine": "codex",
+ "model": "default",
+ "effort": "default",
"quality": 3,
- "cost": 3,
+ "cost": 2,
"quota": {
"known": true,
- "leftPercent": 20,
+ "leftPercent": 5,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 20,
+ "leftPercent": 5,
"resetsAt": 1014400000
},
{
"name": "weekly",
- "leftPercent": 50,
- "resetsAt": 1432000000
+ "leftPercent": 60,
+ "resetsAt": 1259200000
}
],
- "account": "A"
+ "account": "B"
},
"activity": "new",
"known": true,
@@ -532,18 +485,18 @@
"notes": [],
"fit": {
"status": "short",
- "coverage": 0.27,
- "effectiveCost": 2.2,
- "expiring": 0.27,
+ "coverage": 0.1,
+ "effectiveCost": 1.8,
+ "expiring": 0.1,
"spend": {
- "5-hour": 75,
- "weekly": 12
+ "5-hour": 50,
+ "weekly": 8
},
- "account": "A"
+ "account": "B"
},
"id": "c1",
- "title": "New agent · Claude opus high · a",
- "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 75% of the 5-hour window (20% left, resets in 4h, otherwise unused); weekly 12% of 50% · a · new · quota 5-hour 20% left (resets in 4h), weekly 50% left (resets in 5 days)"
+ "title": "New agent · Codex default default · b",
+ "label": "New agent · Codex default default · strength 3, cost 2 · short: needs about 50% of the 5-hour window (5% left, resets in 4h, otherwise unused); weekly 8% of 60% · b · new · quota 5-hour 5% left (resets in 4h), weekly 60% left (resets in 3 days)"
},
{
"kind": "new",
@@ -594,59 +547,12 @@
],
"excluded": [],
"floor": 1,
- "belowFloor": false,
- "short": "The first candidate's 5-hour quota is expected to run out partway and resets in 4h; New agent · Claude sonnet medium · c fits."
+ "belowFloor": false
},
"verdict": {
- "pick": {
- "kind": "new",
- "machineId": "b",
- "machineName": "b",
- "engine": "codex",
- "model": "default",
- "effort": "default",
- "quality": 3,
- "cost": 2,
- "quota": {
- "known": true,
- "leftPercent": 5,
- "resetsAt": null,
- "windows": [
- {
- "name": "5-hour",
- "leftPercent": 5,
- "resetsAt": 1014400000
- },
- {
- "name": "weekly",
- "leftPercent": 60,
- "resetsAt": 1259200000
- }
- ],
- "account": "B"
- },
- "activity": "new",
- "known": true,
- "refusals": [],
- "notes": [],
- "fit": {
- "status": "short",
- "coverage": 0.1,
- "effectiveCost": 1.8,
- "expiring": 0.1,
- "spend": {
- "5-hour": 50,
- "weekly": 8
- },
- "account": "B"
- },
- "id": "c0",
- "title": "New agent · Codex default default · b",
- "label": "New agent · Codex default default · strength 3, cost 2 · short: needs about 50% of the 5-hour window (5% left, resets in 4h, otherwise unused); weekly 8% of 60% · b · new · quota 5-hour 5% left (resets in 4h), weekly 60% left (resets in 3 days)"
- },
- "via": "order",
+ "via": "instructions",
"p": null,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
},
"record": {
"assessment": {
@@ -659,6 +565,29 @@
{
"id": "c0",
"kind": "new",
+ "machineId": "a",
+ "engine": "claude",
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
+ "title": "New agent · Claude opus high · a",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 75% of the 5-hour window (20% left, resets in 4h, otherwise unused); weekly 12% of 50% · a · new · quota 5-hour 20% left (resets in 4h), weekly 50% left (resets in 5 days)",
+ "fit": {
+ "status": "short",
+ "coverage": 0.27,
+ "effectiveCost": 2.2,
+ "expiring": 0.27,
+ "spend": {
+ "5-hour": 75,
+ "weekly": 12
+ },
+ "account": "A"
+ }
+ },
+ {
+ "id": "c1",
+ "kind": "new",
"machineId": "b",
"engine": "codex",
"model": "default",
@@ -680,32 +609,9 @@
}
},
{
- "id": "c1",
+ "id": "c2",
"kind": "new",
- "machineId": "a",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "title": "New agent · Claude opus high · a",
- "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 75% of the 5-hour window (20% left, resets in 4h, otherwise unused); weekly 12% of 50% · a · new · quota 5-hour 20% left (resets in 4h), weekly 50% left (resets in 5 days)",
- "fit": {
- "status": "short",
- "coverage": 0.27,
- "effectiveCost": 2.2,
- "expiring": 0.27,
- "spend": {
- "5-hour": 75,
- "weekly": 12
- },
- "account": "A"
- }
- },
- {
- "id": "c2",
- "kind": "new",
- "machineId": "c",
+ "machineId": "c",
"engine": "claude",
"model": "sonnet",
"effort": "medium",
@@ -729,11 +635,10 @@
"excluded": [],
"floor": 1,
"notes": false,
- "pick": "c0",
- "via": "order",
+ "via": "instructions",
"p": null,
"belowFloor": false,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
}
},
{
@@ -788,25 +693,30 @@
},
{
"kind": "new",
- "machineId": "c",
- "machineName": "c",
- "engine": "codex",
- "model": "default",
- "effort": "default",
+ "machineId": "b",
+ "machineName": "b",
+ "engine": "claude",
+ "model": "opus",
+ "effort": "high",
"quality": 3,
- "cost": 2,
+ "cost": 3,
"quota": {
"known": true,
- "leftPercent": 30,
+ "leftPercent": 40,
"resetsAt": null,
"windows": [
+ {
+ "name": "5-hour",
+ "leftPercent": 40,
+ "resetsAt": 1014400000
+ },
{
"name": "weekly",
- "leftPercent": 30,
- "resetsAt": 1518400000
+ "leftPercent": 80,
+ "resetsAt": 1172800000
}
],
- "account": "C"
+ "account": "B"
},
"activity": "new",
"known": true,
@@ -814,45 +724,40 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 30,
- "effectiveCost": 2,
+ "coverage": 2.67,
+ "effectiveCost": 3,
"expiring": 0,
"spend": {
- "5-hour": 10,
- "weekly": 1
+ "5-hour": 15,
+ "weekly": 1.5
},
- "account": "C"
+ "account": "B"
},
"id": "c1",
- "title": "New agent · Codex default default · c",
- "label": "New agent · Codex default default · strength 3, cost 2 · fits: 5-hour window unknown; weekly 1% of 30% · c · new · quota weekly 30% left (resets in 6 days)"
+ "title": "New agent · Claude opus high · b",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 15% of the 5-hour window (40% left, resets in 4h); weekly 2% of 80% · b · new · quota 5-hour 40% left (resets in 4h), weekly 80% left (resets in 2 days)"
},
{
"kind": "new",
- "machineId": "b",
- "machineName": "b",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
+ "machineId": "c",
+ "machineName": "c",
+ "engine": "codex",
+ "model": "default",
+ "effort": "default",
"quality": 3,
- "cost": 3,
+ "cost": 2,
"quota": {
"known": true,
- "leftPercent": 40,
+ "leftPercent": 30,
"resetsAt": null,
"windows": [
- {
- "name": "5-hour",
- "leftPercent": 40,
- "resetsAt": 1014400000
- },
{
"name": "weekly",
- "leftPercent": 80,
- "resetsAt": 1172800000
+ "leftPercent": 30,
+ "resetsAt": 1518400000
}
],
- "account": "B"
+ "account": "C"
},
"activity": "new",
"known": true,
@@ -860,18 +765,18 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 2.67,
- "effectiveCost": 3,
+ "coverage": 30,
+ "effectiveCost": 2,
"expiring": 0,
"spend": {
- "5-hour": 15,
- "weekly": 1.5
+ "5-hour": 10,
+ "weekly": 1
},
- "account": "B"
+ "account": "C"
},
"id": "c2",
- "title": "New agent · Claude opus high · b",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 15% of the 5-hour window (40% left, resets in 4h); weekly 2% of 80% · b · new · quota 5-hour 40% left (resets in 4h), weekly 80% left (resets in 2 days)"
+ "title": "New agent · Codex default default · c",
+ "label": "New agent · Codex default default · strength 3, cost 2 · fits: 5-hour window unknown; weekly 1% of 30% · c · new · quota weekly 30% left (resets in 6 days)"
}
],
"excluded": [],
@@ -879,55 +784,9 @@
"belowFloor": false
},
"verdict": {
- "pick": {
- "kind": "new",
- "machineId": "a",
- "machineName": "a",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "quota": {
- "known": true,
- "leftPercent": 10,
- "resetsAt": null,
- "windows": [
- {
- "name": "5-hour",
- "leftPercent": 70,
- "resetsAt": 1001200000
- },
- {
- "name": "weekly",
- "leftPercent": 10,
- "resetsAt": 1518400000
- }
- ],
- "account": "A"
- },
- "activity": "new",
- "known": true,
- "refusals": [],
- "notes": [],
- "fit": {
- "status": "fits",
- "coverage": 4.67,
- "effectiveCost": 0,
- "expiring": 1,
- "spend": {
- "5-hour": 15,
- "weekly": 1.5
- },
- "account": "A"
- },
- "id": "c0",
- "title": "New agent · Claude opus high · a",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 15% of the 5-hour window (70% left, resets in 20m, otherwise unused); weekly 2% of 10% · a · new · quota 5-hour 70% left (resets in 20m), weekly 10% left (resets in 6 days)"
- },
- "via": "order",
+ "via": "instructions",
"p": null,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
},
"record": {
"assessment": {
@@ -964,29 +823,6 @@
{
"id": "c1",
"kind": "new",
- "machineId": "c",
- "engine": "codex",
- "model": "default",
- "effort": "default",
- "quality": 3,
- "cost": 2,
- "title": "New agent · Codex default default · c",
- "label": "New agent · Codex default default · strength 3, cost 2 · fits: 5-hour window unknown; weekly 1% of 30% · c · new · quota weekly 30% left (resets in 6 days)",
- "fit": {
- "status": "fits",
- "coverage": 30,
- "effectiveCost": 2,
- "expiring": 0,
- "spend": {
- "5-hour": 10,
- "weekly": 1
- },
- "account": "C"
- }
- },
- {
- "id": "c2",
- "kind": "new",
"machineId": "b",
"engine": "claude",
"model": "opus",
@@ -1006,16 +842,38 @@
},
"account": "B"
}
+ },
+ {
+ "id": "c2",
+ "kind": "new",
+ "machineId": "c",
+ "engine": "codex",
+ "model": "default",
+ "effort": "default",
+ "quality": 3,
+ "cost": 2,
+ "title": "New agent · Codex default default · c",
+ "label": "New agent · Codex default default · strength 3, cost 2 · fits: 5-hour window unknown; weekly 1% of 30% · c · new · quota weekly 30% left (resets in 6 days)",
+ "fit": {
+ "status": "fits",
+ "coverage": 30,
+ "effectiveCost": 2,
+ "expiring": 0,
+ "spend": {
+ "5-hour": 10,
+ "weekly": 1
+ },
+ "account": "C"
+ }
}
],
"excluded": [],
"floor": 1,
"notes": false,
- "pick": "c0",
- "via": "order",
+ "via": "instructions",
"p": null,
"belowFloor": false,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
}
},
{
@@ -1024,8 +882,8 @@
"shown": [
{
"kind": "new",
- "machineId": "b",
- "machineName": "b",
+ "machineId": "a",
+ "machineName": "a",
"engine": "claude",
"model": "opus",
"effort": "high",
@@ -1033,12 +891,12 @@
"cost": 3,
"quota": {
"known": true,
- "leftPercent": 45,
+ "leftPercent": 50,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 45,
+ "leftPercent": 50,
"resetsAt": 1010800000
},
{
@@ -1047,31 +905,31 @@
"resetsAt": 1432000000
}
],
- "account": "B"
+ "account": "A"
},
"activity": "new",
"known": true,
"refusals": [],
"notes": [],
"fit": {
- "status": "fits",
- "coverage": 1,
+ "status": "short",
+ "coverage": 0.56,
"effectiveCost": 3,
"expiring": 0,
"spend": {
"5-hour": 45,
"weekly": 6
},
- "account": "B"
+ "account": "A"
},
"id": "c0",
- "title": "New agent · Claude opus high · b",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (45% left, resets in 3h); weekly 6% of 50% · b · new · quota 5-hour 45% left (resets in 3h), weekly 50% left (resets in 5 days)"
+ "title": "New agent · Claude opus high · a",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 45% of the 5-hour window (25% left, resets in 3h); weekly 6% of 47% · a · new · quota 5-hour 50% left (resets in 3h), weekly 50% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "a",
- "machineName": "a",
+ "machineId": "b",
+ "machineName": "b",
"engine": "claude",
"model": "opus",
"effort": "high",
@@ -1079,12 +937,12 @@
"cost": 3,
"quota": {
"known": true,
- "leftPercent": 50,
+ "leftPercent": 45,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 50,
+ "leftPercent": 45,
"resetsAt": 1010800000
},
{
@@ -1093,26 +951,26 @@
"resetsAt": 1432000000
}
],
- "account": "A"
+ "account": "B"
},
"activity": "new",
"known": true,
"refusals": [],
"notes": [],
"fit": {
- "status": "short",
- "coverage": 0.56,
+ "status": "fits",
+ "coverage": 1,
"effectiveCost": 3,
"expiring": 0,
"spend": {
"5-hour": 45,
"weekly": 6
},
- "account": "A"
+ "account": "B"
},
"id": "c1",
- "title": "New agent · Claude opus high · a",
- "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 45% of the 5-hour window (25% left, resets in 3h); weekly 6% of 47% · a · new · quota 5-hour 50% left (resets in 3h), weekly 50% left (resets in 5 days)"
+ "title": "New agent · Claude opus high · b",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (45% left, resets in 3h); weekly 6% of 50% · b · new · quota 5-hour 45% left (resets in 3h), weekly 50% left (resets in 5 days)"
}
],
"excluded": [],
@@ -1120,55 +978,9 @@
"belowFloor": false
},
"verdict": {
- "pick": {
- "kind": "new",
- "machineId": "b",
- "machineName": "b",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "quota": {
- "known": true,
- "leftPercent": 45,
- "resetsAt": null,
- "windows": [
- {
- "name": "5-hour",
- "leftPercent": 45,
- "resetsAt": 1010800000
- },
- {
- "name": "weekly",
- "leftPercent": 50,
- "resetsAt": 1432000000
- }
- ],
- "account": "B"
- },
- "activity": "new",
- "known": true,
- "refusals": [],
- "notes": [],
- "fit": {
- "status": "fits",
- "coverage": 1,
- "effectiveCost": 3,
- "expiring": 0,
- "spend": {
- "5-hour": 45,
- "weekly": 6
- },
- "account": "B"
- },
- "id": "c0",
- "title": "New agent · Claude opus high · b",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (45% left, resets in 3h); weekly 6% of 50% · b · new · quota 5-hour 45% left (resets in 3h), weekly 50% left (resets in 5 days)"
- },
- "via": "order",
+ "via": "instructions",
"p": null,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
},
"record": {
"assessment": {
@@ -1181,58 +993,57 @@
{
"id": "c0",
"kind": "new",
- "machineId": "b",
+ "machineId": "a",
"engine": "claude",
"model": "opus",
"effort": "high",
"quality": 3,
"cost": 3,
- "title": "New agent · Claude opus high · b",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (45% left, resets in 3h); weekly 6% of 50% · b · new · quota 5-hour 45% left (resets in 3h), weekly 50% left (resets in 5 days)",
+ "title": "New agent · Claude opus high · a",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 45% of the 5-hour window (25% left, resets in 3h); weekly 6% of 47% · a · new · quota 5-hour 50% left (resets in 3h), weekly 50% left (resets in 5 days)",
"fit": {
- "status": "fits",
- "coverage": 1,
+ "status": "short",
+ "coverage": 0.56,
"effectiveCost": 3,
"expiring": 0,
"spend": {
"5-hour": 45,
"weekly": 6
},
- "account": "B"
+ "account": "A"
}
},
{
"id": "c1",
"kind": "new",
- "machineId": "a",
+ "machineId": "b",
"engine": "claude",
"model": "opus",
"effort": "high",
"quality": 3,
"cost": 3,
- "title": "New agent · Claude opus high · a",
- "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 45% of the 5-hour window (25% left, resets in 3h); weekly 6% of 47% · a · new · quota 5-hour 50% left (resets in 3h), weekly 50% left (resets in 5 days)",
+ "title": "New agent · Claude opus high · b",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (45% left, resets in 3h); weekly 6% of 50% · b · new · quota 5-hour 45% left (resets in 3h), weekly 50% left (resets in 5 days)",
"fit": {
- "status": "short",
- "coverage": 0.56,
+ "status": "fits",
+ "coverage": 1,
"effectiveCost": 3,
"expiring": 0,
"spend": {
"5-hour": 45,
"weekly": 6
},
- "account": "A"
+ "account": "B"
}
}
],
"excluded": [],
"floor": 1,
"notes": false,
- "pick": "c0",
- "via": "order",
+ "via": "instructions",
"p": null,
"belowFloor": false,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
}
},
{
@@ -1380,43 +1191,9 @@
"belowFloor": false
},
"verdict": {
- "pick": {
- "kind": "new",
- "machineId": "a",
- "machineName": "a",
- "engine": "codex",
- "model": "default",
- "effort": "default",
- "quality": 3,
- "cost": 2,
- "quota": {
- "known": true,
- "leftPercent": null,
- "resetsAt": null,
- "metered": true
- },
- "activity": "new",
- "known": true,
- "refusals": [],
- "notes": [],
- "fit": {
- "status": "fits",
- "coverage": null,
- "effectiveCost": 2,
- "expiring": 0,
- "spend": {
- "5-hour": 30,
- "weekly": 4
- },
- "account": "a:codex"
- },
- "id": "c0",
- "title": "New agent · Codex default default · a",
- "label": "New agent · Codex default default · strength 3, cost 2 · fits: metered, no usage window to run out · a · new · quota metered"
- },
- "via": "order",
+ "via": "instructions",
"p": null,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
},
"record": {
"assessment": {
@@ -1522,11 +1299,10 @@
"excluded": [],
"floor": 1,
"notes": false,
- "pick": "c0",
- "via": "order",
+ "via": "instructions",
"p": null,
"belowFloor": false,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
}
},
{
@@ -1535,21 +1311,21 @@
"shown": [
{
"kind": "new",
- "machineId": "m05",
- "machineName": "m05",
+ "machineId": "m00",
+ "machineName": "m00",
"engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
+ "model": "sonnet",
+ "effort": "medium",
+ "quality": 2,
+ "cost": 2,
"quota": {
"known": true,
- "leftPercent": 50,
+ "leftPercent": 30,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 50,
+ "leftPercent": 30,
"resetsAt": 1010800000
},
{
@@ -1558,7 +1334,7 @@
"resetsAt": 1432000000
}
],
- "account": "acct5"
+ "account": "acct0"
},
"activity": "new",
"known": true,
@@ -1566,23 +1342,23 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 1.11,
- "effectiveCost": 3,
+ "coverage": 1,
+ "effectiveCost": 2,
"expiring": 0,
"spend": {
- "5-hour": 45,
- "weekly": 6
+ "5-hour": 30,
+ "weekly": 4
},
- "account": "acct5"
+ "account": "acct0"
},
"id": "c0",
- "title": "New agent · Claude opus high · m05",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (50% left, resets in 3h); weekly 6% of 90% · m05 · new · quota 5-hour 50% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude sonnet medium · m00",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (30% left, resets in 3h); weekly 4% of 90% · m00 · new · quota 5-hour 30% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m07",
- "machineName": "m07",
+ "machineId": "m01",
+ "machineName": "m01",
"engine": "claude",
"model": "opus",
"effort": "high",
@@ -1590,12 +1366,12 @@
"cost": 3,
"quota": {
"known": true,
- "leftPercent": 58,
+ "leftPercent": 34,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 58,
+ "leftPercent": 34,
"resetsAt": 1010800000
},
{
@@ -1604,44 +1380,44 @@
"resetsAt": 1432000000
}
],
- "account": "acct7"
+ "account": "acct1"
},
"activity": "new",
"known": true,
"refusals": [],
"notes": [],
"fit": {
- "status": "fits",
- "coverage": 1.29,
+ "status": "short",
+ "coverage": 0.76,
"effectiveCost": 3,
"expiring": 0,
"spend": {
"5-hour": 45,
"weekly": 6
},
- "account": "acct7"
+ "account": "acct1"
},
"id": "c1",
- "title": "New agent · Claude opus high · m07",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (58% left, resets in 3h); weekly 6% of 90% · m07 · new · quota 5-hour 58% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude opus high · m01",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 45% of the 5-hour window (34% left, resets in 3h); weekly 6% of 90% · m01 · new · quota 5-hour 34% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m09",
- "machineName": "m09",
+ "machineId": "m02",
+ "machineName": "m02",
"engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
+ "model": "sonnet",
+ "effort": "medium",
+ "quality": 2,
+ "cost": 2,
"quota": {
"known": true,
- "leftPercent": 66,
+ "leftPercent": 38,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 66,
+ "leftPercent": 38,
"resetsAt": 1010800000
},
{
@@ -1650,7 +1426,7 @@
"resetsAt": 1432000000
}
],
- "account": "acct9"
+ "account": "acct2"
},
"activity": "new",
"known": true,
@@ -1658,23 +1434,23 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 1.47,
- "effectiveCost": 3,
+ "coverage": 1.27,
+ "effectiveCost": 2,
"expiring": 0,
"spend": {
- "5-hour": 45,
- "weekly": 6
+ "5-hour": 30,
+ "weekly": 4
},
- "account": "acct9"
+ "account": "acct2"
},
"id": "c2",
- "title": "New agent · Claude opus high · m09",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (66% left, resets in 3h); weekly 6% of 90% · m09 · new · quota 5-hour 66% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude sonnet medium · m02",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (38% left, resets in 3h); weekly 4% of 90% · m02 · new · quota 5-hour 38% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m11",
- "machineName": "m11",
+ "machineId": "m03",
+ "machineName": "m03",
"engine": "claude",
"model": "opus",
"effort": "high",
@@ -1682,12 +1458,12 @@
"cost": 3,
"quota": {
"known": true,
- "leftPercent": 74,
+ "leftPercent": 42,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 74,
+ "leftPercent": 42,
"resetsAt": 1010800000
},
{
@@ -1696,44 +1472,44 @@
"resetsAt": 1432000000
}
],
- "account": "acct11"
+ "account": "acct3"
},
"activity": "new",
"known": true,
"refusals": [],
"notes": [],
"fit": {
- "status": "fits",
- "coverage": 1.64,
+ "status": "short",
+ "coverage": 0.93,
"effectiveCost": 3,
"expiring": 0,
"spend": {
"5-hour": 45,
"weekly": 6
},
- "account": "acct11"
+ "account": "acct3"
},
"id": "c3",
- "title": "New agent · Claude opus high · m11",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (74% left, resets in 3h); weekly 6% of 90% · m11 · new · quota 5-hour 74% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude opus high · m03",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 45% of the 5-hour window (42% left, resets in 3h); weekly 6% of 90% · m03 · new · quota 5-hour 42% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m13",
- "machineName": "m13",
+ "machineId": "m04",
+ "machineName": "m04",
"engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
+ "model": "sonnet",
+ "effort": "medium",
+ "quality": 2,
+ "cost": 2,
"quota": {
"known": true,
- "leftPercent": 82,
+ "leftPercent": 46,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 82,
+ "leftPercent": 46,
"resetsAt": 1010800000
},
{
@@ -1742,7 +1518,7 @@
"resetsAt": 1432000000
}
],
- "account": "acct13"
+ "account": "acct4"
},
"activity": "new",
"known": true,
@@ -1750,23 +1526,23 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 1.82,
- "effectiveCost": 3,
+ "coverage": 1.53,
+ "effectiveCost": 2,
"expiring": 0,
"spend": {
- "5-hour": 45,
- "weekly": 6
+ "5-hour": 30,
+ "weekly": 4
},
- "account": "acct13"
+ "account": "acct4"
},
"id": "c4",
- "title": "New agent · Claude opus high · m13",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (82% left, resets in 3h); weekly 6% of 90% · m13 · new · quota 5-hour 82% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude sonnet medium · m04",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (46% left, resets in 3h); weekly 4% of 90% · m04 · new · quota 5-hour 46% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m01",
- "machineName": "m01",
+ "machineId": "m05",
+ "machineName": "m05",
"engine": "claude",
"model": "opus",
"effort": "high",
@@ -1774,12 +1550,12 @@
"cost": 3,
"quota": {
"known": true,
- "leftPercent": 34,
+ "leftPercent": 50,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 34,
+ "leftPercent": 50,
"resetsAt": 1010800000
},
{
@@ -1788,44 +1564,44 @@
"resetsAt": 1432000000
}
],
- "account": "acct1"
+ "account": "acct5"
},
"activity": "new",
"known": true,
"refusals": [],
"notes": [],
"fit": {
- "status": "short",
- "coverage": 0.76,
+ "status": "fits",
+ "coverage": 1.11,
"effectiveCost": 3,
"expiring": 0,
"spend": {
"5-hour": 45,
"weekly": 6
},
- "account": "acct1"
+ "account": "acct5"
},
"id": "c5",
- "title": "New agent · Claude opus high · m01",
- "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 45% of the 5-hour window (34% left, resets in 3h); weekly 6% of 90% · m01 · new · quota 5-hour 34% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude opus high · m05",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (50% left, resets in 3h); weekly 6% of 90% · m05 · new · quota 5-hour 50% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m03",
- "machineName": "m03",
+ "machineId": "m06",
+ "machineName": "m06",
"engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
+ "model": "sonnet",
+ "effort": "medium",
+ "quality": 2,
+ "cost": 2,
"quota": {
"known": true,
- "leftPercent": 42,
+ "leftPercent": 54,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 42,
+ "leftPercent": 54,
"resetsAt": 1010800000
},
{
@@ -1834,44 +1610,44 @@
"resetsAt": 1432000000
}
],
- "account": "acct3"
+ "account": "acct6"
},
"activity": "new",
"known": true,
"refusals": [],
"notes": [],
"fit": {
- "status": "short",
- "coverage": 0.93,
- "effectiveCost": 3,
+ "status": "fits",
+ "coverage": 1.8,
+ "effectiveCost": 2,
"expiring": 0,
"spend": {
- "5-hour": 45,
- "weekly": 6
+ "5-hour": 30,
+ "weekly": 4
},
- "account": "acct3"
+ "account": "acct6"
},
"id": "c6",
- "title": "New agent · Claude opus high · m03",
- "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 45% of the 5-hour window (42% left, resets in 3h); weekly 6% of 90% · m03 · new · quota 5-hour 42% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude sonnet medium · m06",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (54% left, resets in 3h); weekly 4% of 90% · m06 · new · quota 5-hour 54% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m00",
- "machineName": "m00",
+ "machineId": "m07",
+ "machineName": "m07",
"engine": "claude",
- "model": "sonnet",
- "effort": "medium",
- "quality": 2,
- "cost": 2,
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
"quota": {
"known": true,
- "leftPercent": 30,
+ "leftPercent": 58,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 30,
+ "leftPercent": 58,
"resetsAt": 1010800000
},
{
@@ -1880,7 +1656,7 @@
"resetsAt": 1432000000
}
],
- "account": "acct0"
+ "account": "acct7"
},
"activity": "new",
"known": true,
@@ -1888,23 +1664,23 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 1,
- "effectiveCost": 2,
+ "coverage": 1.29,
+ "effectiveCost": 3,
"expiring": 0,
"spend": {
- "5-hour": 30,
- "weekly": 4
+ "5-hour": 45,
+ "weekly": 6
},
- "account": "acct0"
+ "account": "acct7"
},
"id": "c7",
- "title": "New agent · Claude sonnet medium · m00",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (30% left, resets in 3h); weekly 4% of 90% · m00 · new · quota 5-hour 30% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude opus high · m07",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (58% left, resets in 3h); weekly 6% of 90% · m07 · new · quota 5-hour 58% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m02",
- "machineName": "m02",
+ "machineId": "m08",
+ "machineName": "m08",
"engine": "claude",
"model": "sonnet",
"effort": "medium",
@@ -1912,12 +1688,12 @@
"cost": 2,
"quota": {
"known": true,
- "leftPercent": 38,
+ "leftPercent": 62,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 38,
+ "leftPercent": 62,
"resetsAt": 1010800000
},
{
@@ -1926,7 +1702,7 @@
"resetsAt": 1432000000
}
],
- "account": "acct2"
+ "account": "acct8"
},
"activity": "new",
"known": true,
@@ -1934,36 +1710,36 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 1.27,
+ "coverage": 2.07,
"effectiveCost": 2,
"expiring": 0,
"spend": {
"5-hour": 30,
"weekly": 4
},
- "account": "acct2"
+ "account": "acct8"
},
"id": "c8",
- "title": "New agent · Claude sonnet medium · m02",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (38% left, resets in 3h); weekly 4% of 90% · m02 · new · quota 5-hour 38% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude sonnet medium · m08",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (62% left, resets in 3h); weekly 4% of 90% · m08 · new · quota 5-hour 62% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m04",
- "machineName": "m04",
+ "machineId": "m09",
+ "machineName": "m09",
"engine": "claude",
- "model": "sonnet",
- "effort": "medium",
- "quality": 2,
- "cost": 2,
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
"quota": {
"known": true,
- "leftPercent": 46,
+ "leftPercent": 66,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 46,
+ "leftPercent": 66,
"resetsAt": 1010800000
},
{
@@ -1972,7 +1748,7 @@
"resetsAt": 1432000000
}
],
- "account": "acct4"
+ "account": "acct9"
},
"activity": "new",
"known": true,
@@ -1980,23 +1756,23 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 1.53,
- "effectiveCost": 2,
+ "coverage": 1.47,
+ "effectiveCost": 3,
"expiring": 0,
"spend": {
- "5-hour": 30,
- "weekly": 4
+ "5-hour": 45,
+ "weekly": 6
},
- "account": "acct4"
+ "account": "acct9"
},
"id": "c9",
- "title": "New agent · Claude sonnet medium · m04",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (46% left, resets in 3h); weekly 4% of 90% · m04 · new · quota 5-hour 46% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude opus high · m09",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (66% left, resets in 3h); weekly 6% of 90% · m09 · new · quota 5-hour 66% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m06",
- "machineName": "m06",
+ "machineId": "m10",
+ "machineName": "m10",
"engine": "claude",
"model": "sonnet",
"effort": "medium",
@@ -2004,12 +1780,12 @@
"cost": 2,
"quota": {
"known": true,
- "leftPercent": 54,
+ "leftPercent": 70,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 54,
+ "leftPercent": 70,
"resetsAt": 1010800000
},
{
@@ -2018,7 +1794,7 @@
"resetsAt": 1432000000
}
],
- "account": "acct6"
+ "account": "acct10"
},
"activity": "new",
"known": true,
@@ -2026,36 +1802,36 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 1.8,
+ "coverage": 2.33,
"effectiveCost": 2,
"expiring": 0,
"spend": {
"5-hour": 30,
"weekly": 4
},
- "account": "acct6"
+ "account": "acct10"
},
"id": "c10",
- "title": "New agent · Claude sonnet medium · m06",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (54% left, resets in 3h); weekly 4% of 90% · m06 · new · quota 5-hour 54% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude sonnet medium · m10",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (70% left, resets in 3h); weekly 4% of 90% · m10 · new · quota 5-hour 70% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m08",
- "machineName": "m08",
+ "machineId": "m11",
+ "machineName": "m11",
"engine": "claude",
- "model": "sonnet",
- "effort": "medium",
- "quality": 2,
- "cost": 2,
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
"quota": {
"known": true,
- "leftPercent": 62,
+ "leftPercent": 74,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 62,
+ "leftPercent": 74,
"resetsAt": 1010800000
},
{
@@ -2064,7 +1840,7 @@
"resetsAt": 1432000000
}
],
- "account": "acct8"
+ "account": "acct11"
},
"activity": "new",
"known": true,
@@ -2072,23 +1848,23 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 2.07,
- "effectiveCost": 2,
+ "coverage": 1.64,
+ "effectiveCost": 3,
"expiring": 0,
"spend": {
- "5-hour": 30,
- "weekly": 4
+ "5-hour": 45,
+ "weekly": 6
},
- "account": "acct8"
+ "account": "acct11"
},
"id": "c11",
- "title": "New agent · Claude sonnet medium · m08",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (62% left, resets in 3h); weekly 4% of 90% · m08 · new · quota 5-hour 62% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude opus high · m11",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (74% left, resets in 3h); weekly 6% of 90% · m11 · new · quota 5-hour 74% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m10",
- "machineName": "m10",
+ "machineId": "m12",
+ "machineName": "m12",
"engine": "claude",
"model": "sonnet",
"effort": "medium",
@@ -2096,12 +1872,12 @@
"cost": 2,
"quota": {
"known": true,
- "leftPercent": 70,
+ "leftPercent": 78,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 70,
+ "leftPercent": 78,
"resetsAt": 1010800000
},
{
@@ -2110,7 +1886,7 @@
"resetsAt": 1432000000
}
],
- "account": "acct10"
+ "account": "acct12"
},
"activity": "new",
"known": true,
@@ -2118,36 +1894,36 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 2.33,
+ "coverage": 2.6,
"effectiveCost": 2,
"expiring": 0,
"spend": {
"5-hour": 30,
"weekly": 4
},
- "account": "acct10"
+ "account": "acct12"
},
"id": "c12",
- "title": "New agent · Claude sonnet medium · m10",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (70% left, resets in 3h); weekly 4% of 90% · m10 · new · quota 5-hour 70% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude sonnet medium · m12",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (78% left, resets in 3h); weekly 4% of 90% · m12 · new · quota 5-hour 78% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
- "machineId": "m12",
- "machineName": "m12",
+ "machineId": "m13",
+ "machineName": "m13",
"engine": "claude",
- "model": "sonnet",
- "effort": "medium",
- "quality": 2,
- "cost": 2,
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
"quota": {
"known": true,
- "leftPercent": 78,
+ "leftPercent": 82,
"resetsAt": null,
"windows": [
{
"name": "5-hour",
- "leftPercent": 78,
+ "leftPercent": 82,
"resetsAt": 1010800000
},
{
@@ -2156,7 +1932,7 @@
"resetsAt": 1432000000
}
],
- "account": "acct12"
+ "account": "acct13"
},
"activity": "new",
"known": true,
@@ -2164,18 +1940,18 @@
"notes": [],
"fit": {
"status": "fits",
- "coverage": 2.6,
- "effectiveCost": 2,
+ "coverage": 1.82,
+ "effectiveCost": 3,
"expiring": 0,
"spend": {
- "5-hour": 30,
- "weekly": 4
+ "5-hour": 45,
+ "weekly": 6
},
- "account": "acct12"
+ "account": "acct13"
},
"id": "c13",
- "title": "New agent · Claude sonnet medium · m12",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (78% left, resets in 3h); weekly 4% of 90% · m12 · new · quota 5-hour 78% left (resets in 3h), weekly 90% left (resets in 5 days)"
+ "title": "New agent · Claude opus high · m13",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (82% left, resets in 3h); weekly 6% of 90% · m13 · new · quota 5-hour 82% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
{
"kind": "new",
@@ -2229,204 +2005,89 @@
"belowFloor": false
},
"verdict": {
- "pick": {
- "kind": "new",
- "machineId": "m05",
- "machineName": "m05",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "quota": {
- "known": true,
- "leftPercent": 50,
- "resetsAt": null,
- "windows": [
- {
- "name": "5-hour",
- "leftPercent": 50,
- "resetsAt": 1010800000
- },
- {
- "name": "weekly",
- "leftPercent": 90,
- "resetsAt": 1432000000
- }
- ],
- "account": "acct5"
- },
- "activity": "new",
- "known": true,
- "refusals": [],
- "notes": [],
- "fit": {
- "status": "fits",
- "coverage": 1.11,
- "effectiveCost": 3,
- "expiring": 0,
- "spend": {
- "5-hour": 45,
- "weekly": 6
- },
- "account": "acct5"
- },
- "id": "c0",
- "title": "New agent · Claude opus high · m05",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (50% left, resets in 3h); weekly 6% of 90% · m05 · new · quota 5-hour 50% left (resets in 3h), weekly 90% left (resets in 5 days)"
- },
- "via": "order",
+ "via": "instructions",
"p": null,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
},
"record": {
"assessment": {
"difficulty": "medium",
"risk": "low",
- "why": "API change.",
- "size": "medium"
- },
- "candidates": [
- {
- "id": "c0",
- "kind": "new",
- "machineId": "m05",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "title": "New agent · Claude opus high · m05",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (50% left, resets in 3h); weekly 6% of 90% · m05 · new · quota 5-hour 50% left (resets in 3h), weekly 90% left (resets in 5 days)",
- "fit": {
- "status": "fits",
- "coverage": 1.11,
- "effectiveCost": 3,
- "expiring": 0,
- "spend": {
- "5-hour": 45,
- "weekly": 6
- },
- "account": "acct5"
- }
- },
- {
- "id": "c1",
- "kind": "new",
- "machineId": "m07",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "title": "New agent · Claude opus high · m07",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (58% left, resets in 3h); weekly 6% of 90% · m07 · new · quota 5-hour 58% left (resets in 3h), weekly 90% left (resets in 5 days)",
- "fit": {
- "status": "fits",
- "coverage": 1.29,
- "effectiveCost": 3,
- "expiring": 0,
- "spend": {
- "5-hour": 45,
- "weekly": 6
- },
- "account": "acct7"
- }
- },
- {
- "id": "c2",
- "kind": "new",
- "machineId": "m09",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "title": "New agent · Claude opus high · m09",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (66% left, resets in 3h); weekly 6% of 90% · m09 · new · quota 5-hour 66% left (resets in 3h), weekly 90% left (resets in 5 days)",
- "fit": {
- "status": "fits",
- "coverage": 1.47,
- "effectiveCost": 3,
- "expiring": 0,
- "spend": {
- "5-hour": 45,
- "weekly": 6
- },
- "account": "acct9"
- }
- },
+ "why": "API change.",
+ "size": "medium"
+ },
+ "candidates": [
{
- "id": "c3",
+ "id": "c0",
"kind": "new",
- "machineId": "m11",
+ "machineId": "m00",
"engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "title": "New agent · Claude opus high · m11",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (74% left, resets in 3h); weekly 6% of 90% · m11 · new · quota 5-hour 74% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "model": "sonnet",
+ "effort": "medium",
+ "quality": 2,
+ "cost": 2,
+ "title": "New agent · Claude sonnet medium · m00",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (30% left, resets in 3h); weekly 4% of 90% · m00 · new · quota 5-hour 30% left (resets in 3h), weekly 90% left (resets in 5 days)",
"fit": {
"status": "fits",
- "coverage": 1.64,
- "effectiveCost": 3,
+ "coverage": 1,
+ "effectiveCost": 2,
"expiring": 0,
"spend": {
- "5-hour": 45,
- "weekly": 6
+ "5-hour": 30,
+ "weekly": 4
},
- "account": "acct11"
+ "account": "acct0"
}
},
{
- "id": "c4",
+ "id": "c1",
"kind": "new",
- "machineId": "m13",
+ "machineId": "m01",
"engine": "claude",
"model": "opus",
"effort": "high",
"quality": 3,
"cost": 3,
- "title": "New agent · Claude opus high · m13",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (82% left, resets in 3h); weekly 6% of 90% · m13 · new · quota 5-hour 82% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "title": "New agent · Claude opus high · m01",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 45% of the 5-hour window (34% left, resets in 3h); weekly 6% of 90% · m01 · new · quota 5-hour 34% left (resets in 3h), weekly 90% left (resets in 5 days)",
"fit": {
- "status": "fits",
- "coverage": 1.82,
+ "status": "short",
+ "coverage": 0.76,
"effectiveCost": 3,
"expiring": 0,
"spend": {
"5-hour": 45,
"weekly": 6
},
- "account": "acct13"
+ "account": "acct1"
}
},
{
- "id": "c5",
+ "id": "c2",
"kind": "new",
- "machineId": "m01",
+ "machineId": "m02",
"engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "title": "New agent · Claude opus high · m01",
- "label": "New agent · Claude opus high · strength 3, cost 3 · short: needs about 45% of the 5-hour window (34% left, resets in 3h); weekly 6% of 90% · m01 · new · quota 5-hour 34% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "model": "sonnet",
+ "effort": "medium",
+ "quality": 2,
+ "cost": 2,
+ "title": "New agent · Claude sonnet medium · m02",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (38% left, resets in 3h); weekly 4% of 90% · m02 · new · quota 5-hour 38% left (resets in 3h), weekly 90% left (resets in 5 days)",
"fit": {
- "status": "short",
- "coverage": 0.76,
- "effectiveCost": 3,
+ "status": "fits",
+ "coverage": 1.27,
+ "effectiveCost": 2,
"expiring": 0,
"spend": {
- "5-hour": 45,
- "weekly": 6
+ "5-hour": 30,
+ "weekly": 4
},
- "account": "acct1"
+ "account": "acct2"
}
},
{
- "id": "c6",
+ "id": "c3",
"kind": "new",
"machineId": "m03",
"engine": "claude",
@@ -2449,99 +2110,99 @@
}
},
{
- "id": "c7",
+ "id": "c4",
"kind": "new",
- "machineId": "m00",
+ "machineId": "m04",
"engine": "claude",
"model": "sonnet",
"effort": "medium",
"quality": 2,
"cost": 2,
- "title": "New agent · Claude sonnet medium · m00",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (30% left, resets in 3h); weekly 4% of 90% · m00 · new · quota 5-hour 30% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "title": "New agent · Claude sonnet medium · m04",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (46% left, resets in 3h); weekly 4% of 90% · m04 · new · quota 5-hour 46% left (resets in 3h), weekly 90% left (resets in 5 days)",
"fit": {
"status": "fits",
- "coverage": 1,
+ "coverage": 1.53,
"effectiveCost": 2,
"expiring": 0,
"spend": {
"5-hour": 30,
"weekly": 4
},
- "account": "acct0"
+ "account": "acct4"
}
},
{
- "id": "c8",
+ "id": "c5",
"kind": "new",
- "machineId": "m02",
+ "machineId": "m05",
"engine": "claude",
- "model": "sonnet",
- "effort": "medium",
- "quality": 2,
- "cost": 2,
- "title": "New agent · Claude sonnet medium · m02",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (38% left, resets in 3h); weekly 4% of 90% · m02 · new · quota 5-hour 38% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
+ "title": "New agent · Claude opus high · m05",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (50% left, resets in 3h); weekly 6% of 90% · m05 · new · quota 5-hour 50% left (resets in 3h), weekly 90% left (resets in 5 days)",
"fit": {
"status": "fits",
- "coverage": 1.27,
- "effectiveCost": 2,
+ "coverage": 1.11,
+ "effectiveCost": 3,
"expiring": 0,
"spend": {
- "5-hour": 30,
- "weekly": 4
+ "5-hour": 45,
+ "weekly": 6
},
- "account": "acct2"
+ "account": "acct5"
}
},
{
- "id": "c9",
+ "id": "c6",
"kind": "new",
- "machineId": "m04",
+ "machineId": "m06",
"engine": "claude",
"model": "sonnet",
"effort": "medium",
"quality": 2,
"cost": 2,
- "title": "New agent · Claude sonnet medium · m04",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (46% left, resets in 3h); weekly 4% of 90% · m04 · new · quota 5-hour 46% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "title": "New agent · Claude sonnet medium · m06",
+ "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (54% left, resets in 3h); weekly 4% of 90% · m06 · new · quota 5-hour 54% left (resets in 3h), weekly 90% left (resets in 5 days)",
"fit": {
"status": "fits",
- "coverage": 1.53,
+ "coverage": 1.8,
"effectiveCost": 2,
"expiring": 0,
"spend": {
"5-hour": 30,
"weekly": 4
},
- "account": "acct4"
+ "account": "acct6"
}
},
{
- "id": "c10",
+ "id": "c7",
"kind": "new",
- "machineId": "m06",
+ "machineId": "m07",
"engine": "claude",
- "model": "sonnet",
- "effort": "medium",
- "quality": 2,
- "cost": 2,
- "title": "New agent · Claude sonnet medium · m06",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (54% left, resets in 3h); weekly 4% of 90% · m06 · new · quota 5-hour 54% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
+ "title": "New agent · Claude opus high · m07",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (58% left, resets in 3h); weekly 6% of 90% · m07 · new · quota 5-hour 58% left (resets in 3h), weekly 90% left (resets in 5 days)",
"fit": {
"status": "fits",
- "coverage": 1.8,
- "effectiveCost": 2,
+ "coverage": 1.29,
+ "effectiveCost": 3,
"expiring": 0,
"spend": {
- "5-hour": 30,
- "weekly": 4
+ "5-hour": 45,
+ "weekly": 6
},
- "account": "acct6"
+ "account": "acct7"
}
},
{
- "id": "c11",
+ "id": "c8",
"kind": "new",
"machineId": "m08",
"engine": "claude",
@@ -2564,7 +2225,30 @@
}
},
{
- "id": "c12",
+ "id": "c9",
+ "kind": "new",
+ "machineId": "m09",
+ "engine": "claude",
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
+ "title": "New agent · Claude opus high · m09",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (66% left, resets in 3h); weekly 6% of 90% · m09 · new · quota 5-hour 66% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "fit": {
+ "status": "fits",
+ "coverage": 1.47,
+ "effectiveCost": 3,
+ "expiring": 0,
+ "spend": {
+ "5-hour": 45,
+ "weekly": 6
+ },
+ "account": "acct9"
+ }
+ },
+ {
+ "id": "c10",
"kind": "new",
"machineId": "m10",
"engine": "claude",
@@ -2587,7 +2271,30 @@
}
},
{
- "id": "c13",
+ "id": "c11",
+ "kind": "new",
+ "machineId": "m11",
+ "engine": "claude",
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
+ "title": "New agent · Claude opus high · m11",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (74% left, resets in 3h); weekly 6% of 90% · m11 · new · quota 5-hour 74% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "fit": {
+ "status": "fits",
+ "coverage": 1.64,
+ "effectiveCost": 3,
+ "expiring": 0,
+ "spend": {
+ "5-hour": 45,
+ "weekly": 6
+ },
+ "account": "acct11"
+ }
+ },
+ {
+ "id": "c12",
"kind": "new",
"machineId": "m12",
"engine": "claude",
@@ -2609,6 +2316,29 @@
"account": "acct12"
}
},
+ {
+ "id": "c13",
+ "kind": "new",
+ "machineId": "m13",
+ "engine": "claude",
+ "model": "opus",
+ "effort": "high",
+ "quality": 3,
+ "cost": 3,
+ "title": "New agent · Claude opus high · m13",
+ "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (82% left, resets in 3h); weekly 6% of 90% · m13 · new · quota 5-hour 82% left (resets in 3h), weekly 90% left (resets in 5 days)",
+ "fit": {
+ "status": "fits",
+ "coverage": 1.82,
+ "effectiveCost": 3,
+ "expiring": 0,
+ "spend": {
+ "5-hour": 45,
+ "weekly": 6
+ },
+ "account": "acct13"
+ }
+ },
{
"id": "c14",
"kind": "new",
@@ -2636,11 +2366,10 @@
"excluded": [],
"floor": 1,
"notes": false,
- "pick": "c0",
- "via": "order",
+ "via": "instructions",
"p": null,
"belowFloor": false,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
}
},
{
@@ -2763,55 +2492,9 @@
"belowFloor": false
},
"verdict": {
- "pick": {
- "kind": "new",
- "machineId": "a",
- "machineName": "a",
- "engine": "claude",
- "model": "sonnet",
- "effort": "medium",
- "quality": 2,
- "cost": 2,
- "quota": {
- "known": true,
- "leftPercent": 80,
- "resetsAt": null,
- "windows": [
- {
- "name": "5-hour",
- "leftPercent": 80,
- "resetsAt": 1010800000
- },
- {
- "name": "weekly",
- "leftPercent": 90,
- "resetsAt": 1432000000
- }
- ],
- "account": "a"
- },
- "activity": "new",
- "known": true,
- "refusals": [],
- "notes": [],
- "fit": {
- "status": "fits",
- "coverage": 2.67,
- "effectiveCost": 2,
- "expiring": 0,
- "spend": {
- "5-hour": 30,
- "weekly": 4
- },
- "account": "a"
- },
- "id": "c0",
- "title": "New agent · Claude sonnet medium · a",
- "label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (80% left, resets in 3h); weekly 4% of 90% · a · new · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
- },
- "via": "order",
+ "via": "instructions",
"p": null,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
},
"record": {
"assessment": {
@@ -2880,11 +2563,10 @@
],
"floor": 1,
"notes": false,
- "pick": "c0",
- "via": "order",
+ "via": "instructions",
"p": null,
"belowFloor": false,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
}
},
{
@@ -2970,46 +2652,9 @@
"belowFloor": false
},
"verdict": {
- "pick": {
- "kind": "new",
- "machineId": "b",
- "machineName": "b",
- "engine": "claude",
- "model": "default",
- "effort": "default",
- "quality": 1,
- "cost": 1,
- "quota": {
- "known": false,
- "leftPercent": null,
- "resetsAt": null
- },
- "activity": "new",
- "known": true,
- "refusals": [],
- "notes": [],
- "gridModel": "kimi-k3",
- "gridName": "swarm-0123456789ab",
- "gridLabel": "Kimi K3",
- "gridKind": "api",
- "fit": {
- "status": "fits",
- "coverage": null,
- "effectiveCost": 1,
- "expiring": 0,
- "spend": {
- "5-hour": 0,
- "weekly": 0
- },
- "account": "local:swarm-0123456789ab:kimi-k3"
- },
- "id": "c0",
- "title": "New agent · Claude on Kimi K3 (API) · b",
- "label": "New agent · Claude on Kimi K3 (API) · strength 1, cost 1 · fits: a local model on the Swarm's grid uses no subscription · b · new · quota unknown"
- },
- "via": "order",
+ "via": "instructions",
"p": null,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
},
"record": {
"assessment": {
@@ -3075,11 +2720,10 @@
"excluded": [],
"floor": 1,
"notes": false,
- "pick": "c0",
- "via": "order",
+ "via": "instructions",
"p": null,
"belowFloor": false,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
}
},
{
@@ -3190,58 +2834,9 @@
"belowFloor": false
},
"verdict": {
- "pick": {
- "kind": "new",
- "machineId": "a",
- "machineName": "a",
- "engine": "claude",
- "model": "claude-opus-6",
- "effort": "default",
- "quality": 1,
- "cost": 1,
- "quota": {
- "known": true,
- "leftPercent": 80,
- "resetsAt": null,
- "windows": [
- {
- "name": "5-hour",
- "leftPercent": 80,
- "resetsAt": 1010800000
- },
- {
- "name": "weekly",
- "leftPercent": 90,
- "resetsAt": 1432000000
- }
- ],
- "account": "a"
- },
- "activity": "new",
- "known": true,
- "refusals": [],
- "notes": [
- "The catalog does not rate this model."
- ],
- "unrated": true,
- "fit": {
- "status": "fits",
- "coverage": 5.33,
- "effectiveCost": 1,
- "expiring": 0,
- "spend": {
- "5-hour": 15,
- "weekly": 2
- },
- "account": "a"
- },
- "id": "c0",
- "title": "New agent · Claude claude-opus-6 default · a",
- "label": "New agent · Claude claude-opus-6 default · unrated, cost 1 · fits: needs about 15% of the 5-hour window (80% left, resets in 3h); weekly 2% of 90% · The catalog does not rate this model. · a · new · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
- },
- "via": "order",
+ "via": "instructions",
"p": null,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
},
"record": {
"assessment": {
@@ -3302,11 +2897,10 @@
"excluded": [],
"floor": 1,
"notes": false,
- "pick": "c0",
- "via": "order",
+ "via": "instructions",
"p": null,
"belowFloor": false,
- "why": "First by strength, then price and quota fit."
+ "why": "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."
}
},
{
@@ -3419,64 +3013,6 @@
"belowFloor": false
},
"verdict": {
- "pick": {
- "kind": "member",
- "machineId": "a",
- "machineName": "a",
- "engine": "claude",
- "model": "gpt-x",
- "effort": "medium",
- "quality": 1,
- "cost": 1,
- "quota": {
- "known": true,
- "leftPercent": 80,
- "resetsAt": null,
- "windows": [
- {
- "name": "5-hour",
- "leftPercent": 80,
- "resetsAt": 1010800000
- },
- {
- "name": "weekly",
- "leftPercent": 90,
- "resetsAt": 1432000000
- }
- ],
- "account": "a"
- },
- "activity": "working",
- "known": true,
- "refusals": [],
- "notes": [],
- "agentId": "m3",
- "unrated": true,
- "terminalUnverified": true,
- "frame": {
- "title": null,
- "project": null,
- "cwd": "/r",
- "root": "/r",
- "remote": "github.com/o/r",
- "branch": null,
- "updatedAt": null
- },
- "fit": {
- "status": "fits",
- "coverage": 16,
- "effectiveCost": 1,
- "expiring": 0,
- "spend": {
- "5-hour": 5,
- "weekly": 0.5
- },
- "account": "a"
- },
- "id": "c0",
- "title": "Member · Claude gpt-x medium · a",
- "label": "Member · Claude gpt-x medium · unrated, cost 1 · fits: needs about 5% of the 5-hour window (80% left, resets in 3h); weekly 1% of 90% · a · working · last active unknown · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
- },
"via": "only",
"p": null,
"why": "Only candidate that can run this task."
@@ -3517,7 +3053,6 @@
"excluded": [],
"floor": 1,
"notes": false,
- "pick": "c0",
"via": "only",
"p": null,
"belowFloor": false,
diff --git a/cli/src/superTabs/machineFit.spec.ts b/cli/src/superTabs/machineFit.spec.ts
index 61f03a017..7846a1c63 100644
--- a/cli/src/superTabs/machineFit.spec.ts
+++ b/cli/src/superTabs/machineFit.spec.ts
@@ -47,7 +47,7 @@ describe('the task says its heavy work and its CI', () => {
expect(heavyNeed({ heavy: ['e2e'] })).toEqual({ memoryBytes: 6 * GB, diskBytes: 10 * GB, words: 'end-to-end tests' })
expect(heavyNeed({ heavy: ['e2e', 'build'] })).toEqual({ memoryBytes: 8 * GB, diskBytes: 30 * GB, words: 'end-to-end tests and a heavy build' })
})
- it('a heavy task\'s start asks its machine for half the need, so a machine ranked later still admits it; any other start asks what it always did', () => {
+ it('a heavy task\'s start asks its machine for half the need, so a machine noted short still admits it; any other start asks what it always did', () => {
expect(startRequirements({ tools: [], devices: [] })).toEqual(START_REQUIREMENTS)
expect(startRequirements({ tools: [], devices: [], heavy: ['build'] })).toMatchObject({ memoryBytes: 4 * GB, diskBytes: 15 * GB })
// End-to-end's half of the disk is less than any start asks, so the start's own stays.
@@ -57,28 +57,35 @@ describe('the task says its heavy work and its CI', () => {
})
describe('machine fit', () => {
- it('a heavy build avoids a low-memory machine: the one that has what it needs ranks first, and the other says why', () => {
+ it('a heavy build on a low-memory machine: that machine says it is short, and the one that has what it needs says nothing', () => {
const choice = ok(route([on('small', { memory: 5, disk: 100 }), on('big', { memory: 16, disk: 100 })], a({ heavy: ['build'] })))
expect(choice.shown.map(s => s.machineId)).toEqual(['big', 'small'])
expect(choice.shown[1]!.notes).toEqual(['Machine fit: Short of free memory for a heavy build: it needs 8 GB memory and 30 GB disk free, '
- + 'so equally strong candidates that have it rank first.'])
+ + 'so prefer an equally strong candidate that has it.'])
expect(choice.shown[0]!.notes).toEqual([])
- // Without heavy work the same machines rank as they always did, by title.
- expect(ok(route([on('small', { memory: 5, disk: 100 }), on('big', { memory: 16, disk: 100 })], a())).shown.map(s => s.machineId)).toEqual(['big', 'small'])
- expect(ok(route([on('a-small', { memory: 5, disk: 100 }), on('big', { memory: 16, disk: 100 })], a())).shown.map(s => s.machineId)).toEqual(['a-small', 'big'])
- expect(ok(route([on('a-small', { memory: 5, disk: 100 }), on('big', { memory: 16, disk: 100 })], a({ heavy: ['build'] }))).shown.map(s => s.machineId)).toEqual(['big', 'a-small'])
+ expect(choice.adjusted).toBe(true)
+ // Since task #2901 a plug-in's finding is a note, never the order.
+ const named = ok(route([on('a-small', { memory: 5, disk: 100 }), on('big', { memory: 16, disk: 100 })], a({ heavy: ['build'] })))
+ expect(named.shown.map(s => s.machineId)).toEqual(['a-small', 'big'])
+ expect(named.shown[0]!.notes[0]).toMatch(/^Machine fit: Short of free memory for a heavy build:/)
+ // Without heavy work the same machines say nothing.
+ expect(ok(route([on('a-small', { memory: 5, disk: 100 }), on('big', { memory: 16, disk: 100 })], a())).shown.map(s => s.notes)).toEqual([[], []])
})
it('short of disk counts like short of memory', () => {
const choice = ok(route([on('a-full', { memory: 16, disk: 20 }), on('b', { memory: 16, disk: 100 })], a({ heavy: ['build'] })))
- expect(choice.shown.map(s => s.machineId)).toEqual(['b', 'a-full'])
- expect(choice.shown[1]!.notes[0]).toMatch(/^Machine fit: Short of free disk for a heavy build:/)
+ expect(choice.shown.map(s => s.machineId)).toEqual(['a-full', 'b'])
+ expect(choice.shown[0]!.notes[0]).toMatch(/^Machine fit: Short of free disk for a heavy build:/)
+ expect(choice.shown[1]!.notes).toEqual([])
})
- it('never passes over a stronger model for a machine: a short machine still ranks above a weaker model that fits', () => {
+ it('a short machine\'s stronger model is noted short, never left out, and a weaker model that fits says nothing', () => {
const choice = ok(route([on('short', { memory: 5, disk: 100 }), on('big', { memory: 16, disk: 100 }, { model: 'sonnet', effort: 'medium', quality: 2, cost: 2 })],
a({ heavy: ['build'] })))
- expect(choice.shown.map(s => `${s.machineId} ${s.model}`)).toEqual(['short opus', 'big sonnet'])
+ // Since task #2901 a plug-in's finding is a note, never the order.
+ expect(choice.shown.map(s => `${s.machineId} ${s.model}`)).toEqual(['big sonnet', 'short opus'])
+ expect(choice.shown[1]!.notes[0]).toMatch(/^Machine fit: Short of free memory for a heavy build:.*prefer an equally strong candidate that has it\.$/)
+ expect(choice.shown[0]!.notes).toEqual([])
// What the candidate is shown and recorded as stays as measured.
- expect(choice.shown[0]!.quality).toBe(3)
+ expect(choice.shown[1]!.quality).toBe(3)
})
it('below half the need the machine cannot run the work: left out with why, and none left is no candidate', () => {
const choice = ok(route([on('tiny', { memory: 3, disk: 100 }), on('big', { memory: 16, disk: 100 })], a({ heavy: ['build'] })))
@@ -89,10 +96,11 @@ describe('machine fit', () => {
// Exactly half is enough to run.
expect(ok(route([on('half', { memory: 4, disk: 15 })], a({ heavy: ['build'] }))).shown).toHaveLength(1)
})
- it('says an unknown reading and ranks it after a machine known to fit, never leaving it out', () => {
+ it('says an unknown reading, and a machine known to fit says nothing, never leaving it out', () => {
const choice = ok(route([on('a-unread', { memory: null, disk: 100 }), on('b', { memory: 16, disk: 100 })], a({ heavy: ['e2e'] })))
- expect(choice.shown.map(s => s.machineId)).toEqual(['b', 'a-unread'])
- expect(choice.shown[1]!.notes).toEqual(['Machine fit: Free memory unknown here; end-to-end tests: it needs 6 GB memory and 10 GB disk free.'])
+ expect(choice.shown.map(s => s.machineId)).toEqual(['a-unread', 'b'])
+ expect(choice.shown[1]!.notes).toEqual([])
+ expect(choice.shown[0]!.notes).toEqual(['Machine fit: Free memory unknown here; end-to-end tests: it needs 6 GB memory and 10 GB disk free.'])
const both = ok(route([on('blind', { memory: null, disk: null })], a({ heavy: ['e2e'] })))
expect(both.shown[0]!.notes).toEqual(['Machine fit: Free memory and disk unknown here; end-to-end tests: it needs 6 GB memory and 10 GB disk free.'])
expect(ok(route([on('d', { memory: 16, disk: null })], a({ heavy: ['e2e'] }))).shown[0]!.notes)
@@ -102,11 +110,12 @@ describe('machine fit', () => {
// A probe with no machine reading at all is unknown too.
expect(ok(route([on('none', { memory: 16, disk: 100 }, { load: undefined })], a({ heavy: ['build'] }))).shown[0]!.notes[0]).toContain('Free memory and disk unknown here')
})
- it('a busy CPU ranks a machine later among equals, never leaving it out, and is said', () => {
+ it('a busy CPU is said on its machine, never leaving it out', () => {
const choice = ok(route([on('a-busy', { memory: 16, disk: 100, cpu: 92.4 }), on('b', { memory: 16, disk: 100, cpu: 30 })], a({ heavy: ['build'] })))
- expect(choice.shown.map(s => s.machineId)).toEqual(['b', 'a-busy'])
- expect(choice.shown[1]!.notes).toEqual(['Machine fit: Its CPU is busy; it has what a heavy build needs.'])
- expect(ok(route([on('s', { memory: 5, disk: 100, cpu: 99 })], a({ heavy: ['build'] }))).shown[0]!.notes[0]).toMatch(/rank first\. Its CPU is busy\.$/)
+ expect(choice.shown.map(s => s.machineId)).toEqual(['a-busy', 'b'])
+ expect(choice.shown[0]!.notes).toEqual(['Machine fit: Its CPU is busy; it has what a heavy build needs.'])
+ expect(choice.shown[1]!.notes).toEqual([])
+ expect(ok(route([on('s', { memory: 5, disk: 100, cpu: 99 })], a({ heavy: ['build'] }))).shown[0]!.notes[0]).toMatch(/has it\. Its CPU is busy\.$/)
expect(ok(route([on('u', { memory: null, disk: 100, cpu: 99 })], a({ heavy: ['build'] }))).shown[0]!.notes[0]).toMatch(/free\. Its CPU is busy\.$/)
})
it('a member is judged by its machine\'s reading too', () => {
@@ -156,11 +165,12 @@ describe('heavy work placed but not yet in the reading', () => {
it('a machine that fits by its reading is short, or left out, once the heavy work just started there is counted, and says so', () => {
const plugin = (starts: Array<Record<string, unknown>>) => machineFit({ placed: placedHeavyWork(starts, NOW) })
const probes = [on('studio', { memory: 14, disk: 100 }), on('z-other', { memory: 16, disk: 100 })]
- expect(ok(route(probes, a({ heavy: ['build'] }), plugin([]))).shown.map(s => s.machineId)).toEqual(['studio', 'z-other'])
+ expect(ok(route(probes, a({ heavy: ['build'] }), plugin([]))).shown.map(s => s.notes)).toEqual([[], []])
const one = ok(route(probes, a({ heavy: ['build'] }), plugin([heavyStart('studio', NOW - 5 * M), heavyStart('studio', NOW - 4 * 60 * M)])))
- expect(one.shown.map(s => s.machineId)).toEqual(['z-other', 'studio'])
- expect(one.shown[1]!.notes[0]).toBe('Machine fit: Short of free memory for a heavy build, counting heavy work started there in the last 15 minutes: '
- + 'it needs 8 GB memory and 30 GB disk free, so equally strong candidates that have it rank first.')
+ expect(one.shown.map(s => s.machineId)).toEqual(['studio', 'z-other'])
+ expect(one.shown[0]!.notes[0]).toBe('Machine fit: Short of free memory for a heavy build, counting heavy work started there in the last 15 minutes: '
+ + 'it needs 8 GB memory and 30 GB disk free, so prefer an equally strong candidate that has it.')
+ expect(one.shown[1]!.notes).toEqual([])
const three = ok(route(probes, a({ heavy: ['build'] }), plugin([1, 2, 3].map(i => heavyStart('studio', NOW - i * M)))))
expect(three.shown.map(s => s.machineId)).toEqual(['z-other'])
expect(three.excluded[0]!.reason).toBe('Machine fit: Too little free memory and disk for a heavy build, counting heavy work started there in the last 15 minutes: '
@@ -202,7 +212,7 @@ describe('the CI jobs limit', () => {
// Unread load: the unchecked note and the over-limit note both show.
expect(ok(route([on('a', { memory: 16, disk: 100 })], a({ ci: { jobs: 21, macos: 0 } }))).shown[0]!.notes).toEqual([`Machine fit: ${CI_UNCHECKED} ${CI_OVER_NOTE({ ci: { jobs: 21, macos: 0 } })}`])
// Beside a heavy fit.
- expect(ok(route([on('a', { memory: 5, disk: 100 })], a({ ci: { jobs: 21, macos: 0 }, heavy: ['build'] }), machineFit({ ci: load(0) }))).shown[0]!.notes[0]).toMatch(/rank first\. This task starts 21 CI jobs/)
+ expect(ok(route([on('a', { memory: 5, disk: 100 })], a({ ci: { jobs: 21, macos: 0 }, heavy: ['build'] }), machineFit({ ci: load(0) }))).shown[0]!.notes[0]).toMatch(/has it\. This task starts 21 CI jobs/)
// Held by the load, the hold's reason is the answer, and it too names the cap.
const held = route([on('a', { memory: 16, disk: 100 })], a({ ci: { jobs: 21, macos: 0 } }), machineFit({ ci: load(3) }))
expect(held).toMatchObject({ error: 'NO_CANDIDATE' })
@@ -224,7 +234,7 @@ describe('the CI jobs limit', () => {
})
it('a task that starts CI is told when the limit could not be checked, beside its fit', () => {
expect(ok(route([on('a', { memory: 16, disk: 100 })], a({ ci: { jobs: 1, macos: 0 } }))).shown[0]!.notes).toEqual([`Machine fit: ${CI_UNCHECKED}`])
- expect(ok(route([on('a', { memory: 5, disk: 100 })], a({ ci: { jobs: 1, macos: 0 }, heavy: ['build'] }))).shown[0]!.notes[0]).toMatch(/rank first\. This repository's running CI jobs could not be read/)
+ expect(ok(route([on('a', { memory: 5, disk: 100 })], a({ ci: { jobs: 1, macos: 0 }, heavy: ['build'] }))).shown[0]!.notes[0]).toMatch(/has it\. This repository's running CI jobs could not be read/)
})
})
@@ -241,8 +251,9 @@ describe('its maker', () => {
starts: [{ request: { machineId: 'team', requirements: startRequirements({ tools: [], devices: [], heavy: ['build'] }), heavy: ['build'] }, requestedAt: now - M }] }
const plugin = (await MACHINE_FIT_MAKER.make(input(a({ heavy: ['build'] }), state)))!
const choice = ok(choose([on('mac', { memory: 12, disk: 100 }), on('z', { memory: 12, disk: 100 })], catalog, a({ heavy: ['build'] }), now, [], [], [], [plugin]))
- expect(choice.shown.map(s => s.machineId)).toEqual(['z', 'mac'])
- expect(choice.shown[1]!.notes[0]).toContain('counting heavy work started there in the last 15 minutes')
+ expect(choice.shown.map(s => s.machineId)).toEqual(['mac', 'z'])
+ expect(choice.shown[0]!.notes[0]).toContain('counting heavy work started there in the last 15 minutes')
+ expect(choice.shown[1]!.notes).toEqual([])
// A tab read with no machines or starts reads as nothing placed.
const bare = (await MACHINE_FIT_MAKER.make(input(a({ heavy: ['build'] }), {})))!
expect(ok(choose([on('mac', { memory: 12, disk: 100 })], catalog, a({ heavy: ['build'] }), now, [], [], [], [bare])).shown).toHaveLength(1)
diff --git a/cli/src/superTabs/machineFit.ts b/cli/src/superTabs/machineFit.ts
index bd3071940..68bc64c11 100644
--- a/cli/src/superTabs/machineFit.ts
+++ b/cli/src/superTabs/machineFit.ts
@@ -2,8 +2,8 @@
* its machine (`needs.heavy`), or starts heavy CI workflows itself (`needs.ci`: OS images, end-to-end, macOS jobs). The
* route's plug-in (route.ts RoutePlugin) then
* - leaves out a machine with less than half of what the work needs free, which cannot run it;
- * - ranks one with less than the need after every equally strong candidate that has it, never above a weaker model;
- * - says when a reading is unknown, and ranks a busy CPU later among equals;
+ * - notes one with less than the need, so an equally strong candidate that has it is preferred, never a weaker model;
+ * - says when a reading is unknown, and when a machine's CPU is busy;
* - counts heavy work started there in the last minutes, which its reading may not show yet (pieces 3 to 6 all started on
* one Mac within ten minutes, and every route saw the same free memory, 2026-10-31);
* - holds work that would start CI past the account's running-jobs limit, with a time to route it again.
@@ -21,10 +21,11 @@ export const HEAVY_NEEDS: Record<HeavyWork, { memoryBytes: number; diskBytes: nu
}
/** Below this share of the need the machine cannot run the work: it is left out. */
export const FLOOR_SHARE = 0.5
-/** How far a short or unread machine ranks down, in catalog strength: less than one step, so a stronger model is never
- * passed over for a machine, while an equally strong one that fits always ranks first. */
+/** Which way a short or unread machine's finding leans, in catalog strength: less than one step, since a stronger model is
+ * never passed over for a machine, only an equally strong one that fits preferred. Since task #2901 it moves nothing: the
+ * note says it (route.ts Adjustment). */
export const SHORT_STRENGTH = -0.5, UNKNOWN_STRENGTH = -0.25
-/** A CPU this busy ranks a machine later among equals; one reading is only a moment, so it never leaves one out. */
+/** A CPU this busy is noted, for choosing between equals; one reading is only a moment, so it never leaves a machine out. */
export const BUSY_CPU_PERCENT = 85, BUSY_CPU_COST = 1
/** A heavy start this recent may not show in its machine's reading yet. */
export const PLACED_RECENT_MS = 15 * 60_000
@@ -138,7 +139,7 @@ function fitOf(candidate: Pick<Probe, 'load'>, needs: Needs, held: Placed | unde
const out = which(memory !== null && memory < floor.memoryBytes, disk !== null && disk < floor.diskBytes)
if (out) return { refuse: true, reason: `Too little free ${out} for ${need.words}${counting}: ${wants}, and at least half to run at all.` }
const short = which(memory !== null && memory < need.memoryBytes, disk !== null && disk < need.diskBytes)
- if (short) return { strength: SHORT_STRENGTH, ...cpu, reason: `Short of free ${short} for ${need.words}${counting}: ${wants}, so equally strong candidates that have it rank first.${cpuWords}` }
+ if (short) return { strength: SHORT_STRENGTH, ...cpu, reason: `Short of free ${short} for ${need.words}${counting}: ${wants}, so prefer an equally strong candidate that has it.${cpuWords}` }
const unknown = which(memory === null, disk === null)
if (unknown) return { strength: UNKNOWN_STRENGTH, ...cpu, reason: `Free ${unknown} unknown here; ${need.words}: ${wants}.${cpuWords}` }
return busy ? { cost: BUSY_CPU_COST, reason: `Its CPU is busy; it has what ${need.words} needs.` } : null
diff --git a/cli/src/superTabs/route.spec.ts b/cli/src/superTabs/route.spec.ts
index ca78e0572..fcf8fb701 100644
--- a/cli/src/superTabs/route.spec.ts
+++ b/cli/src/superTabs/route.spec.ts
@@ -1,6 +1,6 @@
// cli/src/superTabs/route.spec.ts
import { afterEach, describe, expect, it, vi } from 'vitest'
-import { API_BUILDERS, catalogFrom, quotaBrief, catalogRow, choose, decide, gridStrength, LOCAL_NONE, OTHER_REPOSITORY, parseAssessment, quotaOf2, recordOf, repoMatch, repositoryKey, strengthOf,
+import { API_BUILDERS, CHOOSE_BY_INSTRUCTIONS, NONE_COVERS, catalogFrom, quotaBrief, catalogRow, choose, decide, gridStrength, LOCAL_NONE, OTHER_REPOSITORY, parseAssessment, quotaOf2, recordOf, repoMatch, repositoryKey, strengthOf,
type Assessment, type Catalog, type Commitment, type MemberFrame, type Probe, type RoutePlugin, type TaskFolder } from './route.js'
const object = (v: unknown) => v as Record<string, unknown>
@@ -92,7 +92,7 @@ describe('choose', () => {
expect(choose([probe({ refusals: ['Machine is offline.'] })], policy, a())).toEqual({ error: 'NO_CANDIDATE',
excluded: [{ title: 'New agent · Claude sonnet medium · remote-1', reason: 'Machine is offline.', machine: 'remote-1' }] })
})
- it('shows every candidate that can run, stronger first, then by effective cost, member first', () => {
+ it('shows every candidate that can run, by machine name, a member in another repository after the others on its machine', () => {
const r = choose([
probe({ model: 'opus', effort: 'high', quality: 3, cost: 3, quota: windows([80, 3 * H], [90, 5 * D]) }),
probe({ machineId: 'm2', machineName: 'mac', quota: windows([80, 3 * H], [90, 5 * D], 'B') }),
@@ -106,9 +106,9 @@ describe('choose', () => {
expect(r).toMatchObject({ floor: 1, belowFloor: false, excluded: [] })
// A member in another repository would build in that repository's worktree: shown last, with why (#2377).
expect(r.shown.map(s => s.title)).toEqual([
- 'New agent · Claude opus high · remote-1',
- 'Multiply · Claude sonnet medium · remote-1',
'New agent · Claude sonnet medium · mac',
+ 'Multiply · Claude sonnet medium · remote-1',
+ 'New agent · Claude opus high · remote-1',
'New agent · Claude sonnet medium · remote-1',
'Elsewhere · Claude sonnet medium · remote-1',
])
@@ -118,8 +118,9 @@ describe('choose', () => {
// Diego, 10-30: a member in another repository tied a new agent and the title decided, so Ada took the task in her own
// repository's worktree and Zed did not. Review of #2377: ranking it after a new agent was not enough, since what ranks
// before placement (here: price and quota fit) still let it win. The route no longer tells a build from a review, so it is
- // shown last with why, never left out (project instructions: facts only).
- it('ranks a member in another repository last, with why, whatever its name, price or quota; one in the repository wins; an unknown one ranks as before', () => {
+ // shown after the others on its machine with why, never left out (project instructions: facts only). Since task #2901 nothing
+ // else places a member: whether to reuse an idle agent is the Routing instructions' rule 3, so the title orders the rest.
+ it('lists a member in another repository after the others on its machine, with why, whatever its name, price or quota', () => {
const route = (member: Partial<Probe>, task: Partial<Assessment> = {}, others = [probe()]) =>
ok(choose([...others, probe({ kind: 'member', agentId: 'a1', activity: 'idle', ...member })], policy, a(task), NOW))
const order = (member: Partial<Probe>, task: Partial<Assessment> = {}) => route(member, task).shown.map(s => s.kind)
@@ -129,28 +130,27 @@ describe('choose', () => {
expect(ada.excluded).toEqual([])
expect(ada.shown[1]!.notes).toContain(OTHER_REPOSITORY)
expect(ada.shown[1]!.label).toContain(OTHER_REPOSITORY)
+ // In the repository, unknown, or no folder named: the title orders it beside a new agent.
expect(order({ name: 'Ada', repo: 'same' })).toEqual(['member', 'new'])
- expect(order({ name: 'Zed', repo: 'same' })).toEqual(['member', 'new'])
+ expect(order({ name: 'Zed', repo: 'same' })).toEqual(['new', 'member'])
expect(route({ name: 'Ada', repo: 'same' }).shown[0]!.notes).not.toContain(OTHER_REPOSITORY)
- // No folder named: nothing to be in or out of, so a member saves a start as before.
- expect(order({ name: 'Zed' })).toEqual(['member', 'new'])
- // A repository that could not be told keeps its rank beside a new agent: the title still decides between them.
+ expect(order({ name: 'Zed' })).toEqual(['new', 'member'])
expect(order({ name: 'Ada', repo: 'unknown' })).toEqual(['member', 'new'])
expect(order({ name: 'Zed', repo: 'unknown' })).toEqual(['new', 'member'])
- // Nothing that ranks before placement brings it back: cheaper, stronger, or more quota room than the machine that can
- // start a new agent (its own machine at its agent limit).
+ // Nothing brings it forward on its machine: cheaper, stronger, or more quota room.
expect(order({ name: 'Zed', repo: 'different', cost: 1 })).toEqual(['new', 'member'])
expect(order({ name: 'Zed', repo: 'different', model: 'opus', effort: 'high', quality: 3, cost: 3 })).toEqual(['new', 'member'])
const roomy = windows([90, 3 * H], [90, 5 * D], 'A'), tight = windows([40, 3 * H], [60, 5 * D], 'B')
const full = [probe({ quota: roomy, refusals: ['This machine runs as many agents as its owner allows.'] }), probe({ machineId: 'm2', machineName: 'mac', quota: tight })]
expect(route({ name: 'Ada', repo: 'different', quota: roomy }, {}, full).shown.map(s => s.title))
.toEqual(['New agent · Claude sonnet medium · mac', 'Ada · Claude sonnet medium · remote-1'])
- expect(route({ name: 'Ada', repo: 'same', quota: roomy }, {}, full).shown[0]!.title).toBe('Ada · Claude sonnet medium · remote-1')
+ expect(route({ name: 'Ada', repo: 'same', quota: roomy }, {}, full).shown.map(s => s.title))
+ .toEqual(['New agent · Claude sonnet medium · mac', 'Ada · Claude sonnet medium · remote-1'])
// Only members in another repository: shown, with why, for the agent choosing (a review needs no worktree).
const only = ok(choose([probe({ kind: 'member', agentId: 'a1', name: 'Ada', activity: 'idle', repo: 'different' })], policy, a(), NOW))
expect(only.shown.map(s => [s.title, s.notes])).toEqual([['Ada · Claude sonnet medium · remote-1', [OTHER_REPOSITORY]]])
})
- it('leaves out a member in another repository when the task names a repository; with none named it is ranked last', () => {
+ it('leaves out a member in another repository when the task names a repository; with none named it is listed after the others on its machine', () => {
const member = probe({ kind: 'member', agentId: 'a1', name: 'Ada', activity: 'idle', repo: 'different' })
const named = ok(choose([probe(), member], policy, a({ needs: { tools: [], devices: [], cwd: '/w/web' } }), NOW))
expect(named.shown.map(s => s.kind)).toEqual(['new'])
@@ -162,18 +162,18 @@ describe('choose', () => {
expect(none.shown[1]!.notes).toContain(OTHER_REPOSITORY)
expect(none.excluded).toEqual([])
})
- it('shows those that fit before the unknown and the short, at equal strength and price', () => {
+ it('shows each candidate\'s fit, fits, unknown or short, in machine order', () => {
const r = ok(choose([probe({ quality: 1 }), probe({ quality: 1, machineName: 'mac', quota: windows([90, null], [90, null]) })], policy, a({ difficulty: 'high' }), NOW))
expect(r.shown.map(s => [s.machineName, s.fit.status])).toEqual([['mac', 'fits'], ['remote-1', 'unknown']])
expect(r.excluded).toEqual([])
- // Short goes after a candidate that is only partly known; the pick is not short, so nothing is said.
+ // One candidate's being short says nothing of the route: only none covering the task is said.
const short = ok(choose([probe({ quota: windows([10, null], [90, null]) }), probe({ machineName: 'mac', quota: windows([90, null], null) })], policy, a(), NOW))
expect(short.shown.map(s => [s.machineName, s.fit.status])).toEqual([['mac', 'unknown'], ['remote-1', 'short']])
expect(short.short).toBeUndefined()
})
// Every account the coordinator may pick by the project's order is in front of it: the route used to cut the list at 12, one
// row a machine, and a Claude account with 99% left on a machine whose cheaper Codex was used up never showed (Ken, 2026-11-03).
- it('shows a row for every machine and engine, past 12, and fills up to 12 by rank', () => {
+ it('shows a row for every machine and engine, past 12', () => {
const r = choose(Array.from({ length: 20 }, (_, i) => probe({ machineId: `m${i}`, machineName: `box-${String(i).padStart(2, '0')}` })), policy, a())
if ('error' in r) throw new Error('unexpected')
expect(r.shown).toHaveLength(20)
@@ -181,7 +181,8 @@ describe('choose', () => {
})
/** The phase 1 examples (docs/plans/2026-10-21-swarm-routing-phase1.md), on every row offered and, since the project
- * instructions, no reserve: strength ranks first and nothing is left out for its quota. */
+ * instructions, no reserve: nothing is left out for its quota. Since task #2901 they are facts on each candidate (its fit and
+ * effective cost), never its place: the list is by machine, and the Routing instructions choose. */
describe('strength, fit and effective cost', () => {
const defaults: Catalog = { ...policy, models: policy.models.map(m => ({ ...m, offered: true })) }
const OPUS = { engine: 'claude', model: 'opus', effort: 'high', quality: 3, cost: 3 } as const
@@ -192,58 +193,60 @@ describe('strength, fit and effective cost', () => {
const unknown = { known: false, leftPercent: null, resetsAt: null }
const route = (probes: Probe[], patch: Partial<Assessment>, now = NOW, open: Commitment[] = []) => ok(choose(probes, defaults, a(patch), now, open))
const picks = (r: ReturnType<typeof route>) => r.shown.map(s => `${s.model} on ${s.machineName}`)
+ const row = (r: ReturnType<typeof route>, model: string, machine: string) => r.shown.find(s => s.model === model && s.machineName === machine)!
- it('1. high, medium: Opus high, though its window resets in 40 minutes, over Sonnet with more left', () => {
+ it('1. high, medium: Opus high, whose window resets in 40 minutes, fits at no cost, beside Sonnet with more left', () => {
const r = route([on(OPUS, 'a', windows([70, 40 * M], [80, 5 * D], 'A')), on(SONNET, 'b', windows([90, 3 * H], [80, 5 * D], 'B'))], { difficulty: 'high', size: 'medium' })
- // Strength ranks first: the weaker model is shown after it, not left out.
expect(picks(r)).toEqual(['opus on a', 'sonnet on b'])
expect(r.excluded).toEqual([])
expect(r.shown[0].label).toContain('fits: needs about 30% of the 5-hour window (70% left, resets in 40m, otherwise unused); weekly 6% of 80%')
expect(r.shown[0].fit).toEqual({ status: 'fits', coverage: 2.33, effectiveCost: 0, expiring: 1, spend: { '5-hour': 45, weekly: 6 }, account: 'A' })
})
- it('2. high, large: Codex, whose window would go unused, before Opus high, which is expected to run out and is shown short', () => {
+ it('2. high, large: Opus high is expected to run out and is shown short; Codex, whose window would go unused, fits', () => {
const r = route([on(OPUS, 'a', windows([25, 4 * H], [80, 5 * D], 'A')), on(CODEX, 'a', windows([85, 3 * H], [80, 5 * D]))], { difficulty: 'high', size: 'large' })
- expect(picks(r)).toEqual(['default on a', 'opus on a'])
- expect(r.shown.map(s => s.fit.status)).toEqual(['fits', 'short'])
- expect(r.shown[0].fit.account).toBe('a:codex')
+ expect(picks(r)).toEqual(['opus on a', 'default on a'])
+ expect(r.shown.map(s => s.fit.status)).toEqual(['short', 'fits'])
+ expect(r.shown[1].fit.account).toBe('a:codex')
expect(r.excluded).toEqual([])
})
- it('3. low, small: on the account whose weekly window has room, not on the one nearly spent for the week', () => {
+ it('3. low, small: the account nearly spent for the week costs more in effect than the one with room', () => {
const A = windows([80, 4 * H], [2, 5 * D], 'A'), B = windows([60, 4 * H], [70, 5 * D], 'B')
const r = route([OPUS, SONNET, HAIKU].flatMap(row => [on(row, 'a', A), on(row, 'b', B)]), { difficulty: 'low', size: 'small' })
- expect(picks(r)[0]).toBe('opus on b')
+ expect(row(r, 'opus', 'a').fit.effectiveCost).toBeGreaterThan(row(r, 'opus', 'b').fit.effectiveCost)
// A's weekly budget is 0.4% a day; Haiku's 0.5% costs it 1 + 1 × 0.5 / 0.4.
expect(r.shown.find(s => s.model === 'haiku' && s.machineName === 'a')!.fit.effectiveCost).toBe(2.25)
})
- it('4. low, small: Opus high on the account whose 5-hour window resets in 20 minutes, which would otherwise go unused', () => {
+ it('4. low, small: Opus high on the account whose 5-hour window resets in 20 minutes costs less in effect: it would otherwise go unused', () => {
const A = windows([60, 20 * M], [60, 2 * D], 'A'), B = windows([90, 4 * H], [80, 5 * D], 'B')
const r = route([OPUS, SONNET, HAIKU].flatMap(row => [on(row, 'a', A), on(row, 'b', B)]), { difficulty: 'low', size: 'small' })
- expect(picks(r).slice(0, 4)).toEqual(['opus on a', 'opus on b', 'sonnet on a', 'sonnet on b'])
+ expect(row(r, 'opus', 'a').fit.expiring).toBeGreaterThan(0)
+ expect(row(r, 'opus', 'a').fit.effectiveCost).toBeLessThan(row(r, 'opus', 'b').fit.effectiveCost)
})
- it('5. two high, medium routes a minute apart go to two accounts', () => {
+ it('5. a second high, medium route a minute after the first sees what the first one holds on its account', () => {
const probes = [on(OPUS, 'a', windows([60, 3 * H], [80, 5 * D], 'A')), on(OPUS, 'b', windows([58, 3 * H], [80, 5 * D], 'B'))]
const first = route(probes, { difficulty: 'high', size: 'medium' })
- expect(picks(first)[0]).toBe('opus on a')
+ expect(first.shown.map(s => s.fit.status)).toEqual(['fits', 'fits'])
const held: Commitment = { account: first.shown[0].fit.account, spend: first.shown[0].fit.spend, size: 'medium', createdAt: NOW }
const second = route(probes, { difficulty: 'high', size: 'medium' }, NOW + M, [held])
- expect(picks(second)).toEqual(['opus on b', 'opus on a'])
- expect(second.shown[1]!.label).toContain('short: ')
+ expect(picks(second)).toEqual(['opus on a', 'opus on b'])
+ expect(second.shown.map(s => s.fit.status)).toEqual(['short', 'fits'])
+ expect(second.shown[0]!.label).toContain('short: ')
// Once its run time is over a pick holds nothing.
- expect(picks(route(probes, { difficulty: 'high', size: 'medium' }, NOW + 2 * H, [held]))[0]).toBe('opus on a')
+ expect(route(probes, { difficulty: 'high', size: 'medium' }, NOW + 2 * H, [held]).shown[0]!.fit.status).toBe('fits')
})
it('6. high, large: a window that resets in an hour needs only the part of the task before the reset', () => {
const r = route([on(OPUS, 'a', windows([40, H], [80, 5 * D]))], { difficulty: 'high', size: 'large' })
expect(r.shown[0].fit).toMatchObject({ status: 'fits', coverage: 1.6 })
expect(r.shown[0].label).toContain('needs about 25% of the 5-hour window')
})
- it('7. high, large: a strong pick short of quota is shown first, and the agent is told a weaker one fits', () => {
+ it('7. high, large: each candidate shows whether it is short; the route warns only when none fits', () => {
const r = route([on(OPUS, 'a', windows([30, 4 * H], [80, 5 * D], 'A')), on(CODEX, 'a', windows([40, 4.5 * H], [80, 5 * D])),
on(SONNET, 's', windows([95, 4 * H], [80, 5 * D], 'S'))], { difficulty: 'high', size: 'large' })
expect(picks(r)).toEqual(['opus on a', 'default on a', 'sonnet on s'])
expect(r.shown.map(s => s.fit.status)).toEqual(['short', 'short', 'fits'])
- expect(r.short).toBe('The first candidate\'s 5-hour quota is expected to run out partway and resets in 4h; New agent · Claude sonnet medium · s fits.')
+ expect(r.short).toBeUndefined()
// With no candidate that fits, it says so.
- expect(route(r.shown.slice(0, 2), { difficulty: 'high', size: 'large' }).short).toBe('No candidate is expected to cover this task; its 5-hour quota is expected to run out partway and resets in 4h.')
+ expect(route(r.shown.slice(0, 2), { difficulty: 'high', size: 'large' }).short).toBe(NONE_COVERS)
})
it('8. an assessment without size is taken for medium', () => {
const size = parseAssessment({ difficulty: 'high', risk: 'low', why: 'x' }) as Assessment
@@ -262,7 +265,7 @@ describe('strength, fit and effective cost', () => {
expect(route([on(SONNET, 'a', windows([90, 5 * H], [20, null]))], {}).shown[0].fit.effectiveCost).toBe(2)
const spent = route([on(SONNET, 'a', windows([90, 5 * H], [0, 7 * D]))], {})
expect(spent.shown[0].fit).toMatchObject({ status: 'short', effectiveCost: 2 })
- expect(spent.short).toBe('No candidate is expected to cover this task; its weekly quota is expected to run out partway and resets in 7 days.')
+ expect(spent.short).toBe(NONE_COVERS)
})
// A 5-hour window is never what runs out (Ken, 2026-11-03), and a Team account's Claude, whose 5-hour window its host does not
// relay, read as unknown and fell behind every Codex that fit.
@@ -331,22 +334,91 @@ describe('strength, fit and effective cost', () => {
expect(new Set(r.shown.map(s => s.machineName)).size).toBe(14)
expect(r.shown).toHaveLength(28)
})
- it('orders the short by title at equal strength and price, and says when no reset is known', () => {
+ it('lists the short by machine, and labels a window with no reset known', () => {
const r = route([on(SONNET, 'b', windows([20, null], [80, null], 'B')), on(SONNET, 'a', windows([20, null], [80, null], 'A')), on(SONNET, 'c', windows([25, null], [80, null], 'C'))], {})
expect(picks(r)).toEqual(['sonnet on a', 'sonnet on b', 'sonnet on c'])
- expect(r.short).toBe('No candidate is expected to cover this task; its 5-hour quota is expected to run out partway.')
+ expect(r.short).toBe(NONE_COVERS)
expect(r.shown[2].label).toContain('short: needs about 30% of the 5-hour window (25% left); weekly 4% of 80%')
expect(route([on(SONNET, 'a', windows(null, [80, null]))], {}).shown[0].label).toContain('fits: 5-hour window unknown; weekly 4% of 80%')
})
})
+// Ken, 2026-11-04 (task #2901): PMs took the route's top line, nearly always Opus or Astra, against the project's Routing
+// instructions (soonest reset, most left, fewer working agents, grid first for small work). The route now leaves out what cannot
+// run, keeps every fact, and lists the rest in a neutral order the instructions choose from.
+describe('no ranking: the project\'s Routing instructions choose (task #2901)', () => {
+ const STRONG = { engine: 'claude', model: 'opus', effort: 'high', quality: 3, cost: 3 } as const
+ const CHEAP = { engine: 'claude', model: 'haiku', effort: 'auto', quality: 1, cost: 1 } as const
+ const CODEX = { engine: 'codex', model: 'default', effort: 'default', quality: 3, cost: 2 } as const
+ const all: Catalog = { ...policy, models: policy.models.map(m => ({ ...m, offered: true })) }
+ const on = (machine: string, row: Partial<Probe>, quota = windows([80, 3 * H], [90, 5 * D], `${machine}-${row.engine ?? 'claude'}`)) =>
+ probe({ machineId: machine, machineName: machine, ...row, quota })
+ const order = (r: ReturnType<typeof choose>) => ok(r).shown.map(s => `${s.machineName} ${s.engine} ${s.model}`)
+
+ it('lists candidates by machine name, then engine: never the stronger, the cheaper or the better fit first', () => {
+ const probes = [on('zeta', STRONG, windows([99, 3 * H], [99, 2 * D], 'Z')), on('alpha', CODEX, windows([5, 3 * H], [3, 6 * D], 'AX')),
+ on('alpha', CHEAP, windows([40, 3 * H], [40, 6 * D], 'AC')), on('mid', CHEAP, windows([90, 3 * H], [90, 5 * D], 'M'))]
+ const r = choose(probes, all, a({ difficulty: 'high', size: 'large' }), NOW)
+ expect(order(r)).toEqual(['alpha claude haiku', 'alpha codex default', 'mid claude haiku', 'zeta claude opus'])
+ // The same whatever order the machines answered in.
+ expect(order(choose([...probes].reverse(), all, a({ difficulty: 'high', size: 'large' }), NOW))).toEqual(order(r))
+ })
+ it('a plug-in\'s strength or cost adjustment is a note on its candidate, never the order', () => {
+ const boost: RoutePlugin = { name: 'Boost', adjust: c => c.machineName === 'zeta' ? { strength: 5, cost: -10, reason: 'measured twice as good here' } : null }
+ const r = ok(choose([on('zeta', STRONG), on('alpha', STRONG)], all, a(), NOW, [], [], [], [boost]))
+ expect(r.shown.map(s => s.machineName)).toEqual(['alpha', 'zeta'])
+ expect(r.shown[1]!.notes).toEqual(['Boost: measured twice as good here'])
+ expect(r.shown[1]!.label).toContain('Boost: measured twice as good here')
+ expect(r.adjusted).toBe(true)
+ })
+ it('names no pick: its why sends the choice to the Routing instructions, and the record carries no pick', () => {
+ const c = ok(choose([on('zeta', STRONG), on('alpha', CHEAP)], all, a(), NOW))
+ const v = decide(c)
+ expect(v).not.toHaveProperty('pick')
+ expect(v).toMatchObject({ via: 'instructions', p: null })
+ expect(v.why).toContain('Routing instructions')
+ expect(v.why).not.toMatch(/strength|price/i)
+ const record = recordOf(c, v, a())
+ expect(record).not.toHaveProperty('pick')
+ expect(record).toMatchObject({ via: 'instructions', why: v.why })
+ // A backend from before this takes only a record with a pick: c0 stands in for one, as the old order would have named it.
+ expect(recordOf(c, v, a(), 'picked')).toMatchObject({ pick: 'c0', via: 'order' })
+ expect(recordOf(c, v, a(), 'v1')).toMatchObject({ pick: 'c0', via: 'order' })
+ expect(decide(ok(choose([on('alpha', CHEAP)], all, a(), NOW)))).toMatchObject({ via: 'only' })
+ })
+ it('still leaves out what cannot run, a plug-in\'s refusal among it', () => {
+ const fence: RoutePlugin = { name: 'Fit', adjust: c => c.machineName === 'mid' ? { refuse: true, reason: 'no disk for an end-to-end run' } : null }
+ const r = ok(choose([on('zeta', STRONG, undefined), on('alpha', { ...STRONG, refusals: ['Machine is offline.'] }), on('mid', CHEAP)], all, a(), NOW, [], [], [], [fence]))
+ expect(r.shown.map(s => s.machineName)).toEqual(['zeta'])
+ expect(r.excluded).toEqual([{ title: 'New agent · Claude opus high · alpha', reason: 'Machine is offline.', machine: 'alpha' },
+ { title: 'New agent · Claude haiku auto · mid', reason: 'Fit: no disk for an end-to-end run', machine: 'mid' }])
+ })
+ it('keeps every fact on each candidate: strength, price, quota fit, weekly % left and reset, the agents on its machine', () => {
+ const load = { agents: 3, freeMemoryBytes: 8e9, hasFolder: true }
+ const r = ok(choose([on('alpha', { ...CODEX, load }, windows([60, 2 * H], [42, 3 * D + 5 * H], 'AX')), on('zeta', STRONG)], all, a(), NOW))
+ const alpha = r.shown[0]!
+ expect(alpha.label).toContain('strength 3, cost 2')
+ expect(alpha.label).toContain('weekly 42% left (resets in 3 days)')
+ expect(alpha.label).toContain('3 agents running')
+ expect(alpha.fit).toMatchObject({ status: 'fits', account: 'AX' })
+ expect(quotaBrief(alpha, NOW)).toBe('fits: weekly 42% left, resets in 3d5h')
+ })
+ it('says when no candidate is expected to cover the task, naming none as first', () => {
+ const spent = windows([90, 3 * H], [0, 5 * D])
+ const none = ok(choose([on('alpha', CHEAP, spent), on('zeta', STRONG, spent)], all, a(), NOW))
+ expect(none.short).toBe('No candidate is expected to cover this task on its quota.')
+ // One that fits is in the list with its fit; nothing is said of a first candidate, since there is none.
+ expect(ok(choose([on('alpha', CHEAP), on('zeta', STRONG, spent)], all, a(), NOW)).short).toBeUndefined()
+ })
+})
+
const frame = (patch: Partial<MemberFrame> = {}): MemberFrame => ({ title: 'Fix auth', project: 'api', cwd: '/w/api', root: '/w/api', remote: 'github.com/acme/api', branch: 'feat/auth', updatedAt: 1_000_000 - 2 * 3_600_000, ...patch })
const folder = (patch: Partial<TaskFolder> = {}): TaskFolder => ({ cwd: '/w/api', kind: 'git', name: 'api', root: '/w/api', remote: 'github.com/acme/api', ...patch })
describe('verdict and record', () => {
const choice = () => { const r = choose([probe({ kind: 'member', agentId: 'a1', name: 'Multiply', activity: 'idle' }), probe({ machineName: 'mac' })], policy, a()); if ('error' in r) throw new Error('x'); return r }
- it('takes the first in the order, and says when it was the only candidate', () => {
- expect(decide(choice())).toEqual({ pick: choice().shown[0], via: 'order', p: null, why: 'First by strength, then price and quota fit.' })
+ it('names no pick, and says when it was the only candidate', () => {
+ expect(decide(choice())).toEqual({ via: 'instructions', p: null, why: CHOOSE_BY_INSTRUCTIONS })
expect(decide(ok(choose([probe()], policy, a())))).toMatchObject({ via: 'only', p: null })
})
it('produces a record the backend schema accepts, with no floor and no policy notes', () => {
@@ -355,7 +427,8 @@ describe('verdict and record', () => {
candidates: c.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 })),
excluded: [], floor: 1, notes: false, pick: 'c0', via: 'order', p: null, belowFloor: false, why: v.why }
- expect(recordOf(c, v, a())).toEqual({ ...v1, assessment: { ...v1.assessment, size: 'medium' },
+ const { pick: _pick, ...unpicked } = v1
+ expect(recordOf(c, v, a())).toEqual({ ...unpicked, via: 'instructions', assessment: { ...v1.assessment, size: 'medium' },
candidates: v1.candidates.map(x => ({ ...x, fit: { status: 'unknown', coverage: null, effectiveCost: 2, expiring: 0, spend: { '5-hour': 30, weekly: 4 }, account: 'm1:claude' } })) })
// The server stamps the instructions' revision; the route sends none (phase 4, decision 12).
expect(recordOf(c, v, a())).not.toHaveProperty('instructionsRevision')
@@ -415,10 +488,10 @@ describe('edges', () => {
probe({ kind: 'member', agentId: 'a1', quota: { known: true, leftPercent: null, resetsAt: null } }),
probe({ machineName: 'mac', quota: { known: true, leftPercent: 40, resetsAt: null } }),
], policy, a()))
- expect(r.shown.map(s => s.title)).toEqual(['Member · Claude sonnet medium · remote-1', 'New agent · Claude sonnet medium · mac'])
- expect(r.shown[0].label).toContain('Member ·')
- expect(r.shown[0].label).toContain('quota unknown')
- expect(r.shown[1].label).toContain('quota 40% left')
+ expect(r.shown.map(s => s.title)).toEqual(['New agent · Claude sonnet medium · mac', 'Member · Claude sonnet medium · remote-1'])
+ expect(r.shown[1].label).toContain('Member ·')
+ expect(r.shown[1].label).toContain('quota unknown')
+ expect(r.shown[0].label).toContain('quota 40% left')
expect(ok(choose([probe({ known: false, quota: unknownQuota })], policy, a())).shown[0].label).toContain('quota unknown')
expect(ok(choose([probe({ quota: { known: true, leftPercent: 50, resetsAt: 0 } })], policy, a())).shown[0].label).toContain('resets in 1m')
})
@@ -434,17 +507,18 @@ describe('edges', () => {
const soon = { known: true, leftPercent: 50, resetsAt: Date.now() + 3 * 3_600_000 }
expect(ok(choose([probe({ quota: soon })], policy, a())).shown[0].label).toContain('resets in 3h')
})
- it('falls back to unknown probes, to underfunded ones, and breaks every tie deterministically', () => {
+ it('shows unknown probes, and lists every candidate in one order whatever the order they came in', () => {
expect(ok(choose([probe({ known: false, quota: unknownQuota })], policy, a())).shown).toHaveLength(1)
const tie = ok(choose([
probe({ machineName: 'b', quota: unknownQuota }), probe({ machineName: 'a', quota: unknownQuota }),
probe({ kind: 'member', agentId: 'a1', name: 'M', machineName: 'z', quota: unknownQuota }),
], policy, a()))
- expect(tie.shown.map(s => s.title.split(' · ')[2])).toEqual(['z', 'a', 'b'])
- expect(ok(choose([probe({ machineName: 'b' }), probe({ kind: 'member', agentId: 'a1', name: 'M' })], policy, a())).shown[0].kind).toBe('member')
- expect(ok(choose([probe({ kind: 'member', agentId: 'a1', name: 'M' }), probe({ machineName: 'b' })], policy, a())).shown[0].kind).toBe('member')
+ expect(tie.shown.map(s => s.title.split(' · ')[2])).toEqual(['a', 'b', 'z'])
+ // By machine name, a member or not.
+ expect(ok(choose([probe({ machineName: 'b' }), probe({ kind: 'member', agentId: 'a1', name: 'M' })], policy, a())).shown[0].kind).toBe('new')
+ expect(ok(choose([probe({ kind: 'member', agentId: 'a1', name: 'M' }), probe({ machineName: 'b' })], policy, a())).shown[0].kind).toBe('new')
})
- it('ranks a stronger candidate first even when it is low on quota or unknown, and still shows the weaker one', () => {
+ it('shows a candidate low on quota or unknown beside the others, in machine order', () => {
const low = { known: true, leftPercent: 5, resetsAt: null }
const r = ok(choose([probe({ quality: 1 }), probe({ quality: 3, machineName: 'mac', quota: low })], policy, a({ difficulty: 'high' })))
expect(r.shown.map(s => s.title)).toEqual(['New agent · Claude sonnet medium · mac', 'New agent · Claude sonnet medium · remote-1'])
@@ -583,8 +657,8 @@ describe('local models on the Swarm\'s grid', () => {
expect(bare.shown[0]).toMatchObject({ title: 'New agent · Claude on qwen3 (local) · remote-1', fit: { account: 'local::qwen3' } })
expect((recordOf(bare, decide(bare), a()) as { candidates: unknown[] }).candidates[0]).not.toHaveProperty('gridModel')
})
- it('ranks a local model by its strength, and keeps it beside a subscription row of the same name', () => {
- const r = ok(choose([probe(), local()], policy, a({ kind: 'docs' }), NOW))
+ it('lists a local model after its machine\'s engines, and keeps it beside a subscription row of the same name', () => {
+ const r = ok(choose([local(), probe()], policy, a({ kind: 'docs' }), NOW))
expect(r.shown.map(s => s.gridModel)).toEqual([undefined, 'qwen3'])
// Same machine, engine, model and effort as a subscription `default` row: both stay, being different models.
const both = ok(choose([probe({ model: 'default', effort: 'default', quality: 1, cost: 1, quota: windows([80, 3 * H], [90, 5 * D]) }), local()], policy, a({ difficulty: 'low', kind: 'docs' }), NOW))
@@ -641,9 +715,9 @@ describe('local models on the Swarm\'s grid', () => {
})
})
-// Project instructions, phase 4: the route leaves out only what cannot run, and ranks the rest by strength, price, quota fit
-// and idle members. Rules, floors and kinds are gone; what they said is a note on the candidate.
-describe('ranking by facts', () => {
+// Project instructions, phase 4: the route leaves out only what cannot run, and shows the rest with their facts; since task
+// #2901 it ranks none of them. Rules, floors and kinds are gone; what they said is a note on the candidate.
+describe('facts, not ranking', () => {
const NOTE = 'Not offered by default: no Engineer runs on Claude Sonnet or Claude Haiku (Ken and Dee, 2026-10-30).'
const catalog: Catalog = { models: [
{ engine: 'claude', model: 'opus', effort: 'high', strength: 3, cost: 3, offered: true },
@@ -680,16 +754,16 @@ describe('ranking by facts', () => {
expect(member.shown[0]).toMatchObject({ agentId: 'a1', notes: [NOTE] })
})
- it('ranks by strength, then price and quota fit, then idle members', () => {
- expect(shownOf(choose([kimi, opus, codex], catalog, a(), NOW))).toEqual(['codex default', 'claude opus', 'moonshotai/kimi-k3'])
+ it('lists by machine and engine, never by strength, price, quota fit or idle members (task #2901)', () => {
+ expect(shownOf(choose([kimi, opus, codex], catalog, a(), NOW))).toEqual(['claude opus', 'codex default', 'moonshotai/kimi-k3'])
// A strong candidate short of quota is shown, with fit short.
const short = at({ ...opus, machineId: 'm2', machineName: 'b', quota: windows([20, 4 * H], [80, 5 * D]) })
const r = ok(choose([short, opus], catalog, a(), NOW))
expect(r.shown.map(s => [s.machineName, s.fit.status])).toEqual([['a', 'fits'], ['b', 'short']])
expect(r.excluded).toEqual([])
- // At equal strength, price and fit, an idle member before a new agent.
+ // An idle member is not placed before a new agent: reusing one is the Routing instructions' rule 3.
const member = { ...codex, kind: 'member' as const, agentId: 'a1', name: 'Zed' }
- expect(ok(choose([codex, member], catalog, a(), NOW)).shown.map(s => s.kind)).toEqual(['member', 'new'])
+ expect(ok(choose([codex, member], catalog, a(), NOW)).shown.map(s => s.kind)).toEqual(['new', 'member'])
})
it('offers a named model the catalog does not list, unrated', () => {
@@ -767,7 +841,7 @@ describe('route answers without plug-ins', () => {
on('a', { kind: 'member', agentId: 'm1', name: 'Multiply', activity: 'idle', repo: 'same', frame, earlier: [{ group: 'Dial fix', outcome: 'merged' }] }),
on('b', { kind: 'member', agentId: 'm2', name: 'Elsewhere', activity: 'idle', repo: 'different', frame: null }),
on('a', { model: 'haiku', effort: 'auto', quality: 1, cost: 1 })], policy, a(), NOW]],
- ['high, large: strong pick short, weaker one fits', [[on('a', OPUS, windows([20, 4 * H], [50, 5 * D], 'A')), on('b', CODEX, windows([5, 4 * H], [60, 3 * D], 'B')),
+ ['high, large: a strong candidate short, a weaker one fits', [[on('a', OPUS, windows([20, 4 * H], [50, 5 * D], 'A')), on('b', CODEX, windows([5, 4 * H], [60, 3 * D], 'B')),
on('c', {}, windows([90, 4 * H], [90, 6 * D], 'C'))], policy, a({ difficulty: 'high', size: 'large' }), NOW]],
['low, small: weekly day budget and an expiring window', [[on('a', OPUS, windows([70, 20 * M], [10, 6 * D], 'A')), on('b', OPUS, windows([40, 4 * H], [80, 2 * D], 'B')),
on('c', CODEX, windows(null, [30, 6 * D], 'C'))], policy, a({ difficulty: 'low', size: 'small', kind: 'docs' }), NOW]],
@@ -800,7 +874,7 @@ describe('route answers without plug-ins', () => {
return { name, choice, verdict, record: recordOf(choice, verdict, args[2]) }
}
- it('answers every scenario exactly as before the hook', async () => {
+ it('answers every scenario as recorded: no pick, by machine (task #2901)', async () => {
await expect(`${JSON.stringify(SCENARIOS.map(answer), null, 1)}\n`).toMatchFileSnapshot('./__snapshots__/route.answers.json')
})
it('answers the same with an empty plug-in list, and with plug-ins that have nothing to say', () => {
@@ -813,39 +887,39 @@ describe('route answers without plug-ins', () => {
})
})
-/** The hook pieces 3 to 6 plug into: an ordered list of plug-ins, each able to add candidates and to adjust a candidate's place
- * with a reason people read. */
+/** The hook pieces 3 to 6 plug into: an ordered list of plug-ins, each able to add candidates, to note a finding on a candidate
+ * with a reason people read, and to leave out one that cannot run. Since task #2901 a finding never moves a candidate. */
describe('routing plug-ins', () => {
const OPUS = { model: 'opus', effort: 'high', quality: 3, cost: 3 } as const
const on = (machine: string, row: Partial<Probe> = {}) => probe({ machineId: machine, machineName: machine, ...OPUS, quota: windows([80, 3 * H], [90, 5 * D], machine), ...row })
const route = (probes: Probe[], plugins: RoutePlugin[], task: Partial<Assessment> = {}) => choose(probes, policy, a(task), NOW, [], [], [], plugins)
const titles = (r: ReturnType<typeof choose>) => ok(r).shown.map(s => s.machineName)
- it('a plug-in\'s cost adjustment changes the order, and its reason shows on the candidate, in the label and in the record', () => {
+ it('a plug-in\'s cost adjustment leaves the order alone, and its reason shows on the candidate, in the label and in the record', () => {
expect(titles(route([on('a'), on('b')], []))).toEqual(['a', 'b'])
const measured: RoutePlugin = { name: 'Measured cost', adjust: c => c.machineId === 'b' ? { cost: -1, reason: 'its last 5 builds here cost half the catalog price' } : null }
const r = ok(route([on('a'), on('b')], [measured]))
- expect(titles(r)).toEqual(['b', 'a'])
+ expect(titles(r)).toEqual(['a', 'b'])
const reason = 'Measured cost: its last 5 builds here cost half the catalog price'
- expect(r.shown[0]!.notes).toEqual([reason])
- expect(r.shown[0]!.label).toContain(reason)
- expect(r.shown[1]!.notes).toEqual([])
+ expect(r.shown[1]!.notes).toEqual([reason])
+ expect(r.shown[1]!.label).toContain(reason)
+ expect(r.shown[0]!.notes).toEqual([])
const verdict = decide(r)
- expect(verdict.why).toBe('First by strength, then price and quota fit, with the plug-ins\' adjustments in each candidate\'s notes.')
+ expect(verdict.why).toBe(`${CHOOSE_BY_INSTRUCTIONS} Plug-ins' findings are in each candidate's notes.`)
const record = recordOf(r, verdict, a()) as { candidates: Array<{ label: string; fit: { effectiveCost: number }; quality: number; cost: number }> }
- // What the candidate is and what its quota costs are recorded as measured; only the order and the reason change.
- expect(record.candidates[0]).toMatchObject({ quality: 3, cost: 3, fit: { effectiveCost: ok(route([on('b')], [])).shown[0]!.fit.effectiveCost } })
- expect(record.candidates[0]!.label).toContain(reason)
+ // What the candidate is and what its quota costs are recorded as measured; only the reason is added.
+ expect(record.candidates[1]).toMatchObject({ quality: 3, cost: 3, fit: { effectiveCost: ok(route([on('b')], [])).shown[0]!.fit.effectiveCost } })
+ expect(record.candidates[1]!.label).toContain(reason)
})
- it('a strength adjustment ranks before price; adjustments of several plug-ins add up in their order', () => {
+ it('a strength adjustment leaves the order alone too; the notes of several plug-ins add up in their order', () => {
const weaker = on('s', { model: 'sonnet', effort: 'medium', quality: 2, cost: 2 })
const results: RoutePlugin = { name: 'Results', adjust: c => c.model === 'sonnet' ? { strength: 0.75, reason: 'merged 9 of its last 10 docs tasks' } : null }
const fit: RoutePlugin = { name: 'Machine fit', adjust: c => c.model === 'sonnet' ? { strength: 0.5, reason: 'has the task folder' } : null }
expect(titles(route([on('a'), weaker], [results]))).toEqual(['a', 's'])
const r = ok(route([on('a'), weaker], [results, fit]))
- expect(titles(r)).toEqual(['s', 'a'])
- expect(r.shown[0]!.notes).toEqual(['Results: merged 9 of its last 10 docs tasks', 'Machine fit: has the task folder'])
- expect(r.shown[0]!.quality).toBe(2)
+ expect(titles(r)).toEqual(['a', 's'])
+ expect(r.shown[1]!.notes).toEqual(['Results: merged 9 of its last 10 docs tasks', 'Machine fit: has the task folder'])
+ expect(r.shown[1]!.quality).toBe(2)
})
it('a refusal leaves a candidate out with the plug-in\'s reason; refusing every one is no candidate', () => {
const tooSmall: RoutePlugin = { name: 'Machine fit', adjust: c => c.machineId === 'a' ? { refuse: true, reason: 'has 1 GB free, the task needs 4 GB' } : null }
@@ -874,10 +948,10 @@ describe('routing plug-ins', () => {
on('a', { model: 'haiku', effort: 'auto', quality: 1, cost: 1 }),
] }
const r = ok(choose(given, policy, a(), NOW, [], [], [], [sneaky]))
- // An idle member before a new agent at equal strength and price, as without plug-ins.
- expect(r.shown.map(s => s.title)).toEqual(['Kai · Claude opus high · k', 'New agent · Claude opus high · a', 'New agent · Claude sonnet medium · a'])
+ // By machine, as without plug-ins.
+ expect(r.shown.map(s => s.title)).toEqual(['New agent · Claude opus high · a', 'New agent · Claude sonnet medium · a', 'Kai · Claude opus high · k'])
// The added Sonnet on a keeps a's note and quota reading, not its own.
- expect(r.shown[2]).toMatchObject({ notes: ['Its last task here was lost.'], quota: given[0]!.quota })
+ expect(r.shown[1]).toMatchObject({ notes: ['Its last task here was lost.'], quota: given[0]!.quota })
expect(r.excluded).toEqual([
{ title: 'New agent · Claude opus high · b', reason: 'Machine is offline.', machine: 'b' },
{ title: 'New agent · Claude sonnet medium · b', reason: 'Machine is offline.', machine: 'b' },
@@ -931,7 +1005,7 @@ describe('routing plug-ins', () => {
const quick: RoutePlugin = { name: 'Quick', adjust: () => { clock += 10; return null } }
const { warnings, ...rest } = ok(route([on('a'), on('b')], [slowAdd, slowAdjust, quick]))
expect(rest).toEqual(plain)
- expect(warnings).toEqual(['Slow add', 'Slow'].map(n => `The routing plug-in "${n}" was skipped: it took longer than 200 ms. The route is ranked without it.`))
+ expect(warnings).toEqual(['Slow add', 'Slow'].map(n => `The routing plug-in "${n}" was skipped: it took longer than 200 ms. The route is shown without it.`))
})
it('plug-ins run in their list\'s fixed order, and the same route answers the same every time', () => {
const one: RoutePlugin = { name: 'One', adjust: () => ({ cost: 0.5, reason: 'first' }) }
@@ -953,7 +1027,7 @@ describe('routing plug-ins', () => {
const { warnings, ...rest } = r
expect(rest).toEqual(plain)
// Candidates are gathered before any is judged, so those plug-ins are named first.
- expect(warnings).toEqual(['Broken', 'Junk', 'Not a list', 'Half', 'NaN', 'Blank'].map(n => `The routing plug-in "${n}" was skipped: it failed. The route is ranked without it.`))
+ expect(warnings).toEqual(['Broken', 'Junk', 'Not a list', 'Half', 'NaN', 'Blank'].map(n => `The routing plug-in "${n}" was skipped: it failed. The route is shown without it.`))
expect(JSON.stringify(r)).not.toContain('secret')
// Nothing can run: the warning still goes with the answer.
expect(route([on('a', { refusals: ['Machine is offline.'] })], [broken])).toMatchObject({ error: 'NO_CANDIDATE', warnings: [expect.stringContaining('"Broken"')] })
diff --git a/cli/src/superTabs/route.ts b/cli/src/superTabs/route.ts
index acb4eb88f..324de44ba 100644
--- a/cli/src/superTabs/route.ts
+++ b/cli/src/superTabs/route.ts
@@ -1,10 +1,11 @@
-/** Super Tab routing, the pure half (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md), ordered by
- * strength, effective cost and quota fit since phase 1 (docs/plans/2026-10-21-swarm-routing-phase1.md).
+/** 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 ranks every
- * other candidate by strength, price, quota fit and idle members. The owner's rules, floors, review and build limits are
- * gone; what the route knows beside the facts (a lost task, a stalled machine, a catalog note) is a note on the candidate,
- * and the project's instructions say how to choose. */
+ * 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'
@@ -84,20 +85,20 @@ export interface Shown extends Probe { id: string; title: string; label: string;
/** 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 the pick is not expected to cover the task on its quota. `adjusted`: a plug-in moved a candidate or left
+ * `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` shift the two terms the order ranks by (stronger first, then
- * cheaper in effect), in the catalog's units: +0.5 strength or -1 cost moves it up. 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. `reason` is what people read, on the candidate's notes as "name: reason", so it 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. */
+/** 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 ranking that is not the route's own (Scholes's goals, pieces 3 to 6: measured cost and results, more model
+/** 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
@@ -108,14 +109,12 @@ export interface RoutePlugin {
candidates?(probes: readonly Probe[], context: RouteContext): Probe[]
adjust?(candidate: Readonly<Probe & { fit: Fit }>, context: RouteContext): Adjustment | null
}
-/** The order's two adjustable terms for one candidate ([compare]); with no plug-in they are its strength and effective cost. */
-interface Ranked { strength: number; cost: number }
/** 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 ranked without it.`
+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). */
@@ -179,7 +178,9 @@ function pluginAdjustments<T extends Probe & { fit: Fit }>(ranked: T[], plugins:
}
return each
}
-export interface Verdict { pick: Shown; via: 'order' | 'only'; p: null; why: string }
+/** What the route says of its candidates: no pick (task #2901). `via` `instructions`: the project's Routing instructions choose;
+ * `only`: one candidate can run. */
+export interface Verdict { via: 'instructions' | 'only'; p: null; why: string }
const LEVELS: Level[] = ['low', 'medium', 'high']
const HEAVY_WORK: unknown[] = ['build', 'e2e'] satisfies HeavyWork[]
@@ -470,31 +471,28 @@ function sizeUp(p: Probe, a: Assessment, now: number, open: Commitment[]): Sized
}
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).'
-const FIT_ORDER = { fits: 0, unknown: 1, short: 2 } as const
-/** The order: a member in another repository last; then stronger, cheaper in effect (price, less with a 5-hour window that
- * would otherwise go unused), a better quota fit, an idle member in the task's repository before a new agent, then by title
- * (project instructions, phase 4). */
-function compare(x: Probe & Sized & { rank: Ranked }, y: Probe & Sized & { rank: Ranked }): number {
- // A member in another repository tied a new agent and its name decided whether it took the task (Diego, 2026-10-30, #2377);
- // ranked only after a new agent, a cheaper model or more quota still won it. The route no longer tells a build from a
- // review, which needs no worktree, so it is shown last with OTHER_REPOSITORY as a note (choose), never left out.
+/** 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
- const placed = (p: Probe) => p.kind === 'member' && (p.repo ?? 'same') === 'same' ? 0 : 1
- return elsewhere(x) - elsewhere(y)
- || y.rank.strength - x.rank.strength
- || x.rank.cost - y.rank.cost
- || FIT_ORDER[x.fit.status] - FIT_ORDER[y.fit.status]
- || placed(x) - placed(y)
+ 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 rows shown: the best new agent and the best member of every engine on every machine, up to [RECORD_MAX], then the rest by rank up to the limit, all in rank
- * 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 rows shown: the first new agent and the first member of every engine on every machine in the neutral order, up to
+ * [RECORD_MAX], then the rest up to 12, all in that 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). */
function withEveryAccount<T extends Pick<Probe, 'machineId' | 'engine' | 'gridModel' | 'kind'>>(ranked: T[]): T[] {
const keep = new Set<T>(), seen = new Set<string>()
for (const p of ranked) if (!seen.has(slotOf(p)) && keep.size < RECORD_MAX) { seen.add(slotOf(p)); keep.add(p) }
@@ -533,7 +531,7 @@ function unratedProbes(probes: Probe[], named: string): Probe[] {
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, ranked ([compare]), and those that cannot, with why. A catalog row not offered by
+/** 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
@@ -578,55 +576,53 @@ export function choose(given: Probe[], catalog: Catalog, a: Assessment, now: num
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)
- const ranked = sized.flatMap((p, i) => {
- const mine = adjustments[i]!, rank = { strength: p.quality, cost: p.fit.effectiveCost }
- if (!mine.length) return [{ ...p, rank }]
+ // 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 []
}
- for (const { adjustment } of mine) { rank.strength += adjustment.strength ?? 0; rank.cost += adjustment.cost ?? 0 }
- return [{ ...p, notes: [...p.notes, ...reasons], rank }]
+ return [{ ...p, notes: [...p.notes, ...reasons] }]
}).sort(compare)
- if (!ranked.length) return { error: 'NO_CANDIDATE', excluded, ...warned() }
- const shown = withEveryAccount(ranked).map(({ tight, text, rank: _rank, ...p }, i) => ({ ...p, id: `c${i}`, title: titleOf(p), label: labelOf({ ...p, tight, text }, now) }))
- const first = ranked[0]!
- return { shown, excluded, floor: 1, belowFloor: false, ...(first.fit.status === 'short' ? { short: shortOf(first, ranked) } : {}),
+ if (!listed.length) return { error: 'NO_CANDIDATE', excluded, ...warned() }
+ const shown = withEveryAccount(listed).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 agent choosing is told when the pick is not expected to cover the task on its quota: a candidate further down
- * may, or none does. */
-function shortOf(first: Probe & Sized, ranked: Array<Probe & Sized>): string {
- const w = first.tight!, resets = w.resetsIn === null ? '' : ` and resets in ${span(w.resetsIn)}`
- const fitting = ranked.find(p => p.fit.status === 'fits')
- return fitting ? `The first candidate's ${w.name} quota is expected to run out partway${resets}; ${titleOf(fitting)} fits.`
- : `No candidate is expected to cover this task; its ${w.name} quota is expected to run out partway${resets}.`
-}
-
+/** 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 {
- const pick = choice.shown[0]!
- return choice.shown.length === 1 ? { pick, via: 'only', p: null, why: 'Only candidate that can run this task.' }
- : { pick, via: 'order', p: null, why: choice.adjusted ? 'First by strength, then price and quota fit, with the plug-ins\' adjustments in each candidate\'s notes.'
- : 'First by strength, then price and quota fit.' }
+ 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 record in the shape a backend takes: `current` with the job's kind (what attempts are compared by, backend costs/read.ts),
- * `unkinded` for a backend from before kinds, and `v1` without size and fit too, 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' | 'unkinded' | 'v1'
+/** The record in the shape a backend takes: `current` with the job's kind (what attempts are compared by, backend costs/read.ts)
+ * and no pick (task #2901); `picked` for a backend from before that, 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' | 'picked' | 'unkinded' | 'v1'
export function recordOf(choice: Choice, verdict: Verdict, a: Assessment, shape: RecordShape = 'current'): Record<string, unknown> {
- const v1 = shape === 'v1'
+ const v1 = shape === 'v1', kinded = shape === 'current' || shape === 'picked'
return {
- assessment: { difficulty: a.difficulty, risk: a.risk, why: a.why, ...(v1 ? {} : { size: a.size }), ...(shape === 'current' && a.kind ? { kind: a.kind } : {}),
- ...(shape === 'current' && a.local ? { local: true } : {}), ...(shape === 'current' && a.model ? { model: a.model } : {}) },
+ 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: s.fit }),
...(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,
- pick: verdict.pick.id, via: verdict.via, p: verdict.p, belowFloor: false, why: cut(verdict.why, 300),
+ ...(shape === 'current' ? { via: verdict.via } : { pick: choice.shown[0]!.id, via: verdict.via === 'only' ? 'only' : 'order' }),
+ p: verdict.p, belowFloor: false, why: cut(verdict.why, 300),
}
}
diff --git a/cli/src/superTabs/routeCheapFirst.spec.ts b/cli/src/superTabs/routeCheapFirst.spec.ts
index 8a886c563..db8f360b6 100644
--- a/cli/src/superTabs/routeCheapFirst.spec.ts
+++ b/cli/src/superTabs/routeCheapFirst.spec.ts
@@ -26,26 +26,33 @@ const ok = (r: ReturnType<typeof choose>) => { if ('error' in r) throw new Error
const picks = (r: ReturnType<typeof choose>) => ok(r).shown.map(s => s.gridLabel ?? `${s.engine} ${s.model}`)
const reasons = (r: ReturnType<typeof choose>) => r.excluded.map(e => e.reason)
-describe('cheap first: a small, low-risk build goes to a cheap grid model first', () => {
- it('ranks Kimi K3 and DeepSeek above Opus and Codex, says why on the candidate, and records it', () => {
+describe('cheap first: a small, low-risk build notes a cheap grid model as the first choice', () => {
+ it('notes Kimi K3 and DeepSeek as the cheap first choice beside Opus and Codex, says why on the candidate, and records it', () => {
const r = ok(route(first))
- expect(picks(r)).toEqual(['DeepSeek v4.1', 'Kimi K3', 'codex default', 'claude opus', 'Qwen 3'])
- expect(r.shown[0]!.notes).toEqual([`${CHEAP_FIRST}: ${GRID_FIRST}`])
- expect(r.shown[0]!.label).toContain(GRID_FIRST)
- // Opus and Codex are not moved, and a grid model the catalog does not rate (Qwen, 1) is not either.
+ // Since task #2901 a plug-in's finding is a note, never the order.
+ expect(picks(r)).toEqual(picks(choose([opus, codex, kimi, deepseek, qwen], catalog, a(), NOW)))
+ for (const label of ['DeepSeek v4.1', 'Kimi K3']) {
+ const s = r.shown.find(c => c.gridLabel === label)!
+ expect(s.notes).toEqual([`${CHEAP_FIRST}: ${GRID_FIRST}`])
+ expect(s.label).toContain(GRID_FIRST)
+ }
+ expect(r.adjusted).toBe(true)
+ // Opus and Codex are not noted, and a grid model the catalog does not rate (Qwen, 1) is not either.
expect(r.shown.find(s => s.model === 'opus')!.notes).toEqual([])
+ expect(r.shown.find(s => s.engine === 'codex')!.notes).toEqual([])
expect(r.shown.find(s => s.gridLabel === 'Qwen 3')!.notes).toEqual([])
const verdict = decide(r)
- const record = recordOf(r, verdict, a()) as { candidates: Array<{ gridModel?: string; quality: number; label: string }>; pick: string }
+ expect(verdict.via).toBe('instructions')
+ const record = recordOf(r, verdict, a()) as { candidates: Array<{ gridModel?: string; quality: number; label: string }> }
// It is recorded as what it is: a grid model rated 2, with the reason people read.
- expect(record.candidates.find(c => c.gridModel === 'deepseek/deepseek-v4.1')).toMatchObject({ quality: 2 })
- expect(record.candidates[0]!.label).toContain(GRID_FIRST)
- expect(record.pick).toBe(r.shown[0]!.id)
+ const recorded = record.candidates.find(c => c.gridModel === 'deepseek/deepseek-v4.1')!
+ expect(recorded).toMatchObject({ quality: 2 })
+ expect(recorded.label).toContain(GRID_FIRST)
+ expect(record).not.toHaveProperty('pick')
})
- it('keeps today\'s order unless the task is low risk, low difficulty and small in scope', () => {
+ it('says nothing unless the task is low risk, low difficulty and small in scope', () => {
const today = picks(choose([opus, codex, kimi, deepseek, qwen], catalog, a(), NOW))
- expect(today[0]).toBe('codex default')
for (const [task, assessment] of [
[first, { difficulty: 'medium' }], [first, { risk: 'medium' }], [{ ...first, owned: 0 }, {}], [{ ...first, owned: MAX_OWNED + 1 }, {}],
] as Array<[CheapTask, Partial<Assessment>]>) {
@@ -53,14 +60,14 @@ describe('cheap first: a small, low-risk build goes to a cheap grid model first'
expect(picks(r)).toEqual(today)
expect(r.adjusted).toBeUndefined()
}
- expect(picks(route({ ...first, owned: MAX_OWNED }))[0]).toBe('DeepSeek v4.1')
+ expect(ok(route({ ...first, owned: MAX_OWNED })).shown.find(s => s.gridLabel === 'DeepSeek v4.1')!.notes).toEqual([`${CHEAP_FIRST}: ${GRID_FIRST}`])
})
it('never puts a review on a grid model, even one a person names or a local one asked for, and says why', () => {
for (const task of [{ ...first, review: true }, first]) {
const kind = task.review ? {} : { kind: 'review' }
const r = ok(route(task, kind))
- expect(picks(r)).toEqual(['codex default', 'claude opus'])
+ expect(picks(r)).toEqual(['claude opus', 'codex default'])
expect(reasons(r)).toEqual([`${GRID_LIMITS}: ${NEVER_REVIEWS}`, `${GRID_LIMITS}: ${NEVER_REVIEWS}`, `${GRID_LIMITS}: ${NEVER_REVIEWS}`])
expect(route(task, { ...kind, model: 'kimi k3' })).toEqual({ error: 'NO_CANDIDATE', excluded: [{ title: expect.stringContaining('Kimi K3'), reason: `${GRID_LIMITS}: ${NEVER_REVIEWS}`, machine: 'remote-1' }] })
expect(route(task, { ...kind, local: true })).toMatchObject({ error: 'NO_CANDIDATE' })
@@ -86,13 +93,13 @@ describe('cheap first: a small, low-risk build goes to a cheap grid model first'
}
expect(GRID_KINDS_ONLY).toBe('A model on the Swarm\'s grid takes only work whose kind is docs, tests, fixtures, copy or refactor; this task names no such kind.')
// Every kind on the list may try the grid first.
- for (const kind of GRID_KINDS) expect(picks(route(first, { kind }))[0]).toBe('DeepSeek v4.1')
+ for (const kind of GRID_KINDS) expect(ok(route(first, { kind })).shown.find(s => s.gridLabel === 'DeepSeek v4.1')!.notes).toEqual([`${CHEAP_FIRST}: ${GRID_FIRST}`])
})
it('steps up: a task with an earlier attempt routes without grid models, and says why', () => {
const earlier = { ...first, earlier: 'Its first attempt ran on Kimi K3.' }
const r = ok(route(earlier))
- expect(picks(r)).toEqual(['codex default', 'claude opus'])
+ expect(picks(r)).toEqual(['claude opus', 'codex default'])
expect(new Set(reasons(r))).toEqual(new Set([`${CHEAP_FIRST}: ${FIRST_ATTEMPT_ONLY} Its first attempt ran on Kimi K3.`]))
// A person who names a grid model for the next attempt still gets it, told that the task stepped up.
const named = ok(route(earlier, { model: 'kimi' }))
@@ -102,7 +109,7 @@ describe('cheap first: a small, low-risk build goes to a cheap grid model first'
expect(route({ ...earlier, review: true }, { model: 'kimi' })).toMatchObject({ error: 'NO_CANDIDATE' })
})
- it('adds no candidate: it only ranks and leaves out the grid models the route itself found served and rated', () => {
+ it('adds no candidate: it only notes and leaves out the grid models the route itself found served and rated', () => {
// Grid candidates come only from routeCommand.ts localProbes: models a fresh reading says are served, rated from the catalog.
expect(cheapFirst(first).candidates).toBeUndefined()
expect(gridLimits(true).candidates).toBeUndefined()
@@ -119,7 +126,7 @@ describe('cheap first: a small, low-risk build goes to a cheap grid model first'
})
})
-describe('what the route reads of a task before it is ranked', () => {
+describe('what the route reads of a task before it routes it', () => {
const group = (patch: Record<string, unknown> = {}) => ({ id: 'g1', task: { goal: 'Fix it', owns: ['docs/a.md'] }, checks: [{ id: 'c1' }], assignment: null, ...patch })
const state = (patch: Record<string, unknown> = {}) => ({ agents: [], starts: [], ...patch })
const history = { decisions: [], attempts: [] }
@@ -169,7 +176,7 @@ describe('what the route reads of a task before it is ranked', () => {
})
describe('the maker', () => {
- it('is in the route\'s makers list, the guard before the ranking', () => {
+ it('is in the route\'s makers list, the guard before cheap first', () => {
const at = CHEAP_FIRST_MAKERS.map(m => ROUTE_PLUGIN_MAKERS.indexOf(m))
expect(at.every(i => i >= 0)).toBe(true)
expect(at[0]).toBeLessThan(at[1]!)
@@ -207,17 +214,18 @@ describe('the maker', () => {
const empty = { ok: true, value: { decisions: [], attempts: [] } }
for (const tab of [read([]), {}, { tab: { state: 'x' } }]) {
const r = ok(choose([opus, kimi], catalog, a(), NOW, [], [], [], [(await make(Promise.resolve(empty), tab as never))!]))
- // Nothing owned is no small task: today's order, the grid below the strong models.
+ // Nothing owned is no small task: the grid model is not noted as the cheap first choice.
expect(r.shown.map(s => s.gridModel ?? s.model)).toEqual(['opus', 'moonshotai/kimi-k3'])
+ expect(r.shown.flatMap(s => s.notes)).toEqual([])
}
- // A review the tab lists is read as one: the ranking leaves it to the guard.
+ // A review the tab lists is read as one: cheap first leaves it to the guard.
const listed = read([{ id: 'g1', reviewOf: 'g0' }])
const guard = await GRID_LIMITS_MAKER.make({ conversationId: 'g1', assessment: a(), read: listed, catalog, history: Promise.resolve(empty), request: async () => ({}) })
const review = ok(choose([opus, kimi], catalog, a(), NOW, [], [], [], [guard!, (await make(Promise.resolve(empty), listed))!]))
expect(review.excluded.map(e => e.reason)).toEqual([`${GRID_LIMITS}: ${NEVER_REVIEWS}`])
})
- it('a review or security route has no grid choice when the history is unreadable, slow, or the ranking is dropped', async () => {
+ it('a review or security route has no grid choice when the history is unreadable, slow, or cheap first is dropped', async () => {
const review = read([{ id: 'g1', reviewOf: 'g0', task: { owns: ['docs/a.md'] } }])
const gridIn = (plugins: Parameters<typeof choose>[7], assessment: Partial<Assessment> = {}) =>
ok(choose([opus, kimi], catalog, a(assessment), NOW, [], [], [], plugins)).shown.some(s => s.gridModel)
@@ -238,10 +246,10 @@ describe('the maker', () => {
expect(warnings).toEqual([])
expect(plugins.map(p => p.name)).toEqual([GRID_LIMITS, CHEAP_FIRST])
expect(gridIn(plugins, assessment)).toBe(false)
- // With the ranking dropped, as the hook drops a late maker, the guard alone still leaves the grid out.
+ // With cheap first dropped, as the hook drops a late maker, the guard alone still leaves the grid out.
expect(gridIn([plugins[0]!], assessment)).toBe(false)
}
- // A ranking whose maker never answers is dropped after the hook's limit; the guard's plug-in is there all the same.
+ // A cheap first whose maker never answers is dropped after the hook's limit; the guard's plug-in is there all the same.
const hung = { name: CHEAP_FIRST, make: () => new Promise<never>(() => {}) }
const making = makePlugins([GRID_LIMITS_MAKER, hung], input(Promise.resolve(null)))
await vi.advanceTimersByTimeAsync(MAKER_TIMEOUT_MS)
diff --git a/cli/src/superTabs/routeCheapFirst.ts b/cli/src/superTabs/routeCheapFirst.ts
index 39dc44918..f72e2cb86 100644
--- a/cli/src/superTabs/routeCheapFirst.ts
+++ b/cli/src/superTabs/routeCheapFirst.ts
@@ -1,7 +1,8 @@
/** Cheap first (Scholes's goals, piece 4; Ken, 2026-10-29): a small, low-risk build goes to a cheap model on the Swarm's grid
* (Kimi K3, DeepSeek v4.1) before Opus or Astra, and steps up to them once that attempt fails. Reviews and security work never
- * run on the grid. A route plug-in (route.ts RoutePlugin): it ranks and leaves out grid candidates only, each with a reason
- * people read, and leaves every subscription candidate and member as it was.
+ * run on the grid. A route plug-in (route.ts RoutePlugin): it notes and leaves out grid candidates only, each with a reason
+ * people read, and leaves every subscription candidate and member as it was. Since task #2901 its note is never the order:
+ * the project's Routing instructions weigh it.
*
* Since project instructions (#2414) the server no longer steps a task up, and only the server knew a grid attempt's first
* review failed. So the step-up is read from what the route already sees: a grid model takes only a task's first attempt
@@ -23,7 +24,7 @@ export const CHEAP_FIRST = 'Cheap first'
* owned files"). Every routed task names owned code and checks, so their presence says nothing on its own. */
export const MAX_OWNED = 3
/** The least strength a grid model needs to be tried first: the catalog's named grid rows (Kimi K3, DeepSeek v4.1) are 2; an
- * unnamed grid model (a small local one) is 1 and is never moved up. */
+ * unnamed grid model (a small local one) is 1 and is never noted as the cheap first choice. */
const CHEAP_STRENGTH = 2
/** Kinds of work a grid model never takes, as the routing agent names them (route.ts Assessment.kind). */
const SECURITY_KINDS = new Set(['security', 'auth', 'privacy', 'secrets', 'crypto', 'permissions'])
@@ -32,7 +33,7 @@ const SECURITY_KINDS = new Set(['security', 'auth', 'privacy', 'secrets', 'crypt
* Adding a kind here is the one place to widen it. */
export const GRID_KINDS: readonly string[] = ['docs', 'tests', 'fixtures', 'copy', 'refactor']
-export const GRID_FIRST = 'A small, low-risk build: a cheap model on the Swarm\'s grid tries it first. If its review fails or the attempt is lost, the next route steps up to a strong model.'
+export const GRID_FIRST = 'A small, low-risk build: the cheap first choice is a model on the Swarm\'s grid. If its review fails or the attempt is lost, the next route steps up to a strong model.'
export const NEVER_REVIEWS = 'A review never runs on a model on the Swarm\'s grid: reviews need a strong model.'
export const NEVER_SECURITY = 'Security-sensitive work (a security kind or high risk) never runs on a model on the Swarm\'s grid.'
/** The kinds as people read them: "docs, tests, fixtures, copy or refactor". */
@@ -41,7 +42,7 @@ export const GRID_KINDS_ONLY = `A model on the Swarm's grid takes only work whos
/** What the route's help tells every routing agent (service.ts HELP.route), from the same constants the plug-ins apply, so a
* Lead knows which kind to give for the cheap choice (review of #2422: help that called kind optional got it rarely). */
export const ROUTE_KIND_HELP = `one word for the kind of work; a model on the Swarm's grid is offered only for kind ${KINDS_TEXT}`
-export const CHEAP_FIRST_HELP = `Cheap first: small, low-risk work (risk and difficulty low, 1 to ${MAX_OWNED} owned paths) of kind ${KINDS_TEXT} ranks a model on the Swarm's grid first. `
+export const CHEAP_FIRST_HELP = `Cheap first: small, low-risk work (risk and difficulty low, 1 to ${MAX_OWNED} owned paths) of kind ${KINDS_TEXT} notes a model on the Swarm's grid as the cheap first choice. `
+ 'A model on the grid is never offered, even when named, for a review, security work (a security kind or high risk), work of any other kind or with no kind, or a task\'s second attempt.'
export const FIRST_ATTEMPT_ONLY = 'A model on the Swarm\'s grid takes only a task\'s first attempt, so this one steps up.'
export const EARLIER_UNREADABLE = 'Its earlier attempts could not be read, so it is not taken for a first attempt.'
@@ -102,10 +103,10 @@ export function gridLimits(review: boolean): RoutePlugin {
}
}
-/** The ranking for one task, beside [gridLimits]: a grid candidate is left out of any attempt after the first unless a person
- * named it, and ranked first for a small, low-risk build it is strong enough for: above the catalog's strongest, so it is
- * tried before Opus and Astra while keeping the order among grid models. A review or security task is the guard's, so this
- * says nothing of it. */
+/** Cheap first for one task, beside [gridLimits]: a grid candidate is left out of any attempt after the first unless a person
+ * named it, and noted as the cheap first choice for a small, low-risk build it is strong enough for, to be tried before Opus
+ * and Astra. Its strength leans above the catalog's strongest, which since task #2901 moves nothing. A review or security
+ * task is the guard's, so this says nothing of it. */
export function cheapFirst(task: CheapTask): RoutePlugin {
return {
name: CHEAP_FIRST,
@@ -155,5 +156,5 @@ export const CHEAP_FIRST_MAKER: PluginMaker = {
},
}
-/** Piece 4's makers, in order: the guard first, ready at once, then the ranking. */
+/** Piece 4's makers, in order: the guard first, ready at once, then cheap first. */
export const CHEAP_FIRST_MAKERS: readonly PluginMaker[] = [GRID_LIMITS_MAKER, CHEAP_FIRST_MAKER]
diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.ts
index 56572861a..c6fa308ba 100644
--- a/cli/src/superTabs/routeCommand.spec.ts
+++ b/cli/src/superTabs/routeCommand.spec.ts
@@ -6,7 +6,7 @@ import { join } from 'node:path'
import { ELSEWHERE, heldByStarts, heldLocalModels, leftOut, localProbes, NO_SWARM_AGENTS_ON, offlineModels, routeTask, servedModels, STALL_RETRY_MS, stalled } from './routeCommand.js'
import type { describeScmProject } from '../scm/scmProjects.js'
import { admission, quotaOf, RELAYED_QUOTA, USED_UP_WINDOW } from './capacity.js'
-import { OTHER_REPOSITORY, type Catalog, type Probe, type RoutePlugin } from './route.js'
+import { NONE_COVERS, OTHER_REPOSITORY, type Catalog, type Probe, type RoutePlugin } from './route.js'
import { MAKER_TIMEOUT_MS, type PluginInput, type PluginMaker } from './routePlugins.js'
import { placedHeavyWork } from './machineFit.js'
import { inspectCapacity } from './start.js'
@@ -72,6 +72,8 @@ const input = { tabId: 'tab', conversationId: 'g1', assessment: { difficulty: 'm
const opener = (make: (id: string) => ReturnType<typeof daemon> = id => daemon(id, { agents: id === 'm1' ? ['h1'] : [] })) => vi.fn(async (_w: unknown, id = '') => make(id)) as unknown as typeof openDaemon & Mock
const recorded = (s: ReturnType<typeof scoped>) => s.mock.calls.find(c => c[0].action === 'command')![0]
/** Each candidate's line, as the route log keeps it. */
+/** The answer's first new agent row: what a start there reads of its machine. */
+const firstNew = (answer: Answer) => (answer.candidates as Array<Record<string, unknown>>).find(r => r.kind === 'new')!
const labels = (s: ReturnType<typeof scoped>) => (recorded(s).command.decision.candidates as Array<{ label: string }>).map(c => c.label)
describe('routeTask', () => {
@@ -91,7 +93,7 @@ describe('routeTask', () => {
rebound.state.agents = agents.map(a => a.id === 'a1' ? { ...a, harnessId: 'replacement' } : a)
const s = scoped({ tab: rebound })
const result = await routeTask(input, s, where as never, opener(id => daemon(id, { agents: ['replacement'] })), () => 'op')
- expect(result).toMatchObject({ ok: true, pick: { kind: 'member', agentId: 'a1' } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', agentId: 'a1' })]) })
expect(recorded(s).command.decision.excluded.some((c: { title: string }) => c.title.startsWith('Multiply'))).toBe(false)
})
it('shows the group\'s project instructions and notes in its answer, and still answers when they cannot be read', async () => {
@@ -105,10 +107,10 @@ describe('routeTask', () => {
expect(unread).toMatchObject({ ok: true, instructionsUnreadable: true })
expect(unread).not.toHaveProperty('instructions')
})
- it('collects members and new agents, records and returns the first in the order, and never asks Jev', async () => {
+ it('collects members and new agents, records and returns them all, and never asks Jev', async () => {
const s = scoped()
const result = await routeTask(input, s, where as never, opener(), () => 'op')
- expect(result).toMatchObject({ ok: true, routeDecisionId: 'd1', via: 'order', p: null, pick: { id: 'c0' }, warnings: ['w'] })
+ expect(result).toMatchObject({ ok: true, routeDecisionId: 'd1', via: 'instructions', p: null, candidates: expect.arrayContaining([expect.objectContaining({ id: 'c0' })]), warnings: ['w'] })
expect(s.mock.calls.map(c => c[0].action)).toEqual(['routeContext', 'routeHistory', 'instructions', 'command'])
expect(recorded(s).command.decision).not.toHaveProperty('context')
const record = recorded(s)
@@ -116,16 +118,18 @@ describe('routeTask', () => {
// The idle member Multiply is a candidate. (The idle coordinator is too: 'routing by facts', below.)
const titles = (record.command.decision.candidates as Array<{ title: string }>).map(c => c.title)
expect(titles).toContain('Multiply · Claude sonnet medium · remote-1')
- expect((result.alternatives as unknown[]).length).toBeLessThanOrEqual(2)
+ // Every recorded row is in the answer, members on the same account too: the coordinator may reuse a particular one.
+ expect((result.candidates as Array<{ id: string }>).map(r => r.id)).toEqual((record.command.decision.candidates as Array<{ id: string }>).map(c => c.id))
+ expect((result.candidates as Array<{ title: string }>).map(r => r.title)).toContain('Multiply · Claude sonnet medium · remote-1')
})
- it('ranks with the plug-ins its makers make: their reasons in the answer and the record, a failed one named in the warnings', async () => {
+ it('runs the plug-ins its makers make: their reasons in the answer and the record, a failed one named in the warnings', async () => {
const s = scoped()
const plugins: RoutePlugin[] = [{ name: 'Machine fit', adjust: c => c.kind === 'new' ? { strength: 5, reason: 'a fresh worktree here' } : null },
{ name: 'Broken', adjust: () => { throw new Error('secret') } }]
const inputs: PluginInput[] = []
const result = await routeTask(input, s, where as never, opener(), () => 'op', undefined, plugins.map(p => ({ name: p.name, make: async (i: PluginInput) => { inputs.push(i); return p } })))
- expect(result).toMatchObject({ ok: true, pick: { kind: 'new', notes: expect.arrayContaining(['Machine fit: a fresh worktree here']) },
- why: expect.stringContaining('plug-ins'), warnings: ['w', 'The routing plug-in "Broken" was skipped: it failed. The route is ranked without it.'] })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new', notes: expect.arrayContaining(['Machine fit: a fresh worktree here']) })]),
+ why: expect.stringContaining('Plug-ins'), warnings: ['w', 'The routing plug-in "Broken" was skipped: it failed. The route is shown without it.'] })
expect(labels(s)[0]).toContain('Machine fit: a fresh worktree here')
expect(JSON.stringify(result)).not.toContain('secret')
// Each maker gets the task, the route's backend read, the group's history (read once, shared) and the agent's request.
@@ -138,8 +142,8 @@ describe('routeTask', () => {
{ name: 'Nobody', make: async () => ({ name: 'Nobody', adjust: () => ({ refuse: true, reason: 'no room' }) }) },
{ name: 'Broken', make: async () => ({ name: 'Broken', candidates: () => { throw new Error('secret') } }) },
{ name: 'Maker fails', make: async () => { throw new Error('secret') } }])
- expect(none).toMatchObject({ error: 'NO_CANDIDATE', warnings: ['The routing plug-in "Maker fails" was skipped: its maker failed. The route is ranked without it.',
- 'The routing plug-in "Broken" was skipped: it failed. The route is ranked without it.'],
+ expect(none).toMatchObject({ error: 'NO_CANDIDATE', warnings: ['The routing plug-in "Maker fails" was skipped: its maker failed. The route is shown without it.',
+ 'The routing plug-in "Broken" was skipped: it failed. The route is shown without it.'],
leftOut: expect.arrayContaining([{ machine: 'remote-1', reasons: expect.arrayContaining(['Nobody: no room']) }]) })
})
it('reads instructions without notes as none, and cuts a long reason a machine is left out for', async () => {
@@ -154,10 +158,10 @@ describe('routeTask', () => {
// m1 (remote-1) has a fresh week; m2 (mac) resets in 12 hours with 60% left.
const machines = opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], usage: id === 'm2' ? reading('acct-soon', 40, 12 * 3_600_000) : reading('acct-fresh', 10, 5 * 86_400_000) }))
const plain = await routeTask(input, scoped(), where as never, machines, () => 'op', undefined, [])
- expect(plain).toMatchObject({ ok: true, pick: { title: expect.stringContaining('remote-1') } })
+ expect(plain).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ title: expect.stringContaining('remote-1') })]) })
const s = scoped()
const pulled = await routeTask(input, s, where as never, machines, () => 'op')
- expect(pulled).toMatchObject({ ok: true, pick: { title: expect.stringContaining('mac') } })
+ expect(pulled).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ title: expect.stringContaining('mac') })]) })
expect(labels(s)[0]).toContain('Window pull: its account\'s weekly window resets in 12h')
expect(JSON.stringify(pulled)).not.toContain('acct-soon')
})
@@ -186,8 +190,8 @@ describe('routeTask', () => {
const { warnings, ...rest } = await pending as Answer
const { warnings: plainWarnings, ...plainRest } = plain
expect(rest).toEqual(plainRest)
- expect(warnings).toEqual([...(plainWarnings as string[]), 'The routing plug-in "Slow" was skipped: its maker took longer than 3 s. The route is ranked without it.',
- 'The routing plug-in "Fails" was skipped: its maker failed. The route is ranked without it.'])
+ expect(warnings).toEqual([...(plainWarnings as string[]), 'The routing plug-in "Slow" was skipped: its maker took longer than 3 s. The route is shown without it.',
+ 'The routing plug-in "Fails" was skipped: its maker failed. The route is shown without it.'])
} finally { vi.useRealTimers() }
})
// A member at work is not offered; one whose task was lost is, with a note ('a member whose last task was lost').
@@ -195,16 +199,16 @@ describe('routeTask', () => {
const heavy = (needs: Record<string, unknown>) => ({ ...input, assessment: { ...input.assessment, needs: { heavy: ['build'], ...needs } } })
const reading = (resources: Record<string, unknown>) => opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], capacity: { resources, tools: { git: true }, devices: {} } }))
const disky = { memoryTotalBytes: 16e9, memoryUsedBytes: 2e9, cpuPercent: 10, projectDiskFreeBytes: 20e9 }
- const short = 'Machine fit: Short of free disk for a heavy build: it needs 8 GB memory and 30 GB disk free, so equally strong candidates that have it rank first.'
+ const short = 'Machine fit: Short of free disk for a heavy build: it needs 8 GB memory and 30 GB disk free, so prefer an equally strong candidate that has it.'
const answer = await routeTask(heavy({}), scoped(), where as never, reading(disky))
- const shown = [answer.pick, ...answer.alternatives as unknown[]] as Array<{ kind: string; notes?: string[] }>
+ const shown = answer.candidates as Array<{ kind: string; notes?: string[] }>
expect(new Set(shown.map(c => c.kind))).toEqual(new Set(['member', 'new']))
for (const c of shown) expect(c.notes).toContain(short)
const folder = { describe: async () => null, isDirectory: async () => true }
- expect(await routeTask(heavy({ cwd: '/repo' }), scoped(), where as never, reading(disky), () => 'op', folder)).toMatchObject({ ok: true, pick: { notes: expect.arrayContaining([short]) } })
+ expect(await routeTask(heavy({ cwd: '/repo' }), scoped(), where as never, reading(disky), () => 'op', folder)).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ notes: expect.arrayContaining([short]) })]) })
// A read that measured no disk says so; its new agents' starts could not verify the disk either.
const blind = await routeTask(heavy({}), scoped(), where as never, reading({ memoryTotalBytes: 16e9, memoryUsedBytes: 2e9, cpuPercent: 10 }))
- expect(blind).toMatchObject({ pick: { kind: 'member', notes: expect.arrayContaining(['Machine fit: Free disk unknown here; a heavy build: it needs 8 GB memory and 30 GB disk free.']) } })
+ expect(blind).toMatchObject({ candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', notes: expect.arrayContaining(['Machine fit: Free disk unknown here; a heavy build: it needs 8 GB memory and 30 GB disk free.']) })]) })
})
it('answers work that starts heavy CI while the account is at its limit as waiting, with when to route it again', async () => {
const base = scoped()
@@ -220,19 +224,19 @@ describe('routeTask', () => {
expect(plain).not.toHaveProperty('waiting')
})
// Lead, 10-31: a routed heavy start is never refused on the machine the route offered.
- it('ranks a machine between half the need and the need later, and the start there is admitted and counts as heavy', async () => {
+ it('notes a machine between half the need and the need, and the start there is admitted and counts as heavy', async () => {
const between = { memoryTotalBytes: 16e9, memoryUsedBytes: 10e9, cpuPercent: 10, projectDiskFreeBytes: 100e9 }
const roomy = { memoryTotalBytes: 32e9, memoryUsedBytes: 2e9, cpuPercent: 10, projectDiskFreeBytes: 100e9 }
const machines = (id: string) => daemon(id, { capacity: { resources: id === 'm1' ? between : roomy, tools: { git: true }, devices: {} } })
const heavy = { ...input, assessment: { ...input.assessment, needs: { heavy: ['build'] } } }
const noMembers = tab(); noMembers.state.agents = agents.filter(a => a.id === 'a2') as never
const answer = await routeTask(heavy, scoped({ tab: noMembers }), where as never, opener(machines))
- expect(answer).toMatchObject({ ok: true, pick: { machineId: 'm2' } })
- const later = (answer.alternatives as Array<{ machineId: string; engine: string; notes?: string[] }>).find(c => c.machineId === 'm1')!
- expect(later.notes).toContain('Machine fit: Short of free memory for a heavy build: it needs 8 GB memory and 30 GB disk free, so equally strong candidates that have it rank first.')
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ machineId: 'm2' })]) })
+ const later = (answer.candidates as Array<{ machineId: string; engine: string; notes?: string[] }>).find(c => c.machineId === 'm1')!
+ expect(later.notes).toContain('Machine fit: Short of free memory for a heavy build: it needs 8 GB memory and 30 GB disk free, so prefer an equally strong candidate that has it.')
// The start the route suggests, on that machine: its own check admits it, and later routes count it as heavy work there.
- const hint = JSON.parse(String(answer.next).replace(/^Start with: start OPERATION_ID /, '').replace(/, then assign[\s\S]*$/, ''))
- const request = { ...hint, machineId: 'm1', engine: later.engine }
+ const hint = JSON.parse(/start OPERATION_ID (\{.*\}), then/.exec(String(answer.next))![1]!)
+ const request = { ...hint, machineId: 'm1', engine: later.engine, model: 'opus', effort: 'high' }
expect(await inspectCapacity(machines('m1') as never, request)).toMatchObject({ allowed: true })
expect(request.heavy).toEqual(['build'])
expect(placedHeavyWork([{ request, requestedAt: Date.now() }], Date.now()).get('m1')).toMatchObject({ agents: 1, memoryBytes: 8e9 })
@@ -268,9 +272,9 @@ describe('routeTask', () => {
expect(result).toMatchObject({ ok: true })
expect(noted(s)).toEqual(['m1'])
expect(JSON.stringify(recorded(s).command.decision.excluded)).not.toContain('lost this task')
- // With no other machine, that account is the pick, with the note.
+ // With no other machine, that account is offered, with the note.
const alone = await route(true, ['m1'])
- expect(alone.result).toMatchObject({ ok: true, pick: { machineId: 'm1', notes: expect.arrayContaining([expect.stringContaining('Its account lost this task before')]) } })
+ expect(alone.result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ machineId: 'm1', notes: expect.arrayContaining([expect.stringContaining('Its account lost this task before')]) })]) })
})
it('remembers the failed account after its agent is stopped and removed', async () => {
expect(noted((await route(true, ['m1', 'm2'], true)).s)).toEqual(['m1'])
@@ -301,13 +305,13 @@ describe('routeTask', () => {
expect(lineOf(candidates, 'Multiply')).toContain(note)
expect(lineOf(candidates, 'Healthy')).not.toContain('lost its last task')
expect(excluded.some(e => e.title.startsWith('Multiply'))).toBe(false)
- expect(result).toMatchObject({ ok: true, pick: { kind: 'member', agentId: 'a3' } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', agentId: 'a3' })]) })
})
it('is offered with a note after its lost task is handed to another agent', async () => {
const { result, candidates } = await route([...marked, healthy],
[earlier({ id: 'y', agentId: 'a3', status: 'working' }, { lostAttempt: { id: 'x', agentId: 'a1' } })])
expect(lineOf(candidates, 'Multiply')).toContain(note)
- expect(result).toMatchObject({ ok: true, pick: { kind: 'member', agentId: 'a1', notes: [note] } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', agentId: 'a1', notes: [note] })]) })
})
it('carries no note once it finished a new task, which clears its mark', async () => {
const { candidates } = await route([...agents, healthy],
@@ -337,7 +341,7 @@ describe('routeTask', () => {
const ruled = tab(); (ruled.state as Record<string, unknown>).rules = [{ id: 'r1', rule: { kind: 'forbidModel', model: 'sonnet' }, text: 'No Sonnet.' }, { id: 'r2', text: 7 }]
const s = scoped({ tab: ruled })
const result = await routeTask(input, s, where as never, opener(), () => 'op')
- expect(result).toMatchObject({ ok: true, pick: { model: 'sonnet' } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ model: 'sonnet' })]) })
const decision = recorded(s).command.decision
expect(decision.candidates.some((c: { model: string }) => c.model === 'sonnet')).toBe(true)
expect(JSON.stringify(decision)).not.toContain('Breaks the owner')
@@ -378,8 +382,8 @@ describe('routeTask', () => {
const s = scoped({ context })
const result = await routeTask(input, s, where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [],
engines: [{ engine: 'claude', installed: true, signedIn: true }, { engine: 'codex', installed: true, signedIn: true }] })), () => 'op')
- // The idle Claude Opus agent is a candidate at once; Codex's top tier, cheaper, ranks first.
- expect(result).toMatchObject({ ok: true, pick: { kind: 'new', engine: 'codex' } })
+ // The idle Claude Opus agent is a candidate at once, beside Codex's top tier.
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new', engine: 'codex' })]) })
const decision = recorded(s).command.decision
expect(decision.candidates.map((c: { title: string }) => c.title)).toContain('Multiply · Claude opus high · remote-1')
expect(decision.why).not.toMatch(/same-engine/)
@@ -405,7 +409,7 @@ describe('routeTask', () => {
const result = await routeTask(input, s, where as never, opener(), () => 'op')
return { result, decision: 'error' in result ? null : recorded(s).command.decision }
}
- const opusNow = { ok: true, pick: { engine: 'claude', model: 'opus', machineId: 'm1' } }
+ const opusNow = { ok: true, candidates: expect.arrayContaining([expect.objectContaining({ engine: 'claude', model: 'opus', machineId: 'm1' })]) }
it('starts Claude Opus at once for a Claude build while Codex is out of quota for days, with no note', async () => {
const { result, decision } = await routeWith(pool('m2', ['codex'], { usedPercent: 100, resetsIn: 3 * DAY }))
@@ -419,40 +423,43 @@ describe('routeTask', () => {
expect(JSON.stringify(decision.excluded)).not.toMatch(/another engine/)
})
})
- // Project instructions, phase 4: strength ranks, it does not filter. The idle Sonnet member is offered below the top tier.
- it('ranks an idle Sonnet member below the top tier, and tells the server when a person named the model', async () => {
+ // Project instructions, phase 4: strength does not filter. The idle Sonnet member is offered beside the top tier.
+ it('offers an idle Sonnet member beside the top tier, and tells the server when a person named the model', async () => {
const s = scoped({ policy: floorPolicy })
- expect(await routeTask(input, s, where as never, opener(), () => 'op')).toMatchObject({ ok: true, pick: { kind: 'new', model: 'opus' } })
+ expect(await routeTask(input, s, where as never, opener(), () => 'op')).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new', model: 'opus' })]) })
expect(recorded(s).command.decision.candidates).toEqual(expect.arrayContaining([expect.objectContaining({ title: 'Multiply · Claude sonnet medium · remote-1', quality: 2 })]))
expect(JSON.stringify(recorded(s).command.decision.excluded)).not.toContain('rated 3')
const named = scoped({ policy: floorPolicy })
expect(await routeTask({ ...input, assessment: { ...input.assessment, model: 'sonnet' } }, named, where as never, opener(), () => 'op'))
- .toMatchObject({ ok: true, pick: { kind: 'member', agentId: 'a1' } })
+ .toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', agentId: 'a1' })]) })
expect(recorded(named).command.decision.assessment).toMatchObject({ model: 'sonnet' })
})
it('tells the agent how to assign a member or start a new agent with the decision', async () => {
const member = await routeTask(input, scoped(), where as never, opener(), () => 'op')
- // Cheapest first: the member on sonnet.
- expect(member).toMatchObject({ pick: { kind: 'member', agentId: 'a1' } })
- expect(member.next).toContain('"type":"work.assign","conversationId":"g1","agentId":"a1","routeDecisionId":"d1"')
+ expect(member).toMatchObject({ candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', agentId: 'a1' })]) })
+ // The chosen row's agent and the Routing rule that chose it: the route names none (task #2901).
+ expect(member.next).toContain('"type":"work.assign","conversationId":"g1","agentId":"AGENT","routeDecisionId":"d1","overrideReason":"RULE"')
const fresh = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high' } }, scoped({ policy: floorPolicy }), where as never, opener(), () => 'op')
- expect(fresh).toMatchObject({ pick: { kind: 'new', engine: 'claude', model: 'opus', effort: 'high' } })
- expect(fresh.next).toContain('"engine":"claude","model":"opus","effort":"high","routeDecisionId":"d1"')
+ expect(fresh).toMatchObject({ candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new', engine: 'claude', model: 'opus', effort: 'high' })]) })
+ expect(fresh.next).toContain('"machineId":"MACHINE","engine":"ENGINE","model":"MODEL","effort":"EFFORT","routeDecisionId":"d1","overrideReason":"RULE"')
// Without a branch the agent starts from the default one, and the hint says how to choose another.
expect(fresh.next).toContain('"branchRef":"refs/remotes/origin/BRANCH"')
expect(fresh.next).toContain('default branch, fetched first')
// A complete start: every field its schema requires, with the defaults the help gives.
const hint = JSON.parse(/start OPERATION_ID (\{.*\}), then/.exec(fresh.next as string)![1]!)
- expect(hint).toEqual({ conversationId: 'g1', name: 'NAME', roleName: 'ROLE', cwd: '/absolute/repo/on/that/machine', worktree: true,
+ expect(hint).toEqual({ conversationId: 'g1', name: 'NAME', roleName: 'ROLE', cwd: 'CWD', worktree: true,
requirements: { memoryBytes: 2147483648, diskBytes: 10737418240, maxCpuPercent: 100, tools: ['git'], devices: [], quotaRequired: false },
- machineId: 'm2', engine: 'claude', model: 'opus', effort: 'high', routeDecisionId: 'd1' })
+ machineId: 'MACHINE', engine: 'ENGINE', model: 'MODEL', effort: 'EFFORT', routeDecisionId: 'd1', overrideReason: 'RULE' })
+ // Each new agent's row says the folder it starts in.
+ for (const row of (fresh.candidates as Array<{ kind: string; cwd?: string }>).filter(r => r.kind === 'new')) expect(row.cwd).toBe('/absolute/repo/on/that/machine')
// The task's own repository, when the assessment named one, and no decision when none was recorded.
const placed = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high', needs: { cwd: '/repo/api' } } },
scoped({ record: { error: 'BACKEND_UNAVAILABLE' }, policy: floorPolicy }), where as never, opener(), () => 'op')
- expect(JSON.parse(/start OPERATION_ID (\{.*\}), then/.exec(placed.next as string)![1]!)).toMatchObject({ cwd: '/repo/api' })
+ expect((placed.candidates as Array<{ kind: string; cwd?: string }>).find(r => r.kind === 'new')).toMatchObject({ cwd: '/repo/api' })
expect(placed.next).not.toContain('routeDecisionId')
+ expect(placed.next).not.toContain('RULE')
})
- it('admits the pick on the requirements its start hint asks for, with the task\'s tools and devices', async () => {
+ it('admits a candidate on the requirements its start hint asks for, with the task\'s tools and devices', async () => {
const needs = { tools: ['git', 'docker'], devices: ['/dev/ttyUSB0'] }
const hard = { ...input, assessment: { ...input.assessment, difficulty: 'high', needs } }
const daemons: ReturnType<typeof daemon>[] = []
@@ -474,7 +481,7 @@ describe('routeTask', () => {
return d
})
const result = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high' } }, scoped({ policy: floorPolicy }), where as never, make, () => 'op')
- expect(result).toMatchObject({ ok: true, pick: { kind: 'new' } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new' })]) })
})
it('warns when the account\'s machines could not be read, and still offers the Lead\'s own machine', async () => {
const context = { ok: true, value: { agentId: 'lead', tab: tab(), policy: { policy, warnings: ['w'] }, machines: [], machinesUnreadable: true } }
@@ -505,7 +512,7 @@ describe('routeTask', () => {
const os = 'Plan 9'
const plan9 = opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], capacity: { resources: { memoryTotalBytes: 8e9, memoryUsedBytes: 1e9, cpuPercent: 10, projectDiskFreeBytes: 1e11, os }, tools: { git: true }, devices: {} } }))
const s = scoped()
- await withBlocked(os, async () => expect(await routeTask(input, s, where, plan9)).toMatchObject({ ok: true, pick: { kind: 'member' } }))
+ await withBlocked(os, async () => expect(await routeTask(input, s, where, plan9)).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member' })]) }))
expect(recorded(s).command.decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({ title: expect.stringContaining('New agent'),
reason: expect.stringContaining('Swarm agents do not run on Plan 9 yet.') })]))
})
@@ -600,14 +607,14 @@ describe('routeTask', () => {
})
it('names a member that has no name, model or effort of its own, and leaves the decision blank when it is unrecorded', async () => {
const plain = tab(); plain.state.agents = [{ id: 'a1', machineId: 'm1', harnessId: 'h1', configuration: { engine: 'claude' } }, agents[1]] as never
- // A member launched on Claude's own model ranks first where the catalog rates that model 3; with no row it is unrated, at 1.
+ // A member launched on Claude's own model is rated 3 where the catalog rates that model 3; with no row it is unrated, at 1.
const options = { tab: plain, record: { error: 'BACKEND_UNAVAILABLE' }, policy: floorPolicy }
const rated = { ...options, policy: { ...floorPolicy, models: [...floorPolicy.models, { engine: 'claude', model: 'default', effort: 'default', quality: 3, cost: 1, enabled: true }] } }
const easy = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'low' } }, scoped(rated), where as never, opener())
- expect(easy).toMatchObject({ unrecorded: true, pick: { kind: 'member', title: 'Member · Claude default default · remote-1' } })
+ expect(easy).toMatchObject({ unrecorded: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', title: 'Member · Claude default default · remote-1' })]) })
expect(easy.next).not.toContain('routeDecisionId')
const hard = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high' } }, scoped(options), where as never, opener())
- expect(hard).toMatchObject({ unrecorded: true, pick: { kind: 'new' } })
+ expect(hard).toMatchObject({ unrecorded: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new' })]) })
expect(hard.next).not.toMatch(/routeDecisionId"|same routeDecisionId/)
})
it('returns a record refusal as an error, and only a transport failure as unrecorded', async () => {
@@ -630,21 +637,21 @@ describe('routeTask', () => {
const s = scoped()
const open = vi.fn(async () => { throw Object.assign(new Error('gone'), { code: 'MACHINE_UNAVAILABLE' }) })
const result = await routeTask(input, s, where as never, open as never)
- expect(result).toMatchObject({ ok: true, pick: { kind: 'member', agentId: 'a1' } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', agentId: 'a1' })]) })
const decision = recorded(s).command.decision
- // The two members there, the idle coordinator among them.
- expect(decision.candidates.map((c: { agentId?: string }) => c.agentId)).toEqual(['a1', 'lead'])
+ // The two members there, the idle coordinator among them, by title.
+ expect(decision.candidates.map((c: { agentId?: string }) => c.agentId)).toEqual(['lead', 'a1'])
// New agents there stay excluded: nothing can start on a machine nobody can open.
expect(decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({ reason: 'Machine is offline or unreachable.' })]))
expect(decision.excluded.some((e: { title: string }) => e.title.startsWith('Multiply'))).toBe(false)
})
- it('ranks a member whose quota is known before one on a machine that cannot be read, and shows both', async () => {
+ it('shows a member whose quota is known and one on a machine that cannot be read', async () => {
const two = tab(); two.state.agents = [...agents, { id: 'a2', name: 'Collab', machineId: 'theirs', harnessId: 'h2', configuration: { engine: 'claude', model: 'sonnet', effort: 'medium' } }] as never
const s = scoped({ tab: two })
const open = vi.fn(async (_w: unknown, id: string) => id === 'theirs' ? Promise.reject(new Error('not yours')) : daemon(id, { agents: id === 'm1' ? ['h1'] : [] })) as never
// theirs is not in the account's list, m1 is; the collaborator's member there has an unknown quota.
const result = await routeTask(input, s, where as never, open)
- expect(result).toMatchObject({ ok: true, pick: { agentId: 'a1' } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ agentId: 'a1' })]) })
const titles = (recorded(s).command.decision.candidates as Array<{ title: string }>).map(c => c.title)
expect(titles.indexOf('Multiply · Claude sonnet medium · remote-1')).toBeLessThan(titles.indexOf('Collab · Claude sonnet medium · theirs'))
expect(JSON.stringify(recorded(s).command.decision.excluded)).not.toContain('Collab')
@@ -688,7 +695,7 @@ describe('routeTask', () => {
const result = await routeTask(input, s, where as never, opener(), () => 'op')
// 60% left less the 10% reserve and the 45% the open pick holds leaves 5% for a task that needs 30%.
expect(recorded(s).command.decision.candidates.every((c: { fit: { status: string; account: string } }) => c.fit.status === 'short' && c.fit.account === 'acct')).toBe(true)
- expect(result.warnings).toEqual(['w', expect.stringMatching(/^No candidate is expected to cover this task; its 5-hour quota is expected to run out partway and resets in 3h\.$/)])
+ expect(result.warnings).toEqual(['w', NONE_COVERS])
})
it('keeps a queued start in the reroute quota hold until its linked work finishes', async () => {
const queued = { id: 'queued', conversationId: 'g1', account: 'acct', spend: { '5-hour': 45 }, size: 'medium',
@@ -704,13 +711,16 @@ describe('routeTask', () => {
})
it('records again in the shape an older backend knows when it refuses the new fields as invalid', async () => {
const s = scoped(), base = s.getMockImplementation()!
- let refused = 0
- s.mockImplementation(async payload => payload.action === 'command' && !refused++ ? { error: 'VALIDATION_ERROR', detail: 'decision.candidates.0: Unrecognized key: "fit"', status: 400 } : base(payload))
+ s.mockImplementation(async payload => payload.action === 'command' && JSON.stringify(payload.command).includes('"fit"')
+ ? { error: 'VALIDATION_ERROR', detail: 'decision.candidates.0: Unrecognized key: "fit"', status: 400 } : base(payload))
expect(await routeTask(input, s, where as never, opener(), () => 'op')).toMatchObject({ ok: true, routeDecisionId: 'd1' })
- const [phase1, v1] = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0])
- expect(phase1.command.decision.assessment.size).toBe('medium')
+ // With no pick, then with c0 standing in for one (task #2901), then in the shape from before phase 1.
+ const [current, phase1, v1] = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0])
+ expect(current.command.decision).not.toHaveProperty('pick')
+ expect(phase1.command.decision).toMatchObject({ pick: 'c0', assessment: { size: 'medium' } })
expect(phase1.command.decision.candidates[0]).toHaveProperty('fit')
expect(v1.operationId).toBe(phase1.operationId)
+ expect(v1.command.decision).toMatchObject({ pick: 'c0', via: 'order' })
expect(v1.command.decision.assessment).not.toHaveProperty('size')
expect(v1.command.decision.candidates.some((c: object) => 'fit' in c)).toBe(false)
})
@@ -730,28 +740,30 @@ describe('routeTask', () => {
}
const beforeKinds = refusing(['kind":"docs'])
expect(await routeTask(kinded, beforeKinds, where as never, opener(), () => 'op')).toMatchObject({ ok: true, routeDecisionId: 'd1' })
- expect(commands(beforeKinds).map(a => Object.keys(a))).toEqual([['difficulty', 'risk', 'why', 'size', 'kind'], ['difficulty', 'risk', 'why', 'size']])
+ const kind = ['difficulty', 'risk', 'why', 'size', 'kind']
+ // Each refusal of the record with no pick tries it once more with c0 as the pick, the shape a backend from before task #2901 takes.
+ expect(commands(beforeKinds).map(a => Object.keys(a))).toEqual([kind, kind, ['difficulty', 'risk', 'why', 'size']])
const beforePhase1 = refusing(['kind":"docs', 'size'])
expect(await routeTask(kinded, beforePhase1, where as never, opener(), () => 'op')).toMatchObject({ ok: true, routeDecisionId: 'd1' })
- expect(commands(beforePhase1).map(a => Object.keys(a))).toEqual([['difficulty', 'risk', 'why', 'size', 'kind'], ['difficulty', 'risk', 'why', 'size'], ['difficulty', 'risk', 'why']])
+ expect(commands(beforePhase1).map(a => Object.keys(a))).toEqual([kind, kind, ['difficulty', 'risk', 'why', 'size'], ['difficulty', 'risk', 'why']])
// A task with no kind never needs the extra try.
const plain = refusing(['size'])
await routeTask(input, plain, where as never, opener(), () => 'op')
- expect(commands(plain)).toHaveLength(2)
+ expect(commands(plain)).toHaveLength(3)
})
it('still routes when recording fails or the connection is lost', async () => {
const result = await routeTask(input, scoped({ record: { error: 'BACKEND_UNAVAILABLE' } }), where as never, opener())
- expect(result).toMatchObject({ ok: true, via: 'order', unrecorded: true })
+ expect(result).toMatchObject({ ok: true, via: 'instructions', unrecorded: true })
expect(result).not.toHaveProperty('routeDecisionId')
const lost = await routeTask(input, scoped({ recordThrows: true }), where as never, opener())
- expect(lost).toMatchObject({ ok: true, via: 'order', unrecorded: true })
+ expect(lost).toMatchObject({ ok: true, via: 'instructions', unrecorded: true })
})
- it('says when the pick was the only candidate that can run the task', async () => {
+ it('says when one candidate is the only one that can run the task', async () => {
const s = scoped()
// Only the member's machine answers, and its engine is not installed for a new agent.
const open = vi.fn(async (_w: unknown, id: string) => id === 'm1'
? daemon(id, { agents: ['h1'], engines: [{ engine: 'claude', installed: false }] }) as never : Promise.reject(new Error('gone')))
- expect(await routeTask(input, s, where as never, open as never)).toMatchObject({ ok: true, via: 'only', pick: { agentId: 'a1' } })
+ expect(await routeTask(input, s, where as never, open as never)).toMatchObject({ ok: true, via: 'only', candidates: expect.arrayContaining([expect.objectContaining({ agentId: 'a1' })]) })
})
it('refuses an invalid assessment, an unknown group and a failed context read', async () => {
const open = vi.fn()
@@ -836,6 +848,64 @@ describe('routeTask', () => {
})
})
+// Ken, 2026-11-04 (task #2901): PMs took the route's pick, nearly always Opus or Astra, against the project's Routing
+// instructions. The answer lists the candidates by machine with every fact, names none, and says how to start the chosen one.
+describe('route answers with no pick (task #2901)', () => {
+ const weekly = { providers: [{ provider: 'claude', outcome: 'answered', httpStatus: 200, account: 'acct', body: {
+ five_hour: { utilization: 40, resets_at: new Date(Date.now() + 3 * 3_600_000).toISOString() },
+ seven_day: { utilization: 25, resets_at: new Date(Date.now() + 4 * 86_400_000 + 30 * 60_000).toISOString() } } }] }
+ const both = () => opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], usage: weekly }))
+ type Row = { id: string; kind: string; machineId: string; title: string; quota: string; cwd?: string }
+
+ it('lists every candidate by machine, records each with no pick, and sends the choice to the Routing instructions', async () => {
+ const s = scoped()
+ const answer = await routeTask(input, s, where as never, both(), () => 'op')
+ expect(answer).toMatchObject({ ok: true, routeDecisionId: 'd1', via: 'instructions', p: null })
+ expect(answer).not.toHaveProperty('pick')
+ expect(answer).not.toHaveProperty('alternatives')
+ expect(answer.why).toContain('Routing instructions')
+ const rows = answer.candidates as Row[]
+ // mac (m2) before remote-1 (m1), whatever is stronger or cheaper.
+ const machines = rows.map(r => r.title.split(' · ').at(-1)!)
+ expect(machines).toEqual([...machines].sort((x, y) => x.localeCompare(y)))
+ expect(new Set(machines)).toEqual(new Set(['mac', 'remote-1']))
+ expect(rows[0]!.machineId).toBe('m2')
+ const decision = recorded(s).command.decision
+ expect(decision).not.toHaveProperty('pick')
+ expect(decision).toMatchObject({ via: 'instructions', why: answer.why })
+ // Any candidate the coordinator chooses is a recorded one.
+ const ids = new Set((decision.candidates as Array<{ id: string }>).map(c => c.id))
+ for (const row of rows) expect(ids.has(row.id)).toBe(true)
+ })
+ it('carries each candidate\'s weekly quota left and its reset, and a new agent\'s folder on its machine', async () => {
+ const answer = await routeTask(input, scoped(), where as never, both(), () => 'op')
+ const rows = answer.candidates as Row[]
+ expect(rows.length).toBeGreaterThan(1)
+ for (const row of rows) expect(row.quota).toMatch(/^fits: weekly 75% left, resets in 4d(1h)?$/)
+ for (const row of rows.filter(r => r.kind === 'new')) expect(row.cwd).toBe('/absolute/repo/on/that/machine')
+ })
+ it('says how to start or assign the chosen candidate, with the decision and the rule that chose it', async () => {
+ const answer = await routeTask(input, scoped(), where as never, both(), () => 'op')
+ const next = String(answer.next)
+ expect(next).toContain('"type":"work.assign","conversationId":"g1","agentId":"AGENT","routeDecisionId":"d1","overrideReason":"RULE"')
+ const hint = JSON.parse(/start OPERATION_ID (\{.*?\}), then/.exec(next)![1]!)
+ expect(hint).toMatchObject({ conversationId: 'g1', machineId: 'MACHINE', engine: 'ENGINE', model: 'MODEL', effort: 'EFFORT', routeDecisionId: 'd1', overrideReason: 'RULE' })
+ expect(next).toContain('Routing instructions')
+ expect(next).not.toMatch(/\bpick\b/)
+ })
+ it('records with c0 as the pick for a backend from before this, which takes a record only with one', async () => {
+ const s = scoped(), base = s.getMockImplementation()!
+ s.mockImplementation(async payload => payload.action === 'command' && !('pick' in payload.command.decision)
+ ? { error: 'VALIDATION_ERROR', detail: 'decision.pick: Required', status: 400 } : base(payload))
+ expect(await routeTask(input, s, where as never, both(), () => 'op')).toMatchObject({ ok: true, routeDecisionId: 'd1', via: 'instructions' })
+ const [current, picked] = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0])
+ expect(current.command.decision).not.toHaveProperty('pick')
+ expect(picked.command.decision).toMatchObject({ pick: 'c0', via: 'order' })
+ expect(picked.operationId).toBe(current.operationId)
+ expect(picked.command.decision.candidates).toEqual(current.command.decision.candidates)
+ })
+})
+
describe('what the route log says about each candidate', () => {
const git = (patch: Record<string, unknown> = {}) => ({ kind: 'git', name: 'api', cwd: '/w/api', root: '/w/api', remote: 'github.com/acme/api', branch: 'main', ...patch })
/** The Lead's machine, as the folder reader sees it: the folder is there (unless said otherwise) and the SCM describes it. */
@@ -1059,7 +1129,7 @@ describe('routing contributed capacity', () => {
it('routes using owner measurements and the contributed project without opening that machine', async () => {
const { answer } = await runPool(healthy())
expect(answer.ok).toBe(true)
- expect(answer.next).toContain('/owner/project')
+ expect(JSON.stringify(answer.candidates)).toContain('"cwd":"/owner/project"')
const member = await runPool(healthy(), true)
expect(member.answer.ok).toBe(true)
})
@@ -1102,20 +1172,20 @@ describe('routing contributed capacity', () => {
const now = Date.now(), pool = healthy(); Object.assign(pool.observation.resources, { projectDiskFreeBytes: 70e9 })
const heavy = { id: 'h', request: { machineId: 'm1', heavy: ['build'], requirements: { memoryBytes: 4 * GiB, diskBytes: 15 * GiB } }, requestedAt: now - 60_000, error: null }
const { answer } = await runPool(pool, false, { heavy: ['build'] }, undefined, { state: { starts: [heavy] } })
- expect((answer.pick as { notes?: string[] }).notes ?? []).not.toEqual(expect.arrayContaining([expect.stringContaining('Machine fit')]))
+ expect(JSON.stringify(answer.candidates)).not.toContain('Machine fit')
})
it('says on each row what its machine has: free slots, free memory less what starts hold, and free disk', async () => {
const pool = { ...healthy(), availableSlots: 3 }
const { answer } = await runPool(pool, false, {}, undefined, { state: { starts: starting(Date.now()) } })
- expect((answer.pick as { machine: string }).machine).toBe('3 slots free · 24.6 GB memory free (5.4 GB held by starts) · 196.8 GB disk free')
+ expect((firstNew(answer) as { machine: string }).machine).toBe('3 slots free · 24.6 GB memory free (5.4 GB held by starts) · 196.8 GB disk free')
const plain = await runPool({ ...healthy(), availableSlots: 1 })
- expect((plain.answer.pick as { machine: string }).machine).toBe('1 slot free · 30.0 GB memory free · 200.0 GB disk free')
+ expect((firstNew(plain.answer) as { machine: string }).machine).toBe('1 slot free · 30.0 GB memory free · 200.0 GB disk free')
})
it('judges heavy work by the contributed machine\'s free memory, disk and CPU, for members too, and its start says it is heavy', async () => {
const pool = healthy(); Object.assign(pool.observation.resources, { memoryUsedBytes: 26e9, cpuPercent: 92 })
const { answer } = await runPool(pool, true, { heavy: ['build'] })
- const short = 'Machine fit: Short of free memory for a heavy build: it needs 8 GB memory and 30 GB disk free, so equally strong candidates that have it rank first. Its CPU is busy.'
- const shown = [answer.pick, ...answer.alternatives as unknown[]] as Array<{ kind: string; notes?: string[] }>
+ const short = 'Machine fit: Short of free memory for a heavy build: it needs 8 GB memory and 30 GB disk free, so prefer an equally strong candidate that has it. Its CPU is busy.'
+ const shown = answer.candidates as Array<{ kind: string; notes?: string[] }>
expect(new Set(shown.map(c => c.kind))).toEqual(new Set(['member', 'new']))
for (const c of shown) expect(c.notes).toContain(short)
expect((await runPool(healthy(), false, { heavy: ['build'] })).answer.next).toContain('"requirements":{"memoryBytes":4000000000,"diskBytes":15000000000')
@@ -1123,15 +1193,15 @@ describe('routing contributed capacity', () => {
expect((await runPool(healthy(), false)).answer.next).not.toContain('heavy')
// A reading with no CPU says nothing of it, and a machine that has what it needs says nothing at all.
const roomy = await runPool(healthy(), true, { heavy: ['build'] })
- expect((roomy.answer.pick as { notes?: string[] }).notes ?? []).not.toEqual(expect.arrayContaining([expect.stringContaining('Machine fit')]))
+ expect(JSON.stringify(roomy.answer.candidates)).not.toContain('Machine fit')
})
// Review of #2426 (privacy): every reader of the route log reads the reasons, also for a machine the route shows nothing else
// of. A paused machine offers no new agent, so its reading was never shown; its member's reason must not show it either.
it('never shows a paused machine\'s measured memory, disk or CPU in its member\'s reason, the answer or the record', async () => {
const pool = { ...healthy(), paused: true }; Object.assign(pool.observation.resources, { memoryUsedBytes: 26e9, cpuPercent: 92 })
const { answer, s } = await runPool(pool, true, { heavy: ['build'] })
- expect(answer).toMatchObject({ ok: true, pick: { kind: 'member', notes: expect.arrayContaining([
- 'Machine fit: Short of free memory for a heavy build: it needs 8 GB memory and 30 GB disk free, so equally strong candidates that have it rank first. Its CPU is busy.']) } })
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', notes: expect.arrayContaining([
+ 'Machine fit: Short of free memory for a heavy build: it needs 8 GB memory and 30 GB disk free, so prefer an equally strong candidate that has it. Its CPU is busy.']) })]) })
for (const text of [JSON.stringify(answer), JSON.stringify(recorded(s).command.decision)]) {
for (const measured of ['6.0 GB', '200.0 GB', '92%', '6 GB', '200 GB']) expect(text).not.toContain(measured)
}
@@ -1140,7 +1210,7 @@ describe('routing contributed capacity', () => {
const pool = healthy()
pool.engines = ['opencode']
const { answer, s } = await runPool(pool)
- expect(answer).toMatchObject({ ok: true, pick: { engine: 'claude' } })
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ engine: 'claude' })]) })
expect(recorded(s).command.decision.candidates.every((c: { engine: string }) => c.engine === 'claude')).toBe(true)
})
it('keeps a healthy contributed member pickable', async () => {
@@ -1176,7 +1246,7 @@ describe('routing contributed capacity', () => {
it('withholds a contributed member absent from an explicit running-terminal list', async () => {
const pool = healthy(); pool.observation.runningHarnessIds = []
const { answer, s } = await runPool(pool, true)
- expect(answer).toMatchObject({ ok: true, pick: { kind: 'new' } })
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new' })]) })
expect(recorded(s).command.decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({ title: expect.stringContaining('Multiply'),
reason: 'Its terminal is not running.' })]))
})
@@ -1187,7 +1257,7 @@ describe('routing contributed capacity', () => {
const pool = healthy(); pool.observation.runningHarnessIds = []
Object.assign(pool.observation, { stoppedHarnessIds: ['h1'], closedHarnessIds: closed })
const { answer, s } = await runPool(pool, true)
- expect(answer).toMatchObject({ ok: true, pick: { kind: 'new' } })
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new' })]) })
expect(recorded(s).command.decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({ title: expect.stringContaining('Multiply'), reason })]))
}
})
@@ -1208,9 +1278,9 @@ describe('routing contributed capacity', () => {
const project = { id: 'project-two', repository: { machineId: 'other', cwd: '/elsewhere', repositoryUrl: 'https://github.com/example/two' } }
expect((await runPool(healthy(), false, {}, project)).answer.ok).not.toBe(true)
const shared = { ...healthy(), scope: 'swarm', cwd: '/swarm-root' }
- expect((await runPool(shared, false, {}, project)).answer.next).toContain('/swarm-root/project-two')
+ expect(JSON.stringify((await runPool(shared, false, {}, project)).answer.candidates)).toContain('"cwd":"/swarm-root/project-two"')
project.repository.machineId = 'm1'
- expect((await runPool(shared, false, {}, project)).answer.next).toContain('/elsewhere')
+ expect(JSON.stringify((await runPool(shared, false, {}, project)).answer.candidates)).toContain('"cwd":"/elsewhere"')
expect((await runPool(shared, false, {}, { id: 'project-two' })).answer.ok).not.toBe(true)
expect((await runPool(shared)).answer.ok).not.toBe(true)
})
@@ -1234,7 +1304,7 @@ describe('routing contributed capacity', () => {
const { answer } = await runPool(plan9)
expect(answer).toMatchObject({ error: 'NO_CANDIDATE' })
expect(reasons(answer)[0]!.reason).toContain('Swarm agents do not run on Plan 9 yet')
- expect((await runPool(plan9, true)).answer).toMatchObject({ ok: true, pick: { kind: 'member' } })
+ expect((await runPool(plan9, true)).answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member' })]) })
})
})
@@ -1243,7 +1313,7 @@ describe('routing contributed capacity', () => {
for (const members of [false, true]) {
const onWindows = (await runPool(windows, members)).answer
expect(onWindows.ok).toBe(true)
- expect(onWindows.pick).toEqual((await runPool(healthy(), members)).answer.pick)
+ expect(onWindows.candidates).toEqual((await runPool(healthy(), members)).answer.candidates)
}
})
@@ -1293,7 +1363,7 @@ describe('routing contributed capacity', () => {
const grid = 'swarm-0123456789ab', pool = swarm(undefined, [{ engine: 'claude', installed: true, signedIn: false }])
pool.observation.localModels = [{ grid, model: 'qwen3' }]
const { answer, s } = await runPool(pool, false, {}, project, { state: { localModels: { grid, enabled: true } }, kind: 'tests' })
- expect(answer).toMatchObject({ ok: true, pick: { gridModel: 'qwen3' } })
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ gridModel: 'qwen3' })]) })
expect(recorded(s).command.decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({ reason: expect.stringContaining('not signed in') })]))
})
@@ -1338,7 +1408,7 @@ describe('routing contributed capacity', () => {
const start = (extra: Record<string, unknown>) => ({ id: `s${Math.random()}`, request: { machineId: 'm1' }, harnessId: null, dispatched: false, error: null, ...extra })
const failed = start({ error: 'Claude Code is not signed in.' }), queued = start({}), started = start({ harnessId: 'h9', dispatched: true })
const stuck = await runPool(healthy(), true, {}, undefined, { state: { starts: [started, failed, queued] } })
- expect(stuck.answer).toMatchObject({ ok: true, pick: { kind: 'member' } })
+ expect(stuck.answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member' })]) })
const rows = lines(stuck.s)
expect(rows.filter(r => r.title.startsWith('New agent')).every(r => r.label.includes('last 2 starts'))).toBe(true)
expect(rows.find(r => r.title.startsWith('Multiply'))!.label).not.toContain('last 2 starts')
@@ -1380,7 +1450,7 @@ describe('routing contributed capacity', () => {
})
it('routes elsewhere, with the note, while the required machine has no free slot', async () => {
const full = await route(two(p => { p.availableSlots = 0 }), { machines: ['m3'] })
- expect(full.answer).toMatchObject({ ok: true, pick: { machineId: 'm1', notes: expect.arrayContaining([ELSEWHERE]) } })
+ expect(full.answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ machineId: 'm1', notes: expect.arrayContaining([ELSEWHERE]) })]) })
})
it('notes every machine when the required one is one the agent cannot see', async () => {
const { answer, s } = await route(two(), { machines: [], unseenMachines: 1 })
@@ -1426,7 +1496,7 @@ describe('routing contributed capacity', () => {
const s = scoped({ tab: { revision: 3, state: { id: 'tab', agents, conversations: groups } } })
const make = opener(id => daemon(id, { devices: { '/dev/cu.usbmodem1': id === 'm2', '/dev/ttyUSB0': true } }))
const answer = await routeTask({ ...input, assessment: { ...input.assessment, needs: { devices: ['/dev/ttyUSB0'] } } }, s, where as never, make, () => 'op')
- expect(answer).toMatchObject({ ok: true, pick: { machineId: 'm2' } })
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ machineId: 'm2' })]) })
const hint = JSON.parse(/start OPERATION_ID (\{.*\}), then/.exec(answer.next as string)![1]!)
expect(hint.requirements.devices).toEqual(['/dev/ttyUSB0', '/dev/cu.usbmodem1'])
})
@@ -1451,7 +1521,7 @@ describe('routing contributed capacity', () => {
expect((await runPool(p)).answer.ok).toBe(true)
expect((await runPool({ ...p, observation: {} }, true)).answer.ok).not.toBe(true)
})
- it('lists API-key machines beside a subscription one, and offers the best row of every other machine as an alternative', async () => {
+ it('lists API-key machines beside a subscription one, a row for every engine of every machine', async () => {
const keyed = (machineId: string) => ({ ...healthy(), machineId, name: `Keyed ${machineId}`, observation: { ...healthy().observation, runningHarnessIds: [],
quotas: [{ engine: 'claude', known: true, windows: [] }] } })
// The subscription machine has two engines, so its two best rows come before any other machine's.
@@ -1462,15 +1532,14 @@ describe('routing contributed capacity', () => {
const s = scoped({ context: { ok: true, value: { agentId: 'lead', tab: { state: { id: 'tab', agents: [], conversations: conversations(), machines: [subscription, keyed('m2'), keyed('m3')] } },
policy: { policy: enabled, warnings: [] }, machines: [] } } })
const answer = await routeTask(input, s, where, opener())
- expect(answer).toMatchObject({ ok: true, pick: { machineId: 'm1', engine: 'codex' } })
- expect((answer.alternatives as Array<{ machineId: string; engine: string }>).map(x => [x.machineId, x.engine])).toEqual([['m1', 'claude'], ['m2', 'claude'], ['m3', 'claude']])
+ const rows = answer.candidates as Array<{ machineId: string; engine: string; quota: string }>
+ expect(new Set(rows.map(x => `${x.machineId} ${x.engine}`))).toEqual(new Set(['m1 claude', 'm1 codex', 'm2 claude', 'm3 claude']))
// Each row says its account's weekly quota, which the project's order picks by (Ken, 2026-11-03).
- expect((answer.pick as { quota: string }).quota).toBe('fits: weekly 80% left, resets in 5d')
- expect((answer.alternatives as Array<{ quota: string }>).map(x => x.quota)).toEqual(['fits: weekly 80% left, resets in 5d', 'metered', 'metered'])
+ for (const row of rows) expect(row.quota).toBe(row.machineId === 'm1' ? 'fits: weekly 80% left, resets in 5d' : 'metered')
})
// The coordinator picks by the project's order among accounts, so every account is an alternative, once: a Claude account with
// 99% left on a machine whose Codex was used up never reached it (Ken, 2026-11-03).
- it('offers the best row of every engine on every machine as an alternative, and no second row of an account', async () => {
+ it('offers a row of every engine on every machine, with its weekly quota', async () => {
const week = (usedPercent: number) => [{ name: 'weekly', usedPercent, resetsAt: Date.now() + 30 * 3_600_000 }]
const box = (machineId: string) => Object.assign({ ...healthy(), machineId, name: `Box ${machineId}`, engines: ['claude', 'codex'] }, {
observation: { ...healthy().observation, runningHarnessIds: [], quotas: [{ engine: 'claude', known: true, windows: week(1) }, { engine: 'codex', known: true, windows: week(100) }] } })
@@ -1478,8 +1547,8 @@ describe('routing contributed capacity', () => {
const s = scoped({ context: { ok: true, value: { agentId: 'lead', tab: { state: { id: 'tab', agents: [], conversations: conversations(), machines: ['m1', 'm2', 'm3'].map(box) } },
policy: { policy: enabled, warnings: [] }, machines: [] } } })
const answer = await routeTask(input, s, where, opener())
- const rows = [answer.pick, ...answer.alternatives as unknown[]] as Array<{ machineId: string; engine: string; quota: string }>
- expect(rows.map(x => `${x.machineId} ${x.engine}`).sort()).toEqual(['m1 claude', 'm1 codex', 'm2 claude', 'm2 codex', 'm3 claude', 'm3 codex'])
+ const rows = answer.candidates as Array<{ machineId: string; engine: string; quota: string }>
+ expect(new Set(rows.map(x => `${x.machineId} ${x.engine}`))).toEqual(new Set(['m1 claude', 'm1 codex', 'm2 claude', 'm2 codex', 'm3 claude', 'm3 codex']))
expect(rows.find(x => x.engine === 'claude')!.quota).toBe('fits: weekly 99% left, resets in 30h')
expect(rows.find(x => x.engine === 'codex')!.quota).toBe('short: weekly 0% left, resets in 30h')
})
@@ -1497,9 +1566,10 @@ describe('routing contributed capacity', () => {
const answer = await routeTask(input, s as never, where, opener())
expect(answer).toMatchObject({ ok: true, routeDecisionId: 'd1' })
const sent = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0].command.decision.candidates.length)
- expect(sent).toEqual([16, 12])
+ // With no pick, then with c0 as the pick (a backend from before task #2901), then the first 12 of those.
+ expect(sent).toEqual([16, 16, 12])
const recordedIds = new Set(s.mock.calls.filter(c => c[0].action === 'command').at(-1)![0].command.decision.candidates.map((c: { id: string }) => c.id))
- for (const row of [answer.pick, ...answer.alternatives as unknown[]] as Array<{ id: string }>) expect(recordedIds.has(row.id)).toBe(true)
+ for (const row of answer.candidates as Array<{ id: string }>) expect(recordedIds.has(row.id)).toBe(true)
})
it('leaves out a machine that cannot take a teammate\'s project, with the backend\'s reason, and keeps its owner\'s own work there', async () => {
const reason = 'Contributed laptop has no Harness Team account yet, so it runs only its owner\'s projects.'
@@ -1528,7 +1598,7 @@ describe('routing contributed capacity', () => {
const said = 'Contributed laptop runs teammates\' work in Mate\'s own account.'
const pool = { ...healthy(), contributorId: 'mate', teamWork: { allowed: true, ownAccount: said } }
const teammate = (await runPool(pool, true, {}, { id: 'lead', ownerId: 'owner' })).answer
- const rows = [teammate.pick, ...teammate.alternatives as unknown[]] as Array<{ title: string; notes?: string[] }>
+ const rows = teammate.candidates as Array<{ title: string; notes?: string[] }>
expect(rows.length).toBeGreaterThan(1)
for (const row of rows) expect(row.notes ?? [], row.title).toContain(said)
const own = (await runPool(pool, true, {}, { id: 'lead', ownerId: 'mate' })).answer
@@ -1574,8 +1644,8 @@ describe('routing contributed capacity', () => {
it('starts a teammate\'s project in the team account, under the Mac\'s name, without calling the Mac unfit', async () => {
const { answer, candidates, excluded } = await route('owner')
- expect(answer).toMatchObject({ ok: true, pick: { machineId: 'm1-team' } })
- expect(answer.next).toContain('/team/swarm/lead')
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ machineId: 'm1-team' })]) })
+ expect(JSON.stringify(answer.candidates)).toContain('"cwd":"/team/swarm/lead"')
expect(candidates.filter(c => c.kind === 'new').map(c => c.machineId)).toEqual(expect.arrayContaining(['m1-team']))
expect(candidates.some(c => c.kind === 'new' && c.machineId === 'm1')).toBe(false)
expect(excluded.some(e => e.reason === NO_ACCOUNT)).toBe(false)
@@ -1583,7 +1653,7 @@ describe('routing contributed capacity', () => {
it('keeps the Mac\'s owner\'s own project with the owner, never the team account', async () => {
const { answer, candidates } = await route('mate')
- expect(answer).toMatchObject({ ok: true, pick: { machineId: 'm1' } })
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ machineId: 'm1' })]) })
expect(candidates.some(c => c.machineId === 'm1-team')).toBe(false)
})
@@ -1644,7 +1714,7 @@ describe('routing contributed capacity', () => {
const reason = 'The Harness Team account on MacBook Pro is not private (gitconfig: it could read its owner\'s ~/.gitconfig), so it runs only its owner\'s projects.'
const refused = { ...relayed(), teamWork: { allowed: false, code: 'PRIVACY_CHECK_FAILED', reason } }
const picked = await routeWith([fullMac(), refused, other()])
- expect(picked.answer).toMatchObject({ ok: true, pick: { machineId: 'm9' } })
+ expect(picked.answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ machineId: 'm9' })]) })
expect(picked.answer.leftOut).toEqual([{ machine: 'MacBook Pro', reasons: [reason] }])
const none = await routeWith([fullMac(), refused])
expect(none.answer).toMatchObject({ error: 'NO_CANDIDATE' })
@@ -1793,7 +1863,7 @@ describe('local models on the Swarm\'s grid', () => {
{ title: 'Kimi K3', reason: 'Its host 2x 4090 Rig is offline, so an agent on it would never start.' },
{ title: 'unnamed-host', reason: 'Its host, a machine of this Swarm, is offline, so an agent on it would never start.' },
])
- expect(result).toMatchObject({ ok: true, pick: { gridModel: 'deepseek/deepseek-v4.1' } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ gridModel: 'deepseek/deepseek-v4.1' })]) })
// A linked task is routed like any other (project instructions, phase 4): the same is said for it. Nothing with the add-on off.
Object.assign(t.state.conversations[1]!, { reviewOf: 'lead' })
const review = scoped({ tab: t })
@@ -1809,11 +1879,12 @@ describe('local models on the Swarm\'s grid', () => {
const s = scoped({ tab: t })
// A grid model takes only work of a listed kind (routeCheapFirst.ts GRID_KINDS).
const result = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'low', local: true, kind: 'docs' } }, s, where as never, opener(), () => 'op')
- expect(result).toMatchObject({ ok: true, pick: { kind: 'new', gridModel: 'qwen3', gridName: GRID } })
- const hint = JSON.parse(/start OPERATION_ID (\{.*\}), then/.exec(result.next as string)![1]!)
- expect(hint).toMatchObject({ engine: 'claude', gridModel: 'qwen3', gridName: GRID })
- expect(hint).not.toHaveProperty('model')
- expect(recorded(s).command.decision.candidates[0]).toMatchObject({ gridModel: 'qwen3', gridName: GRID })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new', gridModel: 'qwen3', gridName: GRID })]) })
+ // The row's grid model and its name go in the start, in place of model and effort.
+ const row = (result.candidates as Array<Record<string, unknown>>).find(r => r.gridModel === 'qwen3')!
+ expect(row).toMatchObject({ engine: 'claude', gridName: GRID })
+ expect(result.next).toContain('takes its gridModel and gridName in place of model and effort')
+ expect(recorded(s).command.decision.candidates).toContainEqual(expect.objectContaining({ id: row.id, gridModel: 'qwen3', gridName: GRID }))
})
})
@@ -1854,7 +1925,7 @@ describe('routing by facts', () => {
for (const row of rows.filter(r => r.machineId === 'm2')) expect(row.label).toContain('last 2 starts')
expect(recorded(s).command.decision.excluded).toEqual([])
// The answer says the same of what it offers.
- const offered = [result.pick, ...(result.alternatives as unknown[])] as Array<{ machineId: string; notes?: string[] }>
+ const offered = result.candidates as Array<{ machineId: string; notes?: string[] }>
expect(offered.filter(o => o.machineId === 'm1').every(o => o.notes?.some(n => n.includes('Its account lost this task before')))).toBe(true)
})
@@ -1889,7 +1960,7 @@ describe('routing by facts', () => {
it('says when the catalog could not be read, so no new agent is offered', async () => {
const empty = scoped({ context: { ok: true, value: { agentId: 'lead', tab: tab(), policy: {}, machines: [{ machineId: 'm1', name: 'remote-1' }] } } })
const result = await routeTask(input, empty, where as never, opener(), () => 'op')
- expect(result).toMatchObject({ ok: true, pick: { kind: 'member' } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member' })]) })
expect(result.warnings).toContain('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.')
expect(recorded(empty).command.decision.excluded).toContainEqual({ title: 'New agents', reason: expect.stringContaining('The model catalog could not be read') })
})
@@ -1901,13 +1972,13 @@ describe('routing by facts', () => {
const s = scoped({ tab: t })
// A grid model takes only work of a listed kind (routeCheapFirst.ts GRID_KINDS).
const result = await routeTask({ ...input, assessment: { ...input.assessment, local: true, kind: 'tests' } }, s, where as never, opener(), () => 'op')
- expect(result).toMatchObject({ ok: true, pick: { gridModel: 'llama3.2:3b', notes: [why] } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ gridModel: 'llama3.2:3b', notes: [why] })]) })
expect(shown(s).every(r => r.gridModel === 'llama3.2:3b' && r.label.includes(why))).toBe(true)
})
it('gives a neutral next step: the role comes from the project\'s instructions', async () => {
const hard = { ...input, assessment: { ...input.assessment, difficulty: 'high' } }
- // Only the Sonnet member, so a stronger new agent is the pick.
+ // Only the Sonnet member, so a stronger new agent is offered too.
const crew = (reviewOf?: string) => {
const t = tab(); t.state.agents = [agents[0]] as never
if (reviewOf) Object.assign(t.state.conversations[1]!, { reviewOf })
@@ -1916,7 +1987,7 @@ describe('routing by facts', () => {
const build = await routeTask(hard, scoped({ tab: crew(), policy: floorPolicy }), where as never, opener(), () => 'op')
const reviewing = await routeTask(hard, scoped({ tab: crew('lead'), policy: floorPolicy }), where as never, opener(), () => 'op')
for (const answer of [build, reviewing]) {
- expect(answer).toMatchObject({ ok: true, pick: { kind: 'new' } })
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new' })]) })
expect(answer.next).toContain('"roleName":"ROLE"')
expect(answer.next).not.toMatch(/Builder|Reviewer|"role":"reviewer"/)
}
@@ -1947,11 +2018,11 @@ describe('cheap first, through the route', () => {
it('a small, low-risk build\'s first attempt is started on Kimi K3, with why', async () => {
const { answer, s } = await route(cheap())
- expect(answer).toMatchObject({ ok: true, pick: { kind: 'new', gridModel: KIMI, gridName: GRID, notes: [`Cheap first: ${GRID_FIRST}`] } })
- expect(recorded(s).command.decision.candidates[0]).toMatchObject({ gridModel: KIMI, quality: 2 })
- // A medium task keeps today's order: the grid model ranks below the strong ones.
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'new', gridModel: KIMI, gridName: GRID, notes: [`Cheap first: ${GRID_FIRST}`] })]) })
+ expect(recorded(s).command.decision.candidates).toContainEqual(expect.objectContaining({ gridModel: KIMI, quality: 2 }))
+ // A medium task still offers the strong ones.
const medium = await route(cheap(), { ...small, assessment: { ...small.assessment, difficulty: 'medium' } })
- expect(medium.answer).toMatchObject({ ok: true, pick: { kind: 'member', model: 'sonnet' } })
+ expect(medium.answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', model: 'sonnet' })]) })
})
it('steps up: once the task had an attempt on Kimi K3, the next route leaves the grid out and starts a strong model (Sonnet is rated 3 in this table)', async () => {
@@ -1959,12 +2030,12 @@ describe('cheap first, through the route', () => {
agents: [...agents, { id: 'a3', name: 'Kestrel', machineId: 'm1', harnessId: 'h3', configuration: { engine: 'claude', model: 'default', effort: 'default' } }],
starts: [{ id: 's1', harnessId: 'h3', request: { conversationId: 'g1', machineId: 'm1', gridModel: KIMI, gridName: GRID } }] })
const { answer, excluded } = await route(tried)
- expect(answer).toMatchObject({ ok: true, pick: { kind: 'member', model: 'sonnet' } })
- expect((answer.pick as Record<string, unknown>).gridModel).toBeUndefined()
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', model: 'sonnet' })]) })
+ expect((answer.candidates as Array<Record<string, unknown>>).every(r => r.gridModel === undefined)).toBe(true)
expect(excluded).toContainEqual(expect.objectContaining({ reason: `Cheap first: ${FIRST_ATTEMPT_ONLY} Its earlier attempt ran on ${KIMI} on the Swarm's grid.` }))
// A log that could not be read is no proof of a first attempt.
const unread = await route(cheap(), small, { error: 'BACKEND_UNAVAILABLE' })
- expect(unread.answer).toMatchObject({ ok: true, pick: { kind: 'member', model: 'sonnet' } })
+ expect(unread.answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', model: 'sonnet' })]) })
expect(unread.excluded).toContainEqual(expect.objectContaining({ reason: `Cheap first: ${FIRST_ATTEMPT_ONLY} ${EARLIER_UNREADABLE}` }))
})
@@ -1976,7 +2047,7 @@ describe('cheap first, through the route', () => {
built.state.conversations.push({ id: 'r1', title: 'Review: API', leadId: 'lead', agentIds: ['lead'], archived: false, brief: '', checks: [{ description: 'Verdict' }],
assignment: null, reviewOf: 'g1', task: { goal: 'Review it.', owns: ['docs/guide.md'] } } as never)
const { answer, s, excluded } = await route(built, { ...small, conversationId: 'r1' })
- expect(answer).toMatchObject({ ok: true, pick: { kind: 'member', model: 'sonnet' } })
+ expect(answer).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ kind: 'member', model: 'sonnet' })]) })
const candidates = recorded(s).command.decision.candidates as Array<{ gridModel?: string; quality: number }>
expect(candidates.some(c => c.gridModel)).toBe(false)
expect(candidates[0]!.quality).toBe(3)
@@ -1995,22 +2066,22 @@ describe('routing by measured cost and results', () => {
const withCosts = (base: ReturnType<typeof scoped>, answer: (payload: Record<string, unknown>) => Promise<Answer>) =>
vi.fn(async (payload: Record<string, any>) => payload.action === 'costs' ? answer(payload) : base(payload))
- it('reads the last 7 days\' results and ranks the choice that costs less per shipped change first, with its numbers', async () => {
+ it('reads the last 7 days\' results and notes the choice that costs less per shipped change, with its numbers', async () => {
const base = scoped()
- // Sonnet ranks first today (cost 2 against Opus's 3); measured in full, Opus costs $3 per shipped change and Sonnet $9.
+ // Sonnet's catalog cost is 2 against Opus's 3; measured in full, Opus costs $3 per shipped change and Sonnet $9.
const plain = await routeTask(input, scoped(), where as never, opener(), () => 'op')
- expect(plain).toMatchObject({ pick: { model: 'sonnet' } })
+ expect(plain).toMatchObject({ candidates: expect.arrayContaining([expect.objectContaining({ model: 'sonnet' })]) })
const s = withCosts(base, async () => ({ ok: true, value: { truncated: false, rows: [row('opus', 'high', 3), row('sonnet', 'medium', 9)] } }))
const result = await routeTask(built, s, where as never, opener(), () => 'op')
expect(s.mock.calls.filter(c => c[0].action === 'costs').map(c => c[0])).toEqual([{ action: 'costs', days: 7 }])
- expect(result).toMatchObject({ ok: true, pick: { model: 'opus', notes: expect.arrayContaining([expect.stringMatching(/^measured results: build work, last 7 days: 8 of 10 first reviews passed, \$3\.00 per shipped change over 6/)]) } })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ model: 'opus', notes: expect.arrayContaining([expect.stringMatching(/^measured results: build work, last 7 days: 8 of 10 first reviews passed, \$3\.00 per shipped change over 6/)]) })]) })
expect(labels(base)[0]).toContain('measured results: build work')
})
it('a failed read leaves today\'s ranking and says so', async () => {
const s = withCosts(scoped(), async () => ({ error: 'FORBIDDEN' }))
const result = await routeTask(built, s, where as never, opener(), () => 'op')
- expect(result).toMatchObject({ ok: true, pick: { model: 'sonnet' },
- warnings: expect.arrayContaining(['The routing plug-in "measured results" was skipped: its maker failed. The route is ranked without it.']) })
+ expect(result).toMatchObject({ ok: true, candidates: expect.arrayContaining([expect.objectContaining({ model: 'sonnet' })]),
+ warnings: expect.arrayContaining(['The routing plug-in "measured results" was skipped: its maker failed. The route is shown without it.']) })
})
})
diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.ts
index 5fdcff42f..86ebe101d 100644
--- a/cli/src/superTabs/routeCommand.ts
+++ b/cli/src/superTabs/routeCommand.ts
@@ -1,14 +1,15 @@
/** `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 ranks the rest by strength, price, quota fit and idle members, with what else
- * it knows as notes (docs/plans/2026-10-30-project-instructions-design.md, Routing); and records the decision in the tab. */
+ * `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 { RELAYED_QUOTA, 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 { accountOf, API_BUILDERS, bytes, machineBrief, catalogFrom, catalogRow, choose, decide, gridStrength, parseAssessment, OLD_RECORD_MAX, quotaBrief, quotaOf2, slotOf, recordOf, repoMatch, repositoryKey, type Assessment, type Catalog, type CatalogModel, type RecordShape, type Commitment, type Excluded, type HeldModel, type MemberFrame, type Probe, type TaskFolder } from './route.js'
+import { accountOf, API_BUILDERS, bytes, machineBrief, catalogFrom, catalogRow, choose, decide, gridStrength, parseAssessment, OLD_RECORD_MAX, quotaBrief, quotaOf2, 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 { 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'
@@ -406,46 +407,60 @@ export async function routeTask(input: { tabId: string; conversationId: string;
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 every engine on every machine was shown keeps 12 candidates (Ken, 2026-11-03): the best 12 go.
- if (recorded.error === 'VALIDATION_ERROR' && offered.length > OLD_RECORD_MAX) { offered = offered.slice(0, OLD_RECORD_MAX); recorded = await record('current') }
+ // 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
- const decision = typeof routeDecisionId === 'string' ? `,"routeDecisionId":"${routeDecisionId}"` : ''
- // What the agent choosing reads of a candidate: where it runs, and what the route knows of it beside the ranking.
- // A new agent's row says what its machine has for a start; a member needs no new start, and a paused machine, which offers
- // no new agent, shows no reading (review of #2426).
- const publicOf = (s: typeof verdict.pick) => ({ id: s.id, kind: s.kind, ...(s.agentId ? { agentId: s.agentId } : {}), machineId: s.machineId,
+ // 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' && s.load?.room ? { machine: machineBrief(s.load.room) } : {}), ...(s.notes.length ? { notes: s.notes } : {}) })
+ ...(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 } : {}) })
+ // 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 }),
...(instructions ? { instructions } : { instructionsUnreadable: true }),
- pick: publicOf(verdict.pick), via: verdict.via, p: verdict.p, why: verdict.why,
- alternatives: alternativesTo(verdict.pick, offered).map(publicOf),
+ 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: verdict.pick.kind === 'member'
- ? `Assign with: command OPERATION_ID {"type":"work.assign","conversationId":"${input.conversationId}","agentId":"${verdict.pick.agentId}"${decision}}`
- // 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).
- : `Start with: start OPERATION_ID ${JSON.stringify({ conversationId: input.conversationId, name: 'NAME', ...(instructions ? { roleName: 'ROLE' } : {}),
- cwd: text(machines.get(verdict.pick.machineId)?.pool?.cwd) ?? assessment.needs.cwd ?? '/absolute/repo/on/that/machine',
- worktree: true, requirements: startRequirements(assessment.needs), ...(assessment.needs.heavy ? { heavy: assessment.needs.heavy } : {}),
- machineId: verdict.pick.machineId, engine: verdict.pick.engine,
- // A local model is named by the grid alone: no subscription model or effort goes with it.
- ...(verdict.pick.gridModel ? { gridModel: verdict.pick.gridModel, gridName: verdict.pick.gridName } : { model: verdict.pick.model, effort: verdict.pick.effort }),
- ...(typeof routeDecisionId === 'string' ? { routeDecisionId } : {}) })}, then assign the started agent${decision ? ' with the same routeDecisionId' : ''}. `
- + `Put the agent's name for NAME${instructions ? ' and its role in the project\'s instructions for ROLE' : ''}. It starts from the repository's default branch, fetched first; add "branchRef":"refs/remotes/origin/BRANCH" to start from another branch.`,
+ next: nextOf(shownRows, input.conversationId, typeof routeDecisionId === 'string' ? routeDecisionId : undefined, !!instructions, assessment.needs),
}
}
+/** 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']): string {
+ const choose = 'Choose one candidate by the project\'s Routing instructions (Order and quota); the list is by machine name, not by merit.'
+ const decided = routeDecisionId ? { routeDecisionId, overrideReason: 'RULE' } : {}
+ const assign = `Assign a member with: 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 with: 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 the started agent${routeDecisionId ? ' with the same routeDecisionId' : ''}. `
+ + 'Put the chosen row\'s machineId, engine, model, effort and cwd for MACHINE, ENGINE, MODEL, EFFORT and CWD; a row on a model served on the Swarm\'s grid takes its gridModel and gridName in place of model and effort. '
+ + `Put the agent's name for NAME${instructions ? ' and its role in the project\'s instructions for ROLE' : ''}. It starts from the repository's default branch, fetched first; add "branchRef":"refs/remotes/origin/BRANCH" to start from another branch.`
+ const rule = routeDecisionId ? ' Put the Routing rule that chose it for RULE (urgency, context or a machine the work needs where it departs from the order).' : ''
+ 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. */
@@ -460,14 +475,6 @@ export function leftOut(excluded: Excluded[], shown: Array<{ machineName: string
}
const MAX_LEFT_OUT = 20, MAX_REASONS = 4
-/** The next two rows, and the best row of every other machine, so the agent choosing can take another machine. */
-/** The best new agent and the best member of every engine on every machine, in rank order, the pick's own left out: the project's
- * order picks between accounts, then whether to reuse an agent there, so each is in front of the agent choosing once (Ken,
- * 2026-11-03). */
-function alternativesTo<T extends { id: string } & Parameters<typeof slotOf>[0]>(pick: T, shown: T[]): T[] {
- const seen = new Set([slotOf(pick)])
- return shown.filter(s => { const best = !seen.has(slotOf(s)); seen.add(slotOf(s)); return best })
-}
/** A reading this old says nothing is served (backend `MACHINE_FRESH_MS`). */
export const LOCAL_FRESH_MS = 45_000
diff --git a/cli/src/superTabs/routeMeasured.spec.ts b/cli/src/superTabs/routeMeasured.spec.ts
index e7460645b..822550c12 100644
--- a/cli/src/superTabs/routeMeasured.spec.ts
+++ b/cli/src/superTabs/routeMeasured.spec.ts
@@ -4,7 +4,8 @@ import { choose, type Assessment, type Catalog, type Probe } from './route.js'
import { MEASURED, MEASURED_MAKER, measuredFrom, measuredPlugin, readMeasured, type MeasuredRow } from './routeMeasured.js'
import { ROUTE_PLUGIN_MAKERS, type PluginInput } from './routePlugins.js'
-/** Today's strong rows (backend superTabs/catalog.ts): at equal strength Codex's cost 2 ranks before Opus's 3. */
+/** Today's strong rows (backend superTabs/catalog.ts): at equal strength Codex costs 2 against Opus's 3. Opus is on mac-1 and
+ * Codex on mac-2, so the neutral order (machine name) lists Opus first. */
const catalog: Catalog = { grid: { strength: 1, models: [{ model: 'kimi k3', strength: 2 }] }, models: [
{ engine: 'claude', model: 'opus', effort: 'high', strength: 3, cost: 3, offered: true },
{ engine: 'claude', model: 'opus', effort: 'xhigh', strength: 3, cost: 4, offered: true },
@@ -31,55 +32,64 @@ const order = (choice: ReturnType<typeof route>) => choice.shown.map(s => `${s.e
const mine = (s: { notes: string[] }) => s.notes.filter(n => n.startsWith(`${MEASURED}: `))
describe('routing by measured cost and results (Goals piece 3)', () => {
- it('today, without measures, Codex ranks first by its lower catalog cost', () => {
- expect(order(route([]))).toEqual(['codex gpt-6.1-sol', 'claude opus'])
+ it('without measures nothing is said, and the candidates come by machine name', () => {
+ const choice = route([])
+ expect(order(choice)).toEqual(['claude opus', 'codex gpt-6.1-sol'])
+ expect(choice.shown.flatMap(mine)).toEqual([])
+ expect(choice.adjusted).toBeUndefined()
})
- it('the choice that costs less per shipped change in full wins, rework rounds and their reviews counted', () => {
+ it('says each choice\'s full cost per shipped change on the catalog\'s scale, rework rounds and their reviews counted', () => {
// 9 of 10 against 6 of 10: their 95% ranges overlap, so cost decides; counted in full, Opus is cheaper.
const choice = route(measured)
+ // Since task #2901 a plug-in's finding is a note, never the order.
expect(order(choice)).toEqual(['claude opus', 'codex gpt-6.1-sol'])
expect(choice.adjusted).toBe(true)
- expect(mine(choice.shown[0]!)).toEqual([`${MEASURED}: build work, last 7 days: 9 of 10 first reviews passed, $6.00 per shipped change over 10 (failed attempts and every review round included); ranked as cost 2.0 instead of 3`])
- expect(mine(choice.shown[1]!)).toEqual([`${MEASURED}: build work, last 7 days: 6 of 10 first reviews passed, $9.00 per shipped change over 10 (failed attempts and every review round included); ranked as cost 3.0 instead of 2`])
+ expect(mine(choice.shown[0]!)).toEqual([`${MEASURED}: build work, last 7 days: 9 of 10 first reviews passed, $6.00 per shipped change over 10 (failed attempts and every review round included); cost 2.0 in the catalog's terms, against its listed 3`])
+ expect(mine(choice.shown[1]!)).toEqual([`${MEASURED}: build work, last 7 days: 6 of 10 first reviews passed, $9.00 per shipped change over 10 (failed attempts and every review round included); cost 3.0 in the catalog's terms, against its listed 2`])
})
- it('never ranks by the cost of its own attempts alone, which leaves the rework out', () => {
+ it('never goes by the cost of its own attempts alone, which leaves the rework out', () => {
// Without a full cost (a backend before it) nothing is measured, even with a cheaper cost per shipped change of its own.
const old = measured.map(({ fullCostPerShipped: _full, ...r }) => ({ ...r, fullCostPerShipped: null }))
const choice = route(old)
- expect(order(choice)).toEqual(['codex gpt-6.1-sol', 'claude opus'])
+ expect(choice.shown.flatMap(mine)).toEqual([])
expect(choice.adjusted).toBeUndefined()
})
- it('a clearly lower first-review pass rate ranks below its strength\'s other choices, whatever it costs', () => {
- // 2 of 12 against 11 of 12: the ranges do not overlap. Codex is cheaper in full here and still goes second.
+ it('a clearly lower first-review pass rate is said, whatever it costs, so another choice of its strength is preferred', () => {
+ // 2 of 12 against 11 of 12: the ranges do not overlap. Codex is cheaper in full here and its note still says so.
const choice = route([row({ firstReviews: 12, firstReviewPassed: 11, fullCostPerShipped: 9 }),
row({ engine: 'codex', model: 'gpt-6.1-sol', firstReviews: 12, firstReviewPassed: 2, fullCostPerShipped: 3 })])
- expect(order(choice)).toEqual(['claude opus', 'codex gpt-6.1-sol'])
- expect(mine(choice.shown[1]!)[0]).toContain('2 of 12 first reviews passed, clearly fewer than Claude opus high\'s 11 of 12, so it ranks after its strength\'s other choices')
- // Still above a weaker model: the plug-in moves a candidate within its strength, never across it.
+ expect(mine(choice.shown[1]!)[0]).toContain('2 of 12 first reviews passed, clearly fewer than Claude opus high\'s 11 of 12, so prefer another choice of its strength')
+ expect(mine(choice.shown[0]!)[0]).not.toContain('clearly fewer')
+ // A weaker model with no measures says nothing of it.
+ // Since task #2901 a plug-in's finding is a note, never the order.
const sonnet = probe({ machineId: 'm3', machineName: 'mac-3', model: 'sonnet', effort: 'medium', quality: 2, cost: 2 })
- expect(order(route([row({ firstReviews: 12, firstReviewPassed: 11 }), row({ engine: 'codex', model: 'gpt-6.1-sol', firstReviews: 12, firstReviewPassed: 2 })],
- [opus, codex, sonnet]))).toEqual(['claude opus', 'codex gpt-6.1-sol', 'claude sonnet'])
+ const three = route([row({ firstReviews: 12, firstReviewPassed: 11 }), row({ engine: 'codex', model: 'gpt-6.1-sol', firstReviews: 12, firstReviewPassed: 2 })],
+ [opus, codex, sonnet])
+ expect(order(three)).toEqual(['claude opus', 'codex gpt-6.1-sol', 'claude sonnet'])
+ expect(mine(three.shown[2]!)).toEqual([])
})
- it('below the minimum sample today\'s ranking stays, and nothing is said', () => {
+ it('below the minimum sample nothing is said', () => {
const thin = route(measured.map(r => ({ ...r, shipped: 2 })))
- expect(order(thin)).toEqual(['codex gpt-6.1-sol', 'claude opus'])
expect(thin.shown.flatMap(mine)).toEqual([])
- // Too few first reviews keep only the pass rate out: cost still decides with enough shipped changes.
+ expect(thin.adjusted).toBeUndefined()
+ // Too few first reviews keep only the pass rate out: cost is still said with enough shipped changes.
const fewReviews = route(measured.map(r => ({ ...r, firstReviews: 4, firstReviewPassed: Math.min(r.firstReviewPassed, 4) })))
- expect(order(fewReviews)).toEqual(['claude opus', 'codex gpt-6.1-sol'])
expect(mine(fewReviews.shown[0]!)[0]).toContain('first reviews too few to compare (4)')
- // One measured choice has nothing to compare with: its numbers are shown, its place is today's.
+ expect(mine(fewReviews.shown[0]!)[0]).toContain('cost 2.0 in the catalog\'s terms, against its listed 3')
+ // One measured choice has nothing to compare with: its numbers are shown, and no cost in the catalog's terms.
const alone = route([measured[1]!])
- expect(order(alone)).toEqual(['codex gpt-6.1-sol', 'claude opus'])
- expect(mine(alone.shown[0]!)[0]).toMatch(/\$9\.00 per shipped change over 10 .*; no other choice for build work has a cost to compare, so its place is unchanged$/)
+ expect(mine(alone.shown[0]!)).toEqual([])
+ expect(mine(alone.shown[1]!)[0]).toMatch(/\$9\.00 per shipped change over 10 .*; no other choice for build work has a cost to compare it with$/)
// Nor do choices that cost nothing (own hardware), or a run whose model was never known.
for (const others of [[row({ fullCostPerShipped: 0 }), row({ engine: 'codex', model: 'gpt-6.1-sol', fullCostPerShipped: 0 })],
[row({ model: 'unknown', effort: 'unknown' }), measured[1]!]]) {
- expect(order(route(others))).toEqual(['codex gpt-6.1-sol', 'claude opus'])
+ const notes = route(others).shown.flatMap(mine)
+ expect(notes.length).toBeGreaterThan(0)
+ for (const n of notes) expect(n).toMatch(/; no other choice for build work has a cost to compare it with$/)
}
})
@@ -87,7 +97,7 @@ describe('routing by measured cost and results (Goals piece 3)', () => {
const choice = route([row({ firstReviews: 12, firstReviewPassed: 11, shipped: 1, engine: 'opencode', model: 'big' }),
row({ engine: 'codex', model: 'gpt-6.1-sol', firstReviews: 12, firstReviewPassed: 2, shipped: 2 })])
expect(order(choice)).toEqual(['claude opus', 'codex gpt-6.1-sol'])
- expect(mine(choice.shown[1]!)).toEqual([`${MEASURED}: build work, last 7 days: 2 of 12 first reviews passed, clearly fewer than another measured choice's 11 of 12, so it ranks after its strength's other choices, too few shipped changes with known costs to compare cost (2 shipped)`])
+ expect(mine(choice.shown[1]!)).toEqual([`${MEASURED}: build work, last 7 days: 2 of 12 first reviews passed, clearly fewer than another measured choice's 11 of 12, so prefer another choice of its strength, too few shipped changes with known costs to compare cost (2 shipped)`])
expect(mine(choice.shown[0]!)).toEqual([])
})
@@ -106,22 +116,23 @@ describe('routing by measured cost and results (Goals piece 3)', () => {
it('a Claude model it has no family for is matched by its own name', () => {
const odd = probe({ model: 'claude-experimental', effort: 'default', cost: 1, quality: 3 })
const choice = route([...measured, row({ model: 'claude-experimental', effort: 'default', fullCostPerShipped: 60 })], [odd, codex])
- expect(order(choice)).toEqual(['codex gpt-6.1-sol', 'claude claude-experimental'])
+ expect(order(choice)).toEqual(['claude claude-experimental', 'codex gpt-6.1-sol'])
+ expect(mine(choice.shown[0]!)[0]).toContain('$60.00 per shipped change over 10')
})
- it('review work, and any kind with no first reviews, ranks as today: cost alone says nothing of how it went', () => {
+ it('review work, and any kind with no first reviews, says nothing: cost alone says nothing of how it went', () => {
// A review attempt is credited with the reviewed work's ship, and its cost is already in that build's full cost (review of
// #2423: Opus high reviews read as 76 shipped changes at $0.95).
const reviews = measured.map(r => ({ ...r, kind: 'review', firstReviews: 0, firstReviewPassed: 0 }))
for (const [rows, a] of [[reviews, task({ kind: 'review' })], [measured.map(r => ({ ...r, kind: 'review' })), task({ kind: 'review' })],
[measured.map(r => ({ ...r, firstReviews: 0, firstReviewPassed: 0 })), task()]] as const) {
const choice = route([...rows], [opus, codex], a)
- expect(order(choice)).toEqual(['codex gpt-6.1-sol', 'claude opus'])
expect(choice.shown.flatMap(mine)).toEqual([])
+ expect(choice.adjusted).toBeUndefined()
}
})
- it('only choices a candidate can be set the cost scale, so a run of a model nobody offers moves nothing', () => {
+ it('only choices a candidate can be set the cost scale, so a run of a model nobody offers changes no note', () => {
const odd = row({ model: 'sonnet', effort: 'high', fullCostPerShipped: 300 })
expect(route([...measured, odd]).shown.flatMap(mine)).toEqual(route(measured).shown.flatMap(mine))
})
@@ -131,15 +142,15 @@ describe('routing by measured cost and results (Goals piece 3)', () => {
expect(mine(choice.shown[0]!)[0]).toContain('$6.00 per shipped change over 10 (failed attempts and every review round included; 40% of the costs estimated)')
})
- it('a task with no kind, or a kind nothing was measured for, ranks as today', () => {
+ it('a task with no kind, or a kind nothing was measured for, says nothing', () => {
for (const a of [task({ kind: undefined }), task({ kind: 'docs' })]) {
const choice = route(measured, [opus, codex], a)
- expect(order(choice)).toEqual(['codex gpt-6.1-sol', 'claude opus'])
+ expect(choice.shown.flatMap(mine)).toEqual([])
expect(choice.adjusted).toBeUndefined()
}
})
- it('only reorders what the route allows: a refused candidate stays out, and the plug-in adds none', () => {
+ it('only notes what the route allows: a refused candidate stays out, and the plug-in adds none', () => {
const blocked = { ...opus, refusals: ['Machine is offline or unreachable.'] }
const choice = choose([blocked, codex], catalog, task(), NOW, [], [], [], [measuredPlugin({ rows: measured, truncated: false })])
if ('error' in choice) throw new Error('no candidate')
@@ -153,8 +164,9 @@ describe('routing by measured cost and results (Goals piece 3)', () => {
const grid = probe({ machineId: 'm5', machineName: 'grid-1', model: 'default', effort: 'default', quality: 3, cost: 1, gridModel: 'moonshotai/kimi-k3', gridName: 'g', gridLabel: 'Kimi K3', gridKind: 'api' })
const rows = [...measured, row({ model: 'moonshotai/kimi-k3', effort: 'default', firstReviewPassed: 5, fullCostPerShipped: 30 })]
const choice = route(rows, [member, codex, grid])
- expect(order(choice)).toEqual(['claude claude-opus-5-5[1m]', 'codex gpt-6.1-sol', 'claude default'])
- expect(mine(choice.shown[2]!)[0]).toContain('$30.00 per shipped change')
+ expect(order(choice)).toEqual(['claude default', 'codex gpt-6.1-sol', 'claude claude-opus-5-5[1m]'])
+ expect(mine(choice.shown[0]!)[0]).toContain('$30.00 per shipped change')
+ expect(mine(choice.shown[2]!)[0]).toContain('$6.00 per shipped change')
})
it('says when the read held only the newest attempts', () => {
@@ -165,7 +177,7 @@ describe('routing by measured cost and results (Goals piece 3)', () => {
describe('reading the measures', () => {
const answer = (rows: unknown[], extra: Record<string, unknown> = {}) => ({ ok: true, value: { days: 7, truncated: false, rows, ...extra } })
- it('asks for the last 7 days and keeps only the fields it ranks by', async () => {
+ it('asks for the last 7 days and keeps only the fields it goes by', async () => {
const asked: unknown[] = []
const read = await readMeasured(async payload => { asked.push(payload); return answer([{ ...row({}), tokens: { input: 1 }, outcomes: { done: 1 } }], { truncated: true }) })
expect(asked).toEqual([{ action: 'costs', days: 7 }])
@@ -184,13 +196,13 @@ describe('reading the measures', () => {
expect(await readMeasured(async () => { throw new Error('socket closed') })).toBeNull()
expect(await readMeasured(async () => { throw new Error('socket closed again') })).toBeNull()
expect(warn.mock.calls.map(c => String(c[0]))).toEqual([
- '[super-tabs] the route could not read cost results: TEAM_SESSION_LIMITED (403); it ranks without them',
- '[super-tabs] the route could not read cost results: the request failed; it ranks without them',
+ '[super-tabs] the route could not read cost results: TEAM_SESSION_LIMITED (403); the route is shown without them',
+ '[super-tabs] the route could not read cost results: the request failed; the route is shown without them',
])
} finally { warn.mockRestore() }
})
- it('a refusal, a failure, a slow read or an answer it cannot read gives no measures, so the route ranks as today', async () => {
+ it('a refusal, a failure, a slow read or an answer it cannot read gives no measures, so the route has no measured notes', async () => {
expect(await readMeasured(async () => ({ error: 'FORBIDDEN' }))).toBeNull()
expect(await readMeasured(async () => { throw new Error('gone') })).toBeNull()
expect(await readMeasured(() => new Promise(() => {}), 5)).toBeNull()
diff --git a/cli/src/superTabs/routeMeasured.ts b/cli/src/superTabs/routeMeasured.ts
index 83f693c5f..c1ac0b70e 100644
--- a/cli/src/superTabs/routeMeasured.ts
+++ b/cli/src/superTabs/routeMeasured.ts
@@ -1,19 +1,20 @@
/** Routing by what choices actually cost and how they did (Scholes's goals, piece 3, 2026-10-31): a routing plug-in (route.ts
- * RoutePlugin) that moves a candidate within its strength by its choice's measured results for the task's kind of work, over
- * the project's last 7 days (backend superTabs/costs/read.ts, the same read as `harness super-tab costs`, which counts only
+ * RoutePlugin) that notes on a candidate its choice's measured results for the task's kind of work, over the project's last
+ * 7 days (backend superTabs/costs/read.ts, the same read as `harness super-tab costs`, which counts only
* the groups the routing agent may read and refuses a Buddy).
*
* - Cost: the full cost per shipped change, every ended attempt of the choice (failed and lost ones too) and every review of
* its work, rework rounds included. A choice's own attempts alone made one that passes 6 of 10 first reviews look cheaper
* than one that passes 9 of 10, its extra review rounds left out (Lead, 2026-10-31). The measured choices of the kind are
- * ranked by it on the catalog's cost scale, so they keep their place against unmeasured ones on average.
- * - Results: a first-review pass rate clearly under another measured choice's (their 95% ranges apart) ranks the choice after
- * its strength's other choices, never below a weaker strength. With 5 to 10 reviews the ranges nearly always overlap, so
+ * put on the catalog's cost scale by it, so they compare with unmeasured ones on average.
+ * - Results: a first-review pass rate clearly under another measured choice's (their 95% ranges apart) is said, so another
+ * choice of its strength is preferred, never a weaker strength. With 5 to 10 reviews the ranges nearly always overlap, so
* cost decides.
* - Only with enough of it: at least MIN_SHIPPED shipped changes for cost and MIN_FIRST_REVIEWS first reviews for the pass
- * rate (the nightly reflection's own thresholds, costs/reflection.ts); otherwise today's ranking.
- * It never adds or refuses a candidate: what may run is the route's, and only its order changes. The kind is the word the
- * routing agent gives in its assessment (`kind`); none, or one nothing was measured for, ranks as today. */
+ * rate (the nightly reflection's own thresholds, costs/reflection.ts); otherwise nothing is said.
+ * It never adds or refuses a candidate: what may run is the route's, and since task #2901 its finding is a note, never the
+ * order. The kind is the word the routing agent gives in its assessment (`kind`); none, or one nothing was measured for, says
+ * nothing. */
import { claudeAliasForModel } from '../engines/claude/runtimeProfile.js'
import { catalogRow, type Catalog, type Probe, type RoutePlugin } from './route.js'
import type { PluginMaker } from './routePlugins.js'
@@ -24,7 +25,8 @@ export const MEASURED = 'measured results'
export const DAYS = 7
export const MIN_FIRST_REVIEWS = 5
export const MIN_SHIPPED = 3
-/** How far a clearly worse pass rate moves a candidate: after its strength's other choices, before the next strength's. */
+/** Which way a clearly worse pass rate leans, in catalog strength: less than one step, since only another choice of its
+ * strength is preferred. It moves nothing (task #2901). */
const WORSE = -0.5
const Z = 1.96
/** Well under the makers' 3 s (routePlugins.ts MAKER_TIMEOUT_MS), so a slow read is said as this piece's own failure. */
@@ -43,7 +45,7 @@ const count = (v: unknown): v is number => Number.isInteger(v) && (v as number)
const money = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v >= 0
const object = (v: unknown): Record<string, unknown> => v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {}
-/** The rows of a costs answer it can rank by, or null when the answer is no summary. A row it cannot read is dropped; a
+/** The rows of a costs answer it can go by, or null when the answer is no summary. A row it cannot read is dropped; a
* backend before full costs sends none, read as unknown. */
export function measuredFrom(answer: unknown): Measured | null {
const reply = object(answer), value = object(reply.value)
@@ -65,13 +67,13 @@ const saidWhy = new Set<string>()
function sayOnce(why: string): void {
if (saidWhy.has(why)) return
saidWhy.add(why)
- console.warn(`[super-tabs] the route could not read cost results: ${why}; it ranks without them`)
+ console.warn(`[super-tabs] the route could not read cost results: ${why}; the route is shown without them`)
}
const reasonOf = (answer: Record<string, unknown>) =>
`${String(answer.error)}${Number.isInteger(answer.status) ? ` (${answer.status as number})` : ''}`
/** The project's measures, read through the route's own backend request: null when refused, failed, slower than [ms] or
- * unreadable, so the route ranks as today. A refusal is logged by its code, never its detail. The read is the costs
+ * unreadable, so the route has no measured notes. A refusal is logged by its code, never its detail. The read is the costs
* command's, about 0.1 to 0.3 s beyond a plain request on the openharness Swarm (2026-10-31). */
export async function readMeasured(request: ScopedRequest, ms = READ_MS): Promise<Measured | null> {
const answer = await within(request({ action: 'costs', days: DAYS }).catch(() => { sayOnce('the request failed'); return null }), ms)
@@ -104,14 +106,14 @@ const KIND = /^[a-z][a-z0-9-]{0,39}$/
const costed = (r: MeasuredRow) => r.shipped >= MIN_SHIPPED && r.fullCostPerShipped !== null
const reviewed = (r: MeasuredRow) => r.firstReviews >= MIN_FIRST_REVIEWS
-/** The plug-in over [measured]: pure, so the route ranks every candidate with the same numbers. */
+/** The plug-in over [measured]: pure, so the route notes every candidate with the same numbers. */
export function measuredPlugin(measured: Measured): RoutePlugin {
- /** Per kind: its rows, and the measured costs' scale on the catalog's: dollars per cost point, so the measured choices keep
- * their mean place against unmeasured ones. Null when fewer than two choices have a cost to compare. */
+ /** Per kind: its rows, and the measured costs' scale on the catalog's: dollars per cost point, so the measured choices compare
+ * with unmeasured ones on average. Null when fewer than two choices have a cost to compare. */
const byKind = new Map<string, { rows: MeasuredRow[]; scale: number | null; results: boolean }>()
const scaleOf = (rows: MeasuredRow[], catalog: Catalog) => {
// Only the catalog's own choices set the scale: a run of a model nobody offers (an effort the catalog has no row for, a
- // model never reported) would move every candidate without being one (review of #2423).
+ // model never reported) would shift every candidate's measured cost without being one (review of #2423).
const scaled = rows.filter(r => costed(r) && listed(r, catalog))
const points = scaled.reduce((sum, r) => sum + catalogRow(catalog, r.engine, r.model, r.effort)!.cost, 0)
const dollars = scaled.reduce((sum, r) => sum + r.fullCostPerShipped!, 0)
@@ -126,7 +128,7 @@ export function measuredPlugin(measured: Measured): RoutePlugin {
let ofKind = byKind.get(kind)
if (!ofKind) {
const rows = measured.rows.filter(r => r.kind === kind)
- // A kind with no first review at all has no results to go by: cost alone ranks it as nothing else does.
+ // A kind with no first review at all has no results to go by: cost alone would judge it as nothing else is.
ofKind = { rows, scale: rows.some(r => r.firstReviews > 0) ? scaleOf(rows, catalog) : null, results: rows.some(r => r.firstReviews > 0) }
byKind.set(kind, ofKind)
}
@@ -142,17 +144,17 @@ export function measuredPlugin(measured: Measured): RoutePlugin {
if (!costed(mine) && !worse) return null
const pass = !reviewed(mine) ? `first reviews too few to compare (${mine.firstReviews})`
: `${mine.firstReviewPassed} of ${mine.firstReviews} first reviews passed${worse
- ? `, clearly fewer than ${nameOf(best!.r, catalog)}'s ${best!.r.firstReviewPassed} of ${best!.r.firstReviews}, so it ranks after its strength's other choices` : ''}`
+ ? `, clearly fewer than ${nameOf(best!.r, catalog)}'s ${best!.r.firstReviewPassed} of ${best!.r.firstReviews}, so prefer another choice of its strength` : ''}`
let cost: string, shift = 0
if (!costed(mine)) cost = `too few shipped changes with known costs to compare cost (${mine.shipped} shipped)`
else {
const estimated = mine.fullCostKnown !== null && mine.fullCostKnown < 1 ? `; ${Math.round((1 - mine.fullCostKnown) * 100)}% of the costs estimated` : ''
const full = `$${mine.fullCostPerShipped!.toFixed(2)} per shipped change over ${mine.shipped} (failed attempts and every review round included${estimated})`
- if (ofKind.scale === null) cost = `${full}; no other choice for ${kind} work has a cost to compare, so its place is unchanged`
+ if (ofKind.scale === null) cost = `${full}; no other choice for ${kind} work has a cost to compare it with`
else {
const points = mine.fullCostPerShipped! / ofKind.scale
shift = points - candidate.cost
- cost = `${full}; ranked as cost ${points.toFixed(1)} instead of ${candidate.cost}`
+ cost = `${full}; cost ${points.toFixed(1)} in the catalog's terms, against its listed ${candidate.cost}`
}
}
return { reason: `${kind} work, last ${DAYS} days: ${pass}, ${cost}${measured.truncated ? '; only the newest attempts were read' : ''}`,
diff --git a/cli/src/superTabs/routePlugins.spec.ts b/cli/src/superTabs/routePlugins.spec.ts
index 2364a3cfd..c583529ab 100644
--- a/cli/src/superTabs/routePlugins.spec.ts
+++ b/cli/src/superTabs/routePlugins.spec.ts
@@ -7,7 +7,7 @@ const input: PluginInput = { conversationId: 'g1', assessment: { difficulty: 'lo
read: { tab: {} }, catalog: { models: [], grid: { strength: 1, models: [] } }, history: Promise.resolve(null), request: async () => ({ ok: true }) }
const plugin = (name: string): RoutePlugin => ({ name, adjust: () => null })
const maker = (name: string, make: PluginMaker['make']): PluginMaker => ({ name, make })
-const skipped = (name: string, why: string) => `The routing plug-in "${name}" was skipped: ${why}. The route is ranked without it.`
+const skipped = (name: string, why: string) => `The routing plug-in "${name}" was skipped: ${why}. The route is shown without it.`
afterEach(() => { vi.useRealTimers() })
diff --git a/cli/src/superTabs/routePlugins.ts b/cli/src/superTabs/routePlugins.ts
index 94d454fa9..226334aee 100644
--- a/cli/src/superTabs/routePlugins.ts
+++ b/cli/src/superTabs/routePlugins.ts
@@ -48,7 +48,7 @@ const isPlugin = (p: unknown): p is RoutePlugin => {
/** Every maker's plug-in, in the makers' order whatever order they finish in. A maker that throws, rejects, answers what is not
* a plug-in, or has not answered in [ms] is left out and named in `warnings`, with no error text; what it answers later is
- * dropped, so a route already ranked never changes. */
+ * dropped, so a route already shown never changes. */
export async function makePlugins(makers: readonly PluginMaker[], input: PluginInput, ms = MAKER_TIMEOUT_MS): Promise<{ plugins: RoutePlugin[]; warnings: string[] }> {
const made = await Promise.all(makers.map(async maker => {
let timer: NodeJS.Timeout | undefined
diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.ts
index 4cebc9aab..5079416e9 100644
--- a/cli/src/superTabs/service.spec.ts
+++ b/cli/src/superTabs/service.spec.ts
@@ -668,6 +668,22 @@ describe('routeHistory', () => {
expect(person).toMatchObject({ title: 'Pick', account: 'k0', spend: { '5-hour': 30, weekly: 4 } })
expect(lead).not.toHaveProperty('account')
})
+ // Task #2901: a route names no pick; the start or assignment the coordinator made records the candidate it matched, and that
+ // candidate's account and spend are what the open decision holds (the backend keeps every candidate's slim fit).
+ it('takes the title, account and spend of the candidate a pick-less decision\'s start chose', async () => {
+ const slim = (account: string, weekly: number) => ({ account, spend: { '5-hour': weekly * 7, weekly } })
+ const record = { via: 'instructions', assessment: { size: 'small' }, candidates: [{ id: 'c0', title: 'New agent · Claude opus high · a', fit: slim('ka', 1) },
+ { id: 'c1', title: 'New agent · Codex default default · b', fit: slim('kb', 2) }] }
+ const chosen = { id: 'd1', conversationId: 'g1', record, override: null, outcome: null, assignmentId: 'as1', createdAt: '2026-11-04T10:00:00Z',
+ final: { kind: 'new', startId: 's', machineId: 'b', engine: 'codex', model: 'default', effort: 'default', candidateId: 'c1' } }
+ const waiting = { ...chosen, id: 'd2', final: null, assignmentId: null }
+ const { value } = await contextOf(setup(), async path => path.includes('/messages') ? ok({ messages: [] }) : ok([chosen, waiting]))
+ const [started, unstarted] = value.decisions as Array<Record<string, unknown>>
+ expect(started).toMatchObject({ title: 'New agent · Codex default default · b', account: 'kb', spend: { '5-hour': 14, weekly: 2 }, size: 'small', via: 'instructions' })
+ // Nothing chosen yet holds nothing, and says so.
+ expect(unstarted).toMatchObject({ title: 'not chosen yet' })
+ expect(unstarted).not.toHaveProperty('account')
+ })
it('gives every attempt of the group, newest first, with only what the route needs and no more than fifty', async () => {
const t = setup()
const row = (i: number) => ({ id: `as${i}`, agentId: i % 2 ? 'a2' : 'gone', status: 'stopped', result: i === 0 ? 'Tests failed.' : i === 2 ? 'y'.repeat(900) : null, createdAt: '2026-10-19T10:00:00Z',
@@ -845,8 +861,9 @@ it('says a server from before rules does not support them, and passes a malforme
expect(await send({ type: 'rule.set', rule: { kind: 'minEffort', effort: 'huge' }, text: 'x' })).not.toMatchObject({ error: 'RULES_UNSUPPORTED' })
})
-// Project instructions, phase 4: the route ranks by facts and notes the rest; no build, review or grid rule is the help's.
-it('tells every agent what the route leaves out, how it ranks the rest, and which kinds of work may go to the grid', async () => {
+// Project instructions, phase 4: the route shows facts and notes the rest; no build, review or grid rule is the help's. Task #2901:
+// it ranks nothing and names no pick, so the help sends the choice to the Routing instructions and asks for the rule followed.
+it('tells every agent what the route leaves out, that it ranks the rest by nothing, and which kinds of work may go to the grid', async () => {
const help = (await setup().ask({ action: 'help' }, owner)).help as { commands: Array<{ type: string }>; command: string; route: string }
expect(help.route).toContain('The route leaves out what cannot run, and says why')
// Besides what cannot run, the grid rules leave models out (routeCheapFirst.ts), so "only" is no longer said.
@@ -857,8 +874,11 @@ it('tells every agent what the route leaves out, how it ranks the rest, and whic
for (const kind of GRID_KINDS) expect(ROUTE_KIND_HELP).toContain(kind)
expect(CHEAP_FIRST_HELP).toContain(`1 to ${MAX_OWNED} owned paths`)
expect(CHEAP_FIRST_HELP).toMatch(/never offered, even when named, for a review, security work .* or a task's second attempt/)
- expect(help.route).toContain('It ranks the rest by strength, then price and quota fit, then an idle agent before a new one')
- expect(help.route).toContain('Your project\'s instructions say how to choose')
+ expect(help.route).toContain('It ranks nothing and names no pick: the rest come by machine name, then engine')
+ expect(help.route).toContain('weekly % left and reset time')
+ expect(help.route).toContain('choose by your project\'s Routing instructions')
+ expect(help.route).toContain('routeDecisionId and overrideReason, the Routing rule that chose it')
+ expect(help.route).not.toMatch(/ranks the rest|by strength, then price|choose by strength|A pick on/)
expect(`${help.route} ${help.command}`).not.toMatch(/noGridFirst|policy rates 3|low-risk work of kind docs|NO_CANDIDATE/)
expect(help.commands.map(c => c.type)).not.toContain('rule.set')
})
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index 34718506e..de086f657 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -86,7 +86,7 @@ const HELP = {
// A person's own command, for the machines they added; an agent's terminal is refused (command.ts), so no agent raises its
// own machine's room (Lead, 2026-10-28).
setAgents: 'set-agents MACHINE_ID COUNT: for a machine\'s owner, from their own terminal, not an agent\'s: how many Swarm agents may run on that machine at once. Each agent still needs free memory when it starts. A machine may offer one agent for every 2 GB of its memory, and at least 4; a larger number is refused.',
- route: `route GROUP JSON: rank who could do a group's work, before you start an agent or assign it to another. Work you do yourself is not routed. JSON: {"difficulty":"low|medium|high","risk":"low|medium|high","size":"small|medium|large","why":"one sentence","kind":"${ROUTE_KIND_HELP}","local":"optional true, only when a person asked for a local model","model":"optional: the model a person named, in their words; only it is offered","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}. size is how long the work runs: small about 20 minutes, medium about an hour, large about three hours. The route leaves out what cannot run, and says why: a machine offline, paused or full, an engine not installed, signed out or suspended, tools or devices the work needs that a machine lacks, and machines that cannot take a teammate's project (it runs only on Team machines: a Mac's Harness Team account whose privacy check passed, or a machine used only for agents). It ranks the rest by strength, then price and quota fit, then an idle agent before a new one, and notes what else it knows on each candidate: a used-up quota, a lost task, a machine whose last starts failed, a task requirement naming another machine, a model the catalog does not offer by default or does not rate. ${CHEAP_FIRST_HELP} Your project's instructions say how to choose; where they say nothing, choose by strength, quota and price. A named model the catalog does not list is offered unrated. A pick on a model served on the Swarm's grid starts with gridModel and gridName in place of model and effort. Start or assign any candidate with the routeDecisionId, so the decision records what ran.`,
+ route: `route GROUP JSON: list who could do a group's work, before you start an agent or assign it to another. Work you do yourself is not routed. JSON: {"difficulty":"low|medium|high","risk":"low|medium|high","size":"small|medium|large","why":"one sentence","kind":"${ROUTE_KIND_HELP}","local":"optional true, only when a person asked for a local model","model":"optional: the model a person named, in their words; only it is offered","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}. size is how long the work runs: small about 20 minutes, medium about an hour, large about three hours. The route leaves out what cannot run, and says why: a machine offline, paused or full, an engine not installed, signed out or suspended, tools or devices the work needs that a machine lacks, and machines that cannot take a teammate's project (it runs only on Team machines: a Mac's Harness Team account whose privacy check passed, or a machine used only for agents). It ranks nothing and names no pick: the rest come by machine name, then engine, each with its facts (model, effort, the catalog's strength and price, quota fit with weekly % left and reset time, the agents on its machine, idle or new), and it notes what else it knows on each candidate: a used-up quota, a lost task, a machine whose last starts failed, a task requirement naming another machine, a model the catalog does not offer by default or does not rate, a plug-in's finding. ${CHEAP_FIRST_HELP} The first row is first by its machine's name, not by merit: choose by your project's Routing instructions. A named model the catalog does not list is offered unrated. A candidate on a model served on the Swarm's grid starts with gridModel and gridName in place of model and effort. Start or assign the candidate you chose with the routeDecisionId and overrideReason, the Routing rule that chose it, so the decision records what ran and why.`,
screen: 'screen AGENT [--scrollback N]: read another agent\'s terminal in your project as plain text, with up to 200 lines of scrollback. Use it when an agent seems stuck.',
type: 'type AGENT [TEXT] [--key K]...: type text, then keys (Enter, Esc, Tab, Up, Down, Left, Right, Ctrl-C, 0-9), into another agent\'s terminal in your project. Answer prompts within its task; ask the owner before approving anything risky.',
capacity: 'capacity MACHINE_ID JSON: inspect machine, engine and quota headroom. JSON uses the start request fields below. Unknown allowances are not reported as free tokens.',
@@ -654,12 +654,15 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
// An older backend has no such route: its 404 is unreadable like any other failure.
within(backend(core, 'GET', `${path}/conversations/${encodeURIComponent(String(payload.conversationId))}/attempts?${identity}`)),
])
- // The log's records carry every candidate's line; the route needs only who was picked and how it went, and the account and expected spend of what actually runs, which an open pick still holds: after an override
- // that is the person's chosen candidate, and a Lead's own choice outside the list has no known account.
+ // The log's records carry every candidate's line; the route needs only who was chosen and how it went, and the account and expected spend of what actually runs, which an open decision still holds: the
+ // candidate its start or assignment matched (task #2901: a route names no pick, and the backend records that one in the final), else after an override the person's chosen candidate, else an old record's
+ // pick. A Lead's own choice outside the list has no known account.
const decisions = Array.isArray(logged) ? logged.slice(0, 50).map(object).map(d => {
const record = object(d.record), final = object(d.final), candidates = list(record.candidates), pick = candidates.find(c => c.id === record.pick)
- const runs = d.override ? candidates.find(c => c.id === object(d.override).candidateId) : pick, fit = object(runs?.fit)
- return { id: d.id, conversationId: d.conversationId, title: String(pick?.title ?? 'unknown pick'),
+ const byFinal = candidates.find(c => typeof final.candidateId === 'string' && c.id === final.candidateId)
+ const runs = byFinal ?? (d.override ? candidates.find(c => c.id === object(d.override).candidateId) : pick), fit = object(runs?.fit)
+ const title = pick?.title ?? byFinal?.title ?? (record.pick === undefined && candidates.length ? 'not chosen yet' : 'unknown pick')
+ return { id: d.id, conversationId: d.conversationId, title: String(title),
...(typeof fit.account === 'string' ? { account: fit.account, spend: object(fit.spend), size: object(record.assessment).size ?? 'medium' } : {}),
...(typeof record.via === 'string' ? { via: record.via } : {}), outcome: d.outcome ?? null, assignmentId: d.assignmentId ?? null, createdAt: d.createdAt,
final: final.kind === 'member' ? { kind: 'member', agentId: final.agentId } : final.kind === 'new' ? { kind: 'new', engine: final.engine, model: final.model } : null }
diff --git a/cli/src/superTabs/windowPull.spec.ts b/cli/src/superTabs/windowPull.spec.ts
index 22b83068e..fcb4680ed 100644
--- a/cli/src/superTabs/windowPull.spec.ts
+++ b/cli/src/superTabs/windowPull.spec.ts
@@ -34,39 +34,42 @@ const noteOf = (p: { notes: string[] }) => p.notes.find(n => n.startsWith(`${WIN
const fitted = (p: Probe, fit: Partial<Fit> = {}): Probe & { fit: Fit } => ({ ...p, fit: { status: 'fits', coverage: 1, effectiveCost: p.cost, expiring: 0,
spend: { '5-hour': 30, weekly: 4 }, account: p.quota.account ?? '', ...fit } })
-describe('the window pull ranks', () => {
- it('an account whose weekly window resets soon with quota left first, and says why', () => {
+describe('the window pull notes', () => {
+ it('an account whose weekly window resets soon with quota left, and says why', () => {
const probes = [codex('alpha', FRESH), codex('zulu', SOON)]
- // Without it, the two tie on strength, price and fit, and the title decides.
- expect(route(probes, []).shown.map(s => s.machineId)).toEqual(['alpha', 'zulu'])
+ expect(route(probes, []).shown.every(s => !noteOf(s))).toBe(true)
const choice = route(probes, [pull])
- expect(choice.shown.map(s => s.machineId)).toEqual(['zulu', 'alpha'])
- const reason = 'Window pull: its account\'s weekly window resets in 12h, and at this week\'s pace about 57% of it would go unused; this task spends it first'
- expect(choice.shown[0]!.notes).toContain(reason)
- expect(choice.shown[0]!.label).toContain(reason)
- expect(noteOf(choice.shown[1]!)).toBeUndefined()
+ // Since task #2901 a plug-in's finding is a note, never the order.
+ expect(choice.shown.map(s => s.machineId)).toEqual(['alpha', 'zulu'])
+ const reason = 'Window pull: its account\'s weekly window resets in 12h, and at this week\'s pace about 57% of it would go unused; prefer this account to use it before the reset'
+ expect(choice.shown[1]!.notes).toContain(reason)
+ expect(choice.shown[1]!.label).toContain(reason)
+ expect(noteOf(choice.shown[0]!)).toBeUndefined()
const verdict = decide(choice)
- expect(verdict.pick.machineId).toBe('zulu')
- expect(verdict.why).toContain('plug-ins')
+ expect(verdict.via).toBe('instructions')
+ expect(verdict.why).toContain('Plug-ins\' findings are in each candidate\'s notes.')
expect(JSON.stringify(recordOf(choice, verdict, a()))).toContain(reason)
// What the candidate is shown and recorded as stays as measured.
- expect(choice.shown[0]!.fit.effectiveCost).toBe(2)
+ expect(choice.shown[1]!.fit.effectiveCost).toBe(2)
})
- it('an idle agent on such an account over a cheaper new agent: it pulls the queued task', () => {
+ it('an idle agent on such an account, beside a cheaper new agent: it could take the queued task', () => {
const probes = [codex('alpha', FRESH), opusMember('zulu', SOON)]
- // Codex is cheaper than Opus at the same strength.
- expect(route(probes, []).shown[0]!.kind).toBe('new')
const choice = route(probes, [pull])
- expect(choice.shown[0]).toMatchObject({ kind: 'member', agentId: 'agent-1' })
- expect(noteOf(choice.shown[0]!)).toMatch(/this idle agent takes queued work first$/)
+ // Since task #2901 a plug-in's finding is a note, never the order.
+ expect(choice.shown.map(s => s.kind)).toEqual(['new', 'member'])
+ expect(choice.shown[1]).toMatchObject({ kind: 'member', agentId: 'agent-1' })
+ expect(noteOf(choice.shown[1]!)).toMatch(/this idle agent could take queued work to use it$/)
+ expect(noteOf(choice.shown[0]!)).toBeUndefined()
})
- it('never above a stronger model', () => {
+ it('a weaker model on such an account is noted, and the order stays the neutral one', () => {
const sonnet = codex('zulu', SOON, { engine: 'claude', model: 'sonnet', effort: 'medium', quality: 2 })
const choice = route([codex('alpha', FRESH), sonnet], [pull])
+ // Since task #2901 a plug-in's finding is a note, never the order.
expect(choice.shown.map(s => s.model)).toEqual(['default', 'sonnet'])
- expect(noteOf(choice.shown[1]!)).toBeDefined()
+ expect(noteOf(choice.shown[1]!)).toMatch(/prefer this account to use it before the reset$/)
+ expect(choice.shown[1]!.quality).toBe(2)
})
- it('makes a choice at most half as costly, never free, so a clearly better record still wins (pieces 3 and 6 together)', () => {
+ it('leans a choice at most half as costly, never free, and a clearly better record is said beside it (pieces 3 and 6 together)', () => {
// At most half, however much would go unused.
expect(windowPullAdjust(fitted(codex('zulu', SOON)), NOW, [])?.cost).toBe(-2 * MAX_DISCOUNT)
expect(windowPullAdjust(fitted(codex('zulu', SOON), { effectiveCost: 1.2 }), NOW, [])?.cost).toBe(-0.6)
@@ -75,9 +78,10 @@ describe('the window pull ranks', () => {
firstReviews: 10, firstReviewPassed, shipped: 10, costPerShipped: 1, fullCostPerShipped, fullCostKnown: 1 })
const measured = measuredPlugin({ truncated: false, rows: [row('claude', 'opus', 'high', 9, 3), row('codex', 'default', 'default', 6, 9)] })
const probes = [codex('alpha', FRESH, { engine: 'claude', model: 'opus', effort: 'high', cost: 3 }), codex('zulu', SOON)]
- expect(route(probes, [pull], [], { kind: 'build' }).shown[0]!.machineId).toBe('zulu')
+ expect(noteOf(route(probes, [pull], [], { kind: 'build' }).shown[1]!)).toBeDefined()
for (const plugins of [[measured, pull], [pull, measured]]) {
const choice = route(probes, plugins, [], { kind: 'build' })
+ // Since task #2901 a plug-in's finding is a note, never the order.
expect(choice.shown.map(s => s.machineId)).toEqual(['alpha', 'zulu'])
expect(noteOf(choice.shown[1]!)).toBeDefined()
expect(choice.shown[0]!.notes.some(n => n.startsWith(`${MEASURED}: build work`))).toBe(true)
@@ -98,22 +102,20 @@ describe('the window pull leaves alone', () => {
const choice = route([codex('alpha', FRESH), short], [pull])
expect(choice.shown.find(s => s.machineId === 'zulu')!.fit.status).toBe('short')
expect(choice.shown.every(s => !noteOf(s))).toBe(true)
- expect(choice.shown[0]!.machineId).toBe('alpha')
})
it('a candidate whose fit is not known to cover the task: a weekly window that could not be read (review of f97c022)', () => {
- // Opus with only its 5-hour window read: the fit is unknown, and half off would put it above a Codex that fits.
+ // Opus with only its 5-hour window read: the fit is unknown, and half off would read it as cheaper than a Codex that fits.
const unread = { ...opusMember('zulu', windows([90, 12 * H], null, 'acct-soon')), kind: 'new' as const, agentId: undefined, name: undefined }
const choice = route([codex('alpha', FRESH), unread], [pull])
expect(choice.shown.find(s => s.machineId === 'zulu')!.fit.status).toBe('unknown')
- expect(choice.shown[0]!.machineId).toBe('alpha')
expect(choice.shown.every(s => !noteOf(s))).toBe(true)
none(unread, { status: 'unknown' })
})
it('but pulls an account that reports its weekly window alone, Codex or Claude, a complete reading that fits', () => {
const weeklyOnly = codex('zulu', windows(null, [60, 12 * H], 'acct-soon'))
const choice = route([codex('alpha', FRESH), weeklyOnly], [pull])
- expect(choice.shown[0]).toMatchObject({ machineId: 'zulu', fit: { status: 'fits' } })
- expect(noteOf(choice.shown[0]!)).toBeDefined()
+ expect(choice.shown[1]).toMatchObject({ machineId: 'zulu', fit: { status: 'fits' } })
+ expect(noteOf(choice.shown[1]!)).toBeDefined()
// A Team account's Claude, whose host relays no 5-hour window (Ken, 2026-11-03).
const claude = { ...opusMember('zulu', windows(null, [60, 12 * H], 'acct-soon')), kind: 'new' as const, agentId: undefined, name: undefined }
expect(route([codex('alpha', FRESH), claude], [pull]).shown.find(s => s.machineId === 'zulu')!.fit.status).toBe('fits')
@@ -172,7 +174,7 @@ describe('the window pull\'s reason', () => {
const choice = route([codex('alpha', FRESH), soon], made.plugins)
const reason = noteOf(choice.shown.find(s => s.machineId === 'zulu')!)!
// Their pick is counted: about 57% less its 20% (a minute of a 3-hour task over) is about 37%.
- expect(reason).toBe('Window pull: its account\'s weekly window resets in 12h, and at this week\'s pace about 37% of it would go unused; this task spends it first')
+ expect(reason).toBe('Window pull: its account\'s weekly window resets in 12h, and at this week\'s pace about 37% of it would go unused; prefer this account to use it before the reset')
for (const leak of ['payroll', 'Payroll', 'Dee', 'dee', 'acct', 'example.com', 'd-secret', 'as-9', '/Users', 'Rotate']) expect(reason).not.toContain(leak)
})
})
@@ -212,19 +214,18 @@ describe('the window pull\'s maker', () => {
expect(ROUTE_PLUGIN_MAKERS.map(m => m.name)).toContain(WINDOW_PULL)
})
it('two routes a minute apart do not both pull onto one window', async () => {
- // About 2% would go unused, half a medium task: the first route pulls; the second sees that pick, not yet started.
+ // About 2% would go unused, half a medium task: the first route notes the pull; the second sees that pick, not yet started.
const thin = windows([80, 3 * H], [16, 24 * H], 'acct-soon')
const probes = [codex('alpha', FRESH), codex('zulu', thin)]
const first = await makePlugins([windowPullMaker(() => NOW)], input({ ok: true, value: { decisions: [] } }))
- expect(route(probes, first.plugins).shown[0]!.machineId).toBe('zulu')
+ expect(noteOf(route(probes, first.plugins).shown.find(s => s.machineId === 'zulu')!)).toBeDefined()
const routed = { id: 'd1', conversationId: 'g1', account: 'acct-soon', spend: { weekly: 4 }, size: 'medium', outcome: null, final: null, createdAt: new Date(NOW - M).toISOString() }
const second = await makePlugins([windowPullMaker(() => NOW)], input({ ok: true, value: { decisions: [routed] } }))
const choice = route(probes, second.plugins)
- expect(choice.shown[0]!.machineId).toBe('alpha')
expect(choice.shown.every(s => !noteOf(s))).toBe(true)
})
it('is left out, and the route answer says so, when the history could not be read', async () => {
expect(await makePlugins([windowPullMaker()], input(null))).toEqual({ plugins: [],
- warnings: ['The routing plug-in "Window pull" was skipped: its maker failed. The route is ranked without it.'] })
+ warnings: ['The routing plug-in "Window pull" was skipped: its maker failed. The route is shown without it.'] })
})
})
diff --git a/cli/src/superTabs/windowPull.ts b/cli/src/superTabs/windowPull.ts
index c644d9be6..cf724a244 100644
--- a/cli/src/superTabs/windowPull.ts
+++ b/cli/src/superTabs/windowPull.ts
@@ -1,8 +1,8 @@
/** The window pull (Scholes's goals, piece 6: "token maxxing"): a subscription's weekly window that resets soon with quota
- * left loses that quota at the reset, so the route spends it first. A candidate whose account would otherwise leave part of
- * its weekly window unused is made cheaper by that part of the task, never stronger: a stronger model still ranks first, and
- * a candidate the route leaves out stays out (route.ts RoutePlugin). The route's members are idle agents, so an idle agent on
- * such an account takes the next queued task it can run.
+ * left loses that quota at the reset, so the route says so on the candidate, for the Routing instructions to weigh. A
+ * candidate whose account would otherwise leave part of its weekly window unused leans cheaper by that part of the task, never
+ * stronger, and a candidate the route leaves out stays out (route.ts RoutePlugin). Since task #2901 that is a note, never the
+ * order. The route's members are idle agents, so an idle agent on such an account is noted as able to take queued work.
*
* The windows ride on the candidates (routeCommand.ts probeMachine reads them from each machine's last report; one older
* than 45 s is unknown quota, which this leaves alone). What it reads besides is the route history every maker shares: the
@@ -21,9 +21,9 @@ export const RESETS_SOON_MS = 48 * 3_600_000
export const WEEK_MS = 7 * 86_400_000
/** Less than this many percent of a week left unused is a rounding error, not quota worth moving work for. */
export const MIN_UNUSED_PERCENT = 1
-/** The most the pull takes off a candidate's price: half. An expiring window makes a choice look at most half as costly,
- * never free, so a choice with a clearly better record (piece 3, measured cost and results) still beats one whose only edge
- * is quota about to reset (Lead, 10-31). */
+/** The most the pull leans off a candidate's price: half. An expiring window makes a choice look at most half as costly,
+ * never free, so a choice with a clearly better record (piece 3, measured cost and results) still outweighs one whose only
+ * edge is quota about to reset (Lead, 10-31). */
export const MAX_DISCOUNT = 0.5
/** How long a pick nobody has started or assigned yet still holds its account's quota. A route is acted on within minutes;
* one older than this was dropped, and holding quota for it would keep the window from pulling at all. */
@@ -54,11 +54,11 @@ const round = (n: number) => Math.round(n * 100) / 100
/** A reset is told as how far away it is, as the route's labels tell it. */
const inTime = (ms: number) => ms < 3_600_000 ? `${Math.max(1, Math.round(ms / 60_000))}m` : `${Math.round(ms / 3_600_000)}h`
-/** The pull's word on one candidate: its price less up to half ([MAX_DISCOUNT]), by the part of the task its account's weekly
+/** The pull's word on one candidate: its price leaning less by up to half ([MAX_DISCOUNT]), by the part of the task its account's weekly
* window would otherwise leave unused. Only on a candidate whose quota is known to carry the task (fit `fits`; a reading
* of its weekly window alone is complete on either engine, route.ts sizeUp): one that would run out partway trades wasted
- * weekly quota for a stalled task, and one whose weekly window could not be read (`unknown`) would, since price ranks before
- * fit, beat an account known to fit on half a reading (review of f97c022). The reason names the window, never the account or
+ * weekly quota for a stalled task, and one whose weekly window could not be read (`unknown`) would read as
+ * cheaper than an account known to fit on half a reading (review of f97c022). The reason names the window, never the account or
* the machine a reading was relayed from, since every reader of the route log sees it. */
export function windowPullAdjust(p: Readonly<Probe & { fit: Fit }>, now: number, held: readonly Commitment[]): Adjustment | null {
if (p.fit.status !== 'fits' || p.fit.spend.weekly <= 0 || p.fit.effectiveCost <= 0) return null
@@ -66,7 +66,7 @@ export function windowPullAdjust(p: Readonly<Probe & { fit: Fit }>, now: number,
if (!left) return null
const discount = p.fit.effectiveCost * MAX_DISCOUNT * Math.min(1, left.unused / p.fit.spend.weekly)
const why = `its account's weekly window resets in ${inTime(left.resetsIn)}, and at this week's pace about ${Math.round(left.unused)}% of it would go unused`
- return { cost: -round(discount), reason: p.kind === 'member' ? `${why}; this idle agent takes queued work first` : `${why}; this task spends it first` }
+ return { cost: -round(discount), reason: p.kind === 'member' ? `${why}; this idle agent could take queued work to use it` : `${why}; prefer this account to use it before the reset` }
}
/** The plug-in for one route. [pending]: picks of the Swarm's other routes not started or assigned yet, which the route's
diff --git a/desktop/lib/super_tabs/route_row.dart b/desktop/lib/super_tabs/route_row.dart
index ab1cc7077..7052dfe87 100644
--- a/desktop/lib/super_tabs/route_row.dart
+++ b/desktop/lib/super_tabs/route_row.dart
@@ -45,6 +45,9 @@ class _SuperTabRouteRowState extends State<SuperTabRouteRow> {
String get _how => switch (widget.route.via) {
'jev' => 'Jev ${((widget.route.p ?? 0) * 100).round()}%',
'only' => 'Only available candidate',
+ // Task #2901 (Ken, 2026-11-04): the route names no pick; the coordinator
+ // chose by the project's Routing instructions, and its start says which.
+ 'instructions' => 'Chosen by the project\'s Routing instructions',
// An older backend's policy order too: it ranks, never refuses.
_ => 'Ranked by strength, price and quota',
};
diff --git a/desktop/test/super_tab_route_test.dart b/desktop/test/super_tab_route_test.dart
index 4291e38b6..b02c99024 100644
--- a/desktop/test/super_tab_route_test.dart
+++ b/desktop/test/super_tab_route_test.dart
@@ -184,6 +184,13 @@ void main() {
(via: 'order', fallback: 'unsure', text: ranked),
(via: 'order', fallback: 'unavailable', text: ranked),
(via: 'only', fallback: null, text: 'Only available candidate'),
+ // Task #2901 (Ken, 2026-11-04): the route names no pick; the start's row
+ // names the candidate the instructions chose.
+ (
+ via: 'instructions',
+ fallback: null,
+ text: 'Chosen by the project\'s Routing instructions',
+ ),
]) {
testWidgets('keeps ${c.via} ${c.fallback ?? ''} explanation in Details', (
tester,
diff --git a/docs/plans/2026-11-04-route-no-ranking-plan.md b/docs/plans/2026-11-04-route-no-ranking-plan.md
new file mode 100644
index 000000000..46b86fae6
--- /dev/null
+++ b/docs/plans/2026-11-04-route-no-ranking-plan.md
@@ -0,0 +1,116 @@
+# The route stops ranking candidates; the project's Routing instructions choose (task #2901) Implementation Plan
+
+> Implemented by the task's Engineer task by task, each failing test committed before its code (project instructions,
+> Engineer). One independent review on the pull request.
+
+**Goal:** `harness super-tab route` keeps leaving out what cannot run and keeps every fact per candidate. It stops
+ranking by strength or price and names no pick. Candidates come in a neutral, stable order (machine name, then engine).
+The coordinator chooses by the project's Routing instructions, and the start or assignment records which candidate it
+chose and why (Ken, 2026-11-04). Until now PMs took the route's top line, which was nearly always Opus or Astra, against
+the instructions' Order and quota.
+
+**Architecture:**
+
+- CLI `cli/src/superTabs/route.ts`. `compare` no longer orders by strength, effective cost or quota fit. It orders by
+ machine name, then engine, then a member in another repository after the others on that machine, then title.
+ Plug-ins' `strength`/`cost` adjustments become notes and no longer change the order; a plug-in's `refuse` still leaves
+ a candidate out. `decide` names no pick: its verdict is `via: 'instructions'` (`'only'` for a single candidate) with a
+ why that sends the reader to the Routing instructions. `short` ("the first candidate's quota…") goes, because nothing
+ is first; when no candidate fits, the route still warns.
+- CLI `routeCommand.ts`. The answer has `candidates` (one row per machine, engine and kind, in that order) and no
+ `pick`/`alternatives`/`p`. `next` explains how to start or assign the chosen candidate with the `routeDecisionId` and
+ an `overrideReason` naming the Routing rule followed. The record has no `pick` and `via: 'instructions'`. An older
+ backend refuses that record; the CLI then records the old shape, with `c0` as a placeholder pick, so its decision log
+ keeps working.
+- CLI `service.ts` routeHistory reads the candidate that ran from `final.candidateId` (new), then the person's
+ override, then the old pick.
+- Backend `routeRecord.ts`. `pick` is optional, and `via` also takes `'instructions'`. A record without a pick is stored
+ with every candidate's slim quota fit (`account`, `spend`): routeHistory needs the account and spend of whichever
+ candidate runs, and nobody knows which one that is until the start. `RouteFinal` takes an optional `candidateId`.
+- Backend `commands.ts`:
+ - `route.record` without a pick posts no chat row.
+ - `linkDecision` (start and assign) on a decision with no pick, no person's choice and no final yet requires
+ `overrideReason`. It records the candidate the start or assignment matches as `final.candidateId` and posts the
+ `route` row naming it ("Routed to X — by the project's Routing instructions · reason"). Released Desktop and phone
+ apps draw that row, because its source still carries a `pick`. A start that matches no candidate records an
+ override with the reason, as today.
+ - `route.override` with no earlier choice says "chose X".
+- Desktop and mobile `route_row`: the selection line for `via: 'instructions'`.
+- Backend `instructionsTemplate.ts` Routing: there is no order in the route to pick against. The reason goes with the
+ start.
+
+**Tech Stack:** TypeScript (CLI: vitest; backend: vitest + zod), Flutter (one `switch` case each in Desktop and mobile).
+
+**Spec:** task #2901's brief, and Ken's facts in its thread (11-04): clients need `pick` on a route row, the backend
+override path, the instructions text, and that a neutral first row is still a first row.
+
+## Global Constraints
+
+- Red first: no candidate comes first for being stronger or cheaper. Filters still leave out what cannot run. Each
+ candidate carries quota % left and reset time. A start with any candidate's id is recorded.
+- Swarm code stays out of `cli/src/core`.
+- Older clients keep working: an old CLI's record with a pick is taken and linked as before. Released apps draw the
+ route row.
+- Never run a test that signs the Mac out of the real CLI.
+
+## Design
+
+- growth: route decisions are deleted as before, and nothing is added per route except the slim fit on pick-less
+ records: about 130 bytes a candidate (14.6 KB for 42 candidates against 9.2 KB), measured in `routeRecord.test.ts`.
+- concurrency: unchanged. A decision is written inside the Swarm's store write, as before.
+- read cost: unchanged. routeHistory reads the same 50 decisions.
+- scale: 10x the machines means 64 candidates at most (`RECORD_MAX`). The stored size is the first metric to warn.
+- compatibility: an old CLI sends a pick, and its record is handled as before. The new CLI on an old backend falls back
+ to the old shape. Old apps draw the route row from the start's `pick`.
+- migration + rollback: no migration. Rolling back the backend refuses new pick-less records, and the CLI's old-shape
+ fallback covers that.
+- audience: the server enforces who may start, assign and override, as before. The reason requirement is server-side.
+- identity: N/A because nothing here reads or uses a person's login.
+- failure: a start without a reason on a pick-less decision is refused with what to send. A start that matches no
+ candidate is recorded and said in the chat.
+- platforms: CLI on every OS. Desktop and mobile change one label.
+
+## Review Focus
+
+- That the order no longer depends on strength, cost, fit or plug-in adjustments.
+- `linkDecision`'s three cases: a pick (old CLI), a person's choice, and the coordinator's own choice.
+- Released apps keep the route card.
+
+## Tasks
+
+### Task 1: neutral order and no pick (CLI route.ts)
+
+Files: `cli/src/superTabs/route.ts`, `route.spec.ts`, `__snapshots__/route.answers.json`, `routePlugins.spec.ts`.
+
+- [ ] Failing tests: a weaker, cheaper candidate on machine "a" comes before a stronger one on machine "b". A plug-in's
+ strength/cost adjustment adds its note and leaves the order alone. `decide` names no pick, and its why names the
+ Routing instructions. Refusals still leave candidates out. Each shown label still carries weekly % left and reset.
+- [ ] Code: `compare`, `pluginAdjustments` use, `decide`, `recordOf`, and `short` removed.
+- [ ] Snapshots updated.
+
+### Task 2: the route's answer and record (CLI routeCommand.ts, service.ts, help)
+
+Files: `routeCommand.ts`, `routeCommand.spec.ts`, `service.ts` (routeHistory, HELP.route), `service.spec.ts`,
+`cli/src/lib/swarmTools.ts`, `routeCheapFirst.ts` (help text), `docs/swarms.md`.
+
+- [ ] Failing tests: the answer has `candidates` and no `pick`. The record has no pick and `via: 'instructions'`, and
+ falls back to the old shape on VALIDATION_ERROR. routeHistory takes the account from `final.candidateId`.
+- [ ] Code and help text.
+
+### Task 3: backend record and link (backend)
+
+Files: `backend/src/superTabs/routeRecord.ts`, `routeRecord.test.ts`, `commands.ts`, its route tests,
+`parts/touches.ts`, `instructionsTemplate.ts`.
+
+- [ ] Failing tests: a pick-less record is accepted and stored with slim fits. A start matching any candidate records
+ its id and posts the route row with that pick. A start without a reason is refused. A start matching none
+ records an override. A person's override with no earlier choice says "chose". An old record with a pick links as
+ before.
+- [ ] Code.
+
+### Task 4: apps' selection line (Desktop, mobile)
+
+Files: `desktop/lib/super_tabs/route_row.dart`, `mobile/lib/swarm/...` route row, their route tests.
+
+- [ ] Failing test: `via: 'instructions'` reads "Chosen by the project's Routing instructions".
+- [ ] Code.
diff --git a/docs/swarms.md b/docs/swarms.md
index 8c0bb018f..15b159d78 100644
--- a/docs/swarms.md
+++ b/docs/swarms.md
@@ -478,19 +478,20 @@ recorded is never changed.
## Routing
-**Advice, not rules.** `harness super-tab route` ranks the candidates for a task
+**Advice, not rules.** `harness super-tab route` lists the candidates for a task
before an agent is started or assigned. By default the coordinator does it; the
project's instructions may give routing to another role. The route leaves out
only facts: a machine that is offline, removed or paused; an engine that is
signed out or suspended; a model the machine does not serve (a grid model whose
-host is down). Each candidate left out says why. It ranks the rest by strength,
-price, quota fit and idle agents. The project's instructions say what the
-project prefers in their Routing section; where they say nothing, the route's
-order stands. Quota and task requirements are notes on a candidate, never a
-reason to refuse one. A route decision records the revision of the instructions
-it relied on, stamped by the server when the decision is recorded. A person or
-an agent may follow any candidate; following one other than the first needs no
-reason.
+host is down). Each candidate left out says why. It ranks nothing and names no
+pick (task #2901): the rest come by machine name, then engine, each with its
+facts (strength, price, quota fit with weekly quota left and its reset, the
+agents on its machine). The project's instructions choose, in their Routing
+section. Quota and task requirements are notes on a candidate, never a reason
+to refuse one. A route decision records the revision of the instructions it
+relied on, stamped by the server when the decision is recorded. The start or
+assignment that follows it gives the Routing rule that chose its candidate, and
+the decision records which candidate that was.
**The model catalog.** A reviewed, read-only list in the backend (`catalog.ts`,
`MODEL_CATALOG`) holds each engine's models and the efforts offered, with a
diff --git a/mobile/lib/swarm/swarm_special_rows.dart b/mobile/lib/swarm/swarm_special_rows.dart
index 7f1303841..cda0322a7 100644
--- a/mobile/lib/swarm/swarm_special_rows.dart
+++ b/mobile/lib/swarm/swarm_special_rows.dart
@@ -100,6 +100,9 @@ class _SwarmRouteRowState extends State<SwarmRouteRow> {
String get _how => switch (widget.route.via) {
'jev' => 'Jev ${((widget.route.p ?? 0) * 100).round()}%',
'only' => 'Only available candidate',
+ // Task #2901 (Ken, 2026-11-04): the route names no pick; the coordinator
+ // chose by the project's Routing instructions, and its start says which.
+ 'instructions' => 'Chosen by the project\'s Routing instructions',
_ => 'Ranked by strength, price and quota',
};
diff --git a/mobile/test/swarm/swarm_special_rows_test.dart b/mobile/test/swarm/swarm_special_rows_test.dart
index 57585db9a..888e75dd4 100644
--- a/mobile/test/swarm/swarm_special_rows_test.dart
+++ b/mobile/test/swarm/swarm_special_rows_test.dart
@@ -162,6 +162,22 @@ void main() {
expect(fake.paths.where((p) => p == decisions), hasLength(1));
});
+ // Task #2901 (Ken, 2026-11-04): the route names no pick; the start's row
+ // names the candidate the instructions chose.
+ testWidgets('Details says the Routing instructions chose', (tester) async {
+ final fake = backend([
+ row('r1', 2, 'x', {...routeSource(), 'via': 'instructions'}),
+ ]);
+ fake.routes[decisions] = (_) => {
+ 'record': {'instructionsRevision': 7},
+ };
+ const chosen = 'Chosen by the project\'s Routing instructions';
+ await show(tester, fake);
+ await tester.tap(inRow('r1', find.text('Details')));
+ await tester.pumpAndSettle();
+ expect(inRow('r1', find.text('Selection: $chosen')), findsOneWidget);
+ });
+
testWidgets('a failed read says so, and Retry reads again', (tester) async {
final fake = backend([row('r1', 2, 'x', routeSource())]);
var fails = true;