Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat(swarm): a task can require machines or devices, and routing waits for them (#1829)

0xken1535e460f24609
diff --git a/backend/integration/superTabRead.test.ts b/backend/integration/superTabRead.test.ts
index 6523d7e76..d9aff4fce 100644
--- a/backend/integration/superTabRead.test.ts
+++ b/backend/integration/superTabRead.test.ts
@@ -309,6 +309,22 @@ describe('dormant groups on demand (design 4.5)', () => {
})
})
+describe('a dormant group\'s required machines', () => {
+ it('names to each reader only the machines that reader sees, in the dormant list and read by id', async () => {
+ const s = await scene((f, ids) => {
+ // Only an agent of the private project runs on 'secret-mac', so the outsider does not see that machine.
+ f.add('secret-harness', f.group('Secret 2', ids.secret), false, ownerActor, 'secret-mac', owner.sub)
+ f.edit(state => { state.conversations.find(c => c.id === ids.done)!.task = { goal: 'g', changes: 'c', constraints: 'k', owns: ['o'],
+ requires: { machines: ['secret-mac', 'host'] } } })
+ })
+ const requires = async (as: AuthUser) => [
+ (await get(`/api/super-tabs/${s.tabId}/groups?dormant=1`, as)).body.data.groups.find((g: { key: string }) => g.key === s.done).data.task.requires,
+ (await get(`/api/super-tabs/${s.tabId}/groups/${s.done}`, as)).body.data.group.data.task.requires]
+ expect(await requires(owner)).toEqual([{ machines: ['secret-mac', 'host'] }, { machines: ['secret-mac', 'host'] }])
+ expect(await requires(outsider)).toEqual([{ machines: ['host'], unseenMachines: 1 }, { machines: ['host'], unseenMachines: 1 }])
+ })
+})
+
describe('Swarm list and old routes (design 4.9, 4.11)', () => {
it('lists the caller\'s Swarms with their newest change', async () => {
const s = await scene()
diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.ts
index 60e4dcba4..a6e8bf73d 100644
--- a/backend/src/superTabs/commands.test.ts
+++ b/backend/src/superTabs/commands.test.ts
@@ -1384,6 +1384,100 @@ describe('the owner\'s rules', () => {
})
})
+describe('a task that requires a machine or a device', () => {
+ // 2026-10-27: a task to check a device plugged into one person's Mac was routed to another machine by policy order.
+ const task = { goal: 'Check the round device', changes: 'None', constraints: 'On the Mac it is plugged into', owns: ['devices'] }
+ const checks = [{ description: 'It answers.', independent: false }]
+ const requiring = (f: ReturnType<typeof routed>, requires: Record<string, unknown>, actor: Actor = owner) =>
+ f.run({ type: 'work.define', conversationId: 'lead', task: { ...task, requires }, checks } as Command, actor)
+ const startOn = (f: ReturnType<typeof routed>, machineId: string, actor: Actor, devices: string[] = []) => f.run({ type: 'agent.start', request: { conversationId: 'lead', machineId,
+ engine: 'claude', model: 'opus', effort: 'high', name: 'Builder', cwd: '/repo', worktree: true,
+ requirements: { memoryBytes: 1, diskBytes: 1, maxCpuPercent: 80, tools: [], devices, quotaRequired: false } }, ...via } as Command, actor, { contribution: f.contribution, ...decisionIn() })
+ const NOT_HERE = 'This task runs only on the machine it requires, and this is another machine.'
+
+ it('keeps the requirement on the task, without naming the machine in the brief', () => {
+ const f = routed()
+ requiring(f, { machines: ['machine'], devices: ['/dev/cu.usbmodem1'] })
+ expect(f.state.conversations[0]!.task!.requires).toEqual({ machines: ['machine'], devices: ['/dev/cu.usbmodem1'] })
+ expect(f.state.conversations[0]!.brief).not.toContain('machine')
+ })
+ it('takes only machines of the Swarm the setter can see, and at least one machine or device', () => {
+ const f = routed()
+ expect(() => requiring(f, { machines: ['nowhere'] })).toThrow('Name a machine of this Swarm')
+ expect(() => requiring(f, {})).toThrow()
+ expect(() => requiring(f, { machines: [] })).toThrow()
+ expect(() => requiring(f, { devices: ['dev/relative'] })).toThrow()
+ })
+ it('refuses an agent\'s start on another machine, even with an override reason, and starts on the required one', () => {
+ const f = routed()
+ requiring(f, { machines: ['machine'] })
+ expect(() => startOn(f, 'host', f.leadActor)).toThrow(expect.objectContaining({ code: 'REQUIREMENT_UNMET', status: 403, message: `${NOT_HERE} Route again.` }))
+ expect(startOn(f, 'machine', f.leadActor).result.startId).toBeTruthy()
+ })
+ it('refuses an agent\'s assignment of a member on another machine and a recorded pick there', () => {
+ const f = routed()
+ requiring(f, { machines: ['machine'] })
+ // The worker runs on 'host'.
+ expect(() => f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker, ...via }, f.leadActor, decisionIn())).toThrow(NOT_HERE)
+ expect(() => f.run({ type: 'route.record', conversationId: 'lead', decision: record({ candidates: [candidate('c0', { machineId: 'host' })] }) } as Command, f.leadActor, {}))
+ .toThrow(NOT_HERE)
+ expect(f.run({ type: 'route.record', conversationId: 'lead', decision: record({ candidates: [candidate('c0', { machineId: 'machine' })] }) } as Command, f.leadActor, {})
+ .result.routeDecisionId).toBeTruthy()
+ })
+ it('lets a person through with a warning that does not name the machine', () => {
+ const f = routed()
+ requiring(f, { machines: ['machine'] })
+ const effects = startOn(f, 'host', owner)
+ expect(effects.result.warnings).toEqual([NOT_HERE])
+ expect(effects.messages.map(m => m.text)).toContain(`owner started Builder anyway. ${NOT_HERE}`)
+ })
+ it('refuses an agent\'s start that does not ask its machine for the required devices', () => {
+ const f = routed()
+ requiring(f, { devices: ['/dev/cu.usbmodem1'] })
+ expect(() => startOn(f, 'machine', f.leadActor)).toThrow(expect.objectContaining({ code: 'REQUIREMENT_UNMET', message: expect.stringContaining('This task needs /dev/cu.usbmodem1') }))
+ expect(startOn(f, 'machine', f.leadActor, ['/dev/cu.usbmodem1']).result.startId).toBeTruthy()
+ })
+ it('refuses assigning a worker whose start never had its machine check the required device, with or without an override', () => {
+ const f = routed()
+ requiring(f, { devices: ['/dev/cu.usbmodem1'] })
+ const worker = f.state.agents.find(a => a.id === f.worker)!
+ const picked = { routeDecision: { id: 'd1', conversationId: 'lead', final: null, override: null, assignmentId: null, outcome: null,
+ record: record({ candidates: [candidate('c0', { kind: 'member', agentId: f.worker, machineId: 'host' })] }) } as unknown as RouteDecision }
+ const assign = (patch: Record<string, unknown>, context: Partial<CommandContext>) =>
+ f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker, ...patch } as Command, f.leadActor, context)
+ const refused = expect.objectContaining({ code: 'REQUIREMENT_UNMET', status: 403, message: expect.stringContaining('This task needs /dev/cu.usbmodem1') })
+ expect(() => assign({ routeDecisionId: 'd1' }, picked)).toThrow(refused)
+ expect(() => assign(via, decisionIn())).toThrow(refused)
+ expect(() => f.run({ type: 'route.record', conversationId: 'lead', decision: picked.routeDecision.record } as Command, f.leadActor, {})).toThrow(refused)
+ // A start that asked for other devices is no evidence either.
+ f.state.starts = [{ harnessId: worker.harnessId, request: { machineId: 'host', requirements: { devices: ['/dev/other'] } } } as never]
+ expect(() => assign({ routeDecisionId: 'd1' }, picked)).toThrow(refused)
+ f.state.starts = [{ harnessId: worker.harnessId, request: { machineId: 'host', requirements: { devices: ['/dev/cu.usbmodem1'] } } } as never]
+ expect(assign({ routeDecisionId: 'd1' }, picked).result.assignmentId).toBeTruthy()
+ })
+ it('lets a person assign a worker without device evidence, with a warning', () => {
+ const f = routed()
+ requiring(f, { devices: ['/dev/cu.usbmodem1'] })
+ const effects = f.run({ type: 'work.assign', conversationId: 'lead', agentId: f.worker })
+ expect(effects.result.warnings).toEqual([expect.stringContaining('This task needs /dev/cu.usbmodem1')])
+ })
+ it('counts a Mac\'s Harness Team account as that Mac', () => {
+ const f = routed()
+ teamMachine(f, 'owner', 'team')
+ f.state.machines!.find(m => m.machineId === 'team')!.hostMachineId = 'machine'
+ requiring(f, { machines: ['machine'] })
+ expect(startOn(f, 'team', f.leadActor).result.startId).toBeTruthy()
+ })
+ it('shows a reader who cannot see the machine only that the task waits for one', () => {
+ const f = routed()
+ requiring(f, { machines: ['machine', 'host'] })
+ expect(visibleState(f.state, owner).conversations[0]!.task!.requires).toEqual({ machines: ['machine', 'host'] })
+ // No machine record and no agent the reader sees runs there any more.
+ f.state.agents = f.state.agents.filter(a => a.machineId !== 'machine')
+ expect(visibleState(f.state, owner).conversations[0]!.task!.requires).toEqual({ machines: ['host'], unseenMachines: 1 })
+ })
+})
+
describe('the owner\'s rules in a Swarm of projects', () => {
// Backend v1.3.14: once the original 'lead' project is gone, every Lead rule.set failed NOT_FOUND.
const said = (patch: Record<string, unknown> = {}) => ({ askedIn: { author: { kind: 'person', id: 'owner', name: owner.email, membershipGeneration: 'tab' },
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index cfdfd84b9..c845ed611 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -3,12 +3,12 @@ import { assignAgentDisplayNames } from './agentNames.js'
import { z } from 'zod'
import {
activeWork, actorKey, agent, agentRole, appendPullRequestUrls, author, conversation, crossProjectActive, fail, isLeads, person, stableId, syncLeads, numberConversations, nextConversationNumber, renderWorkTask,
- finishWorker, requireWorkerDecisions, reviewing, swarmGridName, AGENT_ONLY,
- type Actor, type Agent, type Author, type CommandEffects, type Conversation, type SuperTabState,
+ finishWorker, requireWorkerDecisions, reviewing, seenMachineIds, swarmGridName, visibleState, AGENT_ONLY,
+ type Actor, type WorkTask, type Agent, type Author, type CommandEffects, type Conversation, type SuperTabState,
} 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 { agentTarget, askedInSchema, broken, MAX_RULES, RULE_MESSAGE_MS, ruleSchema, ruleTextSchema, startTarget, unmet, type RunTarget } from './rules.js'
import { MAX_ATTACHMENTS, type Attachment } from './attachments.js'
import { checkMentions, MAX_MENTIONS, type MentionTarget } from './mentions.js'
import { ANSWERED_NOTICE, answerDecision, askDecisions, checkAsker, decisionChoices, decisionQuestion, MAX_QUESTIONS, type DecisionTarget } from './decisions.js'
@@ -64,6 +64,9 @@ const check = z.object({ description: z.string().trim().min(1).max(1000), indepe
const task = z.object({
goal: z.string().trim().min(1).max(8000), changes: z.string().trim().min(1).max(8000),
constraints: z.string().trim().min(1).max(8000), owns: z.array(z.string().trim().min(1).max(4096)).min(1).max(40),
+ /** model.ts TaskRequirement; `unseenMachines` is only ever read back, never set. */
+ requires: z.object({ machines: z.array(id).min(1).max(20).optional(), devices: z.array(path).min(1).max(20).optional() }).strict()
+ .refine(r => r.machines || r.devices, 'Require at least one machine or device.').optional(),
}).strict()
export const commandSchema = z.discriminatedUnion('type', [
@@ -506,10 +509,26 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
/** The Mac a Harness Team account's machine is, for a machines rule naming the Mac (machines.ts teamStartRequest). */
const macOf = (id: string) => state.machines?.find(m => m.machineId === id)?.hostMachineId
const groupRules = (conversationId: string) => projectRules(state, groupProject(state, conversation(state, conversationId)).id)
+ /** A requirement names only machines its setter sees, so it never names one to a reader who could not (model.ts TaskRequirement). */
+ const requirable = (task: WorkTask | undefined) => {
+ const machines = task?.requires?.machines
+ if (!machines) return
+ const seen = seenMachineIds(visibleState(state, actor, context.now))
+ if (machines.some(m => !seen.has(m))) fail('MACHINE_UNKNOWN', 'Name a machine of this Swarm that you can see.', 400)
+ }
+ /** The owner's rules for the group's project, then the group's own requirement, each with its own code so a caller can tell
+ * an owner's rule from where the task can be done at all. */
+ const refusal = (target: RunTarget, conversationId: string): { code: string; why: string } | null => {
+ const rule = broken(groupRules(conversationId), target, machineName, macOf)
+ if (rule) return { code: 'RULE_BROKEN', why: rule }
+ const requirement = unmet(conversation(state, conversationId).task?.requires, target, macOf)
+ return requirement ? { code: 'REQUIREMENT_UNMET', why: requirement } : null
+ }
const ruled = (target: RunTarget, conversationId: string, done: string, personChose = false) => {
- const why = broken(groupRules(conversationId), target, machineName, macOf)
- if (!why) return
- if (actor.kind === 'agent' && !personChose) fail('RULE_BROKEN', `${why} Route again.`, 403)
+ const refused = refusal(target, conversationId)
+ if (!refused) return
+ const { code, why } = refused
+ if (actor.kind === 'agent' && !personChose) fail(code, `${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 })
}
@@ -1006,6 +1025,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
(actor.kind === 'agent' ? agentProjectId(state, agent(state, actor.agentId)) : 'lead'))
controls(state, actor, project.leadConversationId)
if (state.paused) fail('PAUSED', 'New work is paused in this Super Tab.')
+ requirable(command.task)
if (command.audience) {
// A private conversation is chat only: no task, checks or review, so private work never reaches other Leads.
if (command.task || command.checks.length || command.reviewOf || command.requesterId) fail('AUDIENCE_CHAT_ONLY', 'A private conversation is chat only.', 400)
@@ -1226,8 +1246,8 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
fail('SWARM_ENGINE', 'A Swarm agent runs only Claude Code or Codex.', 400)
}
// 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(groupRules(start.request.conversationId), startTarget(start.request), machineName, macOf)
- if (why) fail('RULE_BROKEN', `${why} This start was not launched. Route again.`, 403)
+ const why = actor.kind === 'agent' && !(start.routeDecisionId && context.routeDecision?.override?.by === 'person') && refusal(startTarget(start.request), start.request.conversationId)
+ if (why) fail(why.code, `${why.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) {
@@ -1603,6 +1623,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
controls(state, actor, command.conversationId)
const group = open(state, command.conversationId)
if (activeWork(group)) fail('WORK_ACTIVE', 'Finish or stop the current assignment before changing its acceptance checks.')
+ requirable(command.task)
if (group.assignment) {
const worker = state.agents.find(a => a.id === group.assignment!.agentId)
if (worker && !worker.workDecision && group.assignment.status !== 'lost') finishWorker(state, worker.id)
diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.ts
index a7cd6e92a..0f219b037 100644
--- a/backend/src/superTabs/model.ts
+++ b/backend/src/superTabs/model.ts
@@ -130,6 +130,25 @@ export interface WorkTask {
changes: string
constraints: string
owns: string[]
+ requires?: TaskRequirement
+}
+/** Where a task can be done at all (2026-10-27: a task to check a device plugged into one person's Mac was routed to another
+ * machine by policy order). `machines`: it runs only there, or on a Mac's Harness Team account of one of them. `devices`:
+ * full paths every start for it asks its machine to check (cli superTabs/capacity.ts). Never in the rendered brief, since
+ * a reader may not see the machine. A reader is handed only the machines they see, and how many others (`unseenMachines`). */
+export interface TaskRequirement { machines?: string[]; devices?: string[]; unseenMachines?: number }
+
+/** The machines a reader sees: listed in their visible state, or running an agent they see. */
+export const seenMachineIds = (visible: Pick<SuperTabState, 'machines' | 'agents'>): Set<string> =>
+ new Set([...(visible.machines ?? []).map(m => m.machineId), ...visible.agents.map(a => a.machineId)])
+
+/** [group] with its requirement as a reader who sees [seen] may read it. The same group read again gives the same result. */
+export function withSeenRequirement<T extends Pick<Conversation, 'task'>>(group: T, seen: ReadonlySet<string>): T {
+ const requires = group.task?.requires
+ if (!requires?.machines?.some(id => !seen.has(id))) return group
+ const machines = requires.machines.filter(id => seen.has(id))
+ return { ...group, task: { ...group.task!, requires: { ...requires, machines,
+ unseenMachines: (requires.unseenMachines ?? 0) + requires.machines.length - machines.length } } }
}
export function renderWorkTask(task: WorkTask): string {
@@ -517,5 +536,7 @@ export function visibleState(state: SuperTabState, actor: Actor, now = Date.now(
else delete target.roleId
}
if (actor.kind !== 'person' || actor.userId !== state.ownerId) visible.invitations = []
+ const seen = seenMachineIds(visible)
+ visible.conversations = visible.conversations.map(c => withSeenRequirement(c, seen))
return visible
}
diff --git a/backend/src/superTabs/read/changes.test.ts b/backend/src/superTabs/read/changes.test.ts
index d07e06c79..b4ce7095e 100644
--- a/backend/src/superTabs/read/changes.test.ts
+++ b/backend/src/superTabs/read/changes.test.ts
@@ -115,4 +115,19 @@ describe('changes since a cursor (design 4.4)', () => {
expect(receive(fresh, changed, peer).progress).toEqual([{ key: 'lead', version: R + 1, changedAt: LATER,
data: { since: 1, summarizedFloor: 0, summarized: {}, requestedFloor: 0, requested: {}, requestedAt: null } }])
})
+
+ it('hands a reader only the required machines they see, whole and in changes', () => {
+ const { s } = scene()
+ // Only an agent of the private project runs on 'secret-mac', so the peer does not see that machine.
+ s.add('secret-harness', s.secretGroup, false, owner, 'secret-mac')
+ s.run({ type: 'work.define', conversationId: s.done, task: { goal: 'Check the device', changes: 'None', constraints: 'None', owns: ['devices'],
+ requires: { machines: ['secret-mac', 'mac'] } }, checks: [{ description: 'It answers.', independent: false }] })
+ const fresh = store.split(s.state, { tabId: 'tab', version: R, now: NOW })
+ const requires = (groups: Array<{ key: string }>) => (groups.find(g => g.key === s.done) as unknown as { data: { task: { requires: unknown } } }).data.task.requires
+ expect(requires(readerView(fresh, owner, LATER, { teamMachines: [] }).parts.groups)).toEqual({ machines: ['secret-mac', 'mac'] })
+ expect(requires(readerView(fresh, peer, LATER, { teamMachines: [] }).parts.groups)).toEqual({ machines: ['mac'], unseenMachines: 1 })
+ const changed = [write(fresh, 'groups', s.done, () => {})]
+ expect(requires(receive(fresh, changed, peer).groups)).toEqual({ machines: ['mac'], unseenMachines: 1 })
+ expect(requires(receive(fresh, changed, owner).groups)).toEqual({ machines: ['secret-mac', 'mac'] })
+ })
})
diff --git a/backend/src/superTabs/read/changes.ts b/backend/src/superTabs/read/changes.ts
index 8101a8283..f81c157bb 100644
--- a/backend/src/superTabs/read/changes.ts
+++ b/backend/src/superTabs/read/changes.ts
@@ -7,7 +7,7 @@ import type { Actor, Agent, AgentStart, Conversation } from '../model.js'
import { canReadAgent, canReadGroup } from '../projects.js'
import { knownKind, type MachineData, type Part } from '../parts/index.js'
import type { ChangesDelta, DormantStub, Tombstone } from './contract.js'
-import { envelope, progressView, visibleGroupView, type ReaderView } from './views.js'
+import { envelope, progressView, seenIn, visibleGroupView, type ReaderView } from './views.js'
export type PartChanges = Pick<ChangesDelta, 'head' | 'members' | 'agents' | 'groups' | 'machines' | 'starts' | 'progress'>
@@ -23,6 +23,7 @@ export function changesFor(view: ReaderView, changed: Part[], actor: Actor): Par
const groupOf = (id: string) => state.conversations.find(c => c.id === id)
?? changed.find(p => p.kind === 'group' && p.key === id)?.data as Conversation | undefined
const visibleAgents = new Set(seen.agents.map(a => a.key))
+ const seenMachines = seenIn(seen)
const out: PartChanges = { head: null, members: [], agents: [], groups: [], machines: [], starts: [], progress: [] }
for (const part of changed) {
switch (part.kind) {
@@ -45,7 +46,7 @@ export function changesFor(view: ReaderView, changed: Part[], actor: Actor): Par
if (part.data && !knownKind(part.data as Conversation)) break
if (part.deleted || part.dormant) { if (groupReadable(part.data as Conversation)) out.groups.push(part.deleted ? stub(part) : dormantStub(part)) }
// Sent from the changed part itself: the reader's view may hold only a conversation's light fields (parts/light.ts).
- else if (groupReadable(part.data as Conversation)) out.groups.push(envelope(part, visibleGroupView(part.data as Conversation, visibleAgents)))
+ else if (groupReadable(part.data as Conversation)) out.groups.push(envelope(part, visibleGroupView(part.data as Conversation, visibleAgents, seenMachines)))
break
}
case 'machine': {
diff --git a/backend/src/superTabs/read/service.ts b/backend/src/superTabs/read/service.ts
index 516132497..5a678447d 100644
--- a/backend/src/superTabs/read/service.ts
+++ b/backend/src/superTabs/read/service.ts
@@ -5,7 +5,7 @@
import type { Prisma, PrismaClient } from '@prisma/client'
import type { AuthUser } from '../../lib/ssoAuth.js'
import { isTeamSession, TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE } from '../../lib/teamSession.js'
-import { author, fail, isLeads, visibleState, type Actor, type AgentStart } from '../model.js'
+import { author, fail, isLeads, seenMachineIds, visibleState, type Actor, type AgentStart } from '../model.js'
import { mentionsWaiting } from '../mentions.js'
import { decisionsWaiting } from '../decisions.js'
import { transaction, type SuperTabStore } from '../store.js'
@@ -21,7 +21,7 @@ import { WEEK_MS } from '../leaderboard/week.js'
import { READ_FORMAT, SWARM_MIGRATING, type Changes, type DormantGroups, type FirstLoad, type OneGroup, type SwarmList } from './contract.js'
import { cursorFor, readCursor } from './cursor.js'
import { changesFor } from './changes.js'
-import { envelope, groupView, readerView, type ReaderView } from './views.js'
+import { envelope, groupView, readerView, seenIn, type ReaderView } from './views.js'
import { decodeDormantPage, encodeDormantPage } from './dormantPage.js'
type Transaction = Prisma.TransactionClient
@@ -77,7 +77,8 @@ export class SwarmReads {
const before = page.before ? decodeDormantPage(page.before) : undefined
const rows = await parts.loadDormant(tx, tabId, { ...(page.projectId ? { projectId: page.projectId } : {}), ...(before ? { before } : {}) })
const readable = rows.filter(p => { try { return canReadGroup(state, actor, p.data!) } catch { return false } })
- return { groups: readable.map(p => envelope(p, groupView({ ...p.data!, dormant: true }))),
+ const seen = readable.some(p => p.data!.task?.requires) ? seenMachineIds(visibleState(state, actor, this.now())) : new Set<string>()
+ return { groups: readable.map(p => envelope(p, groupView({ ...p.data!, dormant: true }, seen))),
next: rows.length === 50 ? encodeDormantPage(rows.at(-1)!) : null }
})
}
@@ -90,7 +91,9 @@ export class SwarmReads {
if (active) return { group: active }
// A dormant group is in no whole-Swarm view; it passes the same read check as on the dormant list.
const dormant = loaded.groups.find(g => g.key === conversationId && g.dormant)
- if (dormant && canReadGroup(view.state, actor, dormant.data!)) return { group: envelope(dormant, groupView({ ...dormant.data!, dormant: true })) }
+ if (dormant && canReadGroup(view.state, actor, dormant.data!)) {
+ return { group: envelope(dormant, groupView({ ...dormant.data!, dormant: true }, seenIn(view.parts))) }
+ }
return fail('NOT_FOUND', 'This conversation is unavailable.', 404)
})
}
diff --git a/backend/src/superTabs/read/views.ts b/backend/src/superTabs/read/views.ts
index 5e8f8477b..01e07320a 100644
--- a/backend/src/superTabs/read/views.ts
+++ b/backend/src/superTabs/read/views.ts
@@ -3,7 +3,7 @@
* plus the private-conversation check, each record sent in its part's envelope. Time-based and cross-part values go only
* in `derived`, so a part never changes without a new version (Lead's ruling).
*/
-import { isLeads, visibleState, type Actor, type Agent, type Conversation, type SuperTabState } from '../model.js'
+import { isLeads, seenMachineIds, visibleState, withSeenRequirement, type Actor, type Agent, type Conversation, type SuperTabState } from '../model.js'
import { machineSlots, teamAccountRequired, teamWorkRefusal, type ContributedMachine } from '../machines.js'
import * as store from '../parts/index.js'
import type { Part, SwarmParts } from '../parts/index.js'
@@ -44,16 +44,21 @@ export const envelope = <T>(part: Pick<Part, 'key' | 'version' | 'changedAt'>, d
/** A group as readers get it: its message counter, a dormant flag only when dormant, never the store's bookkeeping or the
* leaderboard's (the leaderboard read sums it). */
-export function groupView(group: Conversation): GroupView {
- const { messageSeq, reportSeq: _report, lastActivityAt: _activity, ledger: _ledger, dormant, audience, ...rest } = group
+export function groupView(group: Conversation, seenMachines: ReadonlySet<string>): GroupView {
+ const { messageSeq, reportSeq: _report, lastActivityAt: _activity, ledger: _ledger, dormant, audience, ...rest } = withSeenRequirement(group, seenMachines)
return { ...rest, messageSeq: messageSeq ?? 0, ...(dormant ? { dormant: true as const } : {}), ...(audience ? { audience } : {}) }
}
-/** A conversation's whole data as the reader may see it: the Leads conversation lists only the agents the reader can see. */
-export function visibleGroupView(group: Conversation, visibleAgents: ReadonlySet<string>): GroupView {
- return groupView(isLeads(group) ? { ...group, agentIds: group.agentIds.filter(id => visibleAgents.has(id)) } : group)
+/** A conversation's whole data as the reader may see it: the Leads conversation lists only the agents the reader can see, and a
+ * task's requirement only the machines they see. */
+export function visibleGroupView(group: Conversation, visibleAgents: ReadonlySet<string>, seenMachines: ReadonlySet<string>): GroupView {
+ return groupView(isLeads(group) ? { ...group, agentIds: group.agentIds.filter(id => visibleAgents.has(id)) } : group, seenMachines)
}
+/** The machines a reader's view shows them: listed, or running an agent they see (model.ts seenMachineIds). */
+export const seenIn = (parts: ReaderView['parts']): Set<string> =>
+ new Set([...parts.machines.map(m => m.key), ...parts.agents.map(a => a.data.machineId)])
+
export function agentView(agent: Agent): AgentView {
const { downNamed: _named, downSince: _since, limitedUntil: _limit, roleId: _role, ...rest } = agent
return rest
@@ -69,14 +74,14 @@ export function readerView(parts: SwarmParts, actor: Actor, now: number, extras:
const head = Object.fromEntries(HEAD_FIELDS.filter(field => visible[field] !== undefined).map(field => [field, visible[field]])) as HeadView
if (head.projects) head.projects = head.projects.map(({ progress: _progress, ...project }) => project)
head.invitations = visible.invitations.filter(i => readable.has(i.conversationId))
- const projects = new Set((visible.projects ?? []).map(p => p.id))
+ const projects = new Set((visible.projects ?? []).map(p => p.id)), seen = seenMachineIds(visible)
return {
state,
parts: {
head: envelope(parts.head, head),
members: parts.members.filter(m => !m.deleted).map(m => envelope(m, m.data!)),
agents: visible.agents.map(a => envelope(agentPart(a.id), agentView(state.agents.find(s => s.id === a.id)!))),
- groups: groups.map(g => envelope(groupPart(g.id), groupView(g))),
+ groups: groups.map(g => envelope(groupPart(g.id), groupView(g, seen))),
machines: (visible.machines ?? []).map(m => envelope(machinePart(m.machineId), m)),
starts: (visible.starts ?? []).filter(s => readable.has(s.request.conversationId)).map(s => envelope(startPart(s.id), s)),
progress: parts.progress.filter(p => !p.deleted && projects.has(p.key)).map(p => envelope(p, progressView(p.data!))),
diff --git a/backend/src/superTabs/rules.ts b/backend/src/superTabs/rules.ts
index 679059587..dd03890ff 100644
--- a/backend/src/superTabs/rules.ts
+++ b/backend/src/superTabs/rules.ts
@@ -3,7 +3,7 @@
* 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'
+import type { Agent, SuperTabState, TaskRequirement } from './model.js'
const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)
const engine = z.enum(['claude', 'codex'])
@@ -35,8 +35,10 @@ export interface SwarmRule {
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 }
+/** What would run: a start request, an agent's configuration, or a routed pick. Null when not known. `devices` are those its
+ * machine checked are connected: a start's, or the start that launched an agent; absent only for a new agent's pick, whose
+ * start is checked when it is made. */
+export interface RunTarget { machineId: string; engine: string; model: string | null; effort: string | null; devices?: string[] }
const ENGINE: Record<string, string> = { claude: 'Claude', codex: 'Codex' }
/** `default` and `auto` say nothing about the effort, so they never meet a minimum. */
@@ -69,14 +71,30 @@ export function broken(rules: SwarmRule[] | undefined, target: RunTarget, machin
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 })
+/** Said wherever the requirement's machines are not: it never names them, since a reader may not see them. */
+export const ANOTHER_MACHINE = 'This task runs only on the machine it requires, and this is another machine.'
+
+/** Why the task's requirement rules the target out, or null when it does not (model.ts TaskRequirement). A Mac's Harness Team
+ * account is that Mac, as for a machines rule. No machine reports its devices to the server, so the only evidence of a device
+ * is a start that asked its machine to check it: an agent without such a start is refused (review of #1829). */
+export function unmet(requires: TaskRequirement | undefined, target: RunTarget, macOf: (id: string) => string | undefined = () => undefined): string | null {
+ const mac = macOf(target.machineId)
+ if (requires?.machines && !requires.machines.includes(target.machineId) && !(mac && requires.machines.includes(mac))) return ANOTHER_MACHINE
+ const missing = target.devices ? (requires?.devices ?? []).filter(d => !target.devices!.includes(d)) : []
+ const one = missing.length === 1
+ return missing.length ? `This task needs ${missing.join(', ')}: only an agent whose start names ${one ? 'it' : 'them'} in its required devices, so its machine checks ${one ? 'it is' : 'they are'} connected, may take it.` : null
+}
+
+export const startTarget = (request: { machineId: string; engine: string; model?: string; effort?: string; requirements?: { devices: string[] } }): RunTarget =>
+ ({ machineId: request.machineId, engine: request.engine, model: request.model ?? null, effort: request.effort ?? null,
+ ...(request.requirements ? { devices: request.requirements.devices } : {}) })
/** 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
+ const start = state.starts?.find(s => s.harnessId === worker.harnessId && s.request.machineId === worker.machineId)
+ const launched = start?.request.effort
return { machineId: worker.machineId, engine: worker.configuration.engine, model: worker.configuration.model,
- effort: reported && reported !== 'auto' ? reported : launched ?? reported }
+ effort: reported && reported !== 'auto' ? reported : launched ?? reported, devices: start?.request.requirements?.devices ?? [] }
}
diff --git a/cli/src/superTabs/planInput.spec.ts b/cli/src/superTabs/planInput.spec.ts
index eaebcc1aa..6d2e4ff76 100644
--- a/cli/src/superTabs/planInput.spec.ts
+++ b/cli/src/superTabs/planInput.spec.ts
@@ -55,6 +55,22 @@ describe('planSetup', () => {
expect(taskOf(s, 't1').machines).toEqual(['m1-team'])
})
+ it('keeps a task that requires a machine to that machine, or its Mac\'s team account, as the route does', () => {
+ // 2026-10-27: a task to check a device plugged into one person's Mac went to another machine by policy order.
+ const requires = (r: Json) => ({ task: { goal: 'g', changes: 'c', constraints: 'k', owns: ['o'], requires: r } })
+ const s = setup(state({ projects, machines: mac(), conversations: [group('r1', requires({ machines: ['m2'] })),
+ group('r2', { projectId: 'p2', ...requires({ machines: ['m1'] }) }), group('r3', requires({ machines: [], unseenMachines: 1 })), group('free')] }))
+ expect(taskOf(s, 'r1').machines).toEqual(['m2'])
+ expect(taskOf(s, 'r2').machines).toEqual(['m1-team'])
+ expect(taskOf(s, 'r3').machines).toEqual([])
+ expect(taskOf(s, 'free').machines).toEqual(['m1', 'm2'])
+ })
+
+ it('offers no machine to a task that requires a device, since no machine reports its devices to the plan', () => {
+ const s = setup(state({ conversations: [group('d1', { task: { goal: 'g', changes: 'c', constraints: 'k', owns: ['o'], requires: { devices: ['/dev/cu.usbmodem1'] } } })] }))
+ expect(taskOf(s, 'd1').machines).toEqual([])
+ })
+
it('offers a Mac\'s own projects on the Mac and a teammate\'s in its team account, never both', () => {
const s = setup(state({ projects, machines: mac(), conversations: [group('o1', { projectId: 'p1' }), group('t1', { projectId: 'p2' })] }))
expect(taskOf(s, 'o1').machines).toEqual(['m1', 'm2'])
diff --git a/cli/src/superTabs/planInput.ts b/cli/src/superTabs/planInput.ts
index 5d8125ee3..ee20bb72c 100644
--- a/cli/src/superTabs/planInput.ts
+++ b/cli/src/superTabs/planInput.ts
@@ -5,7 +5,7 @@
* (routeCommand.ts), so the plan never offers what the route would refuse. Only new agents are planned, not idle members. */
import { requiredToolReason, startRequirements } from './capacity.js'
import { API_BUILDERS, breaks, floorFor, KIND_WORD, liftEffort, quotaOf2, SIZES, type Assessment, type Level, type Policy, type Size, type SwarmRule } from './route.js'
-import { LOCAL_FRESH_MS, OFFLINE, servedModels, STALLED, stalled, takesBuilder, unreadyPool } from './routeCommand.js'
+import { LOCAL_FRESH_MS, OFFLINE, servedModels, STALLED, stalled, takesBuilder, taskRequirement, unreadyPool } from './routeCommand.js'
import { identifier, object } from './wire.js'
type Json = Record<string, unknown>
@@ -168,6 +168,9 @@ export function planSetup(input: { state: Json; policy: Policy; leadId: string;
const teamPool = list(state.machines).find(m => m.machineId === team)
return teamPool && list(state.machines).some(m => m.machineId === mac) ? [projectOwner === teamPool.contributorId ? team : mac] : []
}))
+ // The group's own requirement, as the route reads it. A required device rules out every machine here: a machine reports
+ // its devices only to a capacity probe the route makes, never in the reading the plan has.
+ const required = taskRequirement(c)
const allowed = [...pools].filter(([machineId, pool]) => {
const repository = object(project?.repository)
const teamWork = object(pool.teamWork)
@@ -177,6 +180,7 @@ export function planSetup(input: { state: Json; policy: Policy; leadId: string;
&& !(pool.scope !== 'swarm' && projectId !== 'lead')
&& !(pool.scope === 'swarm' && repository.machineId !== machineId && typeof repository.repositoryUrl !== 'string')
&& !breaks(rules.filter(r => r.rule.kind === 'machines'), { machineId, engine: '', model: '', effort: '' })
+ && (!required.machines || required.machines.has(machineId) || required.machines.has(macOf.get(machineId) ?? '')) && !required.devices.length
}).map(([machineId]) => machineId)
const modelRules = rules.filter(r => r.rule.kind !== 'machines')
const allowedModels = Object.entries(rows).filter(([rowId, row]) => !(review && gridRows.has(rowId))
diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.ts
index bca9cb350..eaefb1fcd 100644
--- a/cli/src/superTabs/routeCommand.spec.ts
+++ b/cli/src/superTabs/routeCommand.spec.ts
@@ -931,6 +931,91 @@ describe('routing contributed capacity', () => {
})
})
+ describe('a task that requires a machine', () => {
+ // 2026-10-27: a task to check a device plugged into one person's Mac went to another machine by policy order.
+ const two = (diego: (p: any) => void = () => {}) => {
+ const other = { ...healthy(), machineId: 'm3', name: 'Diego Mac', observation: { ...healthy().observation, runningHarnessIds: [] } }
+ diego(other)
+ return [healthy(), other]
+ }
+ const requiring = (requires: Record<string, unknown>) => {
+ const groups = conversations()
+ Object.assign(groups[1]!, { task: { goal: 'Check the device', changes: 'None', constraints: 'None', owns: ['devices'], requires } })
+ return groups
+ }
+ async function route(machines: unknown[], requires: Record<string, unknown>, members = true) {
+ const s = scoped({ context: { ok: true, value: { agentId: 'lead', tab: { state: { id: 'tab', agents: members ? agents : [agents[1]], conversations: requiring(requires), machines } },
+ policy: { policy, warnings: [] }, machines: [] } } })
+ return { answer: await routeTask(input, s, where, opener()), s }
+ }
+ it('offers only the required machine and says why every other one is left out', async () => {
+ const { answer, s } = await route(two(), { machines: ['m3'] })
+ expect(answer).toMatchObject({ ok: true, pick: { machineId: 'm3' } })
+ expect(recorded(s).command.decision.candidates.every((c: { machineId: string }) => c.machineId === 'm3')).toBe(true)
+ expect(recorded(s).command.decision.excluded).toEqual(expect.arrayContaining([
+ { title: 'Multiply · Claude sonnet medium · Contributed laptop', reason: 'This task runs only on the machine it requires.' },
+ { title: 'New agent · Claude opus high · Contributed laptop', reason: 'This task runs only on the machine it requires.' }]))
+ })
+ it('waits while the required machine has no free slot, then routes there', async () => {
+ const full = await route(two(p => { p.availableSlots = 0 }), { machines: ['m3'] })
+ expect(full.answer).toMatchObject({ error: 'NO_CANDIDATE', waiting: true,
+ detail: 'This task waits for the machine it requires; route it again once that machine can take it.' })
+ expect(full.s.mock.calls.some(c => c[0].action === 'command')).toBe(false)
+ const free = await route(two(p => { p.availableSlots = 1 }), { machines: ['m3'] })
+ expect(free.answer).toMatchObject({ ok: true, pick: { machineId: 'm3' } })
+ })
+ it('waits, offering nothing, for a required machine the Lead cannot see', async () => {
+ const { answer } = await route(two(), { machines: [], unseenMachines: 1 })
+ expect(answer).toMatchObject({ error: 'NO_CANDIDATE', waiting: true })
+ expect((answer.excluded as Array<{ reason: string }>).every(e => e.reason === 'This task runs only on the machine it requires.')).toBe(true)
+ })
+ it('counts a Mac\'s Harness Team account as that Mac', async () => {
+ const team = { ...healthy(), machineId: 't3', name: 'Diego Mac', hostMachineId: 'm3', contributorId: 'owner', observation: { ...healthy().observation, runningHarnessIds: [] } }
+ const { answer } = await route([healthy(), team], { machines: ['m3'] }, false)
+ expect(answer).toMatchObject({ ok: true, pick: { machineId: 't3' } })
+ })
+ it('keeps routing a task without a requirement as before', async () => {
+ const { answer } = await route(two(), undefined as never)
+ expect(answer).toMatchObject({ ok: true })
+ })
+ })
+ describe('a task that requires a device', () => {
+ const requiring = (starts: unknown[] = []) => {
+ const groups = conversations()
+ Object.assign(groups[1]!, { task: { goal: 'g', changes: 'c', constraints: 'k', owns: ['o'], requires: { devices: ['/dev/cu.usbmodem1'] } } })
+ return { revision: 3, state: { id: 'tab', agents, conversations: groups, starts } }
+ }
+ it('waits when no machine has the device connected', async () => {
+ const answer = await routeTask(input, scoped({ tab: requiring() }), where as never, opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [] })), () => 'op')
+ expect(answer).toMatchObject({ error: 'NO_CANDIDATE', waiting: true,
+ detail: 'This task waits for the machine it requires; route it again once that machine can take it.' })
+ })
+ it('offers a member only when its own start had its machine check the device, as the server requires', async () => {
+ const connected = opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], devices: { '/dev/cu.usbmodem1': true } }))
+ const members = async (starts: unknown[]) => {
+ const s = scoped({ tab: requiring(starts) })
+ await routeTask(input, s, where as never, connected, () => 'op')
+ return recorded(s).command.decision
+ }
+ const unchecked = await members([])
+ expect(unchecked.candidates.some((c: { kind: string }) => c.kind === 'member')).toBe(false)
+ expect(unchecked.excluded).toEqual(expect.arrayContaining([{ title: 'Multiply · Claude sonnet medium · remote-1',
+ reason: 'Its start did not have its machine check the device this task requires. Start a new agent for it.' }]))
+ const checked = await members([{ harnessId: 'h1', request: { machineId: 'm1', requirements: { devices: ['/dev/cu.usbmodem1'] } } }])
+ expect(checked.candidates.some((c: { kind: string }) => c.kind === 'member')).toBe(true)
+ })
+ })
+ it('asks the machine for the devices the group\'s task requires, beside those the Lead names', async () => {
+ const groups = conversations()
+ Object.assign(groups[1]!, { task: { goal: 'g', changes: 'c', constraints: 'k', owns: ['o'], requires: { devices: ['/dev/cu.usbmodem1'] } } })
+ const s = scoped({ tab: { revision: 3, state: { id: 'tab', agents, conversations: groups } } })
+ const make = opener(id => daemon(id, { devices: { '/dev/cu.usbmodem1': id === 'm2', '/dev/ttyUSB0': true } }))
+ const answer = await routeTask({ ...input, assessment: { ...input.assessment, needs: { devices: ['/dev/ttyUSB0'] } } }, s, where as never, make, () => 'op')
+ expect(answer).toMatchObject({ ok: true, pick: { machineId: 'm2' } })
+ const hint = JSON.parse(/start OPERATION_ID (\{.*\}), then/.exec(answer.next as string)![1]!)
+ expect(hint.requirements.devices).toEqual(['/dev/ttyUSB0', '/dev/cu.usbmodem1'])
+ })
+
it.each([
['stale', (p: any) => { p.observation.receivedAt = 0 }],
['paused', (p: any) => { p.paused = true }],
diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.ts
index c29bd600a..cd4a1e64b 100644
--- a/cli/src/superTabs/routeCommand.ts
+++ b/cli/src/superTabs/routeCommand.ts
@@ -29,6 +29,19 @@ const EXHAUSTED_WINDOW = 'The subscription has an exhausted usage window. Wait f
export const NO_SWARM_AGENTS_ON: readonly string[] = ['Windows']
const ENGINE_NAME: Record<string, string> = { claude: 'Claude Code', codex: 'Codex' }
const NO_PUSH = "This machine's git login cannot push to the project repository. Its owner can sign in to GitHub there (gh auth login, then gh auth setup-git)."
+/** Said of a candidate where the task cannot be done: it never names the required machine, which the Lead may not see. */
+export const ELSEWHERE = 'This task runs only on the machine it requires.'
+const UNCHECKED_DEVICE = 'Its start did not have its machine check the device this task requires. Start a new agent for it.'
+const WAITING = 'This task waits for the machine it requires; route it again once that machine can take it.'
+/** What a group's task requires of where it runs (backend superTabs/model.ts TaskRequirement): the machines it runs on, null
+ * when it names none, and the devices every start for it asks its machine to check. A Lead who does not see a required
+ * machine reads only that there is one, so the set may be empty and still require. */
+export function taskRequirement(group: Json): { machines: Set<string> | null; devices: string[] } {
+ const requires = object(object(group.task).requires)
+ const strings = (value: unknown) => Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : []
+ const unseen = finite(requires.unseenMachines) && requires.unseenMachines > 0
+ return { machines: Array.isArray(requires.machines) || unseen ? new Set(strings(requires.machines)) : null, devices: strings(requires.devices) }
+}
export const STALLED = 'Its last 2 starts on this machine started no agent (they failed or were never picked up), so it is left out until a start there succeeds. Its owner can check the machine.'
/** What a machine says it cannot do for this task (#229 v1 routing): `all` keeps out its new agents, `engines` those of an
* engine, `push` its new agents and members alike. Only a known failure is said; anything unknown says nothing. */
@@ -163,6 +176,8 @@ export async function routeTask(input: { tabId: string; conversationId: string;
const group = conversations.find(c => c.id === input.conversationId)
if (!group) return { error: 'NOT_FOUND', detail: 'No such group in this Super Tab.' }
if (group.leadId !== value.agentId) return { error: 'LEAD_REQUIRED', detail: 'Only the Lead of this group routes its work.' }
+ const required = taskRequirement(group)
+ if (required.devices.length) assessment = { ...assessment, needs: { ...assessment.needs, devices: [...new Set([...assessment.needs.devices, ...required.devices])] } }
const projectId = String(group.projectId ?? 'lead')
const project = list(state.projects).find(p => p.id === projectId)
// The group's Lead and the tab Lead coordinate; neither is a worker candidate even when idle.
@@ -253,6 +268,20 @@ export async function routeTask(input: { tabId: string; conversationId: string;
refusals: [...p.refusals, ...limited(p.agentId), ...lostTask(p.agentId)],
earlier: ended.filter(e => e.agentId === p.agentId).reverse().slice(0, 3).map(e => ({ group: e.group, outcome: e.outcome })) } : p)
probes.push(...localProbes(state, policy, probes, assessment, review))
+ // A Mac's Harness Team account is that Mac, as for the owner's machines rule.
+ const outside = (machineId: string) => !!required.machines && !required.machines.has(machineId) && !required.machines.has(macOf.get(machineId) ?? '')
+ // The server takes a member for a task that requires a device only when the start that launched it had its machine check
+ // that device (backend superTabs/rules.ts unmet): no machine reports its devices to it (review of #1829).
+ const checked = (agentId: string | undefined) => {
+ const member = members.find(m => m.id === agentId)
+ const start = list(state.starts).find(s => s.harnessId === member?.harnessId && object(s.request).machineId === member?.machineId)
+ const devices = object(object(start?.request).requirements).devices
+ return required.devices.every(d => Array.isArray(devices) && devices.includes(d))
+ }
+ for (const [i, p] of probes.entries()) {
+ const refusals = [...(outside(p.machineId) ? [ELSEWHERE] : []), ...(p.kind === 'member' && !checked(p.agentId) ? [UNCHECKED_DEVICE] : [])]
+ if (refusals.length) probes[i] = { ...p, refusals: [...p.refusals, ...refusals] }
+ }
// 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)
@@ -264,7 +293,8 @@ export async function routeTask(input: { tabId: string; conversationId: string;
const avoid = failedOn && failedEngine ? [...new Set([`${failedOn}:${failedEngine}`,
...probes.filter(p => p.machineId === failedOn && p.engine === failedEngine && !p.gridModel).map(accountOf)])] : []
const choice = choose(probes, policy, assessment, Date.now(), working, rules, heldLocalModels(state), avoid)
- if ('error' in choice) return choice
+ // The task stays in the Lead's queue rather than going where it cannot be done.
+ if ('error' in choice) return required.machines || required.devices.length ? { ...choice, waiting: true, detail: WAITING } : choice
const verdict = decide(choice)
const operationId = `route-${newId()}`
const record = (v1: boolean) => scoped({ action: 'command', operationId,
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index 9eac00cd7..1864d16c6 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -43,7 +43,7 @@ const HELP = {
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. On Custom skills, add "roleId" to the start request to start the agent in that role of its kind (a builder or reviewer role from status); without it the agent takes the first role of its kind. 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","kind":"optional word such as ui or docs","local":"optional true, only when a person asked for a local model","model":"optional: the model a person named, in their words; only it is offered","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}. size is how long the work runs: small about 20 minutes, medium about an hour, large about three hours. Candidates that break the owner\'s hard rules are left out, and so are machines that cannot take a teammate\'s project: it runs only on Team machines (a Mac\'s Harness Team account whose privacy check passed, or a machine used only for agents), and the route says why the others were left out. Soft rules (a preferred engine for the kind, idle agents first) rank the rest. A pick on a model served on the Swarm\'s grid starts with gridModel and gridName in place of model and effort. Start or assign 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","local":"optional true, only when a person asked for a local model","model":"optional: the model a person named, in their words; only it is offered","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}. size is how long the work runs: small about 20 minutes, medium about an hour, large about three hours. Candidates that break the owner\'s hard rules are left out, and so are machines that cannot take a teammate\'s project: it runs only on Team machines (a Mac\'s Harness Team account whose privacy check passed, or a machine used only for agents), and the route says why the others were left out. Soft rules (a preferred engine for the kind, idle agents first) rank the rest. A group whose task requires machines or devices (task "requires":{"machines":["MACHINE"],"devices":["/dev/…"]}, set with conversation.create or work.define) is offered only those machines; while none can take it the route answers NO_CANDIDATE with "waiting":true, so keep it queued and route it again later. A pick on a model served on the Swarm\'s grid starts with gridModel and gridName in place of model and effort. Start or assign 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.',
screen: 'screen AGENT [--scrollback N]: read a worker\'s terminal as plain text, with up to 200 lines of scrollback. Only its project\'s Lead may. Use it when a worker seems stuck.',
type: 'type AGENT [TEXT] [--key K]...: type text, then keys (Enter, Esc, Tab, Up, Down, Left, Right, Ctrl-C, 0-9), into a worker\'s terminal. Answer prompts within its task; ask the owner before approving anything risky.',
capacity: 'capacity MACHINE_ID JSON: inspect machine, engine and quota headroom. JSON uses the start request fields below. Unknown allowances are not reported as free tokens.',