The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Swarm routing: cheap first, a small low-risk build tries Kimi K3 or DeepSeek first; never reviews or security (goals piece 4) (#2422)
0xken15f46c92611eaa
diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.tsindex bea18a26e..23e09b4dc 100644--- a/backend/src/superTabs/commands.test.ts+++ b/backend/src/superTabs/commands.test.ts@@ -1359,12 +1359,22 @@ describe('the route is advice', () => {expect(route().record.instructionsRevision).toBe(3)delete f.state.projects![0]!.instructionsRevisionexpect(route().record.instructionsRevision).toBe(0)- // Stamped by the server, never taken from the route; and a step up is no longer written on it.+ // Stamped by the server, never taken from the route: the revision, and the task's own step up (a grid attempt's failed first+ // review, goals piece 4), which the costs report counts.f.state.projects![0]!.instructionsRevision = 5- f.state.conversations.find(c => c.id === 'lead')!.stepUp = { attempt: 2, floor: 2, reason: 'Its first review said Ready no.', at: 1, carry: '' }+ expect(route({ stepUp: { attempt: 3, reason: 'Mine.' } }).record).not.toHaveProperty('stepUp')+ const lead = () => f.state.conversations.find(c => c.id === 'lead')!+ lead().stepUp = { attempt: 2, floor: 3, reason: `Its first review failed on ${'m'.repeat(300)}.`, at: 1, carry: '' }const sent = route({ instructionsRevision: 1, stepUp: { attempt: 3, reason: 'Mine.' } })expect(sent.record.instructionsRevision).toBe(5)- expect(sent.record).not.toHaveProperty('stepUp')+ expect(sent.record.stepUp).toEqual({ attempt: 2, reason: `Its first review failed on ${'m'.repeat(300)}.`.slice(0, 200) })+ // Only the first route after it carries it: the costs report counts one step up per task, however often it is routed.+ expect(lead().stepUp).toMatchObject({ attempt: 2, recorded: true })+ expect(route().record).not.toHaveProperty('stepUp')+ // A step up from before project instructions, past the third attempt, is kept at the record's last attempt.+ lead().stepUp = { attempt: 4, floor: 3, reason: 'Old.', at: 1, carry: '' }+ expect(route().record.stepUp).toEqual({ attempt: 3, reason: 'Old.' })+ expect(route().record).not.toHaveProperty('stepUp')})it('starts with no role default', () => {@@ -4234,7 +4244,7 @@ describe('notices of failed work', () => {}const failed = (effects: { messages: Array<{ source?: Record<string, unknown> | null }> }) => effects.messages.filter(m => m.source?.kind === 'review-failed')- it('tells the coordinator of a grid attempt\'s failed first review and steps nothing up', () => {+ it('tells the coordinator of a grid attempt\'s failed first review, and records the step up for the next route', () => {const { f, group, builder, assign, check, fail, g } = task()const kimi = builder('kimi', 'default', 'moonshotai/kimi-k3')const assignmentId = assign(kimi)@@ -4246,18 +4256,21 @@ describe('notices of failed work', () => {// The findings, up to 500 characters.expect(text.length).toBeLessThanOrEqual(`#${g().number} Offline editing: its first review failed. It ran on moonshotai/kimi-k3 on the Swarm's grid. Findings: `.length + 500)expect(agentOnly(notices[0]!.source, (notices[0] as { recipients: string[] }).recipients)).toBe(true)- // Nothing is cancelled or stepped up, and the agent is told nothing to stop.+ // Nothing is cancelled and the agent is told nothing to stop. The task records the step up (goals piece 4): the next route+ // leaves the grid out, and route records carry it for the costs report.expect(g().assignment).toMatchObject({ id: assignmentId, status: 'review' })- expect(g().stepUp).toBeUndefined()+ expect(g().stepUp).toEqual({ attempt: 2, floor: 3, reason: 'Its first review failed on moonshotai/kimi-k3 on the Swarm\'s grid.', at: 1000, carry: '' })expect(effects.messages.filter(m => m.recipients.includes(kimi))).toEqual([])- // A second failed verdict in the same attempt: no other notice.+ // A second failed verdict in the same attempt: no other notice, and no second step up.expect(failed(check(assignmentId, 'Ready: no. Still broken.'))).toEqual([])+ expect(g().stepUp).toMatchObject({ attempt: 2 })// A subscription attempt's failed first review: its findings reach its agent as they are, and no notice.const { builder: other, assign: give, fail: failIt, g: mine } = task()const sonnet = other('sonnet', 'claude-sonnet-4-5')const attempt = give(sonnet)expect(failed(failIt(attempt, sonnet))).toEqual([])expect(mine().assignment).toMatchObject({ id: attempt, status: 'review' })+ expect(mine().stepUp).toBeUndefined()})it('tells a failed start to the coordinator and the agent that made it', () => {diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex df5e30036..c74907b67 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -792,10 +792,14 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaif (machines.some(m => !seen.has(m))) fail('MACHINE_UNKNOWN', 'Name a machine of this Swarm that you can see.', 400)}/** A grid attempt's first review failed (project instructions, phase 4, decision 8): its coordinator hears what happened, with- * the model and the findings; nothing is cancelled or stepped up, and the findings reach the agent as they do any verdict. */+ * the model and the findings; nothing is cancelled, and the findings reach the agent as they do any verdict. The task keeps+ * the step up (goals piece 4): the route reads it to leave the grid out of the next attempt (cli routeCheapFirst.ts), and+ * route records carry it for the costs report (costs/read.ts stepUps). Its reason names only the model, never the findings,+ * since every reader of the task sees it. */const reviewFailed = (group: Conversation, model: string, evidence: string) => {const worker = state.agents.find(a => a.id === group.assignment?.agentId)if (!worker) return+ group.stepUp = { attempt: (group.stepUp?.attempt ?? 1) + 1, floor: 3, reason: `Its first review failed on ${model} on the Swarm's grid.`, at: context.now, carry: '' }const findings = evidence.length > FINDINGS_CHARS ? `${evidence.slice(0, FINDINGS_CHARS - 1)}…` : evidenceeffects.messages.push(...leadNoticeRows(toLead(state, worker, { id: stableId(operationId, 'review-failed'), conversationId: group.id, author: sender,replyTo: null, recipients: [], text: `#${group.number} ${group.title}: its first review failed. It ran on ${model} on the Swarm's grid. Findings: ${findings}`,@@ -2337,14 +2341,19 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaconst routedGroup = open(state, command.conversationId)const via = decision.via === 'jev' ? `Jev ${Math.round((decision.p ?? 0) * 100)}%`: decision.via === 'only' ? 'only candidate' : 'by policy order'- // The server's own fields are never taken from the route: no step up any more, and the instructions revision the route- // relied on, stamped now (project instructions, phase 4). An older CLI's same-engine note, as a field or at the start of- // its why, is not kept.+ // The server's own fields are never taken from the route: the task's step up (a grid attempt's failed first review, goals+ // piece 4), cut to what a record keeps, and the instructions revision the route relied on, stamped now (project+ // instructions, phase 4). An older CLI's same-engine note, as a field or at the start of its why, is not kept.const { stepUp: _sent, sameEngine: _said, jobKind: _kind, instructionsRevision: _revision, ...sent } = decisionconst made = { ...sent, why: sent.why.replace(OLD_SAME_ENGINE, '') || sent.why }const jobKind = jobKindOf(routedGroup, decision.assessment.kind)const instructionsRevision = groupProject(state, routedGroup).instructionsRevision ?? 0- effects.routeDecisions.push({ op: 'create', id: operationId, conversationId: command.conversationId, record: { ...made, jobKind, instructionsRevision } })+ // Only the first route after a step up carries it, so the costs report counts one step up per task, not one per route+ // (review of #2422); a later failure is a new step up, carried again.+ const step = routedGroup.stepUp && !routedGroup.stepUp.recorded ? routedGroup.stepUp : null+ if (step) step.recorded = true+ 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.const reason = decision.assessment.whydiff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.tsindex 461c5ef8a..409d3f5d2 100644--- a/backend/src/superTabs/model.ts+++ b/backend/src/superTabs/model.ts@@ -305,15 +305,18 @@ export interface Conversation {ledger?: import('./leaderboard/record.js').GroupLedger/** Whether its task is moving, waiting on purpose or stuck, as the time checks last found it (liveness.ts recordTaskStates). */liveness?: TaskLiveness- /** Its last step up from a cheaper model, on a task from before project instructions; never written since (phase 4: a- * failed first review or start is a notice to the coordinator). The leaderboard still reads it on such a task. */+ /** Its last step up from a cheaper model: written when a grid attempt's first review fails (commands.ts reviewFailed, goals+ * piece 4; before project instructions also by the server's step up). Nothing is cancelled: the route reads it to leave the+ * grid out of the next attempt, route records carry it for the costs report, and the leaderboard reads it. */stepUp?: StepUp/** The last route, start or assignment on its task by an agent of its project, or its coordinator's post there (commands.ts). */leadAction?: { kind: 'assign' | 'route' | 'start' | 'post'; at: number }}/** A step up: the attempt it opened (2 or 3), the least quality from then on, why, when, and what the failed attempt left for* the next one's brief; the failed start that caused it, if one did. */-export interface StepUp { attempt: number; floor: number; reason: string; at: number; carry: string; startId?: string }+export interface StepUp { attempt: number; floor: number; reason: string; at: number; carry: string; startId?: string+ /** A route record carries it already (commands.ts route.record): later routes of the task do not, so it counts once. */+ recorded?: true }/** Absent while its task is working (its agent reported in the last 30 minutes; its last progress is its assignment's* `progressAt`) or there is none. `waiting`: on a person (`personId`), a review, its stated* blocker, the new revision of the build it reviews, or its agent's start. `quiet`: its agent has reported nothing for 30 minutesdiff --git a/backend/src/superTabs/routeRecord.ts b/backend/src/superTabs/routeRecord.tsindex 425a01ac3..2c44563eb 100644--- a/backend/src/superTabs/routeRecord.ts+++ b/backend/src/superTabs/routeRecord.ts@@ -58,8 +58,8 @@ export const routeRecordSchema = z.object({why: z.string().trim().min(1).max(300),/** How much context Jev was given and which sources could not be read, so pick quality can later be compared with completeness. */context: z.object({ chars: z.number().int().min(0).max(30_000), missing: z.array(z.string().min(1).max(40)).max(10) }).strict().optional(),- /** The step up this attempt was (the server's step up, gone since project instructions phase 4), on records from before project instructions. Never written since, never taken- * from the route. */+ /** The step up this attempt was: its task's step up (model.ts Conversation.stepUp), stamped by the server when the route is+ * recorded, never taken from the route. */stepUp: z.object({ attempt: z.number().int().min(2).max(3), reason: z.string().min(1).max(200) }).strict().optional(),/** Why a review ran on its Builder's own engine, on records from before 2026-10-30, when another engine had to review when it could. Never written since, never taken from the route. */sameEngine: z.string().min(1).max(300).optional(),diff --git a/cli/src/lib/swarmTools.spec.ts b/cli/src/lib/swarmTools.spec.tsindex f1f8788a1..231c28e5a 100644--- a/cli/src/lib/swarmTools.spec.ts+++ b/cli/src/lib/swarmTools.spec.ts@@ -1,5 +1,6 @@import { describe, expect, it } from 'vitest'import { SWARM_TOOLS_SKILL } from './swarmTools.js'+import { CHEAP_FIRST_HELP, ROUTE_KIND_HELP } from '../superTabs/routeCheapFirst.js'describe('SWARM_TOOLS_SKILL', () => {it('describes the commands and no workflow', () => {@@ -19,6 +20,11 @@ describe('SWARM_TOOLS_SKILL', () => {})// Final review: what the skill says the server does must be what it does.const lineOf = (needle: string) => SWARM_TOOLS_SKILL.split('\n').find(line => line.includes(needle)) ?? ''+ it('says which kinds of work may go to the grid, from the same text as the route\'s help', () => {+ expect(SWARM_TOOLS_SKILL).toContain(`"kind":"${ROUTE_KIND_HELP}"`)+ expect(SWARM_TOOLS_SKILL).toContain(CHEAP_FIRST_HELP)+ expect(SWARM_TOOLS_SKILL).not.toContain('leaves out only')+ })it('has the reviewing agent named with --to, since a review status tells only the group\'s coordinator', () => {expect(SWARM_TOOLS_SKILL).not.toContain('so it is told when that work is ready for review')expect(lineOf('`reviewOf` naming')).toMatch(/--to/)diff --git a/cli/src/lib/swarmTools.ts b/cli/src/lib/swarmTools.tsindex c473c776a..dc9977d7d 100644--- a/cli/src/lib/swarmTools.ts+++ b/cli/src/lib/swarmTools.ts@@ -1,6 +1,8 @@/** The mechanics of the Swarm commands every agent uses, with no workflow and no role names: what to do, and who does it, is* the project's instructions (swarmInstructionsSkill.ts). Built in, so it needs no backend read, and written at launch* beside today's role file. Every command and flag here is checked against superTabs/command.ts and service.ts HELP. */+import { CHEAP_FIRST_HELP, ROUTE_KIND_HELP } from '../superTabs/routeCheapFirst.js'+export const SWARM_TOOLS_SKILL = `---name: swarm-toolsdescription: Use whenever you work in a Harness Swarm project and need the mechanics of harness super-tab: reading status and messages, posting, reacting, commands, starting agents, routing, instructions, decisions, costs and terminals.@@ -77,10 +79,11 @@ 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":"optional word such as ui or docs","local":true,"model":"optional","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}\`.+- \`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"}}\`.- 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 only 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.+ - 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.diff --git a/cli/src/superTabs/routeCheapFirst.spec.ts b/cli/src/superTabs/routeCheapFirst.spec.tsnew file mode 100644index 000000000..8a886c563--- /dev/null+++ b/cli/src/superTabs/routeCheapFirst.spec.ts@@ -0,0 +1,256 @@+// cli/src/superTabs/routeCheapFirst.spec.ts+import { describe, expect, it, vi } from 'vitest'+import { choose, decide, recordOf, type Assessment, type Catalog, type Probe } from './route.js'+import { makePlugins, MAKER_TIMEOUT_MS, ROUTE_PLUGIN_MAKERS } from './routePlugins.js'+import { CHEAP_FIRST, CHEAP_FIRST_MAKER, CHEAP_FIRST_MAKERS, cheapFirst, cheapTaskOf, EARLIER_UNREADABLE, GRID_KINDS, GRID_KINDS_ONLY, GRID_LIMITS, GRID_LIMITS_MAKER, gridLimits, HISTORY_WAIT_MS, FIRST_ATTEMPT_ONLY, GRID_FIRST, MAX_OWNED, NEVER_REVIEWS, NEVER_SECURITY, type CheapTask } from './routeCheapFirst.js'++const NOW = 1_000_000_000, H = 3_600_000, D = 86_400_000+/** Today's catalog (backend superTabs/catalog.ts): Opus and Codex at 3, Kimi K3 and DeepSeek v4.1 at 2 on the grid. */+const catalog: Catalog = { grid: { strength: 1, models: [{ model: 'kimi k3', strength: 2 }, { model: 'deepseek v4.1', strength: 2 }] }, models: [+ { engine: 'claude', model: 'opus', effort: 'high', strength: 3, cost: 3, offered: true },+ { engine: 'codex', model: 'default', effort: 'default', strength: 3, cost: 2, offered: true },+] }+const a = (patch: Partial<Assessment> = {}): Assessment => ({ difficulty: 'low', risk: 'low', size: 'small', why: 'Fix a typo in the docs.', kind: 'docs', needs: { tools: [], devices: [] }, ...patch })+const quota = { known: true, leftPercent: 80, resetsAt: null, windows: [{ name: '5-hour', leftPercent: 80, resetsAt: NOW + 3 * H }, { name: 'weekly', leftPercent: 90, resetsAt: NOW + 5 * D }] }+const opus: Probe = { kind: 'new', machineId: 'm1', machineName: 'remote-1', engine: 'claude', model: 'opus', effort: 'high', quality: 3, cost: 3,+ quota: { ...quota, account: 'acct' }, activity: 'new agent', known: true, refusals: [], notes: [] }+const codex: Probe = { ...opus, engine: 'codex', model: 'default', effort: 'default', quality: 3, cost: 2, quota: { ...quota, account: 'cx' } }+/** A new agent on a grid model, as routeCommand.ts localProbes makes one. */+const grid = (model: string, label: string, quality = 2): Probe => ({ ...opus, model: 'default', effort: 'default', quality, cost: 1,+ quota: { known: false, leftPercent: null, resetsAt: null }, gridModel: model, gridName: 'swarm-grid', gridLabel: label, gridKind: 'api' })+const kimi = grid('moonshotai/kimi-k3', 'Kimi K3'), deepseek = grid('deepseek/deepseek-v4.1', 'DeepSeek v4.1'), qwen = grid('qwen3:4b', 'Qwen 3', 1)+const first: CheapTask = { review: false, owned: 1, earlier: null }+const route = (task: CheapTask, assessment: Partial<Assessment> = {}, probes: Probe[] = [opus, codex, kimi, deepseek, qwen]) =>+ choose(probes, catalog, a(assessment), NOW, [], [], [], [gridLimits(task.review), cheapFirst(task)])+const ok = (r: ReturnType<typeof choose>) => { if ('error' in r) throw new Error(JSON.stringify(r)); return r }+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', () => {+ 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.+ expect(r.shown.find(s => s.model === 'opus')!.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 }+ // 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)+ })++ it('keeps today\'s order 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>]>) {+ const r = ok(route(task, assessment))+ expect(picks(r)).toEqual(today)+ expect(r.adjusted).toBeUndefined()+ }+ expect(picks(route({ ...first, owned: MAX_OWNED }))[0]).toBe('DeepSeek v4.1')+ })++ 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(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' })+ }+ })++ it('never puts security-sensitive work on a grid model: a security kind, or high risk', () => {+ for (const assessment of [{ kind: 'security' }, { kind: 'auth' }, { kind: 'privacy' }, { kind: 'secrets' }, { risk: 'high' as const }]) {+ const r = ok(route(first, assessment))+ expect(r.shown.some(s => s.gridModel)).toBe(false)+ expect(new Set(reasons(r))).toEqual(new Set([`${GRID_LIMITS}: ${NEVER_SECURITY}`]))+ expect(route(first, { ...assessment, model: 'deepseek' })).toMatchObject({ error: 'NO_CANDIDATE' })+ }+ })++ it('fails closed on the kind: a task with no kind, or one not on the list, gets no grid model, even a named one', () => {+ for (const kind of [undefined, 'ui', 'parser', 'Docs']) {+ const r = ok(route(first, { kind }))+ expect(r.shown.some(s => s.gridModel)).toBe(false)+ expect(new Set(reasons(r))).toEqual(new Set([`${GRID_LIMITS}: ${GRID_KINDS_ONLY}`]))+ expect(route(first, { kind, model: 'kimi' })).toMatchObject({ error: 'NO_CANDIDATE' })+ expect(route(first, { kind, local: true })).toMatchObject({ error: 'NO_CANDIDATE' })+ }+ 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')+ })++ 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(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' }))+ expect(picks(named)).toEqual(['Kimi K3'])+ expect(named.shown[0]!.notes).toEqual([`${CHEAP_FIRST}: ${FIRST_ATTEMPT_ONLY} Its first attempt ran on Kimi K3. A person named this model, so it is offered.`])+ // A review is never offered one, named or not, whatever came before.+ 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', () => {+ // 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()+ expect(ok(route(first)).shown).toHaveLength(5)+ })++ it('leaves subscription candidates and members alone in every case', () => {+ const member: Probe = { ...opus, kind: 'member', agentId: 'a1', name: 'Wren' }+ for (const task of [first, { ...first, review: true }, { ...first, earlier: 'x' }]) {+ const r = ok(route(task, {}, [opus, member]))+ expect(r.excluded).toEqual([])+ expect(r.adjusted).toBeUndefined()+ }+ })+})++describe('what the route reads of a task before it is ranked', () => {+ 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: [] }++ it('a first attempt: no earlier assignment, start, routed pick or step-up', () => {+ expect(cheapTaskOf(group(), state(), history)).toEqual({ review: false, owned: 1, earlier: null })+ // A route nobody acted on is no attempt; another group's work is not this one's.+ expect(cheapTaskOf(group(), state({ starts: [{ request: { conversationId: 'g2', gridModel: 'k' } }] }),+ { decisions: [{ conversationId: 'g1', final: null }, { conversationId: 'g2', final: { kind: 'new' } }], attempts: [] }).earlier).toBeNull()+ })++ it('reads a review task, and counts owned code', () => {+ expect(cheapTaskOf(group({ reviewOf: 'g0' }), state(), history).review).toBe(true)+ expect(cheapTaskOf(group({ task: { owns: ['a', 'b', 7] } }), state(), history).owned).toBe(2)+ expect(cheapTaskOf(group({ task: undefined }), state(), history).owned).toBe(0)+ expect(cheapTaskOf(group({ task: { owns: 'a' } }), state(), history).owned).toBe(0)+ })++ it('finds any earlier attempt, naming the grid model it ran on when it was one', () => {+ const on = (patch: Record<string, unknown>) => cheapTaskOf(group(patch.group as never), state(patch.state as never), (patch.history as never) ?? history).earlier+ // The current or last assignment, or one the backend kept after work.define.+ expect(on({ group: { assignment: { id: 'w1', agentId: 'a1', status: 'working' } } })).toBe('It had an earlier attempt.')+ expect(on({ history: { decisions: [], attempts: [{ id: 'w0', agentId: 'a1' }] } })).toBe('It had an earlier attempt.')+ // A lost attempt, a routed pick that started or was assigned, or a start (even one that failed) for it.+ expect(on({ group: { lostAttempt: { id: 'w0', agentId: 'a9' } } })).toBe('It had an earlier attempt.')+ expect(on({ history: { decisions: [{ conversationId: 'g1', final: { kind: 'member', agentId: 'a1' } }], attempts: [] } })).toBe('It had an earlier attempt.')+ expect(on({ state: { starts: [{ request: { conversationId: 'g1' }, error: 'Codex is not signed in.' }] } })).toBe('It had an earlier attempt.')+ // On the grid: its model is named, whether its start failed or its agent worked on it.+ expect(on({ state: { starts: [{ request: { conversationId: 'g1', gridModel: 'moonshotai/kimi-k3' }, error: 'The grid host did not answer.' }] } }))+ .toBe('Its earlier attempt ran on moonshotai/kimi-k3 on the Swarm\'s grid.')+ expect(on({ group: { assignment: { id: 'w1', agentId: 'a1', status: 'working' } },+ state: { agents: [{ id: 'a1', harnessId: 'h1' }], starts: [{ harnessId: 'h1', request: { conversationId: 'g0', gridModel: 'deepseek/deepseek-v4.1' } }] } }))+ .toBe('Its earlier attempt ran on deepseek/deepseek-v4.1 on the Swarm\'s grid.')+ // A step-up the backend recorded (after a grid attempt's failed first review) says why, in its words.+ expect(on({ group: { stepUp: { attempt: 2, reason: 'Its first review said Ready no.' } } })).toBe('Its first review said Ready no.')+ })++ it('an earlier attempt it cannot rule out counts as one: unreadable history is no first attempt', () => {+ expect(cheapTaskOf(group(), state(), null).earlier).toBe(EARLIER_UNREADABLE)+ expect(cheapTaskOf(group(), state(), { decisions: null, attempts: [] }).earlier).toBe(EARLIER_UNREADABLE)+ expect(cheapTaskOf(group(), state(), { decisions: [], attempts: null }).earlier).toBe(EARLIER_UNREADABLE)+ // What the state shows still names the model.+ expect(cheapTaskOf(group(), state({ starts: [{ request: { conversationId: 'g1', gridModel: 'k' } }] }), null).earlier).toContain('ran on k')+ // Junk is read as nothing, never thrown on.+ expect(cheapTaskOf({ id: 'g1' }, { agents: 'x', starts: [null, 3, { request: null }] }, { decisions: [null], attempts: [7] }).earlier).toBeNull()+ })+})++describe('the maker', () => {+ it('is in the route\'s makers list, the guard before the ranking', () => {+ 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]!)+ })++ const read = (conversations: unknown[] = [{ id: 'g1', task: { owns: ['docs/a.md'] } }]) => ({ tab: { state: { conversations, agents: [], starts: [] } } })+ const make = (history: Promise<Record<string, unknown> | null>, tab = read()) =>+ CHEAP_FIRST_MAKER.make({ conversationId: 'g1', assessment: a(), read: tab, catalog, history, request: async () => ({}) })+ const gridOut = async (made: ReturnType<typeof make>) => {+ const r = ok(choose([opus, kimi], catalog, a(), NOW, [], [], [], [(await made)!]))+ return r.shown.some(s => s.gridModel) ? null : r.excluded.map(e => e.reason)+ }++ it('makes the plug-in from the route\'s own reads: a first attempt when the history shows none', async () => {+ expect(await gridOut(make(Promise.resolve({ ok: true, value: { decisions: [], attempts: [] } })))).toBeNull()+ expect((await make(Promise.resolve({ ok: true, value: { decisions: [], attempts: [] } })))!.name).toBe(CHEAP_FIRST)+ })++ it('leaves the grid out rather than skip the rule when the history fails, is junk, or is later than it waits', async () => {+ const unread = [`${CHEAP_FIRST}: ${FIRST_ATTEMPT_ONLY} ${EARLIER_UNREADABLE}`]+ expect(await gridOut(make(Promise.resolve(null)))).toEqual(unread)+ expect(await gridOut(make(Promise.reject(new Error('socket closed'))))).toEqual(unread)+ expect(await gridOut(make(Promise.resolve({ ok: true, value: { decisions: 'x' } })))).toEqual(unread)+ expect(await gridOut(make(Promise.resolve({ error: 'BACKEND_UNAVAILABLE' })))).toEqual(unread)+ vi.useFakeTimers()+ try {+ const made = make(new Promise(() => {}))+ await vi.advanceTimersByTimeAsync(HISTORY_WAIT_MS)+ vi.useRealTimers()+ expect(await gridOut(made)).toEqual(unread)+ } finally { vi.useRealTimers() }+ })++ it('reads a group the tab does not list, or a tab it cannot read, as a task with nothing owned', async () => {+ 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.+ expect(r.shown.map(s => s.gridModel ?? s.model)).toEqual(['opus', 'moonshotai/kimi-k3'])+ }+ // A review the tab lists is read as one: the ranking 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 () => {+ 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)+ const input = (history: Promise<Record<string, unknown> | null>, tab = review) => ({ conversationId: 'g1', assessment: a(), read: tab, catalog, history, request: async () => ({}) })+ // The guard reads nothing: it is made before a history that never answers has done anything.+ let made = false+ void GRID_LIMITS_MAKER.make(input(new Promise(() => {}))).then(() => { made = true })+ await Promise.resolve(); await Promise.resolve()+ expect(made).toBe(true)+ vi.useFakeTimers()+ try {+ const hangs = () => new Promise<null>(() => {})+ for (const [history, tab, assessment] of [[hangs, review, {}], [() => Promise.reject(new Error('down')), review, {}],+ [hangs, read(), { kind: 'security' }], [() => Promise.resolve(null), read(), { risk: 'high' as const }]] as const) {+ const making = makePlugins(CHEAP_FIRST_MAKERS, input(history() as Promise<null>, tab))+ await vi.advanceTimersByTimeAsync(MAKER_TIMEOUT_MS)+ const { plugins, warnings } = await making+ 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.+ 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.+ 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)+ const dropped = await making+ expect(dropped.plugins.map(p => p.name)).toEqual([GRID_LIMITS])+ expect(dropped.warnings).toHaveLength(1)+ expect(gridIn(dropped.plugins)).toBe(false)+ } finally { vi.useRealTimers() }+ // A build with no such kind is not the guard's to touch.+ expect(gridIn([gridLimits(false)])).toBe(true)+ })+})diff --git a/cli/src/superTabs/routeCheapFirst.ts b/cli/src/superTabs/routeCheapFirst.tsnew file mode 100644index 000000000..39dc44918--- /dev/null+++ b/cli/src/superTabs/routeCheapFirst.ts@@ -0,0 +1,159 @@+/** 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.+ *+ * 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+ * (Lead, 2026-10-31), and any earlier assignment, start or routed pick for the task means the next route leaves the grid out.+ * That works with today's backend; a step-up the backend records on the task (`stepUp`) is read too, for its reason. */+import type { Assessment, RoutePlugin } from './route.js'+import type { PluginMaker } from './routePlugins.js'++type Json = Record<string, unknown>+const object = (v: unknown): Json => v && typeof v === 'object' && !Array.isArray(v) ? v as Json : {}+const list = (v: unknown) => Array.isArray(v) ? v.map(object) : []+const text = (v: unknown) => typeof v === 'string' && v.trim() ? v.trim() : null+/** A review task: one linked to the work it reviews. */+const isReview = (group: Json) => typeof group.reviewOf === 'string' && !!group.reviewOf++/** The plug-in's name, which starts each of its reasons on a candidate ("Cheap first: …"). */+export const CHEAP_FIRST = 'Cheap first'+/** How many owned paths a task may name and still be small enough for a grid model to try first (Lead, 2026-10-31: "a few+ * 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. */+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'])+/** The only kinds of work a grid model may take, as the routing agent names them. Anything else, and a task with no kind, gets+ * no grid model: a security task routed as low risk with no kind must never reach one (Ken's rule; Lead, 10-31: fail closed).+ * 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 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". */+const KINDS_TEXT = `${GRID_KINDS.slice(0, -1).join(', ')} or ${GRID_KINDS.at(-1)}`+export const GRID_KINDS_ONLY = `A model on the Swarm's grid takes only work whose kind is ${KINDS_TEXT}; this task names no such kind.`+/** 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. `+ + '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.'+const NAMED = 'A person named this model, so it is offered.'++/** What the plug-in needs of the task, read before the route (RoutePlugin: pure and synchronous). `earlier`: why this is not+ * the task's first attempt, or null when it is. */+export interface CheapTask { review: boolean; owned: number; earlier: string | null }++/** What the route reads of [group]: whether it is a review (a task linked to the work it reviews), how many owned paths it+ * names, and any earlier attempt at it. [history] is the route's read of the log and the group's attempts (service.ts+ * routeHistory), null when it failed: an attempt it cannot rule out counts as one, so a grid model is never sent back to a+ * task that already failed on it because a read timed out. */+export function cheapTaskOf(group: Json, state: Json, history: { decisions: unknown[] | null; attempts: unknown[] | null } | null): CheapTask {+ const id = group.id, owns = object(group.task).owns+ const starts = list(state.starts)+ const harnessOf = new Map(list(state.agents).map(agent => [agent.id, agent.harnessId]))+ /** The grid model an agent was started on, if it was. */+ const gridOf = (agentId: unknown) => {+ const harness = harnessOf.get(agentId)+ return harness ? text(object(starts.find(s => s.harnessId === harness)?.request).gridModel) : null+ }+ const assignment = object(group.assignment), lost = object(group.lostAttempt)+ const mine = starts.filter(s => object(s.request).conversationId === id)+ const decisions = list(history?.decisions).filter(d => d.conversationId === id && d.final && typeof d.final === 'object')+ const attempts = list(history?.attempts).filter(a => typeof a.id === 'string')+ const agentIds = [assignment.agentId, lost.agentId, ...attempts.map(a => a.agentId)]+ const any = !!text(assignment.id) || !!text(lost.id) || mine.length > 0 || decisions.length > 0 || attempts.length > 0+ const onGrid = mine.map(s => text(object(s.request).gridModel)).find(Boolean) ?? agentIds.map(gridOf).find(Boolean)+ const stepped = text(object(group.stepUp).reason)+ const earlier = stepped ?? (onGrid ? `Its earlier attempt ran on ${onGrid} on the Swarm's grid.` : any ? 'It had an earlier attempt.'+ : !history || !history.decisions || !history.attempts ? EARLIER_UNREADABLE : null)+ return { review: isReview(group), owned: Array.isArray(owns) ? owns.filter(o => typeof o === 'string').length : 0, earlier }+}++/** Why the task is one a grid model never takes: a review (a task linked to the work it reviews, or kind `review`), security+ * work (a security kind, or high risk), or work whose kind is not on [GRID_KINDS], a missing kind included. */+function forbidden(review: boolean, a: Pick<Assessment, 'kind' | 'risk'>): string | null {+ if (review || a.kind === 'review') return NEVER_REVIEWS+ if (a.risk === 'high' || (a.kind && SECURITY_KINDS.has(a.kind))) return NEVER_SECURITY+ if (!a.kind || !GRID_KINDS.includes(a.kind)) return GRID_KINDS_ONLY+ return null+}++/** The guard's name, which starts its reasons ("Grid limits: …"). */+export const GRID_LIMITS = 'Grid limits'+/** Ken's rule, "never route reviews to cheap or local models", and the same for security work: a grid candidate is left out of+ * either, and of any work whose kind is not on [GRID_KINDS], even one a person names. The route itself has no such filter (project instructions, #2414), so this plug-in is the+ * only place it lives. It is made from nothing but the task's own row, so it is ready at once and never depends on a read+ * that could be late (Lead, 10-31). */+export function gridLimits(review: boolean): RoutePlugin {+ return {+ name: GRID_LIMITS,+ adjust(candidate, { assessment }) {+ const why = candidate.gridModel ? forbidden(review, assessment) : null+ return why ? { refuse: true, reason: why } : null+ },+ }+}++/** 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. */+export function cheapFirst(task: CheapTask): RoutePlugin {+ return {+ name: CHEAP_FIRST,+ adjust(candidate, { assessment: a, catalog }) {+ if (!candidate.gridModel || forbidden(task.review, a)) return null+ if (task.earlier) {+ const why = `${FIRST_ATTEMPT_ONLY} ${task.earlier}`+ return a.model || a.local ? { reason: `${why} ${NAMED}` } : { refuse: true, reason: why }+ }+ const small = a.risk === 'low' && a.difficulty === 'low' && task.owned > 0 && task.owned <= MAX_OWNED+ if (!small || candidate.quality < CHEAP_STRENGTH) return null+ const top = Math.max(CHEAP_STRENGTH, ...catalog.models.map(m => m.strength))+ return { strength: top + 1 - CHEAP_STRENGTH, reason: GRID_FIRST }+ },+ }+}++/** The task's row in the tab the route read, or only its id when the tab does not list it. */+const groupIn = (read: Record<string, unknown>, conversationId: string) => {+ const state = object(object(read.tab).state)+ return { state, group: list(state.conversations).find(c => c.id === conversationId) ?? { id: conversationId } }+}++/** Makes [gridLimits] from the tab the route already read: no read of its own and nothing to wait for. */+export const GRID_LIMITS_MAKER: PluginMaker = {+ name: GRID_LIMITS,+ make: async ({ conversationId, read }) => gridLimits(isReview(groupIn(read, conversationId).group)),+}++/** How long the cheap-first maker waits for the route's history read: under the makers' limit (routePlugins.ts+ * MAKER_TIMEOUT_MS), so the first-attempt check is made rather than dropped. A history later than this counts as+ * unreadable, so the grid is left out of the attempt. */+export const HISTORY_WAIT_MS = 2000++/** Makes [cheapFirst] from the route's own reads: the task from the tab it read, and the shared history read. It reads+ * nothing of its own and never fails: what it cannot read makes it leave the grid out of the attempt. */+export const CHEAP_FIRST_MAKER: PluginMaker = {+ name: CHEAP_FIRST,+ async make({ conversationId, read, history }) {+ const { state, group } = groupIn(read, conversationId)+ let timer: NodeJS.Timeout | undefined+ const late = new Promise<null>(resolve => { timer = setTimeout(resolve, HISTORY_WAIT_MS, null) })+ const past = object(await Promise.race([history.catch(() => null), late]).finally(() => clearTimeout(timer)))+ const value = object(past.value)+ return cheapFirst(cheapTaskOf(group, state, past.ok !== true ? null+ : { decisions: Array.isArray(value.decisions) ? value.decisions : null, attempts: Array.isArray(value.attempts) ? value.attempts : null }))+ },+}++/** Piece 4's makers, in order: the guard first, ready at once, then the ranking. */+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.tsindex 8cbece16d..55aea7d06 100644--- a/cli/src/superTabs/routeCommand.spec.ts+++ b/cli/src/superTabs/routeCommand.spec.ts@@ -8,6 +8,7 @@ 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 { MAKER_TIMEOUT_MS, type PluginInput, type PluginMaker } from './routePlugins.js'+import { EARLIER_UNREADABLE, FIRST_ATTEMPT_ONLY, GRID_FIRST, GRID_LIMITS, NEVER_REVIEWS } from './routeCheapFirst.js'// Sonnet rated 3, as an owner who wants Sonnet Builders rates it (a build needs 3: route.ts buildRefusals), so the member these// specs probe can build; the specs of the floor itself use a table of their own ([floorPolicy]).@@ -1585,7 +1586,8 @@ describe('local models on the Swarm\'s grid', () => {{ grid: GRID, model: 'deepseek/deepseek-v4.1', kind: 'api' }, { grid: GRID, model: 'starting', starting: true }, { grid: 7, model: 'odd' }] } },{ machineId: 'old', observation: { receivedAt: 'never', localModels: [{ grid: GRID, model: 'unnamed-host' }] } }] })const s = scoped({ tab: t })- const result = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'low', local: true } }, s, where as never, opener(), () => 'op')+ // 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')const excluded = recorded(s).command.decision.excluded as Array<{ title: string; reason: string }>expect(excluded.filter(e => /offline/.test(e.reason))).toEqual([{ title: 'Kimi K3', reason: 'Its host 2x 4090 Rig is offline, so an agent on it would never start.' },@@ -1605,7 +1607,8 @@ describe('local models on the Swarm\'s grid', () => {const t = tab(); Object.assign(t.state, { localModels: { grid: GRID, enabled: true },machines: [{ machineId: 'm1', observation: { receivedAt: Date.now(), localModels: [{ grid: GRID, model: 'qwen3', name: 'Qwen 3' }] } }] })const s = scoped({ tab: t })- const result = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'low', local: true } }, s, where as never, opener(), () => 'op')+ // 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 })@@ -1696,7 +1699,8 @@ describe('routing by facts', () => {const t = tab(); Object.assign(t.state, { localModels: { grid: GRID, enabled: true },machines: [{ machineId: 'rig', name: 'Rig', observation: { receivedAt: Date.now(), localModels: [], refusedModels: [{ grid: GRID, model: 'llama3.2:3b', why }] } }] })const s = scoped({ tab: t })- const result = await routeTask({ ...input, assessment: { ...input.assessment, local: true } }, s, where as never, opener(), () => 'op')+ // 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(shown(s).every(r => r.gridModel === 'llama3.2:3b' && r.label.includes(why))).toBe(true)})@@ -1722,6 +1726,67 @@ describe('routing by facts', () => {})})+/** Cheap first (Scholes's goals, piece 4) through the whole route: what it reads of the task comes from the tab and the log. */+describe('cheap first, through the route', () => {+ const GRID = 'swarm-0123456789ab', KIMI = 'moonshotai/kimi-k3'+ /** The Swarm serves Kimi K3 on its grid beside the Claude agents of remote-1 and the member Multiply; g1 is a one-file fix. */+ const cheap = (group: Record<string, unknown> = {}, more: Record<string, unknown> = {}) => {+ const t = tab()+ Object.assign(t.state, { localModels: { grid: GRID, enabled: true },+ machines: [{ machineId: 'gpu', name: 'rig', observation: { receivedAt: Date.now(), localModels: [{ grid: GRID, model: KIMI, name: 'Kimi K3', kind: 'api' }] } }], ...more })+ Object.assign(t.state.conversations[1]!, { task: { goal: 'Fix the typo.', owns: ['docs/guide.md'] } }, group)+ return t+ }+ const small = { ...input, assessment: { difficulty: 'low', risk: 'low', size: 'small', why: 'A typo in one doc.', kind: 'docs' } }+ /** The table with the catalog's grid ratings: Kimi K3 at 2. */+ const rated = { ...policy, localModels: { quality: 1, enabled: true, models: [{ model: 'kimi k3', quality: 2 }] } } as typeof policy+ const route = (t: ReturnType<typeof tab>, task = small, history?: Record<string, unknown>) => {+ const s = scoped({ tab: t, policy: rated, ...(history ? { history } : {}) })+ return routeTask(task, s, where as never, opener(), () => 'op').then(answer => ({ answer, s, excluded: recorded(s).command.decision.excluded as Array<{ reason: string }> }))+ }++ 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.+ const medium = await route(cheap(), { ...small, assessment: { ...small.assessment, difficulty: 'medium' } })+ expect(medium.answer).toMatchObject({ ok: true, pick: { 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 () => {+ const tried = cheap({ assignment: { id: 'w1', agentId: 'a3', status: 'cancelled', result: 'Its first review said Ready no.' } }, {+ 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(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.excluded).toContainEqual(expect.objectContaining({ reason: `Cheap first: ${FIRST_ATTEMPT_ONLY} ${EARLIER_UNREADABLE}` }))+ })++ it('the review of a grid-built pull request still runs on a strong model: the grid is left out with why', async () => {+ // g1 was built on Kimi K3; its review task r1 is routed as small and low-risk as the build was, with no kind given.+ const built = cheap({ assignment: { id: 'w1', agentId: 'a3', status: 'review' }, pullRequestUrls: ['https://github.com/o/r/pull/1'] }, {+ 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 } }] })+ 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' } })+ 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)+ expect(excluded).toContainEqual(expect.objectContaining({ reason: `${GRID_LIMITS}: ${NEVER_REVIEWS}` }))+ // Even when a person names the grid model for it.+ const named = await routeTask({ ...small, conversationId: 'r1', assessment: { ...small.assessment, model: 'kimi' } }, scoped({ tab: built, policy: rated }), where as never, opener(), () => 'op')+ expect(named).toMatchObject({ error: 'NO_CANDIDATE' })+ })+})+/** Piece 3 through the route itself, with the makers it ships with (routePlugins.ts ROUTE_PLUGIN_MAKERS). */describe('routing by measured cost and results', () => {const row = (model: string, effort: string, fullCostPerShipped: number) => ({ engine: 'claude', model, effort, kind: 'build', firstReviews: 10,diff --git a/cli/src/superTabs/routePlugins.ts b/cli/src/superTabs/routePlugins.tsindex dd92d6046..c234ab45c 100644--- a/cli/src/superTabs/routePlugins.ts+++ b/cli/src/superTabs/routePlugins.ts@@ -5,6 +5,7 @@import { pluginSkipped, type Assessment, type Catalog, type RoutePlugin } from './route.js'import { MEASURED_MAKER } from './routeMeasured.js'import type { ScopedRequest } from './start.js'+import { CHEAP_FIRST_MAKERS } from './routeCheapFirst.js'import { windowPullMaker } from './windowPull.js'type Json = Record<string, unknown>@@ -26,6 +27,7 @@ export interface PluginMaker { readonly name: string; make(input: PluginInput):/** The makers, in the order their plug-ins run. One line per piece. */export const ROUTE_PLUGIN_MAKERS: readonly PluginMaker[] = [+ ...CHEAP_FIRST_MAKERS, // piece 4: never a grid model for a review or security work; a small, low-risk build tries one first// Piece 3: measured cost per shipped change and first-review pass rate, per kind of work.MEASURED_MAKER,windowPullMaker(),diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.tsindex 6ba3453e1..dd30e2ab3 100644--- a/cli/src/superTabs/service.spec.ts+++ b/cli/src/superTabs/service.spec.ts@@ -12,6 +12,7 @@ import { object } from './wire.js'import { hostForm, swarmReply } from './fixtures/read/index.js'import { HostFeed } from './hostFeed.js'import { SwarmReads } from './swarmReads.js'+import { CHEAP_FIRST_HELP, GRID_KINDS, MAX_OWNED, ROUTE_KIND_HELP } from './routeCheapFirst.js'const list = (value: unknown) => Array.isArray(value) ? value.map(object) : []import { hostJournalFile, SuperTabHostError, type SuperTabHost, type SuperTabHostOptions } from './host.js'@@ -829,9 +830,17 @@ it('says a server from before rules does not support them, and passes a malforme})// 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 the route leaves out only what cannot run, and how it ranks the rest', async () => {+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 () => {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 only what cannot run')+ 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.+ expect(help.route).not.toContain('leaves out only')+ // Kind decides whether a grid model is offered (routeCheapFirst.ts): the help names the list from the same constant.+ expect(help.route).toContain(`"kind":"${ROUTE_KIND_HELP}"`)+ expect(help.route).toContain(CHEAP_FIRST_HELP)+ 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} ${help.command}`).not.toMatch(/noGridFirst|policy rates 3|low-risk work of kind docs|NO_CANDIDATE/)diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.tsindex 9b9936cba..0650dfcba 100644--- a/cli/src/superTabs/service.ts+++ b/cli/src/superTabs/service.ts@@ -1,4 +1,5 @@import { readCapabilities } from './capacity.js'+import { CHEAP_FIRST_HELP, ROUTE_KIND_HELP } from './routeCheapFirst.js'import { existsSync } from 'node:fs'import { readAuthSession } from '../lib/authSession.js'import { createHash } from 'node:crypto'@@ -83,7 +84,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":"optional word such as ui or docs","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 only 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. 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: 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.`,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.',diff --git a/cli/vitest.super-tabs.config.ts b/cli/vitest.super-tabs.config.tsindex 4938c454c..b69f82b8b 100644--- a/cli/vitest.super-tabs.config.ts+++ b/cli/vitest.super-tabs.config.ts@@ -8,7 +8,7 @@ import base from './vitest.config.js'const IN_CORE = ['adoption', 'agents', 'attention', 'cards', 'deliveries', 'launch', 'role', 'teamApps', 'teamPurge', 'terminal'].map(name => `src/superTabs/inCore/${name}.ts`)const FILES = ['src/superTabs/route.ts', 'src/superTabs/routeCommand.ts', 'src/superTabs/routePlugins.ts', 'src/superTabs/shortCommand.ts', ...IN_CORE,// The routing plug-ins (routePlugins.ts), one line each.- 'src/superTabs/routeMeasured.ts', 'src/superTabs/windowPull.ts',+ 'src/superTabs/routeCheapFirst.ts', 'src/superTabs/routeMeasured.ts', 'src/superTabs/windowPull.ts',]export default defineConfig({test: {