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.

Batch T: Codex Buddy sandbox (#2087), skills fail fast (#2096), WebSocket 1a follow-up (#2104), WebSocket 1b (#2107), cost records (#2106) (#2119)

0xken15795b302dfe2e
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bde056959..ce46e1770 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -184,6 +184,7 @@ jobs:
/mobile/pubspec.lock
/backend/src/lib/communityContract.ts
/backend/src/lib/hubMetricsContract.ts
+ /backend/src/superTabs/buddyContract.ts
/mobile/lib/p2p/terminal_p2p_plugin.dart
/mobile/lib/p2p/terminal_p2p_link.dart
/mobile/lib/p2p/terminal_p2p_policy.dart
diff --git a/backend/integration/superTabCosts.test.ts b/backend/integration/superTabCosts.test.ts
new file mode 100644
index 000000000..9f9890745
--- /dev/null
+++ b/backend/integration/superTabCosts.test.ts
@@ -0,0 +1,232 @@
+import { randomUUID } from 'node:crypto'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'
+import { PrismaClient } from '@prisma/client'
+import Fastify from 'fastify'
+import type { AuthUser } from '../src/lib/ssoAuth.js'
+import { SuperTabStore } from '../src/superTabs/store.js'
+import type { Command } from '../src/superTabs/commands.js'
+import type { MachineObservation } from '../src/superTabs/machines.js'
+import type { TokensByModel } from '../src/superTabs/costs/tokens.js'
+import { poolRows } from './hostRows.test-support.js'
+import { superTabRoutes } from '../src/routes/superTabs.js'
+import { errorHandler } from '../src/middlewares/errorHandler.js'
+
+// Each attempt keeps what it ran on, how it was paid and its tokens on its route decision, however it ends (Dee, 2026-10-29).
+// A fresh loopback replica set, created here.
+let replica: MongoMemoryReplSet
+let db: PrismaClient
+const owner: AuthUser = { sub: '300000000000000000000001', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
+const host: AuthUser = { sub: '300000000000000000000003', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
+const config = { engine: 'claude', model: 'opus', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }
+const MINUTE = 60_000
+const plan = [{ engine: 'claude', known: true, windows: [{ name: '5-hour', usedPercent: 10, resetsAt: null }] }]
+const opus = (input: number, output: number): TokensByModel => ({ 'claude-opus-5-5': { input, output, cacheRead: 0, cacheWrite: 0 } })
+
+beforeAll(async () => {
+ replica = await MongoMemoryReplSet.create({ binary: { version: '7.0.24', downloadDir: join(tmpdir(), 'harness-super-tab-mongodb-binaries') },
+ replSet: { count: 1, ip: '127.0.0.1', storageEngine: 'wiredTiger' } })
+ const uri = replica.getUri(`swarm_costs_test_${randomUUID().replaceAll('-', '_')}`)
+ await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], {
+ env: { ...process.env, DATABASE_URL: uri }, timeout: 60000,
+ })
+ db = new PrismaClient({ datasources: { db: { url: uri } } })
+ for (const user of [owner, host]) await db.user.create({ data: { id: user.sub, externalId: `fixture-${user.sub}`, email: user.email, autonomousEnv: user.autonomousEnv } })
+ for (const machineId of ['lead-host', 'test-host']) {
+ await db.machine.create({ data: { machineId, userId: host.sub, apiKey: `fixture-${machineId}`, managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })
+ await db.machineShare.create({ data: { machineId, ownerId: host.sub, autonomousEnv: 'prod', emails: [owner.email] } })
+ }
+})
+afterAll(async () => {
+ await db?.$disconnect()
+ await replica?.stop()
+})
+
+/** A Swarm whose Lead routes "Ship the parser" (kind `parser`) to a worker on another of host's machines. */
+async function swarm() {
+ let now = 10_000_000
+ const store = new SuperTabStore(db, () => now, null)
+ const tab = (await store.create(owner, randomUUID(), 'Costs', 'public')).id
+ const execute = (command: Command, user = owner, asAgentId?: string) => store.execute(user, tab, { operationId: randomUUID(), command }, asAgentId)
+ const invitation = await execute({ type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })
+ await execute({ type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)
+ for (const [machineId, name] of [['lead-host', 'Lead Mac'], ['test-host', 'Worker Mac']]) {
+ await execute({ type: 'machine.contribute', machineId: machineId!, name: name!, cwd: '/repo', engines: ['claude'], maxAgents: 4 }, host)
+ }
+ const generations = new Map<string, string>()
+ for (const machineId of ['lead-host', 'test-host']) generations.set(machineId, (await poolRows(store, host, machineId)).find(p => p.tabId === tab)!.machine.generation)
+ const harness = { lead: randomUUID(), worker: randomUUID() }
+ const add = async (conversationId: string, machineId: string, harnessId: string, name: string, lead = false) => String((await execute({ type: 'agent.add',
+ conversationId, machineId, harnessId, name, configuration: config, lead })).result.agentId)
+ const lead = await add('lead', 'lead-host', harness.lead, 'Lead', true)
+ const group = String((await execute({ type: 'conversation.create', title: 'Ship the parser', brief: 'Implement it',
+ checks: [{ description: 'Verified', independent: false }] })).result.conversationId)
+ const worker = await add(group, 'test-host', harness.worker, 'Worker')
+ const observe = (machineId: string, running: string[], extra: Partial<MachineObservation> = {}) => store.observeMachine(host, tab, machineId, {
+ generation: generations.get(machineId)!, resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9,
+ diskTotalBytes: 500e9, projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture', os: 'macOS', gpuPercent: null },
+ quotas: plan, tools: {}, runningHarnessIds: running, stoppedHarnessIds: [], ...extra })
+ /** Both machines report; the worker's with its session's totals. */
+ const beat = async (tokens: TokensByModel) => {
+ await observe('lead-host', [harness.lead])
+ await observe('test-host', [harness.worker], { harnessTokens: { [harness.worker]: tokens }, harnessProgress: { [harness.worker]: now } })
+ }
+ const route = async (kind = 'parser') => {
+ const decision = { assessment: { difficulty: 'medium', risk: 'low', why: 'Parser work.', size: 'medium', kind },
+ candidates: [{ id: 'c0', kind: 'member', agentId: worker, machineId: 'test-host', engine: 'claude', model: 'opus', effort: 'high',
+ quality: 3, cost: 3, title: 'Worker', label: 'Worker' }],
+ excluded: [], floor: 1, notes: false, pick: 'c0', via: 'only', p: null, belowFloor: false, why: 'Only candidate.' }
+ return String((await execute({ type: 'route.record', conversationId: group, decision } as Command, host, lead)).result.routeDecisionId)
+ }
+ const assign = async (routeDecisionId: string) => String((await execute({ type: 'work.assign', conversationId: group, agentId: worker, routeDecisionId } as Command,
+ host, lead)).result.assignmentId)
+ /** The worker marks its work done, sending its session's totals read as it finishes (cli superTabs/service.ts), or none
+ * like an older host; `by` the Lead finishes it instead. */
+ const finish = async (assignmentId: string, tokens?: TokensByModel, by = worker) => {
+ const checkId = (await store.read(owner, tab)).state.conversations.find(c => c.id === group)!.checks[0]!.id
+ await execute({ type: 'work.check', conversationId: group, assignmentId, checkId, passed: true, evidence: 'npm test, 0 failures' } as Command, host, worker)
+ await execute({ type: 'work.status', conversationId: group, assignmentId, status: 'done', result: 'Shipped.', ...(tokens ? { tokens } : {}) } as Command, host, by)
+ }
+ const decision = (id: string) => db.superTabRouteDecision.findUniqueOrThrow({ where: { id } })
+ return { store, tab, execute, lead, group, worker, harness, observe, beat, route, assign, finish, decision,
+ clock: { get now() { return now }, set now(value: number) { now = value } } }
+}
+
+describe('an attempt’s record on its route decision', () => {
+ it('keeps the kind, what ran, how it was paid and the session totals at its start and end, and closes done', async () => {
+ const f = await swarm()
+ await f.beat(opus(1000, 100))
+ const id = await f.route()
+ const assignmentId = await f.assign(id)
+ const started = f.clock.now
+ expect((await f.decision(id)).run).toEqual({ machineId: 'test-host', harnessId: f.harness.worker, engine: 'claude', model: 'opus', effort: 'high',
+ billing: 'subscription', startedAt: started, start: opus(1000, 100) })
+ f.clock.now += MINUTE
+ await f.beat(opus(5000, 900))
+ // Its last turns after that report: the totals it sends as it finishes are its end, not the report's.
+ await f.finish(assignmentId, opus(7000, 1200))
+ const row = await f.decision(id)
+ expect(row).toMatchObject({ assignmentId, outcome: 'done', record: { assessment: { kind: 'parser' } },
+ run: { startedAt: started, start: opus(1000, 100), endedAt: f.clock.now, end: opus(7000, 1200) } })
+ })
+
+ it('leaves the end unknown, never the last report’s, when the attempt is finished without its own reading', async () => {
+ for (const by of ['older host', 'lead'] as const) {
+ const f = await swarm()
+ await f.beat(opus(1000, 100))
+ const id = await f.route()
+ const assignmentId = await f.assign(id)
+ await f.beat(opus(5000, 900))
+ // A Lead finishing it sends its own session's totals, which are never the worker's.
+ if (by === 'lead') await f.finish(assignmentId, opus(9_999_999, 1), f.lead)
+ else await f.finish(assignmentId)
+ expect((await f.decision(id)).run, by).toMatchObject({ end: null, endedAt: f.clock.now })
+ expect((await f.store.costSummary(owner, f.tab, 7)).totals, by).toMatchObject({ attempts: 1, tokensKnown: 0, costKnown: 0, apiCost: null })
+ }
+ })
+
+ it('closes lost when its machine goes silent, and stays lost when the task is handed on', async () => {
+ const f = await swarm()
+ await f.beat(opus(10, 1))
+ const id = await f.route()
+ await f.assign(id)
+ await f.beat(opus(70, 7))
+ const silent = f.clock.now
+ f.clock.now = silent + 2 * MINUTE + 5_000
+ await f.observe('lead-host', [f.harness.lead])
+ expect(await f.decision(id)).toMatchObject({ outcome: 'lost', outcomeAt: new Date(f.clock.now), run: { end: opus(70, 7), endedAt: f.clock.now } })
+ // Handing it on keeps it lost: the hand-over is a new attempt with its own decision.
+ await f.observe('test-host', [f.harness.worker])
+ const next = await f.route()
+ expect((await f.decision(id)).outcome).toBe('lost')
+ await f.assign(next)
+ expect((await f.decision(next)).run).toMatchObject({ startedAt: f.clock.now })
+ })
+
+ it('ends a task lost to its stopped session with the counts reported before the session stopped', async () => {
+ const f = await swarm()
+ await f.beat(opus(10, 1))
+ const id = await f.route()
+ await f.assign(id)
+ await f.beat(opus(250, 25))
+ f.clock.now += 5_000
+ // The report that says the session stopped no longer lists it, nor its counts.
+ await f.observe('test-host', [], { stoppedHarnessIds: [f.harness.worker] })
+ expect(await f.decision(id)).toMatchObject({ outcome: 'lost', run: { start: opus(10, 1), end: opus(250, 25), endedAt: f.clock.now } })
+ })
+
+ it('never shows the machine’s raw token counts to a reader', async () => {
+ const f = await swarm()
+ await f.beat(opus(10, 1))
+ const machine = (await f.store.read(owner, f.tab)).state.machines!.find(m => m.machineId === 'test-host')!
+ expect(machine.observation).toBeDefined()
+ expect(machine.observation).not.toHaveProperty('harnessTokens')
+ const stored = await db.swarmMachine.findFirstOrThrow({ where: { tabId: f.tab, key: 'test-host' } })
+ expect((stored.data as { contribution: { observation: { harnessTokens?: unknown } } }).contribution.observation.harnessTokens).toEqual({ [f.harness.worker]: opus(10, 1) })
+ })
+})
+
+describe('the cost summary', () => {
+ it('shows a finished attempt by engine, model, effort and kind with its tokens, API-equivalent cost and spend', async () => {
+ const f = await swarm()
+ await f.beat(opus(1_000_000, 100_000))
+ const assignmentId = await f.assign(await f.route('parser'))
+ // Twelve minutes of work, its machine reporting every minute as it does every 15 seconds.
+ for (let minute = 0; minute < 12; minute++) {
+ f.clock.now += MINUTE
+ await f.beat(opus(3_000_000, 600_000))
+ }
+ await f.finish(assignmentId, opus(3_000_000, 600_000))
+ const summary = await f.store.costSummary(owner, f.tab, 7)
+ // 2M input at $4 and 0.5M output at $20 per million: $18, on a plan, so nothing spent per token.
+ expect(summary.rows).toEqual([expect.objectContaining({ engine: 'claude', model: 'opus', effort: 'high', kind: 'parser', attempts: 1, shipped: 1,
+ outcomes: { done: 1 }, billing: { subscription: 1 }, medianMinutesToShip: 12, tokensKnown: 1,
+ tokens: { input: 2_000_000, output: 500_000, cacheRead: 0, cacheWrite: 0 }, apiCost: 18, spend: 0, costKnown: 1, costPerShipped: 18 })])
+ expect(summary).toMatchObject({ days: 7, truncated: false, prices: [{ model: 'claude-opus-5-5' }] })
+ // The Lead reads it too, as its own agent.
+ expect((await f.store.costSummary(host, f.tab, 7, f.lead)).totals).toMatchObject({ attempts: 1, apiCost: 18 })
+ // Past the period, nothing.
+ f.clock.now += 8 * 24 * 60 * MINUTE
+ expect((await f.store.costSummary(owner, f.tab, 7)).rows).toEqual([])
+ })
+})
+
+describe('route decision reads', () => {
+ // Review of #2106: members read only the summary, never an attempt's session totals.
+ it('never carry an attempt’s run or its token totals, over HTTP or to the Lead, while the summary still has them', async () => {
+ const f = await swarm()
+ await f.beat(opus(1_000_000, 100_000))
+ const id = await f.route()
+ await f.finish(await f.assign(id), opus(1_000_000, 100_000))
+ expect((await f.decision(id)).run).toMatchObject({ start: opus(1_000_000, 100_000) })
+ const app = Fastify()
+ app.setErrorHandler(errorHandler)
+ app.addHook('onRequest', async (request, reply) => {
+ const user = [owner, host].find(u => `Bearer ${u.sub}` === request.headers.authorization)
+ if (!user) return reply.code(401).send({ success: false })
+ request.user = user
+ })
+ await app.register(superTabRoutes, { store: f.store })
+ await app.ready()
+ try {
+ const get = async (url: string, user = owner) => {
+ const response = await app.inject({ url, headers: { authorization: `Bearer ${user.sub}` } })
+ expect(response.statusCode, url).toBe(200)
+ return response.json().data
+ }
+ const list = await get(`/api/super-tabs/${f.tab}/route-decisions`)
+ const one = await get(`/api/super-tabs/${f.tab}/route-decisions/${id}`)
+ const lead = [...await f.store.routeDecisions(host, f.tab, f.lead), await f.store.routeDecision(host, f.tab, id, f.lead)]
+ for (const decision of [...list, one, ...lead]) {
+ expect(decision).toMatchObject({ id, outcome: 'done' })
+ expect(decision).not.toHaveProperty('run')
+ expect(JSON.stringify(decision)).not.toMatch(/cacheRead|1000000/)
+ }
+ expect((await get(`/api/super-tabs/${f.tab}/costs?days=7`)).totals).toMatchObject({ attempts: 1, shipped: 1 })
+ } finally { await app.close() }
+ })
+})
diff --git a/backend/integration/superTabIndexes.test.ts b/backend/integration/superTabIndexes.test.ts
index 07457deb0..57dc6f443 100644
--- a/backend/integration/superTabIndexes.test.ts
+++ b/backend/integration/superTabIndexes.test.ts
@@ -7,6 +7,7 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest'
import { MongoMemoryReplSet } from 'mongodb-memory-server-core'
import { PrismaClient } from '@prisma/client'
import { inConversationOrder, pageDeliveries, pageReactions } from '../src/superTabs/pageReads.js'
+import { costRows } from '../src/superTabs/costs/read.js'
import { recentDecisions } from '../src/superTabs/routeDecisions.js'
import { settleStuckDeliveries } from '../src/superTabs/deliverySettle.js'
import { revokeNativeContexts } from '../src/superTabs/native.js'
@@ -179,6 +180,17 @@ describe('the delivery pass', () => {
})
})
+describe('cost summary', () => {
+ // The Swarm's cost read (superTabs/costs/read.ts) takes the decisions routed in a period. Never a collection scan, and never
+ // more documents than the period holds, however many the Swarm keeps.
+ it('reads the decisions of a period with one index scan, examining only those', async () => {
+ const [found, profile] = await profiled('SuperTabRouteDecision', () => costRows(db, 'A', T0 + 1500 * 1000))
+ // The fixture's decisions carry no runs, so none is an attempt to summarize; what matters is what Mongo read.
+ expect(found).toEqual({ rows: [], truncated: false })
+ expect(profile).toEqual({ plans: ['IXSCAN { tabId: 1, createdAt: 1 }'], docsExamined: 500, returned: 500 })
+ })
+})
+
describe('route decision list', () => {
const prismaRead = (tabId: string, conversationIds: string[]) => db.superTabRouteDecision.findMany({ where: { tabId, conversationId: { in: conversationIds } },
orderBy: { createdAt: 'desc' }, take: 100 })
@@ -203,11 +215,11 @@ describe('route decision list', () => {
expect(rows.find(row => row.id === 'A-d1800')).toEqual({ id: 'A-d1800', tabId: 'A', conversationId: 'g000',
record: { difficulty: 'medium', candidates: [{ id: 'c0', p: 0.42, slots: 3, title: 'Claude opus high' }, { id: 'c1', p: null, slots: 0 }], why: 'route 1800' },
final: { kind: 'new', startId: 's1800' }, override: { by: 'lead', candidateId: 'c1' }, assignmentId: 'as1800', outcome: 'done',
- outcomeAt: new Date(T0 + 1_800_500), createdAt: new Date(T0 + 1_800_000) })
+ outcomeAt: new Date(T0 + 1_800_500), run: null, createdAt: new Date(T0 + 1_800_000) })
// Written as an older record: none of the optional fields exist.
expect(rows.find(row => row.id === 'A-d0721')).toEqual({ id: 'A-d0721', tabId: 'A', conversationId: 'g001',
record: { difficulty: 'medium', candidates: [{ id: 'c0', p: 0.42, slots: 3, title: 'Claude opus high' }, { id: 'c1', p: null, slots: 0 }], why: 'route 721' },
- final: null, override: null, assignmentId: null, outcome: null, outcomeAt: null, createdAt: new Date(T0 + 721_000) })
+ final: null, override: null, assignmentId: null, outcome: null, outcomeAt: null, run: null, createdAt: new Date(T0 + 721_000) })
expect(await recentDecisions(db, 'A', GROUPS)).toEqual(await prismaRead('A', GROUPS))
expect(await recentDecisions(db, 'A', ['g007', 'g300'])).toEqual(await prismaRead('A', ['g007', 'g300']))
expect(await recentDecisions(db, 'B', [])).toEqual([])
diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prisma
index 01f1e4e26..9f5951eaf 100644
--- a/backend/prisma/schema.prisma
+++ b/backend/prisma/schema.prisma
@@ -1291,6 +1291,8 @@ model SuperTabRouteDecision {
assignmentId String?
outcome String?
outcomeAt DateTime?
+ /// Its attempt's run: what it ran on, how it was paid, its session's token totals at start and end (superTabs/costs/attempts.ts).
+ run Json?
createdAt DateTime @default(now())
@@index([tabId, createdAt])
diff --git a/backend/src/config/env.ts b/backend/src/config/env.ts
index 9dad25fd2..aa1ae4494 100644
--- a/backend/src/config/env.ts
+++ b/backend/src/config/env.ts
@@ -42,6 +42,11 @@ const envSchema = z.object({
// Its size per process, counted as the JSON size of what it holds.
SWARM_CACHE_MB: z.string().default('64').transform(Number),
+ // On: a per-user web-ws socket that says it is a daemon's relay, a link or a group sync (`?client=`) starts the
+ // account's feeds (machine and device statuses, the machine-list, desk/zoo and E2EE-pair channels) only when it asks
+ // for them, lib/webWs.ts. Off (the default): every socket starts them as it connects, as before.
+ WEB_WS_LAZY_FEEDS: z.enum(['on', 'off']).default('off'),
+
// This backend instance's stable id (used to route manager-command replies via Redis in a
// multi-instance deploy). Defaults to the pm2 instance index or a per-process fallback.
BACKEND_INSTANCE_ID: z.string().default(''),
diff --git a/backend/src/lib/webWs.ts b/backend/src/lib/webWs.ts
index 7bf43324b..aec9bf29d 100644
--- a/backend/src/lib/webWs.ts
+++ b/backend/src/lib/webWs.ts
@@ -83,6 +83,11 @@ const WATCH_DEBOUNCE_MS = 250
* re-dialled offline machines every few seconds, 68% of 1,884 selects in 10 minutes (prod, 2026-10-27, #314). The
* Desktop's own longest reconnect backoff, so a machine coming back is seen no later than it was. */
export const OFFLINE_RETRY_AFTER_MS = 30_000
+/** Sockets that never read the account's feeds unless they ask, with WEB_WS_LAZY_FEEDS on: a daemon's relay, `harness
+ * link`'s one-shot socket and the apps' trust-group sync (`?client=`). Prod, 2026-10-29: about 121 connects a minute
+ * living a median 0.4 s, nearly all relays, each reading the account's machines and devices and subscribing five
+ * channels it never read (WebSocket roadmap Phase 1 item 4). A socket that declares nothing may be an older app. */
+const ON_DEMAND_FEED_CLIENTS: ReadonlySet<string> = new Set(['relay', 'link', 'group-sync'])
/** Who is on the other end of a per-user socket, as the client declares it: the surface (`?client=`), and
* for the phone the release (`?release=`, the public x.y.z) and whether the build is a debug or simulator
@@ -200,6 +205,8 @@ function attachUserClient(ws: WebSocket, user: AuthUser, surface: 'mobile' | 'we
// dead. This used to be a second heartbeat loop here, carefully disabled while attached so the two
// sweeps couldn't race; the hub now tracks the socket itself, which is one sweep for both states.
const releaseLiveness = trackSocketLiveness(ws, 'web')
+ // A relay, a link or a group sync starts the feeds below only when it asks (ON_DEMAND_FEED_CLIENTS).
+ const feedsOnDemand = env.WEB_WS_LAZY_FEEDS === 'on' && ON_DEMAND_FEED_CLIENTS.has(declared.client)
// ── Live Machines-list feed ──────────────────────────────────────────────────────────────────
// Subscribe node_status for EVERY agent the user owns and forward it tagged with the machineId (the
@@ -262,7 +269,7 @@ function attachUserClient(ws: WebSocket, user: AuthUser, surface: 'mobile' | 'we
void watchAgents().catch((err) => logger.warn('web-ws watchAgents failed', { userId: user.sub, error: String(err) }))
}, WATCH_DEBOUNCE_MS)
}
- void watchAgents().catch((err) => logger.warn('web-ws watchAgents failed', { userId: user.sub, error: String(err) }))
+ if (!feedsOnDemand) void watchAgents().catch((err) => logger.warn('web-ws watchAgents failed', { userId: user.sub, error: String(err) }))
// ── Live device-status feed (mirror of watchAgents; per-DEVICE statuses over one per-user sub) ──
// Transitions ride the user-scoped `devstatus:{userId}` channel (deviceWs publishes on connect/
@@ -297,32 +304,39 @@ function attachUserClient(ws: WebSocket, user: AuthUser, surface: 'mobile' | 'we
}
await seedDeviceStatuses()
}
- void watchDevices().catch((err) => logger.warn('web-ws watchDevices failed', { userId: user.sub, error: String(err) }))
+ if (!feedsOnDemand) void watchDevices().catch((err) => logger.warn('web-ws watchDevices failed', { userId: user.sub, error: String(err) }))
// ── Live machine-LIST invalidation ─────────────────────────────────────────────────────────────
// The `devmachines:{userId}` channel (despite the device-era name) is the per-user "machine list
// changed" bus: create/delete/rename publish here from whatever worker served the REST call.
// Forward it as `machines_changed` so every open tab re-fetches the list (names stay in sync
- // across tabs without F5).
+ // across tabs without F5). It also ends the socket when the account moves to another environment, so a socket whose
+ // feeds wait to be asked for still hears it from the moment it holds a machine (bindAgent).
let machineListUnsub: (() => void) | null = null
- void (async () => {
- machineListUnsub = await subscribeDeviceMachineListChanged(user.sub, (msg) => {
- if (ws.readyState !== WebSocket.OPEN) return
- if (msg.reason === 'environment_changed' && msg.autonomousEnv && msg.autonomousEnv !== user.autonomousEnv) {
- try { ws.close(4403, `env:${msg.autonomousEnv}`) } catch { /* ignore */ }
- return
- }
- send({ type: 'machines_changed', payload: { reason: msg.reason } })
- })
- if (closed) { machineListUnsub(); machineListUnsub = null }
- })().catch((err) => logger.warn('web-ws machine-list watch failed', { userId: user.sub, error: String(err) }))
+ let machineListWatched = false
+ const watchMachineList = (): void => {
+ if (machineListWatched) return
+ machineListWatched = true
+ void (async () => {
+ machineListUnsub = await subscribeDeviceMachineListChanged(user.sub, (msg) => {
+ if (ws.readyState !== WebSocket.OPEN) return
+ if (msg.reason === 'environment_changed' && msg.autonomousEnv && msg.autonomousEnv !== user.autonomousEnv) {
+ try { ws.close(4403, `env:${msg.autonomousEnv}`) } catch { /* ignore */ }
+ return
+ }
+ send({ type: 'machines_changed', payload: { reason: msg.reason } })
+ })
+ if (closed) { machineListUnsub(); machineListUnsub = null }
+ })().catch((err) => logger.warn('web-ws machine-list watch failed', { userId: user.sub, error: String(err) }))
+ }
+ if (!feedsOnDemand) watchMachineList()
// ── The account's desk and zoo: changed somewhere ────────────────────────────────────────────
// The same `desk:{userId}` and `zoo:{userId}` invalidations every adapter socket hears
// (lib/adapterAccountPushes.ts), forwarded to the clients that have no daemon to relay them — the
// phone. One frame carrying the revision each; see lib/webAccountPushes.ts.
let documentsUnsub: (() => void) | null = null
- void (async () => {
+ if (!feedsOnDemand) void (async () => {
documentsUnsub = await relayWebDocumentPushes(user.sub, (frame) => {
if (ws.readyState !== WebSocket.OPEN) return
send(frame)
@@ -334,7 +348,7 @@ function attachUserClient(ws: WebSocket, user: AuthUser, surface: 'mobile' | 'we
// Not tied to current machine selection: any logged-in page can receive the notice, then the frontend
// checks whether this browser already trusts the target machine before showing the global popup.
let deviceE2eePairUnsub: (() => void) | null = null
- void (async () => {
+ if (!feedsOnDemand) void (async () => {
deviceE2eePairUnsub = await subscribeDeviceE2eePair(user.sub, (msg) => {
if (ws.readyState !== WebSocket.OPEN) return
const { kind, ...payload } = msg
@@ -356,9 +370,10 @@ function attachUserClient(ws: WebSocket, user: AuthUser, surface: 'mobile' | 'we
const mgr = await getAgentPresence(machineId)
if (ws.readyState !== WebSocket.OPEN || currentAgentId !== machineId) return
const online = await machineOnline(machineId, !!mgr)
- const lifecycle = await getMachineLifecycleStatus(machineId)
+ // An online machine is `running` whatever machine_nodes says: read only for one that is not.
+ const lifecycle = online ? 'running' : await getMachineLifecycleStatus(machineId)
if (ws.readyState !== WebSocket.OPEN || currentAgentId !== machineId) return
- send({ type: 'node_status', payload: { online, status: online ? 'running' : lifecycle === 'unknown' ? 'offline' : lifecycle } })
+ send({ type: 'node_status', payload: { online, status: lifecycle === 'unknown' ? 'offline' : lifecycle } })
})(), 'web-ws seed node_status', { userId: user.sub, machineId })
}
const bindAgent = async (machineIdRaw: unknown, refuseOffline: boolean): Promise<void> => {
@@ -425,6 +440,7 @@ function attachUserClient(ws: WebSocket, user: AuthUser, surface: 'mobile' | 'we
currentAgentId = machineId
currentBinding = binding
watchShare(shared ? machineId : null)
+ watchMachineList()
logger.info('web user selected agent', { userId: user.sub, machineId, connId: client.connId, ...(shared ? { shared } : {}) })
ack(machineId)
}
diff --git a/backend/src/lib/webWsFeeds.test.ts b/backend/src/lib/webWsFeeds.test.ts
new file mode 100644
index 000000000..ad05b4e3e
--- /dev/null
+++ b/backend/src/lib/webWsFeeds.test.ts
@@ -0,0 +1,221 @@
+import { EventEmitter } from 'node:events'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// The account's feeds a per-user socket starts (WebSocket roadmap, Phase 1 item 4). Prod, 2026-10-29: about 121
+// web-ws connects a minute living a median 0.4 s, nearly all daemon relays, and each one read the account's machine
+// list and devices, subscribed a status channel per machine and four per-user channels, and armed a 30 s device
+// re-read, none of which a relay ever reads. With WEB_WS_LAZY_FEEDS on, a socket that says it is a relay, a link or a
+// group sync starts them only when it asks (`machines_watch`, `devices_watch`); every other socket is as before.
+const m = vi.hoisted(() => ({
+ auth: vi.fn(), upgrade: vi.fn(), presence: vi.fn(), online: vi.fn(), attach: vi.fn(), machineFindUnique: vi.fn(),
+ machineFindMany: vi.fn(), deviceFindMany: vi.fn(), subscribeStatus: vi.fn(), subscribeDeviceStatus: vi.fn(),
+ subscribeMachineList: vi.fn(), subscribeE2eePair: vi.fn(), documents: vi.fn(), lifecycle: vi.fn(),
+}))
+vi.mock('../utils/logger.js', () => ({ logger: { warn: vi.fn(), info: vi.fn(), error: vi.fn(), debug: vi.fn() } }))
+vi.mock('./ssoAuth.js', async original => ({ ...await original<typeof import('./ssoAuth.js')>(), authenticateAccessToken: m.auth }))
+vi.mock('./wsServer.js', async original => ({ ...await original<typeof import('./wsServer.js')>(), createWss: () => ({ handleUpgrade: m.upgrade }) }))
+vi.mock('./prisma.js', () => ({
+ prisma: { machine: { findUnique: m.machineFindUnique, findMany: m.machineFindMany }, deviceBinding: { findMany: m.deviceFindMany } },
+ machineAlive: { OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }] },
+}))
+vi.mock('./bus.js', () => ({
+ getAgentPresence: m.presence, getAgentPresenceMany: vi.fn(async () => new Map()), subscribeStatus: m.subscribeStatus,
+ getDevicePresence: vi.fn(async () => false), subscribeDeviceStatus: m.subscribeDeviceStatus,
+ subscribeDeviceMachineListChanged: m.subscribeMachineList, subscribeDeviceE2eePair: m.subscribeE2eePair,
+ subscribeMachineShareChanged: vi.fn(async () => () => {}),
+}))
+vi.mock('./providerLink.js', () => ({ machineOnline: m.online }))
+vi.mock('./machineLifecycle.js', () => ({ ensureMachineReady: vi.fn(async () => {}), getMachineLifecycleStatus: m.lifecycle }))
+vi.mock('./webAccountPushes.js', () => ({ relayWebDocumentPushes: m.documents }))
+vi.mock('./hub.js', () => ({ attachHubClient: m.attach, trackSocketLiveness: () => () => {} }))
+
+import { env } from '../config/env.js'
+import { handleWebUpgrade } from './webWs.js'
+
+const owner = { sub: 'owner', email: '[email protected]', role: 'user', autonomousEnv: 'prod' }
+const mac = { machineId: 'owner-mac', userId: 'owner', autonomousEnv: 'prod', billingStatus: 'not_required', authMode: 'remote', deletedAt: null }
+const flush = async () => { for (let i = 0; i < 400; i++) await Promise.resolve() }
+
+class Socket extends EventEmitter {
+ readyState = 1; bufferedAmount = 0
+ send = vi.fn()
+ close = vi.fn(() => { this.readyState = 3; this.emit('close', 1000, Buffer.alloc(0)) })
+ terminate = vi.fn(() => this.close())
+ frame(body: unknown) { this.emit('message', Buffer.from(JSON.stringify(body)), false) }
+ sent() { return this.send.mock.calls.map(c => JSON.parse(c[0] as string)) }
+}
+const raw = () => ({ write: vi.fn(), destroy: vi.fn(), destroyed: false, on: vi.fn(), once: vi.fn() })
+
+async function opens(query = ''): Promise<Socket> {
+ const ws = new Socket()
+ m.upgrade.mockImplementation((_r, _s, _h, done) => done(ws))
+ handleWebUpgrade({ url: `/api/web-ws?autonomousEnv=prod${query}`, headers: { 'sec-websocket-protocol': 'access-token' } } as never, raw() as never, Buffer.alloc(0))
+ await flush()
+ return ws
+}
+
+/** Which of the account's feeds the socket started. */
+const feeds = () => ({
+ machines: m.machineFindMany.mock.calls.length > 0,
+ devices: m.subscribeDeviceStatus.mock.calls.length > 0 || m.deviceFindMany.mock.calls.length > 0,
+ machineList: m.subscribeMachineList.mock.calls.length > 0,
+ documents: m.documents.mock.calls.length > 0,
+ e2eePair: m.subscribeE2eePair.mock.calls.length > 0,
+})
+const all = { machines: true, devices: true, machineList: true, documents: true, e2eePair: true }
+const none = { machines: false, devices: false, machineList: false, documents: false, e2eePair: false }
+
+const before = env.WEB_WS_LAZY_FEEDS
+beforeEach(() => {
+ vi.clearAllMocks()
+ vi.useRealTimers()
+ m.auth.mockResolvedValue(owner)
+ m.machineFindUnique.mockResolvedValue(mac)
+ m.machineFindMany.mockResolvedValue([{ machineId: 'owner-mac', billingStatus: 'not_required' }])
+ m.deviceFindMany.mockResolvedValue([])
+ m.attach.mockReturnValue({ connId: 'conn', detach: vi.fn() })
+ m.presence.mockResolvedValue('manager')
+ m.online.mockResolvedValue(true)
+ m.lifecycle.mockResolvedValue('running')
+ for (const sub of [m.subscribeStatus, m.subscribeDeviceStatus, m.subscribeMachineList, m.subscribeE2eePair, m.documents]) sub.mockResolvedValue(() => {})
+})
+afterEach(() => { env.WEB_WS_LAZY_FEEDS = before; vi.useRealTimers() })
+
+describe('with WEB_WS_LAZY_FEEDS on', () => {
+ beforeEach(() => { env.WEB_WS_LAZY_FEEDS = 'on' })
+
+ it.each(['relay', 'link', 'group-sync'])('a %s socket starts none of the account\'s feeds', async client => {
+ await opens(`&client=${client}`)
+ expect(feeds()).toEqual(none)
+ })
+
+ it.each(['mobile', 'web', 'desktop'])('a %s socket starts them all, as before', async client => {
+ await opens(`&client=${client}`)
+ expect(feeds()).toEqual(all)
+ })
+
+ // Every daemon released before the relays said what they are: nothing tells it apart from an older app.
+ it('a socket that declares nothing starts them all, as before', async () => {
+ await opens()
+ expect(feeds()).toEqual(all)
+ })
+
+ it('a relay that sends machines_watch gets the machine statuses', async () => {
+ const ws = await opens('&client=relay')
+ vi.useFakeTimers()
+ ws.frame({ type: 'machines_watch' })
+ await vi.advanceTimersByTimeAsync(300)
+ vi.useRealTimers()
+ await flush()
+ expect(m.machineFindMany).toHaveBeenCalledOnce()
+ expect(m.subscribeStatus).toHaveBeenCalledWith('owner-mac', expect.any(Function))
+ expect(ws.sent()).toContainEqual({ type: 'machines_status', payload: { statuses: [{ machineId: 'owner-mac', online: true, status: 'running' }] } })
+ })
+
+ it('a relay that sends devices_watch gets the device statuses and their re-read', async () => {
+ m.deviceFindMany.mockResolvedValue([{ deviceId: 'dial', lastSeenAt: null }])
+ const ws = await opens('&client=relay')
+ ws.frame({ type: 'devices_watch' })
+ await flush()
+ expect(m.subscribeDeviceStatus).toHaveBeenCalledWith('owner', expect.any(Function))
+ expect(ws.sent()).toContainEqual({ type: 'devices_status', payload: { statuses: [{ deviceId: 'dial', online: false, lastSeenAt: null }] } })
+ })
+
+ // The machine-list channel also carries the account moving to another environment, which ends every socket signed in
+ // to the old one. A relay that holds a machine keeps hearing it; one refused at its select never subscribes.
+ it('a relay attached to a machine still ends when the account changes environment', async () => {
+ let tell: ((msg: unknown) => void) | null = null
+ m.subscribeMachineList.mockImplementation(async (_user: string, cb: (msg: unknown) => void) => { tell = cb; return () => {} })
+ const ws = await opens('&client=relay')
+ expect(m.subscribeMachineList).not.toHaveBeenCalled()
+ ws.frame({ type: 'machine_select', payload: { machineId: 'owner-mac' } })
+ await flush()
+ expect(m.subscribeMachineList).toHaveBeenCalledOnce()
+ tell!({ reason: 'environment_changed', autonomousEnv: 'dev' })
+ expect(ws.close).toHaveBeenCalledWith(4403, 'env:dev')
+ })
+
+ it('a relay refused at its select subscribes nothing', async () => {
+ m.presence.mockResolvedValue(null)
+ m.online.mockResolvedValue(false)
+ const ws = await opens('&client=relay')
+ ws.frame({ type: 'machine_select', payload: { machineId: 'owner-mac' } })
+ await flush()
+ expect(ws.sent()).toContainEqual(expect.objectContaining({ type: 'machine_select_error' }))
+ expect(feeds()).toEqual(none)
+ })
+
+ it('a relay selecting again subscribes the machine list once', async () => {
+ const ws = await opens('&client=relay')
+ for (let i = 0; i < 3; i++) {
+ ws.frame({ type: 'machine_select', payload: { machineId: 'owner-mac' } })
+ await flush()
+ }
+ expect(m.subscribeMachineList).toHaveBeenCalledOnce()
+ })
+
+ it('a relay closed while its machine-list subscription is pending lets it go', async () => {
+ const unsub = vi.fn()
+ let done: ((u: () => void) => void) | null = null
+ m.subscribeMachineList.mockImplementation(() => new Promise(resolve => { done = resolve }))
+ const ws = await opens('&client=relay')
+ ws.frame({ type: 'machine_select', payload: { machineId: 'owner-mac' } })
+ await flush()
+ ws.emit('close', 1000, Buffer.alloc(0))
+ done!(unsub)
+ await flush()
+ expect(unsub).toHaveBeenCalledOnce()
+ })
+})
+
+describe('with WEB_WS_LAZY_FEEDS off (the default)', () => {
+ beforeEach(() => { env.WEB_WS_LAZY_FEEDS = 'off' })
+
+ it.each(['relay', 'link', 'group-sync', 'mobile'])('a %s socket starts them all, as before', async client => {
+ await opens(`&client=${client}`)
+ expect(feeds()).toEqual(all)
+ })
+})
+
+// The test run sets no WEB_WS_LAZY_FEEDS, so what the module read is the default.
+it('defaults to off', () => {
+ expect(process.env.WEB_WS_LAZY_FEEDS).toBeUndefined()
+ expect(before).toBe('off')
+})
+
+// The ack's node_status said `running` for an online machine whatever `machine_nodes` held, and read it on every
+// accepted select anyway (WebSocket roadmap Phase 1 item 4).
+describe('the select ack', () => {
+ const nodeStatus = (ws: Socket) => ws.sent().filter(f => f.type === 'node_status')
+
+ it('says an online machine is running without reading its lifecycle', async () => {
+ const ws = await opens('&client=relay')
+ ws.frame({ type: 'machine_select', payload: { machineId: 'owner-mac' } })
+ await flush()
+ expect(nodeStatus(ws)).toEqual([{ type: 'node_status', payload: { online: true, status: 'running' } }])
+ expect(m.lifecycle).not.toHaveBeenCalled()
+ })
+
+ it('reads the lifecycle of an offline machine a phone waits on', async () => {
+ m.presence.mockResolvedValue(null)
+ m.online.mockResolvedValue(false)
+ m.lifecycle.mockResolvedValue('stopped')
+ m.machineFindMany.mockResolvedValue([])
+ const ws = await opens('&client=mobile')
+ ws.frame({ type: 'machine_select', payload: { machineId: 'owner-mac' } })
+ await flush()
+ expect(nodeStatus(ws)).toEqual([{ type: 'node_status', payload: { online: false, status: 'stopped' } }])
+ expect(m.lifecycle).toHaveBeenCalledWith('owner-mac')
+ })
+
+ it('says offline for a machine whose lifecycle is unknown', async () => {
+ m.presence.mockResolvedValue(null)
+ m.online.mockResolvedValue(false)
+ m.lifecycle.mockResolvedValue('unknown')
+ m.machineFindMany.mockResolvedValue([])
+ const ws = await opens('&client=mobile')
+ ws.frame({ type: 'machine_select', payload: { machineId: 'owner-mac' } })
+ await flush()
+ expect(nodeStatus(ws)).toEqual([{ type: 'node_status', payload: { online: false, status: 'offline' } }])
+ })
+})
diff --git a/backend/src/routes/superTabs.ts b/backend/src/routes/superTabs.ts
index 1ae45b079..566ec8d83 100644
--- a/backend/src/routes/superTabs.ts
+++ b/backend/src/routes/superTabs.ts
@@ -28,6 +28,7 @@ import { HostReads } from '../superTabs/read/host.js'
import { UPDATE_REQUIRED } from '../superTabs/read/contract.js'
import { isTeamSession, TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE } from '../lib/teamSession.js'
import type { AuthUser } from '../lib/ssoAuth.js'
+import { DEFAULT_DAYS, MAX_DAYS } from '../superTabs/costs/read.js'
const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)
const tabParams = z.object({ tabId: id })
@@ -50,6 +51,7 @@ const personOnly = (user: AuthUser) => { if (isTeamSession(user)) fail(TEAM_SESS
const listQuery = z.object({ after: id.optional() }).strict()
const cursor = z.string().min(1).max(512).regex(/^[A-Za-z0-9_-]+$/)
const changesQuery = agentQuery.extend({ cursor })
+const costsQuery = z.object({ days: z.coerce.number().int().min(1).max(MAX_DAYS).default(DEFAULT_DAYS), asAgentId: id.optional() }).strict()
const leaderboardQuery = z.object({ projectId: id, week: z.coerce.number().int().nonnegative().safe().optional() }).strict()
const dormantQuery = agentQuery.extend({ dormant: z.literal('1'), projectId: id.optional(), before: cursor.optional() })
const groupParams = tabParams.extend({ conversationId: id })
@@ -448,6 +450,10 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
app.get<{ Params: z.infer<typeof messageParams>; Querystring: z.infer<typeof agentQuery> }>('/api/super-tabs/:tabId/conversations/:conversationId/attempts',
{ preHandler: [validateParams(messageParams), validateQuery(agentQuery)] },
(req, reply) => respond(reply, () => store.attempts(req.user!, req.params.tabId, req.params.conversationId, req.query.asAgentId)))
+ // What routed attempts cost and how they went over a period (superTabs/costs/read.ts).
+ app.get<{ Params: z.infer<typeof tabParams>; Querystring: z.infer<typeof costsQuery> }>('/api/super-tabs/:tabId/costs',
+ { preHandler: [validateParams(tabParams), validateQuery(costsQuery)] },
+ (req, reply) => respond(reply, () => store.costSummary(req.user!, req.params.tabId, req.query.days, req.query.asAgentId)))
app.get<{ Params: z.infer<typeof tabParams>; Querystring: z.infer<typeof agentQuery> }>('/api/super-tabs/:tabId/route-decisions',
{ preHandler: [validateParams(tabParams), validateQuery(agentQuery)] },
(req, reply) => respond(reply, () => store.routeDecisions(req.user!, req.params.tabId, req.query.asAgentId)))
diff --git a/backend/src/superTabs/buddies.test.ts b/backend/src/superTabs/buddies.test.ts
index 7c7ac307e..6bb8ff9a4 100644
--- a/backend/src/superTabs/buddies.test.ts
+++ b/backend/src/superTabs/buddies.test.ts
@@ -1,4 +1,7 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
import { describe, expect, it } from 'vitest'
+import { CODEX_BUDDY_REFUSAL } from './buddyContract.js'
import { applyCommand, type Command, type CommandContext } from './commands.js'
import { createSuperTab, visibleState, type Actor, type Conversation } from './model.js'
import { canReadGroup, canWatchAgent, isConfidential } from './projects.js'
@@ -157,6 +160,19 @@ function fresh() {
}
describe('adding a Buddy', () => {
+ it('is refused on Codex for now, saying why, and leaves the chat and starts as they were (security review 1 of #2087)', () => {
+ const f = fresh()
+ const starts = f.state.starts?.length ?? 0, groups = f.state.conversations.length
+ expect(() => addBuddy(f, peer, f.app.projectId, 'peer-mac', 'codex')).toThrow('A Codex Buddy is not available yet')
+ expect([f.state.starts?.length ?? 0, f.state.conversations.length]).toEqual([starts, groups])
+ })
+
+ it('words its Codex refusal as Desktop does beside a disabled Codex (security re-check of #2087)', () => {
+ // Desktop holds the same pair to this constant (desktop test/buddy_refusal_parity_test.dart).
+ const desktop = readFileSync(fileURLToPath(new URL('../../../desktop/lib/super_tabs/buddies.dart', import.meta.url)), 'utf8')
+ expect(/kBuddyEngineRefusals = \{\s*'codex':\s*'([^']*)'/.exec(desktop)?.[1]).toBe(CODEX_BUDDY_REFUSAL)
+ })
+
it('is refused while Buddies are off', () => {
const f = fresh()
f.run({ type: 'tab.buddies', enabled: false })
@@ -165,14 +181,14 @@ describe('adding a Buddy', () => {
it('opens the person\'s Buddy chat, read by them alone, and starts the Buddy on the machine they chose', () => {
const f = fresh()
- const added = addBuddy(f, peer, f.app.projectId, 'peer-mac', 'codex')
+ const added = addBuddy(f, peer, f.app.projectId, 'peer-mac')
const chat = group(f, added.result.conversationId as string)
expect(chat).toMatchObject({ kind: 'buddy', projectId: f.app.projectId, leadId: null, agentIds: [], archived: false,
audience: { people: [{ id: 'peer', generation: 'first' }] } })
expect(added.messages).toEqual([])
const start = f.state.starts!.find(s => s.id === added.result.startId)!
expect(start).toMatchObject({ contributorId: 'peer', machineOwnerId: 'peer', poolGeneration: 'g1', dispatched: false, error: null })
- expect(start.request).toMatchObject({ conversationId: chat.id, machineId: 'peer-mac', engine: 'codex', cwd: `/swarm/${f.app.projectId}`,
+ expect(start.request).toMatchObject({ conversationId: chat.id, machineId: 'peer-mac', engine: 'claude', cwd: `/swarm/${f.app.projectId}`,
worktree: true, name: 'peer\'s Buddy', buddyOf: { personId: 'peer', generation: 'first' } })
expect(start.request.role).toBeUndefined()
})
@@ -586,13 +602,11 @@ describe('where a Buddy runs (Ken\'s ruling, 10-28)', () => {
const add = (f: ReturnType<typeof setup>, machineId: string, owner: string, engine: 'claude' | 'codex' = 'claude', projectId = f.app.projectId) =>
f.run({ type: 'buddy.create', projectId, machineId, engine }, peer, contribution(f, machineId, owner))
- it('is only its owner\'s own machine, for Claude and Codex alike: never one shared with them', () => {
+ it('is only its owner\'s own machine: never one shared with them', () => {
const f = fresh()
machine(f, 'owner-mac', 'owner')
- for (const engine of ['claude', 'codex'] as const) {
- expect(() => add(f, 'owner-mac', 'owner', engine)).toThrow('A Buddy runs only on your own machine')
- }
- expect(add(f, 'peer-mac', 'peer', 'codex').result.startId).toBeTruthy()
+ expect(() => add(f, 'owner-mac', 'owner')).toThrow('A Buddy runs only on your own machine')
+ expect(add(f, 'peer-mac', 'peer').result.startId).toBeTruthy()
})
it('is never a Harness Team account, not even the one on its owner\'s own Mac', () => {
diff --git a/backend/src/superTabs/buddyContract.ts b/backend/src/superTabs/buddyContract.ts
new file mode 100644
index 000000000..8a2121ffd
--- /dev/null
+++ b/backend/src/superTabs/buddyContract.ts
@@ -0,0 +1,8 @@
+/**
+ * What Desktop shows of the server's Buddy rules, kept in one file it reads too: Desktop's CI checks out this file alone
+ * of the backend (.github/workflows/ci.yml, scripts/record-ci-validation.py), and test/buddy_refusal_parity_test.dart
+ * holds Desktop's copy to it.
+ */
+
+/** Why a Codex Buddy is refused for now (commands.ts buddy.create); Desktop shows the same words beside a disabled Codex. */
+export const CODEX_BUDDY_REFUSAL = 'A Codex Buddy is not available yet: Codex would run some commands outside its sandbox without asking. Choose Claude Code.'
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index 68447e114..fc290276f 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -1,6 +1,7 @@
import { admitMachineStart, cleanupOverdue, downSince, expireRemoval, expireRemovals, failTeamWork, removalEnded, machineContribution, machineOffline, ownedMachine, projectFolder, requireTeamWork, teamMachineFor, teamPoolsOf, teamStartRequest, teamWorkCheck, type ContributedMachine } from './machines.js'
import { assignAgentDisplayNames } from './agentNames.js'
import { z } from 'zod'
+import { tokensByModelSchema } from './costs/tokens.js'
import {
activeWork, actorKey, agent, agentRole, appendPullRequestUrls, author, conversation, crossProjectActive, fail, isLeads, person, stableId, syncLeads, numberConversations, nextConversationNumber, renderWorkTask,
finishWorker, requireWorkerDecisions, reviewing, seenMachineIds, swarmGridName, visibleState, AGENT_ONLY,
@@ -27,6 +28,7 @@ import { openReview, openReviewOf, projectPullRequest, verdictPending } from './
import { avatarChoice, setAgentAvatar, setMemberAvatar, setStatus, statusSchema, type AvatarUpload } from './profile.js'
import { agentKind, agentProjectId, audienceOf, agentSetRole, canReadProject, deleteProject, markConfidential, requireSingleRegistration, groupProject, inviteLanding, ledProject, manageProject, MAX_ROLES, mutableProjects, placeRules, projectMembers, projectOf, projectRules, projectsOf, readAgent, readConversation, readProject, roleVersion, sameProject, sharedWithLeads, SKILL_SET_NAMES, skillSetOf, type ProjectRole, type RoleKind, type SwarmProject } from './projects.js'
import { BUDDY_REQUIREMENTS, buddyChatId, buddyReady, isBuddy, isBuddyChat, MAX_PROPOSAL_ASKS, PROPOSAL_ASK_MS, proposalText, requireBuddyCommand } from './buddies.js'
+import { CODEX_BUDDY_REFUSAL } from './buddyContract.js'
const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)
const title = z.string().trim().min(1).max(160)
@@ -173,7 +175,9 @@ export const commandSchema = z.discriminatedUnion('type', [
z.object({ type: z.literal('work.status'), conversationId: id, assignmentId: id,
status: z.enum(['working', 'needs_human', 'blocked', 'review', 'done', 'stopped']), result: text.nullable(),
// A worker's question for one named person, opened as a decision (decisions.ts); the result is the question.
- ask: decisionChoices.extend({ personId: id }).strict().optional() }).strict(),
+ ask: decisionChoices.extend({ personId: id }).strict().optional(),
+ // Its session's token totals by model, read by its host as it finishes (Done, Stopped): the attempt's end (costs/attempts.ts).
+ tokens: tokensByModelSchema.optional() }).strict(),
z.object({ type: z.literal('work.cancel'), conversationId: id, assignmentId: id, reason }).strict(),
// `lostAt` names the loss being resumed (Assignment.lost.at): one task can be lost to a limit, resumed and lost again.
z.object({ type: z.literal('work.resume'), conversationId: id, assignmentId: id, lostAt: z.number().int().nonnegative().safe() }).strict(),
@@ -1382,6 +1386,11 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
if (actor.kind !== 'person') fail('BUDDY_PERSON', 'A person adds their own Buddy.', 403)
if (!state.buddies) fail('BUDDIES_OFF', 'Buddies are off in this Swarm. Its owner can turn them on.', 403)
if (state.paused) fail('PAUSED', 'New work is paused in this Super Tab.')
+ // Codex runs a command its rules files allow outside its sandbox without asking, and those are the person's own and
+ // Harness's, shared by all their Codex sessions: a Buddy could run harness new or send, or anything they once told
+ // Codex to always allow. Refused here, so every machine refuses whatever its CLI, until a Buddy has a Codex home of
+ // its own (security review 1 of #2087). Desktop names this reason beside a disabled Codex.
+ if (command.engine === 'codex') fail('BUDDY_ENGINE', CODEX_BUDDY_REFUSAL, 403)
const project = readProject(state, actor, command.projectId), me = person(state, actor.userId)
const chatId = buddyChatId(project.id, me)
// A down Buddy is replaced (Desktop's Start again, review of #1992): its session closes in this same command, so a
diff --git a/backend/src/superTabs/costs/attempts.test.ts b/backend/src/superTabs/costs/attempts.test.ts
new file mode 100644
index 000000000..139dedf62
--- /dev/null
+++ b/backend/src/superTabs/costs/attempts.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest'
+import type { Assignment, Conversation, SuperTabState } from '../model.js'
+import { attemptChanges, attemptTokens, endRun, startRun, type RouteRun } from './attempts.js'
+
+const opus = (input: number, output = 0) => ({ input, output, cacheRead: 0, cacheWrite: 0 })
+const config = { engine: 'claude', model: 'opus', effort: 'high', contextWindow: null, engineVersion: null }
+const assignment = (over: Partial<Assignment> = {}): Assignment => ({ id: 'a1', agentId: 'w', status: 'working', configuration: config,
+ execution: { machineId: 'm1', harnessId: 'h1', machineOwnerId: 'owner' }, result: null, ...over })
+const group = (task: Assignment | null, id = 'g1') => ({ id, assignment: task }) as Conversation
+function swarm(over: { quotas?: unknown[]; tokens?: Record<string, Record<string, ReturnType<typeof opus>>>; localModels?: unknown[]; gridModel?: string;
+ conversations?: Conversation[]; agentConfig?: typeof config } = {}): SuperTabState {
+ return { agents: [{ id: 'w', machineId: 'm1', harnessId: 'h1', configuration: over.agentConfig ?? config, ...(over.gridModel ? { gridModel: over.gridModel } : {}) }],
+ conversations: over.conversations ?? [],
+ machines: [{ machineId: 'm1', observation: { receivedAt: 1, quotas: over.quotas ?? [], runningHarnessIds: ['h1'], stoppedHarnessIds: [],
+ ...(over.tokens ? { harnessTokens: over.tokens } : {}) } },
+ { machineId: 'm2', observation: { receivedAt: 1, quotas: [], runningHarnessIds: [], stoppedHarnessIds: [], ...(over.localModels ? { localModels: over.localModels } : {}) } }],
+ } as unknown as SuperTabState
+}
+
+describe('which attempts started, ended or resumed in a write', () => {
+ it('finds a new assignment, one that ended (lost apart), one replaced or removed while active, and a lost one resumed', () => {
+ const before = [group(assignment({ id: 'done' }), 'g1'), group(assignment({ id: 'lost' }), 'g2'), group(assignment({ id: 'gone' }), 'g3'),
+ group(assignment({ id: 'resumed', status: 'lost' }), 'g4'), group(assignment({ id: 'old', status: 'done' }), 'g5'), group(assignment({ id: 'still' }), 'g6')]
+ const after = swarm({ conversations: [group(assignment({ id: 'done', status: 'done' }), 'g1'), group(assignment({ id: 'lost', status: 'lost' }), 'g2'),
+ group(assignment({ id: 'resumed', status: 'working' }), 'g4'), group(assignment({ id: 'new' }), 'g5'), group(assignment({ id: 'still', status: 'review' }), 'g6')] })
+ const changes = attemptChanges(before, after)
+ expect(changes.started.map(a => a.id)).toEqual(['new'])
+ expect(changes.ended.map(e => [e.assignment.id, e.outcome])).toEqual([['done', null], ['lost', 'lost'], ['gone', 'superseded']])
+ expect(changes.resumed.map(a => a.id)).toEqual(['resumed'])
+ })
+
+ it('sees nothing when no attempt changed', () => {
+ const before = [group(assignment()), group(null, 'g2')]
+ expect(attemptChanges(before, swarm({ conversations: before }))).toEqual({ started: [], ended: [], resumed: [] })
+ })
+})
+
+describe('what an attempt ran on and how it was paid', () => {
+ it('starts from the session totals its machine last reported, with the agent’s model and effort', () => {
+ const run = startRun(swarm({ tokens: { h1: { 'claude-opus-5-5': opus(500) } }, quotas: [{ engine: 'claude', known: true, windows: [{ name: '5-hour', usedPercent: 3, resetsAt: null }] }] }),
+ assignment(), 1000)
+ expect(run).toEqual({ machineId: 'm1', harnessId: 'h1', engine: 'claude', model: 'opus', effort: 'high', billing: 'subscription',
+ startedAt: 1000, start: { 'claude-opus-5-5': opus(500) } })
+ })
+
+ it('pays per token on an engine whose machine reads no plan windows (an API key), and says unknown when it cannot tell', () => {
+ expect(startRun(swarm({ quotas: [{ engine: 'claude', known: true, windows: [] }] }), assignment(), 1).billing).toBe('api')
+ expect(startRun(swarm({ quotas: [{ engine: 'claude', known: false, windows: [] }] }), assignment(), 1).billing).toBe('unknown')
+ expect(startRun(swarm(), assignment(), 1)).toMatchObject({ billing: 'unknown', start: null })
+ })
+
+ it('names a grid model and pays for it as its servers do: own hardware, a shared API, or unknown when they disagree', () => {
+ const served = (kind: string) => ({ grid: 'swarm-1', model: 'kimi-k3', kind })
+ expect(startRun(swarm({ gridModel: 'kimi-k3', localModels: [served('api')] }), assignment(), 1)).toMatchObject({ grid: 'kimi-k3', billing: 'api' })
+ expect(startRun(swarm({ gridModel: 'kimi-k3', localModels: [served('local')] }), assignment(), 1)).toMatchObject({ grid: 'kimi-k3', billing: 'own-hardware' })
+ expect(startRun(swarm({ gridModel: 'kimi-k3', localModels: [served('local'), served('api')] }), assignment(), 1).billing).toBe('unknown')
+ expect(startRun(swarm({ gridModel: 'kimi-k3' }), assignment(), 1).billing).toBe('unknown')
+ })
+
+ it('ends with the session totals then, the model and effort the agent ran at last, and keeps how it started', () => {
+ const start = startRun(swarm({ tokens: { h1: { 'claude-opus-5-5': opus(500) } } }), assignment(), 1000)
+ const ended = endRun(start, swarm({ tokens: { h1: { 'claude-opus-5-5': opus(900, 40) } }, agentConfig: { ...config, effort: 'max' } }),
+ assignment(), 'w', 5000)
+ expect(ended).toEqual({ ...start, effort: 'max', endedAt: 5000, end: { 'claude-opus-5-5': opus(900, 40) } })
+ })
+
+ it('ends with the totals its machine reported before this write when this write’s report no longer lists the session', () => {
+ const start = startRun(swarm({ tokens: { h1: { m: opus(500) } } }), assignment(), 1000)
+ const ended = endRun(start, swarm(), assignment(), 'w', 5000, swarm({ tokens: { h1: { m: opus(800) } } }))
+ expect(ended).toMatchObject({ endedAt: 5000, end: { m: opus(800) } })
+ expect(endRun(start, swarm({ tokens: { h1: { m: opus(900) } } }), assignment(), 'w', 5000, swarm({ tokens: { h1: { m: opus(800) } } })).end).toEqual({ m: opus(900) })
+ })
+
+ it('ends with the reading its session sent as it finished, and with none (unknown) when it finished without one', () => {
+ const start = startRun(swarm({ tokens: { h1: { m: opus(500) } } }), assignment(), 1000)
+ const stale = swarm({ tokens: { h1: { m: opus(600) } } })
+ expect(endRun(start, stale, assignment(), 'w', 5000, stale, { m: opus(2000) }).end).toEqual({ m: opus(2000) })
+ expect(endRun(start, stale, assignment(), 'w', 5000, stale, null).end).toBeNull()
+ })
+
+ it('starts from nothing when the attempt ends on another session than it began (a replaced terminal)', () => {
+ const start = startRun(swarm({ tokens: { h1: { m: opus(500) } } }), assignment(), 1000)
+ const moved = swarm({ tokens: { h2: { m: opus(30) } } })
+ ;(moved.agents[0] as { harnessId: string }).harnessId = 'h2'
+ const ended = endRun(start, moved, assignment({ execution: { machineId: 'm1', harnessId: 'h2', machineOwnerId: 'owner' } }), 'w', 5000)
+ expect(ended).toMatchObject({ harnessId: 'h2', start: {}, end: { m: opus(30) } })
+ })
+})
+
+describe('an attempt’s tokens', () => {
+ const run = (start: RouteRun['start'], end: RouteRun['end'], over: Partial<RouteRun> = {}): RouteRun => ({ machineId: 'm1', harnessId: 'h1', engine: 'claude',
+ model: 'opus', effort: 'high', billing: 'subscription', startedAt: 1, start, endedAt: 2, end, ...over })
+
+ it('is what the session added during it, by model, taking a counter that went back as restarted', () => {
+ expect(attemptTokens(run({ a: opus(100, 10), b: opus(5) }, { a: opus(150, 30), b: opus(5), c: opus(7, 1) }), false))
+ .toEqual({ a: opus(50, 20), c: opus(7, 1) })
+ expect(attemptTokens(run({ a: opus(100) }, { a: opus(40) }), false)).toEqual({ a: opus(40) })
+ })
+
+ it('counts from zero only for an agent started for it, and is unknown with no reading at either end', () => {
+ expect(attemptTokens(run(null, { a: opus(9) }), true)).toEqual({ a: opus(9) })
+ expect(attemptTokens(run(null, { a: opus(9) }), false)).toBeNull()
+ expect(attemptTokens(run({ a: opus(9) }, null), true)).toBeNull()
+ expect(attemptTokens(run({ a: opus(9) }, undefined), true)).toBeNull()
+ })
+})
diff --git a/backend/src/superTabs/costs/attempts.ts b/backend/src/superTabs/costs/attempts.ts
new file mode 100644
index 000000000..e0450dd4f
--- /dev/null
+++ b/backend/src/superTabs/costs/attempts.ts
@@ -0,0 +1,119 @@
+/**
+ * What each attempt at a Swarm task ran on, how it was paid and how many tokens it used (Dee, 2026-10-29: show "Cheaper", and
+ * route each job to the cheapest harness that still gets it right). Kept on the attempt's route decision (routeDecisions.ts)
+ * and read by costs/read.ts. Pure: the store hands it the states before and after a write.
+ */
+import { activeWork, type Assignment, type Conversation, type SuperTabState } from '../model.js'
+import type { TokensByModel } from './tokens.js'
+
+/** How an attempt's tokens were paid: an engine plan's allowance, per token through an API (an API key, or a grid model a
+ * member shares from one), the Swarm's own GPUs, or unknown. Only `api` is money actually spent per token. */
+export type Billing = 'subscription' | 'api' | 'own-hardware' | 'unknown'
+
+/** One attempt as its route decision keeps it. `start` and `end` are its session's totals by model when it began and ended
+ * (null: no reading); its tokens are the difference (attemptTokens). */
+export interface RouteRun {
+ machineId: string
+ harnessId: string
+ engine: string
+ model: string
+ effort: string
+ /** The model on the Swarm's grid it ran, which its engine never reports (model.ts Agent.gridModel). */
+ grid?: string
+ billing: Billing
+ startedAt: number
+ start: TokensByModel | null
+ endedAt?: number
+ end?: TokensByModel | null
+}
+
+export interface AttemptChanges {
+ started: Assignment[]
+ /** `lost` and `superseded` are outcomes the decision takes from here; the others are closed by the command that ended them
+ * (routeDecisions.ts closeAssignment). */
+ ended: Array<{ assignment: Assignment; outcome: 'lost' | 'superseded' | null }>
+ /** Lost to a usage limit and taken back by the same session (work.resume): the same attempt goes on. */
+ resumed: Assignment[]
+}
+
+/** The attempts a write started, ended or resumed, as store.ts endRuns finds ended work: an active assignment that became
+ * inactive, or that went (its group removed) or was replaced while still active. */
+export function attemptChanges(before: Conversation[], after: SuperTabState): AttemptChanges {
+ const earlier = new Map(before.map(c => [c.id, c.assignment])), later = new Map(after.conversations.map(c => [c.id, c]))
+ const changes: AttemptChanges = { started: [], ended: [], resumed: [] }
+ for (const group of after.conversations) {
+ const now = group.assignment, was = earlier.get(group.id)
+ if (!now) continue
+ if (activeWork(group) && now.id !== was?.id) changes.started.push(now)
+ else if (activeWork(group) && was?.status === 'lost') changes.resumed.push(now)
+ else if (!activeWork(group) && now.id === was?.id && activeWork({ assignment: was } as Conversation)) {
+ changes.ended.push({ assignment: now, outcome: now.status === 'lost' ? 'lost' : null })
+ }
+ }
+ for (const group of before) {
+ if (!activeWork(group)) continue
+ const changed = later.get(group.id)
+ if (!changed || changed.assignment?.id !== group.assignment!.id) changes.ended.push({ assignment: group.assignment!, outcome: 'superseded' })
+ }
+ return changes
+}
+
+const observationOf = (state: SuperTabState, machineId: string) => state.machines?.find(m => m.machineId === machineId)?.observation
+const tokensOf = (state: SuperTabState, machineId: string, harnessId: string): TokensByModel | null =>
+ observationOf(state, machineId)?.harnessTokens?.[harnessId] ?? null
+
+/** A grid model is paid as every machine serving it says: its own GPUs (`local`) or a member's shared API (`api`). Machines
+ * that disagree, or none serving it, leave it unknown rather than guessed. An engine is paid by its plan when its machine
+ * reads plan windows for it, per token when it reads it as known with none (an API key, cli superTabs/capacity.ts). */
+function billingOf(state: SuperTabState, machineId: string, engine: string, grid: string | undefined): Billing {
+ if (grid) {
+ const kinds = new Set((state.machines ?? []).flatMap(m => (m.observation?.localModels ?? []).filter(s => s.model === grid).map(s => s.kind)))
+ if (kinds.size !== 1) return 'unknown'
+ const [kind] = kinds
+ return kind === 'local' ? 'own-hardware' : kind === 'api' ? 'api' : 'unknown'
+ }
+ const quota = observationOf(state, machineId)?.quotas.find(q => q.engine === engine)
+ return !quota?.known ? 'unknown' : quota.windows.length ? 'subscription' : 'api'
+}
+
+function ranOn(state: SuperTabState, assignment: Assignment, agentId: string) {
+ const agent = state.agents.find(a => a.id === agentId)
+ const configuration = agent?.configuration ?? assignment.configuration
+ return { engine: configuration.engine, model: configuration.model ?? 'unknown', effort: configuration.effort ?? 'unknown',
+ ...(agent?.gridModel ? { grid: agent.gridModel } : {}) }
+}
+
+export function startRun(state: SuperTabState, assignment: Assignment, now: number): RouteRun {
+ const { machineId, harnessId } = assignment.execution
+ const ran = ranOn(state, assignment, assignment.agentId)
+ return { machineId, harnessId, ...ran, billing: billingOf(state, machineId, ran.engine, ran.grid), startedAt: now, start: tokensOf(state, machineId, harnessId) }
+}
+
+/** Its end, and the model and effort its agent ran at last. An agent that finishes its own work (Done, Stopped) sends its
+ * session's totals read as it finishes (`final`); finished without them (an older host, or a Lead finishing it) its end is
+ * unknown (null), never the last report's: that can be a report old and price real work at nothing (review of #2106). Other
+ * ends (lost, cancelled, its host's stop) take the totals its machine last reported; the report that says a session
+ * stopped no longer lists it, so then those reported before this write (`before`). A session replaced during the attempt
+ * (agent.rebind) counts from zero, so only the new session's tokens are counted. */
+export function endRun(run: RouteRun, state: SuperTabState, assignment: Assignment, agentId: string, now: number, before?: SuperTabState,
+ final?: TokensByModel | null): RouteRun {
+ const { machineId, harnessId } = assignment.execution
+ const { engine: _engine, grid: _grid, ...ran } = ranOn(state, assignment, agentId)
+ const end = final !== undefined ? final : tokensOf(state, machineId, harnessId) ?? (before ? tokensOf(before, machineId, harnessId) : null)
+ return { ...run, ...ran, ...(harnessId !== run.harnessId ? { harnessId, start: {} } : {}), endedAt: now, end }
+}
+
+/** The tokens the attempt used, by model: its session's end totals less its start totals. A count lower at the end than at the
+ * start restarted (a new transcript), so the end is all of it. With no start reading it counts from zero only for an agent
+ * started for this attempt (`fresh`); with no end reading it is unknown. */
+export function attemptTokens(run: RouteRun, fresh: boolean): TokensByModel | null {
+ if (!run.end || (!run.start && !fresh)) return null
+ const used: TokensByModel = {}
+ for (const [model, end] of Object.entries(run.end)) {
+ const start = run.start?.[model]
+ const delta = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+ for (const key of Object.keys(delta) as Array<keyof typeof delta>) delta[key] = start && end[key] >= start[key] ? end[key] - start[key] : end[key]
+ if (Object.values(delta).some(n => n > 0)) used[model] = delta
+ }
+ return used
+}
diff --git a/backend/src/superTabs/costs/cost.test.ts b/backend/src/superTabs/costs/cost.test.ts
new file mode 100644
index 000000000..c848ae05f
--- /dev/null
+++ b/backend/src/superTabs/costs/cost.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import type { RouteRun } from './attempts.js'
+import { attemptCost } from './cost.js'
+import { PRICES, priceOf } from './prices.js'
+
+const run = (over: Partial<RouteRun> = {}): RouteRun => ({ machineId: 'm', harnessId: 'h', engine: 'claude', model: 'opus', effort: 'high',
+ billing: 'subscription', startedAt: 1, start: {}, endedAt: 2, end: {}, ...over })
+const tokens = (input: number, output: number, cacheRead = 0, cacheWrite = 0) => ({ input, output, cacheRead, cacheWrite })
+
+describe('the reviewed price table', () => {
+ it('gives every model a source link and the date it was checked, in dollars per million tokens', () => {
+ for (const price of PRICES) {
+ expect(price.source, price.model).toMatch(/^https:\/\//)
+ expect(price.checked, price.model).toMatch(/^\d{4}-\d{2}-\d{2}$/)
+ for (const n of [price.input, price.output, price.cacheRead, price.cacheWrite]) expect(n).toBeGreaterThanOrEqual(0)
+ }
+ expect(new Set(PRICES.map(p => p.model)).size).toBe(PRICES.length)
+ })
+
+ it('finds a model by its exact id or a dated release of it, and nothing for a model it does not list', () => {
+ expect(priceOf('claude-opus-5-5')).toMatchObject({ input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 })
+ expect(priceOf('claude-opus-5-5-20261001')?.model).toBe('claude-opus-5-5')
+ expect(priceOf('claude-opus-5-5-preview')).toBeUndefined()
+ expect(priceOf('claude-haiku-5-5')).toBeUndefined()
+ expect(priceOf('unknown')).toBeUndefined()
+ })
+})
+
+describe('an attempt’s cost', () => {
+ it('prices each model’s tokens at its list price: API-equivalent cost, and no spend on a subscription', () => {
+ // Opus 5.5: 1M input $4, 0.5M output $10, 2M cache reads $0.40, 0.2M cache writes $1. Sonnet 5.5: 1M output $10.
+ const cost = attemptCost(run({ end: { 'claude-opus-5-5': tokens(1e6, 5e5, 2e6, 2e5), 'claude-sonnet-5-5': tokens(0, 1e6) } }), true)
+ expect(cost.apiCost).toBeCloseTo(25.4, 10)
+ expect(cost).toMatchObject({ spend: 0, priced: 'list' })
+ })
+
+ it('is money spent when the attempt paid per token', () => {
+ expect(attemptCost(run({ billing: 'api', end: { 'gpt-6.1-sol': tokens(1e6, 1e6, 1e6) } }), true)).toEqual({ apiCost: 12.1, spend: 12.1, priced: 'list' })
+ })
+
+ it('prices a grid model at its API’s rates whatever its transcript calls it, and costs nothing on the Swarm’s own GPUs', () => {
+ const grid = run({ grid: 'moonshotai/kimi-k3', billing: 'api', end: { 'kimi-k3-0905': tokens(1e6, 1e6) } })
+ expect(attemptCost(grid, true).apiCost).toBeCloseTo(20.192, 10)
+ expect(attemptCost({ ...grid, billing: 'own-hardware' }, true)).toEqual({ apiCost: 0, spend: 0, priced: 'own-hardware' })
+ })
+
+ it('has no cost, never a guess, for a model without a price or tokens it never read; spend unknown with unknown billing', () => {
+ expect(attemptCost(run({ end: { 'claude-opus-5-5': tokens(1, 1), 'mystery-model': tokens(1, 1) } }), true)).toEqual({ apiCost: null, spend: null, priced: 'unpriced-model' })
+ expect(attemptCost(run({ end: null }), true)).toEqual({ apiCost: null, spend: null, priced: 'no-tokens' })
+ expect(attemptCost(run({ start: null, end: { 'claude-opus-5-5': tokens(1e6, 0) } }), false)).toMatchObject({ apiCost: null, priced: 'no-tokens' })
+ expect(attemptCost(run({ billing: 'unknown', end: { 'claude-opus-5-5': tokens(1e6, 0) } }), true)).toEqual({ apiCost: 4, spend: null, priced: 'list' })
+ })
+})
diff --git a/backend/src/superTabs/costs/cost.ts b/backend/src/superTabs/costs/cost.ts
new file mode 100644
index 000000000..947ac723e
--- /dev/null
+++ b/backend/src/superTabs/costs/cost.ts
@@ -0,0 +1,28 @@
+/** What an attempt cost: its tokens (costs/attempts.ts) at the list prices (costs/prices.ts). */
+import { attemptTokens, type RouteRun } from './attempts.js'
+import { priceOf } from './prices.js'
+
+export interface AttemptCost {
+ /** What its tokens would have cost on the API, in US dollars; 0 on the Swarm's own GPUs; null when not known. */
+ apiCost: number | null
+ /** Money actually spent per token: its API cost when it paid per token, 0 on a plan or own GPUs, null when not known. */
+ spend: number | null
+ /** How the cost was found: list prices, own hardware, or why there is none (a model without a price, no token reading). */
+ priced: 'list' | 'own-hardware' | 'unpriced-model' | 'no-tokens'
+}
+
+/** `fresh`: the agent was started for this attempt, so with no start reading its tokens count from zero (attemptTokens). */
+export function attemptCost(run: RouteRun, fresh: boolean): AttemptCost {
+ if (run.billing === 'own-hardware') return { apiCost: 0, spend: 0, priced: 'own-hardware' }
+ const used = attemptTokens(run, fresh)
+ if (!used) return { apiCost: null, spend: null, priced: 'no-tokens' }
+ let apiCost = 0
+ for (const [model, t] of Object.entries(used)) {
+ // A grid model's transcript names whatever its API answered as; the Swarm knows which model it started.
+ const price = priceOf(run.grid ?? model)
+ if (!price) return { apiCost: null, spend: null, priced: 'unpriced-model' }
+ apiCost += (t.input * price.input + t.output * price.output + t.cacheRead * price.cacheRead + t.cacheWrite * price.cacheWrite) / 1e6
+ }
+ const spend = run.billing === 'api' ? apiCost : run.billing === 'subscription' ? 0 : null
+ return { apiCost, spend, priced: 'list' }
+}
diff --git a/backend/src/superTabs/costs/prices.ts b/backend/src/superTabs/costs/prices.ts
new file mode 100644
index 000000000..4e94a958c
--- /dev/null
+++ b/backend/src/superTabs/costs/prices.ts
@@ -0,0 +1,38 @@
+/**
+ * API list prices, in US dollars per million tokens, for the models Swarm attempts run on: what an attempt would have cost
+ * on the API (costs/cost.ts). Reviewed by hand; each row names its source and the day it was read. A model not listed has
+ * no cost, never a guessed one. To add or update one, read its provider's own price page and change its row here.
+ *
+ * - Cache writes are the 5-minute rate: transcripts do not say which cache a write went to, so 1-hour writes count low.
+ * - Claude Haiku 5.5 is left out on purpose: its rate doubles past 100,000 prompt tokens, which the counts cannot tell.
+ * - gpt-6.1-sol is its rate up to 272K input tokens; longer prompts cost more.
+ * - Grid models are priced at OpenRouter's rates, which is how the Swarm reaches them (Lead, 2026-10-29). DeepSeek's
+ * off-peak hours are half this rate, so its cost is an upper bound.
+ */
+export interface ModelPrice {
+ model: string
+ input: number
+ output: number
+ cacheRead: number
+ cacheWrite: number
+ source: string
+ /** The day the source was read, YYYY-MM-DD. */
+ checked: string
+}
+
+const ANTHROPIC = 'https://platform.claude.com/docs/en/about-claude/pricing'
+const OPENAI = 'https://developers.openai.com/api/docs/pricing'
+const OPENROUTER = 'https://openrouter.ai/api/v1/models'
+
+export const PRICES: readonly ModelPrice[] = [
+ { model: 'claude-fable-5-1', input: 10, output: 50, cacheRead: 0.25, cacheWrite: 12.5, source: ANTHROPIC, checked: '2026-10-29' },
+ { model: 'claude-opus-5-5', input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5, source: ANTHROPIC, checked: '2026-10-29' },
+ { model: 'claude-sonnet-5-5', input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5, source: ANTHROPIC, checked: '2026-10-29' },
+ { model: 'gpt-6.1-sol', input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5, source: OPENAI, checked: '2026-10-29' },
+ { model: 'moonshotai/kimi-k3', input: 0.192, output: 20, cacheRead: 0.182, cacheWrite: 0, source: OPENROUTER, checked: '2026-10-29' },
+ { model: 'deepseek/deepseek-v4.1-flash-1017', input: 0.3, output: 1.2, cacheRead: 0.006, cacheWrite: 0, source: OPENROUTER, checked: '2026-10-29' },
+]
+
+const byModel = new Map(PRICES.map(p => [p.model, p]))
+/** A model's price by its exact id, or by a dated release of it (`claude-opus-5-5-20261001`). */
+export const priceOf = (model: string): ModelPrice | undefined => byModel.get(model) ?? byModel.get(model.replace(/-\d{8}$/, ''))
diff --git a/backend/src/superTabs/costs/read.test.ts b/backend/src/superTabs/costs/read.test.ts
new file mode 100644
index 000000000..217150279
--- /dev/null
+++ b/backend/src/superTabs/costs/read.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import type { Conversation } from '../model.js'
+import type { RouteRun } from './attempts.js'
+import { summarizeCosts, type CostRow } from './read.js'
+
+const MINUTE = 60_000
+const t = (input: number, output: number) => ({ input, output, cacheRead: 0, cacheWrite: 0 })
+const run = (over: Partial<RouteRun> = {}): RouteRun => ({ machineId: 'm', harnessId: 'h', engine: 'claude', model: 'opus', effort: 'high',
+ billing: 'subscription', startedAt: 0, start: {}, endedAt: 30 * MINUTE, end: { 'claude-opus-5-5': t(1e6, 0) }, ...over })
+const row = (assignmentId: string, over: Partial<CostRow> = {}): CostRow => ({ conversationId: 'g1', assignmentId, outcome: 'done',
+ kind: 'parser', fresh: false, run: run(), ...over })
+const group = (id: string, runs: Array<{ assignmentId: string; firstReview?: boolean }>, shippedAt?: number) => ({ id,
+ ledger: { runs: runs.map(r => ({ engine: 'claude', model: 'opus', at: 0, ...r })), ...(shippedAt === undefined ? {} : { shippedAt }) } }) as Conversation
+
+describe('the cost summary', () => {
+ it('groups attempts by engine, model, effort and kind with pass rate, shipped, median time to ship, tokens and costs', () => {
+ const rows = [
+ row('a1', { run: run({ endedAt: 10 * MINUTE }) }),
+ row('a2', { conversationId: 'g2', outcome: 'lost', run: run({ end: { 'claude-opus-5-5': t(5e5, 0) } }) }),
+ row('a3', { conversationId: 'g3', run: run({ endedAt: 50 * MINUTE, billing: 'api' }) }),
+ row('a4', { conversationId: 'g4', kind: null, run: run({ effort: 'xhigh' }) }),
+ ]
+ const summary = summarizeCosts(rows, [group('g1', [{ assignmentId: 'a1', firstReview: true }], 10 * MINUTE),
+ group('g2', [{ assignmentId: 'a2', firstReview: false }]), group('g3', [{ assignmentId: 'a3' }], 50 * MINUTE), group('g4', [], 30 * MINUTE)])
+ expect(summary.rows).toEqual([
+ { engine: 'claude', model: 'opus', effort: 'high', kind: 'parser', attempts: 3, firstReviews: 2, firstReviewPassed: 1, firstReviewPassRate: 0.5,
+ shipped: 2, outcomes: { done: 2, lost: 1 }, billing: { subscription: 2, api: 1 }, medianMinutesToShip: 30,
+ tokens: { input: 2.5e6, output: 0, cacheRead: 0, cacheWrite: 0 }, tokensKnown: 3, apiCost: 10, spend: 4, costKnown: 3, costPerShipped: 5 },
+ { engine: 'claude', model: 'opus', effort: 'xhigh', kind: 'unspecified', attempts: 1, firstReviews: 0, firstReviewPassed: 0, firstReviewPassRate: null,
+ shipped: 1, outcomes: { done: 1 }, billing: { subscription: 1 }, medianMinutesToShip: 30,
+ tokens: { input: 1e6, output: 0, cacheRead: 0, cacheWrite: 0 }, tokensKnown: 1, apiCost: 4, spend: 0, costKnown: 1, costPerShipped: 4 },
+ ])
+ expect(summary.totals).toMatchObject({ attempts: 4, shipped: 3, apiCost: 14, spend: 4, costPerShipped: 14 / 3 })
+ })
+
+ it('ships a request once, by the attempt that ran when it shipped, however many attempts were done after', async () => {
+ // Done at 10 minutes, then worked on and done again: still one shipped change, and both attempts' cost is its cost.
+ const rows = [row('b1', { run: run({ startedAt: 0, endedAt: 10 * MINUTE }) }), row('b2', { run: run({ startedAt: 20 * MINUTE, endedAt: 30 * MINUTE }) })]
+ const summary = summarizeCosts(rows, [group('g1', [], 10 * MINUTE)])
+ expect(summary.rows[0]).toMatchObject({ attempts: 2, shipped: 1, outcomes: { done: 2 }, medianMinutesToShip: 10, apiCost: 8, costPerShipped: 8 })
+ // Its merge recorded before any Done ships it then, by the attempt running at the merge, even one lost afterwards.
+ const merged = summarizeCosts([row('c1', { outcome: 'lost', run: run({ startedAt: 0, endedAt: 40 * MINUTE }) })], [group('g1', [], 25 * MINUTE)])
+ expect(merged.rows[0]).toMatchObject({ shipped: 1, medianMinutesToShip: 25 })
+ // A done attempt of a request with no recorded ship (a group the reader cannot read) ships nothing here.
+ expect(summarizeCosts([row('d1')], []).rows[0]).toMatchObject({ shipped: 0, costPerShipped: null })
+ })
+
+ it('names a grid model by the model it ran, counts open attempts as open, and leaves costs it cannot know out of the sums', () => {
+ const summary = summarizeCosts([
+ row('a1', { outcome: null, run: run({ grid: 'moonshotai/kimi-k3', billing: 'api', endedAt: undefined, end: undefined }) }),
+ row('a2', { run: run({ end: { mystery: t(1, 1) } }) }),
+ row('a3', { run: run({ start: null }) }),
+ ], [])
+ expect(summary.rows.map(r => [r.model, r.attempts, r.outcomes, r.tokensKnown, r.costKnown, r.apiCost, r.costPerShipped])).toEqual([
+ ['moonshotai/kimi-k3', 1, { open: 1 }, 0, 0, null, null],
+ ['opus', 2, { done: 2 }, 1, 0, null, null],
+ ])
+ })
+
+ it('shows which prices it used, with their sources and dates', () => {
+ expect(summarizeCosts([row('a1')], []).prices).toEqual([{ model: 'claude-opus-5-5', source: 'https://platform.claude.com/docs/en/about-claude/pricing', checked: '2026-10-29' }])
+ })
+})
diff --git a/backend/src/superTabs/costs/read.ts b/backend/src/superTabs/costs/read.ts
new file mode 100644
index 000000000..d78fa90a8
--- /dev/null
+++ b/backend/src/superTabs/costs/read.ts
@@ -0,0 +1,143 @@
+/**
+ * The one read of what Swarm attempts cost and how they went (Dee, 2026-10-29): per engine, model, effort and kind of job over
+ * a period. Used by the Lead for the Product Manager, and meant for the leaderboard's Cheaper row and the nightly reflection.
+ * Reads route decisions by their tabId+createdAt index, at most MAX_ROWS of them, and only the groups those name for their
+ * first-review results (leaderboard/record.ts Run, joined by assignment id). Never messages.
+ */
+import type { Prisma } from '@prisma/client'
+import type { Conversation } from '../model.js'
+import { attemptTokens, type Billing, type RouteRun } from './attempts.js'
+import { attemptCost } from './cost.js'
+import { priceOf } from './prices.js'
+import type { ModelTokens } from './tokens.js'
+
+type Tx = Prisma.TransactionClient
+/** Decisions one read takes, newest first: more than a busy Swarm routes in the longest period (about 300 a week, 10-28). */
+export const MAX_ROWS = 3000
+export const MAX_DAYS = 90
+export const DEFAULT_DAYS = 7
+
+/** One attempt as the summary reads it. `fresh`: its agent was started for it (costs/attempts.ts attemptTokens). */
+export interface CostRow { conversationId: string; assignmentId: string; outcome: string | null; kind: string | null; fresh: boolean; run: RouteRun }
+
+/** The attempts routed since `since`: decisions with an assignment and a run, by the tabId+createdAt index. A plain $match,
+ * as recentDecisions does: Prisma's own filters reach Mongo as $expr, which its planner does not serve from the index. Only
+ * the fields the summary needs leave the database; the candidates' lines stay there. */
+export async function costRows(tx: Tx, tabId: string, since: number): Promise<{ rows: CostRow[]; truncated: boolean }> {
+ const found = await tx.superTabRouteDecision.aggregateRaw({ pipeline: [
+ { $match: { tabId, createdAt: { $gte: { $date: new Date(since).toISOString() } } } },
+ { $sort: { createdAt: -1 } }, { $limit: MAX_ROWS + 1 },
+ { $project: { conversationId: 1, assignmentId: 1, outcome: 1, run: 1, 'final.kind': 1, 'record.assessment.kind': 1 } },
+ ] }) as unknown as Array<Record<string, unknown>>
+ const rows = found.slice(0, MAX_ROWS).flatMap(row => {
+ const run = row.run as RouteRun | null | undefined
+ if (!run || typeof row.assignmentId !== 'string') return []
+ const kind = ((row.record as { assessment?: { kind?: unknown } } | undefined)?.assessment?.kind)
+ return [{ conversationId: String(row.conversationId), assignmentId: row.assignmentId, outcome: (row.outcome ?? null) as string | null,
+ kind: typeof kind === 'string' ? kind : null, fresh: (row.final as { kind?: unknown } | null | undefined)?.kind === 'new', run }]
+ })
+ return { rows, truncated: found.length > MAX_ROWS }
+}
+
+export interface CostSummaryRow {
+ engine: string; model: string; effort: string; kind: string
+ attempts: number
+ /** Attempts whose first review has a verdict, and those that passed it; the rate is null with none. */
+ firstReviews: number; firstReviewPassed: number; firstReviewPassRate: number | null
+ /** Requests shipped, each once, by the attempt that ran when it shipped (shipping). */
+ shipped: number
+ /** By how each ended; `open` while still going. */
+ outcomes: Record<string, number>
+ billing: Partial<Record<Billing, number>>
+ /** From the shipping attempt's start to when its request shipped. */
+ medianMinutesToShip: number | null
+ tokens: ModelTokens
+ /** Attempts whose tokens are known: the sums cover only those. */
+ tokensKnown: number
+ /** API-equivalent cost and actual per-token spend in US dollars, summed over the attempts whose cost is known (costKnown);
+ * null with none known. */
+ apiCost: number | null; spend: number | null; costKnown: number
+ /** apiCost over shipped, only when every ended attempt's cost is known: a partial sum would read cheaper than it was. */
+ costPerShipped: number | null
+}
+
+export interface CostSummary {
+ rows: CostSummaryRow[]
+ totals: Omit<CostSummaryRow, 'engine' | 'model' | 'effort' | 'kind'>
+ /** The prices the costs used, with their sources and the day each was read. */
+ prices: Array<{ model: string; source: string; checked: string }>
+}
+
+const median = (values: number[]): number | null => {
+ if (!values.length) return null
+ const sorted = [...values].sort((a, b) => a - b), mid = Math.floor(sorted.length / 2)
+ return sorted.length % 2 ? sorted[mid]! : (sorted[mid - 1]! + sorted[mid]!) / 2
+}
+
+/** Each shipped request's shipping attempt and when it shipped. A request ships once, at its earliest recorded merge or first
+ * Done (leaderboard/record.ts shippedAt), by the attempt that was running then: the latest started by that time. Attempts
+ * done after it ship nothing new; counting each Done had counted one request once per attempt (review of #2106). */
+function shipping(rows: CostRow[], groups: Conversation[]): Map<string, number> {
+ const shipped = new Map<string, number>()
+ for (const group of groups) {
+ const at = group.ledger?.shippedAt
+ if (at === undefined) continue
+ const ran = rows.filter(r => r.conversationId === group.id && r.run.startedAt <= at).sort((a, b) => b.run.startedAt - a.run.startedAt)[0]
+ if (ran) shipped.set(ran.assignmentId, at)
+ }
+ return shipped
+}
+
+function summarize(rows: CostRow[], firstReview: Map<string, boolean>, shippedAt: Map<string, number>, prices: Set<string>): CostSummary['totals'] {
+ const tokens: ModelTokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+ const outcomes: Record<string, number> = {}, billing: Partial<Record<Billing, number>> = {}, toShip: number[] = []
+ let firstReviews = 0, firstReviewPassed = 0, shipped = 0, tokensKnown = 0, costKnown = 0, apiCost = 0, spend = 0, spendKnown = 0, endedUnknown = 0
+ for (const row of rows) {
+ const verdict = firstReview.get(row.assignmentId)
+ if (verdict !== undefined) { firstReviews++; if (verdict) firstReviewPassed++ }
+ const outcome = row.outcome ?? 'open'
+ outcomes[outcome] = (outcomes[outcome] ?? 0) + 1
+ billing[row.run.billing] = (billing[row.run.billing] ?? 0) + 1
+ const at = shippedAt.get(row.assignmentId)
+ if (at !== undefined) {
+ shipped++
+ toShip.push((at - row.run.startedAt) / 60_000)
+ }
+ const used = attemptTokens(row.run, row.fresh)
+ if (used) {
+ tokensKnown++
+ for (const [model, t] of Object.entries(used)) {
+ for (const key of Object.keys(tokens) as Array<keyof ModelTokens>) tokens[key] += t[key]
+ const price = priceOf(row.run.grid ?? model)
+ if (price) prices.add(price.model)
+ }
+ }
+ const cost = attemptCost(row.run, row.fresh)
+ if (cost.apiCost !== null) { costKnown++; apiCost += cost.apiCost }
+ else if (row.outcome !== null) endedUnknown++
+ if (cost.spend !== null) { spendKnown++; spend += cost.spend }
+ }
+ return { attempts: rows.length, firstReviews, firstReviewPassed, firstReviewPassRate: firstReviews ? firstReviewPassed / firstReviews : null,
+ shipped, outcomes, billing, medianMinutesToShip: median(toShip), tokens, tokensKnown,
+ apiCost: costKnown ? apiCost : null, spend: spendKnown ? spend : null, costKnown,
+ costPerShipped: costKnown && shipped && !endedUnknown ? apiCost / shipped : null }
+}
+
+/** The summary of these attempts; `groups` are the groups they belong to, for their ledgers' first reviews. */
+export function summarizeCosts(rows: CostRow[], groups: Conversation[]): CostSummary {
+ const firstReview = new Map<string, boolean>()
+ for (const group of groups) for (const run of group.ledger?.runs ?? []) if (run.firstReview !== undefined) firstReview.set(run.assignmentId, run.firstReview)
+ const keyOf = (row: CostRow) => [row.run.engine, row.run.grid ?? row.run.model, row.run.effort, row.kind ?? 'unspecified'] as const
+ const byKey = new Map<string, CostRow[]>()
+ for (const row of rows) {
+ const key = JSON.stringify(keyOf(row))
+ byKey.set(key, [...byKey.get(key) ?? [], row])
+ }
+ const prices = new Set<string>(), shippedAt = shipping(rows, groups)
+ const summary = [...byKey.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, group]) => {
+ const [engine, model, effort, kind] = keyOf(group[0]!)
+ return { engine, model, effort, kind, ...summarize(group, firstReview, shippedAt, prices) }
+ })
+ return { rows: summary, totals: summarize(rows, firstReview, shippedAt, new Set()),
+ prices: [...prices].sort().map(model => { const p = priceOf(model)!; return { model: p.model, source: p.source, checked: p.checked } }) }
+}
diff --git a/backend/src/superTabs/costs/tokens.ts b/backend/src/superTabs/costs/tokens.ts
new file mode 100644
index 000000000..aa50c54a7
--- /dev/null
+++ b/backend/src/superTabs/costs/tokens.ts
@@ -0,0 +1,18 @@
+/** Token counts by model, as each Swarm machine reports them for its running agents (cli lib/agentUsageWire.ts) and as an
+ * attempt's route decision keeps them (routeDecisions.ts). Counts only: never text, prompts or folders. */
+import { z } from 'zod'
+
+/** A model as the counts name it: the engine's own identifier, or `unknown` (cli lib/agentUsageWire.ts usageModelName). */
+export const MODEL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,119}$/
+/** Models one session counts apart; its host files the rest as `unknown`. */
+export const MAX_MODELS = 16
+/** Swarm agents one machine reports counts for. A machine offers one agent per 2 GB of memory, so even 400 GB is under it. */
+export const MAX_HARNESSES = 200
+
+const count = z.number().int().nonnegative().safe()
+/** Uncached input, output (reasoning included), cache reads and cache writes. */
+export const modelTokensSchema = z.object({ input: count, output: count, cacheRead: count, cacheWrite: count }).strict()
+export const tokensByModelSchema = z.record(z.string().regex(MODEL_NAME), modelTokensSchema)
+ .refine(v => Object.keys(v).length <= MAX_MODELS, `At most ${MAX_MODELS} models.`)
+export type ModelTokens = z.infer<typeof modelTokensSchema>
+export type TokensByModel = Record<string, ModelTokens>
diff --git a/backend/src/superTabs/machines.test.ts b/backend/src/superTabs/machines.test.ts
index 648ba91dc..c6a888c43 100644
--- a/backend/src/superTabs/machines.test.ts
+++ b/backend/src/superTabs/machines.test.ts
@@ -50,6 +50,17 @@ it('accepts what a machine is ready for, and a reading from before it', () => {
expect(machineObservationSchema.safeParse({ ...sent, readiness: { engines: [{ engine: 'claude', installed: 'yes', signedIn: null }] } }).success).toBe(false)
})
+it('accepts each running agent’s token counts by model, counts only and bounded, and a reading from before them', () => {
+ const { receivedAt: _receivedAt, ...sent } = observation
+ const opus = { input: 10, output: 5, cacheRead: 100, cacheWrite: 20 }
+ expect(machineObservationSchema.safeParse({ ...sent, harnessTokens: { h1: { 'claude-opus-5-5': opus, 'gpt-5.5-codex': opus } } }).success).toBe(true)
+ for (const harnessTokens of [{ h1: { 'two words': opus } }, { h1: { m: { ...opus, prompt: 'text' } } }, { h1: { m: { ...opus, input: -1 } } },
+ { h1: { m: { ...opus, output: 1.5 } } }, { h1: { m: { input: 1 } } }, { h1: Object.fromEntries(Array.from({ length: 17 }, (_, i) => [`m${i}`, opus])) },
+ Object.fromEntries(Array.from({ length: 201 }, (_, i) => [`h${i}`, { m: opus }]))]) {
+ expect(machineObservationSchema.safeParse({ ...sent, harnessTokens }).success, JSON.stringify(harnessTokens).slice(0, 80)).toBe(false)
+ }
+})
+
function setup(machine: Partial<ContributedMachine> = {}) {
const state: SuperTabState = createSuperTab('tab', 'Team', { id: 'owner', email: '[email protected]' }, 'test')
state.machines = [{ machineId: 'host', name: 'Studio Mac', contributorId: 'owner', membershipGeneration: 'tab', generation: 'g1',
diff --git a/backend/src/superTabs/machines.ts b/backend/src/superTabs/machines.ts
index 5bef0232b..ceefda36d 100644
--- a/backend/src/superTabs/machines.ts
+++ b/backend/src/superTabs/machines.ts
@@ -1,4 +1,5 @@
import { z } from 'zod'
+import { MAX_HARNESSES, tokensByModelSchema } from './costs/tokens.js'
import { activeWork, fail, person, stableId, type Actor, type Agent, type AgentStart, type AgentStartRequest, type MessageDraft, type SuperTabState } from './model.js'
import { WORKSPACE_LABEL } from './workspaces.js'
import { agentProjectId, canReadProject, groupProject, ledProject, projectsOf, type SwarmProject } from './projects.js'
@@ -99,6 +100,9 @@ export const machineObservationSchema = z.object({ generation: z.string().max(16
/** When each running agent's screen or transcript last changed (epoch ms); its lease renews on recent progress
* (liveness.ts). Absent from hosts before it, whose agents renew by running alone. */
harnessProgress: z.record(z.string().max(160), z.number().int().nonnegative()).refine(v => Object.keys(v).length <= 1000).optional(),
+ /** Each running Swarm agent's token counts by model, as its session totals (costs/tokens.ts). An attempt's tokens are the
+ * difference between its start and its end (routeDecisions.ts). Absent from hosts before it, whose attempts record none. */
+ harnessTokens: z.record(z.string().max(160), tokensByModelSchema).refine(v => Object.keys(v).length <= MAX_HARNESSES).optional(),
/** Whether each running Swarm session's folder has uncommitted changes (git status), for those its host could read.
* Only a session reported clean is ever stopped for being idle (tidy.ts). Absent from hosts before it. */
harnessUncommitted: z.record(z.string().max(160), z.boolean()).refine(v => Object.keys(v).length <= 1000).optional(),
diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.ts
index 82032a7df..7719287be 100644
--- a/backend/src/superTabs/model.ts
+++ b/backend/src/superTabs/model.ts
@@ -562,6 +562,8 @@ export function visibleState(state: SuperTabState, actor: Actor, now = Date.now(
pool.observation.runningHarnessIds = pool.observation.runningHarnessIds.filter(id => harnesses.has(id))
pool.observation.stoppedHarnessIds = pool.observation.stoppedHarnessIds.filter(id => harnesses.has(id))
if (pool.observation.harnessProgress) pool.observation.harnessProgress = Object.fromEntries(Object.entries(pool.observation.harnessProgress).filter(([id]) => harnesses.has(id)))
+ // Each attempt's tokens are read through the cost summary (costs/read.ts), never from the machine's raw counts.
+ delete pool.observation.harnessTokens
if (pool.observation.stoppedReservations) pool.observation.stoppedReservations = pool.observation.stoppedReservations.filter(r => harnesses.has(r.harnessId))
if (pool.observation.preparingStartIds) pool.observation.preparingStartIds = pool.observation.preparingStartIds.filter(id => visible.starts?.some(s => s.id === id))
}
diff --git a/backend/src/superTabs/routeDecisions.test.ts b/backend/src/superTabs/routeDecisions.test.ts
index 783856557..75deed58f 100644
--- a/backend/src/superTabs/routeDecisions.test.ts
+++ b/backend/src/superTabs/routeDecisions.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest'
-import { closeAssignment, writeRouteEffects } from './routeDecisions.js'
+import { closeAssignment, recordAttempts, writeRouteEffects } from './routeDecisions.js'
type Row = Record<string, unknown> & { id: string; tabId: string; conversationId: string; outcome?: string | null }
@@ -71,3 +71,39 @@ describe('route decision persistence', () => {
expect(outcome('next')).toBeNull()
})
})
+
+describe('attempt records on route decisions', () => {
+ const config = { engine: 'claude', model: 'opus', effort: 'high', contextWindow: null, engineVersion: null }
+ const task = (id: string, status = 'working') => ({ id, agentId: 'w', status, configuration: config,
+ execution: { machineId: 'm1', harnessId: 'h1', machineOwnerId: 'owner' }, result: null })
+ const swarm = (conversations: Array<{ id: string; assignment: ReturnType<typeof task> | null }>, input: number) => ({
+ agents: [{ id: 'w', machineId: 'm1', harnessId: 'h1', configuration: config }], conversations,
+ machines: [{ machineId: 'm1', observation: { receivedAt: 1, quotas: [{ engine: 'claude', known: true, windows: [{ name: '5-hour', usedPercent: 1, resetsAt: null }] }],
+ runningHarnessIds: ['h1'], stoppedHarnessIds: [], harnessTokens: { h1: { 'claude-opus-5-5': { input, output: 0, cacheRead: 0, cacheWrite: 0 } } } } }],
+ }) as never
+ const tokens = (input: number) => ({ 'claude-opus-5-5': { input, output: 0, cacheRead: 0, cacheWrite: 0 } })
+
+ it('starts the run of a new attempt, ends it as lost, reopens it on resume, and ends it again with the real outcome left to its command', async () => {
+ const rows: Row[] = [{ id: 'd1', tabId: 'tab', conversationId: 'g1', assignmentId: 'a1', outcome: null, createdAt: new Date(5) }]
+ const tx = memoryTx(rows)
+ await recordAttempts(tx, 'tab', swarm([{ id: 'g1', assignment: null }], 0), swarm([{ id: 'g1', assignment: task('a1') }], 100), 1000)
+ expect(rows[0]!.run).toEqual({ machineId: 'm1', harnessId: 'h1', engine: 'claude', model: 'opus', effort: 'high', billing: 'subscription',
+ startedAt: 1000, start: tokens(100) })
+ await recordAttempts(tx, 'tab', swarm([{ id: 'g1', assignment: task('a1') }], 0), swarm([{ id: 'g1', assignment: task('a1', 'lost') }], 400), 2000)
+ expect(rows[0]).toMatchObject({ outcome: 'lost', outcomeAt: new Date(2000), run: { endedAt: 2000, end: tokens(400), start: tokens(100) } })
+ await recordAttempts(tx, 'tab', swarm([{ id: 'g1', assignment: task('a1', 'lost') }], 0), swarm([{ id: 'g1', assignment: task('a1') }], 400), 3000)
+ expect(rows[0]).toMatchObject({ outcome: null, outcomeAt: null })
+ await recordAttempts(tx, 'tab', swarm([{ id: 'g1', assignment: task('a1') }], 0), swarm([{ id: 'g1', assignment: task('a1', 'done') }], 900), 4000)
+ expect(rows[0]).toMatchObject({ outcome: null, run: { endedAt: 4000, end: tokens(900) } })
+ })
+
+ it('supersedes an open attempt whose group went while it was active, and never reopens or overwrites a closed outcome', async () => {
+ const rows: Row[] = [{ id: 'd1', tabId: 'tab', conversationId: 'g1', assignmentId: 'a1', outcome: null, createdAt: new Date(5) },
+ { id: 'd2', tabId: 'tab', conversationId: 'g2', assignmentId: 'a2', outcome: 'cancelled', createdAt: new Date(5) }]
+ const tx = memoryTx(rows)
+ await recordAttempts(tx, 'tab', swarm([{ id: 'g1', assignment: task('a1') }, { id: 'g2', assignment: task('a2') }], 0), swarm([], 50), 2000)
+ expect(rows.map(r => r.outcome)).toEqual(['superseded', 'cancelled'])
+ // Recorded before runs existed: it ends with what it ran on, its start unknown and taken as when it was routed.
+ expect(rows[0]!.run).toMatchObject({ engine: 'claude', startedAt: 5, start: null, endedAt: 2000, end: tokens(50) })
+ })
+})
diff --git a/backend/src/superTabs/routeDecisions.ts b/backend/src/superTabs/routeDecisions.ts
index d26bd2d96..e45d220aa 100644
--- a/backend/src/superTabs/routeDecisions.ts
+++ b/backend/src/superTabs/routeDecisions.ts
@@ -1,6 +1,9 @@
/** Persistence for route decisions. Called inside SuperTabStore's transactions. */
import type { Prisma, SuperTabRouteDecision } from '@prisma/client'
import { ms } from './parts/light.js'
+import type { SuperTabState } from './model.js'
+import { attemptChanges, endRun, startRun, type RouteRun } from './costs/attempts.js'
+import type { TokensByModel } from './costs/tokens.js'
import { finalMatches, type RouteDecision, type RouteDecisionEffect, type RouteFinal, type RouteOverride, type RouteRecord } from './routeRecord.js'
type Tx = Prisma.TransactionClient
@@ -12,11 +15,16 @@ export const RETENTION_MS = 90 * 24 * 60 * 60_000
export const decisionOf = (row: SuperTabRouteDecision): RouteDecision => ({
id: row.id, conversationId: row.conversationId, record: row.record as unknown as RouteRecord,
final: (row.final ?? null) as unknown as RouteFinal | null, override: (row.override ?? null) as unknown as RouteOverride | null,
- assignmentId: row.assignmentId, outcome: row.outcome,
+ assignmentId: row.assignmentId, outcome: row.outcome, run: (row.run ?? null) as unknown as RouteRun | null,
})
-/** The decision with the times the log shows: when it was recorded and when its outcome was. */
-export const timedDecisionOf = (row: SuperTabRouteDecision) => ({ ...decisionOf(row), createdAt: row.createdAt, outcomeAt: row.outcomeAt })
+/** The decision as its readers get it, with the times the log shows: when it was recorded and when its outcome was. Its run
+ * stays internal: the session totals in it are a member's raw counts, which readers get only summed (costs/read.ts; review
+ * of #2106). */
+export const timedDecisionOf = (row: SuperTabRouteDecision) => {
+ const { run: _run, ...decision } = decisionOf(row)
+ return { ...decision, createdAt: row.createdAt, outcomeAt: row.outcomeAt }
+}
export async function readDecision(tx: Tx, tabId: string, id: string): Promise<RouteDecision | undefined> {
const row = await tx.superTabRouteDecision.findFirst({ where: { id, tabId } })
@@ -31,7 +39,7 @@ export async function recentDecisions(tx: Tx, tabId: string, conversationIds: st
{ $sort: { createdAt: -1 } }, { $limit: 100 }] }) as unknown as Array<Record<string, unknown>>
return rows.map(row => ({ id: row._id as string, tabId: row.tabId as string, conversationId: row.conversationId as string,
record: row.record as Prisma.JsonValue, final: (row.final ?? null) as Prisma.JsonValue, override: (row.override ?? null) as Prisma.JsonValue,
- assignmentId: (row.assignmentId ?? null) as string | null, outcome: (row.outcome ?? null) as string | null,
+ assignmentId: (row.assignmentId ?? null) as string | null, outcome: (row.outcome ?? null) as string | null, run: (row.run ?? null) as Prisma.JsonValue,
outcomeAt: row.outcomeAt == null ? null : new Date(ms(row.outcomeAt)), createdAt: new Date(ms(row.createdAt)) }))
}
@@ -85,3 +93,33 @@ export async function closeUnassignedStart(tx: Tx, tabId: string, decisionId: st
AND: [open, { OR: [{ assignmentId: null }, { assignmentId: { isSet: false } }] }] },
data: { outcome, outcomeAt: new Date(now) } })
}
+
+/**
+ * Keeps each attempt's run on its route decision (costs/attempts.ts) as a write starts, ends or resumes it: how it began when
+ * it is assigned, its end and the totals then when it ends however it ends (a command, a machine's report, the Lead's poll),
+ * and outcome `lost` or `superseded` when that is how it ended. A lost attempt its own session takes back (work.resume) opens
+ * again: it is the same attempt going on. Only decisions with that assignment are touched, by the tabId+assignmentId index.
+ * Runs inside the store's write, after the route effects, so an assignment made in the same write is linked already.
+ */
+/** `finished`: the attempt its own agent finished in this write (Done or Stopped), with the totals it sent, or null when it
+ * sent none (costs/attempts.ts endRun). */
+export async function recordAttempts(tx: Tx, tabId: string, before: SuperTabState, after: SuperTabState, now: number,
+ finished?: { assignmentId: string; tokens: TokensByModel | null }): Promise<void> {
+ const { started, ended, resumed } = attemptChanges(before.conversations, after)
+ for (const assignment of started) {
+ await tx.superTabRouteDecision.updateMany({ where: { tabId, assignmentId: assignment.id }, data: { run: json(startRun(after, assignment, now)) } })
+ }
+ for (const assignment of resumed) {
+ await tx.superTabRouteDecision.updateMany({ where: { tabId, assignmentId: assignment.id, outcome: 'lost' }, data: { outcome: null, outcomeAt: null } })
+ }
+ for (const { assignment, outcome } of ended) {
+ const rows = await tx.superTabRouteDecision.findMany({ where: { tabId, assignmentId: assignment.id }, select: { id: true, run: true, outcome: true, createdAt: true } })
+ for (const row of rows) {
+ // A decision routed before runs were kept: what it ran on is known now, its start tokens never were.
+ const began = (row.run as unknown as RouteRun | null) ?? { ...startRun(after, assignment, now), startedAt: row.createdAt.getTime(), start: null }
+ const close = outcome && row.outcome == null ? { outcome, outcomeAt: new Date(now) } : {}
+ await tx.superTabRouteDecision.update({ where: { id: row.id }, data: { run: json(endRun(began, after, assignment, assignment.agentId, now, before,
+ finished?.assignmentId === assignment.id ? finished.tokens : undefined)), ...close } })
+ }
+ }
+}
diff --git a/backend/src/superTabs/routeRecord.ts b/backend/src/superTabs/routeRecord.ts
index e7cb81760..890e96580 100644
--- a/backend/src/superTabs/routeRecord.ts
+++ b/backend/src/superTabs/routeRecord.ts
@@ -1,5 +1,6 @@
/** What `harness super-tab route` records (docs/superpowers/specs/2026-10-19-super-tab-routing-v1-design.md). */
import { z } from 'zod'
+import type { RouteRun } from './costs/attempts.js'
const level = z.enum(['low', 'medium', 'high'])
const candidateId = z.string().regex(/^c\d{1,2}$/)
@@ -37,7 +38,9 @@ export const routeCandidateSchema = z.object({
}).strict().refine(c => (c.kind === 'member') === !!c.agentId, 'Members name their agent; new agents do not.')
export const routeRecordSchema = z.object({
assessment: z.object({ difficulty: level, risk: level, why: z.string().trim().min(1).max(300),
- size: z.enum(['small', 'medium', 'large']).optional() }).strict(),
+ size: z.enum(['small', 'medium', 'large']).optional(),
+ /** The job's kind the Lead gave (`ui`, `docs`; `review` for a review), what attempts are compared by (costs/read.ts). */
+ kind: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/).optional() }).strict(),
candidates: z.array(routeCandidateSchema).min(1).max(12),
excluded: z.array(z.object({ title: z.string().trim().min(1).max(160), reason: z.string().trim().min(1).max(500) }).strict()).max(200),
floor: z.number().int().min(1).max(3),
@@ -80,6 +83,8 @@ export interface RouteOverride { by: 'lead' | 'person'; actorKey: string; candid
export interface RouteDecision {
id: string; conversationId: string; record: RouteRecord
final: RouteFinal | null; override: RouteOverride | null; assignmentId: string | null; outcome: string | null
+ /** Its attempt's run: what it ran on, how it was paid, its session's token totals at start and end (costs/attempts.ts). */
+ run: RouteRun | null
}
export type RouteDecisionEffect =
| { op: 'create'; id: string; conversationId: string; record: RouteRecord }
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index ec9578120..916b18309 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -46,7 +46,8 @@ import { agentDisplayName } from './agentNames.js'
import { endedHolds, HOLDING, startedHolds, type WorkHold } from '../github/holds.js'
import { accrueLent } from './leaderboard/lent.js'
import { mayDrive, TERMINAL_ANSWER_MS, TERMINAL_EXPIRY_MS, TERMINAL_PICKUP_MS, TERMINAL_RECHECK_MS, type TerminalEffect } from './terminal.js'
-import { closeAssignment, closeUnassignedStart, readDecision, recentDecisions, timedDecisionOf, writeRouteEffects } from './routeDecisions.js'
+import { costRows, summarizeCosts } from './costs/read.js'
+import { closeAssignment, closeUnassignedStart, readDecision, recentDecisions, recordAttempts, timedDecisionOf, writeRouteEffects } from './routeDecisions.js'
import { listMentions, markDone, mentionsWaiting, openTags, readMention, resolveByReply, writeMentions } from './mentions.js'
import { answerable, fullFor, listDecisions, type DecisionList, readAskedDecision, recordAnswer, repeatOf, waitingIn, waitingInProject, writeDecisions } from './decisions.js'
import { DEFAULT_ROUTING_POLICY, effectivePolicy, routingPolicySchema, type RoutingPolicy } from './routingPolicy.js'
@@ -1218,6 +1219,12 @@ export class SuperTabStore {
ended = endedHolds(original, effects.state)
started = startedHolds(original, effects.state)
await writeRouteEffects(tx, tabId, effects.routeDecisions, context.now)
+ // An attempt finished by its own agent ends with the totals its host read as it finished; finished by anyone else, or
+ // without them, its end is unknown (costs/attempts.ts endRun).
+ const finished = command.type === 'work.status' && (command.status === 'done' || command.status === 'stopped') ? {
+ assignmentId: command.assignmentId, tokens: actor.kind === 'agent'
+ && original.conversations.find(c => c.id === command.conversationId)?.assignment?.agentId === actor.agentId ? command.tokens ?? null : null } : undefined
+ await recordAttempts(tx, tabId, original, effects.state, context.now, finished)
if (command.type === 'agent.startFailed') {
const start = original.starts?.find(s => s.id === command.startId)
if (start?.routeDecisionId) await closeUnassignedStart(tx, tabId, start.routeDecisionId, start.id, 'failed', context.now)
@@ -1832,6 +1839,20 @@ export class SuperTabStore {
})
}
+ /** What the attempts routed in the last `days` cost and how they went (costs/read.ts), over the groups the reader may read.
+ * The decisions are read first, by index, so only the groups they name are loaded. */
+ async costSummary(user: AuthUser, tabId: string, days: number, asAgentId?: string) {
+ return transaction(this.db, async tx => {
+ const until = this.now(), since = until - days * 24 * 60 * 60_000
+ const { rows, truncated } = await costRows(tx, tabId, since)
+ const { state } = await this.load(tx, user, tabId, { groupIds: [...new Set(rows.map(r => r.conversationId))] })
+ const actor = await this.actor(tx, user, state, asAgentId)
+ author(state, actor)
+ const readable = state.conversations.filter(c => canReadGroup(state, actor, c)), ids = new Set(readable.map(c => c.id))
+ return { since, until, days, truncated, ...summarizeCosts(rows.filter(r => ids.has(r.conversationId)), readable) }
+ })
+ }
+
async routeDecision(user: AuthUser, tabId: string, decisionId: string, asAgentId?: string) {
return transaction(this.db, async tx => {
const row = await tx.superTabRouteDecision.findFirst({ where: { id: decisionId, tabId }, select: { conversationId: true } })
@@ -1957,6 +1978,7 @@ export class SuperTabStore {
const sequences = numberMessages(state, rows, now)
const touches = judgedMachines(loaded.state, state, rows).filter(t => t.key !== machineId)
await this.endRuns(tx, tabId, loaded.state, state)
+ await recordAttempts(tx, tabId, loaded.state, state, now)
const version = (await this.save(tx, loaded, state, stamp, touches)).versions.get(`machine:${machineId}`) ?? 0
await this.writeMessages(tx, tabId, state, rows, sequences, true)
return { version }
@@ -1966,8 +1988,10 @@ export class SuperTabStore {
const team = isTeamSession(user)
// Its privacy check counts only from the Harness Team account's own session; an ordinary sign-in's claim is dropped.
// Progress is kept for running sessions only: their leases are read from it (liveness.ts).
- const { privacy: reported, harnessProgress, preparingStartIds, ...reading } = observation
+ const { privacy: reported, harnessProgress, harnessTokens, preparingStartIds, ...reading } = observation
const progress = harnessProgress && Object.fromEntries(Object.entries(harnessProgress).filter(([id]) => observation.runningHarnessIds.includes(id)))
+ // Token counts too: an attempt's run reads its session's totals from them (costs/attempts.ts).
+ const tokens = harnessTokens && Object.fromEntries(Object.entries(harnessTokens).filter(([id]) => observation.runningHarnessIds.includes(id)))
// A machine says preparing only of the starts it launched that are neither running nor failed (liveness.ts).
const preparing = preparingStartIds?.filter(id => state.starts?.some(s => s.id === id && s.request.machineId === machineId
&& s.dispatched && !s.harnessId && !s.error))
@@ -1976,6 +2000,7 @@ export class SuperTabStore {
pool.observation = { ...reading, quotas: observation.quotas.filter(q => contributedEngines(pool, observation).includes(q.engine)), receivedAt: now,
// How the machine is signed in, from the session that reported and never from the report (lib/teamSession.ts).
sessionKind: team ? 'team' : 'computer', ...(privacy ? { privacy } : {}), ...(progress ? { harnessProgress: progress } : {}),
+ ...(tokens ? { harnessTokens: tokens } : {}),
...(preparing ? { preparingStartIds: preparing } : {}) }
// Current-generation physical stop proof also finishes a close whose membership was already withdrawn.
for (const proof of observation.stoppedReservations ?? []) {
@@ -2225,6 +2250,7 @@ export class SuperTabStore {
// The poll also frees agents whose task the checks just lost, and any an older server left marked running (each poll; a
// second finds none).
await this.endRuns(tx, tabId, loaded.state, state)
+ await recordAttempts(tx, tabId, loaded.state, state, this.now())
if (ledProject(state, agentId)) {
await this.releaseRuns(tx, tabId, await this.staleRuns(tx, tabId, state))
}
@@ -2415,6 +2441,7 @@ export class SuperTabStore {
// A confirmed stop finishes its worker, as work.status stopped does (design ruling R5).
const project = group ? groupProject(state, group).id : undefined
await this.save(tx, loaded, state, clock.next(), project && state.projects ? [{ kind: 'progress', key: project }] : [])
+ await recordAttempts(tx, tabId, { ...state, conversations: before.conversations }, state, this.now())
await this.writeMessages(tx, tabId, state, notices, sequences)
if (!prior) await tx.superTabStopReceipt.create({ data: { id, tabId, assignmentId, ...execution, receipt } })
ended = endedHolds(before, state)
diff --git a/backend/vitest.super-tabs.config.ts b/backend/vitest.super-tabs.config.ts
index 425392715..20ea33c1c 100644
--- a/backend/vitest.super-tabs.config.ts
+++ b/backend/vitest.super-tabs.config.ts
@@ -3,6 +3,6 @@ import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { include: ['integration/superTabs.test.ts', 'integration/superTabSharing.test.ts', 'integration/superTabGithub.test.ts', 'integration/superTabTeam.test.ts', 'integration/superTabWorkspaces.test.ts',
'integration/superTabRead.test.ts', 'integration/superTabLeaderboard.test.ts', 'integration/superTabMigration.test.ts', 'integration/superTabLiveness.test.ts', 'integration/superTabTidy.test.ts',
'integration/superTabProfile.test.ts', 'integration/superTabLegacyDrop.test.ts', 'integration/shareRaces.test.ts',
- 'integration/superTabIndexes.test.ts', 'integration/superTabHotReads.test.ts', 'integration/superTabGroupPlans.test.ts', 'integration/superTabInvitationPlans.test.ts', 'integration/superTabCache.test.ts', 'integration/superTabObserver.test.ts', 'integration/productUsageConflicts.test.ts', 'integration/schemaRelease.test.ts', 'integration/superTabBuddies.test.ts',
+ 'integration/superTabIndexes.test.ts', 'integration/superTabHotReads.test.ts', 'integration/superTabGroupPlans.test.ts', 'integration/superTabInvitationPlans.test.ts', 'integration/superTabCache.test.ts', 'integration/superTabObserver.test.ts', 'integration/productUsageConflicts.test.ts', 'integration/schemaRelease.test.ts', 'integration/superTabBuddies.test.ts', 'integration/superTabCosts.test.ts',
'integration/harnessSharesList.test.ts'], hookTimeout: 120000, testTimeout: 30000, setupFiles: ['integration/cacheOn.test-support.ts'],
fileParallelism: false, env: { NODE_ENV: 'test', HARNESS_CREDENTIAL_ENCRYPTION_KEY: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' } } })
diff --git a/cli/e2e/harness/socketMeter.ts b/cli/e2e/harness/socketMeter.ts
index 4ccbf639a..11d520ee3 100644
--- a/cli/e2e/harness/socketMeter.ts
+++ b/cli/e2e/harness/socketMeter.ts
@@ -29,6 +29,8 @@ export interface SocketRecord {
closeCode: number | null
closeReason: string
selects: SelectRecord[]
+ /** The meter entry it came through (`entry()`), which tells apart clients that declare the same; null for the main one. */
+ via: string | null
}
export interface RefusalRecord { endpoint: string; status: number; at: number }
@@ -117,8 +119,10 @@ export class SocketMeter {
readonly refused: RefusalRecord[]
private readonly http: Record<string, number>
private startedAt: number
- private server: Server | null = null
+ private readonly servers: Server[] = []
private readonly live = new Set<WebSocket>()
+ private upstream: URL | null = null
+ private wss: WebSocketServer | null = null
url = ''
wsUrl = ''
@@ -142,8 +146,24 @@ export class SocketMeter {
/** Listen on a free loopback port and forward everything to `target` (`http://127.0.0.1:PORT`). */
static async start(target: string): Promise<SocketMeter> {
const meter = new SocketMeter({ startedAt: Date.now(), sockets: [], refused: [], http: {} })
- const upstream = new URL(target)
- const wss = new WebSocketServer({ noServer: true, perMessageDeflate: false, handleProtocols: (set) => [...set][0] ?? false })
+ meter.upstream = new URL(target)
+ meter.wss = new WebSocketServer({ noServer: true, perMessageDeflate: false, handleProtocols: (set) => [...set][0] ?? false })
+ const { url, wsUrl } = await meter.listen(null)
+ meter.url = url
+ meter.wsUrl = wsUrl
+ return meter
+ }
+
+ /** Another way in, on its own port, whose sockets are recorded with `via: name`: one per daemon, which declare the
+ * same client, version and token, so where they dial is what tells them apart. */
+ entry(name: string): Promise<{ url: string; wsUrl: string }> {
+ return this.listen(name)
+ }
+
+ private async listen(via: string | null): Promise<{ url: string; wsUrl: string }> {
+ const meter = this
+ const upstream = this.upstream!
+ const wss = this.wss!
const server = createServer((req, res) => {
count(meter.http, routeOf(req.method ?? 'GET', req.url ?? '/'))
const forward = request({ host: upstream.hostname, port: upstream.port, method: req.method, path: req.url,
@@ -154,17 +174,15 @@ export class SocketMeter {
forward.on('error', () => { if (!res.headersSent) res.writeHead(502); res.end() })
req.pipe(forward)
})
- server.on('upgrade', (req, socket, head) => meter.upgrade(req, socket, head, upstream, wss))
+ server.on('upgrade', (req, socket, head) => meter.upgrade(req, socket, head, upstream, wss, via))
server.listen(0, '127.0.0.1')
await once(server, 'listening')
const port = (server.address() as { port: number }).port
- meter.server = server
- meter.url = `http://127.0.0.1:${port}`
- meter.wsUrl = `ws://127.0.0.1:${port}`
- return meter
+ this.servers.push(server)
+ return { url: `http://127.0.0.1:${port}`, wsUrl: `ws://127.0.0.1:${port}` }
}
- private upgrade(req: IncomingMessage, socket: Duplex, head: Buffer, upstream: URL, wss: WebSocketServer): void {
+ private upgrade(req: IncomingMessage, socket: Duplex, head: Buffer, upstream: URL, wss: WebSocketServer, via: string | null): void {
const query = new URL(req.url ?? '/', 'http://meter').searchParams
const endpoint = (req.url ?? '/').split('?')[0]
let attached = false
@@ -200,14 +218,14 @@ export class SocketMeter {
socket.off('readable', watch)
if (socket.destroyed || socket.readableEnded) { backend.terminate(); return }
attached = true
- wss.handleUpgrade(req, socket, head, (client) => this.attach(client, backend, endpoint, query, early, hold))
+ wss.handleUpgrade(req, socket, head, (client) => this.attach(client, backend, endpoint, query, early, hold, via))
})
}
private attach(client: WebSocket, backend: WebSocket, endpoint: string, query: URLSearchParams,
- early: Array<[RawData, boolean]>, hold: (data: RawData, binary: boolean) => void): void {
+ early: Array<[RawData, boolean]>, hold: (data: RawData, binary: boolean) => void, via: string | null): void {
const record: SocketRecord = { endpoint, ...declaredKind(endpoint, query), openedAt: Date.now(), closedAt: null, closeCode: null,
- closeReason: '', selects: [] }
+ closeReason: '', selects: [], via }
this.sockets.push(record)
this.live.add(client)
const pending = new Map<string, SelectRecord>()
@@ -310,10 +328,10 @@ export class SocketMeter {
async close(): Promise<void> {
for (const ws of this.live) ws.terminate()
- const server = this.server
- if (!server) return
- server.closeAllConnections()
- await new Promise((resolve) => server.close(resolve))
+ await Promise.all(this.servers.splice(0).map((server) => {
+ server.closeAllConnections()
+ return new Promise((resolve) => server.close(resolve))
+ }))
}
}
diff --git a/cli/e2e/harness/socketScenario.ts b/cli/e2e/harness/socketScenario.ts
index a552da37e..e11463731 100644
--- a/cli/e2e/harness/socketScenario.ts
+++ b/cli/e2e/harness/socketScenario.ts
@@ -95,10 +95,13 @@ export class DesktopWindow {
}
/**
- * A browser tab on machine `machineId`: web-ws with `client=web` (ws_conn.dart's query), select, then the
+ * A browser tab on machine `machineId`: web-ws with `client=web` and its version (ws_conn.dart's query), select, then the
* end-to-end hello a paired browser sends. Redials like a window; 4403 stops it, as a sign-in for
* another environment does.
*/
+/** The web build the tab stands for, as it reads its version from the host's release file. */
+const WEB_BUILD_VERSION = '1.3.64'
+
export class WebTab {
dials = 0
sessions = 0
@@ -114,7 +117,8 @@ export class WebTab {
if (this.closing) return
this.dials++
const { wsUrl, token, machineId, identity, machinePub } = this.options
- const ws = new WebSocket(`${wsUrl}/api/web-ws?autonomousEnv=prod&client=web`, [token])
+ // The web build's version rides every socket since Phase 0 (#2029: ws_conn.dart `'v': declaredAppVersion`).
+ const ws = new WebSocket(`${wsUrl}/api/web-ws?autonomousEnv=prod&client=web&v=${WEB_BUILD_VERSION}`, [token])
this.ws = ws
const crypto = new RelaySessionCrypto({ machineId, selfIdentity: identity, peerPub: machinePub, groupSeen: new Map() })
ws.on('error', () => { /* 'close' follows */ })
@@ -161,6 +165,33 @@ export interface ScenarioResult {
backendLog: string
}
+/**
+ * Why the offline machine's retries break the backend's 30 s retry-after, per daemon; empty when they do not. Every
+ * select of it must come through a named daemon's meter entry, and each daemon must have been refused it at least twice
+ * (review of #2104: a daemon that asked once has no gap to measure, and an empty list of gaps passes any minimum).
+ */
+export function offlineRetryProblems(result: ScenarioResult, daemons: readonly string[] = ['a', 'b']): string[] {
+ const problems: string[] = []
+ const selects = result.sockets.filter((s) => s.endpoint === '/api/web-ws').flatMap((s) => s.selects
+ .filter((select) => select.machineId === result.machines.offline).map((select) => ({ ...select, via: s.via })))
+ const unnamed = selects.filter((select) => select.via === null || !daemons.includes(select.via)).length
+ if (unnamed) problems.push(`${unnamed} select(s) of the offline machine came through no named daemon`)
+ for (const daemon of daemons) {
+ const times = selects.filter((select) => select.via === daemon && select.outcome === 'MACHINE_OFFLINE')
+ .map((select) => select.at).sort((x, y) => x - y)
+ if (times.length < 2) {
+ problems.push(`daemon ${daemon} was refused the offline machine ${times.length} time(s): no retry to measure`)
+ continue
+ }
+ // A second of slack for the timers on both sides.
+ for (let i = 1; i < times.length; i++) {
+ const gap = times[i] - times[i - 1]
+ if (gap < 29_000) problems.push(`daemon ${daemon} asked the offline machine again after ${(gap / 1000).toFixed(1)} s`)
+ }
+ }
+ return problems
+}
+
/**
* What a run is missing to prove anything; empty when it did everything it should. Each check on the run also
* passes when nothing happened (no deleted-machine select, no quick redial), so a run that never reached a machine
@@ -187,11 +218,13 @@ async function resolveMachine(backend: RealBackend, who: Account, label: string)
return { machineId: r.body.data.machine.machineId as string, computerId }
}
-/** A daemon signed in as `who` on machine `machine`, dialling the backend through the meter. */
-async function machineDaemon(meter: SocketMeter, who: Account, machine: { machineId: string; computerId: string },
+/** A daemon signed in as `who` on machine `machine`, dialling the backend through its own meter entry, named `name`:
+ * two daemons of one account declare the same client, version and token, and only the entry tells them apart. */
+async function machineDaemon(meter: SocketMeter, name: string, who: Account, machine: { machineId: string; computerId: string },
e2ee: Record<string, unknown>, stops: Array<() => unknown>): Promise<IsolatedDaemon> {
+ const entry = await meter.entry(name)
const daemon = await IsolatedDaemon.create({ env: {
- ADAPTER_COMPUTER_ID: machine.computerId, BACKEND_WS_URL: meter.wsUrl, WEB_URL: meter.url,
+ ADAPTER_COMPUTER_ID: machine.computerId, BACKEND_WS_URL: entry.wsUrl, WEB_URL: entry.url,
HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200' } })
// Before anything else can throw: the daemon's tmux server and folders exist from here on.
stops.push(() => daemon.close())
@@ -222,7 +255,7 @@ export async function runSocketScenario(options: { durationMs: number; log?: (li
const idA = newIdentity(), idB = newIdentity(), tab = newIdentity()
const linkedAt = Date.now()
- const daemonA = await machineDaemon(meter, alice, a, {
+ const daemonA = await machineDaemon(meter, 'a', alice, a, {
'identity.json': { priv: b64e(idA.priv), pub: b64e(idA.pub) },
// Pins as `harness link connect` left them; X's and Y's keys are never used, their selects fail first.
'machinePeers.json': [
@@ -231,7 +264,7 @@ export async function runSocketScenario(options: { durationMs: number; log?: (li
{ machineId: offline.machineId, pub: b64e(newIdentity().pub), label: 'machine-y', linkedAt },
],
}, stops)
- const daemonB = await machineDaemon(meter, alice, b, {
+ const daemonB = await machineDaemon(meter, 'b', alice, b, {
'identity.json': { priv: b64e(idB.priv), pub: b64e(idB.pub) },
'paired.json': [
{ identityPub: b64e(idA.pub), label: 'machine-a', pairedAt: linkedAt, role: 'web', machineId: a.machineId, kind: 'machine' },
diff --git a/cli/e2e/socketChurn.e2e.ts b/cli/e2e/socketChurn.e2e.ts
index 504afc20b..86a7e6715 100644
--- a/cli/e2e/socketChurn.e2e.ts
+++ b/cli/e2e/socketChurn.e2e.ts
@@ -22,7 +22,7 @@
*/
import { writeFileSync } from 'node:fs'
import { beforeAll, describe, expect, it } from 'vitest'
-import { runSocketScenario, shortfalls, type ScenarioResult } from './harness/socketScenario.js'
+import { offlineRetryProblems, runSocketScenario, shortfalls, type ScenarioResult } from './harness/socketScenario.js'
const minutes = Number(process.env.SOCKET_SCENARIO_MINUTES ?? 3)
/** The scenario's daemons, A and B (harness/socketScenario.ts). */
@@ -63,11 +63,11 @@ describe.skipIf(!process.env.HARNESS_E2E_SERVICES_DIR)('WebSocket phases 0 and 1
expect(selectTimes(result.machines.deleted).length).toBeLessThanOrEqual(DAEMONS)
})
- it('Phase 1: an offline machine is selected again only after the backend\'s retryAfterMs (30 s)', () => {
- const times = selectTimes(result.machines.offline)
- const gaps = times.slice(1).map((at, i) => at - times[i])
- // A second of slack for the timers on both sides.
- expect(Math.min(...gaps, Infinity)).toBeGreaterThanOrEqual(29_000)
+ // Per daemon (Lead, 2026-10-29, #2104): each of A and B is told the 30 s, and each waits it out; one daemon's select
+ // a few seconds after the other's is two clients, not a retry. Each must have retried at least once, through its own
+ // named entry, so the check measures something (harness/socketScenario.ts `offlineRetryProblems`).
+ it('Phase 1: each daemon selects an offline machine again only after the backend\'s retryAfterMs (30 s)', () => {
+ expect(offlineRetryProblems(result)).toEqual([])
})
it('Phase 1: no socket that selected a machine is dropped within a minute', () => {
diff --git a/cli/e2e/socketMeter.e2e.ts b/cli/e2e/socketMeter.e2e.ts
index 1974ace83..d5f942449 100644
--- a/cli/e2e/socketMeter.e2e.ts
+++ b/cli/e2e/socketMeter.e2e.ts
@@ -136,6 +136,28 @@ describe('socket meter', () => {
await web.closed
})
+ // Two daemons of one account declare the same client, version and token, so only where they dial tells them apart
+ // (Lead, 2026-10-29): each gets its own entry, and every socket and HTTP request through it carries that name.
+ it('names the entry a socket came through, and forwards it like any other', async () => {
+ const backend = await standIn()
+ stops.push(() => { backend.server.closeAllConnections(); backend.server.close() })
+ const meter = await SocketMeter.start(backend.url)
+ stops.push(() => meter.close())
+ const a = await meter.entry('a')
+ const b = await meter.entry('b')
+
+ const fromA = await dial(`${a.wsUrl}/api/web-ws?autonomousEnv=prod&client=relay&v=1.2.3`)
+ fromA.ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: KNOWN } }))
+ await until('the select answer', () => fromA.frames.length === 2)
+ const fromB = await dial(`${b.wsUrl}/api/web-ws?autonomousEnv=prod&client=relay&v=1.2.3`)
+ const direct = await dial(`${meter.wsUrl}/api/web-ws?autonomousEnv=prod&client=web`)
+ expect(await (await fetch(`${b.url}/api/machines`)).json()).toEqual({ path: '/api/machines', method: 'GET' })
+
+ expect(meter.sockets.map((s) => s.via)).toEqual(['a', 'b', null])
+ expect(meter.sockets[0].selects).toMatchObject([{ machineId: KNOWN, outcome: 'accepted' }])
+ for (const c of [fromA, fromB, direct]) { c.ws.close(); await c.closed }
+ })
+
it('closes its side to the backend when the client gives up before the upgrade completes', async () => {
const backend = await standIn()
stops.push(() => { backend.server.closeAllConnections(); backend.server.close() })
@@ -199,8 +221,8 @@ describe('socket meter', () => {
{ endpoint: '/api/web-ws', client: 'web', version: '2.0.0', openedAt: at + 20_000, closedAt: at + 50_000, closeCode: 1006, closeReason: '',
selects: [{ machineId: KNOWN, at: at + 20_000, outcome: 'accepted' }] },
// A daemon relay that never selected, 90 s.
- { endpoint: '/api/web-ws', client: 'unknown', version: null, openedAt: at, closedAt: at + 90_000, closeCode: 1000, closeReason: '', selects: [] },
- { endpoint: '/api/adapter-ws', client: 'daemon', version: '1.0.0', openedAt: at, closedAt: null, closeCode: null, closeReason: '', selects: [] },
+ { endpoint: '/api/web-ws', client: 'unknown', version: null, openedAt: at, closedAt: at + 90_000, closeCode: 1000, closeReason: '', selects: [], via: null },
+ { endpoint: '/api/adapter-ws', client: 'daemon', version: '1.0.0', openedAt: at, closedAt: null, closeCode: null, closeReason: '', selects: [], via: null },
// Opened before the clock started (the daemons' own start): outside the report.
{ endpoint: '/api/web-ws', client: 'relay', version: '1.0.0', openedAt: at - 5_000, closedAt: at - 4_000, closeCode: 1011, closeReason: '',
selects: [{ machineId: DELETED, at: at - 5_000, outcome: 'NOT_YOUR_MACHINE' }] },
diff --git a/cli/e2e/socketScenarioRan.e2e.ts b/cli/e2e/socketScenarioRan.e2e.ts
index d67ab3b2b..8645cf95b 100644
--- a/cli/e2e/socketScenarioRan.e2e.ts
+++ b/cli/e2e/socketScenarioRan.e2e.ts
@@ -4,7 +4,7 @@
* scenario first proves it ran (harness/socketScenario.ts `shortfalls`), and these are the ways it can fail to.
*/
import { describe, expect, it } from 'vitest'
-import { shortfalls, type ScenarioResult } from './harness/socketScenario.js'
+import { offlineRetryProblems, shortfalls, type ScenarioResult } from './harness/socketScenario.js'
import type { SocketRecord } from './harness/socketMeter.js'
const A = 'a'.repeat(32), B = 'b'.repeat(32), X = 'c'.repeat(32), Y = 'd'.repeat(32)
@@ -12,7 +12,7 @@ const at = 1_000_000
const socket = (client: string, machineId: string, outcome: string): SocketRecord => ({
endpoint: '/api/web-ws', client, version: null, openedAt: at, closedAt: null, closeCode: null, closeReason: '',
- selects: [{ machineId, at, outcome }],
+ selects: [{ machineId, at, outcome }], via: null,
})
/** What a run that did everything it should looks like. */
@@ -57,3 +57,38 @@ describe('the socket scenario proves it ran', () => {
expect(shortfalls(tabOnly)).toEqual(['machine B was never accepted through a daemon relay'])
})
})
+
+describe('the offline check measures each daemon\'s own retries', () => {
+ const offlineSelect = (via: string | null, at: number, outcome = 'MACHINE_OFFLINE'): SocketRecord => ({
+ ...socket('relay', Y, outcome), via, selects: [{ machineId: Y, at, outcome }],
+ })
+ const withOffline = (...sockets: SocketRecord[]): ScenarioResult => {
+ const result = ran()
+ result.sockets = [...result.sockets.filter((s) => s.selects[0].machineId !== Y), ...sockets]
+ return result
+ }
+
+ it('passes when each daemon waited 30 s between its own refusals, however close the two daemons are', () => {
+ expect(offlineRetryProblems(withOffline(offlineSelect('a', at), offlineSelect('b', at + 1),
+ offlineSelect('a', at + 30_000), offlineSelect('b', at + 30_001)))).toEqual([])
+ })
+
+ // Review of #2104: one select per daemon, a millisecond apart, passed, since an empty list of gaps has no minimum.
+ it('fails when a daemon never retried, or never asked', () => {
+ expect(offlineRetryProblems(withOffline(offlineSelect('a', at), offlineSelect('b', at + 1)))).toEqual([
+ 'daemon a was refused the offline machine 1 time(s): no retry to measure',
+ 'daemon b was refused the offline machine 1 time(s): no retry to measure',
+ ])
+ expect(offlineRetryProblems(withOffline(offlineSelect('a', at), offlineSelect('a', at + 30_000)))).toEqual([
+ 'daemon b was refused the offline machine 0 time(s): no retry to measure',
+ ])
+ })
+
+ it('fails on a quick retry, and on a select no daemon is named for', () => {
+ expect(offlineRetryProblems(withOffline(offlineSelect('a', at), offlineSelect('a', at + 15_000),
+ offlineSelect('b', at), offlineSelect('b', at + 30_000), offlineSelect(null, at + 40_000)))).toEqual([
+ '1 select(s) of the offline machine came through no named daemon',
+ 'daemon a asked the offline machine again after 15.0 s',
+ ])
+ })
+})
diff --git a/cli/src/core/agentQueries.spec.ts b/cli/src/core/agentQueries.spec.ts
index 387a40e61..951f5aec0 100644
--- a/cli/src/core/agentQueries.spec.ts
+++ b/cli/src/core/agentQueries.spec.ts
@@ -34,4 +34,12 @@ describe('what a service in its own process may ask the core of the agents', ()
core.usage = async () => ({ totalTokens: 4, updatedAt: '2026-10-01T00:00:00Z' })
expect(await answerAgentQuery(core, 'agentUsage', { target })).toMatchObject({ value: { totalTokens: 4 } })
})
+
+ it('reads a live agent’s usage fresh from its transcript for a Swarm agent finishing its work, and nothing for another', async () => {
+ const core = fakeCore({ agents: { all: () => [...live, ...stopped], live: () => live } })
+ expect(await answerAgentQuery(core, 'agentUsageFresh', { agentId: 'a1' })).toEqual({ value: null })
+ core.usageFresh = async agentId => agentId === 'a1' ? { totalTokens: 9, updatedAt: '2026-10-29T00:00:00Z' } : null
+ expect(await answerAgentQuery(core, 'agentUsageFresh', { agentId: 'a1' })).toEqual({ value: { totalTokens: 9, updatedAt: '2026-10-29T00:00:00Z' } })
+ for (const agentId of ['a3', 'missing', 7]) expect(await answerAgentQuery(core, 'agentUsageFresh', { agentId })).toEqual({ error: 'STALE_USAGE_TARGET' })
+ })
})
diff --git a/cli/src/core/agentQueries.ts b/cli/src/core/agentQueries.ts
index a7cc6bb03..78972c3a1 100644
--- a/cli/src/core/agentQueries.ts
+++ b/cli/src/core/agentQueries.ts
@@ -4,12 +4,19 @@ import { usageTargetKey, usageTarget, validUsageTarget } from '../lib/agentUsage
* when it has no link module of its own to answer it (the viewers and workspaces do):
* - `agents`: every agent, live then stopped, with the name the apps show for it (search indexes them);
* - `live`: the live agents, as `CoreApi.agents.live` answers in the core's process (the project readers);
- * - `advertised`: the live agents the apps are shown (the monitor samples them).
+ * - `advertised`: the live agents the apps are shown (the monitor samples them);
+ * - `agentUsage`: an agent's cached usage reading; `agentUsageFresh`: a live agent's, read now (the Swarm's attempt ends).
* Each is read as it is asked, so the service works from the registry as it is at that moment.
*/
import type { CoreApi } from './api.js'
-export function answerAgentQuery(core: Pick<CoreApi, 'agents' | 'usage'>, query: string, payload: Record<string, unknown> = {}): Record<string, unknown> | Promise<Record<string, unknown>> {
+export function answerAgentQuery(core: Pick<CoreApi, 'agents' | 'usage' | 'usageFresh'>, query: string, payload: Record<string, unknown> = {}): Record<string, unknown> | Promise<Record<string, unknown>> {
+ // A Swarm agent finishing its work: its totals read from its transcript now, so its attempt ends with every token it used,
+ // not the last cached reading (backend superTabs/costs/attempts.ts endRun). Only for a live agent of this machine.
+ if (query === 'agentUsageFresh') {
+ if (typeof payload.agentId !== 'string' || !core.agents.live().some(row => row.agentId === payload.agentId)) return { error: 'STALE_USAGE_TARGET' }
+ return Promise.resolve(core.usageFresh?.(payload.agentId) ?? null).then(value => ({ value }))
+ }
if (query === 'agentUsage') {
const target = payload.target
if (!validUsageTarget(target) || !core.agents.all().some(row => usageTargetKey(row) === usageTargetKey(target))) return { error: 'STALE_USAGE_TARGET' }
diff --git a/cli/src/core/agents/discovery.spec.ts b/cli/src/core/agents/discovery.spec.ts
index 27bbe8571..6b392b398 100644
--- a/cli/src/core/agents/discovery.spec.ts
+++ b/cli/src/core/agents/discovery.spec.ts
@@ -139,6 +139,12 @@ describe('discovery', () => {
expect(mode, 'this fixture must name a mode').not.toBeNull()
})
+ it('tells a Codex Buddy\'s read-only asking mode from plain read only, so a relaunch keeps it asking', () => {
+ expect(permissionModeFromArgv('codex', 'codex --ask-for-approval on-request --sandbox read-only -c approvals_reviewer="user" -c tui.fullscreen_transcript=false'))
+ .toBe('readOnlyAsk')
+ expect(permissionModeFromArgv('codex', 'codex --sandbox read-only')).toBe('readOnly')
+ })
+
it('adopts the engine someone typed into a terminal, and announces it', async () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
diff --git a/cli/src/engines/__fixtures__/launch-argv.golden.json b/cli/src/engines/__fixtures__/launch-argv.golden.json
index 16aeaf008..07e1af868 100644
--- a/cli/src/engines/__fixtures__/launch-argv.golden.json
+++ b/cli/src/engines/__fixtures__/launch-argv.golden.json
@@ -756,6 +756,7 @@
"codex · new, not approving · zsh · tmux": {"argv":["/usr/bin/env","DISABLE_AUTO_UPDATE=true","/bin/zsh","-lic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","-c","tui.fullscreen_transcript=false"],"script":"533ec1354e8b74a3","command":3},
"codex · new, a mode the engine lacks · zsh · tmux": {"argv":["/usr/bin/env","DISABLE_AUTO_UPDATE=true","/bin/zsh","-lic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","--approve-for-me","-c","tui.fullscreen_transcript=false"],"script":"533ec1354e8b74a3","command":4},
"codex · new, mode auto · zsh · tmux": {"argv":["/usr/bin/env","DISABLE_AUTO_UPDATE=true","/bin/zsh","-lic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","--approve-for-me","-c","tui.fullscreen_transcript=false"],"script":"533ec1354e8b74a3","command":4},
+ "codex · new, mode readOnlyAsk · zsh · tmux": {"argv":["/usr/bin/env","DISABLE_AUTO_UPDATE=true","/bin/zsh","-lic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","--ask-for-approval","on-request","--sandbox","read-only","-c","approvals_reviewer=\"user\"","-c","tui.fullscreen_transcript=false"],"script":"533ec1354e8b74a3","command":9},
"codex · new, mode readOnly · zsh · tmux": {"argv":["/usr/bin/env","DISABLE_AUTO_UPDATE=true","/bin/zsh","-lic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","--sandbox","read-only","-c","tui.fullscreen_transcript=false"],"script":"533ec1354e8b74a3","command":5},
"codex · new, mode ask · zsh · tmux": {"argv":["/usr/bin/env","DISABLE_AUTO_UPDATE=true","/bin/zsh","-lic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","-c","tui.fullscreen_transcript=false"],"script":"533ec1354e8b74a3","command":3},
"codex · new, mode full · zsh · tmux": {"argv":["/usr/bin/env","DISABLE_AUTO_UPDATE=true","/bin/zsh","-lic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","--dangerously-bypass-approvals-and-sandbox","-c","tui.fullscreen_transcript=false"],"script":"533ec1354e8b74a3","command":4},
@@ -1066,6 +1067,7 @@
"codex · new, not approving · bash · no tmux": {"argv":["/bin/bash","-ic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","-c","tui.fullscreen_transcript=false"],"script":"585ef6d2032354bb","command":3},
"codex · new, a mode the engine lacks · bash · no tmux": {"argv":["/bin/bash","-ic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","--approve-for-me","-c","tui.fullscreen_transcript=false"],"script":"585ef6d2032354bb","command":4},
"codex · new, mode auto · bash · no tmux": {"argv":["/bin/bash","-ic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","--approve-for-me","-c","tui.fullscreen_transcript=false"],"script":"585ef6d2032354bb","command":4},
+ "codex · new, mode readOnlyAsk · bash · no tmux": {"argv":["/bin/bash","-ic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","--ask-for-approval","on-request","--sandbox","read-only","-c","approvals_reviewer=\"user\"","-c","tui.fullscreen_transcript=false"],"script":"585ef6d2032354bb","command":9},
"codex · new, mode readOnly · bash · no tmux": {"argv":["/bin/bash","-ic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","--sandbox","read-only","-c","tui.fullscreen_transcript=false"],"script":"585ef6d2032354bb","command":5},
"codex · new, mode ask · bash · no tmux": {"argv":["/bin/bash","-ic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","-c","tui.fullscreen_transcript=false"],"script":"585ef6d2032354bb","command":3},
"codex · new, mode full · bash · no tmux": {"argv":["/bin/bash","-ic",". '<data>/launch/<one-time>.sh'","harness-engine","codex","--dangerously-bypass-approvals-and-sandbox","-c","tui.fullscreen_transcript=false"],"script":"585ef6d2032354bb","command":4},
diff --git a/cli/src/engines/codex/buddySandbox.spec.ts b/cli/src/engines/codex/buddySandbox.spec.ts
new file mode 100644
index 000000000..af29c885f
--- /dev/null
+++ b/cli/src/engines/codex/buddySandbox.spec.ts
@@ -0,0 +1,136 @@
+import { execFileSync, spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createServer, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { PERMISSION_MODES } from '../../lib/engineLaunch.js'
+
+/**
+ * A Codex Buddy launched with full permissions could push and open pull requests with its person's own GitHub login
+ * (Lead, 10-29: Buddies were on in a Swarm that morning). It now launches in the sandbox its mode names, asking before
+ * anything outside it. This runs commands in that sandbox with the real Codex (`codex sandbox`), without a model or an
+ * approval: what it refuses is refused before anyone could be asked. A throwaway CODEX_HOME, never the person's.
+ */
+const hasCodex = (() => { try { execFileSync('codex', ['--version'], { stdio: 'ignore' }); return true } catch { return false } })()
+const hasGh = (() => { try { execFileSync('gh', ['--version'], { stdio: 'ignore' }); return true } catch { return false } })()
+
+const buddyFlags = PERMISSION_MODES.codex!.readOnlyAsk ?? []
+const sandboxMode = buddyFlags[buddyFlags.indexOf('--sandbox') + 1]
+
+interface Run { status: number | null; output: string }
+function run(command: string, args: readonly string[], cwd: string, env: NodeJS.ProcessEnv): Promise<Run> {
+ return new Promise((resolve, reject) => {
+ const child = spawn(command, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] })
+ let output = ''
+ child.stdout.on('data', (chunk) => { output += chunk })
+ child.stderr.on('data', (chunk) => { output += chunk })
+ child.on('error', reject)
+ child.on('close', (status) => resolve({ status, output }))
+ })
+}
+
+describe.skipIf(!hasCodex)('the sandbox a Codex Buddy launches in, with the real Codex', () => {
+ let root: string, repo: string, remote: string, env: NodeJS.ProcessEnv, server: Server, url: string, path: string
+ const received: string[] = []
+ const sandboxed = (...command: string[]) =>
+ run('codex', ['sandbox', '-c', `sandbox_mode=${JSON.stringify(sandboxMode)}`, '--', ...command], repo, env)
+ const git = (...args: string[]) => execFileSync('git', args, { cwd: repo, env, encoding: 'utf8' }).trim()
+
+ beforeAll(async () => {
+ root = mkdtempSync(join(tmpdir(), 'buddy-sandbox-'))
+ repo = join(root, 'repo'); remote = join(root, 'remote.git')
+ mkdirSync(join(root, 'codex-home')); mkdirSync(join(root, 'gh-config')); mkdirSync(repo)
+ env = { ...process.env, CODEX_HOME: join(root, 'codex-home'), GH_CONFIG_DIR: join(root, 'gh-config'), GH_TOKEN: 'not-a-token',
+ GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_AUTHOR_NAME: 't', GIT_AUTHOR_EMAIL: '[email protected]',
+ GIT_COMMITTER_NAME: 't', GIT_COMMITTER_EMAIL: '[email protected]' }
+ git('init', '-q', '-b', 'main')
+ writeFileSync(join(repo, 'notes.txt'), 'first\n')
+ git('add', 'notes.txt'); git('commit', '-qm', 'first commit')
+ execFileSync('git', ['init', '-q', '--bare', remote], { env })
+ git('remote', 'add', 'origin', remote)
+ server = createServer((request, response) => { received.push(`${request.method} ${request.url}`); response.end('ok') })
+ await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+ // A path of this run's own: a request from another run, outliving it, once reached a port reused here (review 2 of #2087).
+ path = `/write-${randomUUID()}`
+ url = `http://127.0.0.1:${(server.address() as AddressInfo).port}${path}`
+ })
+ afterAll(async () => {
+ await new Promise<void>((resolve) => server.close(() => resolve()))
+ rmSync(root, { recursive: true, force: true })
+ })
+
+ it('is the read-only sandbox', () => {
+ expect(sandboxMode).toBe('read-only')
+ })
+
+ it('takes the mode\'s own config overrides (approvals to the person, never Codex\'s reviewer)', async () => {
+ const overrides = buddyFlags.flatMap((flag, i) => buddyFlags[i - 1] === '-c' ? ['-c', flag] : [])
+ expect(overrides).toEqual(['-c', 'approvals_reviewer="user"'])
+ const taken = await run('codex', ['sandbox', ...overrides, '--', 'echo', 'ran'], repo, env)
+ expect([taken.status, taken.output.trim()]).toEqual([0, 'ran'])
+ })
+
+ it('sends approvals to the person even when their config.toml picks Codex\'s own reviewer (security re-check of #2087)', async () => {
+ // What the model is told about escalations, rendered by Codex itself: the person's config.toml says auto_review, and
+ // the Buddy's launch overrides it. The mode's --ask-for-approval and --sandbox are the same settings as config keys.
+ const home = join(root, 'auto-review-home')
+ mkdirSync(home)
+ writeFileSync(join(home, 'config.toml'), 'approvals_reviewer = "auto_review"\n')
+ const launch = ['-c', `approval_policy="${buddyFlags[buddyFlags.indexOf('--ask-for-approval') + 1]}"`, '-c', `sandbox_mode="${sandboxMode}"`]
+ const render = (...overrides: string[]) => run('codex', ['debug', 'prompt-input', ...launch, ...overrides], repo, { ...env, CODEX_HOME: home })
+ const theirs = await render()
+ expect(theirs.status).toBe(0)
+ expect(theirs.output).toContain('`approvals_reviewer` is `auto_review`')
+ const buddy = await render(...buddyFlags.flatMap((flag, i) => buddyFlags[i - 1] === '-c' ? ['-c', flag] : []))
+ expect(buddy.status).toBe(0)
+ expect(buddy.output).not.toContain('auto_review')
+ expect(buddy.output).toContain('Commands are run outside the sandbox if they are approved by the user')
+ })
+
+ it('reads the code and its history', async () => {
+ const log = await sandboxed('git', 'log', '--oneline')
+ expect([log.status, log.output]).toEqual([0, expect.stringContaining('first commit')])
+ const grep = await sandboxed('git', 'grep', '-n', 'first')
+ expect([grep.status, grep.output]).toEqual([0, expect.stringContaining('notes.txt:1:first')])
+ })
+
+ it('cannot push', async () => {
+ const push = await sandboxed('git', 'push', 'origin', 'HEAD:main')
+ expect(push.status).not.toBe(0)
+ expect(execFileSync('git', ['--git-dir', remote, 'for-each-ref'], { env, encoding: 'utf8' })).toBe('')
+ })
+
+ it.each([
+ ['a shell redirect', ['sh', '-c', 'echo changed > notes.txt']],
+ ['tee', ['sh', '-c', 'echo changed | tee notes.txt']],
+ ['sed -i', process.platform === 'darwin' ? ['sed', '-i', '', 's/first/changed/', 'notes.txt'] : ['sed', '-i', 's/first/changed/', 'notes.txt']],
+ ['a new file', ['sh', '-c', 'echo new > created.txt']],
+ ])('cannot write a file with %s', async (_, command) => {
+ const write = await sandboxed(...command)
+ expect(write.status).not.toBe(0)
+ expect(readFileSync(join(repo, 'notes.txt'), 'utf8')).toBe('first\n')
+ expect(() => readFileSync(join(repo, 'created.txt'))).toThrow()
+ })
+
+ it('cannot POST, even to this computer', async () => {
+ // Outside the sandbox the same request lands, so a refusal inside it is the sandbox's.
+ const outside = await run('curl', ['-sS', '-X', 'POST', '-d', 'x', url], repo, env)
+ const ours = () => received.filter((request) => request.endsWith(path))
+ expect([outside.status, ours()]).toEqual([0, [`POST ${path}`]])
+ const inside = await sandboxed('curl', '-sS', '-X', 'POST', '-d', 'x', url)
+ expect(inside.status).not.toBe(0)
+ expect(ours()).toEqual([`POST ${path}`])
+ })
+
+ it.skipIf(!hasGh).each([
+ ['gh pr create', ['gh', 'pr', 'create', '--repo', 'example/example', '--title', 't', '--body', 'b', '--head', 'main']],
+ ['gh issue comment', ['gh', 'issue', 'comment', '1', '--repo', 'example/example', '--body', 'b']],
+ ])('cannot reach GitHub for %s', async (_, command) => {
+ const write = await sandboxed(...command)
+ expect(write.status).not.toBe(0)
+ expect(write.output).toMatch(/error connecting to api\.github\.com/)
+ })
+})
diff --git a/cli/src/engines/codex/launch.ts b/cli/src/engines/codex/launch.ts
index 402c38a6c..a056e5812 100644
--- a/cli/src/engines/codex/launch.ts
+++ b/cli/src/engines/codex/launch.ts
@@ -2,6 +2,13 @@ import type { EngineLaunch } from '../facets/launch.js'
const permissionModes = {
auto: ['--approve-for-me'],
+ // A Buddy's (superTabs/start.ts): it reads in the sandbox, and an approval to go outside it goes to the person at its
+ // terminal, never to Codex's own reviewer, whatever their config.toml says. Their rules files still apply: a command an
+ // `allow` rule names runs outside the sandbox unasked, which is why the backend refuses Codex Buddies for now (security
+ // review 1 of #2087). Ahead of readOnly, whose flags it contains: a process's argv is read back as the first mode it
+ // matches (lib/processTable.ts), so a relaunched Buddy keeps this mode. A Codex without its flag is never relaunched
+ // without it (lib/engineLaunch.ts KEPT_PERMISSION_MODES).
+ readOnlyAsk: ['--ask-for-approval', 'on-request', '--sandbox', 'read-only', '-c', 'approvals_reviewer="user"'],
readOnly: ['--sandbox', 'read-only'],
ask: [],
full: ['--dangerously-bypass-approvals-and-sandbox'],
diff --git a/cli/src/gateway/start.ts b/cli/src/gateway/start.ts
index ebcef5c66..8f28af5cc 100644
--- a/cli/src/gateway/start.ts
+++ b/cli/src/gateway/start.ts
@@ -215,12 +215,12 @@ export function startGateway(host: GatewayHost): StartedGateway {
)
// The Share relay: a window here watching a harness someone shared with this account, over its own
// socket to the backend (`/api/observer-ws`), signed in with the account's token. It finds the share
- // among those the backend lists for this account first.
+ // among those the backend lists for this account first, a list kept a minute for this sign-in (sharing/relay.ts).
const shareRelay = new HarnessShareRelay(host.tokens, env.BACKEND_WS_URL, host.autonomousEnv, async () => {
const result = await accountHttp.backend('GET', '/api/harness-shares')
if (result.status !== 200) throw new Error('Shared harnesses are temporarily unavailable.')
return ((result.body as { data?: { machines?: SharedMachineReference[] } }).data?.machines ?? [])
- })
+ }, () => JSON.stringify([account.machineId, account.autonomousEnv ?? null, account.signIn?.epoch ?? null, account.signIn?.acct ?? null]))
const windowRelay: Required<WindowRelay> = {
acquire: (...args) => relayPool.acquire(...args),
acquireIsolated: (...args) => relayPool.acquireIsolated(...args),
diff --git a/cli/src/lib/__fixtures__/usage-shapes.golden.json b/cli/src/lib/__fixtures__/usage-shapes.golden.json
index e474de006..7d787a788 100644
--- a/cli/src/lib/__fixtures__/usage-shapes.golden.json
+++ b/cli/src/lib/__fixtures__/usage-shapes.golden.json
@@ -7,21 +7,45 @@
"updatedAt": "2026-10-01T00:01:00.000Z",
"inputTokens": 380,
"outputTokens": 40,
- "cachedTokens": 160
+ "cachedTokens": 160,
+ "models": {
+ "unknown": {
+ "input": 200,
+ "output": 40,
+ "cacheRead": 160,
+ "cacheWrite": 20
+ }
+ }
},
"partial": {
"totalTokens": 420,
"updatedAt": "2026-10-01T00:01:30.000Z",
"inputTokens": 380,
"outputTokens": 40,
- "cachedTokens": 160
+ "cachedTokens": 160,
+ "models": {
+ "unknown": {
+ "input": 200,
+ "output": 40,
+ "cacheRead": 160,
+ "cacheWrite": 20
+ }
+ }
},
"completed": {
"totalTokens": 630,
"updatedAt": "2026-10-01T00:02:00.000Z",
"inputTokens": 570,
"outputTokens": 60,
- "cachedTokens": 240
+ "cachedTokens": 240,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 60,
+ "cacheRead": 240,
+ "cacheWrite": 30
+ }
+ }
},
"output-and-work": {
"totalTokens": 630,
@@ -29,6 +53,14 @@
"inputTokens": 570,
"outputTokens": 60,
"cachedTokens": 240,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 60,
+ "cacheRead": 240,
+ "cacheWrite": 30
+ }
+ },
"output": {
"linesAdded": 2,
"linesRemoved": 0,
@@ -64,6 +96,14 @@
"inputTokens": 570,
"outputTokens": 60,
"cachedTokens": 240,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 60,
+ "cacheRead": 240,
+ "cacheWrite": 30
+ }
+ },
"output": {
"linesAdded": 2,
"linesRemoved": 0,
@@ -99,6 +139,14 @@
"inputTokens": 390,
"outputTokens": 20,
"cachedTokens": 80,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 20,
+ "cacheRead": 80,
+ "cacheWrite": 10
+ }
+ },
"work": {
"current": [],
"locations": [
@@ -125,21 +173,45 @@
"updatedAt": "2026-10-01T00:05:00.000Z",
"inputTokens": 290,
"outputTokens": 40,
- "cachedTokens": 80
+ "cachedTokens": 80,
+ "models": {
+ "unknown": {
+ "input": 200,
+ "output": 40,
+ "cacheRead": 80,
+ "cacheWrite": 10
+ }
+ }
},
"codex-deltas": {
"totalTokens": 250,
"updatedAt": "2026-10-01T00:05:30.000Z",
"inputTokens": 200,
"outputTokens": 50,
- "cachedTokens": 100
+ "cachedTokens": 100,
+ "models": {
+ "unknown": {
+ "input": 100,
+ "output": 50,
+ "cacheRead": 100,
+ "cacheWrite": 0
+ }
+ }
},
"codex-append": {
"totalTokens": 380,
"updatedAt": "2026-10-01T00:06:00.000Z",
"inputTokens": 300,
"outputTokens": 80,
- "cachedTokens": 150
+ "cachedTokens": 150,
+ "models": {
+ "unknown": {
+ "input": 150,
+ "output": 80,
+ "cacheRead": 150,
+ "cacheWrite": 0
+ }
+ }
},
"codex-other-conversation": null,
"notifications": [
@@ -158,6 +230,14 @@
"inputTokens": 480,
"outputTokens": 60,
"cachedTokens": 160,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 60,
+ "cacheRead": 160,
+ "cacheWrite": 20
+ }
+ },
"work": {
"current": [],
"locations": [
@@ -182,7 +262,15 @@
"updatedAt": "2026-10-01T00:07:30.000Z",
"inputTokens": 480,
"outputTokens": 60,
- "cachedTokens": 160
+ "cachedTokens": 160,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 60,
+ "cacheRead": 160,
+ "cacheWrite": 20
+ }
+ }
},
"opencode/valid/cold": null,
"opencode/valid": {
@@ -271,21 +359,45 @@
"updatedAt": "2026-10-01T00:01:00.000Z",
"inputTokens": 380,
"outputTokens": 40,
- "cachedTokens": 160
+ "cachedTokens": 160,
+ "models": {
+ "unknown": {
+ "input": 200,
+ "output": 40,
+ "cacheRead": 160,
+ "cacheWrite": 20
+ }
+ }
},
"partial": {
"totalTokens": 420,
"updatedAt": "2026-10-01T00:01:30.000Z",
"inputTokens": 380,
"outputTokens": 40,
- "cachedTokens": 160
+ "cachedTokens": 160,
+ "models": {
+ "unknown": {
+ "input": 200,
+ "output": 40,
+ "cacheRead": 160,
+ "cacheWrite": 20
+ }
+ }
},
"completed": {
"totalTokens": 630,
"updatedAt": "2026-10-01T00:02:00.000Z",
"inputTokens": 570,
"outputTokens": 60,
- "cachedTokens": 240
+ "cachedTokens": 240,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 60,
+ "cacheRead": 240,
+ "cacheWrite": 30
+ }
+ }
},
"output-and-work": {
"totalTokens": 630,
@@ -293,6 +405,14 @@
"inputTokens": 570,
"outputTokens": 60,
"cachedTokens": 240,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 60,
+ "cacheRead": 240,
+ "cacheWrite": 30
+ }
+ },
"output": {
"linesAdded": 2,
"linesRemoved": 0,
@@ -328,6 +448,14 @@
"inputTokens": 570,
"outputTokens": 60,
"cachedTokens": 240,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 60,
+ "cacheRead": 240,
+ "cacheWrite": 30
+ }
+ },
"output": {
"linesAdded": 2,
"linesRemoved": 0,
@@ -363,6 +491,14 @@
"inputTokens": 390,
"outputTokens": 20,
"cachedTokens": 80,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 20,
+ "cacheRead": 80,
+ "cacheWrite": 10
+ }
+ },
"work": {
"current": [],
"locations": [
@@ -389,21 +525,45 @@
"updatedAt": "2026-10-01T00:05:00.000Z",
"inputTokens": 290,
"outputTokens": 40,
- "cachedTokens": 80
+ "cachedTokens": 80,
+ "models": {
+ "unknown": {
+ "input": 200,
+ "output": 40,
+ "cacheRead": 80,
+ "cacheWrite": 10
+ }
+ }
},
"codex-deltas": {
"totalTokens": 250,
"updatedAt": "2026-10-01T00:05:30.000Z",
"inputTokens": 200,
"outputTokens": 50,
- "cachedTokens": 100
+ "cachedTokens": 100,
+ "models": {
+ "unknown": {
+ "input": 100,
+ "output": 50,
+ "cacheRead": 100,
+ "cacheWrite": 0
+ }
+ }
},
"codex-append": {
"totalTokens": 380,
"updatedAt": "2026-10-01T00:06:00.000Z",
"inputTokens": 300,
"outputTokens": 80,
- "cachedTokens": 150
+ "cachedTokens": 150,
+ "models": {
+ "unknown": {
+ "input": 150,
+ "output": 80,
+ "cacheRead": 150,
+ "cacheWrite": 0
+ }
+ }
},
"codex-other-conversation": null,
"notifications": [
@@ -422,6 +582,14 @@
"inputTokens": 480,
"outputTokens": 60,
"cachedTokens": 160,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 60,
+ "cacheRead": 160,
+ "cacheWrite": 20
+ }
+ },
"work": {
"current": [],
"locations": [
@@ -446,7 +614,15 @@
"updatedAt": "2026-10-01T00:07:30.000Z",
"inputTokens": 480,
"outputTokens": 60,
- "cachedTokens": 160
+ "cachedTokens": 160,
+ "models": {
+ "unknown": {
+ "input": 300,
+ "output": 60,
+ "cacheRead": 160,
+ "cacheWrite": 20
+ }
+ }
},
"opencode/valid/cold": null,
"opencode/valid": {
diff --git a/cli/src/lib/agentTokenUsage.spec.ts b/cli/src/lib/agentTokenUsage.spec.ts
index f0e3d6ae0..d730aced5 100644
--- a/cli/src/lib/agentTokenUsage.spec.ts
+++ b/cli/src/lib/agentTokenUsage.spec.ts
@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { AgentTokenUsageCache } from './agentTokenUsage.js'
+import { validUsage } from './agentUsageWire.js'
import type { RegisteredSession } from './registry.js'
const at = '2026-09-22T16:00:00Z'
@@ -354,3 +355,73 @@ it('exports normalized input, output and cached input without double-counting',
expect(store.get(target)).toMatchObject({ totalTokens: 420, inputTokens: 380, outputTokens: 40, cachedTokens: 160 })
} finally { store.dispose(); await store.settled(); await rm(dir, { recursive: true, force: true }) }
})
+
+describe('token counts by model (Swarm cost records)', () => {
+ let dir: string
+ let store: AgentTokenUsageCache
+ let target: Pick<RegisteredSession, 'agentId' | 'sessionId' | 'engine' | 'transcriptPath' | 'registeredAt'>
+ const read = async () => { store.changed(target); await store.settled(); return store.get(target) }
+ const reply = (id: string, model: string | undefined, usage: Record<string, number>) => JSON.stringify({ type: 'assistant', timestamp: at,
+ sessionId: 'conversation', requestId: `req-${id}`, message: { id, ...(model ? { model } : {}), usage } }) + '\n'
+ const settings = (model: string) => JSON.stringify({ type: 'turn_context', timestamp: at, payload: { model, effort: 'high' } }) + '\n'
+ beforeEach(async () => {
+ dir = await mkdtemp(join(tmpdir(), 'harness-token-models-'))
+ target = { agentId: 'harness', sessionId: 'conversation', engine: 'claude', transcriptPath: join(dir, 'transcript.jsonl'), registeredAt: 1 }
+ store = new AgentTokenUsageCache(join(dir, 'cache'))
+ })
+ afterEach(async () => { store.dispose(); await store.settled(); await rm(dir, { recursive: true, force: true }) })
+
+ it('splits Claude usage by the model that answered, merging streaming repeats once', async () => {
+ await writeFile(target.transcriptPath!,
+ reply('one', 'claude-opus-5-5', { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 100, cache_creation_input_tokens: 20 })
+ + reply('one', 'claude-opus-5-5', { input_tokens: 10, output_tokens: 7, cache_read_input_tokens: 100, cache_creation_input_tokens: 20 })
+ + reply('two', 'claude-haiku-5-5', { input_tokens: 3, output_tokens: 2, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 })
+ + reply('three', undefined, { input_tokens: 1, output_tokens: 1 }))
+ expect((await read())?.models).toEqual({
+ 'claude-opus-5-5': { input: 10, output: 7, cacheRead: 100, cacheWrite: 20 },
+ 'claude-haiku-5-5': { input: 3, output: 2, cacheRead: 0, cacheWrite: 0 },
+ unknown: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 },
+ })
+ })
+
+ it('files Codex deltas under the model its turn settings name, with cache reads out of input', async () => {
+ target.engine = 'codex'
+ await writeFile(target.transcriptPath!, settings('gpt-5.5-codex') + codex(100, 20) + settings('gpt-5.4-mini') + codex(200, 50, [100, 30]))
+ // codex(): cached input is half of input, and reasoning is already inside output.
+ expect((await read())?.models).toEqual({
+ 'gpt-5.5-codex': { input: 50, output: 20, cacheRead: 50, cacheWrite: 0 },
+ 'gpt-5.4-mini': { input: 50, output: 30, cacheRead: 50, cacheWrite: 0 },
+ })
+ })
+
+ it('files models past the limit together under one reserved bucket, so the reading stays valid however many a session names', async () => {
+ const one = { input_tokens: 1, output_tokens: 1 }
+ await writeFile(target.transcriptPath!, Array.from({ length: 20 }, (_, i) => reply(`m${i}`, `model-${i}`, one)).join('')
+ + reply('late', 'model-3', one) + reply('odd', 'two words', one))
+ const usage = await read()
+ expect(Object.keys(usage!.models!)).toHaveLength(16)
+ expect(usage!.models!['model-3']).toEqual({ input: 2, output: 2, cacheRead: 0, cacheWrite: 0 })
+ // model-15 to model-19 and the unnamed one: six replies past the fifteen named models.
+ expect(usage!.models!.other).toEqual({ input: 6, output: 6, cacheRead: 0, cacheWrite: 0 })
+ expect(validUsage(usage)).toBe(true)
+ })
+
+ it('keeps a model name that is not a plain identifier out of the counts', async () => {
+ await writeFile(target.transcriptPath!, reply('one', 'evil model\nname', { input_tokens: 4, output_tokens: 1 }))
+ expect(Object.keys((await read())?.models ?? {})).toEqual(['unknown'])
+ })
+
+ it('replays a checkpoint from before model counts once', async () => {
+ await writeFile(target.transcriptPath!, reply('one', 'claude-opus-5-5', { input_tokens: 10, output_tokens: 5 }))
+ await read()
+ const file = join(dir, 'cache', (await readdir(join(dir, 'cache')))[0])
+ const saved = JSON.parse(await readFile(file, 'utf8'))
+ const { models: _models, codexModel: _codexModel, ...before } = { ...saved, version: 5 }
+ await writeFile(file, JSON.stringify(before))
+ store.dispose()
+ store = new AgentTokenUsageCache(join(dir, 'cache'))
+ const usage = await read()
+ expect(usage?.totalTokens).toBe(15)
+ expect(usage?.models).toEqual({ 'claude-opus-5-5': { input: 10, output: 5, cacheRead: 0, cacheWrite: 0 } })
+ })
+})
diff --git a/cli/src/lib/agentTokenUsage.ts b/cli/src/lib/agentTokenUsage.ts
index 9d16bdeb6..6b326ad98 100644
--- a/cli/src/lib/agentTokenUsage.ts
+++ b/cli/src/lib/agentTokenUsage.ts
@@ -9,17 +9,21 @@ import { sqliteReadAll } from './sqliteRead.js'
import { emptyOutputLedger, ingestOutput, outputSnapshot, validOutputLedger, type AgentOutputStats, type OutputLedger } from './agentOutputStats.js'
import { emptySessionWork, ingestSessionWork, sessionWorkSnapshot, validSessionWork, type SessionWork, type SessionWorkLedger } from './sessionWork.js'
-import { usageTargetKey, type AgentTokenUsage, type AgentUsageTarget as Target } from './agentUsageWire.js'
+import { MAX_USAGE_MODELS, OTHER_MODELS, usageModelName, usageTargetKey, type AgentTokenUsage, type AgentUsageTarget as Target, type ModelTokens } from './agentUsageWire.js'
export type { AgentTokenUsage } from './agentUsageWire.js'
type Buckets = [number, number, number, number]
type CodexTotals = [number, number, number, number]
type Checkpoint = {
- version: 5; key: string; offset: number; size: number; mtime: number; inode: string;
+ version: 6; key: string; offset: number; size: number; mtime: number; inode: string;
boundary: string; total: number; observed: boolean; updatedAt: string | null;
claude: Record<string, Buckets>; codex: CodexTotals | null; seen: Record<string, true>;
output: OutputLedger;
work: SessionWorkLedger; sourceSession: string | null;
usage: [number, number, number];
+ /** Per model: uncached input, output, cache read, cache write. What the Swarm prices an attempt by (backend costs/). */
+ models: Record<string, Buckets>
+ /** The model Codex's latest turn settings named: its token counts carry none of their own. */
+ codexModel: string | null
}
type Entry = {
target: Target; value: AgentTokenUsage | null; checked: number; pending: Promise<void> | null;
@@ -53,9 +57,9 @@ function targetSnapshot(s: Target): Target {
codexHome: s.codexHome, cwd: s.cwd, registeredAt: s.registeredAt, forkedFrom: s.forkedFrom ? { ...s.forkedFrom } : null }
}
function empty(key: string): Checkpoint {
- return { version: 5, key, offset: 0, size: 0, mtime: 0, inode: '', boundary: '', total: 0, usage: [0, 0, 0],
+ return { version: 6, key, offset: 0, size: 0, mtime: 0, inode: '', boundary: '', total: 0, usage: [0, 0, 0],
observed: false, updatedAt: null, claude: {}, codex: null, seen: {}, output: emptyOutputLedger(),
- work: emptySessionWork(), sourceSession: null }
+ work: emptySessionWork(), sourceSession: null, models: {}, codexModel: null }
}
function rawCodex(value: unknown): CodexTotals | null {
const row = object(value)
@@ -64,12 +68,23 @@ function rawCodex(value: unknown): CodexTotals | null {
tokens(row.output_tokens), tokens(row.reasoning_output_tokens)] : null
}
+/** Adds a delta to its model's buckets. Past MAX_USAGE_MODELS - 1 models a session files every new one together under
+ * OTHER_MODELS, which keeps one place free for it: the reading stays at MAX_USAGE_MODELS whatever a transcript names, and
+ * stays valid (a 17th bucket had made the whole reading invalid, review of #2106). */
+function addModel(state: Checkpoint, name: unknown, delta: Buckets): void {
+ if (delta.every(n => n === 0)) return
+ let model = usageModelName(name)
+ if (!state.models[model] && Object.keys(state.models).filter(m => m !== OTHER_MODELS).length >= MAX_USAGE_MODELS - 1) model = OTHER_MODELS
+ const into = state.models[model] ??= [0, 0, 0, 0]
+ delta.forEach((n, i) => { into[i] += n })
+}
+
/** Same counting rules as the desktop usage ledger: cached input is included once, reasoning is
* already inside output, Claude streaming repeats merge, and Codex cumulative snapshots are deltas. */
function ingest(state: Checkpoint, line: string, target: Target): void {
if (!line.includes(target.engine === 'claude' ? '"usage"' : '"token_count"')
&& !line.includes('"tool_use"') && !line.includes('"tool_result"') && !line.includes('"response_item"')
- && !line.includes('"session_meta"') && !line.includes('"turn_context"')) return
+ && !line.includes('"session_meta"') && !line.includes('"turn_context"') && !line.includes('"thread_settings_applied"')) return
const row = object(JSON.parse(line))
if (!row) return
// Forks carry old messages into a new conversation. Only work after the fork belongs to it.
@@ -80,6 +95,10 @@ function ingest(state: Checkpoint, line: string, target: Target): void {
const id = row.type === 'session_meta' ? object(row.payload)?.id : null
if (typeof id === 'string') state.sourceSession = id
if (state.sourceSession !== null && state.sourceSession !== target.sessionId) return
+ // The model of the turns that follow, as the engine's runtime profile reads it (engines/codex/runtimeProfile.ts).
+ const settings = row.type === 'turn_context' ? object(row.payload)
+ : row.type === 'event_msg' && object(row.payload)?.type === 'thread_settings_applied' ? object(object(row.payload)?.thread_settings) : null
+ if (typeof settings?.model === 'string' && settings.model) state.codexModel = usageModelName(settings.model)
}
if (row.isSidechain !== true) ingestSessionWork(state.work, row, target.engine, target.cwd)
ingestOutput(state.output, row, target.engine)
@@ -103,6 +122,7 @@ function ingest(state: Checkpoint, line: string, target: Target): void {
state.usage[0] += merged[0] + merged[2] + merged[3] - old[0] - old[2] - old[3]
state.usage[1] += merged[1] - old[1]
state.usage[2] += merged[2] - old[2]
+ addModel(state, message?.model, merged.map((n, i) => n - old[i]) as Buckets)
state.observed = true
} else {
const payload = object(row.payload)
@@ -129,6 +149,7 @@ function ingest(state: Checkpoint, line: string, target: Target): void {
state.usage[0] += Math.max(delta[0], delta[1])
state.usage[1] += delta[2]
state.usage[2] += delta[1]
+ addModel(state, state.codexModel, [Math.max(0, delta[0] - delta[1]), delta[2], delta[1], 0])
state.observed = true
}
}
@@ -240,8 +261,11 @@ export class AgentTokenUsageCache {
if (previous) this.onChanged?.(entry.target)
return
}
+ const models = Object.entries(state.models)
entry.value = { totalTokens: state.observed ? state.total : null, updatedAt: state.updatedAt,
...(state.observed ? { inputTokens: state.usage[0], outputTokens: state.usage[1], cachedTokens: state.usage[2] } : {}),
+ ...(state.observed && models.length ? { models: Object.fromEntries(models.map(([model, [input, output, cacheRead, cacheWrite]]) =>
+ [model, { input, output, cacheRead, cacheWrite } satisfies ModelTokens])) } : {}),
...(output ? { output } : {}), ...(work ? { work } : {}) }
if (previous?.totalTokens !== entry.value.totalTokens
|| JSON.stringify(previous?.output) !== JSON.stringify(output ?? undefined)
@@ -253,7 +277,8 @@ export class AgentTokenUsageCache {
if ((await stat(file)).size > MAX_CACHE_BYTES) return empty(key)
const raw = JSON.parse(await readFile(file, 'utf8')) as Checkpoint
const version: number = raw.version
- if ((version === 3 || version === 4) && raw.key === key) {
+ // v5 kept no per-model counts: replayed once like v3 and v4, so a session's counts by model cover all of it.
+ if ((version === 3 || version === 4 || version === 5) && raw.key === key) {
const work = { ...raw.work, currentOrder: 0, failedOrder: 0 }
if (validSessionWork(work)) {
// Receipts may already have been compacted out of the transcript. Replay the available
@@ -267,7 +292,7 @@ export class AgentTokenUsageCache {
}
}
// Replay old transcripts once: v3 skipped ordinary batched code-mode receipts, including PRs.
- if (raw.version === 5 && raw.key === key && Number.isSafeInteger(raw.total) && raw.total >= 0
+ if (raw.version === 6 && raw.key === key && Number.isSafeInteger(raw.total) && raw.total >= 0
&& Array.isArray(raw.usage) && raw.usage.length === 3 && raw.usage.every(n => Number.isSafeInteger(n) && n >= 0)
&& typeof raw.observed === 'boolean'
&& (raw.updatedAt === null || typeof raw.updatedAt === 'string' && Number.isFinite(Date.parse(raw.updatedAt)))
@@ -277,7 +302,10 @@ export class AgentTokenUsageCache {
&& object(raw.claude) && Object.values(raw.claude).every(validBuckets)
&& object(raw.seen) && Object.values(raw.seen).every(value => value === true)
&& (raw.codex === null || validBuckets(raw.codex)) && validOutputLedger(raw.output)
- && validSessionWork(raw.work) && (raw.sourceSession === null || typeof raw.sourceSession === 'string')) return raw
+ && validSessionWork(raw.work) && (raw.sourceSession === null || typeof raw.sourceSession === 'string')
+ && object(raw.models) && Object.keys(raw.models).length <= MAX_USAGE_MODELS
+ && Object.entries(raw.models).every(([model, buckets]) => usageModelName(model) === model && validBuckets(buckets))
+ && (raw.codexModel === null || usageModelName(raw.codexModel) === raw.codexModel)) return raw
} catch { /* First run, corrupt cache, or removed cache: rebuild from the trusted transcript. */ }
return empty(key)
}
diff --git a/cli/src/lib/agentUsageWire.spec.ts b/cli/src/lib/agentUsageWire.spec.ts
index 6ace060ce..1e4bb7cd8 100644
--- a/cli/src/lib/agentUsageWire.spec.ts
+++ b/cli/src/lib/agentUsageWire.spec.ts
@@ -38,3 +38,15 @@ it('copies aggregates only and rejects malformed or oversized values', () => {
{ ...value, work: { ...value.work, pullRequests: [{ url: 'file:///secret', cwd: null, at }] } },
{ ...value, work: { ...value.work, pullRequests: [{ url: value.work.pullRequests[0].url, cwd: 'relative', at }] } }]) expect(validUsage(bad)).toBe(false)
})
+
+it('carries counts by model only, copied field by field, and refuses anything else under models', () => {
+ const opus = { input: 1, output: 2, cacheRead: 3, cacheWrite: 4 }
+ const value = { totalTokens: 10, updatedAt: at, models: { 'claude-opus-5-5': { ...opus, prompt: 'secret' } as typeof opus } }
+ expect(validUsage({ totalTokens: 10, updatedAt: at, models: { 'claude-opus-5-5': opus } })).toBe(true)
+ expect(usageSnapshot({ totalTokens: 10, updatedAt: at, models: { 'claude-opus-5-5': opus } })?.models).toEqual({ 'claude-opus-5-5': opus })
+ expect(validUsage(value)).toBe(false)
+ for (const models of [[], { 'two words': opus }, { m: { ...opus, input: -1 } }, { m: { ...opus, output: 1.5 } }, { m: { input: 1 } },
+ Object.fromEntries(Array.from({ length: 17 }, (_, i) => [`model-${i}`, opus]))]) {
+ expect(validUsage({ totalTokens: 10, updatedAt: at, models }), JSON.stringify(models)).toBe(false)
+ }
+})
diff --git a/cli/src/lib/agentUsageWire.ts b/cli/src/lib/agentUsageWire.ts
index 122e18204..994c23704 100644
--- a/cli/src/lib/agentUsageWire.ts
+++ b/cli/src/lib/agentUsageWire.ts
@@ -4,11 +4,23 @@ import type { RegisteredSession } from './registry.js'
import type { AgentOutputStats } from './agentOutputStats.js'
import type { SessionWork } from './sessionWork.js'
-export type AgentTokenUsage = { totalTokens: number | null; updatedAt: string; inputTokens?: number; outputTokens?: number; cachedTokens?: number; output?: AgentOutputStats; work?: SessionWork }
+/** One model's tokens in a session: uncached input, output (reasoning included), cache reads and cache writes. Counts only. */
+export type ModelTokens = { input: number; output: number; cacheRead: number; cacheWrite: number }
+export type AgentTokenUsage = { totalTokens: number | null; updatedAt: string; inputTokens?: number; outputTokens?: number; cachedTokens?: number
+ /** By the model that answered (agentTokenUsage.ts); absent for an engine whose records name none (OpenCode). */
+ models?: Record<string, ModelTokens>; output?: AgentOutputStats; work?: SessionWork }
export type AgentUsageTarget = Pick<RegisteredSession, 'engine' | 'sessionId' | 'transcriptPath' | 'codexHome' | 'agentId' | 'forkedFrom' | 'registeredAt'>
& Partial<Pick<RegisteredSession, 'cwd'>>
export const USAGE_LIMIT = 512
export const USAGE_REFRESH_MS = 15_000
+/** Models one session counts apart, `other` among them (OTHER_MODELS). A session switches model a handful of times at most. */
+export const MAX_USAGE_MODELS = 16
+/** Where a session's models past the limit are counted together (agentTokenUsage.ts addModel); never priced. */
+export const OTHER_MODELS = 'other'
+const MODEL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,119}$/
+/** A model as the counts name it: the engine's own identifier, or `unknown` for none or anything that is not a plain one. */
+export const usageModelName = (v: unknown): string => typeof v === 'string' && MODEL_NAME.test(v) ? v : 'unknown'
+const MODEL_TOKEN_KEYS = ['input', 'output', 'cacheRead', 'cacheWrite'] as const
const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
const text = (v: unknown): v is string => typeof v === 'string' && v.length <= 4096 && !/[\x00-\x1f\x7f]/.test(v)
const count = (v: unknown): v is number => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0
@@ -35,6 +47,7 @@ export function validUsage(v: unknown): v is AgentTokenUsage | null {
if (v === null) return true
if (!object(v) || !(v.totalTokens === null || count(v.totalTokens)) || !stamp(v.updatedAt)
|| !['inputTokens', 'outputTokens', 'cachedTokens'].every(k => v[k] === undefined || count(v[k]))) return false
+ if (v.models !== undefined && !validModelTokens(v.models)) return false
if (v.output !== undefined && (!object(v.output) || !['linesAdded', 'linesRemoved', 'pullRequestsCreated']
.every(k => (v.output as Record<string, unknown>)[k] === null || count((v.output as Record<string, unknown>)[k])))) return false
if (v.work !== undefined) {
@@ -54,7 +67,15 @@ export function usageSnapshot(v: AgentTokenUsage | null): AgentTokenUsage | null
...(v.inputTokens === undefined ? {} : { inputTokens: v.inputTokens }),
...(v.outputTokens === undefined ? {} : { outputTokens: v.outputTokens }),
...(v.cachedTokens === undefined ? {} : { cachedTokens: v.cachedTokens }),
+ ...(v.models ? { models: Object.fromEntries(Object.entries(v.models).map(([model, t]) =>
+ [model, { input: t.input, output: t.output, cacheRead: t.cacheRead, cacheWrite: t.cacheWrite }])) } : {}),
...(v.output ? { output: { linesAdded: v.output.linesAdded, linesRemoved: v.output.linesRemoved, pullRequestsCreated: v.output.pullRequestsCreated } } : {}),
...(v.work ? { work: { current: v.work.current.map(p => ({ cwd: p.cwd, at: p.at })), locations: v.work.locations.map(p => ({ cwd: p.cwd, at: p.at })),
pullRequests: v.work.pullRequests.map(p => ({ url: p.url, cwd: p.cwd, at: p.at })), uncertain: v.work.uncertain, truncated: v.work.truncated } } : {}) }
}
+
+/** At most MAX_USAGE_MODELS plainly named models, each with exactly its four counts. */
+export function validModelTokens(v: unknown): v is Record<string, ModelTokens> {
+ return object(v) && Object.keys(v).length <= MAX_USAGE_MODELS && Object.entries(v).every(([model, t]) => usageModelName(model) === model
+ && object(t) && Object.keys(t).length === MODEL_TOKEN_KEYS.length && MODEL_TOKEN_KEYS.every(k => count(t[k])))
+}
diff --git a/cli/src/lib/e2ee/groupSyncer.spec.ts b/cli/src/lib/e2ee/groupSyncer.spec.ts
index bb10453d6..1a613332b 100644
--- a/cli/src/lib/e2ee/groupSyncer.spec.ts
+++ b/cli/src/lib/e2ee/groupSyncer.spec.ts
@@ -497,7 +497,9 @@ describe('GroupSyncer', () => {
for (const n of f.nodes) n.syncer.stop()
})
- it('a round that missed a member tries again soon, then backs off', async () => {
+ // The first retry waits 30 s, as the relay holds a refused machine (remoteRelay.ts): at 15 s it went through the background
+ // pools and asked an offline machine again before the backend's retry-after was up (socket churn e2e, 2026-10-29).
+ it('a round that missed a member tries again after 30 s, then backs off', async () => {
vi.useFakeTimers()
const f = fleet()
const [a, b] = [f.add('a'), f.add('b')]
@@ -507,7 +509,7 @@ describe('GroupSyncer', () => {
const handle = vi.spyOn(b.syncer, 'handle')
await a.syncer.syncAll()
b.online = true
- await vi.advanceTimersByTimeAsync(14_000)
+ await vi.advanceTimersByTimeAsync(29_000)
expect(handle).not.toHaveBeenCalled()
await vi.advanceTimersByTimeAsync(2_000)
expect(handle).toHaveBeenCalledTimes(1)
@@ -517,6 +519,24 @@ describe('GroupSyncer', () => {
for (const n of f.nodes) n.syncer.stop()
})
+ // Review of #2104: with the first retry at 30 s, a new link waited behind the pending retry instead of going out at
+ // once. Fresh news is sent now, whatever retry for a missed member is pending.
+ it('a new link goes out at once, even while a retry for a missed member is pending', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b, phone] = [f.add('a'), f.add('b'), f.add('p', false)]
+ b.online = false
+ f.link(a, b)
+ b.syncer.stop()
+ await vi.advanceTimersByTimeAsync(0) // the link's fan-out misses B: a retry is pending
+ await vi.advanceTimersByTimeAsync(5_000)
+ b.online = true
+ a.syncer.linked({ pub: phone.pub, kind: 'viewer', label: 'new phone' })
+ await vi.advanceTimersByTimeAsync(0)
+ expect(b.trusted.has(phone.pub)).toBe(true)
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
it('sessionOpened() does not re-sync a machine it just synced with', async () => {
vi.useFakeTimers()
const f = fleet()
diff --git a/cli/src/lib/e2ee/groupSyncer.ts b/cli/src/lib/e2ee/groupSyncer.ts
index a150c2441..5c6f48d66 100644
--- a/cli/src/lib/e2ee/groupSyncer.ts
+++ b/cli/src/lib/e2ee/groupSyncer.ts
@@ -46,8 +46,10 @@ const PERIODIC_MS = 10 * 60_000
/** A machine synced this recently is not synced again just because a session to it opened. */
const RECONTACT_MS = 5 * 60_000
/** After a round where a member could not be reached (or refused, having not heard of this machine yet),
- * try again this soon — then less often. The periodic round takes over after the last. */
-const RETRY_MS = [15_000, 60_000, 4 * 60_000]
+ * try again this soon — then less often. The periodic round takes over after the last. The first is 30 s, the backend's
+ * retry-after for an offline machine and the relay's longest hold: at 15 s the retry asked an offline machine again
+ * through the background pools before that was up (socket churn e2e, 2026-10-29). */
+const RETRY_MS = [30_000, 60_000, 4 * 60_000]
export interface GroupSyncerDeps {
store: TrustGroupStore
@@ -92,6 +94,8 @@ export class GroupSyncer {
private readonly lastSynced = new Map<string, number>()
private readonly inFlight = new Map<string, Promise<boolean>>()
private fanOutTimer: ReturnType<typeof setTimeout> | null = null
+ /** When the pending fan-out runs. */
+ private fanOutAt = 0
private periodic: ReturnType<typeof setInterval> | null = null
private retryRound = 0
/** Bumped when the account changes: an exchange started before is not merged into the new roster. */
@@ -327,7 +331,13 @@ export class GroupSyncer {
* retry schedule over. */
private scheduleFanOut(delayMs: number, retry = false): void {
if (!retry) this.retryRound = 0
- if (this.fanOutTimer) return
+ if (this.fanOutTimer) {
+ // News does not wait behind a retry for a missed member (review of #2104): a link made during a 30 s retry went
+ // out at the retry, not at once. A retry never moves a fan-out that is already due sooner.
+ if (retry || Date.now() + delayMs >= this.fanOutAt) return
+ clearTimeout(this.fanOutTimer)
+ }
+ this.fanOutAt = Date.now() + delayMs
this.fanOutTimer = setTimeout(() => {
this.fanOutTimer = null
// What changed reaches every member, not just the recently-contacted ones.
diff --git a/cli/src/lib/e2ee/machinePeers.spec.ts b/cli/src/lib/e2ee/machinePeers.spec.ts
index ff0335d86..0d9b97bbb 100644
--- a/cli/src/lib/e2ee/machinePeers.spec.ts
+++ b/cli/src/lib/e2ee/machinePeers.spec.ts
@@ -1,4 +1,7 @@
-import { beforeEach, describe, expect, it } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { chmodSync } from 'node:fs'
+import { join } from 'node:path'
+import { env } from '../../config/env.js'
import { MachinePeerStore } from './machinePeers.js'
/** A machine the backend said was deleted (remoteRelay.ts): unpinned and remembered, so the trust group does not pin it
@@ -34,4 +37,27 @@ describe('a machine marked gone', () => {
expect(gone.has((299).toString(16).padStart(32, '0'))).toBe(true)
expect(gone.has((0).toString(16).padStart(32, '0'))).toBe(false)
})
+
+ // Review of #2101 (Batch S): restore() runs in the machine-list callback, and a mark file it cannot rewrite (a full or
+ // read-only disk) threw out of it. The machine is back for this process all the same, and the log says so.
+ it('is back even when the file cannot be rewritten, without throwing', () => {
+ const peers = new MachinePeerStore()
+ peers.markGone(a)
+ const file = join(env.ADAPTER_DATA_DIR, 'e2e', 'machinePeers-gone.json')
+ chmodSync(file, 0o400)
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+ try {
+ expect(peers.restore([a])).toBe(true)
+ expect(peers.gone().has(a)).toBe(false)
+ expect(new MachinePeerStore().gone().has(a)).toBe(false)
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('could not record'))
+ // Marked gone again later, it is gone again.
+ chmodSync(file, 0o600)
+ peers.markGone(a)
+ expect(peers.gone().has(a)).toBe(true)
+ } finally {
+ chmodSync(file, 0o600)
+ warn.mockRestore()
+ }
+ })
})
diff --git a/cli/src/lib/e2ee/machinePeers.ts b/cli/src/lib/e2ee/machinePeers.ts
index 783ff3406..c35dc1298 100644
--- a/cli/src/lib/e2ee/machinePeers.ts
+++ b/cli/src/lib/e2ee/machinePeers.ts
@@ -26,6 +26,8 @@ const GONE_MAX = 256
// Marks the file could not take (a full or read-only disk, review of #2101), for every store in this process: they still
// keep the trust group from pinning the machine again and the relay from dialling it, until the daemon restarts.
const goneInMemory = new Set<string>()
+// And the other way: machines listed again whose mark the file could not drop (review of #2101, Batch S).
+const backInMemory = new Set<string>()
export interface MachinePeer {
machineId: string
@@ -76,9 +78,10 @@ export class MachinePeerStore {
return true
}
- /** The backend said [machineId] was deleted: drop its pin, and remember it so the trust group does not pin it again. */
- /** Throws when the mark or the unpin cannot be written; the mark holds in memory for this process all the same. */
+ /** The backend said [machineId] was deleted: drop its pin, and remember it so the trust group does not pin it again.
+ * Throws when the mark or the unpin cannot be written; the mark holds in memory for this process all the same. */
markGone(machineId: string): void {
+ backInMemory.delete(machineId)
const gone = this.gone()
gone.delete(machineId)
gone.add(machineId)
@@ -93,19 +96,27 @@ export class MachinePeerStore {
const raw = JSON.parse(readFileSync(GONE_FILE, 'utf-8')) as unknown
if (Array.isArray(raw)) kept = raw.filter((id): id is string => typeof id === 'string')
} catch { /* none yet, or unreadable: the marks in memory still hold */ }
- return new Set([...kept, ...goneInMemory])
+ return new Set([...kept.filter((id) => !backInMemory.has(id)), ...goneInMemory])
}
- /** The account's machine list names [listed]: any of them marked gone is back (re-added, or shared again). True when one was. */
+ /** The account's machine list names [listed]: any of them marked gone is back (re-added, or shared again). True when one was.
+ * Never throws: it runs in the machine-list callback, and a file it cannot rewrite leaves them back in memory. */
restore(listed: Iterable<string>): boolean {
const gone = this.gone()
- let back = false
+ const back: string[] = []
for (const id of listed) {
+ if (!gone.delete(id)) continue
goneInMemory.delete(id)
- back = gone.delete(id) || back
+ back.push(id)
}
- if (back) writeGone(new Set([...gone].filter((id) => !goneInMemory.has(id))))
- return back
+ if (!back.length) return false
+ try {
+ writeGone(gone)
+ } catch (err) {
+ for (const id of back) backInMemory.add(id)
+ console.warn(`[relay] could not record ${back.length} machine(s) as back on the list, kept in memory: ${err instanceof Error ? err.message : String(err)}`)
+ }
+ return true
}
list(): Array<MachinePeer & { fingerprint: string }> {
diff --git a/cli/src/lib/engineLaunch.spec.ts b/cli/src/lib/engineLaunch.spec.ts
index e8d1b7df9..a5be9f29b 100644
--- a/cli/src/lib/engineLaunch.spec.ts
+++ b/cli/src/lib/engineLaunch.spec.ts
@@ -824,6 +824,9 @@ printf '%s %s' "$harness_status" "$resumed"`], { encoding: 'utf8', stdio: ['igno
.toEqual([engineBin('claude'), '--dangerously-skip-permissions'])
expect(buildEngineCommandArgv('codex', { permissionMode: 'readOnly' }))
.toEqual([engineBin('codex'), '--sandbox', 'read-only', ...CODEX_SCREEN])
+ // A Codex Buddy: reads in the sandbox, and asks the person at the terminal before anything outside it (Lead, 10-29).
+ expect(buildEngineCommandArgv('codex', { permissionMode: 'readOnlyAsk', bypassPermission: true }))
+ .toEqual([engineBin('codex'), '--ask-for-approval', 'on-request', '--sandbox', 'read-only', '-c', 'approvals_reviewer="user"', ...CODEX_SCREEN])
expect(buildEngineCommandArgv('codex', { permissionMode: 'full' }))
.toEqual([engineBin('codex'), '--dangerously-bypass-approvals-and-sandbox', ...CODEX_SCREEN])
// A mode the engine lacks falls back to the yes/no.
@@ -1262,6 +1265,17 @@ describe('the permission gates', () => {
expect(refusal?.detail).not.toContain('choose Ask')
})
+ it('holds a Buddy\'s relaunch rather than starting it without its mode (security review 1 of #2087)', async () => {
+ const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-gate-'))
+ dirs.push(binDir)
+ process.env.HARNESS_ENGINE_TEST_PATH = binDir
+ fakeEngine(binDir, 'codex', '--sandbox')
+ const held = await dropPermissionFlagIfUnsupported('codex', { permissionMode: 'readOnlyAsk', bypassPermission: false }, bashProbeShell())
+ expect(held.choice).toEqual({ permissionMode: 'readOnlyAsk', bypassPermission: false })
+ expect(held.droppedFlag).toBeNull()
+ expect(held.nativeHold).toContain('does not support --ask-for-approval')
+ })
+
it('leaves a relaunch alone when the flag is supported', async () => {
const shell = withFakeOpencode('--auto')
const kept = await dropPermissionFlagIfUnsupported('opencode', { permissionMode: 'auto', bypassPermission: true }, shell)
diff --git a/cli/src/lib/engineLaunch.ts b/cli/src/lib/engineLaunch.ts
index e92876ee6..c42899dd5 100644
--- a/cli/src/lib/engineLaunch.ts
+++ b/cli/src/lib/engineLaunch.ts
@@ -75,6 +75,10 @@ export const PERMISSION_MODES: Readonly<Partial<Record<AgentEngine, Readonly<Rec
opencode: { auto: ['--auto'], ask: [] },
}
+/** Modes a relaunch never trades for the engine's own default when the engine on disk lacks their flag: a Buddy's, whose
+ * default would let it act with its person's own credentials (security review 1 of #2087). The relaunch is held. */
+const KEPT_PERMISSION_MODES: ReadonlySet<string> = new Set(['readOnlyAsk'])
+
/** The argv of [mode] for [engine], or null when the engine has no such mode. */
export function permissionModeFlags(engine: AgentEngine, mode: string): readonly string[] | null {
const modes = PERMISSION_MODES[engine]
@@ -1596,6 +1600,11 @@ export async function dropPermissionFlagIfUnsupported<T extends PermissionLaunch
if (support === 'unknown') return { choice, droppedFlag: null, nativeHold: 'Waiting to confirm the selected executable’s permission flags.' }
const droppedFlag = support === 'supported' ? null : native ? permissionFlagToVerify(engine, choice) : await unsupportedPermissionFlag(engine, choice, shell)
if (!droppedFlag) return { choice, droppedFlag: null }
+ if (choice.permissionMode && KEPT_PERMISSION_MODES.has(choice.permissionMode)) {
+ const update = engineUpdateCommand(engine)
+ return { choice, droppedFlag: null, nativeHold: `The ${engine} CLI on this machine does not support ${droppedFlag}, which this harness's `
+ + `permission mode needs. It stays stopped until ${engine} is updated${update ? ` (${update})` : ''}.` }
+ }
// Ask in its place, launched with no flag at all: Claude Code's Ask names its mode with the very flag a build
// this old may lack, so it goes as the engine's own default, which asked before auto mode existed.
return { choice: { ...choice, permissionMode: permissionModeFlags(engine, 'ask')?.length ? null : 'ask', bypassPermission: false }, droppedFlag }
diff --git a/cli/src/lib/remoteRelay.spec.ts b/cli/src/lib/remoteRelay.spec.ts
index a2e5a61e7..3f5b4fd9b 100644
--- a/cli/src/lib/remoteRelay.spec.ts
+++ b/cli/src/lib/remoteRelay.spec.ts
@@ -799,6 +799,34 @@ describe('RemoteRelayPool keeps background (isolated) clients cheap', () => {
}
})
+ // WebSocket roadmap Phase 1 item 6. The shelf held 4 per machine, and one more was torn down with no close frame, so
+ // the backend logged it as a dropped connection (1006) like any network failure, and nothing counted overflows.
+ it('the shelf keeps 8 warm background sessions per machine, and closes one more cleanly saying why', async () => {
+ const pool = new RemoteRelayPool(...ctorArgs)
+ const made: Array<{ ws: { close: ReturnType<typeof vi.fn>; terminate: ReturnType<typeof vi.fn> }; lingerTimer: ReturnType<typeof setTimeout> | null }> = []
+ const dialSpy = vi.spyOn(RemoteRelayPool.prototype as unknown as { connect: (machineId: string) => Promise<unknown> }, 'connect')
+ .mockImplementation(async function (this: unknown, machineId: string) {
+ const entry = fakeEntry({ attached: new Set(), sink: null, ws: { send: vi.fn(), close: vi.fn(), terminate: vi.fn() }, viewers: { reset: vi.fn(), close: vi.fn() } })
+ made.push(entry as unknown as typeof made[number])
+ ;(this as { entries: Map<string, unknown> }).entries.set(machineId, entry)
+ return entry
+ })
+ try {
+ const sessions = []
+ for (let i = 0; i < 9; i++) sessions.push(await pool.acquireIsolated('m1', 'env', select, sink(), vi.fn()))
+ for (const session of sessions) session.detach()
+ expect(pool.idleIsolatedCount('m1')).toBe(8)
+ const shut = made.filter((entry) => entry.ws.close.mock.calls.length > 0)
+ expect(shut).toHaveLength(1)
+ expect(shut[0].ws.close).toHaveBeenCalledWith(1000, 'shelf full')
+ expect(made.some((entry) => entry.ws.terminate.mock.calls.length > 0)).toBe(false)
+ for (const entry of made) clearTimeout(entry.lingerTimer!)
+ } finally {
+ pool.close()
+ dialSpy.mockRestore()
+ }
+ })
+
it('a failed background dial is answered from the failure for the cooldown, not re-dialled per poll', async () => {
vi.useFakeTimers()
try {
diff --git a/cli/src/lib/remoteRelay.ts b/cli/src/lib/remoteRelay.ts
index f83d7960c..88160a19d 100644
--- a/cli/src/lib/remoteRelay.ts
+++ b/cli/src/lib/remoteRelay.ts
@@ -63,8 +63,10 @@ const REFUSED_BACKOFF_MAX_MS = 30_000
const RETRY_AFTER_MAX_MS = 5 * 60_000
// Warm background sessions kept per machine. Each concurrent background client needs its own (they
// must not see each other's frames), so the cap is "how many pollers may overlap on one machine and
-// still find a warm session"; beyond it the extra session is torn down on detach as it always was.
-const ISOLATED_IDLE_MAX = 4
+// still find a warm session"; beyond it the extra session is closed on detach, as `shelf full`, so the backend's
+// disconnect lines count it. 4 until the WebSocket roadmap's Phase 1 (item 6): each idle session costs the backend one
+// quiet socket, and with no count of the overflows the cap was doubled rather than tuned; those lines tune it next.
+const ISOLATED_IDLE_MAX = 8
// Same convention/value as localWsServer.ts's app<->daemon heartbeat. Without this, a machine-node
// cycling (e.g. `harness start` on the OTHER end after a crash/restart) can leave this daemon holding
// an upstream socket the backend silently dropped with no close frame — every RPC sent through it then
@@ -369,7 +371,7 @@ export class RemoteRelayPool {
detached = true
session.detach() // the pool's own linger starts here
const idle = this.idleIsolated.get(machineId) ?? []
- if (idle.length >= ISOLATED_IDLE_MAX) { pool.invalidate(machineId); return }
+ if (idle.length >= ISOLATED_IDLE_MAX) { pool.invalidate(machineId, { code: 1000, reason: 'shelf full' }); return }
idle.push(pool)
this.idleIsolated.set(machineId, idle)
},
@@ -392,7 +394,7 @@ export class RemoteRelayPool {
* without ever touching this socket (nothing else — not even the heartbeat, since backend itself
* keeps answering pings fine — would ever notice on its own). Signalled by the local client sending
* `forceReconnect: true` on a fresh `machine_select` after observing a live RPC time out. */
- invalidate(machineId: string): void {
+ invalidate(machineId: string, close?: { code: number; reason: string }): void {
const entry = this.entries.get(machineId)
if (!entry) return
this.entries.delete(machineId)
@@ -410,7 +412,8 @@ export class RemoteRelayPool {
entry.onClosed = null
void entry.p2p?.stop('invalidated', false)
entry.p2p = null
- try { entry.ws.terminate() } catch { /* already gone */ }
+ // A healthy session put away is closed saying why; one known dead is cut.
+ try { if (close) entry.ws.close(close.code, close.reason); else entry.ws.terminate() } catch { /* already gone */ }
}
/** Every session this pool holds, ended, for a gateway that is going (its core went away, or it is
diff --git a/cli/src/lib/swarmSkills.spec.ts b/cli/src/lib/swarmSkills.spec.ts
index f63f52757..96ad63815 100644
--- a/cli/src/lib/swarmSkills.spec.ts
+++ b/cli/src/lib/swarmSkills.spec.ts
@@ -101,8 +101,25 @@ describe('built-in Swarm skills', () => {
['default', 'dev', "- Mark ready for review, with the revision and the PR link, when the work needs review: the Swarm opens the review from your handoff. Otherwise mark done.\n",
"- Mark ready for review when the group has a Reviewer; otherwise mark done.\n"],
]
- const approved = (text: string, mode: 'orchestration' | 'default') =>
- autoReview.filter(([m]) => m === mode).reduce((t, [, , line, before]) => t.replace(line, before), text)
+ // Fail fast on a missing tool (Tony 10-29: a device build sat an hour on his Mac's Team account, which had no Flutter and no
+ // iPhone): the Builder's and the Reviewer's check, in both modes, and the Lead's move, in both modes.
+ const toolCheck = '- In your first minutes, check that this machine and account have every tool, device and sign-in you need to do the work yourself (for example flutter, xcodebuild, a connected iPhone, a signed-in gh or App Store account, docker); a device step the brief leaves to a person stays a "Needs:" line. If one is missing, mark blocked at once and stop (see Blocked).\n'
+ // The stop lives in the Builder's Blocked section, the only place its skill lets it stop (review of #2096).
+ const missingStop = '- A missing tool, device or sign-in on this machine and account: mark blocked at once, naming what is missing, the machine, and whether it is the owner\'s or the Team account (no emails or tokens), and stop: the Lead moves the task. Never wait silently.\n'
+ // The Reviewer's, at the end of its first paragraph.
+ const reviewCheck = ' In your first minutes, check that this machine and account have every tool, device and sign-in the review needs; if one is missing, mark blocked at once, naming what is missing, the machine, and whether it is the owner\'s or the Team account (no emails or tokens), and stop: the Lead moves the task.'
+ const moveMissing = '- A Builder or Reviewer blocked on a missing tool, device or sign-in: within minutes, route the task again with what was missing in its needs (fix its required machine if that is the one without it), assign it to a machine and account that has it, then stop the blocked agent unless other work fits its machine. A Mac\'s own account and its Team account are different: the Team account has none of the owner\'s tools, devices or sign-ins. If none has it, tag the requester with the choice.\n'
+ // The Builder's check replaces its machine-or-device line; the Default Builder keeps the person part of it. The orchestration
+ // Builder's "missing machine" now means another machine, since its own is the stop above.
+ const failFast: Array<['orchestration' | 'default', 'lead' | 'dev', string, string]> = [
+ ['orchestration', 'dev', toolCheck, '- If the brief needs a machine or device, check it is reachable and usable before you start; if not, mark blocked with a "Needs:" line.\n'],
+ ['orchestration', 'dev', 'Another machine the work needs, test data, or a person\'s hands is still a "Needs:" line;', 'A missing machine, test data, or a person\'s hands is still a "Needs:" line;'],
+ ['default', 'dev', `${toolCheck}- If the brief needs a person, check they are available; if not, post a "Needs:" line and do the parts that don't depend on it.\n`,
+ '- If the brief needs a machine, device or person, check it is available; if not, post a "Needs:" line and do the parts that don\'t depend on it.\n'],
+ ]
+ // By role too: the Builder's and the Reviewer's tool-check line is the same, and only the Builder's replaced an approved one.
+ const approved = (text: string, mode: 'orchestration' | 'default', role: 'lead' | 'dev' | 'review') =>
+ [...autoReview, ...failFast].filter(([m, r]) => m === mode && r === role).reduce((t, [, , line, before]) => t.replace(line, before), text)
it('tells each Lead the Swarm opens reviews by itself, and each Builder to hand off with a pull request link', () => {
for (const [mode, role, line, before] of autoReview) {
const text = readFileSync(prepareSwarmSkill(fixture(), { role, key: 'session', mode }).file, 'utf8')
@@ -140,8 +157,13 @@ describe('built-in Swarm skills', () => {
expect(text.split(failedStart)).toHaveLength(role === 'lead' ? 2 : 1)
expect(text.split(shared)).toHaveLength(role === 'lead' ? 1 : 2)
expect(text.split(report)).toHaveLength(role === 'lead' ? 2 : 1)
- expect(sha(approved(text, 'orchestration').replace(twoHours, '').replace(terminal, '').replace(overlap, '').replace(local, '').replace(failedStart, '').replace(mention, '').replace(lost, '').replace(checkpoint, '')
- .replace(limit, '').replace(digest, '').replace(decision, '').replace(ask, '').replace(requests, '').replace(shared, '').replace(report, ''))).toBe(sha256)
+ expect(text.split(toolCheck)).toHaveLength(role === 'dev' ? 2 : 1)
+ expect(text.split(missingStop)).toHaveLength(role === 'dev' ? 2 : 1)
+ expect(text.split(reviewCheck)).toHaveLength(role === 'review' ? 2 : 1)
+ expect(text.split(moveMissing)).toHaveLength(role === 'lead' ? 2 : 1)
+ expect(sha(approved(text, 'orchestration', role).replace(twoHours, '').replace(terminal, '').replace(overlap, '').replace(local, '').replace(failedStart, '').replace(mention, '').replace(lost, '').replace(checkpoint, '')
+ .replace(limit, '').replace(digest, '').replace(decision, '').replace(ask, '').replace(requests, '').replace(shared, '').replace(report, '')
+ .replace(missingStop, '').replace(reviewCheck, '').replace(moveMissing, ''))).toBe(sha256)
}
})
it('adds the 2-hour line to section 7 right after the 6-hour rule', () => {
@@ -179,7 +201,7 @@ describe('built-in Swarm skills', () => {
const orchestration = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session' }).file, 'utf8')
expect(orchestration).toContain(`- Needs-human: get the person's decision now.\n${mention}${decision}- Blocked: change something.`)
const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session', mode: 'default' }).file, 'utf8')
- expect(plain).toContain(`- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.\n${mention}${decision}- Settle ambiguities`)
+ expect(plain).toContain(`- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.\n${mention}${decision}`)
})
it('adds the decision lines right after the mention line for the Lead, and after the needs-human rule for the Builder', () => {
for (const mode of ['orchestration', 'default'] as const) {
@@ -230,6 +252,30 @@ describe('built-in Swarm skills', () => {
const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'dev', key: 'session', mode: 'default' }).file, 'utf8')
expect(plain).toContain(`- Have something to show at least every 20 minutes: a push or a short progress line.\n${checkpoint}`)
})
+ it('has each Builder check its tools first, and stop from its Blocked section when one is missing', () => {
+ const orchestration = readFileSync(prepareSwarmSkill(fixture(), { role: 'dev', key: 'session' }).file, 'utf8')
+ expect(orchestration).toContain(`and rule on mismatches.\n${toolCheck}- If something you need is missing,`)
+ expect(orchestration).toContain(`- Post a "Needs:" line, continue the independent parts, and mark working again once it moves.\n${missingStop}- Stop for a decision only`)
+ expect(orchestration).not.toContain('check it is reachable and usable before you start')
+ expect(orchestration).not.toContain('A missing machine, test data')
+ expect(orchestration).toContain('Another machine the work needs, test data, or a person\'s hands is still a "Needs:" line; continue the independent parts.')
+ const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'dev', key: 'session', mode: 'default' }).file, 'utf8')
+ expect(plain).toContain(`- Read how the code behaves today before changing it.\n${toolCheck}- If the brief needs a person, check they are available;`)
+ expect(plain).toContain(`- Can't go on: mark blocked with why and what would unblock you, then do the independent parts.\n${missingStop}- Stop and ask`)
+ expect(plain).not.toContain('If the brief needs a machine, device or person')
+ })
+ it('has each Reviewer check its tools at the end of its first paragraph', () => {
+ const orchestration = readFileSync(prepareSwarmSkill(fixture(), { role: 'review', key: 'session' }).file, 'utf8')
+ expect(orchestration).toContain(`if you cannot, tell the Lead.${reviewCheck}\n\n## 2. What to check, in order`)
+ const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'review', key: 'session', mode: 'default' }).file, 'utf8')
+ expect(plain).toContain(`If you cannot, tell the Lead.${reviewCheck}\n\n## 2. What to look for`)
+ })
+ it('has each Lead move a task blocked on a missing tool: after its blocked rule, or after the decision lines in Default', () => {
+ const orchestration = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session' }).file, 'utf8')
+ expect(orchestration).toContain(`Never resend the same thing to the same model.\n${moveMissing}- Rulings, not stalls`)
+ const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session', mode: 'default' }).file, 'utf8')
+ expect(plain).toContain(`${decision}${moveMissing}- Settle ambiguities`)
+ })
// The owner's approved Default texts (attached to the spec, 2026-10-23), byte for byte.
it.each([
['lead', '8de53bf338b564fe1cec581a302280b778d1e62e788f8e310b36b5ad1d8f3309'],
@@ -254,8 +300,13 @@ describe('built-in Swarm skills', () => {
expect(text.split(failedStart)).toHaveLength(role === 'lead' ? 2 : 1)
expect(text.split(sharedLast)).toHaveLength(role === 'lead' ? 1 : 2)
expect(text.split(report)).toHaveLength(role === 'lead' ? 2 : 1)
- expect(sha(approved(text, 'default').replace(terminal, '').replace(overlap, '').replace(localDefault, '').replace(failedStart, '').replace(mention, '').replace(lost, '').replace(checkpoint, '')
- .replace(limit, '').replace(digest, '').replace(decision, '').replace(ask, '').replace(requestsLast, '').replace(sharedLast, '').replace(report, ''))).toBe(sha256)
+ expect(text.split(toolCheck)).toHaveLength(role === 'dev' ? 2 : 1)
+ expect(text.split(missingStop)).toHaveLength(role === 'dev' ? 2 : 1)
+ expect(text.split(reviewCheck)).toHaveLength(role === 'review' ? 2 : 1)
+ expect(text.split(moveMissing)).toHaveLength(role === 'lead' ? 2 : 1)
+ expect(sha(approved(text, 'default', role).replace(terminal, '').replace(overlap, '').replace(localDefault, '').replace(failedStart, '').replace(mention, '').replace(lost, '').replace(checkpoint, '')
+ .replace(limit, '').replace(digest, '').replace(decision, '').replace(ask, '').replace(requestsLast, '').replace(sharedLast, '').replace(report, '')
+ .replace(missingStop, '').replace(reviewCheck, '').replace(moveMissing, ''))).toBe(sha256)
expect(prepared.instructions).toBe(`Use the swarm-${role} skill for this session: the team process; otherwise work your usual way. Before working, read ${JSON.stringify(prepared.file)} with your file or shell tool.`)
})
diff --git a/cli/src/lib/swarmSkills.ts b/cli/src/lib/swarmSkills.ts
index e8b9a12ef..691f6799f 100644
--- a/cli/src/lib/swarmSkills.ts
+++ b/cli/src/lib/swarmSkills.ts
@@ -109,6 +109,7 @@ For large work, post the group plan and get the owner's ok before assigning; onc
- When you need a person to act or decide, tag them in the message.
- Ask people for decisions in one place: decision.ask puts up to 10 questions to one person at once, each with 2 to 5 options, the one you recommend and what the answer unblocks. Keep working on your recommendation, marked provisional, until they answer: a notice in that conversation tells you, and harness super-tab decisions --answered shows the answer. A decision is not a private channel: anything private goes through Chat with PM.
- Blocked: change something. Give more context, re-route to a stronger model, cut the work smaller, or fix the plan. Never resend the same thing to the same model.
+- A Builder or Reviewer blocked on a missing tool, device or sign-in: within minutes, route the task again with what was missing in its needs (fix its required machine if that is the one without it), assign it to a machine and account that has it, then stop the blocked agent unless other work fits its machine. A Mac's own account and its Team account are different: the Team account has none of the owner's tools, devices or sign-ins. If none has it, tag the requester with the choice.
- Rulings, not stalls: when a Builder hits an ambiguity you can settle, settle it and record "Ruling: what — why — cost if wrong". Ask the person only what changes what gets built.
- Each time you are woken, look at active work. Ask a worker with active work that has said nothing for 20 minutes; reassign work that has not moved for 6 hours; report on-screen trust, sign-in or permission questions in chat, naming the machine owner who can answer.
- A Builder or Reviewer that has been down for 2 hours (machine offline, session gone or stopped): cancel its task with the reason, route it, and assign it to another agent with what the first one left (branch, last revision, last report).
@@ -191,7 +192,7 @@ You finish one group's work completely, inside its brief, with proof. Work as if
- Say in the group chat that you took it and what your first step is; mark it working.
- Read the brief: goal, spec, changes, constraints, owned code, consumes and produces, checks, most likely wrong, hand back, needs, carry-over. If the brief links the spec, read it.
- Before step one, check what your brief consumes against what the producing group or code actually provides, and rule on mismatches.
-- If the brief needs a machine or device, check it is reachable and usable before you start; if not, mark blocked with a "Needs:" line.
+- In your first minutes, check that this machine and account have every tool, device and sign-in you need to do the work yourself (for example flutter, xcodebuild, a connected iPhone, a signed-in gh or App Store account, docker); a device step the brief leaves to a person stays a "Needs:" line. If one is missing, mark blocked at once and stop (see Blocked).
- If something you need is missing, ask the Lead for all of it at once, and continue what doesn't depend on it.
- Harness already created your worktree; do not create another. Run the project's tests before changing anything, and report failures that existed before your change by name. If baseline failures touch your owned code, ask the Lead before relying on them, and continue the parts they don't touch.
@@ -236,7 +237,8 @@ With several clearly separate failures, you may start read-only subagents to inv
- When you know who decides, add ask to that needs-human (the person, 2 to 5 options, the one you recommend, what it unblocks) and keep working on your recommendation, marked provisional, until a notice says it was answered; read the answer with harness super-tab decisions --answered.
- Can't go on: mark blocked with why, and what would unblock you.
- Post a "Needs:" line, continue the independent parts, and mark working again once it moves.
-- Stop for a decision only for an irreversible or destructive step, a security-sensitive action, an effect outside your worktree, or a brief so broken that every path is a guess. Settle other ambiguity with the narrowest safe reading and a Ruling, and keep going. A missing machine, test data, or a person's hands is still a "Needs:" line; continue the independent parts.
+- A missing tool, device or sign-in on this machine and account: mark blocked at once, naming what is missing, the machine, and whether it is the owner's or the Team account (no emails or tokens), and stop: the Lead moves the task. Never wait silently.
+- Stop for a decision only for an irreversible or destructive step, a security-sensitive action, an effect outside your worktree, or a brief so broken that every path is a guess. Settle other ambiguity with the narrowest safe reading and a Ruling, and keep going. Another machine the work needs, test data, or a person's hands is still a "Needs:" line; continue the independent parts.
- Escalate to the Lead with a "Needs:" line when the work needs an architecture choice between valid options, code you cannot understand, or restructuring the brief did not plan; or when you doubt your approach or keep reading without progress. Keep doing the independent parts; bad work is worse than none.
- Read an ambiguous answer in its narrowest safe sense, and record that reading.
- Write to people briefly, in their language, without commands or internal IDs. Call the roles Product Manager, Engineer and Reviewer.
@@ -315,7 +317,7 @@ You give an independent verdict on one revision. You judge the work product, not
4. Project instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) outrank this skill; judge against them.
## 1. Inputs
-You get the goal, constraints, owned code, acceptance checks, most-likely-wrong list, the Builder's rulings, the revision range and the Builder's handoff. You do not get the chat history. If something essential is missing, ask the Lead once. Start reading within 30 minutes of the request; if you cannot, tell the Lead.
+You get the goal, constraints, owned code, acceptance checks, most-likely-wrong list, the Builder's rulings, the revision range and the Builder's handoff. You do not get the chat history. If something essential is missing, ask the Lead once. Start reading within 30 minutes of the request; if you cannot, tell the Lead. In your first minutes, check that this machine and account have every tool, device and sign-in the review needs; if one is missing, mark blocked at once, naming what is missing, the machine, and whether it is the owner's or the Team account (no emails or tokens), and stop: the Lead moves the task.
## 2. What to check, in order
1. Brief compliance: everything asked for is present; when the brief lists several files each with its own change, check that each has it. Flag each deviation so the Builder can say if it was intended. If the brief or spec itself is wrong, say so.
@@ -416,6 +418,7 @@ Keep each Builder's list a few tasks deep; do the easy, self-contained parts fir
- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.
- When you need a person to act or decide, tag them in the message.
- Ask people for decisions in one place: decision.ask puts up to 10 questions to one person at once, each with 2 to 5 options, the one you recommend and what the answer unblocks. Keep working on your recommendation, marked provisional, until they answer: a notice in that conversation tells you, and harness super-tab decisions --answered shows the answer. A decision is not a private channel: anything private goes through Chat with PM.
+- A Builder or Reviewer blocked on a missing tool, device or sign-in: within minutes, route the task again with what was missing in its needs (fix its required machine if that is the one without it), assign it to a machine and account that has it, then stop the blocked agent unless other work fits its machine. A Mac's own account and its Team account are different: the Team account has none of the owner's tools, devices or sign-ins. If none has it, tag the requester with the choice.
- Settle ambiguities you can and record "Ruling: what — why — cost if wrong".
- When a worker finishes: reuse, keep or stop. Prefer stop.
@@ -457,7 +460,8 @@ You finish one group's work completely, inside its brief, as if nobody will come
- Say in the group that you took it and what you will do first; mark it working.
- Read the whole brief: why, wanted, owned code, hand back, checks, most likely wrong, needs.
- Read how the code behaves today before changing it.
-- If the brief needs a machine, device or person, check it is available; if not, post a "Needs:" line and do the parts that don't depend on it.
+- In your first minutes, check that this machine and account have every tool, device and sign-in you need to do the work yourself (for example flutter, xcodebuild, a connected iPhone, a signed-in gh or App Store account, docker); a device step the brief leaves to a person stays a "Needs:" line. If one is missing, mark blocked at once and stop (see Blocked).
+- If the brief needs a person, check they are available; if not, post a "Needs:" line and do the parts that don't depend on it.
- Harness already created your worktree; work there.
## 2. Do the work
@@ -473,6 +477,7 @@ You finish one group's work completely, inside its brief, as if nobody will come
- A person's decision: mark needs-human with one short question.
- When you know who decides, add ask to that needs-human (the person, 2 to 5 options, the one you recommend, what it unblocks) and keep working on your recommendation, marked provisional, until a notice says it was answered; read the answer with harness super-tab decisions --answered.
- Can't go on: mark blocked with why and what would unblock you, then do the independent parts.
+- A missing tool, device or sign-in on this machine and account: mark blocked at once, naming what is missing, the machine, and whether it is the owner's or the Team account (no emails or tokens), and stop: the Lead moves the task. Never wait silently.
- Stop and ask before anything irreversible, security-sensitive, outside your worktree, visible or audible on a real device, or moving hardware.
## 4. Hand off
@@ -511,7 +516,7 @@ You give an independent verdict on one revision. Work otherwise the way you norm
4. Project instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) outrank this skill.
## 1. When
-Start within 30 minutes of being asked; oldest ready work first. If you cannot, tell the Lead.
+Start within 30 minutes of being asked; oldest ready work first. If you cannot, tell the Lead. In your first minutes, check that this machine and account have every tool, device and sign-in the review needs; if one is missing, mark blocked at once, naming what is missing, the machine, and whether it is the owner's or the Team account (no emails or tokens), and stop: the Lead moves the task.
## 2. What to look for
- Wrong behaviour, missed cases, and what the brief asked for but is missing.
@@ -626,8 +631,8 @@ const BUDDY_CLAUDE_SETTINGS = { permissions: { defaultMode: 'default', allow: ['
/**
* A Buddy never changes code (Lead's ruling, privacy review of #1992): its own worktree gets Claude Code's settings above,
* and every file in it is made read-only. Its folders stay writable, so the worktree is removed like any other, and the
- * Harness runtime folder (its skill and records) is left alone. A Codex Buddy keeps full permissions, under which read-only
- * files only slow it down: it runs only on its owner's own machine (backend commands.ts buddy.create).
+ * Harness runtime folder (its skill and records) is left alone. A Codex Buddy runs in Codex's read-only sandbox instead,
+ * asking before anything outside it (superTabs/start.ts), on its owner's own machine only (backend commands.ts buddy.create).
*/
function lockBuddyFolder(root: string): void {
const settings = join(root, '.claude', 'settings.local.json')
diff --git a/cli/src/services/processCoreApi.spec.ts b/cli/src/services/processCoreApi.spec.ts
index e254b3b4a..3dc94defd 100644
--- a/cli/src/services/processCoreApi.spec.ts
+++ b/cli/src/services/processCoreApi.spec.ts
@@ -69,6 +69,19 @@ describe('the core API a light service runs on in its own process', () => {
ask.mockRejectedValueOnce(new Error('offline'))
expect(await api.usage!(target)).toBeNull()
})
+ it('reads an agent’s usage fresh through the core, validated, and nothing without a core', async () => {
+ expect(await processCoreApi('/data', 'superTabs').usageFresh!('a')).toBeNull()
+ const ask = vi.fn(async (_type: string, _payload: Record<string, unknown>): Promise<Record<string, unknown>> => ({ value: { totalTokens: 4, updatedAt: '2026-10-01T00:00:00Z' } }))
+ const api = processCoreApi('/data', 'superTabs', { ask })
+ expect(await api.usageFresh!('a')).toEqual({ totalTokens: 4, updatedAt: '2026-10-01T00:00:00Z' })
+ expect(ask).toHaveBeenCalledWith('agentUsageFresh', { agentId: 'a' })
+ for (const answer of [{}, { error: 'STALE_USAGE_TARGET' }, { value: { totalTokens: -1 } }]) {
+ ask.mockResolvedValueOnce(answer)
+ expect(await api.usageFresh!('a')).toBeNull()
+ }
+ ask.mockRejectedValueOnce(new Error('offline'))
+ expect(await api.usageFresh!('a')).toBeNull()
+ })
it('answers the agents from what the core last said, by agent id or session id', () => {
const live = [agent('a1'), agent('a2')]
const api = processCoreApi('/data', 'projects', { live: () => live, advertised: () => [live[1]] })
diff --git a/cli/src/services/processCoreApi.ts b/cli/src/services/processCoreApi.ts
index 8381510f6..630d964da 100644
--- a/cli/src/services/processCoreApi.ts
+++ b/cli/src/services/processCoreApi.ts
@@ -114,6 +114,10 @@ export function processCoreApi(dataDir: string, service: string, view: AgentsVie
const answer = await ask?.('agentUsage', { target: usageTarget(target) }).catch(() => null)
return validUsageTarget(answer?.target) && usageTargetKey(answer.target) === usageTargetKey(target) && validUsage(answer?.value) ? usageSnapshot(answer.value) : null
},
+ usageFresh: async agentId => {
+ const answer = await ask?.('agentUsageFresh', { agentId }).catch(() => null)
+ return answer && 'value' in answer && validUsage(answer.value) ? usageSnapshot(answer.value) : null
+ },
conversations: CONVERSATIONS_OFF,
// Terminals are launched by the core alone (the shell service, #893): a service in its own process
// is refused, never handed a way to start a process outside the core.
diff --git a/cli/src/sharing/relay.spec.ts b/cli/src/sharing/relay.spec.ts
index ec8f176e3..34e0e1f64 100644
--- a/cli/src/sharing/relay.spec.ts
+++ b/cli/src/sharing/relay.spec.ts
@@ -23,19 +23,25 @@ describe('recipient relay', () => {
const share = { id: 'share', agentId: 'agent', name: 'Demo', engine: null,
ownerPublicKey: b64e(identity.pub), expiresAt: new Date(Date.now() + 100000).toISOString() }
let relay: HarnessShareRelay
+ let account: string
+ let tokens: ReturnType<typeof vi.fn<() => Promise<string>>>
let discover: ReturnType<typeof vi.fn<() => Promise<any[]>>>
let sink: { sendFrame: ReturnType<typeof vi.fn>; sendBinary: ReturnType<typeof vi.fn> }, closed: ReturnType<typeof vi.fn<(code: number, reason: string) => void>>
beforeEach(() => {
vi.useFakeTimers(); state.sockets = []; state.stop.mockReset()
sink = { sendFrame: vi.fn(() => true), sendBinary: vi.fn(() => true) }; closed = vi.fn()
discover = vi.fn(async () => [{ machineId: 'machine', shares: [share] }])
- relay = new HarnessShareRelay({ accessToken: async () => 'signed-in-token' } as AuthSessionManager,
- 'ws://localhost:1234/', 'prod', discover)
+ account = 'first'
+ tokens = vi.fn(async () => 'signed-in-token')
+ relay = new HarnessShareRelay({ accessToken: tokens } as unknown as AuthSessionManager,
+ 'ws://localhost:1234/', 'prod', discover, () => account)
})
afterEach(() => { relay.close(); vi.useRealTimers() })
async function begin() {
+ const count = state.sockets.length
const pending = relay.acquire('machine', 'share', sink as never, closed)
- await Promise.resolve(); await Promise.resolve()
+ // Its socket opens once the share is found: wait for that, however many steps it takes.
+ for (let i = 0; i < 100 && state.sockets.length === count; i++) await Promise.resolve()
const ws = state.sockets.at(-1)
ws.emit('open')
return { pending, ws }
@@ -159,4 +165,266 @@ describe('recipient relay', () => {
log.mockRestore()
})
+ // Every window opened on a shared harness asked the backend for the account's whole list of shares first
+ // (WebSocket roadmap Phase 1 item 5). The list is kept now; the backend still checks the share on every connect.
+ describe('the list of shares', () => {
+ it('is read once for windows opened within a minute', async () => {
+ (await ready()).session.detach()
+ await vi.advanceTimersByTimeAsync(59_000);
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledOnce()
+ })
+
+ it('is read again after a minute', async () => {
+ (await ready()).session.detach()
+ await vi.advanceTimersByTimeAsync(60_000);
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(2)
+ })
+
+ it('is read again for a share it does not hold, so a new invitation opens at once', async () => {
+ (await ready()).session.detach()
+ const invited = { ...share, id: 'invited' }
+ discover.mockResolvedValue([{ machineId: 'machine', shares: [share, invited] }])
+ const pending = relay.acquire('machine', 'invited', sink as never, closed)
+ await vi.advanceTimersByTimeAsync(0)
+ expect(discover).toHaveBeenCalledTimes(2)
+ expect(state.sockets.at(-1).args[0]).toContain('share=invited')
+ pending.catch(() => {})
+ })
+
+ it('is read again for a share it holds that has expired', async () => {
+ (await ready()).session.detach()
+ await vi.setSystemTime(new Date(share.expiresAt).getTime() + 1)
+ discover.mockResolvedValue([])
+ await expect(relay.acquire('machine', 'share', sink as never, closed)).rejects.toBeInstanceOf(SharingEndedError)
+ expect(discover).toHaveBeenCalledTimes(2)
+ })
+
+ // The backend lists the shares it still honours; this computer's clock may run ahead of it.
+ it('opens a share the backend has just listed, whatever this computer\'s clock says of its expiry', async () => {
+ await vi.setSystemTime(new Date(share.expiresAt).getTime() + 1)
+ const { pending } = await begin()
+ pending.catch(() => {})
+ expect(state.sockets).toHaveLength(1)
+ })
+
+ it('is read once for windows that open together', async () => {
+ const first = relay.acquire('machine', 'share', sink as never, closed)
+ const second = relay.acquire('machine', 'share', sink as never, closed)
+ first.catch(() => {}); second.catch(() => {})
+ await vi.advanceTimersByTimeAsync(0)
+ expect(discover).toHaveBeenCalledOnce()
+ expect(state.sockets).toHaveLength(2)
+ })
+
+ it.each([
+ ['the owner ended the sharing', (ws: any) => frame(ws, 'observer_closed')],
+ ['the socket closed before the owner answered', (ws: any) => ws.emit('close', 4403, Buffer.from('Sharing ended or invitation expired'))],
+ ['the owner could not be verified', (ws: any) => frame(ws, 'observer_welcome', { ephemeral: 'forged', signature: 'forged' })],
+ ])('is read again after a window failed to open: %s', async (_why, fail) => {
+ const { pending, ws } = await begin()
+ const failed = expect(pending).rejects.toThrow()
+ frame(ws, 'observer_connected')
+ fail(ws)
+ await failed;
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(2)
+ })
+
+ it.each([
+ ['told the sharing ended', (ws: any) => frame(ws, 'observer_closed')],
+ ['closed as no longer shared', (ws: any) => ws.emit('close', 4403, Buffer.from('Access removed'))],
+ ])('is read again after an open window was %s', async (_how, end) => {
+ const { ws } = await ready()
+ end(ws);
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(2)
+ })
+
+ it('is kept when an open window lost its owner for a while', async () => {
+ const { ws } = await ready()
+ ws.emit('close', 1006, Buffer.alloc(0));
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledOnce()
+ })
+
+ it('is not kept when reading it failed', async () => {
+ discover.mockRejectedValueOnce(new Error('Shared harnesses are temporarily unavailable.'))
+ await expect(relay.acquire('machine', 'share', sink as never, closed)).rejects.toThrow('temporarily unavailable');
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(2)
+ })
+
+ it('answers nothing once another account signs in', async () => {
+ (await ready()).session.detach()
+ account = 'second';
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(2)
+ })
+
+ it('read for one account is not kept when another signed in meanwhile', async () => {
+ let answer: ((machines: any[]) => void) | null = null
+ discover.mockImplementationOnce(() => new Promise(resolve => { answer = resolve }))
+ const pending = relay.acquire('machine', 'share', sink as never, closed)
+ pending.catch(() => {})
+ await vi.advanceTimersByTimeAsync(0)
+ account = 'second'
+ answer!([{ machineId: 'machine', shares: [share] }])
+ await vi.advanceTimersByTimeAsync(0);
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(2)
+ })
+
+ // Review of #2107, finding 1: the list read for one sign-in opened a window with the next sign-in's token.
+ it('a window whose list was read for another sign-in opens nothing with the new one', async () => {
+ let answer: ((machines: any[]) => void) | null = null
+ discover.mockImplementationOnce(() => new Promise(resolve => { answer = resolve }))
+ .mockImplementationOnce(async () => [])
+ const pending = relay.acquire('machine', 'share', sink as never, closed)
+ await vi.advanceTimersByTimeAsync(0)
+ account = 'second'
+ answer!([{ machineId: 'machine', shares: [share] }])
+ await expect(pending).rejects.toBeInstanceOf(SharingEndedError)
+ expect(discover).toHaveBeenCalledTimes(2)
+ expect(state.sockets).toHaveLength(0)
+ })
+
+ it('a window whose sign-in changed while it fetched its token opens nothing with the new one', async () => {
+ let tokenAnswer: ((token: string) => void) | null = null
+ const tokens = vi.fn<() => Promise<string>>(async () => `token-${account}`)
+ const fenced = new HarnessShareRelay({ accessToken: tokens } as unknown as AuthSessionManager, 'ws://localhost:1234/', 'prod', discover, () => account)
+ try {
+ tokens.mockImplementationOnce(() => new Promise(resolve => { tokenAnswer = resolve }))
+ const pending = fenced.acquire('machine', 'share', sink as never, closed)
+ await vi.advanceTimersByTimeAsync(0)
+ expect(tokens).toHaveBeenCalledOnce()
+ discover.mockResolvedValue([])
+ account = 'second'
+ tokenAnswer!('token-first')
+ await expect(pending).rejects.toBeInstanceOf(SharingEndedError)
+ expect(state.sockets).toHaveLength(0)
+ } finally { fenced.close() }
+ })
+
+ // Finding 2: a refresh that failed left the list it was replacing in use.
+ it('is not used after a refresh of it failed', async () => {
+ (await ready()).session.detach()
+ discover.mockRejectedValueOnce(new Error('Shared harnesses are temporarily unavailable.'))
+ await expect(relay.acquire('machine', 'missing', sink as never, closed)).rejects.toThrow('temporarily unavailable');
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(3)
+ })
+
+ // Re-check of #2107: a window that took its share from the kept list and was waiting for its token still opened
+ // after another window's refresh failed.
+ it('a window waiting for its token looks again after another window\'s refresh failed', async () => {
+ (await ready()).session.detach()
+ let tokenAnswer: ((token: string) => void) | null = null
+ tokens.mockImplementationOnce(() => new Promise(resolve => { tokenAnswer = resolve }))
+ const before = state.sockets.length
+ const waiting = relay.acquire('machine', 'share', sink as never, closed)
+ await vi.advanceTimersByTimeAsync(0)
+ expect(tokenAnswer).not.toBeNull()
+ discover.mockRejectedValueOnce(new Error('Shared harnesses are temporarily unavailable.'))
+ .mockResolvedValueOnce([])
+ await expect(relay.acquire('machine', 'missing', sink as never, closed)).rejects.toThrow('temporarily unavailable')
+ tokenAnswer!('signed-in-token')
+ await expect(waiting).rejects.toBeInstanceOf(SharingEndedError)
+ expect(discover).toHaveBeenCalledTimes(3)
+ expect(state.sockets).toHaveLength(before)
+ })
+
+ it('a refresh that fails for a sign-in no longer current leaves the current list alone', async () => {
+ let fail: ((error: Error) => void) | null = null
+ discover.mockImplementationOnce(() => new Promise((_resolve, reject) => { fail = reject }))
+ relay.acquire('machine', 'missing', sink as never, closed).catch(() => {})
+ await vi.advanceTimersByTimeAsync(0)
+ account = 'second';
+ (await ready()).session.detach()
+ fail!(new Error('Shared harnesses are temporarily unavailable.'))
+ await vi.advanceTimersByTimeAsync(0);
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(2)
+ })
+
+ // Finding 3: a refresh begun before a revocation brought the revoked list back, and later windows joined it.
+ it('a refresh begun before a revocation does not bring the list back', async () => {
+ const { ws } = await ready()
+ let answer: ((machines: any[]) => void) | null = null
+ discover.mockImplementationOnce(() => new Promise(resolve => { answer = resolve }))
+ const missing = relay.acquire('machine', 'missing', sink as never, closed)
+ missing.catch(() => {})
+ await vi.advanceTimersByTimeAsync(0)
+ ws.emit('close', 4403, Buffer.from('Sharing ended'))
+ answer!([{ machineId: 'machine', shares: [share] }])
+ await vi.advanceTimersByTimeAsync(0);
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(3)
+ })
+
+ it('a window opened after a revocation does not join a refresh begun before it', async () => {
+ const { ws } = await ready()
+ discover.mockImplementationOnce(() => new Promise(() => {}))
+ relay.acquire('machine', 'missing', sink as never, closed).catch(() => {})
+ await vi.advanceTimersByTimeAsync(0)
+ ws.emit('close', 4403, Buffer.from('Sharing ended'));
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(3)
+ })
+
+ it('a window whose list was revoked while it was read reads it again', async () => {
+ const { ws } = await ready()
+ let answer: ((machines: any[]) => void) | null = null
+ await vi.advanceTimersByTimeAsync(60_000)
+ discover.mockImplementationOnce(() => new Promise(resolve => { answer = resolve }))
+ .mockImplementationOnce(async () => [])
+ const pending = relay.acquire('machine', 'share', sink as never, closed)
+ await vi.advanceTimersByTimeAsync(0)
+ const before = state.sockets.length
+ ws.emit('close', 4403, Buffer.from('Sharing ended'))
+ answer!([{ machineId: 'machine', shares: [share] }])
+ await expect(pending).rejects.toBeInstanceOf(SharingEndedError)
+ expect(discover).toHaveBeenCalledTimes(3)
+ expect(state.sockets).toHaveLength(before)
+ })
+
+ it('a window whose sign-in keeps changing while it looks gives up after three lookups and opens nothing', async () => {
+ discover.mockImplementation(async () => { account = `${account}+`; return [{ machineId: 'machine', shares: [share] }] })
+ await expect(relay.acquire('machine', 'share', sink as never, closed)).rejects.toThrow('temporarily unavailable')
+ expect(discover).toHaveBeenCalledTimes(3)
+ expect(state.sockets).toHaveLength(0)
+ })
+
+ it('being read for one account does not end the read of another when it finishes', async () => {
+ let first: ((machines: any[]) => void) | null = null
+ let second: ((machines: any[]) => void) | null = null
+ discover.mockImplementationOnce(() => new Promise(resolve => { first = resolve }))
+ .mockImplementationOnce(() => new Promise(resolve => { second = resolve }))
+ relay.acquire('machine', 'share', sink as never, closed).catch(() => {})
+ await vi.advanceTimersByTimeAsync(0)
+ account = 'second'
+ relay.acquire('machine', 'share', sink as never, closed).catch(() => {})
+ await vi.advanceTimersByTimeAsync(0)
+ first!([])
+ await vi.advanceTimersByTimeAsync(0)
+ relay.acquire('machine', 'share', sink as never, closed).catch(() => {})
+ await vi.advanceTimersByTimeAsync(0)
+ expect(discover).toHaveBeenCalledTimes(2)
+ second!([{ machineId: 'machine', shares: [share] }])
+ await vi.advanceTimersByTimeAsync(0)
+ // All three open on the second sign-in's list: the first looked its share up again once the sign-in changed.
+ expect(discover).toHaveBeenCalledTimes(2)
+ expect(state.sockets).toHaveLength(3)
+ })
+
+ it('being read for one account is not shared with a window of another', async () => {
+ discover.mockImplementationOnce(() => new Promise(() => {}))
+ relay.acquire('machine', 'share', sink as never, closed).catch(() => {})
+ await vi.advanceTimersByTimeAsync(0)
+ account = 'second';
+ (await ready()).session.detach()
+ expect(discover).toHaveBeenCalledTimes(2)
+ })
+ })
})
diff --git a/cli/src/sharing/relay.ts b/cli/src/sharing/relay.ts
index fadb2c54f..54b918318 100644
--- a/cli/src/sharing/relay.ts
+++ b/cli/src/sharing/relay.ts
@@ -17,18 +17,30 @@ export interface SharedMachineReference {
export class SharingEndedError extends Error {}
+/** How long the account's list of shares answers which windows may open before it is read again. Every window opened
+ * on a shared harness read the whole list first (WebSocket roadmap Phase 1 item 5). A share the list does not hold,
+ * or holds expired, is read again at once, and so is the list after any window failed to open: a new invitation
+ * opens at once, and the backend checks the share on every connect whatever the list said. */
+const SHARES_LIST_MS = 60_000
+/** How many times a window looks its share up again when the sign-in changed, or the list was put in doubt, while it
+ * looked. Past it the window does not open. */
+const SHARE_LOOKUPS_MAX = 3
+
/** One invitation per connection. Never promoted into a full machine link or a shared connection pool. */
export class HarnessShareRelay {
private sessions = new Set<() => void>()
+ private listed: { at: number; account: string; machines: SharedMachineReference[] } | null = null
+ private reading: { account: string; machines: Promise<SharedMachineReference[]> } | null = null
+ /** Bumped whenever the list is put in doubt (a window failed to open or was no longer shared, or a refresh failed):
+ * a read begun before is neither kept nor joined, and a window that looked its share up across it looks again. */
+ private generation = 0
+ /** `account` names the sign-in the list is read for: a list read for another one answers nothing. */
constructor(private readonly auth: Pick<AuthSessionManager, 'accessToken'>, private readonly backendWsBase: string,
- private readonly environment: string, private readonly discover: () => Promise<SharedMachineReference[]>) {}
+ private readonly environment: string, private readonly discover: () => Promise<SharedMachineReference[]>,
+ private readonly account: () => string) {}
async acquire(machineId: string, shareId: string, sink: LocalClientSink,
onClosed: (code: number, reason: string) => void): Promise<RelaySession> {
- const machines = await this.discover()
- const machine = machines.find(m => m.machineId === machineId)
- const share = machine?.shares.find(s => s.id === shareId)
- if (!share) throw new SharingEndedError('Sharing ended or invitation expired')
- const token = await this.auth.accessToken()
+ const { share, token } = await this.lookUp(machineId, shareId)
const url = `${this.backendWsBase.replace(/\/$/, '')}/api/observer-ws?share=${encodeURIComponent(shareId)}&autonomousEnv=${encodeURIComponent(this.environment)}`
+ `&${declaredClientQuery('relay')}`
const ws = new WebSocket(url, [token], { handshakeTimeout: 10_000, maxPayload: 3 * 1024 * 1024 })
@@ -36,6 +48,7 @@ export class HarnessShareRelay {
let cipher: ObserverCipher | null = null, detached = false, settled = false
let heartbeat: ReturnType<typeof watchSocketLiveness> | null = null
const detach = () => { detached = true; heartbeat?.stop(); this.sessions.delete(detach); ws.terminate() }
+ const failed = () => this.doubt()
this.sessions.add(detach)
try {
await new Promise<void>((resolve, reject) => {
@@ -48,6 +61,8 @@ export class HarnessShareRelay {
ws.on('error', () => { if (!settled) { clearTimeout(timeout); reject(new Error('Could not connect to the shared harness.')) } })
ws.on('close', (code, reason) => {
clearTimeout(timeout); heartbeat?.stop(); this.sessions.delete(detach)
+ // Not opened, or no longer shared: whatever the list said of this share is in doubt.
+ if (!settled || code === 4403) failed()
if (!settled) reject(new Error(reason.toString() || 'The owner’s machine is offline.'))
if (!detached) onClosed(code === 4403 ? 4403 : 1012, reason.toString() || 'Owner disconnected')
})
@@ -67,6 +82,7 @@ export class HarnessShareRelay {
cipher = recipientHandshake(ephemeral, machineId, shareId, share.ownerPublicKey, frame.payload)
ready()
} else if (frame.type === 'observer_closed') {
+ failed()
onClosed(frame.payload?.retry === true ? 1012 : 4403, String(frame.payload?.reason || 'Sharing ended'))
if (!settled) { clearTimeout(timeout); reject(new Error('Sharing ended')) }
detach()
@@ -79,7 +95,7 @@ export class HarnessShareRelay {
} else if (!(typeof clear.type === 'string' && DAEMON_LOCAL_ONLY_TYPES.has(clear.type))) sink.sendFrame(clear)
}
} catch {
- clearTimeout(timeout)
+ clearTimeout(timeout); failed()
if (settled) onClosed(1011, 'The shared harness identity could not be verified.')
reject(new Error('The shared harness identity could not be verified.')); detach()
}
@@ -104,4 +120,54 @@ export class HarnessShareRelay {
}
}
close(): void { for (const stop of [...this.sessions]) stop() }
+
+ /** The share and the token to open it with, both for the same sign-in and the same list: if either changed while
+ * this looked, it looks again, so a window never opens on one sign-in's list with another's token. */
+ private async lookUp(machineId: string, shareId: string): Promise<{ share: SharedHarnessReference; token: string }> {
+ for (let lookup = 1; ; lookup++) {
+ const account = this.account(), generation = this.generation
+ const unchanged = () => this.account() === account && this.generation === generation
+ const listed = this.listed && this.listed.account === account && Date.now() - this.listed.at < SHARES_LIST_MS
+ ? this.listed.machines : null
+ const kept = this.find(listed, machineId, shareId)
+ const share = kept && Date.parse(kept.expiresAt) > Date.now() ? kept : this.find(await this.read(), machineId, shareId)
+ if (unchanged()) {
+ if (!share) throw new SharingEndedError('Sharing ended or invitation expired')
+ const token = await this.auth.accessToken()
+ if (unchanged()) return { share, token }
+ }
+ if (lookup === SHARE_LOOKUPS_MAX) throw new Error('Shared harnesses are temporarily unavailable.')
+ }
+ }
+
+ /** The list is in doubt: whatever was kept, or is being read, answers no window from now on. */
+ private doubt(): void {
+ this.generation++
+ this.listed = null
+ this.reading = null
+ }
+
+ /** The share in `machines`, if it holds it. A kept list's share past its expiry is read again; a list just read is
+ * the backend's word, whatever this computer's clock says. */
+ private find(machines: SharedMachineReference[] | null, machineId: string, shareId: string): SharedHarnessReference | undefined {
+ return machines?.find(m => m.machineId === machineId)?.shares.find(s => s.id === shareId)
+ }
+
+ /** The list read now, once for every window of the same sign-in asking at the same time. It is kept only while the
+ * sign-in and the list's generation are still those it was read under. A failed read leaves no list to use. */
+ private read(): Promise<SharedMachineReference[]> {
+ const account = this.account(), generation = this.generation
+ if (this.reading?.account === account) return this.reading.machines
+ const current = () => this.account() === account && this.generation === generation
+ const machines = this.discover().then((list) => {
+ if (current()) this.listed = { at: Date.now(), account, machines: list }
+ return list
+ }, (error: unknown) => {
+ // The list it was replacing is in doubt too, for windows already looking at it.
+ if (current()) this.doubt()
+ throw error
+ }).finally(() => { if (this.reading?.machines === machines) this.reading = null })
+ this.reading = { account, machines }
+ return machines
+ }
}
diff --git a/cli/src/superTabs/command.spec.ts b/cli/src/superTabs/command.spec.ts
index 638874a04..95917acef 100644
--- a/cli/src/superTabs/command.spec.ts
+++ b/cli/src/superTabs/command.spec.ts
@@ -311,3 +311,11 @@ it('parses a Buddy\'s propose OPERATION_ID JSON as its proposal command, whateve
.toMatchObject({ action: 'command', operationId: 'op-1', command: { ...proposal, type: 'buddy.propose' } })
expect(() => parseSuperTabArgs([...prefix, 'propose', 'op-1'], where)).toThrow('harness super-tab')
})
+
+// Cost records (Dee, 2026-10-29): what routed attempts cost and how they went, over the last days.
+it('reads the cost summary of the last 7 days, or of --days N up to 90', () => {
+ expect(parseSuperTabArgs([...prefix, 'costs'], where).payload).toMatchObject({ action: 'costs', days: 7 })
+ expect(parseSuperTabArgs([...prefix, 'costs', '--days', '30'], where).payload).toMatchObject({ action: 'costs', days: 30 })
+ for (const argv of [[...prefix, 'costs', '--days'], [...prefix, 'costs', '--days', '0'], [...prefix, 'costs', '--days', '91'],
+ [...prefix, 'costs', '--days', '7x'], [...prefix, 'costs', 'extra']]) expect(() => parseSuperTabArgs(argv, where), argv.join(' ')).toThrow('harness super-tab')
+})
diff --git a/cli/src/superTabs/command.ts b/cli/src/superTabs/command.ts
index 07f2e5a4c..dd25d2cb8 100644
--- a/cli/src/superTabs/command.ts
+++ b/cli/src/superTabs/command.ts
@@ -10,7 +10,7 @@ import { uploadAttachments } from './attach.js'
import { keyName } from './terminal.js'
import { randomUUID } from 'node:crypto'
-const USAGE = 'harness super-tab --tab ID [--agent ID] [--port N --machine ID] status | messages GROUP | message GROUP MESSAGE_ID | decisions [--answered] | post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... [--mention PERSON]... | command OPERATION_ID JSON | propose OPERATION_ID JSON | start OPERATION_ID JSON | resume START_ID | capacity MACHINE_ID JSON | route GROUP JSON | plan [JSON] | remove-machine MACHINE_ID [--yes] | set-agents MACHINE_ID COUNT | screen AGENT [--scrollback N] | type AGENT [TEXT] [--key K]... | help'
+const USAGE = 'harness super-tab --tab ID [--agent ID] [--port N --machine ID] status | messages GROUP | message GROUP MESSAGE_ID | decisions [--answered] | costs [--days N] | post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... [--mention PERSON]... | command OPERATION_ID JSON | propose OPERATION_ID JSON | start OPERATION_ID JSON | resume START_ID | capacity MACHINE_ID JSON | route GROUP JSON | plan [JSON] | remove-machine MACHINE_ID [--yes] | set-agents MACHINE_ID COUNT | screen AGENT [--scrollback N] | type AGENT [TEXT] [--key K]... | help'
export function parseSuperTabArgs(argv: readonly string[], where: Where) {
const positional: string[] = []
let tabId = '', agentId = ''
@@ -29,6 +29,9 @@ export function parseSuperTabArgs(argv: readonly string[], where: Where) {
const payload: Record<string, unknown> = { action, tabId, agentId }
if (action === 'messages' && identifier(first) && positional.length === 2) payload.conversationId = first
else if (action === 'decisions' && (positional.length === 1 || (positional.length === 2 && first === '--answered'))) payload.state = first ? 'answered' : 'open'
+ else if (action === 'costs' && (positional.length === 1 || (positional.length === 3 && first === '--days' && /^[1-9][0-9]?$/.test(second ?? '') && Number(second) <= 90))) {
+ payload.days = positional.length === 3 ? Number(second) : 7
+ }
else if (action === 'message' && identifier(first) && identifier(second) && positional.length === 3) {
Object.assign(payload, { conversationId: first, messageId: second })
}
diff --git a/cli/src/superTabs/machines.spec.ts b/cli/src/superTabs/machines.spec.ts
index cdc94aa9d..f7143e5d8 100644
--- a/cli/src/superTabs/machines.spec.ts
+++ b/cli/src/superTabs/machines.spec.ts
@@ -662,6 +662,47 @@ describe('contributed machine executor', () => {
expect(posts().map(fields).slice(-2)).toEqual([['harnessUncommitted', 'harnessProgress'], ['harnessProgress']])
})
+ it('sends each running harness’s token counts by model, and nothing for one with none or not running', async () => {
+ const f = fixture()
+ const session = (id: string) => ({ agentId: id, sessionId: `session-${id}`, engine: 'claude', transcriptPath: `/transcripts/${id}.jsonl`, registeredAt: 1 })
+ vi.mocked(f.core.agents.byAgent).mockImplementation(id => ['running', 'quiet'].includes(id) ? session(id) as never : undefined)
+ f.pool.harnessIds = ['running', 'quiet', 'stopped']
+ const opus = { input: 10, output: 5, cacheRead: 100, cacheWrite: 20 }
+ f.core.usage = vi.fn(async target => target.agentId === 'running'
+ ? { totalTokens: 135, updatedAt: '2026-10-29T00:00:00Z', inputTokens: 130, outputTokens: 5, models: { 'claude-opus-5-5': opus },
+ work: { current: [{ cwd: '/private/work', at: '2026-10-29T00:00:00Z' }], locations: [], pullRequests: [], uncertain: false, truncated: false } }
+ : { totalTokens: null, updatedAt: '2026-10-29T00:00:00Z' })
+ await f.machine.tick()
+ const body = f.backend.mock.calls.find(c => c[1] === 'POST')![3] as Record<string, unknown>
+ // Counts only: never the session's folders, pull requests or any other part of its usage reading.
+ expect(body.harnessTokens).toEqual({ running: { 'claude-opus-5-5': opus } })
+ expect(f.core.usage).toHaveBeenCalledTimes(2)
+ f.core.usage = vi.fn(async () => null)
+ f.advance(); await f.machine.tick()
+ expect(f.backend.mock.calls.filter(c => c[1] === 'POST').at(-1)![3]).not.toHaveProperty('harnessTokens')
+ })
+
+ it('drops token counts for a backend that refuses them, keeping every other field, and offers them again ten minutes later', async () => {
+ const f = fixture()
+ vi.mocked(f.core.agents.byAgent).mockImplementation(id => id === 'running'
+ ? { agentId: id, sessionId: 's', engine: 'claude', transcriptPath: '/t.jsonl', registeredAt: 1 } as never : undefined)
+ f.core.usage = vi.fn(async () => ({ totalTokens: 3, updatedAt: '2026-10-29T00:00:00Z', models: { m: { input: 1, output: 1, cacheRead: 1, cacheWrite: 0 } } }))
+ const original = f.backend.getMockImplementation()!
+ f.backend.mockImplementation(async (core, method, path, body) => {
+ if (method === 'POST' && (body as Record<string, unknown>)?.harnessTokens) throw new SuperTabHostError('VALIDATION_ERROR', 'Unrecognized key: harnessTokens', 400)
+ return original(core, method, path, body)
+ })
+ const machine = new ContributedMachines(f.core, 'host', { ...f.deps, progress: () => ({ running: 900 }) } as never)
+ const posts = () => f.backend.mock.calls.filter(c => c[1] === 'POST' && String(c[2]).includes('/machines/'))
+ const fields = (post: unknown) => ['harnessTokens', 'harnessProgress'].filter(key => key in (post as object))
+ await machine.tick()
+ expect(posts().map(c => fields(c[3]))).toEqual([['harnessTokens', 'harnessProgress'], ['harnessProgress']])
+ f.advance(); await machine.tick()
+ expect(posts().map(c => fields(c[3])).at(-1)).toEqual(['harnessProgress'])
+ f.step(600_000); await machine.tick()
+ expect(posts().map(c => fields(c[3])).slice(-2)).toEqual([['harnessTokens', 'harnessProgress'], ['harnessProgress']])
+ })
+
it('drops progress for a backend that refuses it, and offers it again ten minutes later', async () => {
const f = fixture()
const original = f.backend.getMockImplementation()!
diff --git a/cli/src/superTabs/machines.ts b/cli/src/superTabs/machines.ts
index b418e5662..cfae2922c 100644
--- a/cli/src/superTabs/machines.ts
+++ b/cli/src/superTabs/machines.ts
@@ -21,6 +21,7 @@ import { teamPrivacyObserver } from '../team/observer.js'
import { teamRelayed } from '../team/relay.js'
import type { PrivacyObservation } from '../team/privacy.js'
import { repositoryKey } from './route.js'
+import { usageTarget, validModelTokens, validUsageTarget, type ModelTokens } from '../lib/agentUsageWire.js'
const finite = (v: unknown) => typeof v === 'number' && Number.isFinite(v) ? v : null
const list = (v: unknown) => Array.isArray(v) ? v.map(object) : []
@@ -188,6 +189,7 @@ export class ContributedMachines {
private privacyRefusedUntil = 0
/** Until when the reading leaves out its progress, which the backend refused. */
private progressRefusedUntil = 0
+ private tokensRefusedUntil = 0
private uncommittedRefusedUntil = 0
/** Per running session, whether its folder had uncommitted changes when last read, and until when that stands. */
private readonly uncommittedCache = new Map<string, { cwd: string; dirty: boolean; until: number; readAt: number; shown?: number }>()
@@ -423,7 +425,9 @@ export class ContributedMachines {
const shown = began >= this.progressRefusedUntil ? this.deps.progress?.(running) ?? {} : {}
const progress = Object.fromEntries(running.flatMap(id => typeof shown[id] === 'number' ? [[id, shown[id]]] : []))
const uncommitted = began >= this.uncommittedRefusedUntil ? this.uncommitted(running, began, shown) : {}
- const observation = { generation: pool.generation, tools: reportedTools, ...(preparing.length ? { preparingStartIds: preparing } : {}),
+ const tokens = began >= this.tokensRefusedUntil ? await this.tokensOf(running) : {}
+ const observation = { generation: pool.generation, tools: reportedTools, ...(Object.keys(tokens).length ? { harnessTokens: tokens } : {}),
+ ...(preparing.length ? { preparingStartIds: preparing } : {}),
...(Object.keys(uncommitted).length ? { harnessUncommitted: uncommitted } : {}),
...(Object.keys(progress).length ? { harnessProgress: progress } : {}), ...(localModels ? { localModels } : {}),
...((readyEngines || checkouts) && began >= this.readinessRefusedUntil ? { readiness } : {}),
@@ -451,7 +455,8 @@ export class ContributedMachines {
// readiness, progress, then privacy): a backend that takes everything else keeps the local models it reads. Their
// boolean-only view still safely refuses an unverified tool, and a reading without privacy is never one a Team
// machine passes on.
- const { preparingStartIds: _preparing, ...unprepared } = observation
+ const { harnessTokens: _tokens, ...untokened } = observation
+ const { preparingStartIds: _preparing, ...unprepared } = untokened
const { harnessUncommitted: _uncommitted, ...known } = unprepared
const { readiness: _readiness, ...ready } = known
const { harnessProgress: _progress, ...withoutProgress } = ready
@@ -460,7 +465,8 @@ export class ContributedMachines {
// A backend before `starting` refuses it: it gets the models the grid lists, as before, not none at all.
const listedOnly = localModels?.some(m => m.starting)
? [{ ...withoutPrivacy, localModels: localModels.filter(m => !m.starting) }] : []
- const attempts = [...('preparingStartIds' in observation ? [observation] : []), ...('harnessUncommitted' in unprepared ? [unprepared] : []),
+ const attempts = [...('harnessTokens' in observation ? [observation] : []), ...('preparingStartIds' in untokened ? [untokened] : []),
+ ...('harnessUncommitted' in unprepared ? [unprepared] : []),
...('readiness' in known ? [known] : []), ready, ...('harnessProgress' in ready ? [withoutProgress] : []),
...('privacy' in withoutProgress ? [withoutPrivacy] : []), ...listedOnly,
...('toolProbeErrors' in observation || 'localModels' in observation || 'refusedModels' in observation ? [legacy] : [])]
@@ -472,7 +478,8 @@ export class ContributedMachines {
break
} catch (error) {
if (!refused(error) || index === attempts.length - 1) throw error
- if ('preparingStartIds' in attempt) this.preparingRefusedUntil = began + FIELD_REFUSED_MS
+ if ('harnessTokens' in attempt) this.tokensRefusedUntil = began + FIELD_REFUSED_MS
+ else if ('preparingStartIds' in attempt) this.preparingRefusedUntil = began + FIELD_REFUSED_MS
else if ('harnessUncommitted' in attempt) this.uncommittedRefusedUntil = began + FIELD_REFUSED_MS
else if ('readiness' in attempt) this.readinessRefusedUntil = began + FIELD_REFUSED_MS
else if ('harnessProgress' in attempt) this.progressRefusedUntil = began + FIELD_REFUSED_MS
@@ -564,6 +571,20 @@ export class ContributedMachines {
}
} finally { local?.close() }
}
+ /** Each running session's token counts by model, from the daemon's last usage reading (never a transcript read): the
+ * Swarm prices each attempt by them (backend superTabs/costs). Counts only; the reading's folders and pull requests stay
+ * here. A session with none read yet is left out. */
+ private async tokensOf(running: readonly string[]): Promise<Record<string, Record<string, ModelTokens>>> {
+ const counted: Record<string, Record<string, ModelTokens>> = {}
+ for (const id of running) {
+ const session = this.core.agents.byAgent(id)
+ const target = session && usageTarget(session)
+ if (!target || !validUsageTarget(target)) continue
+ const models = (await this.core.usage?.(target).catch(() => null))?.models
+ if (models && Object.keys(models).length && validModelTokens(models)) counted[id] = models
+ }
+ return counted
+ }
/** Whether each running session's folder has uncommitted changes (git status), as last read, for the sessions git could
* read: the backend stops a worker idle for 15 minutes only when its host says it is clean (backend superTabs/tidy.ts).
* The folders due are read beside the pass, never holding the reading up; what they say goes with a later one. A folder
diff --git a/cli/src/superTabs/route.spec.ts b/cli/src/superTabs/route.spec.ts
index 586fe37cc..5afe3e8be 100644
--- a/cli/src/superTabs/route.spec.ts
+++ b/cli/src/superTabs/route.spec.ts
@@ -246,10 +246,12 @@ describe('verdict and record', () => {
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, 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')
+ expect(recordOf(c, v, a(), policy, 'v1')).toEqual(v1)
+ // The task's kind is recorded, so attempts can be compared by the kind of job they were (backend costs/read.ts).
+ expect(recordOf(c, v, a({ kind: 'ui' }), policy).assessment).toEqual({ difficulty: 'medium', risk: 'low', why: 'API change.', size: 'medium', kind: 'ui' })
+ // A backend from before kinds gets everything else; one from before phase 1 gets neither.
+ expect(recordOf(c, v, a({ kind: 'ui' }), policy, 'unkinded').assessment).toEqual({ difficulty: 'medium', risk: 'low', why: 'API change.', size: 'medium' })
+ expect(object(recordOf(c, v, a({ kind: 'ui' }), policy, 'v1').assessment)).not.toHaveProperty('kind')
})
})
diff --git a/cli/src/superTabs/route.ts b/cli/src/superTabs/route.ts
index cb0115b16..faa3c0b05 100644
--- a/cli/src/superTabs/route.ts
+++ b/cli/src/superTabs/route.ts
@@ -421,10 +421,14 @@ export function decide(choice: Choice): Verdict {
: { 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, v1 = false): Record<string, unknown> {
+/** The record in the shape a backend takes: `current` with the job's kind (what attempts are compared by, backend costs/read.ts),
+ * `unkinded` for a backend from before kinds, and `v1` without size and fit too, for one from before phase 1. Each refuses the
+ * newer fields with its strict schema. */
+export type RecordShape = 'current' | 'unkinded' | 'v1'
+export function recordOf(choice: Choice, verdict: Verdict, a: Assessment, policy: Policy, shape: RecordShape = 'current'): Record<string, unknown> {
+ const v1 = shape === 'v1'
return {
- assessment: { difficulty: a.difficulty, risk: a.risk, why: a.why, ...(v1 ? {} : { size: a.size }) },
+ assessment: { difficulty: a.difficulty, risk: a.risk, why: a.why, ...(v1 ? {} : { size: a.size }), ...(shape === 'current' && a.kind ? { kind: a.kind } : {}) },
candidates: choice.shown.map(s => ({ id: s.id, kind: s.kind, ...(s.agentId ? { agentId: s.agentId } : {}), machineId: s.machineId,
engine: s.engine, model: s.model, effort: s.effort, quality: s.quality, cost: s.cost, title: s.title, label: s.label, ...(v1 ? {} : { fit: s.fit }),
...(s.gridModel && s.gridName ? { gridModel: s.gridModel, gridName: s.gridName } : {}) })),
diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.ts
index 6ba7b0192..980c6578b 100644
--- a/cli/src/superTabs/routeCommand.spec.ts
+++ b/cli/src/superTabs/routeCommand.spec.ts
@@ -472,6 +472,31 @@ describe('routeTask', () => {
expect(v1.command.decision.assessment).not.toHaveProperty('size')
expect(v1.command.decision.candidates.some((c: object) => 'fit' in c)).toBe(false)
})
+ it('records the job kind, leaving only it out for a backend from before kinds, and phase 1 fields only after a second refusal', async () => {
+ const kinded = { ...input, assessment: { ...input.assessment, kind: 'docs' } }
+ const commands = (s: ReturnType<typeof scoped>) => s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0].command.decision.assessment)
+ const current = scoped()
+ await routeTask(kinded, current, where as never, opener(), () => 'op')
+ expect(commands(current)).toEqual([{ difficulty: 'medium', risk: 'low', why: 'Endpoint.', size: 'medium', kind: 'docs' }])
+ const refusing = (keys: string[]) => {
+ const s = scoped(), base = s.getMockImplementation()!
+ s.mockImplementation(async payload => {
+ const sent = payload.action === 'command' ? JSON.stringify(payload.command) : ''
+ return keys.some(key => sent.includes(`"${key}"`)) ? { error: 'VALIDATION_ERROR', detail: `Unrecognized key: "${keys[0]}"`, status: 400 } : base(payload)
+ })
+ return s
+ }
+ const beforeKinds = refusing(['kind":"docs'])
+ expect(await routeTask(kinded, beforeKinds, where as never, opener(), () => 'op')).toMatchObject({ ok: true, routeDecisionId: 'd1' })
+ expect(commands(beforeKinds).map(a => Object.keys(a))).toEqual([['difficulty', 'risk', 'why', 'size', 'kind'], ['difficulty', 'risk', 'why', 'size']])
+ const beforePhase1 = refusing(['kind":"docs', 'size'])
+ expect(await routeTask(kinded, beforePhase1, where as never, opener(), () => 'op')).toMatchObject({ ok: true, routeDecisionId: 'd1' })
+ expect(commands(beforePhase1).map(a => Object.keys(a))).toEqual([['difficulty', 'risk', 'why', 'size', 'kind'], ['difficulty', 'risk', 'why', 'size'], ['difficulty', 'risk', 'why']])
+ // A task with no kind never needs the extra try.
+ const plain = refusing(['size'])
+ await routeTask(input, plain, where as never, opener(), () => 'op')
+ expect(commands(plain)).toHaveLength(2)
+ })
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 })
diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.ts
index d68db2b17..d737bc719 100644
--- a/cli/src/superTabs/routeCommand.ts
+++ b/cli/src/superTabs/routeCommand.ts
@@ -7,7 +7,7 @@ import { openDaemon, type Daemon, type Where } from '../agentClient/daemon.js'
import { requiredToolReason, startRequirements } from './capacity.js'
import { inspectCapacity, type ScopedRequest } from './start.js'
import { ENDED_WORK, object, within } from './wire.js'
-import { accountOf, API_BUILDERS, choose, decide, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, repositoryKey, type Assessment, type Commitment, type HeldModel, type MemberFrame, type Policy, type Probe, type SwarmRule, type TaskFolder } from './route.js'
+import { accountOf, API_BUILDERS, choose, decide, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, repositoryKey, type Assessment, type RecordShape, type Commitment, type HeldModel, 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'
@@ -299,11 +299,13 @@ export async function routeTask(input: { tabId: string; conversationId: string;
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,
- 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)
+ const record = (shape: RecordShape) => scoped({ action: 'command', operationId,
+ command: { type: 'route.record', conversationId: input.conversationId, decision: recordOf(choice, verdict, assessment, policy, shape) } })
+ let recorded = await record('current')
+ // A backend from before kinds, or before phase 1, refuses the new fields as invalid; the decision is still worth keeping in
+ // the shape it knows. A task with no kind has nothing to leave out at the first step.
+ if (recorded.error === 'VALIDATION_ERROR' && assessment.kind) recorded = await record('unkinded')
+ if (recorded.error === 'VALIDATION_ERROR') recorded = await record('v1')
if (typeof recorded.error === 'string' && !TRANSPORT.has(recorded.error)) return recorded
const routeDecisionId = recorded.ok === true ? object(object(recorded.value).result).routeDecisionId : undefined
const decision = typeof routeDecisionId === 'string' ? `,"routeDecisionId":"${routeDecisionId}"` : ''
diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.ts
index 427352fdb..c32e403aa 100644
--- a/cli/src/superTabs/service.spec.ts
+++ b/cli/src/superTabs/service.spec.ts
@@ -1026,3 +1026,34 @@ describe('mentions on a post', () => {
expect(String((await help(t, { tabId: 'tab', agentId: t.agentId })).post)).not.toContain('--mention')
})
})
+
+// Review of #2106: an attempt ends with every token its session used, read as it finishes, not the last machine report's.
+describe('finishing your own work', () => {
+ const opus = { 'claude-opus-5-5': { input: 7000, output: 1200, cacheRead: 0, cacheWrite: 0 } }
+ const status = (status: string) => ({ type: 'work.status', conversationId: 'g1', assignmentId: 'a1', status, result: 'Shipped.' })
+ const posts = (t: ReturnType<typeof setup>) => t.call.mock.calls.filter(c => c[0] === 'POST' && c[1] === '/api/super-tabs/tab/commands').map(c => (c[2] as { command: Record<string, unknown> }).command)
+
+ it('sends Done and Stopped with your session’s totals read now, and nothing with any other status or without a reading', async () => {
+ const t = setup()
+ const fresh = vi.fn(async (_agentId: string) => ({ totalTokens: 8200, updatedAt: '2026-10-29T00:00:00Z', models: opus }))
+ t.core.usageFresh = fresh
+ for (const s of ['done', 'stopped', 'review']) await t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: `op-${s}`, command: status(s) }, owner)
+ expect(posts(t)).toEqual([{ ...status('done'), tokens: opus }, { ...status('stopped'), tokens: opus }, status('review')])
+ expect(fresh).toHaveBeenCalledWith('native')
+ fresh.mockResolvedValueOnce({ totalTokens: null, updatedAt: '2026-10-29T00:00:00Z' } as never)
+ await t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'op-none', command: status('done') }, owner)
+ fresh.mockRejectedValueOnce(new Error('unreadable'))
+ await t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'op-fail', command: status('done') }, owner)
+ expect(posts(t).slice(-2)).toEqual([status('done'), status('done')])
+ })
+
+ it('sends Done again without the totals to a backend from before them', async () => {
+ const t = setup()
+ t.core.usageFresh = async () => ({ totalTokens: 8200, updatedAt: '2026-10-29T00:00:00Z', models: opus })
+ const answer = t.call.getMockImplementation()!
+ t.call.mockImplementation(async (method, path, body) => (body as { command?: { tokens?: unknown } })?.command?.tokens
+ ? { status: 400, body: { success: false, error: { code: 'VALIDATION_ERROR', message: 'command: Unrecognized key: "tokens"' } } } : answer(method, path, body))
+ expect(await t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'op', command: status('done') }, owner)).toMatchObject({ ok: true })
+ expect(posts(t)).toEqual([{ ...status('done'), tokens: opus }, status('done')])
+ })
+})
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index dd88d6f7b..dc7962038 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs'
import { readAuthSession } from '../lib/authSession.js'
import { createHash } from 'node:crypto'
import type { CoreApi, ServiceRequests, SuperTabsPort } from '../core/api.js'
+import { validModelTokens } from '../lib/agentUsageWire.js'
import { backend, swarmRoleFor, hostJournalFile, identifier, object, SuperTabHost, SuperTabHostError, type SuperTabHostOptions, type SwarmSources } from './host.js'
import { HostFeed } from './hostFeed.js'
import { SwarmReads, type SwarmRead } from './swarmReads.js'
@@ -34,6 +35,15 @@ import { createOwnerSubscriptions } from '../lib/ownerSubscriptions.js'
import { startSubscriptionRelay } from '../lib/subscriptionRelay.js'
const POST_HELP = '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.'
+/** Done or Stopped from an agent finishing its own work carries its session's token totals by model, read from its transcript
+ * now (core `usageFresh`): its attempt ends with every token it used, not a machine report up to a beat old (backend
+ * superTabs/costs/attempts.ts endRun; review of #2106). Counts only. No reading, and the status goes without them. */
+async function finishingWith(core: CoreApi, command: Record<string, unknown>, harnessId: string): Promise<Record<string, unknown>> {
+ if (command.type !== 'work.status' || (command.status !== 'done' && command.status !== 'stopped')) return command
+ const models = (await core.usageFresh?.(harnessId).catch(() => null))?.models
+ return models && Object.keys(models).length && validModelTokens(models) ? { ...command, tokens: models } : command
+}
+
const HELP = {
status: 'Read the shared tab roster and work. Its rules are the project owners\' routing rules, each in the owner\'s own words; each binds only the agents of its projectId. A Lead\'s status also lists otherProjectsWork: the active work of the Swarm\'s other projects (group, project, title, owned code, status, Engineer, PR), read only. A project on Custom skills lists its roles (id, name, kind) in status.',
leads: 'The Leads conversation (leadsConversationId in a Lead\'s status) is one conversation for the whole Swarm, outside every project. Only Leads and people post there, and only Leads among agents receive it. Before assigning, look at otherProjectsWork; if your task touches the same code, say so there and agree an order first, then tell your own project. The Swarm posts there by itself when two projects\' active tasks own the same code.',
@@ -42,6 +52,7 @@ const HELP = {
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.',
decisions: 'decisions [--answered]: the decisions you asked of people, still open, or with --answered those answered (each with its choice and note). A Lead also sees those asked in its project. When your work needs a person to decide, ask through work.status needs_human with ask: the question as its result, 2 to 5 options, the one you recommend and what the answer unblocks. Keep working on your recommendation, marked provisional, until a notice in that conversation says it was answered; then read the answer here with --answered. The notice carries none of the answer. A decision is not a private channel: anything private goes through Chat with PM.',
+ costs: 'costs [--days N]: what the attempts routed in the last N days (7 unless set, at most 90) cost and how they went, per engine, model, effort and kind of job: attempts, first-review pass rate, shipped, median minutes to ship, tokens, API-equivalent cost and actual per-token spend in US dollars, and cost per shipped change, with the prices and their sources. Only attempts routed since cost records began, in the groups you may read.',
post: `post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]...: ${POST_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.',
@@ -477,6 +488,10 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
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: { ...(decisions ? { decisions } : { decisionsUnreadable: true }), ...(attempts ? { attempts } : { attemptsUnreadable: true }) } }
}
+ // What routed attempts cost and how they went over a period (backend superTabs/costs/read.ts).
+ if (payload.action === 'costs' && Number.isInteger(payload.days) && Number(payload.days) >= 1 && Number(payload.days) <= 90) {
+ return { ok: true, value: await backend(core, 'GET', `${path}/costs?days=${payload.days}&${identity}`) }
+ }
if (payload.action === 'decisions' && (payload.state === 'open' || payload.state === 'answered')) {
return { ok: true, value: await backend(core, 'GET', `${path}/decisions?state=${payload.state}&${identity}`) }
}
@@ -497,11 +512,16 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
} catch { return { ok: true, value: page } }
}
if (payload.action === 'command' && identifier(payload.operationId) && payload.command && typeof payload.command === 'object' && !Array.isArray(payload.command)) {
- const command = await mentionCommand(taskCommand(object(payload.command)), async () => (await swarm()).state)
+ const command = await finishingWith(core, await mentionCommand(taskCommand(object(payload.command)), async () => (await swarm()).state), String(agent.harnessId))
const send = (command: Record<string, unknown>) => backend(core, 'POST', `${path}/commands`,
{ operationId: payload.operationId, command, asAgentId: agentId })
let value: unknown
try { value = await send(command) } catch (error) {
+ // A backend from before cost records refuses the totals; the status itself still goes.
+ if (command.tokens && error instanceof SuperTabHostError && error.status === 400 && error.code === 'VALIDATION_ERROR' && /"tokens"|'tokens'/.test(error.message)) {
+ const { tokens: _tokens, ...status } = command
+ return { ok: true, operationId: payload.operationId, value: await send(status) }
+ }
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.' }
}
diff --git a/cli/src/superTabs/serviceReads.spec.ts b/cli/src/superTabs/serviceReads.spec.ts
index 1c493d767..9478c49ee 100644
--- a/cli/src/superTabs/serviceReads.spec.ts
+++ b/cli/src/superTabs/serviceReads.spec.ts
@@ -171,3 +171,13 @@ describe('decisions', () => {
}
})
})
+
+describe('costs', () => {
+ it('reads the cost summary of the period as that agent, and lists it in help', async () => {
+ const summary = { days: 30, rows: [], totals: { attempts: 0 }, prices: [] }
+ const s = swarm((_method, path) => path.startsWith(`/api/super-tabs/${T}/costs?`) ? ok(summary) : undefined)
+ expect(await s.ask({ action: 'costs', tabId: T, agentId: FIXTURE.leadId, days: 30 }, owner)).toEqual({ ok: true, value: summary })
+ expect(s.call).toHaveBeenCalledWith('GET', `/api/super-tabs/${T}/costs?days=30&asAgentId=${FIXTURE.leadId}`, undefined)
+ expect(((await s.ask({ action: 'help', tabId: T, agentId: FIXTURE.leadId }, owner)) as { help: { costs?: string } }).help.costs).toMatch(/^costs \[--days N\]/)
+ })
+})
diff --git a/cli/src/superTabs/start.spec.ts b/cli/src/superTabs/start.spec.ts
index ba45239d8..90e69e7c2 100644
--- a/cli/src/superTabs/start.spec.ts
+++ b/cli/src/superTabs/start.spec.ts
@@ -256,8 +256,8 @@ it.each(['claude', 'codex'])('starts a %s Buddy with the built-in swarm-buddy sk
expect(payload.prompt).not.toContain('swarm-dev')
})
-it('starts a Claude Buddy in asking mode, never with full permissions, and no Buddy with the GitHub App\'s token', async () => {
- for (const [engine, mode, bypass] of [['claude', 'ask', false], ['codex', 'full', true]] as const) {
+it('starts no Buddy with full permissions or the GitHub App\'s token: Claude asking, Codex in its read-only sandbox asking', async () => {
+ for (const [engine, mode, bypass] of [['claude', 'ask', false], ['codex', 'readOnlyAsk', false]] as const) {
const f = fixture()
f.start.request = { ...f.start.request, engine, buddyOf: { personId: 'peer', generation: 'g' } } as typeof f.start.request
await startAgent({ action: 'start', tabId: 'tab', operationId: `buddy-${engine}`, request: f.start.request, hostDispatch: true, github: { requester: 'peer' } } as never,
diff --git a/cli/src/superTabs/start.ts b/cli/src/superTabs/start.ts
index 9322aaf1b..73dd10fd3 100644
--- a/cli/src/superTabs/start.ts
+++ b/cli/src/superTabs/start.ts
@@ -340,11 +340,13 @@ async function startOnce(input: Json, scoped: ScopedRequest, where: Where, open:
const facts = skilled && !hosted ? await projectFacts(scoped, request.conversationId, start.machineOwnerId) : null
const mode = !skilled ? null : isSwarmSkillMode(start.skillMode) ? start.skillMode : facts?.mode ?? 'orchestration'
// A Buddy never writes code (Lead's ruling, privacy review of #1992): never the GitHub App's token, and a Claude Buddy
- // asks before anything but its Super Tab commands, which its folder's settings pre-approve (lib/swarmSkills.ts).
+ // asks before anything but its Super Tab commands, which its folder's settings pre-approve (lib/swarmSkills.ts). A
+ // Codex Buddy reads in its read-only sandbox and asks before anything outside it: with full permissions it could push
+ // and open pull requests with its person's own GitHub login (Lead, 10-29).
const github = buddy ? null : hosted ? (typeof hosted.requester === 'string' && hosted.requester ? { requester: hosted.requester } : null) : facts?.github ?? null
- const asks = buddy && request.engine === 'claude'
+ const asks = !buddy ? null : request.engine === 'claude' ? 'ask' : request.engine === 'codex' ? 'readOnlyAsk' : null
const payload: Json = { engine: request.engine, name: request.name, creationId, startedBy: 'agent', bypassPermission: !asks,
- ...(asks ? { permissionMode: 'ask' } : permissionModeFlags(request.engine as AgentEngine, 'full') ? { permissionMode: 'full' } : {}),
+ ...(asks ? { permissionMode: asks } : permissionModeFlags(request.engine as AgentEngine, 'full') ? { permissionMode: 'full' } : {}),
...(mode ? { swarmRole: role, swarmSkillMode: mode } : {}),
...(github ? { swarmGitHub: true } : {}),
prompt: buddy ? buddyPrompt(String(input.tabId), String(request.conversationId), mode) : `You are joining a shared Super Tab${reviewer ? ' as a Reviewer' : ''}. ${mode ? `${swarmSkillUse(role, mode)} ` : ''}Run harness super-tab --tab ${input.tabId} status until this harness appears in the roster. ${reviewer
diff --git a/desktop/lib/core/permission_modes.dart b/desktop/lib/core/permission_modes.dart
index c9bc3bcd2..9601af7e8 100644
--- a/desktop/lib/core/permission_modes.dart
+++ b/desktop/lib/core/permission_modes.dart
@@ -81,6 +81,18 @@ const Map<String, List<PermissionMode>> kEnginePermissionModes = {
],
};
+/// Modes Harness launches on its own and New Harness never offers: a
+/// Buddy's (CLI superTabs/start.ts), named here so its details read by name.
+const Map<String, List<PermissionMode>> kLaunchOnlyPermissionModes = {
+ 'codex': [
+ PermissionMode(
+ 'readOnlyAsk',
+ 'Read only, asks you',
+ 'Reads in its sandbox, asks you before anything outside it',
+ ),
+ ],
+};
+
/// The modes [engine] offers, or empty when it has none to choose between.
List<PermissionMode> permissionModesOf(String engine) =>
kEnginePermissionModes[engine] ?? const [];
diff --git a/desktop/lib/super_tabs/agent_details.dart b/desktop/lib/super_tabs/agent_details.dart
index be4933814..c0c715689 100644
--- a/desktop/lib/super_tabs/agent_details.dart
+++ b/desktop/lib/super_tabs/agent_details.dart
@@ -116,10 +116,10 @@ class SuperTabAgentInfo {
String? get permission {
final mode = _known(native?.permissionMode);
if (mode == null) return null;
- return permissionModesOf(agent.engine)
- .where((choice) => choice.id == mode)
- .firstOrNull
- ?.label ??
+ return [
+ ...permissionModesOf(agent.engine),
+ ...?kLaunchOnlyPermissionModes[agent.engine],
+ ].where((choice) => choice.id == mode).firstOrNull?.label ??
'Unrecognized setting';
}
diff --git a/desktop/lib/super_tabs/buddies.dart b/desktop/lib/super_tabs/buddies.dart
index 408d9be9e..31311bcee 100644
--- a/desktop/lib/super_tabs/buddies.dart
+++ b/desktop/lib/super_tabs/buddies.dart
@@ -14,6 +14,23 @@ import 'model.dart';
/// The engines a Buddy runs on (spec: Buddies, 10-28).
const kBuddyEngines = {'claude': 'Claude', 'codex': 'Codex'};
+/// Engines a Buddy cannot run on yet, and why, in the backend's own words
+/// (`CODEX_BUDDY_REFUSAL`, backend superTabs/commands.ts): the dialog offers
+/// them turned off, with this beside them (security review 1 of #2087).
+const kBuddyEngineRefusals = {
+ 'codex': 'A Codex Buddy is not available yet: Codex would run some commands outside its sandbox without asking. Choose Claude Code.',
+};
+
+/// The engine Start again asks for: the Buddy's own, or Claude Code in place
+/// of one the server refuses, which it would refuse again (review 2 of #2087).
+String buddyRestartEngine(String engine) =>
+ kBuddyEngineRefusals.containsKey(engine) ? 'claude' : engine;
+
+/// Start again's label: "Start with Claude Code" where it changes the engine.
+String buddyRestartLabel(String engine) => buddyRestartEngine(engine) == engine
+ ? 'Start again'
+ : 'Start with Claude Code';
+
/// An engine as people read it: "Claude", "Codex".
String buddyEngineName(String engine) =>
kBuddyEngines[engine] ??
@@ -247,7 +264,9 @@ class _AddBuddyDialogState extends State<_AddBuddyDialog> {
Flexible(
child: RadioListTile<String>(
value: key,
- enabled: !_busy,
+ enabled:
+ !_busy &&
+ !kBuddyEngineRefusals.containsKey(key),
dense: true,
contentPadding: EdgeInsets.zero,
title: Text(value),
@@ -259,6 +278,16 @@ class _AddBuddyDialogState extends State<_AddBuddyDialog> {
),
],
),
+ for (final refusal in kBuddyEngineRefusals.values) ...[
+ const SizedBox(height: 4),
+ Padding(
+ padding: const EdgeInsets.only(left: _labelWidth),
+ child: Text(
+ refusal,
+ style: DesktopChrome.control(color: DesktopChrome.muted),
+ ),
+ ),
+ ],
if (_error case final error?) ...[
const SizedBox(height: 12),
Text(error, style: DesktopChrome.control()),
@@ -372,10 +401,10 @@ class SuperTabBuddyBar extends StatelessWidget {
c.addBuddy(
projectId: chat.projectId,
machineId: machineId,
- engine: engine,
+ engine: buddyRestartEngine(engine),
),
),
- child: const Text('Start again'),
+ child: Text(buddyRestartLabel(engine)),
),
],
),
@@ -425,10 +454,10 @@ class SuperTabBuddyBar extends StatelessWidget {
c.addBuddy(
projectId: chat.projectId,
machineId: agent.machineId,
- engine: agent.engine,
+ engine: buddyRestartEngine(agent.engine),
),
),
- child: const Text('Start again'),
+ child: Text(buddyRestartLabel(agent.engine)),
),
],
),
diff --git a/desktop/lib/super_tabs/roles_editor.dart b/desktop/lib/super_tabs/roles_editor.dart
index 1c8a1d971..01667411a 100644
--- a/desktop/lib/super_tabs/roles_editor.dart
+++ b/desktop/lib/super_tabs/roles_editor.dart
@@ -65,6 +65,7 @@ Keep each Builder's list a few tasks deep; do the easy, self-contained parts fir
- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.
- When you need a person to act or decide, tag them in the message.
- Ask people for decisions in one place: decision.ask puts up to 10 questions to one person at once, each with 2 to 5 options, the one you recommend and what the answer unblocks. Keep working on your recommendation, marked provisional, until they answer: a notice in that conversation tells you, and harness super-tab decisions --answered shows the answer. A decision is not a private channel: anything private goes through Chat with PM.
+- A Builder or Reviewer blocked on a missing tool, device or sign-in: within minutes, route the task again with what was missing in its needs (fix its required machine if that is the one without it), assign it to a machine and account that has it, then stop the blocked agent unless other work fits its machine. A Mac's own account and its Team account are different: the Team account has none of the owner's tools, devices or sign-ins. If none has it, tag the requester with the choice.
- Settle ambiguities you can and record "Ruling: what — why — cost if wrong".
- When a worker finishes: reuse, keep or stop. Prefer stop.
@@ -107,7 +108,8 @@ You finish one group's work completely, inside its brief, as if nobody will come
- Say in the group that you took it and what you will do first; mark it working.
- Read the whole brief: why, wanted, owned code, hand back, checks, most likely wrong, needs.
- Read how the code behaves today before changing it.
-- If the brief needs a machine, device or person, check it is available; if not, post a "Needs:" line and do the parts that don't depend on it.
+- In your first minutes, check that this machine and account have every tool, device and sign-in you need to do the work yourself (for example flutter, xcodebuild, a connected iPhone, a signed-in gh or App Store account, docker); a device step the brief leaves to a person stays a "Needs:" line. If one is missing, mark blocked at once and stop (see Blocked).
+- If the brief needs a person, check they are available; if not, post a "Needs:" line and do the parts that don't depend on it.
- Harness already created your worktree; work there.
## 2. Do the work
@@ -123,6 +125,7 @@ You finish one group's work completely, inside its brief, as if nobody will come
- A person's decision: mark needs-human with one short question.
- When you know who decides, add ask to that needs-human (the person, 2 to 5 options, the one you recommend, what it unblocks) and keep working on your recommendation, marked provisional, until a notice says it was answered; read the answer with harness super-tab decisions --answered.
- Can't go on: mark blocked with why and what would unblock you, then do the independent parts.
+- A missing tool, device or sign-in on this machine and account: mark blocked at once, naming what is missing, the machine, and whether it is the owner's or the Team account (no emails or tokens), and stop: the Lead moves the task. Never wait silently.
- Stop and ask before anything irreversible, security-sensitive, outside your worktree, visible or audible on a real device, or moving hardware.
## 4. Hand off
@@ -162,7 +165,7 @@ You give an independent verdict on one revision. Work otherwise the way you norm
4. Project instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) outrank this skill.
## 1. When
-Start within 30 minutes of being asked; oldest ready work first. If you cannot, tell the Lead.
+Start within 30 minutes of being asked; oldest ready work first. If you cannot, tell the Lead. In your first minutes, check that this machine and account have every tool, device and sign-in the review needs; if one is missing, mark blocked at once, naming what is missing, the machine, and whether it is the owner's or the Team account (no emails or tokens), and stop: the Lead moves the task.
## 2. What to look for
- Wrong behaviour, missed cases, and what the brief asked for but is missing.
diff --git a/desktop/lib/viewer/group_sync.dart b/desktop/lib/viewer/group_sync.dart
index dbb98cd35..65a4fc7a6 100644
--- a/desktop/lib/viewer/group_sync.dart
+++ b/desktop/lib/viewer/group_sync.dart
@@ -8,6 +8,7 @@ import '../e2ee/envelope.dart';
import '../e2ee/relay_session_crypto.dart';
import 'password_link.dart' show RelaySocketFactory, defaultRelaySocket;
import 'viewer_key_store.dart';
+import '../ws/ws_conn.dart' show declaredAppVersion;
/// The trust group, on a device with no harness CLI — the viewer's half of `cli/src/lib/e2ee/
/// trustGroup.ts` and `groupSyncer.ts`.
@@ -240,9 +241,13 @@ Future<GroupSyncOutcome> syncTrustGroup({
identity: identity,
peerPub: pin.pub,
);
- // It says what it is (`?client=`; backend lib/wsAttribution.ts, WebSocket roadmap Phase 0).
+ // It says what it is and which build (`?client=`, `?v=`; backend lib/wsAttribution.ts, Phase 0).
final uri = Uri.parse('$wsBaseUrl/api/web-ws').replace(
- queryParameters: {'autonomousEnv': autonomousEnv, 'client': 'group-sync'},
+ queryParameters: {
+ 'autonomousEnv': autonomousEnv,
+ 'client': 'group-sync',
+ 'v': ?declaredAppVersion,
+ },
);
final ch = channel = socket(uri, [accessToken]);
final reply = await () async {
diff --git a/desktop/lib/viewer/password_link.dart b/desktop/lib/viewer/password_link.dart
index 58fda61a0..64a38012f 100644
--- a/desktop/lib/viewer/password_link.dart
+++ b/desktop/lib/viewer/password_link.dart
@@ -10,6 +10,7 @@ import '../e2ee/envelope.dart';
import '../e2ee/keys.dart';
import '../e2ee/password_pake.dart';
import '../e2ee/primitives.dart';
+import '../ws/ws_conn.dart' show declaredAppVersion;
/// How far a password link has got — the stages `harness link connect --json` reports, spelled the
/// same (see [wireName]) so the link form shows one progress for either build.
@@ -70,9 +71,13 @@ Future<PasswordLinkResult> linkWithPassword({
Duration timeout = const Duration(seconds: 30),
}) async {
onProgress?.call(PasswordLinkStage.connecting);
- // It says what it is (`?client=`; backend lib/wsAttribution.ts, WebSocket roadmap Phase 0).
+ // It says what it is and which build (`?client=`, `?v=`; backend lib/wsAttribution.ts, Phase 0).
final uri = Uri.parse('$wsBaseUrl/api/web-ws').replace(
- queryParameters: {'autonomousEnv': autonomousEnv, 'client': 'link'},
+ queryParameters: {
+ 'autonomousEnv': autonomousEnv,
+ 'client': 'link',
+ 'v': ?declaredAppVersion,
+ },
);
final channel = socket(uri, [accessToken]);
final run = _PasswordLinkRun(machineId, password, identity, channel, onProgress);
diff --git a/desktop/test/buddy_refusal_parity_test.dart b/desktop/test/buddy_refusal_parity_test.dart
new file mode 100644
index 000000000..86bc5630e
--- /dev/null
+++ b/desktop/test/buddy_refusal_parity_test.dart
@@ -0,0 +1,25 @@
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/super_tabs/buddies.dart' show kBuddyEngineRefusals;
+
+/// The words beside a disabled Codex in Add a Buddy are the server's own
+/// refusal (security re-check of #2087), from the one backend file Desktop's CI
+/// checks out (backend superTabs/buddyContract.ts). The backend holds the same
+/// pair to this file (superTabs/buddies.test.ts), so a change on either side
+/// fails until it is carried to the other.
+void main() {
+ test('Desktop\'s Codex Buddy refusal is the server\'s', () {
+ final contract = File('../backend/src/superTabs/buddyContract.ts');
+ if (!contract.existsSync()) {
+ throw StateError(
+ '${contract.path} missing: run from desktop/ in the monorepo',
+ );
+ }
+ final server = RegExp(r"export const CODEX_BUDDY_REFUSAL = '([^']*)'")
+ .firstMatch(contract.readAsStringSync())
+ ?.group(1);
+ expect(server, isNotNull, reason: 'the backend names its refusal');
+ expect(kBuddyEngineRefusals['codex'], server);
+ });
+}
diff --git a/desktop/test/super_tab_buddies_test.dart b/desktop/test/super_tab_buddies_test.dart
index 8252663c3..f2a484110 100644
--- a/desktop/test/super_tab_buddies_test.dart
+++ b/desktop/test/super_tab_buddies_test.dart
@@ -1,6 +1,7 @@
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/super_tabs/buddies.dart' show kBuddyEngineRefusals;
import 'package:harness/super_tabs/controller.dart';
import 'package:harness/super_tabs/view.dart';
@@ -66,7 +67,7 @@ void main() {
await c.addBuddy(
projectId: 'lead',
machineId: 'ken-mac',
- engine: 'codex',
+ engine: 'claude',
),
isTrue,
);
@@ -76,7 +77,7 @@ void main() {
'type': 'buddy.create',
'projectId': 'lead',
'machineId': 'ken-mac',
- 'engine': 'codex',
+ 'engine': 'claude',
},
]);
expect(c.buddy('lead'), isNotNull);
@@ -84,6 +85,24 @@ void main() {
},
);
+ test('a Codex Buddy is refused, as the backend does for now', () async {
+ final server = buddySwarm();
+ final c = server.controller(account: 'peer');
+ addTearDown(c.dispose);
+ await c.refresh();
+
+ expect(
+ await c.addBuddy(
+ projectId: 'lead',
+ machineId: 'ken-mac',
+ engine: 'codex',
+ ),
+ isFalse,
+ );
+ expect(c.operationError, kBuddyEngineRefusals['codex']);
+ expect(c.buddy('lead'), isNull);
+ });
+
test('a refused add says why and opens nothing', () async {
final server = buddySwarm();
server.refuse = {
@@ -463,15 +482,13 @@ void main() {
expect(find.text('Kens-Mini'), findsWidgets);
await tester.tap(find.text('Kens-Mini').last);
await tester.pumpAndSettle();
- await tester.tap(find.text('Codex'));
- await tester.pumpAndSettle();
await tester.tap(submit);
await tester.pumpAndSettle();
expect(commands(server, 'buddy.create').single, {
'type': 'buddy.create',
'projectId': 'lead',
'machineId': 'ken-mini',
- 'engine': 'codex',
+ 'engine': 'claude',
});
await close(tester, c);
},
@@ -532,8 +549,6 @@ void main() {
};
final c = await show(tester, server);
await open(tester);
- await tester.tap(find.text('Codex'));
- await tester.pumpAndSettle();
await tester.tap(submit);
await tester.pumpAndSettle();
@@ -551,7 +566,31 @@ void main() {
);
await tester.tap(submit);
await tester.pumpAndSettle();
- expect(commands(server, 'buddy.create').last['engine'], 'codex');
+ expect(commands(server, 'buddy.create').last['engine'], 'claude');
+ await close(tester, c);
+ });
+
+ testWidgets('offers Codex turned off, saying why, and starts Claude', (
+ tester,
+ ) async {
+ final server = buddySwarm();
+ final c = await show(tester, server);
+ await open(tester);
+
+ final codex = find.widgetWithText(RadioListTile<String>, 'Codex');
+ expect(tester.widget<RadioListTile<String>>(codex).enabled, isFalse);
+ expect(
+ find.descendant(
+ of: find.byType(AlertDialog),
+ matching: find.text(kBuddyEngineRefusals['codex']!),
+ ),
+ findsOneWidget,
+ );
+ await tester.tap(codex);
+ await tester.pumpAndSettle();
+ await tester.tap(submit);
+ await tester.pumpAndSettle();
+ expect(commands(server, 'buddy.create').single['engine'], 'claude');
await close(tester, c);
});
@@ -635,7 +674,7 @@ void main() {
'a Buddy that is down offers Start again on the same machine',
(tester) async {
final server = buddySwarm();
- giveBuddy(server, engine: 'codex');
+ giveBuddy(server, engine: 'claude');
((server.state['agents'] as List).last as Map)['downSince'] =
'2026-10-28T09:00:00Z';
final c = await show(tester, server);
@@ -652,7 +691,7 @@ void main() {
'type': 'buddy.create',
'projectId': 'lead',
'machineId': 'ken-mac',
- 'engine': 'codex',
+ 'engine': 'claude',
});
// The new Buddy replaces the down one: one Buddy, running.
expect(c.operationError, isNull);
@@ -666,6 +705,55 @@ void main() {
},
);
+ testWidgets(
+ 'a down Codex Buddy offers Claude Code in its place, on the same machine (review 2 of #2087)',
+ (tester) async {
+ final server = buddySwarm();
+ giveBuddy(server, engine: 'codex');
+ ((server.state['agents'] as List).last as Map)['downSince'] =
+ '2026-10-28T09:00:00Z';
+ final c = await show(tester, server);
+ await tester.tap(buddyEntry);
+ await tester.pumpAndSettle();
+
+ expect(find.widgetWithText(TextButton, 'Start again'), findsNothing);
+ await tester.tap(
+ find.widgetWithText(TextButton, 'Start with Claude Code'),
+ );
+ await tester.pumpAndSettle();
+ expect(commands(server, 'buddy.create').single, {
+ 'type': 'buddy.create',
+ 'projectId': 'lead',
+ 'machineId': 'ken-mac',
+ 'engine': 'claude',
+ });
+ expect(c.operationError, isNull);
+ await close(tester, c);
+ },
+ );
+
+ testWidgets(
+ 'a Codex Buddy whose start failed offers Claude Code in its place (review 2 of #2087)',
+ (tester) async {
+ final server = buddySwarm();
+ startBuddy(
+ server,
+ engine: 'codex',
+ error: 'Its machine did not start it within 3 minutes.',
+ );
+ final c = await show(tester, server);
+ await tester.tap(buddyEntry);
+ await tester.pumpAndSettle();
+
+ await tester.tap(
+ find.widgetWithText(TextButton, 'Start with Claude Code'),
+ );
+ await tester.pumpAndSettle();
+ expect(commands(server, 'buddy.create').single['engine'], 'claude');
+ await close(tester, c);
+ },
+ );
+
testWidgets(
'a message to the Buddy never reads as having no Lead: a Buddy chat has none',
(tester) async {
diff --git a/desktop/test/super_tab_roster_test.dart b/desktop/test/super_tab_roster_test.dart
index 324613e49..1a2ec28f1 100644
--- a/desktop/test/super_tab_roster_test.dart
+++ b/desktop/test/super_tab_roster_test.dart
@@ -603,6 +603,31 @@ void main() {
await f.close(tester);
});
+ testWidgets(
+ 'a Codex Buddy\'s mode, which New Harness does not offer, reads by name',
+ (tester) async {
+ final f = await fixture(tester);
+ f.app.stateOf('m')!.agents = const [
+ Agent(
+ id: 'a1',
+ name: 'Multiply',
+ engine: 'codex',
+ permissionMode: 'readOnlyAsk',
+ ),
+ ];
+ (f.server.state['agents'] as List)[1]['configuration'] = {
+ 'engine': 'codex',
+ };
+ await f.controller.refresh();
+ await f.show(tester);
+ await tester.tap(f.row(1));
+ await tester.pumpAndSettle();
+ expect(find.text('Read only, asks you'), findsOneWidget);
+ expect(find.text('Unrecognized setting'), findsNothing);
+ await f.close(tester);
+ },
+ );
+
testWidgets(
'question details name the machine owner only for an on-screen question',
(tester) async {
diff --git a/desktop/test/support/super_tab_fixture.dart b/desktop/test/support/super_tab_fixture.dart
index 38fce8a60..d81384a9f 100644
--- a/desktop/test/support/super_tab_fixture.dart
+++ b/desktop/test/support/super_tab_fixture.dart
@@ -5,6 +5,7 @@ import 'dart:typed_data';
import 'package:dio/dio.dart' show CancelToken;
import 'package:harness/super_tabs/attachment_upload.dart';
+import 'package:harness/super_tabs/buddies.dart' show kBuddyEngineRefusals;
import 'package:harness/super_tabs/controller.dart';
import 'package:harness/super_tabs/reading.dart';
@@ -665,6 +666,14 @@ class ConversationServer {
// at once.
final person = reader ?? 'owner';
final projectId = command['projectId'] as String;
+ // As the backend: no Codex Buddy for now (security review 1 of #2087).
+ if (command['engine'] == 'codex') {
+ throw SuperTabFailure(
+ 'BUDDY_ENGINE',
+ kBuddyEngineRefusals['codex']!,
+ statusCode: 403,
+ );
+ }
bool mine(Object? a) =>
a is Map &&
(a['buddyOf'] as Map?)?['personId'] == person &&
diff --git a/desktop/test/viewer/group_sync_test.dart b/desktop/test/viewer/group_sync_test.dart
index a25bf87e0..e720842ec 100644
--- a/desktop/test/viewer/group_sync_test.dart
+++ b/desktop/test/viewer/group_sync_test.dart
@@ -11,6 +11,7 @@ import 'package:harness/e2ee/primitives.dart';
import 'package:harness/viewer/group_sync.dart';
import 'package:harness/viewer/viewer_key_store.dart';
import 'package:web_socket_channel/web_socket_channel.dart';
+import 'package:harness/ws/ws_conn.dart' show declaredAppVersion;
/// The viewer build's trust-group swap (`lib/viewer/group_sync.dart`) — the same code the phone
/// runs, against a machine end that answers exactly as manager.ts does.
@@ -164,6 +165,8 @@ void main() {
'removed': [],
};
});
+ declaredAppVersion = '1.3.64';
+ addTearDown(() => declaredAppVersion = null);
final outcome = await syncTrustGroup(
machineId: _machineId,
keys: keys,
@@ -175,10 +178,10 @@ void main() {
);
expect(seen!['self'], containsPair('kind', 'viewer'));
expect(outcome.pinned, [_c]);
- // It says what it is (WebSocket roadmap Phase 0).
+ // It says what it is, and which build (WebSocket roadmap Phase 0).
expect(
socket.dialled.toString(),
- 'wss://relay.test/api/web-ws?autonomousEnv=prod&client=group-sync',
+ 'wss://relay.test/api/web-ws?autonomousEnv=prod&client=group-sync&v=1.3.64',
);
expect(b64e((await keys.peer(_c))!.pub), cPub);
},
diff --git a/desktop/test/viewer/password_link_version_test.dart b/desktop/test/viewer/password_link_version_test.dart
new file mode 100644
index 000000000..a8a67e666
--- /dev/null
+++ b/desktop/test/viewer/password_link_version_test.dart
@@ -0,0 +1,33 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/e2ee/keys.dart';
+import 'package:harness/viewer/password_link.dart';
+import 'package:harness/ws/ws_conn.dart' show declaredAppVersion;
+
+/// A password link's socket says what it is and which build (WebSocket roadmap Phase 0): without the
+/// version it counted against the 95% of web-ws connects that must name both.
+void main() {
+ test('a password link dials saying it is a link, and the build', () async {
+ declaredAppVersion = '1.3.64';
+ addTearDown(() => declaredAppVersion = null);
+ Uri? dialled;
+ await expectLater(
+ linkWithPassword(
+ machineId: 'a' * 32,
+ password: 'pw',
+ identity: await E2eeIdentity.generate(),
+ accessToken: 't',
+ wsBaseUrl: 'wss://relay.test',
+ autonomousEnv: 'prod',
+ socket: (uri, _) {
+ dialled = uri;
+ throw StateError('no network in tests');
+ },
+ ),
+ throwsStateError,
+ );
+ expect(
+ dialled.toString(),
+ 'wss://relay.test/api/web-ws?autonomousEnv=prod&client=link&v=1.3.64',
+ );
+ });
+}
diff --git a/docs/swarms.md b/docs/swarms.md
index 5ec879722..7f03c7425 100644
--- a/docs/swarms.md
+++ b/docs/swarms.md
@@ -196,17 +196,23 @@ The Swarm's owner turns Buddies on for the Swarm; they are off until then. Turni
any still starting, and stops their posts. Their chats stay for their owners to read.
- Each person may add one Buddy per project. They choose the project, one of their own machines in the Swarm's Machines
- list, and Claude Code or Codex. Like a Product Manager, a Buddy runs only on its owner's own machine, in their own
+ list, and Claude Code (a Codex Buddy is refused for now; see below). Like a Product Manager, a Buddy runs only on its owner's own machine, in their own
account: never on a machine shared with them, and never in a Harness Team account.
- A Buddy reads its project's chat and its own chat, nothing else. It cannot read workgroups, other people's chats or
the Leads conversation. It can post only in its own chat. The server refuses every other command, and a Buddy's own
Swarm read shows no machines or routing rules.
- A Buddy never changes code. A Claude Code Buddy starts in asking mode: only its Super Tab commands run without asking,
- file editing is turned off, and the files in its own copy of the project are read-only. A Codex Buddy keeps Codex's
- full permissions with read-only files (follow-up: give Codex the same pre-approved commands). No Buddy gets the
+ file editing is turned off, and the files in its own copy of the project are read-only. No Buddy gets the
Harness GitHub App's token.
Claude Code also merges allow rules from the machine owner's own settings and the project's checked-in settings: a
broad shell rule there applies to a Buddy too, so keep those narrow on machines that run Claude Buddies.
+- The server refuses a Codex Buddy for now. Codex runs a command its rules files allow outside its sandbox without
+ asking, and those files are shared by all of the person's Codex sessions: Harness's own allows `harness new` and
+ `harness send`, and the person's keeps everything they once told Codex to always allow. A Codex Buddy comes back once
+ it has a Codex home of its own. Every Codex Buddy started before the refusal (Harness before 10-29) runs with Codex's
+ full permissions, and its relaunches keep the mode it was started with: remove it and add a Claude Code Buddy. A
+ start the server recorded before the refusal, run by a Harness from 10-29 on, starts in Codex's read-only sandbox
+ with approvals sent to the person, and a Codex too old for that mode stays stopped rather than starting without it.
- Nobody else is ever added to a Buddy chat, the Swarm's owner and the product manager included.
- A proposal is sent only for its owner's own message in their Buddy chat that asked for it: their newest message there,
or one from the last hour, and only once for each such message. The server writes the "on behalf of" label, so a Buddy cannot leave it out or change it.
@@ -286,6 +292,79 @@ never records what anyone wrote. The only text it shows is the title of a
conversation the reader can read. Private conversations, Chat with PM among
them, never count and never appear in it.
+## Cost records
+
+Every task a Lead routes records what it ran on, what it cost and how it ended,
+so a Swarm can show that it gets work done cheaper and route each job to the
+cheapest harness that still gets it right.
+
+Each attempt keeps:
+
+- the kind of job the Lead gave when routing (`ui`, `docs`; `review` for a
+ review), or none;
+- the engine, model and effort it ran at, and the model on the Swarm's grid when
+ it ran one;
+- how it was paid: an engine plan (subscription), per token through an API (an
+ API key, or a grid model shared from one), the Swarm's own GPUs, or unknown;
+- its session's token counts by model (input, output, cache reads and cache
+ writes) when it started and when it ended. Its tokens are the difference. A
+ session counts up to 15 models apart; any more are counted together as
+ `other`, which has no price;
+- its end reading: an agent finishing its own work (Done or Stopped) sends its
+ session's totals read at that moment. Finished by someone else, or by a host
+ from before cost records, its tokens are unknown rather than taken from an
+ older report. A lost, cancelled or host-stopped attempt ends with its
+ machine's last report;
+- how it ended: done, stopped, cancelled, lost, or superseded when its group went
+ while it was still active. A task lost to a usage limit and taken back by the
+ same session is the same attempt, still going. Handing a lost task to another
+ agent is a new attempt; the old one stays lost.
+
+Each machine sends its running Swarm agents' token counts with its usual report.
+Only counts leave the machine: never text, prompts, folders or pull requests.
+Members never see the raw counts; they read the summary.
+
+**Prices.** Costs use API list prices per model, in US dollars, from one reviewed
+table in the backend (`backend/src/superTabs/costs/prices.ts`). Each price names
+its source and the day it was read. A model without a listed price has no cost,
+never a guessed one. Grid models reached through OpenRouter are priced at
+OpenRouter's rates. A model served on the Swarm's own GPUs costs 0, and its
+attempts say so. Two costs are shown: what the tokens would have cost on the API,
+and what was actually spent per token (nothing on a plan or on own GPUs).
+
+**Reading it.** The Lead reads `harness super-tab costs [--days N]` (7 days unless
+set, at most 90), for the Product Manager, and later for the leaderboard and the
+nightly reflection. Per engine, model, effort and kind of job it gives:
+attempts, first-review pass rate, shipped, median minutes to ship, tokens,
+API-equivalent cost, actual spend, and cost per shipped change. A request ships
+once, at its merge or first Done as the leaderboard records it, by the attempt
+that was running then; more attempts done afterwards ship nothing new. Time to
+ship runs from that attempt's start to when the request shipped. Cost per shipped change is shown only when every ended attempt's cost is
+known, so a partial sum never reads cheaper than it was. It covers only attempts
+routed since cost records began, in the groups the reader may read.
+
+Design:
+
+- Growth: the records live on route decisions, which are deleted after 90 days
+ as before. A machine's report keeps counts only for its running agents.
+- Concurrency: recorded in the same write that starts or ends the attempt, so a
+ newer write retries on current data like every other Swarm write.
+- Read cost: one index read of the period's decisions (tabId and creation time),
+ at most 3,000, then only the groups they name. It never reads messages.
+- Scale: a busy Swarm routes about 300 tasks a week, so 90 days is about 4,000;
+ the 3,000 cap says when it cut. The read's time is the first warning.
+- Compatibility: an old host sends no counts and its attempts have no tokens; an
+ old backend refuses the new fields and the CLI sends its report and routes
+ without them. The backend deploys first.
+- Migration and rollback: additive fields, no migration. Rolling back leaves them
+ unread.
+- Audience: the server returns only attempts in groups the reader may read.
+- Identity: counts are recorded per Swarm agent, never as the machine owner.
+- Failure: an attempt with no reading or no price shows no cost and is counted
+ apart, never as zero.
+- Platforms: the counts come from Claude Code and Codex transcripts on macOS,
+ Linux and Windows hosts alike.
+
## Avatars, status and celebrations
People and agents each show one avatar wherever they appear: messages, the
diff --git a/scripts/record-ci-validation.py b/scripts/record-ci-validation.py
index 1c62eee01..c0b12e47c 100644
--- a/scripts/record-ci-validation.py
+++ b/scripts/record-ci-validation.py
@@ -39,9 +39,11 @@ SOURCE_INPUTS = {
# daemon metadata and store catalog/artwork, including docs/images posters,
# the Hub's publication rules that desktop/lib/community/hub_contract.dart mirrors, its usage
# counters that desktop/lib/measurement/hub_usage.dart sends (test/hub_usage_contract_test.dart), and the
- # phone's P2P/E2EE sources the web's copies are checked against (test/p2p/mobile_parity_test.dart).
+ # phone's P2P/E2EE sources the web's copies are checked against (test/p2p/mobile_parity_test.dart), and the
+ # server's Buddy refusal its Add a Buddy dialog shows (test/buddy_refusal_parity_test.dart).
"desktop": (".github/", "scripts/", "desktop/", "cli/", "tests/", "daemons/", "store/", "docs/images/",
"mobile/pubspec.lock", "backend/src/lib/communityContract.ts", "backend/src/lib/hubMetricsContract.ts",
+ "backend/src/superTabs/buddyContract.ts",
"mobile/lib/p2p/terminal_p2p_plugin.dart", "mobile/lib/p2p/terminal_p2p_link.dart", "mobile/lib/p2p/terminal_p2p_policy.dart",
"mobile/lib/ws/terminal_transport_plugin.dart", "mobile/lib/ws/relay_codec.dart", "mobile/lib/e2ee/relay_session_crypto.dart",
".gitattributes", ".gitignore", ".gitmodules", "Makefile"),