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.

The route picks by the Routing order (#3576) (#3296)

harness-for-autonomous[bot]006cfc8a4e0d
diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.ts
index 91027243d..cb85416b3 100644
--- a/backend/src/superTabs/commands.test.ts
+++ b/backend/src/superTabs/commands.test.ts
@@ -1349,19 +1349,18 @@ describe('decisions linked to work', () => {
const request = { conversationId: task, machineId: 'machine', engine: 'claude', model: 'opus', effort: 'xhigh', name: 'Builder', cwd: '/repo', worktree: false,
requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }
const start = (extra: Record<string, unknown> = {}) => f.run({ type: 'agent.start', request, routeDecisionId: 'd1', ...extra } as Command, f.leadActor, { routeDecision: open({ conversationId: task }), contribution: f.contribution })
- expect(start().routeDecisions[0]).toMatchObject({ op: 'final', override: { by: 'lead', reason: 'No reason given.' } })
+ expect(() => start()).toThrow(expect.objectContaining({ code: 'ROUTE_REASON_REQUIRED' }))
const effects = start({ overrideReason: 'Xhigh is needed here.' })
expect(effects.routeDecisions[0]).toMatchObject({ op: 'final', override: { by: 'lead', reason: 'Xhigh is needed here.' } })
expect(effects.messages[0]).toMatchObject({ text: 'lead started Builder instead of Title c0. Reason: Xhigh is needed here.',
source: { kind: 'route-override', decisionId: 'd1', by: 'lead' } })
})
- it('records a mismatch as the agent\'s override, with its reason when one is given', () => {
+ it('records a mismatch as the agent\'s override, with its reason (required when the route picked)', () => {
const f = routed()
f.define('lead')
- expect(f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker, routeDecisionId: 'd1' }, f.leadActor, { routeDecision: open() }).routeDecisions[0])
- .toMatchObject({ op: 'final', override: { by: 'lead', reason: 'No reason given.' } })
- f.state.conversations.find(c => c.id === 'lead')!.assignment = null
+ expect(() => f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker, routeDecisionId: 'd1' }, f.leadActor, { routeDecision: open() }))
+ .toThrow(expect.objectContaining({ code: 'ROUTE_REASON_REQUIRED' }))
const effects = f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker, routeDecisionId: 'd1', overrideReason: 'This worker already has the context.' }, f.leadActor, { routeDecision: open() })
expect(effects.routeDecisions[0]).toMatchObject({ op: 'final', override: { by: 'lead', reason: 'This worker already has the context.' } })
expect(effects.messages.some(m => m.source?.kind === 'route-override')).toBe(true)
@@ -1536,7 +1535,7 @@ describe('a route that names no pick', () => {
// 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).
+// following another candidate needs a reason when the route named a pick (task #3576; it is still recorded).
describe('the route is advice', () => {
const request = (patch: Record<string, unknown> = {}) => ({ conversationId: 'lead', machineId: 'machine', engine: 'claude', model: 'opus', effort: 'high',
name: 'Builder', cwd: '/repo', worktree: false, requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false },
@@ -1608,18 +1607,23 @@ describe('the route is advice', () => {
expect(f.state.conversations.find(c => c.id === group)!.task!.requires).toEqual(requires)
})
- it('follows another candidate with no reason', () => {
+ // Anh Dee, 2026-11-06 (task #3576): the route picks by the Routing order, so the pick is followed as it is and another candidate
+ // is chosen only with a reason; it is still recorded as an override.
+ it('follows the pick with no reason, and another candidate only with one', () => {
const f = routed(), group = f.group(), engineer = f.add('engineer')
const decision = (id: string) => ({ id, conversationId: group, record: record(), final: null, override: null, assignmentId: null, outcome: null }) as unknown as RouteDecision
- const assigned = f.run({ type: 'work.assign', conversationId: group, agentId: f.worker, routeDecisionId: 'd1' }, as(engineer), { routeDecision: decision('d1') })
- expect(assigned.routeDecisions).toEqual([expect.objectContaining({ op: 'final', id: 'd1', override: expect.objectContaining({ by: 'lead', reason: 'No reason given.' }) })])
- expect(assigned.messages.find(m => m.source?.kind === 'route-override')!.text).toBe('engineer assigned worker instead of Title c0.')
+ expect(() => f.run({ type: 'work.assign', conversationId: group, agentId: f.worker, routeDecisionId: 'd1' }, as(engineer), { routeDecision: decision('d1') }))
+ .toThrow(expect.objectContaining({ code: 'ROUTE_REASON_REQUIRED', message: expect.stringContaining('Title c0') }))
const start = (id: string, overrideReason?: string) => f.run({ type: 'agent.start', request: request({ conversationId: group, effort: 'xhigh' }), routeDecisionId: id,
...(overrideReason ? { overrideReason } : {}) }, as(engineer), { routeDecision: decision(id), contribution: f.contribution })
- expect(start('d2').messages.find(m => m.source?.kind === 'route-override')!.text).toBe('engineer started Builder instead of Title c0.')
+ expect(() => start('d2')).toThrow(expect.objectContaining({ code: 'ROUTE_REASON_REQUIRED' }))
const reasoned = start('d3', 'Xhigh is needed here.')
expect(reasoned.routeDecisions[0]).toMatchObject({ override: { by: 'lead', reason: 'Xhigh is needed here.' } })
expect(reasoned.messages.find(m => m.source?.kind === 'route-override')!.text).toBe('engineer started Builder instead of Title c0. Reason: Xhigh is needed here.')
+ // The pick itself needs none and records no override.
+ const followed = f.run({ type: 'agent.start', request: request({ conversationId: group, effort: 'high' }), routeDecisionId: 'd4' }, as(engineer),
+ { routeDecision: decision('d4'), contribution: f.contribution })
+ expect(followed.routeDecisions).toEqual([expect.not.objectContaining({ override: expect.anything() })])
})
it('records the instructions revision a route relied on', () => {
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index e719b6920..3892d35c0 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -95,7 +95,7 @@ const STEPS_LISTED = 200
function listStep(task: Conversation, id: string): void {
if (task.stepIds) task.stepIds = [...task.stepIds, id].slice(-STEPS_LISTED)
}
-/** A route override's reason when its agent gave none: following another candidate needs none (project instructions). */
+/** A route override's reason when its agent gave none, on a decision whose chosen candidate was not a pick (a person's choice, or an older record). */
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.'
@@ -190,6 +190,8 @@ const task = z.object({
requires: z.object({ machines: z.array(id).min(1).max(20).optional(), devices: z.array(path).min(1).max(20).optional(),
access: z.array(accessName).min(1).max(20).optional() }).strict()
.refine(r => r.machines || r.devices || r.access, 'Require at least one machine, device or access.').optional(),
+ /** model.ts WorkTask.strength: `strong` for big, hard or risky work, which the crew's dispatch hands only to a member on Opus or Astra (#3576). */
+ strength: z.enum(['standard', 'strong']).optional(),
/** model.ts ReviewPlan: what its reviews check first, and 2 for two independent reviews, said in its brief (#2382). */
review: z.object({ focus: z.string().trim().min(1).max(2000).optional(), reviews: z.union([z.literal(1), z.literal(2)]).optional() }).strict()
.refine(r => r.focus !== undefined || r.reviews !== undefined, 'Give the review a focus or a number of reviews.').optional(),
@@ -1350,7 +1352,8 @@ 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. A route that picked (task #3576) asks for the
+ * reason when the start or assignment leaves its pick.
* 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. */
@@ -1381,6 +1384,10 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
}
const expected = decision.record.candidates.find(c => c.id === chosenId)!
const matched = matches(expected, decision)
+ // The route picked by the Routing order (task #3576): another candidate is chosen for a reason (urgency, context, a machine the work needs).
+ if (!matched && !reasonText && chosenId === decision.record.pick) {
+ fail('ROUTE_REASON_REQUIRED', `This route picked ${expected.title}. Start or assign it, or send, as overrideReason, why another candidate is better (urgency, context, a machine the work needs; "idle" is not a reason).`)
+ }
const override: RouteOverride | undefined = matched ? undefined : { by: 'lead', actorKey: actorKey(actor), reason: reasonText ?? NO_REASON }
// 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)
diff --git a/backend/src/superTabs/dispatch.test.ts b/backend/src/superTabs/dispatch.test.ts
index ec762178f..f8915e22d 100644
--- a/backend/src/superTabs/dispatch.test.ts
+++ b/backend/src/superTabs/dispatch.test.ts
@@ -238,6 +238,70 @@ describe('what a free crew member gets', () => {
})
})
+// River, 2026-11-06 (task #3576): the lane dispatch gave a big, risky task to a Sonnet member, while Routing puts big or risky work on
+// Opus or Astra. A task the PM marks strong (or one that wants two reviews) goes only to a member on a strong model.
+describe('dispatch keeps big or risky work for a strong model', () => {
+ function crew() {
+ const s = crewSwarm(['Sonny', 'Opal'])
+ for (const [name, model, effort] of [['Sonny', 'claude-sonnet-4-6', 'high'], ['Opal', 'claude-opus-4-7', 'high']] as const) {
+ const member = s.state.agents.find(a => a.id === s.ids[name])!
+ member.crew = { role: 'Engineer', at: 1000, by: 'owner' }
+ Object.assign(member.configuration, { model, effort })
+ }
+ const strongTask = (title: string, task: Record<string, unknown>) => s.run({ type: 'conversation.create', title,
+ task: { goal: `${title}.`, changes: 'The change.', constraints: 'None.', owns: ['backend/src/x.ts'], ...task }, checks: [] } as Command).result.conversationId as string
+ const plan = () => dispatchPlan(s.state, 'lead', DISPATCH_RULES, NOW).map(p => [s.state.agents.find(a => a.id === p.agentId)!.name, s.group(p.conversationId).title])
+ return { ...s, strongTask, plan }
+ }
+
+ it('does not hand a strong task to a Sonnet member, and hands it to an Opus member', () => {
+ const s = crew()
+ s.strongTask('Rebuild sync', { strength: 'strong' })
+ expect(s.plan()).toEqual([['Opal', 'Rebuild sync']])
+ })
+
+ it('counts a task that wants two reviews as strong, unless the PM marks it standard', () => {
+ const s = crew()
+ s.strongTask('Payments', { review: { reviews: 2 } })
+ expect(s.plan()).toEqual([['Opal', 'Payments']])
+ const t = crew()
+ t.strongTask('Typo', { review: { reviews: 2 }, strength: 'standard' })
+ expect(t.plan()).toEqual([['Sonny', 'Typo']])
+ })
+
+ it('hands an ordinary task to either member, and Sonnet keeps its turn when a strong task is first', () => {
+ const s = crew()
+ s.strongTask('Rebuild sync', { strength: 'strong' })
+ s.strongTask('Fix typo', {})
+ expect(s.plan()).toEqual([['Sonny', 'Fix typo'], ['Opal', 'Rebuild sync']])
+ })
+
+ it('takes Astra as strong too, and a pinned strong task stays with its member', () => {
+ const s = crew()
+ Object.assign(s.state.agents.find(a => a.id === s.ids.Opal)!.configuration, { engine: 'codex', model: 'gpt-6-astra', effort: 'xhigh' })
+ const id = s.strongTask('Rebuild sync', { strength: 'strong' })
+ expect(s.plan()).toEqual([['Opal', 'Rebuild sync']])
+ s.group(id).pin = { agentId: s.ids.Sonny!, why: 'ci', at: 2000 }
+ expect(s.plan()).toEqual([['Sonny', 'Rebuild sync']])
+ })
+
+ it('counts Astra only at xhigh, and a member with no effort set as not strong', () => {
+ const s = crew()
+ Object.assign(s.state.agents.find(a => a.id === s.ids.Opal)!.configuration, { engine: 'codex', model: 'gpt-6-astra', effort: 'high' })
+ s.strongTask('Rebuild sync', { strength: 'strong' })
+ expect(s.plan()).toEqual([])
+ Object.assign(s.state.agents.find(a => a.id === s.ids.Opal)!.configuration, { engine: 'claude', model: 'claude-opus-4-7', effort: null })
+ expect(s.plan()).toEqual([])
+ })
+
+ it('does not count Opus at a low effort as strong', () => {
+ const s = crew()
+ Object.assign(s.state.agents.find(a => a.id === s.ids.Opal)!.configuration, { effort: 'low' })
+ s.strongTask('Rebuild sync', { strength: 'strong' })
+ expect(s.plan()).toEqual([])
+ })
+})
+
describe('the crew\'s clocks: 2 hours without progress tells the member, 3 hours puts the task back in its lane', () => {
const HOUR = 3_600_000, AT = 1000
/** Ash (crew, backend) working on Api since AT; Birch (crew, backend) free. */
diff --git a/backend/src/superTabs/dispatch.ts b/backend/src/superTabs/dispatch.ts
index 12574a33d..1a3c61675 100644
--- a/backend/src/superTabs/dispatch.ts
+++ b/backend/src/superTabs/dispatch.ts
@@ -7,7 +7,7 @@
import { SEED_RULES, type ProjectRules } from './policy.js'
import { isBuddy } from './buddies.js'
import { sessionClosed } from './closedAgents.js'
-import { activeWork, handed, occupiesAgent, type Agent, type Assignment, type Conversation, type SuperTabState } from './model.js'
+import { activeWork, handed, occupiesAgent, reviewsWanted, type Agent, type Assignment, type Conversation, type SuperTabState } from './model.js'
import { agentProjectId, onTeamAccount, projectOf, projectsOf } from './projects.js'
import { barredFromTeamWritten } from './teamWritten.js'
import { digestOf, localNow } from './digest.js'
@@ -15,6 +15,7 @@ import { DEFAULT_TIME_ZONE } from './costs/reflection.js'
import { queueOrder, queueSiblings } from './taskQueue.js'
import { unavailableReason } from './liveness.js'
import { FAILED, type PullRequestWatch } from './pullRequestEvents.js'
+import { modelMatches } from './rules.js'
import { roleNameOf } from './instructions.js'
import { reviewerCandidates } from './reviewerPick.js'
import { stepName } from './steps.js'
@@ -151,6 +152,16 @@ function takes(state: SuperTabState, member: Agent, rules: DispatchRules): (lane
return own ? lane => lane !== null && laneNamed(rules.lanes, own) === lane : () => true
}
+/** Whether [group] is big, hard or risky work, which Routing puts on Opus or Astra: the PM marked it strong, or it wants two reviews
+ * and the PM did not mark it standard (#3576). */
+const needsStrongModel = (group: Conversation): boolean => group.task?.strength === 'strong' || (group.task?.strength === undefined && reviewsWanted(group.task) === 2)
+/** Whether [member] runs a model Routing allows for big or risky work: Opus at high effort or above, or Astra at xhigh (an effort
+ * not set is not known to be either). */
+const onStrongModel = (member: Agent): boolean => {
+ const effort = (member.configuration.effort ?? '').toLowerCase(), model = member.configuration.model
+ return (modelMatches('opus', model) && ['high', 'xhigh', 'max'].includes(effort)) || (modelMatches('astra', model) && ['xhigh', 'max'].includes(effort))
+}
+
/** The tasks [member] could be handed now, best first: those pinned to it (oldest pin first), then its lane's open tasks.
* A task it just lost to the 3-hour clock is not offered to it. */
export function candidatesFor(state: SuperTabState, member: Agent, rules: DispatchRules, now: number, open = openTasks(state, agentProjectId(state, member)!, now),
@@ -169,7 +180,7 @@ export function candidatesFor(state: SuperTabState, member: Agent, rules: Dispat
const lane = open.filter(g => (!g.lane || !!laneNamed(rules.lanes, g.lane)) && !g.reviewOf && !pinned.includes(g) && !(pinOf(g) && members.has(pinOf(g)!.agentId)) && !lostByIt(g)
// Ordinary workers recover work; new tasks still need the PM's route or a standing crew lane.
&& (member.crew || (g.assignment?.status === 'lost' && g.lostAttempt))
- && acceptsLane(laneOf(g, rules.lanes)))
+ && acceptsLane(laneOf(g, rules.lanes)) && (!needsStrongModel(g) || onStrongModel(member)))
// Team-written code goes to Team accounts only (teamWritten.ts); a pick refused this round is not sent again (store.ts).
const allowed = (group: Conversation) => (!group.reviewOf || steps.includes(group)) && !barredFromTeamWritten(state, group, member) && !skip(group.id, member.id)
return [...pinned.filter(allowed).map(group => ({ group, why: 'pin' as const })),
diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.ts
index ef2e58fd1..77e68f500 100644
--- a/backend/src/superTabs/model.ts
+++ b/backend/src/superTabs/model.ts
@@ -341,6 +341,9 @@ export interface WorkTask {
constraints: string
owns: string[]
requires?: TaskRequirement
+ /** `strong`: big, hard or risky work, which the crew's dispatch hands only to a member on a strong model (dispatch.ts, #3576); a task
+ * that wants two reviews counts as strong unless this says `standard`. */
+ strength?: 'standard' | 'strong'
/** What its reviews check first, and how many independent reviews it wants: written into its brief (renderWorkTask), which
* whoever opens its review reads. The server opens and counts no review (project instructions, phase 4). */
review?: ReviewPlan
diff --git a/cli/src/superTabs/pmAccounts.ts b/cli/src/superTabs/pmAccounts.ts
index 4fc05233b..d10690f5e 100644
--- a/cli/src/superTabs/pmAccounts.ts
+++ b/cli/src/superTabs/pmAccounts.ts
@@ -15,6 +15,8 @@ const list = (value: unknown): Json[] => Array.isArray(value) ? value.map(object
const text = (value: unknown): string | undefined => typeof value === 'string' && value ? value : undefined
export const PM_ACCOUNT_NOTE = (pms: string[]) => `This account runs the PM of ${pms.join(' and ')}.`
+/** Whether [p] spends an account a project's PM runs on (withPmAccounts). */
+export const runsPm = (p: Pick<Probe, 'notes'>): boolean => p.notes.some(n => n.startsWith(PM_ACCOUNT_NOTE([]).slice(0, 'This account runs the PM of'.length)))
/** The PM accounts the read carries, or, from an older backend, those of the projects the reader sees (a Swarm from before
* projects has one, its Lead conversation `lead`). */
diff --git a/cli/src/superTabs/route.ts b/cli/src/superTabs/route.ts
index 8304a3cb4..e161a0729 100644
--- a/cli/src/superTabs/route.ts
+++ b/cli/src/superTabs/route.ts
@@ -74,7 +74,7 @@ export interface Probe {
/** A model the catalog does not rate: a person named it, or a member runs it. */
unrated?: true
/** Members: the frame (null when it could not be read), whether the member is in the task's repository, and its earlier work in this Super Tab. */
- frame?: MemberFrame | null; repo?: 'same' | 'different' | 'unknown'; earlier?: Array<{ group: string; outcome: string }>
+ frame?: MemberFrame | null; repo?: 'same' | 'different' | 'unknown'; earlier?: Array<{ group: string; groupId?: string; outcome: string }>
terminalUnverified?: boolean
/** What the machine has: for new agents, and for members where their machine's reading is known. */
load?: MachineLoad
@@ -208,7 +208,8 @@ function pluginAdjustments<T extends Probe & { fit: Fit }>(ranked: T[], plugins:
}
/** 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 }
+/** `order`: the route's pick by the Routing order (routePick.ts, task #3576), with `pick` (a candidate's id) and `reasons`, one per step. */
+export interface Verdict { via: 'instructions' | 'only' | 'order'; p: null; why: string; pick?: string; reasons?: string[] }
const LEVELS: Level[] = ['low', 'medium', 'high']
const HEAVY_WORK: unknown[] = ['build', 'e2e'] satisfies HeavyWork[]
@@ -552,7 +553,7 @@ function modelTier(p: Probe, catalog: Catalog): Tier | null {
}
/** How well a candidate fits [tier]: 0 on the tier's model and effort, 1 on neither tier's model or the tier's at another
* effort, 2 on the other tier's model. */
-function fitRank(p: Probe, catalog: Catalog, tier: Tier): 0 | 1 | 2 {
+export function fitRank(p: Probe, catalog: Catalog, tier: Tier): 0 | 1 | 2 {
const runs = modelTier(p, catalog)
if (runs === null) return 1
if (runs !== tier) return 2
@@ -591,7 +592,7 @@ export function machineBrief(room: MachineRoom): string {
/** A quota's weekly window, the one the project's order compares: its percent left and reset, or a reading with no windows
* named as one; null left when it was not read. */
-function weekly(q: Quota): { left: number | null; resetsAt: number | null } {
+export function weekly(q: Quota): { left: number | null; resetsAt: number | null } {
const week = q.windows?.find(w => w.name === 'weekly')
const left = !q.known ? null : week ? week.leftPercent : q.windows?.length ? null : q.leftPercent
return { left, resetsAt: week ? week.resetsAt : q.resetsAt }
@@ -700,6 +701,13 @@ export function decide(choice: Choice): Verdict {
: { via: 'instructions', p: null, why: choice.adjusted ? `${CHOOSE_BY_INSTRUCTIONS} Plug-ins' findings are in each candidate's notes.` : CHOOSE_BY_INSTRUCTIONS }
}
+/** The verdict with the route's pick (task #3576, anh Dee 11-06): the candidate [picked] names, by the Routing order, with its reasons.
+ * With no pick (nothing has the quota the work needs) or one candidate, the verdict is [decide]'s, as before. */
+export function decideByOrder(choice: Choice, picked: { id: string; reasons: string[] } | null): Verdict {
+ if (!picked || choice.shown.length === 1) return decide(choice)
+ return { via: 'order', p: null, why: cut(picked.reasons.join(' '), 300), pick: picked.id, reasons: picked.reasons }
+}
+
/** The record in the shape a backend takes: `current` with the job's kind (what attempts are compared by, backend costs/read.ts),
* no pick (task #2901) and each candidate's weekly % left and reset in its fit (task #3163: without them quota at route time
* could not be measured); `unquoted` the same without them, for a backend from before them; `picked` for a backend from before
@@ -718,7 +726,8 @@ export function recordOf(choice: Choice, verdict: Verdict, a: Assessment, shape:
...(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,
- ...(pickless ? { via: verdict.via } : { pick: choice.shown[0]!.id, via: verdict.via === 'only' ? 'only' : 'order' }),
+ ...(verdict.pick && choice.shown.some(c => c.id === verdict.pick) ? { pick: verdict.pick, via: 'order' }
+ : pickless ? { via: verdict.via } : { pick: choice.shown[0]!.id, via: verdict.via === 'only' ? 'only' : 'order' }),
p: verdict.p, belowFloor: false, why: cut(verdict.why, 300),
}
}
diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.ts
index 2a944ab6c..1d5be3694 100644
--- a/cli/src/superTabs/routeCommand.spec.ts
+++ b/cli/src/superTabs/routeCommand.spec.ts
@@ -112,7 +112,7 @@ describe('routeTask', () => {
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: 'instructions', p: null, candidates: expect.arrayContaining([expect.objectContaining({ id: 'c0' })]), warnings: ['w'] })
+ expect(result).toMatchObject({ ok: true, routeDecisionId: 'd1', via: 'order', 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)
@@ -131,7 +131,7 @@ describe('routeTask', () => {
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, 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.'] })
+ 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.
@@ -452,11 +452,11 @@ describe('routeTask', () => {
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')
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"')
+ // The chosen row's agent; the route names the pick (task #3576), so no rule is asked for.
+ expect(member.next).toContain('"type":"work.assign","conversationId":"g1","agentId":"AGENT","routeDecisionId":"d1"}')
const fresh = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high' } }, scoped({ policy: floorPolicy }), where as never, opener(), () => 'op')
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"')
+ expect(fresh.next).toContain('"machineId":"MACHINE","engine":"ENGINE","model":"MODEL","effort":"EFFORT","routeDecisionId":"d1"}')
// 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')
@@ -464,7 +464,7 @@ describe('routeTask', () => {
const hint = JSON.parse(/start OPERATION_ID (\{.*\}), then/.exec(fresh.next as string)![1]!)
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: 'MACHINE', engine: 'ENGINE', model: 'MODEL', effort: 'EFFORT', routeDecisionId: 'd1', overrideReason: 'RULE' })
+ machineId: 'MACHINE', engine: 'ENGINE', model: 'MODEL', effort: 'EFFORT', routeDecisionId: 'd1' })
// 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.
@@ -736,7 +736,7 @@ describe('routeTask', () => {
expect(quoted.command.decision.candidates[0].fit).toHaveProperty('left')
expect(quoted.command.decision.candidates[0].fit).toHaveProperty('resetsAt')
expect(unquoted.operationId).toBe(quoted.operationId)
- expect(unquoted.command.decision).not.toHaveProperty('pick')
+ expect(unquoted.command.decision).toHaveProperty('pick')
expect(unquoted.command.decision.candidates[0].fit).not.toHaveProperty('left')
expect(unquoted.command.decision.candidates[0].fit).toHaveProperty('status')
})
@@ -758,15 +758,15 @@ describe('routeTask', () => {
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' })
- // With no pick, then without the candidates' quota (task #3163), then with c0 standing in for one (task #2901), then in the
+ // With the pick (task #3576), then without the candidates' quota (task #3163), then with c0 standing in for one, then in the
// shape from before phase 1.
const [current, unquoted, phase1, v1] = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0])
- expect(current.command.decision).not.toHaveProperty('pick')
- expect(unquoted.command.decision).not.toHaveProperty('pick')
- expect(phase1.command.decision).toMatchObject({ pick: 'c0', assessment: { size: 'medium' } })
+ expect(current.command.decision).toHaveProperty('pick')
+ expect(unquoted.command.decision).toHaveProperty('pick')
+ expect(phase1.command.decision).toMatchObject({ pick: expect.stringMatching(/^c\d+$/), 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).toMatchObject({ pick: expect.stringMatching(/^c\d+$/), via: 'order' })
expect(v1.command.decision.assessment).not.toHaveProperty('size')
expect(v1.command.decision.candidates.some((c: object) => 'fit' in c)).toBe(false)
})
@@ -800,10 +800,10 @@ describe('routeTask', () => {
})
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: 'instructions', unrecorded: true })
+ expect(result).toMatchObject({ ok: true, via: 'order', 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: 'instructions', unrecorded: true })
+ expect(lost).toMatchObject({ ok: true, via: 'order', unrecorded: true })
})
it('says when one candidate is the only one that can run the task', async () => {
const s = scoped()
@@ -897,32 +897,30 @@ 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)', () => {
+// Anh Dee, 2026-11-06 (task #3576): rules that can be checked run as code. The route picks by the Routing order (routePick.ts), so
+// the pick is first in the answer with its reasons, and the PM follows it or gives a reason for another candidate.
+describe('route answers with the pick (task #3576, after #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 () => {
+ it('lists every candidate by machine, with the pick first and its reasons, and records the pick', 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')
+ expect(answer).toMatchObject({ ok: true, routeDecisionId: 'd1', via: 'order', p: null, pick: { id: expect.stringMatching(/^c\d+$/), title: expect.any(String) },
+ reasons: [expect.stringMatching(/^1\. Need:/), expect.stringMatching(/^2\. Quota:/), expect.stringMatching(/^3\. Idle:/), expect.stringMatching(/^4\. Load and price:/)] })
+ expect(Object.keys(answer).slice(0, 4)).toEqual(['ok', 'routeDecisionId', 'pick', 'reasons'])
const rows = answer.candidates as Row[]
- // mac (m2) before remote-1 (m1), whatever is stronger or cheaper.
+ // The candidates stay in the neutral order, 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)
+ expect(decision).toMatchObject({ via: 'order', pick: (answer.pick as { id: string }).id, why: answer.why })
+ expect(rows.some(r => r.id === (answer.pick as { id: string }).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')
@@ -931,27 +929,17 @@ describe('route answers with no pick (task #2901)', () => {
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 () => {
+ it('says how to start or assign the pick, and that another candidate needs a reason', 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"')
+ expect(next).toContain('"type":"work.assign","conversationId":"g1","agentId":"AGENT","routeDecisionId":"d1"}')
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, unquoted, picked] = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0])
- expect(current.command.decision).not.toHaveProperty('pick')
- expect(unquoted.command.decision).not.toHaveProperty('pick')
- expect(picked.command.decision).toMatchObject({ pick: 'c0', via: 'order' })
- expect(picked.operationId).toBe(current.operationId)
- // The candidates as the record without their quota sent them (task #3163).
- expect(picked.command.decision.candidates).toEqual(unquoted.command.decision.candidates)
+ expect(hint).toMatchObject({ conversationId: 'g1', machineId: 'MACHINE', engine: 'ENGINE', model: 'MODEL', effort: 'EFFORT', routeDecisionId: 'd1' })
+ expect(hint).not.toHaveProperty('overrideReason')
+ expect(next).toContain(`the pick (${(answer.pick as { id: string }).id})`)
+ expect(next).toMatch(/another candidate.*overrideReason/)
+ // Until the machine rules are in the rules record, the pick does not apply them: the instructions' Machines section still does (review 2 of #3296).
+ expect(next).toMatch(/Machines rules.*still apply.*pick that breaks one.*overrideReason/s)
})
})
@@ -1021,6 +1009,18 @@ describe('what the route log says about each candidate', () => {
// Multiply's earlier work in this Super Tab: the finished assignment (also in the log), and the log's one in a group this tab no longer has.
expect(memberLabel(s)).toContain('earlier here: API done; another group done')
})
+ // Review 2 of #3296: the pick's "work that follows on" rule compares the route's own group by id; the label shows its title.
+ it('picks the member that worked on this very task before, whatever its account, because the earlier work carries the task\'s id', async () => {
+ const decision = { id: 'd6', conversationId: 'g1', title: 'Pick d6', via: 'order', outcome: 'done', assignmentId: 'x', createdAt: '2026-10-19T10:00:00Z',
+ final: { kind: 'member', agentId: 'a1' } }
+ // At high effort: the fixture's Sonnet at medium is not a candidate the pick may take.
+ const t = tab(); t.state.agents = [{ ...agents[0], configuration: { engine: 'claude', model: 'sonnet', effort: 'high' } }, agents[1], agents[2]] as never
+ const s = scoped(world({ tab: t, decisions: [decision] }, { id: 'x', agentId: 'a1', status: 'done', result: 'Shipped.' }))
+ const answer = await routeTask(input, s, where as never, opener(), () => 'op')
+ const pick = (answer.candidates as Array<{ id: string; agentId?: string }>).find(c => c.id === (answer.pick as { id: string }).id)
+ expect(pick).toMatchObject({ agentId: 'a1' })
+ expect((answer.reasons as string[])[2]).toContain('worked on this task before')
+ })
it('labels a member with the effort it was launched with when it reports none, and keeps an effort it reports', async () => {
const label = async (effort: string | undefined, start: unknown) => {
const t = tab(); t.state.agents = [{ ...agents[0], configuration: { engine: 'claude', model: 'sonnet', effort } }, agents[1]] as never
@@ -2423,9 +2423,9 @@ describe('the route answer an agent reads (task #3294)', () => {
expect(line).toMatch(new RegExp(`^${row.id} ${row.kind === 'new' ? 'new' : `\\S+ \\(agent ${row.agentId}, idle\\)`} · ${row.engine} ${row.model} ${row.effort} · `))
expect(machine).toMatch(new RegExp(`· machineId ${row.machineId} · 2 agents$`))
}
- // The why of an unranked route is the next's first sentence; the record keeps it whole.
+ // A pick's why is its reasons, which the answer prints; an unranked route's is the next's first sentence. The record keeps it whole.
expect(printed).not.toHaveProperty('why')
- expect(printed.next).toMatch(/^Not ranked: listed by machine name\. Choose one by the project's Routing instructions \(Order and quota\)/)
+ expect(printed.next).toMatch(/^Use the pick \(c\d+\), chosen by the project's Routing order/)
expect(routeAnswer({ ok: true, via: 'only', why: 'Only candidate that can run this task.' })).toMatchObject({ why: 'Only candidate that can run this task.' })
// The folder a start takes is said once when every machine shares it (a live route: 23 machines, one folder of 85 characters).
expect(printed.cwd).toBe('/absolute/repo/on/that/machine')
diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.ts
index c56a77206..7f796730e 100644
--- a/cli/src/superTabs/routeCommand.ts
+++ b/cli/src/superTabs/routeCommand.ts
@@ -10,7 +10,8 @@ import { START_DEADLINE_MS, START_WINDOW_MS } from './reservations.js'
import { inspectCapacity, type ScopedRequest } from './start.js'
import { ENDED_WORK, object, within } from './wire.js'
import { withPmAccounts } from './pmAccounts.js'
-import { accountOf, API_BUILDERS, bytes, machineBrief, catalogFrom, catalogRow, choose, decide, gridStrength, parseAssessment, OLD_RECORD_MAX, quotaBrief, quotaLine, quotaOf2, recentStartNotes, UNRATED, recordOf, repoMatch, repositoryKey, type Assessment, type Catalog, type CatalogModel, type RecordShape, type Commitment, type Excluded, type Shown, type HeldModel, type MemberFrame, type Probe, type TaskFolder } from './route.js'
+import { accountOf, API_BUILDERS, bytes, machineBrief, catalogFrom, catalogRow, choose, decideByOrder, gridStrength, parseAssessment, OLD_RECORD_MAX, quotaBrief, quotaLine, quotaOf2, recentStartNotes, UNRATED, recordOf, repoMatch, repositoryKey, type Assessment, type Catalog, type CatalogModel, type RecordShape, type Commitment, type Excluded, type Shown, type HeldModel, type MemberFrame, type Probe, type TaskFolder } from './route.js'
+import { pickByOrder } from './routePick.js'
import { 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'
@@ -264,20 +265,21 @@ const finite = (value: unknown): value is number => typeof value === 'number' &&
* attempts and each group's last assignment, joined by assignment id. The log knows which agent a decision started; the
* attempts are every earlier assignment of this group, also those `work.define` took out of the state (a person's
* assignment has no decision); the state knows the agent of each group's last one. */
-interface Ended { assignmentId: string; group: string; agentId: string | null; outcome: string }
+/** `group` is the group's title, for the printed note; `groupId` its id, which the pick compares with the routed task (routePick.ts). */
+interface Ended { assignmentId: string; group: string; groupId: string; agentId: string | null; outcome: string }
function endedWork(conversations: Json[], decisions: Json[] | null, attempts: Json[] | null, attemptsGroup: string): Ended[] {
const titleOf = (id: unknown) => String(conversations.find(c => c.id === id)?.title ?? 'another group')
const ended: Ended[] = [...(decisions ?? [])].reverse().flatMap(d => {
const final = object(d.final)
return typeof d.assignmentId === 'string' && ENDED_WORK.includes(String(d.outcome)) && final.kind
- ? [{ assignmentId: d.assignmentId, group: titleOf(d.conversationId), outcome: String(d.outcome), agentId: final.kind === 'member' ? String(final.agentId) : null }]
+ ? [{ assignmentId: d.assignmentId, group: titleOf(d.conversationId), groupId: String(d.conversationId), outcome: String(d.outcome), agentId: final.kind === 'member' ? String(final.agentId) : null }]
: []
})
// The assignment's own record wins on the agent: a started agent is a member by then.
const join = (assignment: Json, groupId: string) => {
const known = ended.find(e => e.assignmentId === assignment.id)
if (known) return Object.assign(known, { agentId: String(assignment.agentId) })
- const added: Ended = { assignmentId: String(assignment.id), group: titleOf(groupId), agentId: String(assignment.agentId), outcome: String(assignment.status) }
+ const added: Ended = { assignmentId: String(assignment.id), group: titleOf(groupId), groupId, agentId: String(assignment.agentId), outcome: String(assignment.status) }
ended.push(added)
return added
}
@@ -480,7 +482,7 @@ export async function routeTask(input: { tabId: string; conversationId: string;
const probes = probed.flat()
.map(p => p.kind === 'member' ? { ...p, repo: repoMatch(folder, p.frame ?? null, p.machineId === where.machineId),
notes: [...p.notes, ...limited(p.agentId), ...lostTask(p.agentId)],
- earlier: ended.filter(e => e.agentId === p.agentId).reverse().slice(0, 3).map(e => ({ group: e.group, outcome: e.outcome })) } : p)
+ earlier: ended.filter(e => e.agentId === p.agentId).reverse().slice(0, 3).map(e => ({ group: e.group, groupId: e.groupId, outcome: e.outcome })) } : p)
probes.push(...localProbes(state, catalog, probes))
// The task's requirement is not enforced (project instructions, Routing): a candidate elsewhere, or a member whose start
// did not have its machine check the required device, says so. A Mac's Harness Team account is that Mac.
@@ -522,7 +524,9 @@ export async function routeTask(input: { tabId: string; conversationId: string;
if ('error' in choice) return { ...choice, ...(skipped.length ? { warnings: skipped } : {}), leftOut: leftOut(choice.excluded, []),
...required.machines || required.devices.length ? { waiting: true, detail: WAITING } : {},
...ciHeld ? { waiting: true, retryAfterMinutes: CI_RETRY_MINUTES, detail: ciHeld.reason.slice(MACHINE_FIT_MAKER.name.length + 2) } : {} }
- const verdict = decide(choice)
+ // The pick by the project's Routing order (routePick.ts, task #3576): the recorded candidate that start or assignment follows.
+ const verdict = decideByOrder(choice, pickByOrder({ shown: choice.shown, catalog, assessment: { ...assessment, ended: endedAttempts(group, attempts) }, now,
+ conversationId: input.conversationId }))
const operationId = `route-${newId()}`
// The rows recorded are the rows offered: the agent choosing assigns by a recorded candidate.
let offered = choice.shown
@@ -563,6 +567,7 @@ export async function routeTask(input: { tabId: string; conversationId: string;
const shownRows = offered
return {
ok: true, ...(typeof routeDecisionId === 'string' ? { routeDecisionId } : { unrecorded: true }),
+ ...(verdict.pick ? { pick: { id: verdict.pick, title: shownRows.find(s => s.id === verdict.pick)?.title }, reasons: verdict.reasons } : {}),
...(instructions ? { instructions } : { instructionsUnreadable: true }),
via: verdict.via, p: verdict.p, why: verdict.why,
candidates: shownRows.map(publicOf),
@@ -571,17 +576,22 @@ export async function routeTask(input: { tabId: string; conversationId: string;
...(catalog.models.length ? [] : [CATALOG_UNREADABLE]),
...(choice.shown.some(p => p.kind === 'member' && p.terminalUnverified) ? ["A member's terminal could not be verified from its machine's snapshot. Check it before assignment."] : []),
...(choice.short ? [choice.short] : []), ...skipped],
- next: nextOf(shownRows, input.conversationId, typeof routeDecisionId === 'string' ? routeDecisionId : undefined, !!instructions, assessment.needs),
+ next: nextOf(shownRows, input.conversationId, typeof routeDecisionId === 'string' ? routeDecisionId : undefined, !!instructions, assessment.needs, verdict.pick),
}
}
/** 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 {
+function nextOf(rows: Shown[], conversationId: string, routeDecisionId: string | undefined, instructions: boolean, needs: Assessment['needs'], pick?: string): string {
// Said once and short (task #3294): it rode on every route, 467 a day in one PM's context.
- const choose = 'Not ranked: listed by machine name. Choose one by the project\'s Routing instructions (Order and quota), and give the rule that chose it as overrideReason.'
- const decided = routeDecisionId ? { routeDecisionId, overrideReason: 'RULE' } : {}
+ const choose = pick
+ ? `Use the pick (${pick}), chosen by the project's Routing order: start or assign it as listed, with no overrideReason. `
+ + 'The pick does not apply the instructions\' Machines rules (hours a machine is off, phone work on the phone Mac, no Codex on a named Mac, no reviewing on a local-model Codex): '
+ + 'they still apply, and a pick that breaks one is not used; choose another candidate and give that rule as overrideReason. '
+ + 'For any other candidate, give the reason as overrideReason (urgency, context, a machine the work needs; "idle" is not one).'
+ : 'Not ranked: listed by machine name. Choose one by the project\'s Routing instructions (Order and quota), and give the rule that chose it as overrideReason.'
+ const decided = routeDecisionId ? pick ? { routeDecisionId } : { routeDecisionId, overrideReason: 'RULE' } : {}
const assign = `Assign a member: command OPERATION_ID ${JSON.stringify({ type: 'work.assign', conversationId, agentId: 'AGENT', ...decided })}`
// No fixed role name: NAME and ROLE are the agent's to fill from the project's instructions. A backend without instructions
// takes no roleName (it came with them, phase 2).
@@ -590,7 +600,7 @@ function nextOf(rows: Shown[], conversationId: string, routeDecisionId: string |
machineId: 'MACHINE', engine: 'ENGINE', model: 'MODEL', effort: 'EFFORT', ...decided })}, then assign it${routeDecisionId ? ' with the same routeDecisionId' : ''}. `
+ 'MACHINE is its machine\'s machineId, CWD the cwd its machine names or else the answer\'s; ENGINE, MODEL and EFFORT its line\'s; a grid line takes its gridModel and gridName in place of model and effort. '
+ `NAME is the agent's name${instructions ? ', ROLE its role in the instructions' : ''}. It starts from the default branch, fetched first; add "branchRef":"refs/remotes/origin/BRANCH" for another.`
- const rule = routeDecisionId ? ' RULE: the Routing rule that chose it.' : ''
+ const rule = routeDecisionId && !pick ? ' RULE: the Routing rule that chose it.' : ''
return [choose, ...(rows.some(r => r.kind === 'member') ? [assign] : []), ...(rows.some(r => r.kind === 'new') ? [start] : [])].join(' ') + rule
}
@@ -869,7 +879,7 @@ export function routingSection(text: string): string | null {
export function routeAnswer(answer: Json, options: { fullInstructions?: boolean; instructionsRead?: number } = {}): Json {
const { instructions, candidates, leftOut: out, excluded, warnings, p, why, ...rest } = answer
// An unranked route's why is its next's first sentence; the record keeps it whole.
- const printed: Json = { ...rest, ...(p === null || p === undefined ? {} : { p }), ...(why === undefined || answer.via === 'instructions' ? {} : { why }) }
+ const printed: Json = { ...rest, ...(p === null || p === undefined ? {} : { p }), ...(why === undefined || answer.via === 'instructions' || answer.via === 'order' ? {} : { why }) }
const written = instructions && typeof instructions === 'object' ? object(instructions) : null
if (written) {
const notes = Array.isArray(written.notes) ? written.notes.map(n => String(object(n).text ?? n)) : []
diff --git a/cli/src/superTabs/routePick.spec.ts b/cli/src/superTabs/routePick.spec.ts
new file mode 100644
index 000000000..bc8707512
--- /dev/null
+++ b/cli/src/superTabs/routePick.spec.ts
@@ -0,0 +1,189 @@
+// cli/src/superTabs/routePick.spec.ts
+import { describe, expect, it } from 'vitest'
+import { PM_ACCOUNT_NOTE } from './pmAccounts.js'
+import { pickByOrder, type PickInput } from './routePick.js'
+import { decide, decideByOrder, recordOf, type Assessment, type Catalog, type Choice, type Shown } from './route.js'
+
+const NOW = 1_000_000_000, H = 3_600_000, D = 86_400_000
+const catalog: Catalog = { grid: { strength: 2, models: [{ model: 'kimi k3', strength: 2 }] }, models: [
+ { engine: 'claude', model: 'sonnet', effort: 'high', strength: 2, cost: 2, offered: true },
+ { engine: 'claude', model: 'opus', effort: 'high', strength: 3, cost: 3, offered: true },
+ { engine: 'codex', model: 'gpt-6.1-sol', effort: 'high', strength: 2, cost: 2, offered: true },
+ { engine: 'codex', model: 'gpt-6-astra', effort: 'xhigh', strength: 3, cost: 3, offered: true },
+] }
+const small = (patch: Partial<Assessment> = {}): Assessment => ({ difficulty: 'low', risk: 'low', size: 'small', why: 'Fix a typo.', kind: 'fix',
+ needs: { tools: [], devices: [] }, ...patch })
+const big = (patch: Partial<Assessment> = {}): Assessment => small({ difficulty: 'high', size: 'large', why: 'Rebuild the sync.', kind: 'feature', ...patch })
+
+let n = 0
+/** A shown candidate: a new Claude Sonnet on its own account unless the patch says otherwise. [left] and [resets] are the weekly window. */
+function row(patch: Partial<Shown> & { left?: number | null; resets?: number | null; account?: string; agents?: number } = {}): Shown {
+ const { left = 50, resets = NOW + 3 * D, account, agents, ...rest } = patch
+ const id = `c${n++}`
+ return { id, title: id, label: id, kind: 'new', machineId: 'm1', machineName: 'mac-1', engine: 'claude', model: 'sonnet', effort: 'high', quality: 2, cost: 2,
+ quota: { known: left !== null, leftPercent: left, resetsAt: resets, account: account ?? id,
+ windows: left === null ? [] : [{ name: 'weekly', leftPercent: left, resetsAt: resets }] },
+ activity: 'new agent', known: true, refusals: [], notes: [], load: { agents: agents ?? 0, freeMemoryBytes: null, hasFolder: null },
+ fit: { status: 'fits', coverage: null, effectiveCost: 2, expiring: 0, spend: { '5-hour': 0, weekly: 0 }, account: account ?? id }, ...rest } as Shown
+}
+const grid = (patch: Partial<Shown> = {}): Shown => row({ model: 'default', effort: 'default', cost: 1, gridModel: 'moonshotai/kimi-k3', gridName: 'swarm', gridLabel: 'Kimi K3',
+ gridKind: 'api', quota: { known: false, leftPercent: null, resetsAt: null }, ...patch })
+const opus = (patch: Parameters<typeof row>[0] = {}) => row({ model: 'opus', quality: 3, cost: 3, ...patch })
+const astra = (patch: Parameters<typeof row>[0] = {}) => row({ engine: 'codex', model: 'gpt-6-astra', effort: 'xhigh', quality: 3, cost: 3, ...patch })
+const sol = (patch: Parameters<typeof row>[0] = {}) => row({ engine: 'codex', model: 'gpt-6.1-sol', ...patch })
+const pick = (shown: Shown[], assessment: Assessment = small(), extra: Partial<PickInput> = {}) =>
+ pickByOrder({ shown, catalog, assessment, now: NOW, conversationId: 'g1', ...extra })
+
+describe('pickByOrder step 1: what the work needs', () => {
+ it('small work goes to a grid model when one is offered, else to Sonnet or Sol at high effort', () => {
+ const g = grid(), s = row(), o = opus()
+ expect(pick([s, o, g])!.id).toBe(g.id)
+ expect(pick([o, s])!.id).toBe(s.id)
+ })
+
+ it('big, hard or risky work goes to Opus high or Astra xhigh, never to a grid model or the smaller model', () => {
+ const o = opus(), a = astra(), s = row(), g = grid()
+ expect([o.id, a.id]).toContain(pick([s, g, o, a], big())!.id)
+ expect(pick([s, g, o], big({ difficulty: 'low', risk: 'high', size: 'small' }))!.id).toBe(o.id)
+ })
+
+ it('a review goes to the strong tier and never to a grid model, even when nothing else is offered', () => {
+ const o = opus(), g = grid()
+ expect(pick([g, o], small({ kind: 'review' }))!.id).toBe(o.id)
+ expect(pick([g], small({ kind: 'review' }))).toBeNull()
+ })
+
+ // Review of #3296 (SecReview3293): "nothing below high effort, no Haiku" is a rule of step 1, so a pool of only those names no pick.
+ it('never picks a candidate below high effort or on Haiku, unless a person named the model; with only those, there is no pick', () => {
+ for (const low of ['minimal', 'low', 'medium']) expect(pick([row({ effort: low })])).toBeNull()
+ expect(pick([row({ model: 'haiku', effort: 'high' })])).toBeNull()
+ expect(pick([opus({ effort: 'medium' })], big())).toBeNull()
+ const fine = row({ left: 5, resets: NOW + 6 * D })
+ expect(pick([row({ model: 'haiku' }), row({ effort: 'medium' }), fine])!.id).toBe(fine.id)
+ const haiku = row({ model: 'haiku' })
+ expect(pick([haiku], small({ model: 'haiku' }))!.id).toBe(haiku.id)
+ })
+
+ it('a model at the wrong effort comes after one at the tier\'s effort', () => {
+ const low = row({ effort: 'medium' }), high = row()
+ expect(pick([low, high])!.id).toBe(high.id)
+ })
+})
+
+describe('pickByOrder step 2: accounts with weekly quota left', () => {
+ it('takes the account resetting soonest, then the one with the most left', () => {
+ const later = row({ left: 90, resets: NOW + 5 * D }), sooner = row({ left: 20, resets: NOW + 1 * D }), soonerMore = row({ left: 60, resets: NOW + 1 * D })
+ expect(pick([later, sooner, soonerMore])!.id).toBe(soonerMore.id)
+ expect(pick([later, sooner])!.id).toBe(sooner.id)
+ })
+
+ it('leaves out an account under 5% for big work and under 2% for small work, a review or a test', () => {
+ const low = row({ left: 4, resets: NOW + 1 * D }), fine = row({ left: 30, resets: NOW + 4 * D })
+ expect(pick([low, fine])!.id).toBe(low.id)
+ const lowO = opus({ left: 4, resets: NOW + 1 * D }), fineO = opus({ left: 30, resets: NOW + 4 * D })
+ expect(pick([lowO, fineO], big())!.id).toBe(fineO.id)
+ const nearZero = row({ left: 1, resets: NOW + 1 * D })
+ expect(pick([nearZero, fine])!.id).toBe(fine.id)
+ expect(pick([lowO, fineO], small({ kind: 'review' }))!.id).toBe(lowO.id)
+ expect(pick([opus({ left: 1.5, resets: NOW + 1 * D }), fineO], small({ kind: 'test' }))!.id).toBe(fineO.id)
+ })
+
+ it('an account that runs a PM takes no new work under 20%', () => {
+ const pm = row({ left: 15, resets: NOW + 1 * D, notes: [PM_ACCOUNT_NOTE(['lamp (Faye)'])] }), other = row({ left: 40, resets: NOW + 4 * D })
+ expect(pick([pm, other])!.id).toBe(other.id)
+ const pmRich = row({ left: 25, resets: NOW + 1 * D, notes: [PM_ACCOUNT_NOTE(['lamp (Faye)'])] })
+ expect(pick([pmRich, other])!.id).toBe(pmRich.id)
+ })
+
+ it('an account whose quota is unknown comes after every account with a reading, and is picked when it is all there is', () => {
+ const unknown = row({ left: null, resets: null }), known = row({ left: 10, resets: NOW + 6 * D })
+ expect(pick([unknown, known])!.id).toBe(known.id)
+ expect(pick([unknown])!.id).toBe(unknown.id)
+ })
+
+ it('names no pick when no account has the quota the work needs', () => {
+ expect(pick([row({ left: 1 }), row({ left: 0 })])).toBeNull()
+ })
+
+ it('a later step never overrides an earlier one: a better account loses to a better-fitting model', () => {
+ const rightModel = row({ left: 10, resets: NOW + 6 * D }), wrongModel = opus({ left: 90, resets: NOW + 1 * D })
+ expect(pick([wrongModel, rightModel])!.id).toBe(rightModel.id)
+ })
+})
+
+describe('pickByOrder step 3: an idle agent is reused only between equals', () => {
+ const idle = (patch: Parameters<typeof row>[0] = {}) => row({ kind: 'member', agentId: 'ada', name: 'Ada', activity: 'idle', ...patch })
+
+ it('reuses an idle agent over a new one on the same account', () => {
+ const member = idle({ account: 'acct' }), fresh = row({ account: 'acct' })
+ expect(pick([fresh, member])!.id).toBe(member.id)
+ })
+
+ it('does not reuse an idle agent on a worse account: a better account wins first', () => {
+ const member = idle({ left: 20, resets: NOW + 5 * D }), fresh = row({ left: 20, resets: NOW + 1 * D })
+ expect(pick([member, fresh])!.id).toBe(fresh.id)
+ })
+
+ it('reuses the same reviewer for its next round, and an agent for work that follows on, whatever its account', () => {
+ const member = idle({ left: 20, resets: NOW + 5 * D, earlier: [{ group: 'Title of g1', groupId: 'g1', outcome: 'changes requested' }] }), fresh = opus({ left: 90, resets: NOW + 1 * D })
+ expect(pick([fresh, { ...member, model: 'opus', quality: 3 } as Shown], small({ kind: 'review' }))!.id).toBe(member.id)
+ const other = idle({ left: 20, resets: NOW + 5 * D, earlier: [{ group: 'Title of g9', groupId: 'g9', outcome: 'done' }] })
+ expect(pick([fresh, { ...other, model: 'opus', quality: 3 } as Shown], small({ kind: 'review' }))!.id).toBe(fresh.id)
+ expect(pick([row({ left: 90, resets: NOW + 1 * D }), member])!.id).toBe(member.id)
+ })
+
+ it('the exception still needs the model and the quota the work needs', () => {
+ const wrong = idle({ model: 'haiku', earlier: [{ group: 'Title of g1', groupId: 'g1', outcome: 'done' }] }), fresh = row()
+ expect(pick([wrong, fresh])!.id).toBe(fresh.id)
+ })
+})
+
+describe('pickByOrder step 4: fewer agents working, then price', () => {
+ it('between equals takes the machine with fewer agents working', () => {
+ const busy = row({ account: 'acct', agents: 3, machineId: 'm1' }), quiet = row({ account: 'acct', agents: 1, machineId: 'm2' })
+ expect(pick([busy, quiet])!.id).toBe(quiet.id)
+ })
+
+ it('then the lower price', () => {
+ const dear = opus({ account: 'acct', agents: 1 }), cheap = astra({ account: 'acct', agents: 1, cost: 2 })
+ expect(pick([dear, cheap], big())!.id).toBe(cheap.id)
+ })
+})
+
+describe('pickByOrder reasons', () => {
+ it('gives one reason per step, in order, that names what decided it', () => {
+ const a = row({ left: 20, resets: NOW + 1 * D }), b = row({ left: 60, resets: NOW + 4 * D })
+ const result = pick([b, a])!
+ expect(result.id).toBe(a.id)
+ expect(result.reasons).toHaveLength(4)
+ expect(result.reasons[0]).toMatch(/^1\. Need:/)
+ expect(result.reasons[1]).toMatch(/^2\. Quota:.*resets soonest/)
+ expect(result.reasons[2]).toMatch(/^3\. Idle:/)
+ expect(result.reasons[3]).toMatch(/^4\. Load and price:/)
+ })
+
+ it('names nothing for a route with no candidate', () => {
+ expect(pick([])).toBeNull()
+ })
+})
+
+describe('the pick in the verdict and the record', () => {
+ const choice = (shown: Shown[]): Choice => ({ shown, excluded: [], floor: 1, belowFloor: false })
+
+ it('a route with a pick says via order, names the pick and its reasons, and records both', () => {
+ const a = row({ left: 20, resets: NOW + 1 * D }), b = row({ left: 60, resets: NOW + 4 * D })
+ const c = choice([b, a]), picked = pick(c.shown)
+ const verdict = decideByOrder(c, picked)
+ expect(verdict).toMatchObject({ via: 'order', p: null, pick: a.id, reasons: picked!.reasons })
+ expect(verdict.why.length).toBeLessThanOrEqual(300)
+ for (const shape of ['current', 'unquoted'] as const) expect(recordOf(c, verdict, small(), shape)).toMatchObject({ pick: a.id, via: 'order', why: verdict.why })
+ })
+
+ it('a route with nothing to pick, or one candidate, is as it was: no pick', () => {
+ const only = choice([row()])
+ expect(decideByOrder(only, pick(only.shown))).toEqual(decide(only))
+ const two = choice([row({ left: 0 }), row({ left: 1 })])
+ expect(decideByOrder(two, pick(two.shown))).toEqual(decide(two))
+ expect(recordOf(two, decide(two), small())).not.toHaveProperty('pick')
+ })
+})
diff --git a/cli/src/superTabs/routePick.ts b/cli/src/superTabs/routePick.ts
new file mode 100644
index 000000000..5986dc653
--- /dev/null
+++ b/cli/src/superTabs/routePick.ts
@@ -0,0 +1,97 @@
+/**
+ * The route's pick (task #3576, anh Dee 11-06: a rule that can be checked runs as code, not as a prompt the PM follows by
+ * hand). The project's Routing order, "Order and quota", applied to the candidates the route shows:
+ * 1. what the work needs: a model strong enough (Sonnet or Sol at high effort for small work, a grid model first when one is
+ * offered; Opus high or Astra xhigh for big, hard or risky work and for reviews, never a grid model for a review);
+ * 2. every account with weekly quota left: the one resetting soonest, then the one with the most left; a big task needs 5%
+ * left, small work, a review or a test 2%, and an account that runs a PM takes no new work under 20%;
+ * 3. an idle agent is reused only between candidates equal so far, except the same reviewer for its next round and work that
+ * follows straight on from what the agent just did (its earlier work on this task);
+ * 4. between equals, the machine with fewer agents working, then price.
+ * Pure: the route's own facts in, a pick and one reason per step out. The machine rules (hours off, phone work, an engine
+ * forbidden on a Mac) are refusals the route makes before this runs; they are not ranked here.
+ */
+import { runsPm } from './pmAccounts.js'
+import { fitRank, tierOf, weekly, type Assessment, type Catalog, type Shown, type Tier } from './route.js'
+
+const D = 86_400_000, H = 3_600_000
+/** Weekly quota an account needs left to take a big task, and small work, a review or a test (the Routing order). */
+export const BIG_NEEDS = 5, SMALL_NEEDS = 2
+/** Below this much weekly quota left, an account that runs a PM takes no new work. */
+export const PM_RESERVE = 20
+
+/** Efforts below high, which no agent runs at. */
+const BELOW_HIGH = new Set(['minimal', 'low', 'medium'])
+
+export interface PickInput { shown: readonly Shown[]; catalog: Catalog; assessment: Assessment; now: number; conversationId: string }
+export interface Picked { id: string; reasons: string[] }
+
+const kindIs = (a: Assessment, word: string) => new RegExp(`(^|-)${word}(-|$)`).test(a.kind ?? '')
+const pct = (n: number) => `${Math.round(n)}%`
+const span = (ms: number) => ms >= D ? `${Math.round(ms / D)}d` : `${Math.max(1, Math.round(ms / H))}h`
+
+interface Ranked { p: Shown; need: number; left: number | null; resetsAt: number | null; follows: boolean }
+
+export function pickByOrder({ shown, catalog, assessment: a, now, conversationId }: PickInput): Picked | null {
+ const tier: Tier | null = tierOf(a)
+ const review = kindIs(a, 'review'), test = kindIs(a, 'test')
+ const named = !!a.model || !!a.local
+ const big = !review && !test && tier === 'strong'
+ const needs = big ? BIG_NEEDS : SMALL_NEEDS
+
+ // 1. What the work needs. A person naming a model, or asking for a local one, has already narrowed the candidates.
+ const fits = shown.flatMap((p): Ranked[] => {
+ const { left, resetsAt } = weekly(p.quota)
+ const follows = p.kind === 'member' && !!p.earlier?.some(e => e.groupId === conversationId)
+ // No agent runs below high effort, and none on Haiku (the Routing order, Models), unless a person named the model.
+ if (!named && !p.gridModel && (BELOW_HIGH.has(p.effort.toLowerCase()) || /haiku/i.test(p.model))) return []
+ let need: number
+ if (named) need = 0
+ else if (p.gridModel) {
+ if (review || tier === 'strong') return []
+ // Small work goes first to a grid model when one is offered (free, Sonnet-level).
+ need = tier === 'standard' ? -1 : 0
+ } else if (tier === null) need = 0
+ else {
+ need = fitRank(p, catalog, tier)
+ if (tier === 'strong' && need === 2) return []
+ }
+ return [{ p, need, left, resetsAt, follows }]
+ })
+
+ // 2. Quota: an account is used while it has the weekly quota the work needs; grid and metered models use no subscription,
+ // and a reading that is missing does not rule an account out.
+ const usable = fits.filter(r => {
+ if (r.p.gridModel || r.p.quota.metered || r.left === null) return true
+ return r.left >= needs && !(runsPm(r.p) && r.left < PM_RESERVE)
+ })
+ if (!usable.length) return null
+ const best = Math.min(...usable.map(r => r.need))
+ const pool = usable.filter(r => r.need === best)
+
+ const unread = (r: Ranked) => r.left === null ? 1 : 0
+ const byAccount = (x: Ranked, y: Ranked) => unread(x) - unread(y) || (x.resetsAt ?? Infinity) - (y.resetsAt ?? Infinity) || (y.left ?? 0) - (x.left ?? 0)
+ const agents = (r: Ranked) => r.p.load?.agents ?? 0
+ const order = [...pool].sort((x, y) => Number(y.follows) - Number(x.follows) || byAccount(x, y)
+ || Number(y.p.kind === 'member') - Number(x.p.kind === 'member') || agents(x) - agents(y) || x.p.cost - y.p.cost || x.p.id.localeCompare(y.p.id))
+ const win = order[0]!
+
+ const accounts = new Set(pool.map(r => r.p.fit.account)).size
+ const sameAccountPosition = (r: Ranked) => byAccount(win, r) === 0
+ const reasons = [
+ `1. Need: ${win.p.title} ${win.p.gridModel ? 'is a grid model, free, for small work' : tier === null ? 'runs the work (no size given)'
+ : win.need === 0 ? `is the ${tier === 'strong' ? (review ? 'strong model a review needs' : 'strong model for big, hard or risky work') : 'model for small work'}`
+ : 'is the closest fit to the model the work needs'}.`,
+ win.p.gridModel || win.p.quota.metered ? '2. Quota: it uses no subscription.'
+ : win.left === null ? `2. Quota: weekly unknown; no account with a reading has the ${pct(needs)} the work needs.`
+ : `2. Quota: weekly ${pct(win.left)} left${win.resetsAt === null ? '' : `, resets in ${span(Math.max(0, win.resetsAt - now))}`}`
+ + (accounts === 1 ? ': the only account with quota left.'
+ : pool.some(r => r !== win && (r.resetsAt ?? Infinity) > (win.resetsAt ?? Infinity)) ? `: resets soonest of ${accounts} accounts.`
+ : `: the most left of ${accounts} accounts resetting together.`),
+ win.p.kind === 'member'
+ ? `3. Idle: reuses ${win.p.name ?? 'the idle agent'}${win.follows ? ', which worked on this task before' : ', equal so far to a new agent'}.`
+ : `3. Idle: a new agent; ${pool.some(r => r.p.kind === 'member' && !sameAccountPosition(r)) ? 'an idle agent is on a worse account' : 'no idle agent is equal so far'}.`,
+ `4. Load and price: ${agents(win)} ${agents(win) === 1 ? 'agent' : 'agents'} working on ${win.p.machineName}, price ${win.p.cost}.`,
+ ]
+ return { id: win.p.id, reasons }
+}
diff --git a/docs/plans/2026-11-06-route-pick-by-order-plan.md b/docs/plans/2026-11-06-route-pick-by-order-plan.md
new file mode 100644
index 000000000..99494c713
--- /dev/null
+++ b/docs/plans/2026-11-06-route-pick-by-order-plan.md
@@ -0,0 +1,57 @@
+# The route picks by the Routing order — Plan (task #3576, part 1)
+
+**Goal:** `harness super-tab route` returns a pick computed from its candidates by the project's Routing order (Order and
+quota, steps 1–4), with one reason per step; a start or assignment without an override uses the pick, and choosing another
+candidate needs an override reason.
+
+**Architecture:** A pure function `pickByOrder` in `cli/src/superTabs/routePick.ts` ranks the shown candidates (the route's
+own facts: model tier fit, grid, weekly quota left and reset, PM account, agents on the machine, price, the member's earlier
+work on this task) and returns `{ id, reasons }`. `routeCommand.ts` records it (`via: 'order'`, `pick`, reasons in `why`) and
+prints it first. The backend already stores a pick; `linkDecision` now asks for a reason when a start or assignment is not
+the pick. No new stored data.
+
+**Tech Stack:** TypeScript; CLI vitest specs (`cli/src/superTabs/*.spec.ts`), backend vitest.
+
+**Spec:** the task brief (#3576), part 1. Part 2 (the four machine rules as rules-record kinds: hours a machine is off,
+phone work on the phone Mac, no Codex on a named Mac, no reviewer on a local-model Codex) is a separate task. Until then the route
+reads none of them (the server enforces no rule of the record): the route's `next` says the instructions' Machines rules still apply
+and a pick that breaks one is overridden with that rule as the reason.
+
+## Global Constraints
+- Swarm code stays out of `cli/src/core`. Backend change is limited to `backend/src/superTabs/`.
+- `decide()` and the unranked answer stay for a route with no pick (nothing eligible, plug-in findings only): no behavior
+ change there.
+- A backend from before accepts the record unchanged (pick + via `order` are already in its schema).
+
+## Review Focus
+- Each step of the order, in order, and that a later step never overrides an earlier one.
+- The exceptions: same reviewer for its next round / follow-on work; PM account under 20%; 5% / 2% quota floors.
+- Backend: a start or assignment that is not the pick is refused without a reason.
+
+## Task 1: pickByOrder (`routePick.ts`)
+**Files:** `cli/src/superTabs/routePick.ts`, `routePick.spec.ts`
+- [ ] Failing specs, one per step: need (tier model, grid first for small work, never grid for reviews), quota (floors,
+ soonest reset, then most left, PM account under 20%), idle only between equals plus the exceptions, fewer agents then price.
+- [ ] Code.
+
+## Task 2: Record and print the pick (`route.ts`, `routeCommand.ts`)
+**Files:** `route.ts`, `routeCommand.ts`, `routeCommand.spec.ts`
+- [ ] Failing specs: the answer has `pick` and `reasons` first, the record has `pick` and `via: 'order'`.
+- [ ] Code.
+
+## Task 3: Backend override reason (`commands.ts`)
+**Files:** `backend/src/superTabs/commands.ts`, `commands.test.ts`
+- [ ] Failing tests: following the pick needs no reason; another candidate without a reason is refused; with a reason it is
+ recorded as an override.
+- [ ] Code.
+
+## Task 4: Lane dispatch skips a member too weak for the task (`dispatch.ts`, `model.ts`, `commands.ts`)
+(Added at River's word, 11-06: dispatch gave a big, risky task to a Sonnet member.)
+**Files:** `backend/src/superTabs/dispatch.ts`, `model.ts`, `commands.ts` (task contract), `dispatch.test.ts`
+**Interfaces:** `WorkTask.strength?: 'standard' | 'strong'`, set by the PM with the brief (big, hard or risky work is `strong`);
+a task asking for two reviews counts as `strong` too. `candidatesFor` leaves out a `strong` task for a member whose model is not
+Opus or Astra (the Routing rule for big or risky work), so a weaker member keeps waiting for work it may take. A pinned task
+(a member sent back for its own CI or conflict) is not skipped: it is that member's own work.
+- [ ] Failing tests: a Sonnet member is not handed a `strong` task, an Opus member is; a `standard` task goes to either;
+ a pin stays with its member.
+- [ ] Code.