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
Owner rules replace Jev in Swarm routing (#1586)
0xken15975ff323d4da
diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.tsindex 6cb7cbb85..a539cc23d 100644--- a/backend/integration/superTabs.test.ts+++ b/backend/integration/superTabs.test.ts@@ -776,6 +776,24 @@ describe('Super Tabs on a real Mongo replica set', () => {await expect(store.read({ ...owner, autonomousEnv: 'stag' }, tab)).rejects.toMatchObject({ code: 'NOT_FOUND' })})+ it('lets the Lead record a rule only by quoting a message the owner wrote in this tab', async () => {+ const { tab, lead } = await fixture()+ await invite(tab)+ const said = (await run(tab, message('Never use Haiku.'))).result.messageId as string+ const other = (await run(tab, message('Use Haiku.'), peer)).result.messageId as string+ const rule = (messageId: string): Command => ({ type: 'rule.set', rule: { kind: 'forbidModel', model: 'haiku' }, text: 'Never use Haiku.',+ askedIn: { conversationId: 'lead', messageId } })+ await expect(run(tab, rule(other), host, lead)).rejects.toMatchObject({ code: 'OWNER_MESSAGE_REQUIRED' })+ await expect(run(tab, rule('missing'), host, lead)).rejects.toMatchObject({ code: 'OWNER_MESSAGE_REQUIRED' })+ await run(tab, rule(said), host, lead)+ const state = (await store.read(owner, tab)).state+ expect(state.rules).toEqual([expect.objectContaining({ text: 'Never use Haiku.', askedBy: owner.sub, askedIn: { conversationId: 'lead', messageId: said } })])+ // One message may ask for several rules, but the owner's "Rule added" row is not the owner asking.+ await run(tab, { ...rule(said), rule: { kind: 'minEffort', effort: 'high' } } as Command, host, lead)+ expect((await store.read(owner, tab)).state.rules).toHaveLength(2)+ const ownRow = await run(tab, { type: 'rule.set', rule: { kind: 'preferIdle' }, text: 'Reuse idle agents.' })+ await expect(run(tab, rule(ownRow.result.messageId as string), host, lead)).rejects.toMatchObject({ code: 'OWNER_MESSAGE_REQUIRED' })+ })it('closes the replying agent\'s own deliveries of a message as answered, and nobody else\'s', async () => {const { tab, lead } = await fixture()const helper = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: randomUUID(),diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.tsindex a419fe254..fec0b59af 100644--- a/backend/src/superTabs/commands.test.ts+++ b/backend/src/superTabs/commands.test.ts@@ -3,6 +3,7 @@ import { applyCommand, commandSchema, PAIR_CHAIN_LIMIT, type Command, type Commaimport { machineSlots } from './machines.js'import { activeWork, agentRole, createSuperTab, visibleState, type Actor, type AgentConfiguration } from './model.js'import type { RouteDecision } from './routeRecord.js'+import { agentTarget, broken } from './rules.js'const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }const peer: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'peer', email: '[email protected]' }@@ -1162,3 +1163,173 @@ describe('Reviewer role', () => {expect(f.state.agents.find(a => a.id === reviewer)).not.toHaveProperty('workDecision')})})++describe('the owner\'s rules', () => {+ const asked = { askedIn: { conversationId: 'lead', messageId: 'm1' } }+ const said = (patch: Record<string, unknown> = {}) => ({ askedIn: { author: { kind: 'person', id: 'owner', name: owner.email, membershipGeneration: 'tab' },+ source: false, createdAt: 1000, ...patch } }) as Partial<CommandContext>+ const ownerSaid = said()+ const quoting = (messageId: string) => ({ askedIn: { conversationId: 'lead', messageId } })+ const set = (rule: Record<string, unknown>, text = 'No Haiku.') => ({ type: 'rule.set', rule, text } as Command)+ const startBy = (f: ReturnType<typeof routed>, actor: Actor, patch: Record<string, unknown> = {}) => f.run({ type: 'agent.start', request: { conversationId: 'lead', machineId: 'machine',+ engine: 'claude', model: 'opus', effort: 'high', name: 'Builder', cwd: '/repo', worktree: true,+ requirements: { memoryBytes: 1, diskBytes: 1, maxCpuPercent: 80, tools: [], devices: [], quotaRequired: false }, ...patch }, ...via } as Command, actor, { contribution: f.contribution, ...decisionIn() })++ it('lets the owner set, list and remove rules, and records who asked', () => {+ const f = routed()+ const added = f.run(set({ kind: 'forbidModel', model: 'haiku' }))+ expect(f.state.rules).toEqual([{ id: added.result.ruleId, rule: { kind: 'forbidModel', model: 'haiku' }, text: 'No Haiku.', askedBy: 'owner', askedIn: null,+ addedBy: 'person:owner', createdAt: new Date(1000).toISOString() }])+ expect(added.messages[0]).toMatchObject({ conversationId: 'lead', text: 'Rule added: No Haiku.', source: { kind: 'rule' } })+ // Everyone in the Swarm reads the rules with the tab.+ expect(visibleState(f.state, f.leadActor).rules).toHaveLength(1)+ // A second list of machines replaces the first.+ f.run(set({ kind: 'machines', machineIds: ['m1'] }, 'Only m1.'))+ f.run(set({ kind: 'machines', machineIds: ['m2'] }, 'Only m2.'))+ expect(f.state.rules!.map(r => r.text)).toEqual(['No Haiku.', 'Only m2.'])+ expect(f.run({ type: 'rule.remove', ruleId: added.result.ruleId as string }).messages[0]!.text).toBe('Rule removed: No Haiku.')+ f.run({ type: 'rule.remove', ruleId: f.state.rules![0]!.id })+ expect(f.state).not.toHaveProperty('rules')+ expect(() => f.run({ type: 'rule.remove', ruleId: 'gone' })).toThrow('no such rule')+ for (let i = 0; i < 50; i++) f.run(set({ kind: 'preferIdle' }, `Rule ${i}.`))+ expect(() => f.run(set({ kind: 'preferIdle' }))).toThrow('50 rules')+ expect(() => f.run(set({ kind: 'minEffort', effort: 'huge' }))).toThrow()+ })+ it('lets the Lead change rules only by quoting the owner\'s message, and nobody else', () => {+ const f = routed()+ const added = f.run({ ...set({ kind: 'forbidModel', model: 'haiku' }), ...asked } as Command, f.leadActor, ownerSaid)+ expect(f.state.rules![0]).toMatchObject({ askedBy: 'owner', askedIn: asked.askedIn, addedBy: `agent:${f.lead}` })+ const relay = (messageId: string, context: Partial<CommandContext>) => f.run({ ...set({ kind: 'preferIdle' }), ...quoting(messageId) } as Command, f.leadActor, context)+ expect(() => f.run(set({ kind: 'preferIdle' }), f.leadActor, ownerSaid)).toThrow('quote a chat message the owner wrote')+ expect(() => relay('m2', {})).toThrow('quote a chat message the owner wrote')+ for (const author of [{ kind: 'person', id: 'peer' }, { kind: 'agent', id: 'owner' }]) {+ expect(() => relay('m2', said({ author }))).toThrow('quote a chat message the owner wrote')+ }+ // The owner's own system rows ("Rule added", warnings) and a message older than a day do not count.+ expect(() => relay('m2', said({ source: true }))).toThrow('quote a chat message the owner wrote')+ expect(() => relay('m2', said({ createdAt: 1000 - 24 * 3_600_000 - 1 }))).toThrow('quote a chat message the owner wrote')+ // One message may ask for several rules.+ expect(relay('m1', ownerSaid).result.ruleId).toBeTruthy()+ expect(relay('m2', said({ createdAt: 1000 - 24 * 3_600_000 })).result.ruleId).toBeTruthy()+ expect(() => f.run({ ...set({ kind: 'preferIdle' }), ...asked } as Command, f.workerActor, ownerSaid)).toThrow('Only the Swarm owner')+ f.invite()+ expect(() => f.run(set({ kind: 'preferIdle' }), peer)).toThrow('Only the Swarm owner')+ expect(() => f.run({ type: 'rule.remove', ruleId: added.result.ruleId as string }, peer)).toThrow('Only the Swarm owner')+ f.run({ type: 'rule.remove', ruleId: added.result.ruleId as string, ...asked }, f.leadActor, ownerSaid)+ expect(f.state.rules!.map(r => r.text)).toEqual(['No Haiku.', 'No Haiku.'])+ })+ it('refuses an agent\'s start that breaks a hard rule, whatever reason it gives', () => {+ const f = routed()+ expect(startBy(f, f.leadActor).result.startId).toBeTruthy()+ f.run(set({ kind: 'forbidModel', model: 'OPUS' }, 'No Opus.'))+ expect(() => startBy(f, f.leadActor)).toThrow('The owner\'s rule "No Opus." rules out Claude opus. Route again.')+ expect(startBy(f, f.leadActor, { model: 'sonnet' }).result.startId).toBeTruthy()+ f.run(set({ kind: 'minEffort', engine: 'claude', effort: 'high' }, 'High effort.'))+ expect(() => startBy(f, f.leadActor, { model: 'sonnet', effort: 'medium' })).toThrow('rules out Claude at medium effort')+ expect(() => startBy(f, f.leadActor, { model: 'sonnet', effort: undefined })).toThrow('rules out Claude at an unnamed effort')+ expect(startBy(f, f.leadActor, { model: 'sonnet', effort: 'max' }).result.startId).toBeTruthy()+ f.run(set({ kind: 'machines', machineIds: ['elsewhere'] }, 'Only elsewhere.'))+ expect(() => startBy(f, f.leadActor, { model: 'sonnet' })).toThrow('rules out this machine')+ })+ it('lets a person through with a warning the group sees', () => {+ const f = routed()+ f.run(set({ kind: 'forbidModel', model: 'opus' }, 'No Opus.'))+ const effects = startBy(f, owner)+ expect(effects.result).toMatchObject({ startId: expect.any(String), warnings: ['The owner\'s rule "No Opus." rules out Claude opus.'] })+ expect(effects.messages).toEqual(expect.arrayContaining([expect.objectContaining({ conversationId: 'lead',+ text: 'owner started Builder anyway. The owner\'s rule "No Opus." rules out Claude opus.', source: { kind: 'rule' } })]))+ })+ it('refuses an agent\'s assignment of a worker that breaks a hard rule, with the effort it was launched with', () => {+ const f = routed()+ f.define('lead')+ f.run(set({ kind: 'forbidModel', engine: 'codex', model: 'test' }, 'No test model.'))+ expect(() => f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker, ...via }, f.leadActor, decisionIn())).toThrow('rules out Codex test-model')+ const effects = f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker })+ expect(effects.result.warnings).toEqual(['The owner\'s rule "No test model." rules out Codex test-model.'])+ expect(effects.messages.map(m => m.text)).toContain('owner assigned worker anyway. The owner\'s rule "No test model." rules out Codex test-model.')+ // An agent that reports `auto` is held to the effort its start asked for.+ const worker = f.state.agents.find(a => a.id === f.worker)!+ worker.configuration.effort = 'auto'+ const rule = [{ id: 'r', rule: { kind: 'minEffort', effort: 'high' } as const, text: 'High.', askedBy: 'owner', askedIn: null, addedBy: 'person:owner', createdAt: '' }]+ expect(broken(rule, agentTarget(f.state, worker))).toContain('an unnamed effort')+ f.state.starts = [{ harnessId: worker.harnessId, request: { machineId: worker.machineId, effort: 'xhigh' } } as never]+ expect(broken(rule, agentTarget(f.state, worker))).toBeNull()+ })+ it('refuses a recorded pick that breaks a hard rule, but not a ruled-out candidate that was not picked', () => {+ const f = routed()+ const route = (decision: unknown) => f.run({ type: 'route.record', conversationId: 'lead', decision } as Command, f.leadActor, { recentRoutes: 0 })+ f.run(set({ kind: 'forbidModel', model: 'sonnet' }, 'No Sonnet.'))+ expect(route(record()).result.routeDecisionId).toBeTruthy()+ expect(() => route(record({ pick: 'c1' }))).toThrow('The owner\'s rule "No Sonnet." rules out Claude sonnet.')+ // A member pick is judged by what the member runs now.+ const member = record({ candidates: [candidate('c0', { kind: 'member', agentId: f.worker, machineId: 'host', engine: 'codex', model: 'other' })] })+ f.run(set({ kind: 'forbidModel', model: 'test-model' }, 'No test model.'))+ expect(() => route(member)).toThrow('rules out Codex test-model')+ })+ it('lets a person override to a ruled-out candidate with a warning', () => {+ const f = routed()+ f.run(set({ kind: 'forbidModel', model: 'sonnet' }, 'No Sonnet.'))+ const open = { id: 'd1', conversationId: 'lead', record: record(), final: null, override: null, assignmentId: null, outcome: null } as unknown as RouteDecision+ const effects = f.run({ type: 'route.override', decisionId: 'd1', candidateId: 'c1', reason: 'Because.' }, owner, { routeDecision: open })+ expect(effects.result.warnings).toEqual(['The owner\'s rule "No Sonnet." rules out Claude sonnet.'])+ })+})++describe('the owner\'s rules, after review', () => {+ const set = (rule: Record<string, unknown>, text = 'Rule.') => ({ type: 'rule.set', rule, text } as Command)+ const request = (patch: Record<string, unknown> = {}) => ({ conversationId: 'lead', machineId: 'machine', engine: 'claude', model: 'opus', effort: 'high', name: 'Builder',+ cwd: '/repo', worktree: true, requirements: { memoryBytes: 1, diskBytes: 1, maxCpuPercent: 80, tools: [], devices: [], quotaRequired: false }, ...patch })+ it('checks an agent joining or leading a group, and never one leaving it', () => {+ const f = routed(), group = f.group()+ f.run(set({ kind: 'forbidModel', model: 'test-model' }, 'No test model.'))+ expect(() => f.run({ type: 'conversation.agent', conversationId: 'lead', agentId: f.worker, present: true, lead: false }, f.leadActor))+ .toThrow('The owner\'s rule "No test model." rules out Codex test-model. Route again.')+ const byHand = f.run({ type: 'conversation.agent', conversationId: group, agentId: f.worker, present: true, lead: true })+ expect(byHand.result.warnings).toEqual(['The owner\'s rule "No test model." rules out Codex test-model.'])+ expect(byHand.messages[0]).toMatchObject({ text: 'owner added worker anyway. The owner\'s rule "No test model." rules out Codex test-model.' })+ expect(f.run({ type: 'conversation.agent', conversationId: 'lead', agentId: f.worker, present: false, lead: false }, f.leadActor).messages).toEqual([])+ })+ it('does not launch a start recorded before a rule, unless a person chose it', () => {+ const f = routed()+ const startId = f.run({ type: 'agent.start', request: request(), ...via } as Command, f.leadActor, { contribution: f.contribution, ...decisionIn() }).result.startId as string+ f.run(set({ kind: 'minEffort', effort: 'max' }, 'Max effort.'))+ expect(() => f.run({ type: 'agent.startDispatch', startId }, f.leadActor, { contribution: f.contribution }))+ .toThrow('The owner\'s rule "Max effort." rules out Claude at high effort. This start was not launched. Route again.')+ const chosen = decisionIn().routeDecision+ f.run({ type: 'agent.startDispatch', startId }, f.leadActor, { contribution: f.contribution, routeDecision: { ...chosen, override: { by: 'person', actorKey: 'person:owner', candidateId: 'c0', reason: 'r' } } })+ expect(f.state.starts!.find(s => s.id === startId)!.dispatched).toBe(true)+ // A person's own start is launched; the warning was given when it was asked for.+ const own = f.run({ type: 'agent.start', request: request() } as Command, owner, { contribution: f.contribution }).result.startId as string+ expect(f.run({ type: 'agent.startDispatch', startId: own }, owner, { contribution: f.contribution }).messages).toEqual([])+ })+ it('lets the Lead carry out a person\'s override to a ruled-out candidate, and nothing else', () => {+ const f = routed()+ f.run(set({ kind: 'forbidModel', model: 'sonnet' }, 'No Sonnet.'))+ const decision = { ...decisionIn().routeDecision, override: { by: 'person', actorKey: 'person:owner', candidateId: 'c1', reason: 'Opus is busy.' } } as RouteDecision+ const sonnet = request({ model: 'sonnet' })+ const effects = f.run({ type: 'agent.start', request: sonnet, routeDecisionId: 'd1' } as Command, f.leadActor, { contribution: f.contribution, routeDecision: decision })+ expect(effects.result.warnings).toEqual(['The owner\'s rule "No Sonnet." rules out Claude sonnet.'])+ // Without the person's choice the same start is refused, and a reason of the Lead's own does not get past it.+ expect(() => f.run({ type: 'agent.start', request: sonnet, ...via } as Command, f.leadActor, { contribution: f.contribution, ...decisionIn() })).toThrow('Route again')+ // The person chose sonnet; the Lead starting something else that breaks a rule is still refused.+ f.run(set({ kind: 'forbidModel', model: 'opus' }, 'No Opus.'))+ expect(() => f.run({ type: 'agent.start', request: request(), routeDecisionId: 'd1', overrideReason: 'Mine.' } as Command, f.leadActor, { contribution: f.contribution, routeDecision: decision })).toThrow('No Opus.')+ // An assignment that carries out the person's choice of a member goes through too.+ f.define('lead')+ const member = { ...decision, record: record({ candidates: [candidate('c0'), candidate('c1', { kind: 'member', agentId: f.worker, machineId: 'host', engine: 'codex', model: 'test-model' })] }) } as unknown as RouteDecision+ f.run(set({ kind: 'forbidModel', model: 'test' }, 'No test model.'))+ expect(f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker, routeDecisionId: 'd1' }, f.leadActor, { routeDecision: member }).result.warnings).toHaveLength(1)+ })+ it('matches a model as the owner named it: an alias for a full id, and never an unknown default', () => {+ const rule = (model: string) => [{ id: 'r', rule: { kind: 'forbidModel', model } as const, text: 'R.', askedBy: 'owner', askedIn: null, addedBy: 'person:owner', createdAt: '' }]+ const target = (model: string | null) => ({ machineId: 'm', engine: 'claude', model, effort: 'high' })+ expect(broken(rule('claude-haiku-4-5'), target('haiku'))).toContain('R.')+ expect(broken(rule('haiku'), target('claude-haiku-4-5'))).toContain('R.')+ expect(broken(rule('claude-haiku-4-5'), target('sonnet'))).toBeNull()+ expect(broken(rule('claude-haiku-4-5'), target('claude-haiku-3'))).toBeNull()+ for (const model of ['def', 'default']) {+ expect(broken(rule(model), target('default'))).toBeNull()+ expect(broken(rule(model), target(null))).toBeNull()+ }+ })+})diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex 0acee3b42..257dc61d9 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -8,6 +8,7 @@ import {} from './model.js'import { routeRecordSchema, routeTitle, startedAs, type RouteCandidate, type RouteDecision, type RouteFinal, type RouteOverride } from './routeRecord.js'import { routingOverrideSchema } from './routingPolicy.js'+import { agentTarget, askedInSchema, broken, MAX_RULES, RULE_MESSAGE_MS, ruleSchema, ruleTextSchema, startTarget, type RunTarget } from './rules.js'import { MAX_ATTACHMENTS, type Attachment } from './attachments.js'import { agentProjectId, deleteProject, groupProject, inviteLanding, manageProject, mutableProjects, projectMembers, projectOf, readAgent, readConversation, readProject, sameProject } from './projects.js'@@ -58,6 +59,8 @@ export const commandSchema = z.discriminatedUnion('type', [z.object({ type: z.literal('tab.project'), machineId: id, project }).strict(),z.object({ type: z.literal('tab.pause'), paused: z.boolean() }).strict(),z.object({ type: z.literal('tab.routingPolicy'), policy: routingOverrideSchema.nullable() }).strict(),+ z.object({ type: z.literal('rule.set'), rule: ruleSchema, text: ruleTextSchema, askedIn: askedInSchema.optional() }).strict(),+ z.object({ type: z.literal('rule.remove'), ruleId: id, askedIn: askedInSchema.optional() }).strict(),z.object({ type: z.literal('project.create'), name: title, visibility: z.enum(['public', 'private']), brief: z.string().trim().max(8000).default('') }).strict(),z.object({ type: z.literal('project.rename'), projectId: id, name: title }).strict(),z.object({ type: z.literal('project.delete'), projectId: id }).strict(),@@ -112,6 +115,8 @@ export interface CommandContext {contribution?: { machineOwnerId: string; contributorId: string; hostGrant?: string | null }/** Loaded from this tab and conversation by the store. */reply?: { id: string; conversationId: string; author: Author }+ /** The message a Lead quotes as the owner's request for a rule change, loaded from this tab by the store. */+ askedIn?: { author: Author; source: boolean; createdAt: number }/** The newest messages of this conversation before the one being sent, newest first, loaded by the store for `message.send`. */recent?: { author: Author; recipients: string[] }[]/** A host's receipt, not an elapsed lease, proves that an assignment stopped. */@@ -169,6 +174,7 @@ export function authorizeCommandAccess(state: SuperTabState, actor: Actor, commaif ('projectId' in command && command.projectId) readProject(state, actor, command.projectId)if ('agentId' in command) readAgent(state, actor, command.agentId)if (command.type === 'agent.start') readConversation(state, actor, command.request.conversationId)+ if ((command.type === 'rule.set' || command.type === 'rule.remove') && command.askedIn) readConversation(state, actor, command.askedIn.conversationId)if ('startId' in command && command.type !== 'route.modelResult') {const start = state.starts?.find(s => s.id === command.startId) ?? fail('NOT_FOUND', 'This agent start is unavailable.', 404)readConversation(state, actor, start.request.conversationId)@@ -237,6 +243,31 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaconst routed = (routeDecisionId?: string) => {if (actor.kind === 'agent' && !routeDecisionId) fail('ROUTE_REQUIRED', 'Route this task first, then start or assign the pick with its routeDecisionId.', 400)}+ /** Rows the system writes for rules; a Lead cannot quote one as the owner asking. Names, not emails, in the text. */+ const RULE_ROW = { kind: 'rule' }+ const who = sender.kind === 'person' ? sender.name.split('@')[0]! : sender.name+ /** A hard rule refuses an agent, unless it carries out what a person chose by hand. A person is not blocked: the+ * command goes through and the group is told. */+ const ruled = (target: RunTarget, conversationId: string, done: string, personChose = false) => {+ const why = broken(state.rules, target)+ if (!why) return+ if (actor.kind === 'agent' && !personChose) fail('RULE_BROKEN', `${why} Route again.`, 403)+ result.warnings = [why]+ effects.messages.push({ id: stableId(operationId, 'rule'), conversationId, author: sender, text: `${done} anyway. ${why}`, replyTo: null, recipients: [], source: RULE_ROW })+ }+ /** Only the owner changes rules, or the tab's Lead quoting a chat message the owner wrote in the last day (review of+ * #1586: any owner row, a rule row included, could otherwise be quoted at any time). One message may ask for several rules. */+ const ruleChange = (askedIn: { conversationId: string; messageId: string } | undefined) => {+ if (actor.kind === 'person' && actor.userId === state.ownerId) return+ if (actor.kind !== 'agent' || conversation(state, 'lead').leadId !== actor.agentId) {+ fail('OWNER_REQUIRED', 'Only the Swarm owner, or the Lead passing on the owner\'s request, changes rules.', 403)+ }+ const asked = askedIn && context.askedIn+ if (!asked || asked.author.kind !== 'person' || asked.author.id !== state.ownerId || asked.source+ || context.now - asked.createdAt > RULE_MESSAGE_MS) {+ fail('OWNER_MESSAGE_REQUIRED', 'Only the Swarm owner sets rules; quote a chat message the owner wrote in the last day asking for this change.', 403)+ }+ }const openDecision = (): RouteDecision => {const decision = context.routeDecision ?? fail('NOT_FOUND', 'This routing decision is unavailable.', 404)if (decision.outcome) fail('ROUTE_CLOSED', 'This routing decision is no longer open. Route the task again.')@@ -390,6 +421,25 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaif (command.policy && Object.keys(command.policy).length) state.routingPolicy = command.policyelse delete state.routingPolicybreak+ case 'rule.set': {+ ruleChange(command.askedIn)+ // There is one machines list; a new one replaces it.+ const rules = (state.rules ?? []).filter(r => command.rule.kind !== 'machines' || r.rule.kind !== 'machines')+ if (rules.length >= MAX_RULES) fail('RULES_FULL', `This Swarm has ${MAX_RULES} rules. Remove one first.`)+ state.rules = [...rules, { id: operationId, rule: command.rule, text: command.text, askedBy: state.ownerId,+ askedIn: command.askedIn ?? null, addedBy: actorKey(actor), createdAt: new Date(context.now).toISOString() }]+ result.ruleId = operationId+ message('lead', `Rule added: ${command.text}`, [], null, RULE_ROW)+ break+ }+ case 'rule.remove': {+ ruleChange(command.askedIn)+ const rule = state.rules?.find(r => r.id === command.ruleId) ?? fail('NOT_FOUND', 'This Swarm has no such rule.', 404)+ state.rules = state.rules!.filter(r => r.id !== rule.id)+ if (!state.rules.length) delete state.rules+ message('lead', `Rule removed: ${rule.text}`, [], null, RULE_ROW)+ break+ }case 'conversation.create': {const brief = command.task ? renderWorkTask(command.task) : command.brief ?? ''const project = readProject(state, actor, command.projectId ??@@ -500,6 +550,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: CommacontributorId: contributor.id, membershipGeneration: contributor.generation, machineOwnerId: grant.machineOwnerId,hostGrant: grant.hostGrant ?? null, request: command.request, harnessId: null, dispatched: false, error: null })result.startId = operationId+ let personChose = falseif (command.routeDecisionId) {const r = command.requestconst model = r.model ?? 'default', effort = r.effort ?? 'default'@@ -508,7 +559,9 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma() => ({ kind: 'new', startId: operationId, machineId: r.machineId, engine: r.engine, model, effort }), command.overrideReason)if (override) message(r.conversationId, `Lead started ${r.name} instead of ${expected.title}. Reason: ${override.reason}`, [], null,{ kind: 'route-override', decisionId: decision.id, by: 'lead' })+ personChose = !override && decision.override?.by === 'person'}+ ruled(startTarget(command.request), command.request.conversationId, `${who} started ${command.request.name}`, personChose)break}case 'agent.startDispatch':@@ -521,6 +574,9 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commacontrols(state, actor, start.request.conversationId)if (command.type === 'agent.startDispatch') {if (state.paused) fail('PAUSED', 'New work is paused in this Super Tab.')+ // A start recorded before a rule was added is not launched past it, unless a person asked for it by hand.+ const why = actor.kind === 'agent' && !(start.routeDecisionId && context.routeDecision?.override?.by === 'person') && broken(state.rules, startTarget(start.request))+ if (why) fail('RULE_BROKEN', `${why} This start was not launched. Route again.`, 403)requireWorkerDecisions(state, actor, open(state, start.request.conversationId))const grant = context.contribution ?? fail('HOST_REQUIRED', 'The original machine grant is unavailable.', 403)if (grant.machineOwnerId !== start.machineOwnerId || (grant.hostGrant ?? null) !== start.hostGrant) {@@ -670,6 +726,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commagroup.agentIds = group.agentIds.filter(id => id !== command.agentId)if (group.leadId === command.agentId) group.leadId = null} else {+ ruled(agentTarget(state, member), group.id, `${who} added ${member.name}`)if (!group.agentIds.includes(command.agentId)) group.agentIds.push(command.agentId)// Adding a Reviewer to a group reuses it, as assigning work reuses a Builder.if (reviewer) delete member.workDecision@@ -762,6 +819,8 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaconst chosen = command.decision.candidates.find(c => c.id === command.decision.pick)!const member = chosen.kind === 'member' ? state.agents.find(a => a.id === chosen.agentId) : undefinedif (member) assignable(conversation(state, command.conversationId), member)+ // Only the pick is checked, so an older CLI that still lists a ruled-out candidate records an allowed pick.+ ruled(member ? agentTarget(state, member) : chosen, command.conversationId, `${who} routed to ${chosen.title}`)requireWorkerDecisions(state, actor, open(state, command.conversationId), chosen.kind === 'member' ? chosen.agentId : undefined)if ((context.recentRoutes ?? 0) >= 30) fail('RATE_LIMITED', 'This Super Tab routed 30 tasks in the last hour. Wait before routing again.', 429)const decision = command.decision@@ -799,6 +858,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaconst chosen = decision.record.candidates.find(c => c.id === command.candidateId) ?? fail('NOT_FOUND', 'Choose one of this decision’s candidates.', 404)if (chosen.id === current) fail('ALREADY_CHOSEN', 'That candidate is already the choice.')if (chosen.kind === 'member' && !state.agents.some(a => a.id === chosen.agentId)) fail('CANDIDATE_UNAVAILABLE', 'That agent left this Super Tab. Choose another.')+ ruled(chosen.kind === 'member' ? agentTarget(state, agent(state, chosen.agentId!)) : chosen, decision.conversationId, `${who} chose ${chosen.title}`)effects.routeDecisions.push({ op: 'override', id: decision.id, override: { by: 'person', actorKey: actorKey(actor), candidateId: chosen.id, reason: command.reason } })const lead = conversation(state, decision.conversationId).leadIdmessage(decision.conversationId,@@ -851,7 +911,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaexecution: { machineId: worker.machineId, harnessId: worker.harnessId, machineOwnerId: worker.machineOwnerId }, result: null }group.checks.forEach(c => { c.evidence = null; c.passedBy = null })result.assignmentId = operationId- let routeNote: { decisionId: string; text: string } | null = null+ let routeNote: { decisionId: string; text: string } | null = null, personChose = falseif (command.routeDecisionId) {const started = (d: RouteDecision) => d.final?.kind === 'new' &&!!state.starts?.some(s => s.id === (d.final as { startId: string }).startId && s.harnessId === worker.harnessId && s.request.machineId === worker.machineId)@@ -861,7 +921,9 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: CommastartedAs(c, d.final)),d => started(d) ? d.final! : { kind: 'member', agentId: worker.id, machineId: worker.machineId }, command.overrideReason, operationId)if (override) routeNote = { decisionId: decision.id, text: `Lead assigned ${worker.name} instead of ${expected.title}. Reason: ${override.reason}` }+ personChose = !override && decision.override?.by === 'person'}+ ruled(agentTarget(state, worker), group.id, `${who} assigned ${worker.name}`, personChose)message(group.id, `${group.brief}\n\nAcceptance checks:\n${group.checks.map(c => `- ${c.description}`).join('\n')}`, [worker.id])if (routeNote) effects.messages.push({ id: stableId(operationId, 'route-override'), conversationId: group.id, author: sender,text: routeNote.text, replyTo: null, recipients: [], source: { kind: 'route-override', decisionId: routeNote.decisionId, by: 'lead' } })diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.tsindex dba5caa4a..6c9e38e87 100644--- a/backend/src/superTabs/model.ts+++ b/backend/src/superTabs/model.ts@@ -133,6 +133,8 @@ export interface SuperTabState {environment: string/** Fields this tab overrides from its owner's account routing policy (routingPolicy.ts). */routingPolicy?: import('./routingPolicy.js').RoutingOverride+ /** The owner's routing rules (rules.ts); absent until the first is set. */+ rules?: import('./rules.js').SwarmRule[]/** Owner-only sharing configuration; visibleState always removes it. */sharing?: import('./sharing.js').SwarmSharingpaused: booleandiff --git a/backend/src/superTabs/rules.ts b/backend/src/superTabs/rules.tsnew file mode 100644index 000000000..6378c6bfd--- /dev/null+++ b/backend/src/superTabs/rules.ts@@ -0,0 +1,74 @@+/** The Swarm owner's routing rules (docs/plans/2026-10-22-swarm-rules-routing.md). Hard rules bind agents: the backend+ * refuses an agent's start, assignment or recorded pick that breaks one, and lets a person through with a warning.+ * Soft rules only rank candidates in the CLI's route. They replaced Jev in routing after the Lead overrode its pick about+ * half the time on 2026-10-22 (Haiku, a stopping agent, low effort) because it did not know the owner's rules. */+import { z } from 'zod'+import type { Agent, SuperTabState } from './model.js'++const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)+const engine = z.enum(['claude', 'codex'])+const EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const+export const ruleSchema = z.discriminatedUnion('kind', [+ z.object({ kind: z.literal('forbidModel'), engine: engine.optional(), model: z.string().trim().min(1).max(200) }).strict(),+ z.object({ kind: z.literal('machines'), machineIds: z.array(id).min(1).max(50) }).strict(),+ z.object({ kind: z.literal('minEffort'), engine: engine.optional(), effort: z.enum(EFFORTS) }).strict(),+ z.object({ kind: z.literal('preferEngine'), taskKind: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/).nullable(), engine }).strict(),+ z.object({ kind: z.literal('preferIdle') }).strict(),+])+export const ruleTextSchema = z.string().trim().min(1).max(200)+export const askedInSchema = z.object({ conversationId: id, messageId: id }).strict()+export const MAX_RULES = 50+/** How long an owner's message can back the rule changes the Lead passes on. */+export const RULE_MESSAGE_MS = 24 * 3_600_000++export interface SwarmRule {+ id: string+ rule: z.infer<typeof ruleSchema>+ /** The owner's words, shown when the rules are listed and quoted when one refuses. */+ text: string+ askedBy: string+ /** The owner's message a Lead relayed; null when the owner set the rule. */+ askedIn: z.infer<typeof askedInSchema> | null+ addedBy: string+ createdAt: string+}+/** What would run: a start request, an agent's configuration, or a routed pick. Null when not known. */+export interface RunTarget { machineId: string; engine: string; model: string | null; effort: string | null }++const ENGINE: Record<string, string> = { claude: 'Claude', codex: 'Codex' }+/** `default` and `auto` say nothing about the effort, so they never meet a minimum. */+const rank = (effort: string | null) => EFFORTS.indexOf((effort ?? '') as typeof EFFORTS[number])+const FAMILY = /haiku|sonnet|opus|fable/+/** A rule names a model as the owner said it: `haiku` matches every Haiku id, and `claude-haiku-4-5` also matches a start+ * that asks for the `haiku` alias. `default` is not known, so nothing matches it. */+export function modelMatches(ruleModel: string, model: string | null): boolean {+ const rule = ruleModel.toLowerCase(), target = (model ?? 'default').toLowerCase()+ return target !== 'default' && (target.includes(rule) || (FAMILY.exec(target)?.[0] === target && FAMILY.exec(rule)?.[0] === target))+}++/** Why a hard rule rules the target out, or null when none does. */+export function broken(rules: SwarmRule[] | undefined, target: RunTarget): string | null {+ for (const { rule, text } of rules ?? []) {+ const engineName = ENGINE[target.engine] ?? target.engine+ const out = rule.kind === 'forbidModel' ? (!rule.engine || rule.engine === target.engine)+ && modelMatches(rule.model, target.model) && `${engineName} ${target.model}`+ : rule.kind === 'machines' ? !rule.machineIds.includes(target.machineId) && 'this machine'+ : rule.kind === 'minEffort' ? (!rule.engine || rule.engine === target.engine) && rank(target.effort) < rank(rule.effort)+ && `${engineName} at ${target.effort && rank(target.effort) >= 0 ? `${target.effort} effort` : 'an unnamed effort'}`+ : false+ if (out) return `The owner's rule "${text}" rules out ${out}.`+ }+ return null+}++export const startTarget = (request: { machineId: string; engine: string; model?: string; effort?: string }): RunTarget =>+ ({ machineId: request.machineId, engine: request.engine, model: request.model ?? null, effort: request.effort ?? null })++/** A started agent was launched with `--effort`, which Claude never reports back, so its configuration may say `auto`; its+ * start record still holds what it was launched with (manual run 2026-10-19). */+export function agentTarget(state: SuperTabState, worker: Agent): RunTarget {+ const reported = worker.configuration.effort+ const launched = state.starts?.find(s => s.harnessId === worker.harnessId && s.request.machineId === worker.machineId)?.request.effort+ return { machineId: worker.machineId, engine: worker.configuration.engine, model: worker.configuration.model,+ effort: reported && reported !== 'auto' ? reported : launched ?? reported }+}diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex daef9afcb..2d8f36f29 100644--- a/backend/src/superTabs/store.ts+++ b/backend/src/superTabs/store.ts@@ -399,6 +399,10 @@ export class SuperTabStore {const reply = await tx.superTabMessage.findFirst({ where: { id: command.replyTo, tabId, conversationId: command.conversationId } })if (reply) context.reply = { id: reply.id, conversationId: reply.conversationId, author: reply.author as unknown as Author }}+ if ((command.type === 'rule.set' || command.type === 'rule.remove') && command.askedIn) {+ const asked = await tx.superTabMessage.findFirst({ where: { id: command.askedIn.messageId, tabId, conversationId: command.askedIn.conversationId } })+ if (asked) context.askedIn = { author: asked.author as unknown as Author, source: !!asked.source, createdAt: asked.createdAt.getTime() }+ }if (command.type === 'message.send' && actor.kind === 'agent') {const recent = await tx.superTabMessage.findMany({ where: { tabId, conversationId: command.conversationId },orderBy: { sequence: 'desc' }, take: PAIR_CHAIN_LIMIT, select: { author: true, recipientIds: true } })@@ -415,6 +419,9 @@ export class SuperTabStore {const decisionId = command.type === 'route.override' || command.type === 'route.modelResult' ? command.decisionId: command.type === 'work.assign' || command.type === 'agent.start' ? command.routeDecisionId : undefinedif (decisionId) context.routeDecision = await readDecision(tx, tabId, decisionId) ?? fail('NOT_FOUND', 'This routing decision is unavailable.', 404)+ // A dispatch reads its start's decision only to see whether a person chose this start by hand (rules.ts).+ const dispatched = command.type === 'agent.startDispatch' ? original.starts?.find(s => s.id === command.startId)?.routeDecisionId : undefined+ if (dispatched) context.routeDecision = await readDecision(tx, tabId, dispatched) ?? undefinedconst effects = applyCommand(original, actor, command, context)if (command.type === 'agent.add' || command.type === 'agent.started') {const target = agent(effects.state, effects.result.agentId as string)diff --git a/cli/src/superTabs/route.spec.ts b/cli/src/superTabs/route.spec.tsindex c1634ee95..3a4cec7e6 100644--- a/cli/src/superTabs/route.spec.ts+++ b/cli/src/superTabs/route.spec.ts@@ -1,7 +1,8 @@// cli/src/superTabs/route.spec.ts-import { createHash } from 'node:crypto'import { describe, expect, it } from 'vitest'-import { choose, contextSize, decide, floorFor, jevQuestion, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, scrub, type Assessment, type Commitment, type MemberFrame, type Policy, type Probe, type TaskFolder } from './route.js'+import { breaks, choose, decide, floorFor, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, type Assessment, type Commitment, type MemberFrame, type Policy, type Probe, type SwarmRule, type TaskFolder } from './route.js'++const object = (v: unknown) => v as Record<string, unknown>const policy: Policy = { version: 1, floor: { low: 1, medium: 2, high: 3 }, quotaReserve: 10, notes: 'Frontend prefers Claude.', models: [{ engine: 'claude', model: 'opus', effort: 'high', quality: 3, cost: 3, enabled: true },@@ -192,52 +193,28 @@ describe('strength, fit and effective cost', () => {})})-const base = { title: 'T', brief: '', checks: [] as string[], messages: [] as Array<{ from: string; text: string }> | null, folder: null as TaskFolder | null,- attempts: [] as Array<{ agent: string; outcome: string; result?: string }>, recent: [] as Array<{ title: string; via: string; outcome: string | null }> | null }const frame = (patch: Partial<MemberFrame> = {}): MemberFrame => ({ title: 'Fix auth', project: 'api', cwd: '/w/api', root: '/w/api', remote: 'github.com/acme/api', branch: 'feat/auth', updatedAt: 1_000_000 - 2 * 3_600_000, ...patch })const folder = (patch: Partial<TaskFolder> = {}): TaskFolder => ({ cwd: '/w/api', kind: 'git', name: 'api', root: '/w/api', remote: 'github.com/acme/api', ...patch })-describe('Jev context and verdict', () => {+describe('verdict and record', () => {const choice = () => { const r = choose([probe({ kind: 'member', agentId: 'a1', name: 'Multiply', activity: 'idle' }), probe({ machineName: 'mac' })], policy, a()); if ('error' in r) throw new Error('x'); return r }- it('builds at most four string keys within the hosted limits, with no email', () => {- const q = jevQuestion({ ...base, title: 'Build', brief: 'b'.repeat(5000), checks: ['Tests pass', 'Docs updated'], attempts: [{ agent: 'Builder', outcome: 'stopped' }] }, a(), policy, choice())- expect(Object.keys(q.state)).toEqual(['task', 'lead', 'policy', 'history'])- expect(Object.values(q.state).every(v => typeof v === 'string')).toBe(true)- expect(Object.values(q.state).join('').length).toBeLessThanOrEqual(17_000)- expect(q.state.task.length).toBeLessThan(5000)- expect(q.state.history).toContain('Builder: stopped')- expect(q.state.policy).toContain('Frontend prefers Claude.')- expect(Object.keys(q.questions.who.criteria)).toEqual(['c0', 'c1'])- expect(Object.values(q.questions.who.criteria).every(v => v.length <= 640)).toBe(true)- expect(q.questions.who.instructions.length).toBeLessThanOrEqual(1500)- expect(JSON.stringify(q)).not.toMatch(/@/)- })- it('takes a sure Jev pick, falls back to order when unsure or unavailable, and skips Jev for one candidate', () => {- const c = choice()- expect(decide(c, { choice: 'c1', probabilities: { c0: 0.2, c1: 0.8 } }, null)).toMatchObject({ via: 'jev', p: 0.8, pick: { id: 'c1' } })- expect(decide(c, { choice: 'c1', probabilities: { c0: 0.45, c1: 0.55 } }, null)).toMatchObject({ via: 'order', fallback: 'unsure', pick: { id: 'c0' }, why: expect.stringContaining('Jev unsure') })- expect(decide(c, undefined, 'BUSY')).toMatchObject({ via: 'order', fallback: 'unavailable', pick: { id: 'c0' }, why: expect.stringContaining('Jev unavailable') })- const one = choose([probe()], policy, a()); if ('error' in one) throw new Error('x')- expect(decide(one, undefined, null)).toMatchObject({ via: 'only', p: null })- })- it('broken Jev answers fall back to order', () => {- const c = choice()- expect(decide(c, { choice: 'c9', probabilities: { c0: 0.1, c9: 0.9 } }, null).via).toBe('order')- expect(decide(c, { choice: 'c1', probabilities: { c1: 0.9 } }, null).via).toBe('order')+ it('takes the first in the fixed order, and says when it was the only candidate', () => {+ expect(decide(choice())).toEqual({ pick: choice().shown[0], via: 'order', p: null, why: "First by the owner's rules and the policy order." })+ expect(decide(ok(choose([probe()], policy, a())))).toMatchObject({ via: 'only', p: null })})it('produces a record the backend schema accepts', () => {- const c = choice(), v = decide(c, { choice: 'c1', probabilities: { c0: 0.2, c1: 0.8 } }, null)+ const c = choice(), v = decide(c)const v1 = { assessment: { difficulty: 'medium', risk: 'low', why: 'API change.' },candidates: c.shown.map(s => ({ id: s.id, kind: s.kind, ...(s.agentId ? { agentId: s.agentId } : {}), machineId: s.machineId,engine: s.engine, model: s.model, effort: s.effort, quality: s.quality, cost: s.cost, title: s.title, label: s.label })),- excluded: [], floor: 2, notes: true, pick: 'c1', via: 'jev', p: 0.8, belowFloor: false, why: v.why }+ excluded: [], floor: 2, notes: true, pick: 'c0', via: 'order', p: null, belowFloor: false, why: v.why }expect(recordOf(c, v, a(), policy)).toEqual({ ...v1, assessment: { ...v1.assessment, size: 'medium' },candidates: v1.candidates.map(x => ({ ...x, fit: { status: 'unknown', coverage: null, effectiveCost: 2, expiring: 0, spend: { '5-hour': 30, weekly: 4 }, account: 'm1:claude' } })) })// For a backend from before sizes and fit.- expect(recordOf(c, v, a(), policy, undefined, true)).toEqual(v1)- // The policy order says which fallback decided; the other routes carry none.- const order = decide(c, undefined, 'BUSY')- expect(recordOf(c, order, a(), policy)).toMatchObject({ via: 'order', fallback: 'unavailable', why: order.why })+ expect(recordOf(c, v, a(), policy, true)).toEqual(v1)+ // The task's kind is not recorded, so the record's schema is unchanged.+ expect(recordOf(c, v, a({ kind: 'ui' }), policy)).toMatchObject({ assessment: { difficulty: 'medium', risk: 'low', why: 'API change.', size: 'medium' } })+ expect(object(recordOf(c, v, a({ kind: 'ui' }), policy).assessment)).not.toHaveProperty('kind')})})@@ -288,7 +265,7 @@ describe('edges', () => {expect(ok(choose([probe({ known: false, quota: unknownQuota })], policy, a())).shown[0].label).toContain('quota unknown')expect(ok(choose([probe({ quota: { known: true, leftPercent: 50, resetsAt: 0 } })], policy, a())).shown[0].label).toContain('resets in 1m')})- it('tells Jev how far away a reset is, because Jev does not know the time', () => {+ it('tells how far away a reset is, which reads the same whenever the log is opened', () => {const label = (resetsAt: number) => ok(choose([probe({ quota: { known: true, leftPercent: 50, resetsAt } })], policy, a(), 1_000_000)).shown[0].labelexpect(label(1_000_000 + 30 * 60_000)).toContain('quota 50% left, resets in 30m')expect(label(1_000_000 + 2 * 3_600_000)).toContain('resets in 2h')@@ -310,22 +287,6 @@ describe('edges', () => {expect(ok(choose([probe({ machineName: 'b' }), probe({ kind: 'member', agentId: 'a1', name: 'M' })], policy, a())).shown[0].kind).toBe('member')expect(ok(choose([probe({ kind: 'member', agentId: 'a1', name: 'M' }), probe({ machineName: 'b' })], policy, a())).shown[0].kind).toBe('member')})- it('tells Jev about tools, devices, an empty history, a missed floor and absent notes', () => {- const r = ok(choose([probe({ quality: 1 })], policy, a({ difficulty: 'high' })))- const q = jevQuestion({ ...base, title: 'T' }, a({ needs: { tools: ['git', 'node'], devices: ['cam'] } }), { ...policy, notes: '' }, r)- expect(q.state.lead).toContain('tools: git, node; devices: cam')- expect(q.state.policy).toContain('no candidate meets it')- expect(q.state.policy).toContain('Notes: none')- expect(q.state.history).toContain('No earlier attempts in this group.')- })- it('ends the Lead\'s reason with exactly one period, whatever the Lead ended it with', () => {- const r = ok(choose([probe({ quality: 3 })], policy, a()))- const lead = (why: string) => jevQuestion({ ...base, title: 'T' }, a({ why }), policy, r).state.lead- for (const why of ['Add one function', 'Add one function.', 'Add one function...']) expect(lead(why)).toContain('Why: Add one function. Task folder')- // A question or an exclamation is already a full stop.- expect(lead('Is it safe?')).toContain('Why: Is it safe? Task folder')- expect(lead('Do it now!')).toContain('Why: Do it now! Task folder')- })it('keeps a floor-meeting candidate even when it is low on quota or unknown', () => {const low = { known: true, leftPercent: 5, resetsAt: null }const r = ok(choose([probe({ quality: 1 }), probe({ quality: 3, machineName: 'mac', quota: low })], policy, a({ difficulty: 'high' })))@@ -339,7 +300,7 @@ describe('edges', () => {const long = 'x'.repeat(900)const r = ok(choose([probe({ kind: 'member', agentId: 'a_1-B', name: long, machineId: 'm-1_X' }), probe({ machineName: long })], policy, a()))const rec = recordOf({ ...r, excluded: Array.from({ length: 250 }, () => ({ title: long.slice(0, 160), reason: long })) },- decide(r, undefined, long), a(), { ...policy, notes: '' }) as { candidates: Array<Record<string, string>>; excluded: Array<{ reason: string }>; why: string; notes: boolean; p: number | null }+ decide(r), a(), { ...policy, notes: '' }) as { candidates: Array<Record<string, string>>; excluded: Array<{ reason: string }>; why: string; notes: boolean; p: number | null }expect(rec.candidates.every(c => /^c\d{1,2}$/.test(c.id) && c.title.length <= 160 && c.label.length <= 640 && /^[A-Za-z0-9_-]+$/.test(c.machineId))).toBe(true)expect(rec.excluded).toHaveLength(200)expect(rec.excluded.every(e => e.reason.length <= 500)).toBe(true)@@ -349,67 +310,12 @@ describe('edges', () => {})})-// Every fake secret is built here from pieces, so that no source line holds a whole key shape (GitHub push protection-// refuses those, even in a test).-const fake = (...parts: string[]) => parts.join('')-const AWS_ID = fake('AKIA', 'IOSFODNN7', 'EXAMPLE')-const AWS_SECRET = fake('wJalrXUtnFEMI/', 'K7MDENG/', 'bPxRfiCYEXAMPLEKEY')-// Random-looking 40-character base64 keys that keep a `/` inside (a leading one is not a key shape): the same twelve every run.-const slashedKeys = Array.from({ length: 400 }, (_, i) => createHash('sha256').update(String(i)).digest('base64').slice(0, 40))- .filter(key => key.slice(1, -1).includes('/')).slice(0, 12)--describe('scrub', () => {- it('replaces emails and each token shape, and leaves ordinary text alone', () => {- const text = [- 'mail [email protected] now', fake('key sk-', 'proj-', 'abcdefghijklmnop1234'), fake('gh ghp', '_abcdefghijklmnopqrstuvwx'), fake('slack xox', 'b-1234567890-abcdef'),- fake('aws AKIA', 'ABCDEFGHIJKLMNOP'), fake('auth Bear', 'er eyJ', 'hbGciOi.abc-def_ghi'), `hex ${'a1'.repeat(16)}`, `b64 ${'Zm9vYmFy0'.repeat(5)}==`, 'plain words and /usr/bin/node stay',- ].join('\n')- const out = scrub(text)- expect(out).not.toMatch(/@|sk-|ghp_|xoxb|AKIA|Bearer|a1a1a1|Zm9v/)- expect(out.match(/\[email\]/g)).toHaveLength(1)- expect(out.match(/\[secret\]/g)!.length).toBeGreaterThanOrEqual(7)- expect(out).toContain('plain words and /usr/bin/node stay')- expect(scrub('commit abc1234 at v1.2.3')).toBe('commit abc1234 at v1.2.3')- })- it('keeps paths, URLs, branch names, UUIDs and file names, and still catches real keys', () => {- for (const keep of [- 'docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md', 'https://github.com/autonomous-ai/openharness/pull/1424',- '0xken15/feat/super-tab-jev-context-v2', '/Users/nqhieu84/harnesses/worktrees/openharness/routing-v1', '3f2b8c1e-9a4d-4e57-8b1a-6c0d2e9f7a31',- 'feature/Add-OAuth2-Flow-For-Mobile-Clients-2026-10',- ]) expect(scrub(`see ${keep} now`)).toBe(`see ${keep} now`)- // A key is judged on its own, even inside a path or after an equals sign.- for (const key of [- fake('sk-', 'proj-', 'AbCdEf0123456789abcdefGH'), fake('ghp', '_AbCdEf0123456789abcdefghijklmn'), AWS_ID, fake('xox', 'b-123456789012-abcdefABCDEF'),- fake('eyJ', 'hbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.', 'eyJ', 'zdWIiOiIxMjM0NTY3ODkwIn0.', 'dBjftJeZ4CVPmB92K27', 'uhbUJU1p1rwW1gFWFOEjXk'),- fake('wJalrXUtnFEMIK7MDENG', 'bPxRfiCYEXAMPLEKEY12='),- fake('Zm9vYmFyQmF6UXV4', 'MTIzNDU2Nzg5MEFiQ2RF', 'ZkdoSWpLbE1u'), fake('Ab3_dEf-9GhI1jKl_', 'MnO5pQr-StU7vWx_YzA2bCd4'), fake('e3b0c44298fc1c14', '9afbf4c8996fb924', '27ae41e4'),- ]) {- expect(scrub(`k ${key} z`)).toBe('k [secret] z')- expect(scrub(`path/${key}/end`)).toContain('[secret]')- }- // Standard base64 keys keep their `/`: AWS's documented example secret key, and a fixed sample of random 40-character keys.- expect(scrub(`secret ${AWS_SECRET} here`)).toBe('secret [secret] here')- expect(scrub(`AWS_SECRET_ACCESS_KEY=${AWS_SECRET}`)).toBe('AWS_SECRET_ACCESS_KEY=[secret]')- expect(slashedKeys).toHaveLength(12)- for (const key of slashedKeys) {- expect(scrub(`k ${key} z`)).toBe('k [secret] z')- expect(scrub(`"${key}"`)).toBe('"[secret]"')- }- // A relative path of plain words is not a key, even with a digit and a capital in it.- expect(scrub('see src/superTabs/RouteCommand/specHelpers/Util2/fixtures now')).toBe('see src/superTabs/RouteCommand/specHelpers/Util2/fixtures now')- // Bearer needs a token-like value, and its spelling.- expect(scrub('Bearer is a word, and bearer token too')).toBe('Bearer is a word, and bearer token too')- expect(scrub(fake('Authorization: Bear', 'er abcdefghij', '0123456789klmn'))).toBe('Authorization: [secret]')- })-})--describe('the context Jev is given', () => {+describe('candidate labels', () => {const now = 1_000_000const members = (patch: Partial<Probe> = {}) => ok(choose([probe({ kind: 'member', agentId: 'a1', name: 'Multiply', activity: 'idle', frame: frame(), repo: 'same', earlier: [{ group: 'API', outcome: 'done' }], ...patch }),probe({ machineName: 'mac', load: { agents: 3, freeMemoryBytes: 6.5e9, hasFolder: true } }),], policy, a(), now))- const ask = (patch: Record<string, unknown> = {}, choice = members()) => jevQuestion({ ...base, ...patch }, a({ needs: { tools: [], devices: [], cwd: '/w/api' } }), policy, choice)it('tells what a member is doing, where, and whether it is the task\'s repository', () => {const label = members().shown.find(s => s.kind === 'member')!.label@@ -460,104 +366,6 @@ describe('the context Jev is given', () => {const label = ok(choose([probe({ quota })], policy, a(), now)).shown[0].labelexpect(label).toContain('quota 5-hour 40% left (resets in 2h), weekly 90% left (resets in 5 days), window 75% left')})- it('names the task folder and its repository in the Lead\'s assessment', () => {- expect(ask({ folder: folder() }).state.lead).toContain('Task folder: api (git repository api)')- expect(ask({ folder: folder({ cwd: '/w/notes', kind: 'none', name: null, root: null }) }).state.lead).toContain('Task folder: notes (not a git repository)')- expect(ask({ folder: folder({ kind: 'unknown', name: null }) }).state.lead).toContain('Task folder: api (repository unknown)')- expect(ask({ folder: folder({ cwd: '/', name: null }) }).state.lead).toContain('Task folder: / (git repository )')- expect(ask({ folder: folder({ kind: 'missing', name: null, root: null, remote: null }) }).state.lead).toContain('Task folder: api (not on the Lead\'s machine)')- expect(ask({ folder: null }).state.lead).toContain('Task folder: not stated')- expect(ask({ folder: folder() }).state.lead).not.toContain('/w/')- })- it('gives the last messages as a role-tagged transcript, newest last, and marks missing or empty ones', () => {- const messages = Array.from({ length: 4 }, (_, i) => ({ from: i % 2 ? 'Lead' : 'person', text: `m${i}` }))- expect(ask({ messages }).state.task).toContain('Recent messages:\nperson: m0\nLead: m1\nperson: m2\nLead: m3')- expect(ask({ messages: [] }).state.task).toContain('Recent messages: none')- expect(ask({ messages: null }).state.task).toContain('Recent messages: unknown')- expect(ask({ messages: [], noneInLatest: true }).state.task).toContain('Recent messages: none in the latest 100 messages')- expect(ask({ messages: [{ from: 'Multiply', text: 'x' }] }).state.task).toContain('Multiply: x')- })- it('tells the policy: the cost scale and why the floor is what it is', () => {- const policyText = (assessment: Assessment, p = policy) => { const c = ok(choose([probe({ quality: 3 })], p, assessment, now)); return jevQuestion(base, assessment, p, c).state.policy }- expect(policyText(a({ difficulty: 'high', risk: 'low' }))).toContain('Quality floor: 3 (difficulty high needs quality 3).')- expect(policyText(a({ difficulty: 'medium', risk: 'high' }))).toContain('Quality floor: 3 (difficulty medium needs quality 2, plus 1 for high risk).')- expect(policyText(a({ difficulty: 'high', risk: 'high' }))).toContain('Quality floor: 3 (difficulty high needs quality 3, plus 1 for high risk, at most 3).')- expect(policyText(a())).toContain('Cost is relative: cost 3 is about 3 times cost 1.')- })- it('lists all attempts in the group with their outcome and a cut result, and the last routing decisions', () => {- const q = ask({ attempts: [{ agent: 'Multiply', outcome: 'stopped', result: 'r'.repeat(300) }, { agent: 'New agent (claude opus)', outcome: 'done' }],- recent: [{ title: 'Multiply · Claude sonnet medium · remote-1', via: 'jev', outcome: 'stopped' }, { title: 'New agent · Codex', via: 'order', outcome: null }] })- expect(q.state.history).toContain(`- Multiply: stopped — ${'r'.repeat(199)}…`)- expect(q.state.history).toContain('- New agent (claude opus): done')- expect(q.state.history).toContain('- Multiply · Claude sonnet medium · remote-1 (jev): stopped')- expect(q.state.history).toContain('- New agent · Codex (order): open')- expect(ask({ recent: [{ title: 'Pick', outcome: 'done' }] }).state.history).toContain('- Pick: done')- expect(ask({ recent: null }).state.history).toContain('Recent routing in this Super Tab: unknown')- expect(ask({ recent: [] }).state.history).toContain('Recent routing in this Super Tab: none')- })- it('keeps the newest of too many messages and attempts, with a mark for what was dropped', () => {- const words = (i: number) => `msg${i} ${'lorem ipsum '.repeat(40)}`.slice(0, 500).padEnd(500, '.')- const messages = Array.from({ length: 10 }, (_, i) => ({ from: 'person', text: words(i) }))- const task = ask({ messages }).state.task- const part = task.slice(task.indexOf('Recent messages:'))- expect(part.length).toBeLessThanOrEqual('Recent messages:\n'.length + 3500)- expect(part).toContain('…\n')- expect(part.endsWith(words(9))).toBe(true)- expect(part).not.toContain('msg0')- const attempts = Array.from({ length: 60 }, (_, i) => ({ agent: `Agent${i}`, outcome: 'stopped', result: 'x'.repeat(200) }))- const history = ask({ attempts }).state.history- expect(history).toContain('Agent59')- expect(history).not.toContain('Agent0:')- expect(history).toMatch(/…/)- })- it('scrubs emails and secrets everywhere, so no @ or token reaches Jev', () => {- const dirty = fake('ping [email protected] with sk-', 'abcdefghijklmnopqrstu and Bear', 'er abcdef.ghijklmnop.qrstuvwxyz and ghp', '_abcdefghijklmnopqrstuvw')- const choice = ok(choose([probe({ kind: 'member', agentId: 'a1', name: 'Multiply', frame: frame({ title: dirty, branch: '[email protected]' }), repo: 'same', earlier: [{ group: dirty, outcome: 'done' }] }),- probe({ machineName: 'mac' })], policy, a(), now))- const q = jevQuestion({ ...base, title: dirty, brief: dirty, checks: [dirty], messages: [{ from: 'person', text: dirty }],- attempts: [{ agent: 'Multiply', outcome: 'stopped', result: dirty }], recent: [{ title: dirty, via: 'jev', outcome: null }] },- a({ why: dirty, needs: { tools: [], devices: [], cwd: '/w/[email protected]' } }), { ...policy, notes: dirty }, choice)- const all = JSON.stringify(q)- expect(all).not.toMatch(/@|sk-abc|ghp_|Bearer/)- expect(all).toContain('[email]')- expect(all).toContain('[secret]')- })- it('stays within every hosted limit and its own budget at the worst case', () => {- const long = (c: string, n: number) => c.repeat(n)- const probes = Array.from({ length: 12 }, (_, i) => probe({ kind: 'member', agentId: `a${i}`, name: long('N', 80), machineName: long('M', 80), model: long('o', 200), activity: 'idle',- frame: frame({ title: long('T', 300), project: long('P', 300), branch: long('Q', 300) }), repo: 'same',- earlier: Array.from({ length: 9 }, () => ({ group: long('G', 90), outcome: 'stopped' })),- quota: { known: true, leftPercent: 50, resetsAt: now + 1e9, windows: [{ name: '5-hour', leftPercent: 50, resetsAt: now + 3_600_000 }, { name: 'weekly', leftPercent: 70, resetsAt: now + 5 * 86_400_000 }] } }))- const choice = ok(choose(probes, { ...policy, notes: long('n', 3000) }, a(), now))- const q = jevQuestion({ title: long('t', 500), brief: long('k', 9000), checks: Array.from({ length: 30 }, () => long('q', 200)),- messages: Array.from({ length: 10 }, () => ({ from: long('X', 90), text: long('m', 2000) })), folder: folder({ cwd: `/${long('z', 300)}`, name: long('r', 300) }),- attempts: Array.from({ length: 40 }, () => ({ agent: long('Y', 90), outcome: 'stopped', result: long('x', 900) })),- recent: Array.from({ length: 5 }, () => ({ title: long('R', 200), via: 'jev', outcome: 'stopped' })) },- a({ why: long('w', 300), needs: { tools: Array.from({ length: 20 }, () => long('t', 80)), devices: Array.from({ length: 20 }, () => long('/z', 40)), cwd: `/${long('z', 300)}` } }),- { ...policy, notes: long('n', 3000) }, choice)- expect(Object.keys(q.state)).toEqual(['task', 'lead', 'policy', 'history'])- const limit = { task: 7000, lead: 1000, policy: 1000, history: 6000 } as const- for (const key of Object.keys(limit) as Array<keyof typeof limit>) {- expect(q.state[key].length).toBeLessThanOrEqual(limit[key])- // Whole messages and attempts are kept or dropped, so a part may end up to one line short of its budget.- expect(q.state[key].length).toBeGreaterThan(limit[key] - 700)- }- expect(Object.values(q.state).reduce((sum, v) => sum + v.length, 0)).toBeLessThanOrEqual(15_000)- const labels = Object.values(q.questions.who.criteria)- expect(labels).toHaveLength(12)- expect(labels.every(l => l.length <= 640)).toBe(true)- expect(labels.some(l => l.endsWith('…'))).toBe(true)- expect(q.questions.who.instructions.length).toBeLessThanOrEqual(1500)- expect(contextSize(q)).toBe(Object.values(q.state).reduce((sum, v) => sum + v.length, 0) + labels.reduce((sum, l) => sum + l.length, 0) + q.questions.who.instructions.length)- // The parts that matter stay: the end of the messages and the task's own budgets.- expect(q.state.task).toContain('Brief: ' + long('k', 100))- expect(q.state.task).toContain('Recent messages:')- })- it('records the size of the context and what was missing, only when given', () => {- const c = members(), v = decide(c, undefined, 'BUSY')- expect(recordOf(c, v, a(), policy, { chars: 5000, missing: ['messages'] })).toMatchObject({ context: { chars: 5000, missing: ['messages'] } })- expect(recordOf(c, v, a(), policy)).not.toHaveProperty('context')- })})describe('repoMatch', () => {@@ -585,3 +393,71 @@ describe('repoMatch', () => {expect(repoMatch(missing, frame({ remote: null, root: '/w/web', cwd: '/w/web' }), true)).toBe('different')})})++describe('the owner\'s rules', () => {+ const rule = (r: SwarmRule['rule'], text = 'Rule.'): SwarmRule => ({ rule: r, text })+ const titles = (r: ReturnType<typeof choose>) => ok(r).shown.map(s => s.title)+ const haiku = probe({ machineName: 'cheap', model: 'haiku', effort: 'auto', quality: 2, cost: 1 })+ const sonnet = probe({ machineName: 'mac' })+ it('leaves out a candidate that breaks a hard rule, with the owner\'s words as the reason', () => {+ const r = ok(choose([haiku, sonnet], policy, a(), NOW, [], [rule({ kind: 'forbidModel', model: 'HAIKU' }, 'No Haiku.')]))+ expect(r.shown.map(s => s.machineName)).toEqual(['mac'])+ expect(r.excluded).toEqual([{ title: 'New agent · Claude haiku auto · cheap', reason: 'Breaks the owner\'s rule: No Haiku.' }])+ // A full model id is caught too, a rule for another engine is not, and `default` is never matched.+ expect(breaks([rule({ kind: 'forbidModel', model: 'haiku' })], { machineId: 'm', engine: 'claude', model: 'claude-haiku-4-5', effort: 'high' })).toContain('Rule.')+ expect(breaks([rule({ kind: 'forbidModel', engine: 'codex', model: 'haiku' })], { machineId: 'm', engine: 'claude', model: 'haiku', effort: 'high' })).toBeNull()+ // `default` is not known, so nothing matches it; a rule naming a full id matches the alias a start asks for.+ expect(breaks([rule({ kind: 'forbidModel', model: 'def' })], { machineId: 'm', engine: 'codex', model: 'default', effort: 'high' })).toBeNull()+ expect(breaks([rule({ kind: 'forbidModel', model: 'claude-haiku-4-5' })], { machineId: 'm', engine: 'claude', model: 'haiku', effort: 'high' })).toContain('Rule.')+ expect(breaks([rule({ kind: 'forbidModel', model: 'claude-haiku-4-5' })], { machineId: 'm', engine: 'claude', model: 'sonnet', effort: 'high' })).toBeNull()+ })+ it('keeps agents to the owner\'s machines', () => {+ const r = choose([sonnet, probe({ machineId: 'm2', machineName: 'other' })], policy, a(), NOW, [], [rule({ kind: 'machines', machineIds: ['m2'] })])+ expect(titles(r)).toEqual(['New agent · Claude sonnet medium · other'])+ // When nobody is left, the Lead is told why each one was left out.+ expect(choose([sonnet], policy, a(), NOW, [], [rule({ kind: 'machines', machineIds: ['m9'] }, 'Only m9.')]))+ .toEqual({ error: 'NO_CANDIDATE', excluded: [{ title: 'New agent · Claude sonnet medium · mac', reason: 'Breaks the owner\'s rule: Only m9.' }] })+ })+ it('holds a minimum effort, and lifts a new agent whose effort the engine chooses to that minimum', () => {+ const codex = probe({ machineName: 'box', engine: 'codex', model: 'default', effort: 'default', quality: 3, cost: 2 })+ const member = probe({ kind: 'member', agentId: 'a1', name: 'Low', effort: 'low' })+ const unknown = probe({ kind: 'member', agentId: 'a2', name: 'Auto', effort: 'auto' })+ const r = ok(choose([codex, member, unknown, sonnet], policy, a(), NOW, [], [rule({ kind: 'minEffort', effort: 'high' }, 'High effort.')]))+ expect(r.shown.map(s => s.title)).toEqual(['New agent · Codex default high · box'])+ expect(r.excluded.map(e => e.title)).toEqual(['Low · Claude sonnet low · remote-1', 'Auto · Claude sonnet auto · remote-1', 'New agent · Claude sonnet medium · mac'])+ // The highest minimum that applies to the engine wins; one for another engine is ignored.+ const two = ok(choose([codex], policy, a(), NOW, [], [rule({ kind: 'minEffort', effort: 'medium' }), rule({ kind: 'minEffort', engine: 'codex', effort: 'xhigh' }), rule({ kind: 'minEffort', engine: 'claude', effort: 'max' })]))+ expect(two.shown[0].effort).toBe('xhigh')+ // A lifted row that equals another on the same machine is shown once.+ const high = probe({ machineName: 'box', engine: 'codex', model: 'default', effort: 'high', quality: 3, cost: 2 })+ expect(ok(choose([codex, high], policy, a(), NOW, [], [rule({ kind: 'minEffort', effort: 'high' })])).shown.map(s => s.title)).toEqual(['New agent · Codex default high · box'])+ const auto = probe({ machineName: 'box', engine: 'codex', model: 'default', effort: 'auto', quality: 3, cost: 2 })+ expect(ok(choose([codex, auto], policy, a(), NOW, [], [rule({ kind: 'minEffort', effort: 'high' })])).shown).toHaveLength(1)+ // Without a minimum, nothing is lifted.+ expect(ok(choose([codex], policy, a(), NOW, [], [rule({ kind: 'minEffort', engine: 'claude', effort: 'high' })])).shown[0].effort).toBe('default')+ })+ it('ranks by the preferred engine for the task\'s kind, before cost, without changing who is shown', () => {+ const codex = probe({ machineName: 'box', engine: 'codex', model: 'default', effort: 'default', quality: 2, cost: 3 })+ const plain = ok(choose([codex, sonnet], policy, a(), NOW))+ expect(plain.shown.map(s => s.engine)).toEqual(['claude', 'codex'])+ const rules = [rule({ kind: 'preferEngine', taskKind: 'ui', engine: 'codex' }), rule({ kind: 'preferEngine', taskKind: null, engine: 'claude' })]+ expect(ok(choose([codex, sonnet], policy, a({ kind: 'ui' }), NOW, [], rules)).shown.map(s => s.engine)).toEqual(['codex', 'claude'])+ // Another kind falls to the rule for every task.+ expect(ok(choose([sonnet, codex], policy, a({ kind: 'docs' }), NOW, [], rules)).shown.map(s => s.engine)).toEqual(['claude', 'codex'])+ expect(ok(choose([codex, sonnet], policy, a(), NOW, [], [rules[0]])).shown).toHaveLength(plain.shown.length)+ })+ it('puts idle members first, then the least busy machine, when the owner prefers idle agents', () => {+ const member = probe({ kind: 'member', agentId: 'a1', name: 'Idle', cost: 3, quality: 2 })+ const busy = probe({ machineName: 'busy', cost: 1, load: { agents: 5, freeMemoryBytes: null, hasFolder: null } })+ const quiet = probe({ machineName: 'quiet', cost: 2, load: { agents: 1, freeMemoryBytes: null, hasFolder: null } })+ const unread = probe({ machineName: 'unread', cost: 1 })+ expect(titles(choose([busy, member, quiet, unread], policy, a(), NOW))[0]).toBe('New agent · Claude sonnet medium · busy')+ expect(titles(choose([busy, member, quiet, unread], policy, a(), NOW, [], [rule({ kind: 'preferIdle' })])).map(t => t.split(' · ')[0] === 'Idle' ? 'Idle' : t.split(' · ')[2]))+ .toEqual(['Idle', 'quiet', 'busy', 'unread'])+ })+ it('parses the task\'s kind', () => {+ expect(parseAssessment({ difficulty: 'low', risk: 'low', why: 'x', kind: 'ui' })).toMatchObject({ kind: 'ui' })+ expect(parseAssessment({ difficulty: 'low', risk: 'low', why: 'x', kind: 'UI work' })).toContain('kind')+ expect(parseAssessment({ difficulty: 'low', risk: 'low', why: 'x' })).not.toHaveProperty('kind')+ })+})diff --git a/cli/src/superTabs/route.ts b/cli/src/superTabs/route.tsindex db6ec4c12..a519079aa 100644--- a/cli/src/superTabs/route.ts+++ b/cli/src/superTabs/route.ts@@ -1,16 +1,23 @@/** Super Tab routing v1, the pure half (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md), ordered by* strength, quota fit and effective cost since phase 1 (docs/plans/2026-10-21-swarm-routing-phase1.md).- * The system removes what cannot run the task, Jev chooses among the rest with the full context, and a- * fixed policy order decides when Jev is unsure or unavailable. Jev's acceptance rule is the voice- * router's (`jevPick`), tuned on the owner's desk on 2026-10-10. */-import { basename, isAbsolute } from 'node:path'-import type { JevChoice, JevChoiceAnswer } from '../lib/jev/jevClient.js'+ * The system removes what cannot run the task or breaks one of the owner's hard rules, and the first in a fixed order+ * (the owner's soft rules, then the policy order) is the pick (docs/plans/2026-10-22-swarm-rules-routing.md). Jev chose+ * among the candidates until 2026-10-22, when the Lead overrode it about half the time because it did not know the rules. */+import { isAbsolute } from 'node:path'import { claudeAliasForModel } from '../engines/claude/runtimeProfile.js'-import { jevPick } from '../lib/routeDecide.js'export type Level = 'low' | 'medium' | 'high'export type Size = 'small' | 'medium' | 'large'-export interface Assessment { difficulty: Level; risk: Level; size: Size; why: string; needs: { tools: string[]; devices: string[]; cwd?: string } }+/** `kind` is a word the Lead may give (`ui`, `docs`) for the owner's preferred-engine rules; a review group's is `review`. */+export interface Assessment { difficulty: Level; risk: Level; size: Size; why: string; kind?: string; needs: { tools: string[]; devices: string[]; cwd?: string } }+/** The owner's rules as the backend keeps them (backend/src/superTabs/rules.ts); only the rule and its words are read here. */+export type Rule =+ | { kind: 'forbidModel'; engine?: string; model: string }+ | { kind: 'machines'; machineIds: string[] }+ | { kind: 'minEffort'; engine?: string; effort: string }+ | { kind: 'preferEngine'; taskKind: string | null; engine: string }+ | { kind: 'preferIdle' }+export interface SwarmRule { rule: Rule; text: string }export interface PolicyModel { engine: 'claude' | 'codex'; model: string; effort: string; quality: number; cost: number; enabled: boolean }export interface Policy { version: 1; models: PolicyModel[]; floor: Record<Level, number>; quotaReserve: number; notes: string }/** One usage window, named by the reader (`5-hour`, `weekly`); `leftPercent` is what remains of it. */@@ -44,7 +51,7 @@ export interface Commitment { account: string; spend: Partial<Record<Window, numexport interface Shown extends Probe { id: string; title: string; label: string; fit: Fit }/** `short` is set when no candidate is expected to cover the task, to tell the Lead. */export interface Choice { shown: Shown[]; excluded: Array<{ title: string; reason: string }>; floor: number; belowFloor: boolean; short?: string }-export interface Verdict { pick: Shown; via: 'jev' | 'order' | 'only'; p: number | null; why: string; fallback?: 'unsure' | 'unavailable' }+export interface Verdict { pick: Shown; via: 'order' | 'only'; p: null; why: string }const LEVELS: Level[] = ['low', 'medium', 'high']/** Run time and spend per window by task size, for a policy row of cost 2 (owner's table, 2026-10-21); not in the policy yet. */@@ -58,37 +65,40 @@ const MAX_SHOWN = 12const ENGINE = { claude: 'Claude', codex: 'Codex' } as constconst cut = (text: string, max: number) => text.length <= max ? text : `${text.slice(0, max - 1)}…`-/** Jev is a hosted model, so nothing that identifies a person or opens an account goes to it. Emails and the common- * key shapes are replaced before any text is cut, so a cut never leaves half a key behind. A long hex run is taken- * for a key even when it is a commit id: a lost id costs less than a leaked key. */-const SECRETS = [- /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}/g, /\bgh[pousr]_[A-Za-z0-9]{20,}/g, /\bxox[a-z]-[A-Za-z0-9-]{10,}/g, /\bAKIA[0-9A-Z]{16}\b/g,- /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}/g, /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]*/g, /\b[0-9a-fA-F]{32,}\b/g,-]-/** A base64 or base64url key, as opposed to a path, a URL or a branch name that is just as long: it has all three of- * upper case, lower case and digits, and no words joined by hyphens. `/` and `.` end a run, so a long path is judged by- * its segments and a JWT by its parts. */-const keyLike = (run: string) => /[A-Z]/.test(run) && /[a-z]/.test(run) && /\d/.test(run) && !/[A-Z]?[a-z]{3,}-[A-Z]?[a-z]{3,}/.test(run)-/** Standard base64 uses `/`, which also separates path pieces. A whole token (not a path from the root, no dot) is a key- * when it looks like one and none of its pieces is a plain word, which a relative path would have. */-const plainWord = (piece: string) => /^[A-Z]?[a-z]{5,}$/.test(piece)-const slashedKey = (token: string) => /^[A-Za-z0-9+/]{32,}={0,2}$/.test(token) && token.includes('/') && keyLike(token) && !token.split('/').some(plainWord)-export function scrub(text: string): string {- const plain = SECRETS.reduce((t, pattern) => t.replace(pattern, '[secret]'), text.replace(/[^\s@<>()"',;]+@[^\s@<>()"',;]+/g, '[email]'))- return plain.replace(/[^\s"'=:,;()<>]+/g, token => slashedKey(token) ? '[secret]' : token)- .replace(/[A-Za-z0-9+_=-]{32,}/g, run => keyLike(run) ? '[secret]' : run)+const EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max']+/** `default` and `auto` say nothing about the effort, so they never meet a minimum. */+const rank = (effort: string) => EFFORTS.indexOf(effort)+const applies = (rule: { engine?: string }, engine: string) => !rule.engine || rule.engine === engine+const FAMILY = /haiku|sonnet|opus|fable/+/** The backend's `modelMatches`: `haiku` matches every Haiku id, `claude-haiku-4-5` also the `haiku` alias, and nothing+ * matches `default`, which is not known. */+function modelMatches(ruleModel: string, model: string): boolean {+ const rule = ruleModel.toLowerCase(), target = model.toLowerCase()+ return target !== 'default' && (target.includes(rule) || (FAMILY.exec(target)?.[0] === target && FAMILY.exec(rule)?.[0] === target))}-const fit = (text: string, max: number) => cut(scrub(text), max)-/** The newest lines that fit, for logs where the end matters most; a leading mark says older ones were dropped. */-function newest(lines: string[], max: number): string {- if (lines.join('\n').length <= max) return lines.join('\n')- let kept = ''- for (let i = lines.length - 1; i >= 0; i--) {- const next = kept ? `${lines[i]}\n${kept}` : lines[i]- if (next.length > max - 2) break- kept = next- }- return `…\n${kept}`++/** The backend's check (backend/src/superTabs/rules.ts `broken`), so a pick shown here is never refused when it is+ * started, assigned or recorded. */+export function breaks(rules: SwarmRule[], p: { machineId: string; engine: string; model: string; effort: string }): string | null {+ const out = rules.find(({ rule }) => rule.kind === 'forbidModel' ? applies(rule, p.engine) && modelMatches(rule.model, p.model)+ : rule.kind === 'machines' ? !rule.machineIds.includes(p.machineId)+ : rule.kind === 'minEffort' && applies(rule, p.engine) && rank(p.effort) < rank(rule.effort))+ return out ? `Breaks the owner's rule: ${out.text}` : null+}+/** A new agent whose policy row leaves the effort to the engine starts at the owner's minimum instead (Lead, 2026-10-22), so+ * a minimum does not rule out the Codex `default` row. */+function lifted(rules: SwarmRule[], p: Probe): Probe {+ if (p.kind !== 'new' || rank(p.effort) >= 0) return p+ const least = Math.max(-1, ...rules.flatMap(({ rule }) => rule.kind === 'minEffort' && applies(rule, p.engine) ? [rank(rule.effort)] : []))+ return least < 0 ? p : { ...p, effort: EFFORTS[least] }+}+/** The soft rules for this task: the engine preferred for its kind (a rule for the kind before one for every task), and+ * whether idle agents come first. */+interface Soft { engine: string | null; idle: boolean }+function softOf(rules: SwarmRule[], kind: string | undefined): Soft {+ const prefer = rules.flatMap(({ rule }) => rule.kind === 'preferEngine' ? [rule] : [])+ const engine = (prefer.find(r => kind && r.taskKind === kind) ?? prefer.find(r => r.taskKind === null))?.engine ?? null+ return { engine, idle: rules.some(r => r.rule.kind === 'preferIdle') }}export function parseAssessment(value: unknown): Assessment | string {@@ -104,7 +114,9 @@ export function parseAssessment(value: unknown): Assessment | string {const list = (x: unknown) => Array.isArray(x) && x.every(i => typeof i === 'string') ? x as string[] : []const cwd = needs.cwdif (cwd !== undefined && (typeof cwd !== 'string' || !isAbsolute(cwd))) return 'needs.cwd must be an absolute path.'- return { difficulty: v.difficulty as Level, risk: v.risk as Level, size: size as Size, why, needs: { tools: list(needs.tools), devices: list(needs.devices), ...(cwd ? { cwd } : {}) } }+ if (v.kind !== undefined && (typeof v.kind !== 'string' || !/^[a-z][a-z0-9-]{0,39}$/.test(v.kind))) return 'Set kind to one lowercase word, such as ui or docs.'+ return { difficulty: v.difficulty as Level, risk: v.risk as Level, size: size as Size, why, ...(v.kind ? { kind: v.kind as string } : {}),+ needs: { tools: list(needs.tools), devices: list(needs.devices), ...(cwd ? { cwd } : {}) } }}export const floorFor = (policy: Policy, a: Assessment): number => Math.min(3, policy.floor[a.difficulty] + (a.risk === 'high' ? 1 : 0))@@ -151,7 +163,7 @@ export function rateFor(policy: Policy, engine: string, model: string | null, ef}const titleOf = (p: Probe) => cut(`${p.kind === 'member' ? p.name ?? 'Member' : 'New agent'} · ${ENGINE[p.engine]} ${p.model} ${p.effort} · ${p.machineName}`, 160)-/** Jev does not know the time, so a reset or a last activity is told as how far away it is. */+/** A reset or a last activity is told as how far away it is, which reads the same whenever the log is opened. */function span(ms: number): string {if (ms < 3_600_000) return `${Math.max(1, Math.round(ms / 60_000))}m`// Under ten hours, half an hour decides whether a task fits before the reset, so it keeps its minutes (4h30).@@ -177,8 +189,8 @@ function memberText(p: Probe, now: number): string[] {const f = p.frameconst repo = p.repo ? [p.repo === 'unknown' ? 'repo unknown' : `${p.repo} repo`] : []if (!f) return [...repo, 'activity unknown']- const where = [f.project && fit(f.project, 40), f.branch && `branch ${fit(f.branch, 40)}`].filter(Boolean).join(', ')- return [...repo, ...(f.title ? [`on "${fit(f.title, 80)}"`] : []), ...(where ? [f.project ? `in ${where}` : where] : []),+ const where = [f.project && cut(f.project, 40), f.branch && `branch ${cut(f.branch, 40)}`].filter(Boolean).join(', ')+ return [...repo, ...(f.title ? [`on "${cut(f.title, 80)}"`] : []), ...(where ? [f.project ? `in ${where}` : where] : []),f.updatedAt === null ? 'last active unknown' : `last active ${span(Math.max(0, now - f.updatedAt))} ago`]}function machineText(load: MachineLoad): string[] {@@ -186,15 +198,15 @@ function machineText(load: MachineLoad): string[] {load.agents === null ? 'agents running unknown' : `${load.agents} ${load.agents === 1 ? 'agent' : 'agents'} running`,load.freeMemoryBytes === null ? 'free memory unknown' : `${bytes(load.freeMemoryBytes)} memory free`]}-/** The most telling parts come first and the least last, because the hosted limit cuts the end. */-const labelOf = (p: Probe & Sized, now: number) => fit([- p.kind === 'member' ? `Member ${fit(p.name ?? '', 40)}`.trim() : 'New agent', `${ENGINE[p.engine]} ${p.model} ${p.effort}`, `quality ${p.quality}, cost ${p.cost}`,- p.text, fit(p.machineName, 40), p.activity, ...(p.kind === 'member' ? memberText(p, now) : p.load ? machineText(p.load) : []),- ...(p.earlier?.length ? [`earlier here: ${p.earlier.slice(0, 3).map(e => `${fit(e.group, 40)} ${e.outcome}`).join('; ')}`] : []), quotaText(p.quota, now),+/** The most telling parts come first and the least last, because the log's limit cuts the end. */+const labelOf = (p: Probe & Sized, now: number) => cut([+ p.kind === 'member' ? `Member ${cut(p.name ?? '', 40)}`.trim() : 'New agent', `${ENGINE[p.engine]} ${p.model} ${p.effort}`, `quality ${p.quality}, cost ${p.cost}`,+ p.text, cut(p.machineName, 40), p.activity, ...(p.kind === 'member' ? memberText(p, now) : p.load ? machineText(p.load) : []),+ ...(p.earlier?.length ? [`earlier here: ${p.earlier.slice(0, 3).map(e => `${cut(e.group, 40)} ${e.outcome}`).join('; ')}`] : []), quotaText(p.quota, now),].join(' · '), 640)interface Measured { name: Window; usable: number; needed: number; resetsIn: number | null }-/** A probe's fit, its tightest window (the one that runs out first) and the sentence Jev reads. */+/** A probe's fit, its tightest window (the one that runs out first) and the sentence the log keeps. */interface Sized { fit: Fit; tight: Measured | null; text: string }const pct = (n: number) => `${Math.round(n)}%`const round = (n: number) => Math.round(n * 100) / 100@@ -232,20 +244,29 @@ const WAY = ['right away', 'about a quarter of the way in', 'about halfway', 'abconst runsOut = (w: Measured) => `The ${w.name} window is expected to run out ${WAY[Math.round(Math.max(0, w.usable / w.needed) * 4)]}${w.resetsIn === null ? '' : `; resets in ${span(w.resetsIn)}`}.`const UNREAD = 'Its quota could not be read in full, and another candidate\'s quota fits this task.'-/** The fixed policy order: cheaper in effect, stronger, more room on the tightest window, an idle member in the task's- * repository before a new agent, then by title. */-function compare(x: Probe & Sized, y: Probe & Sized): number {+/** The fixed order: the owner's preferred engine, an idle member before a new agent and a less busy machine first when the+ * owner prefers idle agents; then the policy order: cheaper in effect, stronger, more room on the tightest window, an idle+ * member in the task's repository before a new agent, then by title. */+function compare(x: Probe & Sized, y: Probe & Sized, soft: Soft): number {const placed = (p: Probe) => p.kind === 'member' && (p.repo ?? 'same') === 'same' ? 0 : 1- return x.fit.effectiveCost - y.fit.effectiveCost+ const preferred = (p: Probe) => soft.engine && p.engine !== soft.engine ? 1 : 0+ const fresh = (p: Probe) => soft.idle && p.kind === 'new' ? 1 : 0+ const busy = (p: Probe) => soft.idle && p.kind === 'new' ? p.load?.agents ?? 1000 : 0+ return preferred(x) - preferred(y) || fresh(x) - fresh(y) || busy(x) - busy(y)+ || x.fit.effectiveCost - y.fit.effectiveCost|| y.quality - x.quality|| (y.tight?.usable ?? -Infinity) - (x.tight?.usable ?? -Infinity)|| placed(x) - placed(y)|| titleOf(x).localeCompare(titleOf(y))}-export function choose(probes: Probe[], policy: Policy, a: Assessment, now: number = Date.now(), open: Commitment[] = []): Choice | { error: 'NO_CANDIDATE'; excluded: Array<{ title: string; reason: string }> } {- const excluded = probes.filter(p => p.refusals.length).map(p => ({ title: titleOf(p), reason: p.refusals.join(' ') }))- const viable = probes.filter(p => !p.refusals.length)+export function choose(probes: Probe[], policy: Policy, a: Assessment, now: number = Date.now(), open: Commitment[] = [], rules: SwarmRule[] = []): Choice | { error: 'NO_CANDIDATE'; excluded: Array<{ title: string; reason: string }> } {+ // A lifted row can equal another row on the same machine (Codex `default` lifted to high beside Codex high); one is kept.+ const raised = probes.map(p => lifted(rules, p)), key = (p: Probe) => `${p.kind}\0${p.machineId}\0${p.engine}\0${p.model}\0${p.effort}`+ const ruled = raised.filter((p, i) => p === probes[i] || !raised.some((q, j) => j !== i && key(q) === key(p) && (q === probes[j] || j < i)))+ .map(p => { const why = breaks(rules, p); return why ? { ...p, refusals: [...p.refusals, why] } : p })+ const excluded = ruled.filter(p => p.refusals.length).map(p => ({ title: titleOf(p), reason: p.refusals.join(' ') }))+ const viable = ruled.filter(p => !p.refusals.length)if (!viable.length) return { error: 'NO_CANDIDATE', excluded }const floor = floorFor(policy, a)const meeting = viable.filter(p => p.quality >= floor)@@ -257,87 +278,28 @@ export function choose(probes: Probe[], policy: Policy, a: Assessment, now: numbconst status = (['fits', 'unknown', 'short'] as const).find(s => sized.some(p => p.fit.status === s))!excluded.push(...sized.filter(p => p.fit.status !== status).map(p => ({ title: titleOf(p), reason: p.fit.status === 'unknown' ? UNREAD : runsOut(p.tight!) })))// When every candidate is short, the one expected to get furthest goes first.- const set = sized.filter(p => p.fit.status === status).sort((x, y) => status === 'short' ? y.fit.coverage! - x.fit.coverage! || compare(x, y) : compare(x, y))+ const soft = softOf(rules, a.kind)+ const set = sized.filter(p => p.fit.status === status).sort((x, y) => status === 'short' ? y.fit.coverage! - x.fit.coverage! || compare(x, y, soft) : compare(x, y, soft))const shown = set.slice(0, MAX_SHOWN).map(({ tight, text, ...p }, i) => ({ ...p, id: `c${i}`, title: titleOf(p), label: labelOf({ ...p, tight, text }, now) }))const first = set[0].tight!return { shown, excluded, floor, belowFloor: !meeting.length, ...(status === 'short'? { short: `No candidate is expected to cover this task; its ${first.name} quota is expected to run out partway${first.resetsIn === null ? '' : ` and resets in ${span(first.resetsIn)}`}.` } : {}) }}-const INSTRUCTIONS = cut([- 'Choose the candidate that should do this task.',- 'The Lead assessed its difficulty and risk; every candidate shown meets the quality floor unless the policy says none does.',- 'The list is already ordered by strength for the difficulty, fit and effective cost. Keep the first unless the task, its history or the policy notes give a clear reason otherwise.',- 'A member marked "same repo" already has the task\'s code open, which saves a start; prefer it over an equal candidate.',- 'A candidate that already failed or stopped on this task is a worse choice. A member that is idle in the Super Tab saves a start.',- 'Unknown means the information could not be read; it is not a bad sign.',-].join(' '), 1500)--const folderText = (f: TaskFolder | null) => !f ? 'not stated'- : `${fit(basename(f.cwd) || f.cwd, 80)} (${f.kind === 'git' ? `git repository ${fit(f.name ?? '', 80)}` : f.kind === 'none' ? 'not a git repository'- : f.kind === 'missing' ? 'not on the Lead\'s machine' : 'repository unknown'})`--export interface JevInput {- title: string; brief: string; checks: string[]- /** The last messages as `person`, `Lead` or an agent's name; null when they could not be read. */- messages: Array<{ from: string; text: string }> | null- /** True when the latest page of the group held only log rows (routing notes, transcripts), so "none" would mislead. */- noneInLatest?: boolean- folder: TaskFolder | null; attempts: Attempt[]- /** The Super Tab's latest routing decisions; null when they could not be read. */- recent: RecentRoute[] | null-}--/** The hosted route allows 4 keys and 17,000 characters of state. Each key has its own budget so that one long- * brief cannot push out the messages or the history. */-export function jevQuestion(input: JevInput, a: Assessment, policy: Policy, choice: Choice) {- const messages = input.messages === null ? 'Recent messages: unknown' : input.messages.length- ? `Recent messages:\n${newest(input.messages.map(m => `${fit(m.from, 40)}: ${fit(m.text, 600)}`), 3500)}` : `Recent messages: none${input.noneInLatest ? ' in the latest 100 messages' : ''}`- const base = policy.floor[a.difficulty]- const risk = a.risk === 'high' ? `, plus 1 for high risk${base + 1 > 3 ? ', at most 3' : ''}` : ''- const floor = `Quality floor: ${choice.floor} (difficulty ${a.difficulty} needs quality ${base}${risk})${choice.belowFloor ? '; no candidate meets it, so all are shown' : ''}. `- + 'Cost is relative: cost 3 is about 3 times cost 1. Notes: '- const attempts = input.attempts.length- ? `Attempts in this group:\n${newest(input.attempts.map(t => `- ${fit(t.agent, 60)}: ${fit(t.outcome, 20)}${t.result ? ` — ${fit(t.result, 200)}` : ''}`), 4700)}` : 'No earlier attempts in this group.'- const recent = input.recent === null ? 'Recent routing in this Super Tab: unknown' : input.recent.length- ? `Recent routing in this Super Tab:\n${input.recent.map(r => `- ${fit(r.title, 200)}${r.via ? ` (${fit(r.via, 20)})` : ''}: ${r.outcome ? fit(r.outcome, 20) : 'open'}`).join('\n')}` : 'Recent routing in this Super Tab: none'- const state = {- task: fit(`Group: ${fit(input.title, 160)}\nBrief: ${fit(input.brief, 2000)}\nChecks:\n${fit(input.checks.map(c => `- ${c}`).join('\n'), 1000)}\n${messages}`, 7000),- lead: fit(`Difficulty: ${a.difficulty}. Risk: ${a.risk}. Why: ${/[!?]$/.test(a.why) ? a.why : `${a.why.replace(/\.+$/, '')}.`} Task folder: ${folderText(input.folder)}. Needs tools: ${a.needs.tools.join(', ') || 'none'}; devices: ${a.needs.devices.join(', ') || 'none'}.`, 1000),- policy: fit(`${floor}${policy.notes || 'none'}`, 1000),- history: fit(`${attempts}\n\n${recent}`, 6000),- }- const questions: Record<string, JevChoice> = {- who: { type: 'choice', instructions: INSTRUCTIONS, criteria: Object.fromEntries(choice.shown.map(s => [s.id, s.label])) },- }- return { state, questions }-}--/** How many characters Jev was given in all, for the decision log. */-export const contextSize = (q: ReturnType<typeof jevQuestion>): number =>- Object.values(q.state).reduce((sum, v) => sum + v.length, 0) + Object.values(q.questions.who.criteria).reduce((sum, v) => sum + v.length, 0) + q.questions.who.instructions.length--export function decide(choice: Choice, answer: JevChoiceAnswer | undefined, unavailable: string | null): Verdict {- const first = choice.shown[0]- if (choice.shown.length === 1) return { pick: first, via: 'only', p: null, why: 'Only candidate that can run this task.' }- const picked = unavailable ? undefined : jevPick(answer, choice.shown.map(s => s.id), true)- if (picked) {- const pick = choice.shown.find(s => s.id === picked)!- return { pick, via: 'jev', p: answer!.probabilities[picked], why: `Jev chose ${pick.title}.` }- }- const reason = unavailable ? `Jev unavailable (${unavailable})` : 'Jev unsure'- return { pick: first, via: 'order', p: null, why: `${reason}; first in the policy order.`, fallback: unavailable ? 'unavailable' : 'unsure' }+export function decide(choice: Choice): Verdict {+ const pick = choice.shown[0]+ return choice.shown.length === 1 ? { pick, via: 'only', p: null, why: 'Only candidate that can run this task.' }+ : { pick, via: 'order', p: null, why: "First by the owner's rules and the policy order." }}/** `v1` leaves out size and fit, for a backend from before phase 1, whose strict schema refuses them. */-export function recordOf(choice: Choice, verdict: Verdict, a: Assessment, policy: Policy, context?: { chars: number; missing: string[] }, v1 = false): Record<string, unknown> {+export function recordOf(choice: Choice, verdict: Verdict, a: Assessment, policy: Policy, v1 = false): Record<string, unknown> {return {assessment: { difficulty: a.difficulty, risk: a.risk, why: a.why, ...(v1 ? {} : { size: a.size }) },candidates: choice.shown.map(s => ({ id: s.id, kind: s.kind, ...(s.agentId ? { agentId: s.agentId } : {}), machineId: s.machineId,engine: s.engine, model: s.model, effort: s.effort, quality: s.quality, cost: s.cost, title: s.title, label: s.label, ...(v1 ? {} : { fit: s.fit }) })),excluded: choice.excluded.slice(0, 200).map(e => ({ title: e.title, reason: cut(e.reason, 500) })),floor: choice.floor, notes: policy.notes.length > 0,- pick: verdict.pick.id, via: verdict.via, ...(verdict.fallback ? { fallback: verdict.fallback } : {}), p: verdict.p, belowFloor: choice.belowFloor, why: cut(verdict.why, 300),- ...(context ? { context } : {}),+ pick: verdict.pick.id, via: verdict.via, p: verdict.p, belowFloor: choice.belowFloor, why: cut(verdict.why, 300),}}diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.tsindex 7d952f031..f8fafc7f2 100644--- a/cli/src/superTabs/routeCommand.spec.ts+++ b/cli/src/superTabs/routeCommand.spec.ts@@ -40,16 +40,10 @@ function daemon(machineId: string, options: { agents?: string[]; frames?: Record}}type Answer = Record<string, unknown>-function scoped(answers: { jev?: Answer; record?: Answer; tab?: unknown; context?: Answer; history?: Answer; historyHangs?: boolean; jevThrows?: boolean; recordThrows?: boolean } = {}) {+function scoped(answers: { record?: Answer; tab?: unknown; context?: Answer; history?: Answer; historyHangs?: boolean; recordThrows?: boolean } = {}) {return vi.fn(async (payload: Record<string, any>): Promise<Record<string, unknown>> => {if (payload.action === 'routeContext') return answers.context ?? { ok: true, value: { agentId: 'lead', tab: answers.tab ?? tab(), policy: { policy, warnings: ['w'] }, machines: [{ machineId: 'm1', name: 'remote-1' }, { machineId: 'm2', name: 'mac' }] } }- if (payload.action === 'routeHistory') return answers.historyHangs ? new Promise(() => {}) : answers.history ?? { ok: true, value: { messages: [], decisions: [], attempts: [] } }- if (payload.action === 'routeJev') {- if (answers.jevThrows) throw new Error('socket closed')- // Jev answers over every candidate it was shown, as the real client's answers do.- const ids = Object.keys(payload.questions.who.criteria)- return answers.jev ?? { ok: true, value: { answers: { who: { choice: 'c1', probabilities: Object.fromEntries(ids.map(id => [id, id === 'c1' ? 0.9 : 0.1 / (ids.length - 1)])) } } } }- }+ if (payload.action === 'routeHistory') return answers.historyHangs ? new Promise(() => {}) : answers.history ?? { ok: true, value: { decisions: [], attempts: [] } }if (payload.action === 'command') {if (answers.recordThrows) throw new Error('socket closed')return answers.record ?? { ok: true, value: { result: { routeDecisionId: 'd1' } } }@@ -61,13 +55,16 @@ const where = { port: 1, dataDir: '/nonexistent', machineId: 'm1' }const input = { tabId: 'tab', conversationId: 'g1', assessment: { difficulty: 'medium', risk: 'low', why: 'Endpoint.' } }const opener = (make: (id: string) => ReturnType<typeof daemon> = id => daemon(id, { agents: id === 'm1' ? ['h1'] : [] })) => vi.fn(async (_w: unknown, id = '') => make(id)) as unknown as typeof openDaemon & Mockconst recorded = (s: ReturnType<typeof scoped>) => s.mock.calls.find(c => c[0].action === 'command')![0]-const jevCall = (s: ReturnType<typeof scoped>) => s.mock.calls.find(c => c[0].action === 'routeJev')![0]+/** Each candidate's line, as the route log keeps it. */+const labels = (s: ReturnType<typeof scoped>) => (recorded(s).command.decision.candidates as Array<{ label: string }>).map(c => c.label)describe('routeTask', () => {- it('collects members and new agents, asks Jev, records and returns the pick', async () => {+ it('collects members and new agents, records and returns the first in the order, 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: 'jev', pick: { id: 'c1' }, warnings: ['w'] })+ expect(result).toMatchObject({ ok: true, routeDecisionId: 'd1', via: 'order', p: null, pick: { id: 'c0' }, warnings: ['w'] })+ expect(s.mock.calls.map(c => c[0].action)).toEqual(['routeContext', 'routeHistory', 'command'])+ expect(recorded(s).command.decision).not.toHaveProperty('context')const record = recorded(s)expect(record).toMatchObject({ operationId: 'route-op', command: { type: 'route.record', conversationId: 'g1' } })// The idle Lead is not a candidate (neither the group's nor the tab's); the idle member Multiply is.@@ -84,11 +81,25 @@ describe('routeTask', () => {expect(offered.length).toBeGreaterThan(0)expect(offered.some(c => /^(Lead|Multiply) ·/.test(c))).toBe(false)})+ it('does not offer a member that is already working on a task', async () => {+ const s = scoped({ tab: tab({ id: 'x', agentId: 'a1', status: 'working' }) })+ await routeTask(input, s, where as never, opener(id => daemon(id, { agents: ['h1'] })))+ expect((recorded(s).command.decision.candidates as Array<{ title: string }>).some(c => c.title.startsWith('Multiply'))).toBe(false)+ })+ it('leaves out what breaks the owner\'s rules in the tab, and ignores a rule it cannot read', async () => {+ const ruled = tab(); (ruled.state as Record<string, unknown>).rules = [{ id: 'r1', rule: { kind: 'forbidModel', model: 'sonnet' }, text: 'No Sonnet.' }, { id: 'r2', text: 7 }]+ const s = scoped({ tab: ruled })+ const result = await routeTask(input, s, where as never, opener(), () => 'op')+ expect(result).toMatchObject({ ok: true, pick: { model: 'opus' }, belowFloor: false })+ const decision = recorded(s).command.decision+ expect(decision.candidates.every((c: { model: string }) => c.model === 'opus')).toBe(true)+ expect(decision.excluded).toEqual(expect.arrayContaining([{ title: 'Multiply · Claude sonnet medium · remote-1', reason: 'Breaks the owner\'s rule: No Sonnet.' }]))+ })it('offers a Reviewer only for a review group, and starts a new one as a Reviewer', async () => {const offered = async (reviewer: boolean, reviewGroup: boolean) => {const t = tab(); t.state.agents = agents.map(a => a.id === 'a1' && reviewer ? { ...a, role: 'reviewer' } : a)if (reviewGroup) (t.state.conversations[1] as Record<string, unknown>).reviewOf = 'g0'- const s = scoped({ tab: t, jev: { ok: true, value: { unavailable: 'BUSY' } } })+ const s = scoped({ tab: t })const result = await routeTask(input, s, where as never, opener(), () => 'op')const titles = (recorded(s).command.decision.candidates as Array<{ title: string }>).map(c => c.title)return { member: titles.some(c => c.startsWith('Multiply')), next: String(result.next) }@@ -101,11 +112,11 @@ describe('routeTask', () => {expect((await offered(false, false)).next).not.toContain('"role"')})it('tells the Lead how to assign a member or start a new agent with the decision', async () => {- const member = await routeTask(input, scoped({ jev: { ok: true, value: { unavailable: 'BUSY' } } }), where as never, opener(), () => 'op')+ const member = await routeTask(input, scoped(), where as never, opener(), () => 'op')// Cheapest first: the member on sonnet.expect(member).toMatchObject({ pick: { kind: 'member', agentId: 'a1' } })expect(member.next).toContain('"type":"work.assign","conversationId":"g1","agentId":"a1","routeDecisionId":"d1"')- const fresh = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high' } }, scoped({ jev: { ok: true, value: { unavailable: 'BUSY' } } }), where as never, opener(), () => 'op')+ const fresh = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high' } }, scoped(), where as never, opener(), () => 'op')expect(fresh).toMatchObject({ pick: { kind: 'new', engine: 'claude', model: 'opus', effort: 'high' } })expect(fresh.next).toContain('"engine":"claude","model":"opus","effort":"high","routeDecisionId":"d1"')// Without a branch the agent starts from the default one, and the hint says how to choose another.@@ -203,7 +214,7 @@ describe('routeTask', () => {})it('names a member that has no name, model or effort of its own, and leaves the decision blank when it is unrecorded', async () => {const plain = tab(); plain.state.agents = [{ id: 'a1', machineId: 'm1', harnessId: 'h1', configuration: { engine: 'claude' } }, agents[1]] as never- const options = { tab: plain, record: { error: 'BACKEND_UNAVAILABLE' }, jev: { ok: true, value: { unavailable: 'BUSY' } } }+ const options = { tab: plain, record: { error: 'BACKEND_UNAVAILABLE' } }const easy = await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'low' } }, scoped(options), where as never, opener())expect(easy).toMatchObject({ unrecorded: true, pick: { kind: 'member', title: 'Member · Claude default default · remote-1' } })expect(easy.next).not.toContain('routeDecisionId')@@ -217,13 +228,6 @@ describe('routeTask', () => {expect(await routeTask(input, s, where as never, open as never)).toMatchObject({ error: 'LEAD_REQUIRED' })expect(open).not.toHaveBeenCalled()})- it('returns a Jev-stage refusal as the result instead of falling back to the policy order', async () => {- for (const error of ['RATE_LIMITED', 'LEAD_REQUIRED']) {- const s = scoped({ jev: { error, detail: 'no', status: 429 } })- expect(await routeTask(input, s, where as never, opener())).toMatchObject({ error })- expect(s.mock.calls.some(c => c[0].action === 'command')).toBe(false)- }- })it('returns a record refusal as an error, and only a transport failure as unrecorded', async () => {expect(await routeTask(input, scoped({ record: { error: 'RATE_LIMITED', detail: 'slow down', status: 429 } }), where as never, opener())).toMatchObject({ error: 'RATE_LIMITED' })@@ -253,7 +257,7 @@ describe('routeTask', () => {})it('prefers a member whose capacity is known over one on a machine that cannot be read', async () => {const two = tab(); two.state.agents = [...agents, { id: 'a2', name: 'Collab', machineId: 'theirs', harnessId: 'h2', configuration: { engine: 'claude', model: 'sonnet', effort: 'medium' } }] as never- const s = scoped({ tab: two, jev: { ok: true, value: { unavailable: 'BUSY' } } })+ const s = scoped({ tab: two })const open = vi.fn(async (_w: unknown, id: string) => id === 'theirs' ? Promise.reject(new Error('not yours')) : daemon(id, { agents: id === 'm1' ? ['h1'] : [] })) as never// theirs is not in the account's list, m1 is; the unknown collaborator member is shown only as a fallback.const result = await routeTask(input, s, where as never, open)@@ -281,7 +285,7 @@ describe('routeTask', () => {{ id: 'a3', name: 'Sonnet hand', machineId: 'm1', harnessId: 'h3', configuration: { engine: 'claude', model: 'claude-sonnet-4-5[1m]', effort: 'medium' } },{ id: 'a4', name: 'Codex hand', machineId: 'm1', harnessId: 'h4', configuration: { engine: 'codex', model: 'gpt-5.5', effort: 'high' } },agents[1]] as never- const s = scoped({ tab: working, jev: { ok: true, value: { unavailable: 'BUSY' } } })+ const s = scoped({ tab: working })const open = opener(id => daemon(id, { agents: id === 'm1' ? ['h1', 'h3', 'h4'] : [], usage: { providers: [] }, engines: [{ engine: 'claude', installed: true, signedIn: true }, { engine: 'codex', installed: true, signedIn: true }] }))await routeTask(input, s, where as never, open)const rated = Object.fromEntries((recorded(s).command.decision.candidates as Array<{ title: string; quality: number; cost: number }>)@@ -311,29 +315,19 @@ describe('routeTask', () => {expect(v1.command.decision.assessment).not.toHaveProperty('size')expect(v1.command.decision.candidates.some((c: object) => 'fit' in c)).toBe(false)})- it('falls back to the policy order when Jev is unavailable, and still routes when recording fails', async () => {- const result = await routeTask(input, scoped({ jev: { ok: true, value: { unavailable: 'BUSY' } }, record: { error: 'BACKEND_UNAVAILABLE' } }), where as never, opener())+ it('still routes when recording fails or the connection is lost', async () => {+ const result = await routeTask(input, scoped({ record: { error: 'BACKEND_UNAVAILABLE' } }), where as never, opener())expect(result).toMatchObject({ ok: true, via: 'order', unrecorded: true })expect(result).not.toHaveProperty('routeDecisionId')- })- it('treats a failed Jev answer or a lost connection as Jev unavailable and still routes', async () => {- const failed = await routeTask(input, scoped({ jev: { error: 'AGENT_UNAVAILABLE' } }), where as never, opener())- expect(failed).toMatchObject({ ok: true, via: 'order' })- expect(failed.why).toContain('UNAVAILABLE')- const lost = await routeTask(input, scoped({ jevThrows: true, recordThrows: true }), where as never, opener())+ const lost = await routeTask(input, scoped({ recordThrows: true }), where as never, opener())expect(lost).toMatchObject({ ok: true, via: 'order', unrecorded: true })- const noAnswer = await routeTask(input, scoped({ jev: { ok: true, value: { answers: {} } } }), where as never, opener())- expect(noAnswer).toMatchObject({ ok: true, via: 'order' })- const s = scoped(); await routeTask(input, s, where as never, opener())- expect(jevCall(s).conversationId).toBe('g1')})- it('does not ask Jev when only one candidate can run the task', async () => {+ it('says when the pick was the only candidate that can run the task', async () => {const s = scoped()// Only the member's machine answers, and its engine is not installed for a new agent.const open = vi.fn(async (_w: unknown, id: string) => id === 'm1'? daemon(id, { agents: ['h1'], engines: [{ engine: 'claude', installed: false }] }) as never : Promise.reject(new Error('gone')))expect(await routeTask(input, s, where as never, open as never)).toMatchObject({ ok: true, via: 'only', pick: { agentId: 'a1' } })- expect(s.mock.calls.filter(c => c[0].action === 'routeJev')).toHaveLength(0)})it('refuses an invalid assessment, an unknown group and a failed context read', async () => {const open = vi.fn()@@ -363,19 +357,6 @@ describe('routeTask', () => {await routeTask(input, t, where as never, opener(id => daemon(id, { listFails: true })))expect(recorded(t).command.decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({ reason: 'Its terminal is not running.' })]))})- it('gives the history of a group whose last attempt ended', async () => {- for (const [assignment, line] of [- [{ id: 'x', agentId: 'a1', status: 'stopped', result: 'Tests failed.' }, 'Multiply: stopped — Tests failed.'],- [{ id: 'x', agentId: 'gone', status: 'done' }, 'An agent: done'],- ] as const) {- const s = scoped({ tab: tab(assignment) })- await routeTask(input, s, where as never, opener())- expect(jevCall(s).state.history).toContain(`- ${line}`)- }- const s = scoped({ tab: tab({ id: 'x', agentId: 'a1', status: 'working' }) })- await routeTask(input, s, where as never, opener(id => daemon(id, { agents: ['h1'] })))- expect(jevCall(s).state.history).toContain('No earlier attempts in this group.')- })it('keeps a group without brief or checks routable', async () => {const odd = tab(); const group = odd.state.conversations[1] as Record<string, unknown>delete group.brief; group.title = undefined; group.checks = [{}]@@ -416,7 +397,7 @@ describe('routeTask', () => {})})-describe('the context routeTask gives Jev', () => {+describe('what the route log says about each candidate', () => {const git = (patch: Record<string, unknown> = {}) => ({ kind: 'git', name: 'api', cwd: '/w/api', root: '/w/api', remote: 'github.com/acme/api', branch: 'main', ...patch })/** The Lead's machine, as the folder reader sees it: the folder is there (unless said otherwise) and the SCM describes it. */const describeGit = (found: unknown = git(), isDirectory = true) => ({ describe: vi.fn(async () => found) as unknown as typeof describeScmProject & Mock, isDirectory: vi.fn(async () => isDirectory) })@@ -428,26 +409,20 @@ describe('the context routeTask gives Jev', () => {const world = (extra: Record<string, unknown> = {}, assignment: unknown = null) => {const { tab: given, ...past } = extrareturn { context: { ok: true, value: { agentId: 'lead', tab: given ?? tab(assignment), policy: { policy, warnings: [] }, machines: [{ machineId: 'm1', name: 'remote-1' }, { machineId: 'm2', name: 'mac' }] } },- history: { ok: true, value: { messages: [{ from: 'person', text: 'Please add the endpoint.' }, { from: 'Lead', text: 'On it.' }], decisions: [], attempts: [], ...past } } }+ history: { ok: true, value: { decisions: [], attempts: [], ...past } } }}- const labels = (s: ReturnType<typeof scoped>) => Object.values(jevCall(s).questions.who.criteria as Record<string, string>)const memberLabel = (s: ReturnType<typeof scoped>) => labels(s).find(l => l.startsWith('Member Multiply'))!const newLabel = (s: ReturnType<typeof scoped>) => labels(s).find(l => l.startsWith('New agent'))!- it('reads the messages, the task folder, the member frames and the machines, and gives Jev what each says', async () => {+ it('reads the task folder, the member frames and the machines, and labels each candidate with what they say', async () => {const s = scoped(world())const make = (id: string) => daemon(id, { agents: id === 'm1' ? ['h1', 'x', 'y'] : ['z'], frames: { h1: frame() } })const describeRepo = describeGit()await routeTask(withCwd, s, where as never, opener(make), () => 'op', describeRepo)expect(describeRepo.describe).toHaveBeenCalledWith('/w/api')expect(describeRepo.isDirectory).toHaveBeenCalledWith('/w/api')- expect(jevCall(s).state.task).toContain('Recent messages:\nperson: Please add the endpoint.\nLead: On it.')- expect(jevCall(s).state.lead).toContain('Task folder: api (git repository api)')expect(memberLabel(s)).toContain('same repo · on "Fix auth" · in api, branch feat/auth · last active 2h ago')expect(labels(s).some(l => /^New agent.*remote-1.*has the task folder · 3 agents running · 7\.0 GB memory free/.test(l))).toBe(true)- expect(recorded(s).command.decision.context).toEqual({ chars: expect.any(Number), missing: [] })- expect(recorded(s).command.decision.context.chars).toBeGreaterThan(1000)- expect(recorded(s).command.decision.context.chars).toBeLessThan(17_000 + 31 * 640)})it('marks a member in another repository, and one it cannot compare', async () => {const other = frame({ project: git({ name: 'web', remote: 'github.com/acme/web', root: '/w/web', cwd: '/w/web' }) })@@ -460,7 +435,6 @@ describe('the context routeTask gives Jev', () => {const u = scoped(world())await routeTask(input, u, where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], frames: { h1: frame() } })), () => 'op')expect(memberLabel(u)).not.toMatch(/repo/)- expect(u.mock.calls.find(c => c[0].action === 'command')![0].command.decision.context.missing).toEqual([])})it('compares a member on another machine by remote only, and uses the branch the frame\'s project reports', async () => {const two = tab(); two.state.agents = [{ ...agents[0], machineId: 'm2' }, agents[1]] as never@@ -475,20 +449,14 @@ describe('the context routeTask gives Jev', () => {await routeTask(withCwd, s, where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], frames: { h1: { title: 5, updatedAt: 'later', project: null } } })), () => 'op', describeGit({ kind: 'none', cwd: '/w/api', root: null, remote: null, name: 'api', branch: null }))expect(memberLabel(s)).toMatch(/repo unknown · last active unknown/)expect(memberLabel(s)).not.toMatch(/on "|branch/)- expect(jevCall(s).state.lead).toContain('Task folder: api (not a git repository)')})- it('tells Jev what the group and the Super Tab have tried: ended attempts from the state and the log, and the last five decisions', async () => {+ it('labels a member with its earlier work in this Super Tab, from the state and the log', async () => {const decision = (id: string, conversationId: string, patch: Record<string, unknown> = {}) => ({ id, conversationId, title: `Pick ${id}`, via: 'jev', outcome: 'stopped', assignmentId: `as-${id}`,createdAt: '2026-10-19T10:00:00Z', final: { kind: 'new', engine: 'claude', model: 'opus' }, ...patch })const decisions = [{ ...decision('d7', 'g1', { outcome: null, assignmentId: null, final: null }), via: undefined }, decision('d6', 'g1', { outcome: 'done', assignmentId: 'x', final: { kind: 'member', agentId: 'a1' } }), decision('d5', 'g1'),decision('d4', 'other', { final: { kind: 'member', agentId: 'a1' }, outcome: 'done' }), decision('d3', 'g1', { final: null }), decision('d2', 'lead'), decision('d1', 'g1', { outcome: 'superseded' }), decision('d0', 'g1', { final: { kind: 'member', agentId: 'gone' } })]const s = scoped(world({ decisions }, { id: 'x', agentId: 'a1', status: 'done', result: 'Shipped.' }))await routeTask(input, s, where as never, opener())- const history = jevCall(s).state.history as string- // Oldest first: the log's attempt by an agent the tab no longer has, its stopped new-agent attempt, then the member's finished one with the result its assignment holds.- expect(history).toMatch(/Attempts in this group:\n- An agent: stopped\n- New agent \(claude opus\): stopped\n- Multiply: done — Shipped\./)- expect(history).toContain('Recent routing in this Super Tab:\n- Pick d7: open\n- Pick d6 (jev): done\n- Pick d5 (jev): stopped\n- Pick d4 (jev): done\n- Pick d3 (jev): stopped')- expect(history).not.toContain('Pick d2')// 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')})@@ -513,52 +481,33 @@ describe('the context routeTask gives Jev', () => {await routeTask(input, s, where as never, opener())expect(memberLabel(s)).toContain('Claude opus high')})- it('keeps a stopped attempt in the history and in the member\'s earlier work after the group was defined again', async () => {+ it('keeps a stopped attempt in the member\'s earlier work after the group was defined again', async () => {// `work.define` took the stopped assignment out of the state and no decision of the log names it (a person assigned it).// A row without an id names no assignment and is left out.const attempts = [{ agentId: 'a1', status: 'done' }, { id: 'as-2', agentId: 'a1', status: 'done', result: 'Shipped.' }, { id: 'as-1', agentId: 'a1', status: 'stopped', result: 'Tests failed.' }]const s = scoped(world({ attempts }))await routeTask(input, s, where as never, opener())- expect(jevCall(s).state.history).toContain('Attempts in this group:\n- Multiply: stopped — Tests failed.\n- Multiply: done — Shipped.')expect(memberLabel(s)).toContain('earlier here: API done; API stopped')})- it('orders the group\'s attempts oldest first, a person\'s assignment before a routed one, and keeps the newest for the member', async () => {+ it('orders the member\'s attempts oldest first, a person\'s assignment before a routed one', async () => {// as-1 was assigned by a person (no decision); as-2 was routed. The log alone would list as-2 first.const decision = { id: 'd2', conversationId: 'g1', title: 'Pick', via: 'jev', outcome: 'done', assignmentId: 'as-2', createdAt: '2026-10-19T11:00:00Z', final: { kind: 'member', agentId: 'a1' } }const attempts = [{ id: 'as-2', agentId: 'a1', status: 'done', result: 'Second.', createdAt: '2026-10-19T11:00:00Z' }, { id: 'as-1', agentId: 'a1', status: 'stopped', result: 'First.', createdAt: '2026-10-19T10:00:00Z' }]const s = scoped(world({ decisions: [decision], attempts }, { id: 'as-3', agentId: 'a1', status: 'stopped', result: 'Third.' }))await routeTask(input, s, where as never, opener())- expect(jevCall(s).state.history).toContain('Attempts in this group:\n- Multiply: stopped — First.\n- Multiply: done — Second.\n- Multiply: stopped — Third.')expect(memberLabel(s)).toContain('earlier here: API stopped; API done; API stopped')// Without the attempts read the log's order stays.const old = scoped(world({ decisions: [decision], attempts: undefined, attemptsUnreadable: true }, { id: 'as-3', agentId: 'a1', status: 'stopped', result: 'Third.' }))await routeTask(input, old, where as never, opener())- expect(jevCall(old).state.history).toContain('Attempts in this group:\n- Multiply: done\n- Multiply: stopped — Third.')+ expect(memberLabel(old)).toContain('earlier here: API stopped; API done')})it('lists an attempt once when the log and the attempts both know it', async () => {const decision = { id: 'd5', conversationId: 'g1', title: 'Pick', via: 'jev', outcome: 'stopped', assignmentId: 'as-1', createdAt: '2026-10-19T10:00:00Z', final: { kind: 'new', engine: 'claude', model: 'opus' } }const s = scoped(world({ decisions: [decision], attempts: [{ id: 'as-1', agentId: 'gone', status: 'stopped', result: 'Out of memory.' }] }, { id: 'as-2', agentId: 'a1', status: 'done', result: 'Shipped.' }))await routeTask(input, s, where as never, opener())- const history = jevCall(s).state.history as string- // The log names the started agent; the attempt gives the result.- expect(history).toContain('Attempts in this group:\n- New agent (claude opus): stopped — Out of memory.\n- Multiply: done — Shipped.')- expect(history.match(/Out of memory/g)).toHaveLength(1)expect(memberLabel(s)).toContain('earlier here: API done')})- it('cuts an attempt\'s result to 200 characters and scrubs it', async () => {- const result = `Key sk-${'a1'.repeat(20)} sent to [email protected]. ${'x'.repeat(400)}`- const s = scoped(world({ attempts: [{ id: 'as-1', agentId: 'a1', status: 'stopped', result }] }))- await routeTask(input, s, where as never, opener())- const line = (jevCall(s).state.history as string).split('\n').find(l => l.startsWith('- Multiply: stopped'))!- expect(line).toContain('[secret] sent to [email]')- expect(line).not.toMatch(/@|sk-/)- expect(line.length).toBeLessThanOrEqual('- Multiply: stopped — '.length + 200)- })- it('keeps the log\'s name for a started agent whose assignment names an agent the tab no longer has', async () => {- const decision = { id: 'd5', conversationId: 'g1', title: 'Pick', via: 'jev', outcome: 'stopped', assignmentId: 'as-5', createdAt: '2026-10-19T10:00:00Z', final: { kind: 'new', engine: 'claude', model: 'opus' } }- const s = scoped(world({ decisions: [decision] }, { id: 'as-5', agentId: 'gone', status: 'stopped', result: 'Out of memory.' }))- await routeTask(input, s, where as never, opener())- expect(jevCall(s).state.history).toContain('- New agent (claude opus): stopped — Out of memory.')+ it('finds nothing to admit on a machine that reports no capacity', async () => {// A machine that reports no capacity measured nothing, so nothing there can be admitted; the route says so.expect(await routeTask(withCwd, scoped(world()), where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], capacity: {} })), () => 'op', describeGit())).toMatchObject({ error: 'NO_CANDIDATE' })})@@ -571,41 +520,29 @@ describe('the context routeTask gives Jev', () => {expect(memberLabel(s)).toContain('earlier here: Group 4 stopped; Group 3 stopped; Group 2 stopped')expect(memberLabel(s)).not.toContain('Group 1')})- it('still routes when a source cannot be read, and lists each one in the decision', async () => {+ it('still routes when a source cannot be read', async () => {const run = async (extra: Record<string, unknown>, options: Record<string, unknown> = {}, describeRepo: ReturnType<typeof describeGit> = describeGit()) => {const s = scoped(world(extra))const answer = await routeTask(withCwd, s, where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], frames: { h1: frame() }, ...options })), () => 'op', describeRepo)expect(answer).toMatchObject({ ok: true })- return { s, missing: recorded(s).command.decision.context.missing as string[] }+ return s}- expect((await run({})).missing).toEqual([])- const noMessages = await run({ messages: undefined, messagesUnreadable: true })- expect(jevCall(noMessages.s).state.task).toContain('Recent messages: unknown')- expect(noMessages.missing).toEqual(['messages'])- // An older backend (404) and a failed read both leave the attempts out: today's history, and a note in the decision.- const noAttempts = await run({ attempts: undefined, attemptsUnreadable: true })- expect(jevCall(noAttempts.s).state.history).toContain('No earlier attempts in this group.')- expect(noAttempts.missing).toEqual(['attempts'])- const noLog = await run({ decisions: undefined, decisionsUnreadable: true })- expect(jevCall(noLog.s).state.history).toContain('Recent routing in this Super Tab: unknown')- expect(noLog.missing).toEqual(['route log'])+ expect(memberLabel(await run({}))).toContain('same repo')+ // An older backend (404) and a failed read both leave the attempts and the log out.+ expect(memberLabel(await run({ attempts: undefined, attemptsUnreadable: true }))).toContain('same repo')+ expect(memberLabel(await run({ decisions: undefined, decisionsUnreadable: true }))).toContain('same repo')for (const failing of [vi.fn(async () => { throw new Error('git') }), vi.fn(async () => null)]) {- const noFolder = await run({}, {}, { ...describeGit(), describe: failing as never })- expect(jevCall(noFolder.s).state.lead).toContain('Task folder: api (repository unknown)')- expect(memberLabel(noFolder.s)).toContain('repo unknown')- expect(noFolder.missing).toEqual(['task folder'])+ expect(memberLabel(await run({}, {}, { ...describeGit(), describe: failing as never }))).toContain('repo unknown')}// A folder read that never answers does not hold the route: it is given up after three seconds.vi.useFakeTimers()try {const pending = run({}, {}, { ...describeGit(), describe: vi.fn(() => new Promise(() => {})) as never })await vi.advanceTimersByTimeAsync(3000)- expect((await pending).missing).toEqual(['task folder'])+ expect(memberLabel(await pending)).toContain('repo unknown')} finally { vi.useRealTimers() }// Without the agent list there is no machine load; the members there cannot run, so only new agents are shown.- const noList = await run({}, { listFails: true })- expect(noList.missing).toEqual(['machine load'])- expect(newLabel(noList.s)).toContain('agents running unknown')+ expect(newLabel(await run({}, { listFails: true }))).toContain('agents running unknown')})it('finds a member in the task\'s folder when the Lead\'s machine does not have it', async () => {const two = tab(); two.state.agents = [{ ...agents[0], machineId: 'm2' }, agents[1]] as never@@ -614,26 +551,25 @@ describe('the context routeTask gives Jev', () => {const reader = describeGit(git(), false)await routeTask(withCwd, s, where as never, opener(id => daemon(id, { agents: id === 'm2' ? ['h1'] : [], frames: { h1: there } })), () => 'op', reader)expect(memberLabel(s)).toContain('same repo')- expect(jevCall(s).state.lead).toContain('Task folder: api (not on the Lead\'s machine)')expect(reader.describe).not.toHaveBeenCalled()- expect(recorded(s).command.decision.context.missing).toEqual(['task folder'])})it('says a folder is unknown, not missing, when it cannot be told apart from a refusal', async () => {for (const code of ['EACCES', 'ENOTDIR']) {const s = scoped(world())await routeTask(withCwd, s, where as never, opener(), () => 'op', { describe: vi.fn() as never, isDirectory: async () => { throw Object.assign(new Error(code), { code }) } })- expect(jevCall(s).state.lead).toContain('Task folder: api (repository unknown)')- expect(recorded(s).command.decision.context.missing).toEqual(['task folder'])+ expect(memberLabel(s)).toContain('repo unknown')}})it('reads the task folder on this machine when no reader is given', async () => {const dir = await mkdtemp(join(tmpdir(), 'route-folder-'))try {await writeFile(join(dir, 'file'), 'x')- for (const [cwd, folder] of [[dir, 'not a git repository'], [join(dir, 'absent'), 'not on the Lead\'s machine'], [join(dir, 'file', 'inside'), 'repository unknown']] as const) {+ // A member standing in the folder is in it when the folder is there or absent here; a broken path says nothing.+ for (const [cwd, repo] of [[dir, 'same repo'], [join(dir, 'absent'), 'same repo'], [join(dir, 'file', 'inside'), 'repo unknown']] as const) {const s = scoped(world())- await routeTask({ ...input, assessment: { ...input.assessment, needs: { cwd } } }, s, where as never, opener(), () => 'op')- expect(jevCall(s).state.lead).toContain(folder)+ const there = frame({ project: { name: 'x', cwd, root: null, remote: null } })+ await routeTask({ ...input, assessment: { ...input.assessment, needs: { cwd } } }, s, where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], frames: { h1: there } })), () => 'op')+ expect(memberLabel(s)).toContain(repo)}} finally { await rm(dir, { recursive: true, force: true }) }})@@ -647,11 +583,9 @@ describe('the context routeTask gives Jev', () => {// Both context reads are still waiting, and the machines have already been opened.expect(s.mock.calls.some(c => c[0].action === 'routeHistory')).toBe(true)expect(open).toHaveBeenCalled()- expect(s.mock.calls.some(c => c[0].action === 'routeJev')).toBe(false)await vi.advanceTimersByTimeAsync(3000)expect(await pending).toMatchObject({ ok: true })} finally { vi.useRealTimers() }- expect(recorded(s).command.decision.context.missing).toEqual(expect.arrayContaining(['messages', 'route log', 'attempts', 'task folder']))})it('lists a member whose machine cannot be opened as one whose activity is unknown', async () => {const two = tab(); two.state.agents = [...agents, { id: 'a2', name: 'Collab', machineId: 'theirs', harnessId: 'h2', configuration: { engine: 'claude', model: 'sonnet', effort: 'medium' } }] as never@@ -659,14 +593,6 @@ describe('the context routeTask gives Jev', () => {const open = vi.fn(async (_w: unknown, id: string) => id === 'theirs' ? Promise.reject(new Error('not yours')) : daemon(id, { agents: id === 'm1' ? ['h1'] : [], frames: { h1: frame() }, usage: { providers: [] } })) as neverawait routeTask(input, s, where as never, open)expect(labels(s).find(l => l.startsWith('Member Collab'))).toContain('activity unknown')- expect(recorded(s).command.decision.context.missing).toEqual(['member activity'])- })- it('records no context when Jev was not asked', async () => {- const s = scoped(world())- const open = vi.fn(async (_w: unknown, id: string) => id === 'm1'- ? daemon(id, { agents: ['h1'], engines: [{ engine: 'claude', installed: false }] }) as never : Promise.reject(new Error('gone')))- expect(await routeTask(input, s, where as never, open as never)).toMatchObject({ via: 'only' })- expect(recorded(s).command.decision).not.toHaveProperty('context')})})diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.tsindex 3b17c138d..f48346ac4 100644--- a/cli/src/superTabs/routeCommand.ts+++ b/cli/src/superTabs/routeCommand.ts@@ -1,15 +1,15 @@/** `harness super-tab route GROUP JSON`: the Lead's routing step (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md).- * Reads the tab, the effective policy and the account's machines; probes each machine once per engine with- * the same admission `start` uses; then orders, asks Jev, and records the decision in the tab. */+ * Reads the tab, its rules, the effective policy and the account's machines; probes each machine once per engine with+ * the same admission `start` uses; then filters and orders by the rules (docs/plans/2026-10-22-swarm-rules-routing.md)+ * and records the decision in the tab. */import { randomUUID } from 'node:crypto'import { openDaemon, type Daemon, type Where } from '../agentClient/daemon.js'import { startRequirements } from './capacity.js'import { inspectCapacity, type ScopedRequest } from './start.js'import { ENDED_WORK, object, within } from './wire.js'-import { choose, contextSize, decide, jevQuestion, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, type Assessment, type Attempt, type Commitment, type MemberFrame, type Policy, type Probe, type TaskFolder } from './route.js'+import { choose, decide, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, type Assessment, type Commitment, type MemberFrame, type Policy, type Probe, type SwarmRule, type TaskFolder } from './route.js'import { stat } from 'node:fs/promises'import { describeScmProject } from '../scm/scmProjects.js'-import type { JevChoiceAnswer } from '../lib/jev/jevClient.js'type Json = Record<string, unknown>const ENGINES = ['claude', 'codex']@@ -51,27 +51,24 @@ function withLaunchEffort(member: Json, starts: Json[]): Json {}const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)-/** Work that ended in this Super Tab, oldest first: the log's decisions, the group's attempts and each group's last- * assignment, joined by assignment id. The log knows which agent a decision started; the attempts are every earlier- * assignment of this group, also those `work.define` took out of the state (a person's assignment has no decision);- * the state knows the agent and the result of each group's last one. */-interface Ended { assignmentId: string; groupId: string; group: string; agentId: string | null; agent: string; outcome: string; result?: string }-function endedWork(conversations: Json[], agents: Json[], decisions: Json[] | null, attempts: Json[] | null, attemptsGroup: string): Ended[] {+/** Work that ended in this Super Tab, oldest first, for each member's earlier work: the log's decisions, the group's+ * attempts and each group's last assignment, joined by assignment id. The log knows which agent a decision started; the+ * attempts are every earlier assignment of this group, also those `work.define` took out of the state (a person's+ * assignment has no decision); the state knows the agent of each group's last one. */+interface Ended { assignmentId: string; group: 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 nameOf = (id: unknown) => text(agents.find(a => a.id === id)?.name)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, groupId: String(d.conversationId), group: titleOf(d.conversationId), outcome: String(d.outcome),- agentId: final.kind === 'member' ? String(final.agentId) : null,- agent: final.kind === 'member' ? nameOf(final.agentId) ?? 'An agent' : `New agent (${String(final.engine)} ${String(final.model)})` }]+ ? [{ assignmentId: d.assignmentId, group: titleOf(d.conversationId), outcome: String(d.outcome), agentId: final.kind === 'member' ? String(final.agentId) : null }]: []})- // The assignment's own record wins on agent and outcome; a started agent the tab no longer has keeps the log's name.+ // The assignment's own record wins on the agent: a started agent is a member by then.const join = (assignment: Json, groupId: string) => {- const result = text(assignment.result) ?? undefined, known = ended.find(e => e.assignmentId === assignment.id)- if (known) return Object.assign(known, { agentId: String(assignment.agentId), agent: nameOf(assignment.agentId) ?? known.agent, result })- const added: Ended = { assignmentId: String(assignment.id), groupId, group: titleOf(groupId), agentId: String(assignment.agentId), agent: nameOf(assignment.agentId) ?? 'An agent', outcome: String(assignment.status), result }+ 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) }ended.push(added)return added}@@ -102,8 +99,9 @@ export async function routeTask(input: { tabId: string; conversationId: string;return { error: 'AGENT_UNAVAILABLE', detail: error instanceof Error ? error.message : 'The request to the machine failed.' }}}- const assessment = parseAssessment(input.assessment)- if (typeof assessment === 'string') return { error: 'INVALID_REQUEST', detail: assessment }+ const parsed = parseAssessment(input.assessment)+ if (typeof parsed === 'string') return { error: 'INVALID_REQUEST', detail: parsed }+ let assessment = parsedconst cwd = assessment.needs.cwdconst context = await scoped({ action: 'routeContext' })if (context.error || context.ok !== true) return context@@ -120,6 +118,9 @@ export async function routeTask(input: { tabId: string; conversationId: string;...conversations.filter(c => active(c.assignment)).map(c => String(object(c.assignment).agentId))])// A review group is assigned only to a Reviewer, and a Reviewer nothing else.const review = typeof group.reviewOf === 'string'+ if (review) assessment = { ...assessment, kind: 'review' }+ // A backend from before rules keeps none, so routing there is the policy order alone.+ const rules = list(state.rules).filter(r => r.rule && typeof r.text === 'string') as unknown as SwarmRule[]const members = agents.filter(a => !busy.has(String(a.id)) && (a.role === 'reviewer') === review && ENGINES.includes(String(object(a.configuration).engine))).map(a => withLaunchEffort(a, list(state.starts)))// A new agent starts only on a machine in the Swarm's Machines list (the backend refuses any other): a contributed machine, or// one an agent of the Swarm runs on. The Lead runs here, so its own machine is always listed. Of the account's machines@@ -157,38 +158,19 @@ export async function routeTask(input: { tabId: string; conversationId: string;const folder: TaskFolder | null = !cwd ? null : read ?? { cwd, kind: 'unknown', name: null, root: null, remote: null }const past = object(history?.ok === true ? history.value : {})const decisions = Array.isArray(past.decisions) ? list(past.decisions) : null- const messages = Array.isArray(past.messages) ? list(past.messages).map(m => ({ from: String(m.from), text: String(m.text) })) : nullconst attempts = Array.isArray(past.attempts) ? list(past.attempts) : null- const ended = endedWork(conversations, agents, decisions, attempts, input.conversationId)+ const ended = endedWork(conversations, decisions, attempts, input.conversationId)const probes = probed.flat().map(p => p.kind === 'member' ? { ...p, repo: repoMatch(folder, p.frame ?? null, p.machineId === where.machineId),earlier: ended.filter(e => e.agentId === p.agentId).reverse().slice(0, 3).map(e => ({ group: e.group, outcome: e.outcome })) } : p)// Picks started or assigned and still at work hold part of their account's quota; the log, and so this, is per Swarm.const working = (decisions ?? []).filter(d => d.final && d.outcome === null && typeof d.account === 'string').map(d => ({ account: d.account, spend: object(d.spend), size: d.size, createdAt: Date.parse(String(d.createdAt)) }) as Commitment)- const choice = choose(probes, policy, assessment, Date.now(), working)+ const choice = choose(probes, policy, assessment, Date.now(), working, rules)if ('error' in choice) return choice- // What Jev could not be told, for the decision log: pick quality can later be compared with how complete this was.- const missing = [...(messages ? [] : ['messages']), ...(decisions ? [] : ['route log']), ...(attempts ? [] : ['attempts']), ...(folder && ['unknown', 'missing'].includes(folder.kind) ? ['task folder'] : []),- ...(choice.shown.some(s => s.kind === 'member' && !s.frame) ? ['member activity'] : []),- ...(choice.shown.some(s => s.kind === 'new' && (s.load!.agents === null || s.load!.freeMemoryBytes === null)) ? ['machine load'] : [])]-- let answer: JevChoiceAnswer | undefined, unavailable: string | null = null, question: ReturnType<typeof jevQuestion> | undefined- if (choice.shown.length > 1) {- const checks = list(group.checks).map(c => String(c.description ?? ''))- // Every attempt in this group that ended: a worker that stopped on this task is a worse choice.- const attempts: Attempt[] = ended.filter(e => e.groupId === input.conversationId).map(e => ({ agent: e.agent, outcome: e.outcome, ...(e.result ? { result: e.result } : {}) }))- const recent = decisions?.slice(0, 5).map(d => ({ title: String(d.title), ...(typeof d.via === 'string' ? { via: d.via } : {}), outcome: text(d.outcome) })) ?? null- question = jevQuestion({ title: String(group.title ?? ''), brief: String(group.brief ?? ''), checks, messages, noneInLatest: past.noneInLatest === true, folder, attempts, recent }, assessment, policy, choice)- const reply = await scoped({ action: 'routeJev', conversationId: input.conversationId, ...question })- if (typeof reply.error === 'string' && !TRANSPORT.has(reply.error)) return reply- const jev = object(reply.value)- if (reply.ok !== true || typeof jev.unavailable === 'string') unavailable = typeof jev.unavailable === 'string' ? jev.unavailable : 'UNAVAILABLE'- else answer = object(jev.answers).who as JevChoiceAnswer | undefined- }- const verdict = decide(choice, answer, unavailable)+ const verdict = decide(choice)const operationId = `route-${newId()}`const record = (v1: boolean) => scoped({ action: 'command', operationId,- command: { type: 'route.record', conversationId: input.conversationId, decision: recordOf(choice, verdict, assessment, policy, question && { chars: contextSize(question), missing }, v1) } })+ command: { type: 'route.record', conversationId: input.conversationId, decision: recordOf(choice, verdict, assessment, policy, v1) } })let recorded = await record(false)// A backend from before phase 1 refuses the new fields as invalid; the decision is still worth keeping in the shape it knows.if (recorded.error === 'VALIDATION_ERROR') recorded = await record(true)diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.tsindex 2ac620d3d..2c1e89228 100644--- a/cli/src/superTabs/service.spec.ts+++ b/cli/src/superTabs/service.spec.ts@@ -4,14 +4,9 @@ import { fakeCore } from '../testing/fakeCore.js'import type { CoreApi } from '../core/api.js'import { superTabService } from './service.js'import { SuperTabHostError, type SuperTabHost } from './host.js'-import { createJevDecide, type JevDecide } from '../lib/jev/jevClient.js'--// The real client would read the developer's OpenRouter key; the account backend is the only part under test.-vi.mock('../lib/jev/jevClient.js', async importOriginal => ({ ...await importOriginal<typeof import('../lib/jev/jevClient.js')>(), createJevDecide: vi.fn() }))-const createJev = vi.mocked(createJevDecide)const owner = { local: true, owner: true }, visitor = { local: false, owner: false }-function setup(options: { jev?: () => JevDecide; prepareContribution?: typeof import('./contribution.js').prepareContribution } = {}) {+function setup(options: { prepareContribution?: typeof import('./contribution.js').prepareContribution } = {}) {const agentId = createHash('sha256').update(JSON.stringify(['machine-1', 'native'])).digest('hex').slice(0, 24)const agent = { id: agentId, machineId: 'machine-1', harnessId: 'native' }const call = vi.fn<CoreApi['account']['backend']>(async () => ({ status: 200, body: { success: true, data: { state: { agents: [agent] } } } }))@@ -259,7 +254,7 @@ it('returns the routing context to a verified contribution', async () => {machines: [{ machineId: 'm1', name: 'remote-1', status: 'online' }, { machineId: 'm2', name: 'shared', status: 'online' }] } })expect(t.call).toHaveBeenCalledWith('GET', `/api/super-tabs/tab/routing-policy?asAgentId=${t.agentId}`, undefined)})-describe('routeHistory for Jev', () => {+describe('routeHistory', () => {const contextOf = (t: ReturnType<typeof setup>, read: (path: string) => Promise<unknown>, lead?: string) => {const state = { agents: [{ ...t.agent, name: 'Boss' }, { id: 'a2', name: 'Multiply' }, { id: 'a3', name: 'Reader' }], conversations: [{ id: 'g1', leadId: lead ?? t.agentId }] }vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => {@@ -270,38 +265,16 @@ describe('routeHistory for Jev', () => {return t.ask({ action: 'routeHistory', tabId: 'tab', harnessId: 'native', conversationId: 'g1' }, owner) as Promise<{ value: Record<string, unknown> }>}const ok = (data: unknown) => ({ status: 200, body: { success: true, data } })- it('gives the last ten group messages with a role instead of an author, and never an agent transcript or a routing note', async () => {+ it('reads only the route log and the attempts, never the group\'s messages, which only Jev read', async () => {const t = setup()- const person = (text: string) => ({ author: { kind: 'person', id: 'u1', name: '[email protected]' }, text })- const rows = [- ...Array.from({ length: 8 }, (_, i) => person(`early ${i}`)),- { author: { kind: 'agent', id: t.agentId, name: 'Boss' }, text: 'Lead says' },- { author: { kind: 'agent', id: 'a2', name: 'Multiply' }, text: 'Worker says', source: null },- { author: { kind: 'agent', id: 'a2', name: 'Multiply' }, text: 'TRANSCRIPT', source: { kind: 'native', phase: 'answer' } },- { author: { kind: 'agent', id: t.agentId, name: 'Boss' }, text: 'Routed to X', source: { kind: 'route', decisionId: 'd' } },- { author: { kind: 'agent', id: 'gone', name: 'Gone' }, text: 'x'.repeat(1500) },- { author: { kind: 'agent', id: 'a3', name: 'Reader' }, text: 'last' },- ]- const { value } = await contextOf(t, async path => path.includes('/messages') ? ok({ messages: rows }) : ok([]))- const messages = value.messages as Array<{ from: string; text: string }>- expect(messages.map(m => m.from)).toEqual([...Array(6).fill('person'), 'Lead', 'Multiply', 'agent', 'Reader'])- expect(messages[0].text).toBe('early 2')- expect(messages[8].text).toBe('x'.repeat(1000))- expect(JSON.stringify(value.messages)).not.toMatch(/@|TRANSCRIPT|Routed to/)- expect(value).not.toHaveProperty('messagesUnreadable')- expect(vi.mocked(t.core.account.backend)).toHaveBeenCalledWith('GET', `/api/super-tabs/tab/conversations/g1/messages?asAgentId=${t.agentId}`, undefined)- })- it('says the latest page held only log rows, instead of saying nothing was said', async () => {- const only = [{ author: { kind: 'agent', id: 'a2', name: 'Multiply' }, text: 'T', source: { kind: 'native' } }]- const { value } = await contextOf(setup(), async path => path.includes('/messages') ? ok({ messages: only }) : ok([]))- expect(value).toMatchObject({ messages: [], noneInLatest: true })- const empty = await contextOf(setup(), async path => path.includes('/messages') ? ok({ messages: [] }) : ok([]))- expect(empty.value).toEqual({ messages: [], decisions: [], attempts: [] })+ const { value } = await contextOf(t, async () => ok([]))+ expect(value).toEqual({ decisions: [], attempts: [] })+ expect(vi.mocked(t.core.account.backend)).not.toHaveBeenCalledWith('GET', expect.stringContaining('/messages'), undefined)})it('is for the Lead of the group only, like the route', async () => {const t = setup()expect(await contextOf(t, async () => ok([]), 'someone-else')).toMatchObject({ error: 'LEAD_REQUIRED', status: 403 })- expect(vi.mocked(t.core.account.backend)).not.toHaveBeenCalledWith('GET', expect.stringContaining('/messages'), undefined)+ expect(vi.mocked(t.core.account.backend)).not.toHaveBeenCalledWith('GET', expect.stringContaining('/route-decisions'), undefined)})it('gives the latest routing decisions in brief, newest first, without their records', async () => {const t = setup()@@ -334,7 +307,7 @@ describe('routeHistory for Jev', () => {expect(person).toMatchObject({ title: 'Pick', account: 'k0', spend: { '5-hour': 30, weekly: 4 } })expect(lead).not.toHaveProperty('account')})- it('gives every attempt of the group, newest first, with only what Jev needs and no more than fifty', async () => {+ it('gives every attempt of the group, newest first, with only what the route needs and no more than fifty', async () => {const t = setup()const row = (i: number) => ({ id: `as${i}`, agentId: i % 2 ? 'a2' : 'gone', status: 'stopped', result: i === 0 ? 'Tests failed.' : i === 2 ? 'y'.repeat(900) : null, createdAt: '2026-10-19T10:00:00Z',conversationId: 'g1', execution: { harnessId: 'secret' } })@@ -351,30 +324,27 @@ describe('routeHistory for Jev', () => {it('marks the attempts unreadable when an older backend answers 404 or the read fails or hangs', async () => {const without = (path: string) => path.includes('/messages') ? ok({ messages: [] }) : ok([])const old = await contextOf(setup(), async path => path.includes('/attempts') ? { status: 404, body: { success: false, error: { code: 'NOT_FOUND' } } } : without(path))- expect(old.value).toMatchObject({ messages: [], decisions: [], attemptsUnreadable: true })+ expect(old.value).toMatchObject({ decisions: [], attemptsUnreadable: true })expect(old.value).not.toHaveProperty('attempts')const failed = await contextOf(setup(), async path => path.includes('/attempts') ? Promise.reject(new Error('down')) : without(path))- expect(failed.value).toMatchObject({ attemptsUnreadable: true, messages: [] })+ expect(failed.value).toMatchObject({ attemptsUnreadable: true, decisions: [] })const odd = await contextOf(setup(), async path => path.includes('/attempts') ? ok({ attempts: 'no' }) : without(path))expect(odd.value).toMatchObject({ attemptsUnreadable: true })vi.useFakeTimers()try {const slow = contextOf(setup(), async path => path.includes('/attempts') ? new Promise(() => {}) : without(path))await vi.advanceTimersByTimeAsync(3000)- expect((await slow).value).toMatchObject({ messages: [], decisions: [], attemptsUnreadable: true })+ expect((await slow).value).toMatchObject({ decisions: [], attemptsUnreadable: true })} finally { vi.useRealTimers() }})- it('marks each source it could not read on its own, and never waits longer than three seconds for one', async () => {- const failed = await contextOf(setup(), async path => path.includes('/messages') ? Promise.reject(new Error('down')) : ok([]))- expect(failed.value).toMatchObject({ messagesUnreadable: true, decisions: [] })- expect(failed.value).not.toHaveProperty('decisionsUnreadable')- const odd = await contextOf(setup(), async path => path.includes('/messages') ? ok({ messages: 'no' }) : { status: 503, body: { error: 'SERVICE_UNAVAILABLE' } })- expect(odd.value).toMatchObject({ messagesUnreadable: true, decisionsUnreadable: true })+ it('marks the route log unreadable on its own, and never waits longer than three seconds for it', async () => {+ const odd = await contextOf(setup(), async path => path.includes('/attempts') ? ok([]) : { status: 503, body: { error: 'SERVICE_UNAVAILABLE' } })+ expect(odd.value).toEqual({ decisionsUnreadable: true, attempts: [] })vi.useFakeTimers()try {- const slow = contextOf(setup(), async path => path.includes('/messages') ? ok({ messages: [] }) : new Promise(() => {}))+ const slow = contextOf(setup(), async path => path.includes('/attempts') ? ok([]) : new Promise(() => {}))await vi.advanceTimersByTimeAsync(3000)- expect((await slow).value).toMatchObject({ messages: [], decisionsUnreadable: true })+ expect((await slow).value).toEqual({ decisionsUnreadable: true, attempts: [] })} finally { vi.useRealTimers() }})})@@ -390,59 +360,10 @@ it('says the machine list could not be read, instead of offering none', async ()t.core.account.machines = vi.fn(async () => ({ status: 200, body: { data: { machines: [{ machineId: 'm1', name: 'remote-1', status: 'online' }] } } }))expect((await t.ask({ action: 'routeContext', tabId: 'tab', harnessId: 'native' }, owner) as { value: object }).value).not.toHaveProperty('machinesUnreadable')})-const routing = (t: ReturnType<typeof setup>, decisions: unknown[] = [], leadId?: string) => vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => path.includes('/route-decisions')- ? { status: 200, body: { success: true, data: decisions } }- : { status: 200, body: { success: true, data: { state: { agents: [t.agent], conversations: [{ id: 'g1', leadId: leadId ?? t.agentId }] } } } })-it('asks Jev with a three-second limit and reports unavailability instead of failing', async () => {- const answer = { who: { choice: 'c1', probabilities: { c0: 0.2, c1: 0.8 } } }- const decide = vi.fn<JevDecide>(async () => answer)- const t = setup({ jev: () => decide }); routing(t)- expect(await t.ask({ action: 'routeJev', tabId: 'tab', harnessId: 'native', conversationId: 'g1', state: { task: 't' }, questions: { who: {} } }, owner))- .toEqual({ ok: true, value: { answers: answer } })- expect(decide.mock.calls[0][2]).toBeInstanceOf(AbortSignal)- const ask = (extra: object = {}) => t.ask({ action: 'routeJev', tabId: 'tab', harnessId: 'native', conversationId: 'g1', state: {}, questions: {}, ...extra }, owner)- decide.mockRejectedValueOnce(Object.assign(new Error('busy'), { code: 'BUSY' }))- expect(await ask()).toEqual({ ok: true, value: { unavailable: 'BUSY' } })- decide.mockRejectedValueOnce(new DOMException('The operation timed out.', 'TimeoutError'))- expect(await ask()).toEqual({ ok: true, value: { unavailable: 'TIMEOUT' } })- decide.mockRejectedValueOnce(new DOMException('Aborted', 'AbortError'))- expect(await ask()).toEqual({ ok: true, value: { unavailable: 'TIMEOUT' } })- decide.mockRejectedValueOnce(new Error('boom'))- expect(await ask()).toEqual({ ok: true, value: { unavailable: 'UNAVAILABLE' } })- decide.mockRejectedValueOnce('odd')- expect(await ask()).toEqual({ ok: true, value: { unavailable: 'UNAVAILABLE' } })-})-it('builds Jev from the account backend when no override is given', async () => {+it('no longer asks Jev: the daemon has no routeJev action', async () => {const t = setup()- const hosted = { who: { choice: 'c0', probabilities: { c0: 1 } } }- vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => path === '/api/route/jev'- ? { status: 200, body: { data: { answers: hosted } } }- : path.includes('/route-decisions') ? { status: 200, body: { success: true, data: [] } }- : { status: 200, body: { success: true, data: { state: { agents: [t.agent], conversations: [{ id: 'g1', leadId: t.agentId }] } } } })- createJev.mockImplementationOnce(options => (async () => {- const reply = await options!.backend!('POST', '/api/route/jev', {})- return (reply.body.data as { answers: Record<string, never> }).answers- }) as JevDecide)- const service = superTabService(t.core, { host: () => ({ machineId: 'machine-1', start: vi.fn(), stop: vi.fn() }) as unknown as SuperTabHost })- expect(await service.requests.super_tabs({ action: 'routeJev', tabId: 'tab', harnessId: 'native', conversationId: 'g1', state: {}, questions: {} }, owner))- .toEqual({ ok: true, value: { answers: hosted } })-})-it('refuses routing to anyone but the group Lead, and past 30 decisions in the rolling hour, before asking Jev', async () => {- const decide = vi.fn<JevDecide>(async () => ({}))- const t = setup({ jev: () => decide })- const ask = (conversationId: string) => t.ask({ action: 'routeJev', tabId: 'tab', harnessId: 'native', conversationId, state: {}, questions: {} }, owner)- routing(t, [], 'someone-else')- expect(await ask('g1')).toMatchObject({ error: 'LEAD_REQUIRED', status: 403 })- routing(t)- expect(await ask('missing')).toMatchObject({ error: 'LEAD_REQUIRED' })- const recent = (n: number, age = 1000) => Array.from({ length: n }, () => ({ createdAt: new Date(Date.now() - age).toISOString() }))- routing(t, recent(30))- expect(await ask('g1')).toMatchObject({ error: 'RATE_LIMITED', status: 429 })- routing(t, [...recent(29), ...recent(50, 61 * 60_000)])- expect(await ask('g1')).toMatchObject({ ok: true })- routing(t, { not: 'a list' } as never)- expect(await ask('g1')).toMatchObject({ ok: true })- expect(decide).toHaveBeenCalledTimes(2)+ expect(await t.ask({ action: 'routeJev', tabId: 'tab', harnessId: 'native', conversationId: 'g1', state: {}, questions: {} }, owner)).not.toMatchObject({ ok: true })+ expect(vi.mocked(t.core.account.backend)).not.toHaveBeenCalledWith('POST', '/api/route/jev', expect.anything())})it('prepares machines only for their owner and clears setup receipts on disconnect', async () => {@@ -534,6 +455,19 @@ it('teaches agents to say when their work needs a person or is stuck', async ()expect(help.help.command).toContain('needs_human')})+it('says a server from before rules does not support them, and passes a malformed rule\'s refusal through', async () => {+ const t = setup()+ const refuse = (message: string) => t.call.mockImplementation(async (...args: unknown[]) => args[0] === 'POST'+ ? { status: 400, body: { success: false, error: { code: 'VALIDATION_ERROR', message } } } as never+ : { status: 200, body: { success: true, data: { state: { agents: [t.agent] } } } })+ const send = (command: object) => t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'rule', command }, owner)+ refuse("command.type: Invalid discriminator value. Expected 'machine.contribute'")+ expect(await send({ type: 'rule.set', rule: { kind: 'preferIdle' }, text: 'Idle first.' })).toEqual({ error: 'RULES_UNSUPPORTED', detail: 'This Swarm\'s server does not support rules yet.' })+ expect(await send({ type: 'rule.remove', ruleId: 'r' })).toMatchObject({ error: 'RULES_UNSUPPORTED' })+ refuse('command.rule.effort: Invalid option')+ expect(await send({ type: 'rule.set', rule: { kind: 'minEffort', effort: 'huge' }, text: 'x' })).not.toMatchObject({ error: 'RULES_UNSUPPORTED' })+})+it('documents finished worker decisions and explains an older backend without release support', async () => {const t = setup()const help = (await t.ask({ action: 'help' }, owner)).help as { commands: unknown[]; release: string }diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.tsindex 33a76b3ba..3e9065a75 100644--- a/cli/src/superTabs/service.ts+++ b/cli/src/superTabs/service.ts@@ -4,7 +4,6 @@ import { createHash } from 'node:crypto'import type { CoreApi, ServiceRequests, SuperTabsPort } from '../core/api.js'import { backend, swarmRoleFor, hostJournalFile, identifier, object, SuperTabHost, SuperTabHostError } from './host.js'import { within } from './wire.js'-import { createJevDecide, type JevDecide } from '../lib/jev/jevClient.js'import { machineChoices } from '../lib/newCommand.js'import { START_REQUIREMENTS } from './capacity.js'import { CapacityReservations, type ReservationBook } from './reservations.js'@@ -13,18 +12,18 @@ import { messageIdOf } from './attach.js'import { cardId, SwarmCards } from './cards.js'const HELP = {- status: 'Read the shared tab roster and work.',+ status: 'Read the shared tab roster and work. Its rules are the owner\'s routing rules, each in the owner\'s own words.',messages: 'messages GROUP: read recent messages in a conversation.',message: 'message GROUP MESSAGE_ID: read one exact message, including an earlier question or result referenced by a reply.',post: 'post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]...: reply in that conversation. Use a unique ID per message and reuse it after an interrupted request. Answer a message once, with --reply-to its ID. --attach sends a file (a screenshot, a log; up to 10 files of 10 MB each), and TEXT may then be empty.',start: 'start OPERATION_ID JSON: create one agent in a conversation on a machine in this Swarm\'s Machines list; to use another machine, a person adds it to the Swarm first. Repeat exactly after an interruption; it follows the same native creation receipt. It does not assign work. With worktree true, the agent starts from the repository\'s default branch, fetched first, unless you set branchRef (refs/heads/BRANCH, or refs/remotes/origin/BRANCH to fetch it first) to start from another branch, such as the one this work builds on. Set role "reviewer" to start a Reviewer; leave role out for a Builder. The role is kept for the session. A Reviewer runs on claude or codex and is assigned only review groups (conversation.create with reviewOf naming the group it reviews); a review group is assigned only to a Reviewer. Add the Reviewer to the reviewed group with conversation.agent so it is told when that work is ready for review and can pass its independent check. Start one with a routeDecisionId like any agent.',release: 'When a Builder finishes, decide reuse, keep or stop; prefer stop unless more work is coming soon. Reuse assigns new work; agent.release records keep or requests stop. Wait for the execution host to confirm a stop. A person can withdraw a stuck stop; the session cannot receive new work in that Swarm. Its native capacity stays reserved until its host confirms stopping. Other Swarms wait up to two minutes for an in-flight close, then may reuse it.',resume: 'resume START_ID: finish a pending start without creating another agent.',- route: 'route GROUP JSON: before you start an agent or assign work to another agent, choose who does it. Work you do yourself is not routed. JSON: {"difficulty":"low|medium|high","risk":"low|medium|high","size":"small|medium|large","why":"one sentence","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. Start or assign the pick with its routeDecisionId; to choose otherwise, pass overrideReason. An agent\'s start or work.assign without a routeDecisionId is refused, so route first; a person can still start and assign by hand.',+ route: 'route GROUP JSON: before you start an agent or assign work to another agent, choose who does 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","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. Candidates that break the owner\'s hard rules are left out; soft rules (a preferred engine for the kind, idle agents first) rank the rest. Start or assign the pick with its routeDecisionId; to choose otherwise, pass overrideReason. An agent\'s start or work.assign without a routeDecisionId is refused, so route first; a person can still start and assign by hand.',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.',startRequest: { conversationId: 'GROUP', machineId: 'MACHINE', engine: 'codex', name: 'Builder', cwd: '/absolute/repo/on/that/machine', worktree: true, branchRef: 'refs/remotes/origin/BASE_BRANCH', requirements: START_REQUIREMENTS,model: 'opus', effort: 'high', routeDecisionId: 'DECISION' },- command: 'command OPERATION_ID JSON: send one of the commands below. Reuse exactly the same ID and JSON after an interrupted request. When your assignment needs a person to decide, set work.status needs_human; when you cannot go on, blocked. Set working again once it moves.',+ command: 'command OPERATION_ID JSON: send one of the commands below. Reuse exactly the same ID and JSON after an interrupted request. When your assignment needs a person to decide, set work.status needs_human; when you cannot go on, blocked. Set working again once it moves. rule.set and rule.remove change the owner\'s routing rules: only the owner does, or the Lead passing on the owner\'s request, with askedIn naming the owner\'s message. A start, assignment or route that breaks a hard rule (forbidModel, machines, minEffort) is refused for agents; preferEngine and preferIdle only rank.',commands: [{ type: 'project.report', projectId: 'PROJECT', throughRevision: 123, text: 'What changed, what is blocked, and what comes next. Use null when nothing merits repeating.' },{ type: 'project.repository', projectId: 'PROJECT', repositoryUrl: 'https://github.com/OWNER/REPOSITORY' },@@ -35,6 +34,12 @@ const HELP = {{ type: 'work.define', conversationId: 'GROUP', task: { goal: 'What to deliver', changes: 'What changes', constraints: 'What must stay true', owns: ['Paths or code areas'] }, checks: [{ description: 'Observable acceptance evidence', independent: false }] },{ type: 'work.cancel', conversationId: 'GROUP', assignmentId: 'ATTEMPT', reason: 'Lead or tab owner only: why the task is cancelled, in one short sentence' },{ type: 'agent.release', agentId: 'AGENT', decision: 'keep|stop' },+ { type: 'rule.set', rule: { kind: 'forbidModel', model: 'haiku' }, text: 'The owner\'s words: No Haiku.', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },+ { type: 'rule.set', rule: { kind: 'minEffort', effort: 'high' }, text: 'At least high effort.', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },+ { type: 'rule.set', rule: { kind: 'machines', machineIds: ['MACHINE'] }, text: 'Only these machines.', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },+ { type: 'rule.set', rule: { kind: 'preferEngine', taskKind: 'ui', engine: 'codex' }, text: 'Codex for UI work.', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },+ { type: 'rule.set', rule: { kind: 'preferIdle' }, text: 'Reuse idle agents first.', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },+ { type: 'rule.remove', ruleId: 'RULE', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },{ type: 'work.assign', conversationId: 'GROUP', agentId: 'AGENT', routeDecisionId: 'DECISION' },{ type: 'work.status', conversationId: 'GROUP', assignmentId: 'ATTEMPT', status: 'working', result: null },// Both reach the Lead and alert the Harness Pro on the machine running the agent until the status moves on.@@ -84,8 +89,6 @@ export interface SuperTabServiceOptions {capacity?: typeof readCapabilitieshost?: (core: CoreApi, machineId: string) => SuperTabHostreservations?: (core: CoreApi, machineId: string) => ReservationBook- /** Jev for `route`; Harness's hosted key through the backend when the person has no key of their own. */- jev?: (core: CoreApi) => JevDecide/** The Swarm cards' reader (superTabs/cards.ts), for a spec. */cards?: (core: CoreApi, machineId: string) => SwarmCards}@@ -201,27 +204,17 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =machines: readable ? machineChoices(object(object(machines.body).data), null).filter(m => !m.toAdd).map(m => ({ machineId: m.machineId, name: m.label, status: m.status })) : [],...(readable ? {} : { machinesUnreadable: true }) } }}- // What Jev reads besides the candidates. Apart from `routeContext` so the Lead reads it while it probes the- // machines; the group's Lead only, like the route itself.+ // The route log and the group's attempts, for the quota open picks hold and what members did before. Apart from+ // `routeContext` so the Lead reads it while it probes the machines; the group's Lead only, like the route itself.if (payload.action === 'routeHistory') {const group = list(state.conversations).find(c => c.id === payload.conversationId)if (!group || group.leadId !== agentId) return { error: 'LEAD_REQUIRED', detail: 'The coordinating Lead of this group owns routing.', status: 403 }- const [written, logged, tried] = await Promise.all([- within(backend(core, 'GET', `${path}/conversations/${payload.conversationId}/messages?${identity}`)),+ const [logged, tried] = await Promise.all([within(backend(core, 'GET', `${path}/route-decisions?${identity}`)),// An older backend has no such route: its 404 is unreadable like any other failure.within(backend(core, 'GET', `${path}/conversations/${payload.conversationId}/attempts?${identity}`)),])- // Jev reads the group's talk as roles: an email is a person's name here, so it never leaves this step.- // Native rows are an agent's own transcript and route rows are the log's, so only the talk is kept.- const rows = Array.isArray(object(written).messages) ? list(object(written).messages) : null- const messages = rows?.filter(m => !m.source).slice(-10).map(m => {- const by = object(m.author)- return { from: by.kind === 'person' ? 'person' : by.id === group.leadId ? 'Lead' : String(list(state.agents).find(a => a.id === by.id)?.name ?? 'agent'),- text: String(m.text ?? '').slice(0, 1000) }- })- // The log's records carry every candidate's line; Jev needs only who was picked and how it went. The route also- // needs the account and expected spend of what actually runs, which an open pick still holds: after an override+ // The log's records carry every candidate's line; the route needs only who was picked and how it went, and the account and expected spend of what actually runs, which an open pick still holds: after an override// that is the person's chosen candidate, and a Lead's own choice outside the list has no known account.const decisions = Array.isArray(logged) ? logged.slice(0, 50).map(object).map(d => {const record = object(d.record), final = object(d.final), candidates = list(record.candidates), pick = candidates.find(c => c.id === record.pick)@@ -233,28 +226,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =}) : null// Every attempt the group had, also the ones `work.define` took out of the state; the server already cut the results.const attempts = Array.isArray(tried) ? tried.slice(0, 50).map(object).map(a => ({ id: a.id, agentId: a.agentId, status: a.status, result: typeof a.result === 'string' ? a.result.slice(0, 500) : null, createdAt: a.createdAt ?? null })) : null- return { ok: true, value: { ...(messages ? { messages, ...(rows!.length && !messages.length ? { noneInLatest: true } : {}) } : { messagesUnreadable: true }),- ...(decisions ? { decisions } : { decisionsUnreadable: true }), ...(attempts ? { attempts } : { attemptsUnreadable: true }) } }- }- if (payload.action === 'routeJev') {- // Jev costs money and the decision is the Lead's, so both rules are checked before it is asked.- const group = Array.isArray(state.conversations) ? state.conversations.map(object).find(c => c.id === payload.conversationId) : undefined- if (!group || group.leadId !== agentId) return { error: 'LEAD_REQUIRED', detail: 'The coordinating Lead of this group owns routing.', status: 403 }- const decisions = await backend(core, 'GET', `${path}/route-decisions?${identity}`)- const hourAgo = Date.now() - 60 * 60_000- if ((Array.isArray(decisions) ? decisions : []).filter(d => Date.parse(String(object(d).createdAt)) >= hourAgo).length >= 30) {- return { error: 'RATE_LIMITED', detail: 'This Super Tab routed 30 tasks in the last hour. Wait before routing again.', status: 429 }- }- const decide = (options.jev ?? (api => createJevDecide({ backend: (m, p, b) => api.account.backend(m, p, b) })))(core)- try {- // Routing never waits on Jev beyond three seconds; the policy order decides instead.- return { ok: true, value: { answers: await decide(payload.state, object(payload.questions) as never, AbortSignal.timeout(3000)) } }- } catch (error) {- // A timeout is a DOMException whose `code` is a number; Jev's own refusals carry a string code.- const name = error instanceof Error ? error.name : ''- const code = error && typeof error === 'object' && 'code' in error && typeof error.code === 'string' ? error.code : null- return { ok: true, value: { unavailable: name === 'TimeoutError' || name === 'AbortError' ? 'TIMEOUT' : code ?? 'UNAVAILABLE' } }- }+ return { ok: true, value: { ...(decisions ? { decisions } : { decisionsUnreadable: true }), ...(attempts ? { attempts } : { attemptsUnreadable: true }) } }}if (payload.action === 'messages' && identifier(payload.conversationId)) {const page = await backend(core, 'GET', `${path}/conversations/${payload.conversationId}/messages?${identity}`)@@ -281,6 +253,10 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =if (command.type === 'agent.release' && error instanceof SuperTabHostError && error.status === 400 && ['VALIDATION_ERROR', 'INVALID_REQUEST'].includes(error.code)) {return { error: 'RELEASE_UNSUPPORTED', detail: 'This backend does not support releasing Builders yet. Update the backend and try again.' }}+ // A backend from before rules does not know the command type at all; a malformed rule is the Lead's to fix.+ if (['rule.set', 'rule.remove'].includes(String(command.type)) && error instanceof SuperTabHostError && error.status === 400 && /discriminator/i.test(error.message)) {+ return { error: 'RULES_UNSUPPORTED', detail: 'This Swarm\'s server does not support rules yet.' }+ }if (!['conversation.create', 'work.define'].includes(String(command.type)) || !command.task || !(error instanceof SuperTabHostError)) throw errorconst oldSchema = error.status === 400 && error.code === 'VALIDATION_ERROR'&& /^(?:command: )?Unrecognized (?:key: "task"|key\(s\) in object: 'task')$/.test(error.message)diff --git a/docs/plans/2026-10-22-swarm-rules-routing.md b/docs/plans/2026-10-22-swarm-rules-routing.mdnew file mode 100644index 000000000..2847cec64--- /dev/null+++ b/docs/plans/2026-10-22-swarm-rules-routing.md@@ -0,0 +1,224 @@+# Swarm rules replace Jev in routing++Date: 2026-10-22. Status: approved by the Lead on 2026-10-22 and implemented.++## Why++On 2026-10-22 the Lead overrode Jev's pick about half the time: Haiku, a stopping agent on an offline+machine, low effort. Jev does not know the owner's rules, so asking it is a step the Lead then undoes.+The rules also lived only in the Lead's head. They move into the Swarm. The system enforces the hard+ones and ranks candidates by the soft ones, and routing stops asking a hosted model.++## Rules++A rule is stored in the Swarm's state (`SuperTabState.rules`, at most 50 rules):++```ts+interface Rule {+ id: string // the operation id of the command that added it+ rule:+ | { kind: 'forbidModel'; engine?: 'claude' | 'codex'; model: string } // hard+ | { kind: 'machines'; machineIds: string[] } // hard+ | { kind: 'minEffort'; engine?: 'claude' | 'codex'; effort: Effort } // hard+ | { kind: 'preferEngine'; taskKind: string | null; engine: 'claude' | 'codex' } // soft+ | { kind: 'preferIdle' } // soft+ text: string // the owner's words, 1–200 characters, e.g. "No Haiku, ever."+ askedBy: string // the owner's user id+ askedIn: { conversationId: string; messageId: string } | null // the owner's message, when a Lead relays it+ addedBy: string // actorKey of whoever sent the command (owner or Lead)+ createdAt: string+}+type Effort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'+```++The meaning of each rule:++- **forbidModel** (hard): no agent may run a model whose id contains `model`, compared case-insensitively.+ This catches the short name and the full id (`haiku` matches `haiku` and `claude-haiku-4-5`). A rule+ naming a full id also matches a start that asks for that family's alias (`claude-haiku-4-5` matches+ `haiku`). A model of `default` matches nothing, because the actual model is not known.+- **machines** (hard): agents run only on the listed machines. There is at most one such rule; adding+ another replaces it.+- **minEffort** (hard): the effort is at least `effort`, in the order+ minimal < low < medium < high < xhigh < max. An unknown effort (`default`, `auto`) does not meet it.+ A member's `auto` is first resolved from its start record, as `withLaunchEffort` does today. A+ new-agent candidate whose policy row says `default` or `auto` is not dropped: it is lifted to the+ minimum, and the start it suggests names that effort.+- **preferEngine** (soft): for tasks of `taskKind`, or for every task when it is null, candidates on+ `engine` rank first. A task's kind is a new optional `kind` word in the route JSON+ (`"kind":"ui"`). A review group's kind is always `review`.+- **preferIdle** (soft): an idle member ranks before a new agent. Among new agents, a machine with fewer+ running agents ranks first.++Routing already removes an offline machine, a stopping agent (it is busy or refused) and an exhausted+quota. Those stay as they are and are not rules.++## Who changes rules++Two new commands go through the existing `command` path:++```json+{"type":"rule.set","rule":{"kind":"forbidModel","model":"haiku"},"text":"No Haiku.","askedIn":{"conversationId":"…","messageId":"…"}}+{"type":"rule.remove","ruleId":"…","askedIn":{"conversationId":"…","messageId":"…"}}+```++- A person may change rules only if they are the Swarm owner, and they omit `askedIn`.+- An agent may change rules only if it is the tab's Lead (the `controls(state, actor)` check that+ `tab.rename` uses), and it must pass `askedIn`. The backend reads that message, the way it reads+ `replyTo` for `message.send`. The message must meet three conditions:+ - its author is the owner, as a person;+ - it is a plain chat message: no system row, such as the owner's own "Rule added" row or a warning;+ - it is at most a day old.++ Otherwise the change is refused with "Only the Swarm owner sets rules; quote a chat message the owner+ wrote in the last day asking for this change." This was added in the review of #1586. One owner+ message may ask for several rules, so the Lead may quote it for each of them.+- Everyone else is refused with `OWNER_REQUIRED`: "Only the Swarm owner, or the Lead passing on the+ owner's request, changes rules."+- Each change posts one row in the lead group ("Rule added: No Haiku."), so the change can be seen+ without any UI. The row has no email in it; who asked is kept on the rule.+- **Listing:** the rules are part of the tab state that `status` already returns, with each rule's+ `text`. When asked, the Lead lists them in the owner's own words. No new command is added.++## Backend enforcement (hard rules)++The check is one pure function, `broken(rules, { machineId, engine, model, effort })`, in+`backend/src/superTabs/rules.ts`. It returns the sentence for the first broken rule, or null. The CLI+has the same check (`breaks` in `route.ts`), so a pick it offers is never refused later. It is called by:++- **agent.start**, with the request's machine, engine, model and effort;+- **work.assign**, with the worker's machine and configuration (effort resolved from its start record+ when it reports `auto`);+- **conversation.agent** when an agent joins or leads a group (leaving is never checked);+- **agent.startDispatch**, so a start recorded before a rule was added is not launched past it. An agent's+ dispatch is refused, and the start stays unlaunched;+- **route.record**, with the pick (a new-agent candidate's fields, or the member's current+ configuration). Other candidates in the record are not checked, so an older CLI that lists a+ forbidden candidate can still record a decision when its pick is allowed.++An **agent** that breaks a rule is refused with `RULE_BROKEN` and one plain sentence, for example:+`The owner's rule "No Haiku." rules out Claude haiku. Route again.` An `overrideReason` does not get+past a hard rule.++A **person** is not blocked. The command goes through, its result carries `warnings`, and the group gets+one row (a rule row, with a name rather than an email): `ken started Builder anyway. The owner's rule+"No Haiku." rules out Claude haiku.` A person's `route.override` to a candidate that breaks a rule works+the same way.++The person's choice carries through. When the Lead then starts or assigns exactly the candidate the person+chose, it is let through with the same warning; anything else the Lead does is still refused. The same+applies to dispatching such a start.++Agents that were already running when a rule was added keep running. Routing just stops offering them,+and new assignments to them are refused.++Soft rules are not enforced by the backend.++## CLI routing (`cli/src/superTabs/route.ts`, `routeCommand.ts`, `service.ts`)++`choose()` goes through these steps:++1. **Refusals** (unchanged).+2. **Hard rules**: a candidate that breaks a rule moves to `excluded` with the reason+ `Breaks the owner's rule: …`. If nobody is left, the result is `NO_CANDIDATE`, and the excluded+ list says why.+3. **Quality floor, strength for hard tasks, quota fit groups** (unchanged).+4. **Fixed order**: preferred engine for the kind (soft), then idle member before new agent (soft), then+ today's order (effective cost, quality, room on the tightest window, member in the same repository,+ title).++`decide()` keeps the first candidate. The verdict is `only` when there is one candidate and `order`+otherwise, with no `fallback`.++Removed:++- `routeJev` (the daemon action) and the `jev` option in `service.ts`;+- the group-messages read in `routeHistory`, which only Jev used;+- `jevQuestion`, `contextSize`, `INSTRUCTIONS`, `folderText`, `JevInput`, the `jevPick` import and the+ record's `context` field;+- `scrub`, which existed so that nothing identifying reached the hosted model. Labels now go only to+ the Swarm's own log, which its members can already read.++Kept:++- the decision log (`route.record`), and labels and fit in it;+- the commitments read from the log;+- the rule from #1555 that an agent's start or assign needs a routeDecisionId;+- the 30-per-hour limit;+- `jevClient`, `jevPick` and the backend `jevRoute`, which the voice router, recaps and devices+ still use.++The route reads its rules from the tab state that `routeContext` already returns. No new daemon action+or backend read is needed.++CLI help (`HELP` in `service.ts`):++- `route` gains the optional `kind` and the sentence "Candidates that break the owner's hard rules+ are left out; soft rules rank."+- `command` gains `rule.set` and `rule.remove`, including that `askedIn` is the owner's message.+- `status` notes that `rules` lists them.++## Mixing versions++| | Old backend (no rules) | New backend |+|---|---|---|+| **Old CLI** | today | It still asks Jev. The record is refused only when the pick breaks a hard rule, with a sentence asking the Lead to update or route again. Start and assign are enforced. |+| **New CLI** | No rules in the state, so routing is today's minus Jev. `rule.set` and `rule.remove` are refused by the strict schema, and the CLI reports "This Swarm's server does not support rules yet." | full |++The record keeps today's schema. `via: 'jev'` stays valid in it for old CLIs, and nothing new is added to+it, so the CLI's existing v1 retry is unchanged. A new CLI with a daemon that has not restarted still+works, because it no longer calls `routeJev`.++With no rules, the result is today's order, minus Jev's three-second call and minus the overrides Jev+caused.++## Tests++The tests are unit tests only. They never touch port 18473, `~/.harness`, `~/.claude`, `~/.codex` or+real tmux.++- `backend/src/superTabs/commands.test.ts`:+ - set, list and remove by the owner;+ - set and remove by the Lead with an owner message;+ - refused for the Lead without one, for the Lead quoting a non-owner message, for a collaborator, and+ for a non-Lead agent;+ - `agent.start`, `work.assign` and `route.record` refused for an agent that breaks each hard rule+ kind;+ - a person passes with a warning row;+ - `overrideReason` does not bypass a rule;+ - with no rules, today's behaviour (the existing suite is unchanged).+- `backend/integration/superTabs.test.ts`: on a real database, the Lead records a rule only by quoting a+ message the owner wrote in the tab.+- `route.spec.ts`:+ - each hard rule moves candidates to excluded;+ - a lifted effort for a `default` row under minEffort;+ - each soft rule changes only the order, never the set;+ - with no rules, the same order as today.+- `routeCommand.spec.ts` and `service.spec.ts`:+ - no Jev call is made (the injected `request` never sees `routeJev`, and service options have no+ `jev`);+ - the rules come from the tab state;+ - a hard rule leaves only allowed picks.++Commands, recorded in the PR:++- `cd backend && npm run typecheck && npx vitest run src/superTabs src/routes/superTabs && npm run test:super-tabs`+- `cd cli && npm run typecheck && npx vitest run src/superTabs src/lib/routeDecide src/lib/jev src/architecture.spec.ts && npm run test:super-tabs`+ (`test:super-tabs` holds `route.ts` and `routeCommand.ts` at 100%). No `src/core` or `src/services` file changes,+ so `test:core` does not apply.++## Lead skill wording (proposed, not applied)++> Routing follows the owner's rules. When the owner states a lasting rule in chat ("never Haiku",+> "only these machines", "at least high effort", "prefer Codex for UI", "reuse idle agents"),+> record it with `rule.set` and quote the owner's message in `askedIn`. Remove it with `rule.remove`+> when asked. When asked what the rules are, read `rules` in `status` and answer in the owner's+> words. The backend refuses starts and assignments that break a hard rule, so route again+> instead of overriding.++## Open questions for the Lead++1. **Lifting a `default`/`auto` effort to the minimum** instead of dropping the candidate. This keeps+ Codex's `default` row usable under "at least high". Proposed: lift.+2. **Recording `kind`.** It is not recorded in the decision log, which keeps the record schema+ unchanged. Proposed: not recorded.