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.

Merge batch 11-05 i1625: #3129 #3091 #3117 #3122 #3125 (#3136)

0xken15432b687c1339
diff --git a/backend/integration/superTabWorkspaces.test.ts b/backend/integration/superTabWorkspaces.test.ts
index 42f0f5f74..92f16fe8d 100644
--- a/backend/integration/superTabWorkspaces.test.ts
+++ b/backend/integration/superTabWorkspaces.test.ts
@@ -14,6 +14,7 @@ import type { AuthUser } from '../src/lib/ssoAuth.js'
import type { Command } from '../src/superTabs/commands.js'
import { migrateWorkspaces, rollbackWorkspaces } from '../src/superTabs/migration/workspaces.js'
import { hasWorkspaceAccess, SwarmWorkspaces } from '../src/superTabs/workspaceStore.js'
+import { plan, profiled, reads } from './plans.test-support.js'
// Workspaces above Swarms (docs/plans/2026-10-27-swarm-workspaces.md): every route, authorization and Mongo transaction is real.
let replica: MongoMemoryReplSet, db: PrismaClient, store: SuperTabStore, app: FastifyInstance
@@ -253,6 +254,84 @@ describe('removing someone from a Workspace', () => {
expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/accept`, peer, {})).statusCode).toBe(200)
expect((await call('POST', `/api/super-tabs/${tab}/join`, peer, { operationId: randomUUID(), token })).statusCode).toBe(200)
})
+
+ it('withdraws their pending invitation, so accepting it afterwards finds none and they stay removed', async () => {
+ const workspaceId = await workspace('Final')
+ // Sent before the removal, and never accepted: today it would bring them back as an admin.
+ expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/invitations`, owner, { email: member.email, role: 'admin' })).statusCode).toBe(200)
+ expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/members/${member.sub}/remove`, owner, {})).statusCode).toBe(200)
+ expect(await db.swarmWorkspaceInvitation.findUnique({ where: { id: `${workspaceId}:${member.email}` } })).toBeNull()
+ expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/accept`, member, {})).statusCode).toBe(404)
+ expect((await db.swarmWorkspaceMember.findUniqueOrThrow({ where: { id: `${workspaceId}:${member.sub}` } })).removedAt).not.toBeNull()
+ expect((await workspacesOf(member)).map(o => o.id)).not.toContain(workspaceId)
+ })
+
+ it('refuses an invitation sent before their latest removal, and accepts one sent after it', async () => {
+ const workspaceId = await workspace('Stale')
+ expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/members/${member.sub}/remove`, owner, {})).statusCode).toBe(200)
+ // As a removal before this fix left it: an admin invitation sent a minute before the removal, still pending.
+ const removal = await db.swarmWorkspaceRemoval.findFirstOrThrow({ where: { workspaceId, userId: member.sub } })
+ const sentAt = removal.removedAt.getTime() - 60_000
+ await db.swarmWorkspaceInvitation.create({ data: { id: `${workspaceId}:${member.email}`, workspaceId, email: member.email, role: 'admin',
+ invitedBy: owner.sub, expiresAt: new Date(sentAt + 14 * 24 * 60 * 60 * 1000) } })
+ expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/accept`, member, {})).statusCode).toBe(404)
+ expect((await db.swarmWorkspaceMember.findUniqueOrThrow({ where: { id: `${workspaceId}:${member.sub}` } })).removedAt).not.toBeNull()
+ // A new invitation, sent after the removal, brings them back with its role.
+ expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/invitations`, owner, { email: member.email, role: 'guest' })).statusCode).toBe(200)
+ const accepted = await call('POST', `/api/super-tabs/workspaces/${workspaceId}/accept`, member, {})
+ expect(accepted.statusCode).toBe(200)
+ expect(accepted.json().data.role).toBe('guest')
+ })
+
+ it('reads only the accepting person\'s removals, by the Workspace and person index', async () => {
+ const workspaceId = await workspace('Removal reads')
+ for (const who of [peer, member]) expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/members/${who.sub}/remove`, owner, {})).statusCode).toBe(200)
+ expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/invitations`, owner, { email: member.email, role: 'guest' })).statusCode).toBe(200)
+ const entries = await profiled(db, async () => expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/accept`, member, {})).statusCode).toBe(200))
+ // The read of the newest removal; finishPending's read of open ones names finishedAt.
+ const rows = reads(entries, 'SwarmWorkspaceRemoval', ['workspaceId', 'userId'], ['finishedAt'])
+ expect(rows, JSON.stringify(plan(rows))).toHaveLength(1)
+ expect(rows[0]!.planSummary, JSON.stringify(plan(rows))).toMatch(/IXSCAN \{ workspaceId: 1, userId: 1, finishedAt: 1/)
+ expect(rows[0]!.docsExamined, JSON.stringify(plan(rows))).toBe(1)
+ })
+
+ it('accepts an invitation for someone never removed as today', async () => {
+ const workspaceId = await workspace('Never removed')
+ expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/invitations`, admin, { email: newcomer.email, role: 'member' })).statusCode).toBe(200)
+ const accepted = await call('POST', `/api/super-tabs/workspaces/${workspaceId}/accept`, newcomer, {})
+ expect(accepted.statusCode).toBe(200)
+ expect(accepted.json().data).toEqual({ workspaceId, role: 'member' })
+ expect(await roleOf(workspaceId, newcomer)).toBe('member')
+ })
+})
+
+describe('revoking a pending Workspace invitation', () => {
+ const revoke = (workspaceId: string, as: AuthUser, email: string) => call('POST', `/api/super-tabs/workspaces/${workspaceId}/invitations/revoke`, as, { email })
+ const pending = async (workspaceId: string) =>
+ ((await people(workspaceId, owner)).json().data.invitations as Array<{ email: string; role: string }>).map(i => i.email)
+
+ it('lets owners and admins revoke invitations for roles they may give, after which accepting finds none', async () => {
+ const workspaceId = await workspace('Revoke')
+ for (const [email, role] of [[other.email, 'admin'], [newcomer.email, 'guest']] as const) {
+ expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/invitations`, owner, { email, role })).statusCode).toBe(200)
+ }
+ // A member, a guest and an outsider cannot; an admin cannot withdraw an admin invitation it could not have sent.
+ expect((await revoke(workspaceId, member, other.email)).statusCode).toBe(403)
+ expect((await revoke(workspaceId, peer, other.email)).statusCode).toBe(403)
+ expect((await revoke(workspaceId, returner, other.email)).statusCode).toBe(404)
+ expect((await revoke(workspaceId, admin, other.email)).statusCode).toBe(403)
+ expect((await pending(workspaceId)).sort()).toEqual([newcomer.email, other.email].sort())
+
+ expect((await revoke(workspaceId, admin, newcomer.email)).statusCode).toBe(200)
+ const revoked = await revoke(workspaceId, owner, other.email.toUpperCase())
+ expect(revoked.statusCode).toBe(200)
+ expect(revoked.json().data).toEqual({ email: other.email, revoked: true })
+ expect(await pending(workspaceId)).toEqual([])
+ expect(await db.swarmWorkspaceInvitation.count({ where: { workspaceId } })).toBe(0)
+ for (const who of [other, newcomer]) expect((await call('POST', `/api/super-tabs/workspaces/${workspaceId}/accept`, who, {})).statusCode).toBe(404)
+ // Nothing left to revoke.
+ expect((await revoke(workspaceId, owner, other.email)).statusCode).toBe(404)
+ })
})
describe('a machine contributed to Swarms of two Workspaces', () => {
@@ -518,6 +597,21 @@ describe('a Swarm invitation for someone the Workspace removed', () => {
expect(await swarmPeople(tab)).toContain(returner.sub)
})
+ it('refuses even an admin\'s invitation sent before the removal, while one sent after it brings them back (#3173)', async () => {
+ const { workspaceId, tab } = await setUp('Sent before removal')
+ // Sent while they were in the Workspace and not yet in this Swarm; the removal leaves only Swarms they are in.
+ const early = (await inviteAs(tab, admin)).json().data.result.inviteId as string
+ await removeReturner(workspaceId)
+ await expect(accept(tab, early)).rejects.toMatchObject({ code: 'WORKSPACE_ACCESS_REVOKED', status: 403 })
+ await keptOut(workspaceId, tab)
+
+ const again = await inviteAs(tab, admin)
+ expect(again.statusCode).toBe(200)
+ await accept(tab, again.json().data.result.inviteId as string)
+ expect(await rowOf(workspaceId, returner)).toMatchObject({ removedAt: null, role: 'guest', addedBy: admin.sub })
+ expect(await swarmPeople(tab)).toContain(returner.sub)
+ })
+
it('lets a person never removed join through a member\'s invitation as today, credited to that member', async () => {
const { workspaceId, tab } = await setUp('Never removed')
const created = await inviteAs(tab, member, newcomer.email)
diff --git a/backend/src/config/env.ts b/backend/src/config/env.ts
index c3d695f78..2dbd9fc27 100644
--- a/backend/src/config/env.ts
+++ b/backend/src/config/env.ts
@@ -309,13 +309,18 @@ const envSchema = z.object({
GITHUB_APP_CLIENT_SECRET: z.string().default(''),
// Phone push (push/keys.ts, task #2905): a thread reply or a tag reaches a phone whose app is closed. APNs for iPhones: the
- // key Apple generated in the developer account (the .p8 file, with its line breaks as \n, or base64 of it), its Key ID and
+ // Production key Apple generated in the developer account (the .p8 file, with its line breaks as \n, or base64 of it), its Key ID and
// the Team ID; all three or none. FCM for Android: base64 of the Firebase service account's JSON key. Unset: that platform
// gets no push, and each one skipped is counted and logged. A value that cannot be right stops the backend at startup, with
// a message that never shows it.
APNS_KEY_ID: z.string().default(''),
APNS_TEAM_ID: z.string().default(''),
APNS_PRIVATE_KEY: z.string().default(''),
+ // Apple's keys are per environment: the three above are the Production key, used on Apple's production host alone. The
+ // Sandbox key, for an Xcode build's tokens, is used on the sandbox host alone; both or neither, and only beside the
+ // production key. Unset: an Xcode build's push is skipped, and logged (Ken, 11-05).
+ APNS_SANDBOX_KEY_ID: z.string().default(''),
+ APNS_SANDBOX_PRIVATE_KEY: z.string().default(''),
// The iPhone app's bundle id, which Apple sends to.
APNS_TOPIC: z.string().default('ai.autonomous.harness.ios'),
FCM_SERVICE_ACCOUNT: z.string().default(''),
diff --git a/backend/src/push/apns.test.ts b/backend/src/push/apns.test.ts
index e82ab711c..3c7b55c14 100644
--- a/backend/src/push/apns.test.ts
+++ b/backend/src/push/apns.test.ts
@@ -7,7 +7,11 @@ import type { PushDevice } from './devices.js'
import type { PhoneNotice } from './sender.js'
const { privateKey } = generateKeyPairSync('ec', { namedCurve: 'prime256v1' })
-const keys = { keyId: 'ABC123DEFG', teamId: 'TEAM123456', privateKey, topic: 'ai.autonomous.harness.ios' }
+const sandboxKey = generateKeyPairSync('ec', { namedCurve: 'prime256v1' }).privateKey
+// Apple's keys are per environment: the production key is refused on the sandbox host and the other way round (Ken, 11-05).
+const keys = { teamId: 'TEAM123456', topic: 'ai.autonomous.harness.ios', production: { keyId: 'ABC123DEFG', privateKey },
+ sandbox: { keyId: '5UTFPCN7LP', privateKey: sandboxKey } }
+const productionOnly = { ...keys, sandbox: null }
const device: PushDevice = { id: 'd1', userId: 'u1', platform: 'ios', token: 'ab'.repeat(32), sandbox: false }
const notice: PhoneNotice = { personId: 'u1', key: 'reply:tab:row', title: 'Mia replied in a thread', subtitle: 'openharness',
body: 'Open Harness to read it.', link: 'swarm:tab/conv/message/m/thread/root' }
@@ -64,10 +68,26 @@ describe('APNs sender (task #2905)', () => {
}
})
- it('tries a development build\'s token on the sandbox host once, and says so when it is taken there', async () => {
+ it('tries a development build\'s token on the sandbox host once, signed with the sandbox key, and says so when it is taken there', async () => {
const { asked, transport } = scripted({ status: 400, reason: 'BadDeviceToken' }, { status: 200, reason: null })
expect(await apnsSender(keys, { transport }).send(device, notice)).toEqual({ outcome: 'sandbox' })
expect(asked.map(r => r.sandbox)).toEqual([false, true])
+ expect(part(jwtOf(asked[0]!), 0).kid).toBe('ABC123DEFG')
+ expect(part(jwtOf(asked[1]!), 0).kid).toBe('5UTFPCN7LP')
+ const [head, claims, signature] = jwtOf(asked[1]!).split('.')
+ expect(verify('sha256', Buffer.from(`${head}.${claims}`), { key: createPublicKey(sandboxKey), dsaEncoding: 'ieee-p1363' }, Buffer.from(signature!, 'base64url'))).toBe(true)
+ })
+
+ it('without a sandbox key, never sends to the sandbox host: a production BadDeviceToken is skipped, and the token kept', async () => {
+ const { asked, transport } = scripted({ status: 400, reason: 'BadDeviceToken' })
+ expect(await apnsSender(productionOnly, { transport }).send(device, notice)).toEqual({ outcome: 'unconfigured', reason: 'no APNs sandbox key' })
+ expect(asked.map(r => r.sandbox)).toEqual([false])
+ })
+
+ it('without a sandbox key, sends nothing for a token known to be a sandbox one', async () => {
+ const { asked, transport } = scripted()
+ expect(await apnsSender(productionOnly, { transport }).send({ ...device, sandbox: true }, notice)).toEqual({ outcome: 'unconfigured', reason: 'no APNs sandbox key' })
+ expect(asked).toEqual([])
})
it('calls a token neither host takes gone', async () => {
@@ -75,10 +95,11 @@ describe('APNs sender (task #2905)', () => {
expect(await apnsSender(keys, { transport }).send(device, notice)).toEqual({ outcome: 'gone', reason: 'BadDeviceToken' })
})
- it('sends a sandbox token to the sandbox host alone', async () => {
+ it('sends a sandbox token to the sandbox host alone, signed with the sandbox key', async () => {
const { asked, transport } = scripted({ status: 200, reason: null })
expect(await apnsSender(keys, { transport }).send({ ...device, sandbox: true }, notice)).toEqual({ outcome: 'sent' })
expect(asked.map(r => r.sandbox)).toEqual([true])
+ expect(part(jwtOf(asked[0]!), 0)).toEqual({ alg: 'ES256', kid: '5UTFPCN7LP' })
})
it('fails on Apple\'s error, a broken connection, or no answer in time', async () => {
diff --git a/backend/src/push/apns.ts b/backend/src/push/apns.ts
index 3dd132961..6ada2cecf 100644
--- a/backend/src/push/apns.ts
+++ b/backend/src/push/apns.ts
@@ -1,6 +1,6 @@
import { sign } from 'node:crypto'
import http2 from 'node:http2'
-import type { ApnsKeys } from './keys.js'
+import type { ApnsKey, ApnsKeys } from './keys.js'
import type { PushDevice } from './devices.js'
import { SEND_TIMEOUT_MS, SWARM_CHANNEL, withTimeout, type PhoneNotice, type Sender, type SendResult } from './sender.js'
@@ -17,23 +17,26 @@ const GONE = new Set(['Unregistered', 'DeviceTokenNotForTopic', 'BadDeviceToken'
const base64url = (value: string | Buffer) => Buffer.from(value).toString('base64url')
/**
- * Sends to iPhones through Apple's HTTP/2 API with a token signed by the team's key (task #2905). An Xcode build's token is
- * known only to the sandbox host: production calls it bad, so it is tried there once, and the device is marked (`sandbox`).
+ * Sends to iPhones through Apple's HTTP/2 API (task #2905), each host with a token signed by its own environment's key: Apple
+ * refuses the production key on the sandbox host and the other way round (Ken, 11-05). An Xcode build's token is known only to
+ * the sandbox host: production calls it bad, so it is tried there once, and the device is marked (`sandbox`). With no sandbox
+ * key, nothing goes to the sandbox host: such a push is skipped (`unconfigured`) and the token kept.
*/
export function apnsSender(keys: ApnsKeys, options: { transport?: ApnsTransport; now?: () => number; timeoutMs?: number } = {}): Sender {
const transport = options.transport ?? http2Transport(), now = options.now ?? Date.now, timeoutMs = options.timeoutMs ?? SEND_TIMEOUT_MS
- let jwt: { value: string; at: number } | null = null
- const bearer = () => {
- const at = now()
- if (!jwt || at - jwt.at >= JWT_RENEW_MS) {
- const signed = `${base64url(JSON.stringify({ alg: 'ES256', kid: keys.keyId }))}.${base64url(JSON.stringify({ iss: keys.teamId, iat: Math.floor(at / 1000) }))}`
- jwt = { value: `${signed}.${base64url(sign('sha256', Buffer.from(signed), { key: keys.privateKey, dsaEncoding: 'ieee-p1363' }))}`, at }
- }
- return jwt.value
+ const jwts = new Map<ApnsKey, { value: string; at: number }>()
+ const bearer = (key: ApnsKey) => {
+ const at = now(), jwt = jwts.get(key)
+ if (jwt && at - jwt.at < JWT_RENEW_MS) return jwt.value
+ const signed = `${base64url(JSON.stringify({ alg: 'ES256', kid: key.keyId }))}.${base64url(JSON.stringify({ iss: keys.teamId, iat: Math.floor(at / 1000) }))}`
+ const value = `${signed}.${base64url(sign('sha256', Buffer.from(signed), { key: key.privateKey, dsaEncoding: 'ieee-p1363' }))}`
+ jwts.set(key, { value, at })
+ return value
}
+ const noSandboxKey: SendResult = { outcome: 'unconfigured', reason: 'no APNs sandbox key' }
const ask = async (device: PushDevice, notice: PhoneNotice, sandbox: boolean): Promise<ApnsAnswer> => withTimeout(transport({
sandbox, path: `/3/device/${device.token}`,
- headers: { authorization: `bearer ${bearer()}`, 'apns-topic': keys.topic, 'apns-push-type': 'alert', 'apns-priority': '10',
+ headers: { authorization: `bearer ${bearer(sandbox ? keys.sandbox! : keys.production)}`, 'apns-topic': keys.topic, 'apns-push-type': 'alert', 'apns-priority': '10',
'apns-expiration': String(Math.floor(now() / 1000) + 24 * 60 * 60) },
body: JSON.stringify({ aps: { alert: { title: notice.title, subtitle: notice.subtitle, body: notice.body }, sound: 'default',
'thread-id': SWARM_CHANNEL, category: SWARM_CHANNEL }, key: notice.key, link: notice.link }),
@@ -46,8 +49,11 @@ export function apnsSender(keys: ApnsKeys, options: { transport?: ApnsTransport;
return {
async send(device, notice) {
try {
+ if (device.sandbox && !keys.sandbox) return noSandboxKey
const answer = await ask(device, notice, device.sandbox)
if (device.sandbox || answer.status !== 400 || answer.reason !== 'BadDeviceToken') return judged(answer, false)
+ // Perhaps an Xcode build's token: only the sandbox host can say, with the sandbox key.
+ if (!keys.sandbox) return noSandboxKey
return judged(await ask(device, notice, true), true)
} catch (error) {
return { outcome: 'failed', reason: (error as Error).message === 'timeout' ? 'timeout' : (error as NodeJS.ErrnoException).code ?? (error as Error).message }
diff --git a/backend/src/push/keys.test.ts b/backend/src/push/keys.test.ts
index c6976dad0..00f9842cb 100644
--- a/backend/src/push/keys.test.ts
+++ b/backend/src/push/keys.test.ts
@@ -6,7 +6,9 @@ const ec = generateKeyPairSync('ec', { namedCurve: 'prime256v1' }).privateKey.ex
const rsa = generateKeyPairSync('rsa', { modulusLength: 2048 }).privateKey.export({ type: 'pkcs8', format: 'pem' }).toString()
const account = { type: 'service_account', project_id: 'harness-push', client_email: '[email protected]',
private_key: rsa, token_uri: 'https://oauth2.googleapis.com/token' }
-const none = { APNS_KEY_ID: '', APNS_TEAM_ID: '', APNS_PRIVATE_KEY: '', APNS_TOPIC: 'ai.autonomous.harness.ios', FCM_SERVICE_ACCOUNT: '' }
+const none = { APNS_KEY_ID: '', APNS_TEAM_ID: '', APNS_PRIVATE_KEY: '', APNS_SANDBOX_KEY_ID: '', APNS_SANDBOX_PRIVATE_KEY: '', APNS_TOPIC: 'ai.autonomous.harness.ios',
+ FCM_SERVICE_ACCOUNT: '' }
+const ec2 = generateKeyPairSync('ec', { namedCurve: 'prime256v1' }).privateKey.export({ type: 'pkcs8', format: 'pem' }).toString()
const apns = { ...none, APNS_KEY_ID: 'ABC123DEFG', APNS_TEAM_ID: 'TEAM123456', APNS_PRIVATE_KEY: ec.replace(/\n/g, '\\n') }
const fcm = { ...none, FCM_SERVICE_ACCOUNT: Buffer.from(JSON.stringify(account)).toString('base64') }
@@ -18,11 +20,23 @@ describe('push keys from the server\'s secret store (task #2905)', () => {
it('reads the APNs key as Apple hands it out, with its line breaks as \\n or as base64 of the .p8 file', () => {
for (const key of [apns.APNS_PRIVATE_KEY, Buffer.from(ec).toString('base64')]) {
const keys = pushKeysFromEnv({ ...apns, APNS_PRIVATE_KEY: key })
- expect(keys.apns).toMatchObject({ keyId: 'ABC123DEFG', teamId: 'TEAM123456', topic: 'ai.autonomous.harness.ios' })
- expect(keys.apns!.privateKey.asymmetricKeyType).toBe('ec')
+ expect(keys.apns).toMatchObject({ teamId: 'TEAM123456', topic: 'ai.autonomous.harness.ios', production: { keyId: 'ABC123DEFG' }, sandbox: null })
+ expect(keys.apns!.production.privateKey.asymmetricKeyType).toBe('ec')
}
})
+ it('reads Apple\'s sandbox key beside the production one: each key signs for its own host alone (Ken, 11-05)', () => {
+ const keys = pushKeysFromEnv({ ...apns, APNS_SANDBOX_KEY_ID: '5UTFPCN7LP', APNS_SANDBOX_PRIVATE_KEY: Buffer.from(ec2).toString('base64') })
+ expect(keys.apns).toMatchObject({ production: { keyId: 'ABC123DEFG' }, sandbox: { keyId: '5UTFPCN7LP' } })
+ expect(keys.apns!.sandbox!.privateKey.asymmetricKeyType).toBe('ec')
+ })
+
+ it('stops the server when the sandbox key is set in part, or without the production key, naming what is missing', () => {
+ expect(() => pushKeysFromEnv({ ...apns, APNS_SANDBOX_KEY_ID: '5UTFPCN7LP' })).toThrow(/APNS_SANDBOX_PRIVATE_KEY/)
+ expect(() => pushKeysFromEnv({ ...apns, APNS_SANDBOX_PRIVATE_KEY: ec2 })).toThrow(/APNS_SANDBOX_KEY_ID/)
+ expect(() => pushKeysFromEnv({ ...none, APNS_SANDBOX_KEY_ID: '5UTFPCN7LP', APNS_SANDBOX_PRIVATE_KEY: ec2 })).toThrow(/APNS_KEY_ID/)
+ })
+
it('reads the Firebase service account from base64 of its JSON file', () => {
expect(pushKeysFromEnv(fcm).fcm).toMatchObject({ projectId: 'harness-push', clientEmail: account.client_email, tokenUri: account.token_uri })
})
@@ -33,13 +47,13 @@ describe('push keys from the server\'s secret store (task #2905)', () => {
})
it('stops the server on a key that cannot be right, and never repeats it', () => {
- const cases = [{ ...apns, APNS_PRIVATE_KEY: 'not-a-key-SECRET' }, { ...apns, APNS_PRIVATE_KEY: rsa.replace(/\n/g, '\\n') },
+ const cases = [{ ...apns, APNS_PRIVATE_KEY: 'not-a-key-SECRET' }, { ...apns, APNS_SANDBOX_KEY_ID: '5UTFPCN7LP', APNS_SANDBOX_PRIVATE_KEY: 'not-a-key-SECRET' }, { ...apns, APNS_PRIVATE_KEY: rsa.replace(/\n/g, '\\n') },
{ ...none, FCM_SERVICE_ACCOUNT: 'SECRETnotbase64json' }, { ...none, FCM_SERVICE_ACCOUNT: Buffer.from(JSON.stringify({ ...account, private_key: 'SECRET' })).toString('base64') },
{ ...none, FCM_SERVICE_ACCOUNT: Buffer.from(JSON.stringify({ ...account, project_id: '' })).toString('base64') }]
for (const env of cases) {
let message = ''
try { pushKeysFromEnv(env) } catch (error) { message = (error as Error).message }
- expect(message).toMatch(/APNS_PRIVATE_KEY|FCM_SERVICE_ACCOUNT/)
+ expect(message).toMatch(/APNS_PRIVATE_KEY|APNS_SANDBOX_PRIVATE_KEY|FCM_SERVICE_ACCOUNT/)
expect(message).not.toMatch(/SECRET|BEGIN/)
}
})
diff --git a/backend/src/push/keys.ts b/backend/src/push/keys.ts
index 49ed8fb3a..b924c1cd2 100644
--- a/backend/src/push/keys.ts
+++ b/backend/src/push/keys.ts
@@ -1,11 +1,15 @@
import { createPrivateKey, type KeyObject } from 'node:crypto'
-/** Apple's push key (a .p8 from the developer account), the ids it is signed with, and the app it sends to. */
-export interface ApnsKeys { keyId: string; teamId: string; privateKey: KeyObject; topic: string }
+/** One of Apple's push keys (a .p8 from the developer account) and its Key ID. */
+export interface ApnsKey { keyId: string; privateKey: KeyObject }
+/** Apple's push keys are per environment: the production key signs for the production host alone, the sandbox key (an Xcode
+ * build's tokens) for the sandbox host alone; each is refused on the other host (Ken, 11-05). The team, and the app they send to. */
+export interface ApnsKeys { teamId: string; topic: string; production: ApnsKey; sandbox: ApnsKey | null }
/** The Firebase service account that sends to Android phones. */
export interface FcmAccount { projectId: string; clientEmail: string; privateKey: KeyObject; tokenUri: string }
-export interface PushEnv { APNS_KEY_ID: string; APNS_TEAM_ID: string; APNS_PRIVATE_KEY: string; APNS_TOPIC: string; FCM_SERVICE_ACCOUNT: string }
+export interface PushEnv { APNS_KEY_ID: string; APNS_TEAM_ID: string; APNS_PRIVATE_KEY: string; APNS_SANDBOX_KEY_ID: string; APNS_SANDBOX_PRIVATE_KEY: string
+ APNS_TOPIC: string; FCM_SERVICE_ACCOUNT: string }
/** A PEM private key with its line breaks as `\n`, or base64 of the file. Errors name the variable, never the value. */
function readKey(name: string, value: string, type: 'ec' | 'rsa'): KeyObject {
@@ -39,11 +43,16 @@ function readAccount(value: string): FcmAccount {
*/
export function pushKeysFromEnv(env: PushEnv): { apns: ApnsKeys | null; fcm: FcmAccount | null } {
const keyId = env.APNS_KEY_ID.trim(), teamId = env.APNS_TEAM_ID.trim(), key = env.APNS_PRIVATE_KEY.trim()
+ const sandboxId = env.APNS_SANDBOX_KEY_ID.trim(), sandboxKey = env.APNS_SANDBOX_PRIVATE_KEY.trim()
+ const missing = (pairs: string[][]) => pairs.filter(([, v]) => !v).map(([n]) => n).join(', ')
let apns: ApnsKeys | null = null
- if (keyId || teamId || key) {
- const missing = [['APNS_KEY_ID', keyId], ['APNS_TEAM_ID', teamId], ['APNS_PRIVATE_KEY', key]].filter(([, v]) => !v).map(([n]) => n)
- if (missing.length) throw new Error(`Set APNS_KEY_ID, APNS_TEAM_ID and APNS_PRIVATE_KEY for phone push, or none: ${missing.join(', ')} missing.`)
- apns = { keyId, teamId, privateKey: readKey('APNS_PRIVATE_KEY', key, 'ec'), topic: env.APNS_TOPIC.trim() }
+ if (keyId || teamId || key || sandboxId || sandboxKey) {
+ const production = missing([['APNS_KEY_ID', keyId], ['APNS_TEAM_ID', teamId], ['APNS_PRIVATE_KEY', key]])
+ if (production) throw new Error(`Set APNS_KEY_ID, APNS_TEAM_ID and APNS_PRIVATE_KEY for phone push, or none: ${production} missing.`)
+ const sandbox = sandboxId || sandboxKey ? missing([['APNS_SANDBOX_KEY_ID', sandboxId], ['APNS_SANDBOX_PRIVATE_KEY', sandboxKey]]) : ''
+ if (sandbox) throw new Error(`Set APNS_SANDBOX_KEY_ID and APNS_SANDBOX_PRIVATE_KEY together, or neither: ${sandbox} missing.`)
+ apns = { teamId, topic: env.APNS_TOPIC.trim(), production: { keyId, privateKey: readKey('APNS_PRIVATE_KEY', key, 'ec') },
+ sandbox: sandboxId ? { keyId: sandboxId, privateKey: readKey('APNS_SANDBOX_PRIVATE_KEY', sandboxKey, 'ec') } : null }
}
return { apns, fcm: env.FCM_SERVICE_ACCOUNT.trim() ? readAccount(env.FCM_SERVICE_ACCOUNT) : null }
}
diff --git a/backend/src/push/send.test.ts b/backend/src/push/send.test.ts
index 1572dd61c..d9ed7b7d0 100644
--- a/backend/src/push/send.test.ts
+++ b/backend/src/push/send.test.ts
@@ -42,6 +42,16 @@ describe('sendPhoneNotices (task #2905)', () => {
expect(JSON.stringify([m.warn.mock.calls, m.info.mock.calls])).not.toContain('secret-token')
})
+ it('keeps a token whose sandbox push was skipped for want of a sandbox key, and logs it without the token', async () => {
+ m.devicesOf.mockResolvedValue([phone('dev', 'a')])
+ const ios = answering({ dev: { outcome: 'unconfigured', reason: 'no APNs sandbox key' } })
+ await sendPhoneNotices(db, { ios: ios.sender, android: null }, [notice('a')])
+ expect(m.forget).not.toHaveBeenCalled()
+ expect(m.count).toHaveBeenCalledWith('ios', 'unconfigured')
+ expect(m.warn).toHaveBeenCalledWith('phone push skipped', { platform: 'ios', reason: 'no APNs sandbox key' })
+ expect(JSON.stringify(m.warn.mock.calls)).not.toContain('secret-token')
+ })
+
it('counts and logs a push it cannot send for want of the platform\'s keys', async () => {
m.devicesOf.mockResolvedValue([phone('a2', 'a', 'android')])
await sendPhoneNotices(db, { ios: null, android: null }, [notice('a')])
diff --git a/backend/src/push/send.ts b/backend/src/push/send.ts
index ef2028471..db3c270b9 100644
--- a/backend/src/push/send.ts
+++ b/backend/src/push/send.ts
@@ -17,7 +17,8 @@ const AT_ONCE = 8
export function phoneSendersFromEnv(env: PushEnv): PhoneSenders {
const keys = pushKeysFromEnv(env)
const senders = { ios: keys.apns && apnsSender(keys.apns), android: keys.fcm && fcmSender(keys.fcm) }
- logger.info('phone push', { ios: senders.ios ? 'on' : 'off: no APNs key', android: senders.android ? 'on' : 'off: no FCM service account' })
+ const ios = !keys.apns ? 'off: no APNs key' : keys.apns.sandbox ? 'on, Xcode builds too' : 'on, but Xcode builds skipped: no APNs sandbox key'
+ logger.info('phone push', { ios, android: senders.android ? 'on' : 'off: no FCM service account' })
return senders
}
@@ -51,6 +52,7 @@ export async function sendPhoneNotices(db: PrismaClient, senders: PhoneSenders,
if (result.outcome === 'gone') await forgetPushDevice(db, device.id)
if (result.outcome === 'sandbox') await markSandbox(db, device.id)
if (result.outcome === 'failed') logger.warn('phone push failed', { platform: device.platform, reason: result.reason })
+ if (result.outcome === 'unconfigured') logger.warn('phone push skipped', { platform: device.platform, reason: result.reason })
}
}
await Promise.all(Array.from({ length: Math.min(AT_ONCE, sends.length) }, lane))
diff --git a/backend/src/push/sender.ts b/backend/src/push/sender.ts
index bd133d275..6a10b4b6c 100644
--- a/backend/src/push/sender.ts
+++ b/backend/src/push/sender.ts
@@ -7,8 +7,9 @@ import type { PushDevice } from './devices.js'
*/
export interface PhoneNotice { personId: string; key: string; title: string; subtitle: string; body: string; link: string }
-/** sent; gone: the token is dead, forget it; sandbox: taken by Apple's sandbox host, send there from now on; failed. */
-export type SendOutcome = 'sent' | 'gone' | 'sandbox' | 'failed'
+/** sent; gone: the token is dead, forget it; sandbox: taken by Apple's sandbox host, send there from now on; failed;
+ * unconfigured: the server has no key for where it would go (Apple's sandbox host), so nothing was sent and the token is kept. */
+export type SendOutcome = 'sent' | 'gone' | 'sandbox' | 'failed' | 'unconfigured'
/** `reason` is Apple's or Google's word for it, or `timeout`: never the token. */
export interface SendResult { outcome: SendOutcome; reason?: string }
diff --git a/backend/src/routes/superTabs.ts b/backend/src/routes/superTabs.ts
index a98de5497..ae2c06ef5 100644
--- a/backend/src/routes/superTabs.ts
+++ b/backend/src/routes/superTabs.ts
@@ -76,6 +76,7 @@ const workspaceName = z.string().trim().min(1).max(160)
const workspaceCreate = z.object({ operationId: id, name: workspaceName }).strict()
const workspaceRename = z.object({ name: workspaceName }).strict()
const workspaceInvite = z.object({ email: z.email().max(320), role: z.enum(['admin', 'member', 'guest']) }).strict()
+const workspaceRevoke = z.object({ email: z.email().max(320) }).strict()
const workspaceRole = z.object({ role: z.enum(['admin', 'member', 'guest']) }).strict()
const workspaceTransfer = z.object({ userId: id }).strict()
const workspaceVisibility = z.object({ visibility: z.enum(['invite-only', 'workspace']) }).strict()
@@ -484,6 +485,10 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
app.post<{ Params: z.infer<typeof workspaceParams>; Body: z.infer<typeof workspaceInvite> }>('/api/super-tabs/workspaces/:workspaceId/invitations',
{ preHandler: [validateParams(workspaceParams), validateBody(workspaceInvite)] },
(req, reply) => respond(reply, () => { personOnly(req.user!); return store.workspaces.invite(req.user!, req.params.workspaceId, req.body.email, req.body.role) }))
+ // A POST, not a DELETE, for the daemon (below).
+ app.post<{ Params: z.infer<typeof workspaceParams>; Body: z.infer<typeof workspaceRevoke> }>('/api/super-tabs/workspaces/:workspaceId/invitations/revoke',
+ { preHandler: [validateParams(workspaceParams), validateBody(workspaceRevoke)] },
+ (req, reply) => respond(reply, () => { personOnly(req.user!); return store.workspaces.revokeInvitation(req.user!, req.params.workspaceId, req.body.email) }))
app.post<{ Params: z.infer<typeof workspaceParams> }>('/api/super-tabs/workspaces/:workspaceId/accept', { preHandler: validateParams(workspaceParams) },
(req, reply) => respond(reply, () => { personOnly(req.user!); return store.workspaces.accept(req.user!, req.params.workspaceId) }))
app.post<{ Params: z.infer<typeof workspaceMemberParams>; Body: z.infer<typeof workspaceRole> }>('/api/super-tabs/workspaces/:workspaceId/members/:userId',
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index 474a5ecda..104ddcd00 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -69,6 +69,9 @@ const NO_REASON = 'No reason given.'
const ONLY_CANDIDATE = 'Only candidate that can run this task.'
/** What an older client's policy, skill-set, role or rule-removal save answers: accepted, kept nowhere (project instructions,
* phase 4, decision 3). The old rules, policy rows and role texts stay in place, unread. */
+/** How long a Swarm invitation stays open; its sent time is its expiry minus this (store.ts invite.accept). */
+export const SWARM_INVITATION_MS = 7 * 86_400_000
+
export const IGNORED_NOTE = 'Routing and roles live in each project\'s instructions now. Update Harness to edit them there.'
const title = z.string().trim().min(1).max(160)
const reason = z.string().trim().min(1).max(300)
@@ -3203,7 +3206,7 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
if (context.inviteeRemoved) fail('WORKSPACE_ROLE_REQUIRED', `This person was removed from the ${WORKSPACE_LABEL}. Only its owners and admins can invite them back.`, 403)
state.invitations = state.invitations.filter(i => i.email !== email)
state.invitations.push({ id: operationId, email, role: command.role, conversationId: landing,
- expiresAt: context.now + 7 * 86_400_000, ...(actor.kind === 'person' ? { invitedBy: actor.userId } : {}) })
+ expiresAt: context.now + SWARM_INVITATION_MS, ...(actor.kind === 'person' ? { invitedBy: actor.userId } : {}) })
result.inviteId = operationId
break
}
diff --git a/backend/src/superTabs/engineHealth.test.ts b/backend/src/superTabs/engineHealth.test.ts
index 679e8efc7..1b4344af9 100644
--- a/backend/src/superTabs/engineHealth.test.ts
+++ b/backend/src/superTabs/engineHealth.test.ts
@@ -31,6 +31,22 @@ describe('an engine whose starts fail on a machine', () => {
expect(engineUnusable(pool, 'claude', NOW)).toBeNull()
})
+ // 11-05: six first starts failed to clone on four machines, and each pair suspended the engine there for hours.
+ it('is never suspended by starts that failed to clone the project, which is the network or GitHub, not the engine', () => {
+ const pool = machine(), state = stateWith(pool)
+ for (const error of ["This machine could not clone the project repository with the Harness GitHub App's token: Could not clone the repository (git said: early EOF). Check the URL and connection, then retry.",
+ "This machine could not clone the project repository with the Harness GitHub App's token: Cloning stopped making progress after 120 s.",
+ 'This machine could not access the project repository over HTTPS or SSH. Its owner needs GitHub access to it here: run gh auth login.']) {
+ for (let i = 0; i < 3; i++) expect(noteStartFailed(state, start({}, error), NOW)).toBeNull()
+ }
+ expect(pool.engineFailures).toBeUndefined()
+ expect(suspendedEngines(pool, NOW)).toEqual({})
+ // A real failure in between still counts, and clone failures do not reset the count.
+ noteStartFailed(state, start(), NOW)
+ expect(noteStartFailed(state, start({}, 'Could not clone the repository.'), NOW)).toBeNull()
+ expect(noteStartFailed(state, start(), NOW)).not.toBeNull()
+ })
+
it('says so once per suspension, never on a later failed start or report', () => {
const pool = machine(), state = stateWith(pool)
noteStartFailed(state, start(), NOW)
diff --git a/backend/src/superTabs/engineHealth.ts b/backend/src/superTabs/engineHealth.ts
index 63e464f24..8024ef260 100644
--- a/backend/src/superTabs/engineHealth.ts
+++ b/backend/src/superTabs/engineHealth.ts
@@ -12,12 +12,15 @@ export const SUSPEND_AFTER = 2
export const SUSPENSION_MS = 6 * 3_600_000
const NAME: Record<string, string> = { claude: 'Claude Code', codex: 'Codex' }
const named = (engine: string) => NAME[engine] ?? engine
-/** Failures that say nothing of the engine: the machine was removed, the start was dropped, or it lacked memory. Read at
+/** Failures that say nothing of the engine: the machine was removed, the start was dropped, it lacked memory, or it could not clone the project. Read at
* call time: machines.ts imports this file, and startFailure.ts reaches machines.ts, so its constants may not exist yet
* while this file loads. */
const notTheEngine = (error: string) => error === MACHINE_REMOVED || error === ABANDONED || error === 'Removed by its owner before it started.'
- || MEMORY_SHORT.test(error)
+ || MEMORY_SHORT.test(error) || CLONE_FAILED.test(error)
const MEMORY_SHORT = /^Not enough free memory: /
+/** A first start whose machine could not clone the project (cli superTabs/projectFolder.ts): the network or GitHub, not the engine.
+ * Six starts on four machines failed this way on 2026-11-05, and each pair suspended an engine there for hours. */
+const CLONE_FAILED = /could not (?:clone|access) the (?:project )?repository/i
function pool(state: SuperTabState, machineId: string) { return state.machines?.find(m => m.machineId === machineId) }
/** Only a routed worker's start: a Product Manager's start has its own retries (leadStart.ts), and a Buddy is its owner's own. */
diff --git a/backend/src/superTabs/routeRecord.test.ts b/backend/src/superTabs/routeRecord.test.ts
index a7f991971..06e23dfb0 100644
--- a/backend/src/superTabs/routeRecord.test.ts
+++ b/backend/src/superTabs/routeRecord.test.ts
@@ -119,33 +119,60 @@ describe('a route decision of every engine on every machine, as stored (task #27
})
// Task #2901: with no pick, nobody knows which candidate runs until the start, and the route history needs that one's account
- // and spend (cli service.ts routeHistory). So every candidate keeps those two of its fit, and nothing else of it.
+ // and spend (cli service.ts routeHistory). So every candidate keeps those of its fit, and its quota status (task #3163).
const pickless = (): RouteRecord => {
const { pick: _pick, ...rest } = routed()
return { ...rest, via: 'instructions', why: 'No ranking: the project\'s Routing instructions choose.' } as RouteRecord
}
- // Measured 11-04: 14,568 bytes, of which the 42 slim fits are 5,376 (128 bytes a candidate, its 64-character account most of it).
- it('stores a record that names no pick, 42 candidates each with its account and spend, in under 15 KB (measured 14,568 bytes)', () => {
- expect(size(storedRecord(pickless()))).toBeLessThan(15_000)
+ // Measured 11-04: 14,568 bytes, of which the 42 slim fits are 5,376 (128 bytes a candidate, its 64-character account most of it);
+ // 15,282 bytes since each keeps its fit status too (task #3163), from a CLI that sends no % left or reset.
+ it('stores a record that names no pick, 42 candidates each with its account, spend and status, in under 16 KB (measured 15,282 bytes)', () => {
+ expect(size(storedRecord(pickless()))).toBeLessThan(16_000)
})
- it('keeps of every candidate of a record that names no pick who and where it is, its title and its account and spend', () => {
+ it('keeps of every candidate of a record that names no pick who and where it is, its title and its account, spend and status', () => {
const r = pickless(), back = readRecord(storedRecord(r))
for (const [i, c] of r.candidates.entries()) {
const kept = back.candidates[i]!
expect(kept).toEqual({ id: c.id, kind: c.kind, ...c.agentId ? { agentId: c.agentId } : {}, machineId: c.machineId, engine: c.engine, model: c.model,
- effort: c.effort, title: c.title, fit: { account: c.fit!.account, spend: c.fit!.spend } })
+ effort: c.effort, title: c.title, fit: { account: c.fit!.account, spend: c.fit!.spend, status: c.fit!.status } })
}
})
+ // Task #3163 (Ken, 2026-11-05): with only account and spend kept, 3,905 of 3,915 Codex candidates on production had no fit
+ // status, and quota at route time could not be measured. Every candidate keeps its status, weekly % left and reset again.
+ const quoted = (): RouteRecord => {
+ const r = pickless()
+ r.candidates = r.candidates.map((c, i) => ({ ...c, fit: { ...c.fit!, status: i % 3 ? 'fits' as const : 'short' as const, left: i % 3 ? 64 : 2, resetsAt: 1_793_900_000_000 + i } }))
+ return r
+ }
+ it('takes each candidate\'s weekly % left and reset in its fit, and refuses them out of range', () => {
+ expect(routeRecordSchema.safeParse(quoted()).success).toBe(true)
+ const r = quoted()
+ r.candidates[0]!.fit = { ...r.candidates[0]!.fit!, left: null, resetsAt: null }
+ expect(routeRecordSchema.safeParse(r).success).toBe(true)
+ r.candidates[0]!.fit = { ...r.candidates[0]!.fit!, left: 101 }
+ expect(routeRecordSchema.safeParse(r).success).toBe(false)
+ })
+ it('keeps of every candidate of a record that names no pick its fit status, weekly % left and reset beside its account and spend', () => {
+ const r = quoted(), back = readRecord(storedRecord(r))
+ for (const [i, c] of r.candidates.entries()) {
+ expect(back.candidates[i]!.fit).toEqual({ account: c.fit!.account, spend: c.fit!.spend, status: c.fit!.status, left: c.fit!.left, resetsAt: c.fit!.resetsAt })
+ }
+ })
+ // Measured 11-05: 16,742 bytes, the 42 candidates' status, % left and reset 2,174 of it (about 52 bytes a candidate).
+ it('stores a record that names no pick, 42 candidates each with its quota, in under 17 KB (measured 16,742 bytes)', () => {
+ expect(size(storedRecord(quoted()))).toBeLessThan(17_000)
+ })
+
it('keeps no fit of a candidate that had none, and no account of one that had none', () => {
const r = pickless()
delete r.candidates[0]!.fit
delete r.candidates[1]!.fit!.account
const [first, second] = storedRecord(r).candidates
expect(first).not.toHaveProperty('fit')
- expect(second!.fit).toEqual({ spend: { '5-hour': 2.5, weekly: 1 } })
+ expect(second!.fit).toEqual({ spend: { '5-hour': 2.5, weekly: 1 }, status: r.candidates[1]!.fit!.status })
})
it('keeps a grid model on a candidate that runs one', () => {
diff --git a/backend/src/superTabs/routeRecord.ts b/backend/src/superTabs/routeRecord.ts
index 818b1fc46..7e3c1de25 100644
--- a/backend/src/superTabs/routeRecord.ts
+++ b/backend/src/superTabs/routeRecord.ts
@@ -17,6 +17,10 @@ const fit = z.object({
spend: z.object({ '5-hour': amount.optional(), weekly: amount.optional() }).strict(),
/** The hashed usage key, or `machineId:engine` when the machine reports none. */
account: z.string().min(1).max(200).optional(),
+ /** The account's weekly window when the route ran (cli route.ts quotaBrief): percent left and reset in epoch ms, null when
+ * not read. Absent from a CLI from before task #3163. */
+ left: z.number().finite().min(0).max(100).nullable().optional(),
+ resetsAt: z.number().finite().nonnegative().nullable().optional(),
}).strict()
export const routeCandidateSchema = z.object({
id: candidateId,
@@ -76,8 +80,10 @@ export const routeRecordSchema = z.object({
}).strict().refine(d => d.pick === undefined || d.candidates.some(c => c.id === d.pick), 'The pick must be one of the candidates.')
.refine(d => new Set(d.candidates.map(c => c.id)).size === d.candidates.length, 'Candidate ids must be unique.')
-/** The part of a quota fit every candidate of a record without a pick keeps: what the route history reads of the one that ran. */
-export type KeptFit = Pick<z.infer<typeof fit>, 'account' | 'spend'>
+/** The part of a quota fit every candidate of a record without a pick keeps: what the route history reads of the one that ran,
+ * and its quota when the route ran (task #3163: with account and spend alone, quota at route time could not be measured).
+ * Rows written before keep no status, % left or reset. */
+export type KeptFit = Pick<z.infer<typeof fit>, 'account' | 'spend'> & Partial<Pick<z.infer<typeof fit>, 'status' | 'left' | 'resetsAt'>>
/** A candidate as a decision keeps it: the pick whole; any other only who and where it is and its title, and with no pick its
* account and spend too (storedRecord). */
export type KeptCandidate = Omit<RouteCandidate, 'quality' | 'cost' | 'label' | 'fit'> & Partial<Pick<RouteCandidate, 'quality' | 'cost' | 'label'>>
@@ -98,12 +104,16 @@ export interface StoredRouteRecord extends Omit<ReadRouteRecord, 'excluded'> {
* and where it is (a start or assignment matching it, startedAs; a person choosing it, route.override; its Team-work check) and
* its title (the chat lines, Desktop's Details). Its label, strength, cost and quota fit are read of the pick only: the route
* showed the others when it ran, and the route history takes the account and spend of the pick (cli service.ts routeHistory).
- * A record with no pick (task #2901) keeps every candidate's account and spend instead, as any of them may be the one that
+ * A record with no pick (task #2901) keeps every candidate's account, spend and quota instead, as any of them may be the one that
* runs and nobody knows which until the start. Each exclusion reason is kept once, with its titles in order. */
+function keptFit({ account, spend, status, left, resetsAt }: z.infer<typeof fit>): KeptFit {
+ return { ...account ? { account } : {}, spend, status, ...left !== undefined ? { left } : {}, ...resetsAt !== undefined ? { resetsAt } : {} }
+}
+
export function storedRecord(record: RouteRecord): StoredRouteRecord {
const { excluded, ...rest } = record
const candidates = record.candidates.map(({ label: _label, quality: _quality, cost: _cost, fit, ...c }, i): KeptCandidate =>
- record.pick === undefined ? { ...c, ...fit ? { fit: { ...fit.account ? { account: fit.account } : {}, spend: fit.spend } } : {} }
+ record.pick === undefined ? { ...c, ...fit ? { fit: keptFit(fit) } : {} }
: c.id === record.pick ? record.candidates[i]! : c)
const byReason = new Map<string, string[]>()
for (const { title, reason } of excluded) byReason.set(reason, [...byReason.get(reason) ?? [], title])
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index da4ca3b35..1614278dc 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -21,7 +21,7 @@ import { isTeamSession, teamMachine, TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE
import { machineShareGrant, sharedVia } from '../lib/machineSharePolicy.js'
import { machineBillingAllowsDataPlane } from '../lib/billingState.js'
import { DELETED_SWARM_COMMANDS, DELETION_COMMANDS, notThere } from './deletion.js'
-import { applyCommand, authorizeCommandAccess, IGNORED_NOTE, LOOP_NOTICE_AT, mayResumeStart, operationSchema, postable, reserveHarnessSlot, worksInProjectChat, ruleProject, type Command, type CommandContext } from './commands.js'
+import { applyCommand, authorizeCommandAccess, IGNORED_NOTE, SWARM_INVITATION_MS, LOOP_NOTICE_AT, mayResumeStart, operationSchema, postable, reserveHarnessSlot, worksInProjectChat, ruleProject, type Command, type CommandContext } from './commands.js'
import { redactCredentials } from './credentials.js'
import type { AvatarUpload } from './profile.js'
import { reactionCounts, type ReactionTarget } from './reactions.js'
@@ -78,7 +78,7 @@ import { freeze, readHostStamp, stampOwed, swarmReadCache, swarmTransaction, typ
import { countReport, DEADLINE_CAP_MS, localReportMemory, RECORD_TTL_MS, recordHolds, type ReportMemory, type ReportRecord } from './machineReports.js'
import { DIRECT, readLastChangedAt, readParts, type ReadNamed } from './cachedReads.js'
import { revokeNativeContexts, SuperTabNativeStore } from './native.js'
-import { activeMember, addMember, hasWorkspaceAccess, listWorkspaces, memberId, removedFromWorkspace, WORKSPACE_ACCESS_REVOKED, workspaceForNewSwarm, requireWorkspaceAccess, requireWorkspaceRole, SwarmWorkspaces } from './workspaceStore.js'
+import { activeMember, addMember, hasWorkspaceAccess, latestRemovalAt, listWorkspaces, memberId, removedFromWorkspace, WORKSPACE_ACCESS_REVOKED, workspaceForNewSwarm, requireWorkspaceAccess, requireWorkspaceRole, SwarmWorkspaces } from './workspaceStore.js'
import { WORKSPACE_LABEL, workspaceCan, type WorkspaceRole } from './workspaces.js'
import { STATUS_LABELS,
activeWork, actorKey, agent, agentOnly, appendPullRequestUrls, author, conversation, createSuperTab, fail, person, stableId, visibleState, finishWorker,
@@ -1547,9 +1547,12 @@ export class SuperTabStore {
// Workspace owners, admins and members may invite to a Swarm (invite.create). Someone the Workspace removed comes
// back only on the word of an owner or admin, as a Workspace invitation needs, read now rather than when it was
// sent: otherwise a member's invitation would undo the removal and its auto-join decline (task #2939).
+ // Nor does any invitation sent before the removal, an admin's included: the removal is final against it (task #3173).
if (await removedFromWorkspace(tx, original.workspaceId, user.sub)) {
const sender = invite.invitedBy ? await activeMember(tx, original.workspaceId, invite.invitedBy) : null
- if (!sender || !workspaceCan(sender.role as WorkspaceRole, 'workspace.invite')) {
+ const removedAt = await latestRemovalAt(tx, original.workspaceId, user.sub)
+ if (!sender || !workspaceCan(sender.role as WorkspaceRole, 'workspace.invite')
+ || (removedAt !== null && invite.expiresAt - SWARM_INVITATION_MS < removedAt)) {
fail(WORKSPACE_ACCESS_REVOKED, `You were removed from this Swarm's ${WORKSPACE_LABEL}. Ask one of its owners or admins to invite you.`, 403)
}
}
diff --git a/backend/src/superTabs/workspaceStore.ts b/backend/src/superTabs/workspaceStore.ts
index 83d54d8a0..f4a1701ed 100644
--- a/backend/src/superTabs/workspaceStore.ts
+++ b/backend/src/superTabs/workspaceStore.ts
@@ -79,6 +79,13 @@ export async function addMember(tx: Transaction, workspaceId: string, person: {
: tx.swarmWorkspaceMember.create({ data: { id, workspaceId, userId: person.id, ...data } })
}
+/** When this Workspace last removed `userId`, or null. An invitation sent before then is refused (task #3173). Removal records
+ * outlive any invitation (30 days after they finish), so none sent before a removal is missed. */
+export async function latestRemovalAt(tx: Transaction, workspaceId: string, userId: string): Promise<number | null> {
+ const removal = await tx.swarmWorkspaceRemoval.findFirst({ where: { workspaceId, userId }, orderBy: { removedAt: 'desc' }, select: { removedAt: true } })
+ return removal ? removal.removedAt.getTime() : null
+}
+
/** Whether this Workspace removed `userId`: auto-join never adds them to its Swarms. Unlike the member row, never purged. */
export async function autoJoinDeclinedBy(tx: Transaction, workspaceId: string, userId: string): Promise<boolean> {
const workspace = await tx.swarmWorkspace.findUnique({ where: { id: workspaceId }, select: { autoJoinDeclined: true } })
@@ -155,6 +162,8 @@ export async function listWorkspaces(db: PrismaClient, user: AuthUser): Promise<
/** How long a removed person's row and a deleted Workspace stay before they are purged (design, Growth). */
export const WORKSPACE_PURGE_MS = 30 * 24 * 60 * 60 * 1000
const INVITATION_MS = 14 * 24 * 60 * 60 * 1000
+/** When an invitation was last sent: `invite` sets, and every resend moves, `expiresAt` to then plus INVITATION_MS. */
+const sentAt = (invitation: { expiresAt: Date }): number => invitation.expiresAt.getTime() - INVITATION_MS
interface WorkspaceDeps {
transaction<T>(body: (tx: Transaction) => Promise<T>): Promise<T>
@@ -226,6 +235,22 @@ export class SwarmWorkspaces {
})
}
+ /** Withdraws a pending invitation, for owners and admins, and only one for a role they may give (task #3173). */
+ async revokeInvitation(user: AuthUser, workspaceId: string, email: string) {
+ const address = email.trim().toLowerCase()
+ return this.deps.transaction(async tx => {
+ await this.workspace(tx, user, workspaceId)
+ const me = await requireWorkspaceRole(tx, workspaceId, user.sub, 'workspace.invite')
+ const invitation = await tx.swarmWorkspaceInvitation.findUnique({ where: { id: `${workspaceId}:${address}` } })
+ if (!invitation || invitation.expiresAt.getTime() <= this.deps.now()) fail('NOT_FOUND', 'This invitation is unavailable.', 404)
+ if (!mayAssignRole(me.role, invitation.role as WorkspaceRole)) {
+ fail('WORKSPACE_ROLE_REQUIRED', `Your role in this ${WORKSPACE_LABEL} cannot revoke an invitation as ${invitation.role}.`, 403)
+ }
+ await tx.swarmWorkspaceInvitation.delete({ where: { id: invitation.id } })
+ return { email: address, revoked: true as const }
+ })
+ }
+
/** Invitations waiting for the signed-in person. */
async invitationsFor(user: AuthUser) {
const rows = await this.db.swarmWorkspaceInvitation.findMany({ where: { email: user.email.trim().toLowerCase(), expiresAt: { gt: new Date(this.deps.now()) } }, take: 100 })
@@ -246,6 +271,10 @@ export class SwarmWorkspaces {
await this.workspace(tx, user, workspaceId)
const invitation = await tx.swarmWorkspaceInvitation.findUnique({ where: { id: `${workspaceId}:${address}` } })
if (!invitation || invitation.expiresAt.getTime() <= this.deps.now()) fail('NOT_FOUND', 'This invitation is unavailable.', 404)
+ // A removal is final against an invitation sent before it (task #3173): `remove` deletes the pending one, and this
+ // refuses one a removal from before that fix left behind. One sent after the removal is a new decision and stands.
+ const removedAt = await latestRemovalAt(tx, workspaceId, user.sub)
+ if (removedAt !== null && sentAt(invitation) < removedAt) fail('NOT_FOUND', 'This invitation is unavailable.', 404)
await tx.swarmWorkspaceInvitation.delete({ where: { id: invitation.id } })
const role = invitation.role as WorkspaceRole
const current = await activeMember(tx, workspaceId, user.sub)
@@ -310,6 +339,8 @@ export class SwarmWorkspaces {
const now = new Date(this.deps.now())
await tx.swarmWorkspaceMember.update({ where: { id: target.id }, data: { removedAt: now, removedBy: user.sub,
purgeAt: new Date(now.getTime() + WORKSPACE_PURGE_MS), version: { increment: 1 } } })
+ // An invitation still pending would bring them back with its role (task #3173), as a Swarm's member.remove drops theirs.
+ await tx.swarmWorkspaceInvitation.deleteMany({ where: { id: `${workspaceId}:${target.email}` } })
// Swarm auto-join never adds them back, even after this row is purged (spec 2026-11-03; security review 2 of #2714).
const declined = (await tx.swarmWorkspace.findUnique({ where: { id: workspaceId }, select: { autoJoinDeclined: true } }))?.autoJoinDeclined ?? []
if (!declined.includes(userId)) await tx.swarmWorkspace.update({ where: { id: workspaceId }, data: { autoJoinDeclined: [...declined, userId].sort() } })
diff --git a/cli/src/lib/projectFolder.spec.ts b/cli/src/lib/projectFolder.spec.ts
index d1ea9ea44..206f37668 100644
--- a/cli/src/lib/projectFolder.spec.ts
+++ b/cli/src/lib/projectFolder.spec.ts
@@ -135,8 +135,21 @@ describe('project folder preparation', () => {
for (const diagnostic of ['fatal: unable to access: Could not resolve host: github.com', '']) {
const error = cloneFailure(diagnostic)
expect(error, diagnostic).not.toBeInstanceOf(RepositoryAccessError)
- expect(error).toMatchObject({ code: 'CLONE_FAILED', message: 'Could not clone the repository. Check the URL and connection, then retry.' })
+ expect(error).toMatchObject({ code: 'CLONE_FAILED' })
}
+ expect(cloneFailure('').message).toBe('Could not clone the repository. Check the URL and connection, then retry.')
+ })
+
+ // Six first starts failed on 11-05 with "Could not clone the repository" and nothing else to go on.
+ it('names git\'s own reason in a failed clone, without a credential', () => {
+ expect(cloneFailure('Cloning into \'x\'...\nfatal: unable to access \'https://github.com/o/r/\': Could not resolve host: github.com\n').message)
+ .toBe('Could not clone the repository (git said: unable to access \'https://github.com/o/r/\': Could not resolve host: github.com). Check the URL and connection, then retry.')
+ const leaked = cloneFailure('fatal: unable to access \'https://x-access-token:[email protected]/o/r/\': The requested URL returned error: 500').message
+ expect(leaked).toContain('returned error: 500')
+ expect(leaked).not.toMatch(/ghs_|x-access-token/)
+ expect(cloneFailure(`error: ${'a'.repeat(900)}`).message.length).toBeLessThan(400)
+ // A progress line is no reason: the last error line is.
+ expect(cloneFailure('error: RPC failed; HTTP 502\nfatal: early EOF\nReceiving objects: 40%\n').message).toContain('git said: early EOF')
})
it('names an untrusted host key, which is no refusal: GitHub was never asked', () => {
@@ -424,7 +437,8 @@ describe('the project clone of a large repository', () => {
const failure = await cloneRepository('https://github.com/owner/repo', join(root, 'checkout'), process.env, { git, stallMs: 1500 })
.then(() => null, (error: unknown) => error)
expect(failure).toBeInstanceOf(ProjectFolderError)
- expect(failure).toMatchObject({ code: 'CLONE_TIMEOUT', message: 'Cloning stopped making progress. Check the connection and retry.' })
+ expect(failure).toMatchObject({ code: 'CLONE_TIMEOUT', message: expect.stringContaining('Cloning stopped making progress') })
+ expect((failure as Error).message).toContain('git\'s last words: Receiving objects: 1%')
expect(Date.now() - started).toBeLessThan(10_000)
expect(running(Number(await readFile(join(root, 'pid'), 'utf8')))).toBe(false)
}, 20_000)
diff --git a/cli/src/lib/projectFolder.ts b/cli/src/lib/projectFolder.ts
index a6469fdfa..e839cc34e 100644
--- a/cli/src/lib/projectFolder.ts
+++ b/cli/src/lib/projectFolder.ts
@@ -325,7 +325,10 @@ export function cloneRepository(url: string, destination: string, gitEnv?: NodeJ
})
child.on('close', (code) => {
clearTimeout(stall)
- if (stalled) reject(new ProjectFolderError('CLONE_TIMEOUT', 'Cloning stopped making progress. Check the connection and retry.'))
+ if (stalled) {
+ const last = lastLine(diagnostic)
+ reject(new ProjectFolderError('CLONE_TIMEOUT', `Cloning stopped making progress${last ? ` (git's last words: ${last})` : ''}. Check the connection and retry.`))
+ }
else if (code !== 0) reject(cloneFailure(diagnostic))
else {
execFile(git, ['-C', destination, 'config', 'remote.origin.fetch', ALL_BRANCHES], { env, timeout: 10_000, killSignal: 'SIGKILL' },
@@ -343,6 +346,21 @@ export class RepositoryAccessError extends ProjectFolderError {}
* refusal, so the apps never call it "No access", and it may mean the key changed. Another way in checks its own key. */
export class RepositoryHostKeyError extends ProjectFolderError {}
+/** Credentials and tokens cut from a line of git's, which may quote the address it used or a helper's answer. */
+function plain(line: string): string {
+ return line.replace(/\/\/[^/@\s]*@/g, '//').replace(/\b(gh[pousr]_|github_pat_)\w+/g, '').replace(/x-access-token\S*/gi, '').trim().slice(0, 200)
+}
+/** The last thing git said, a progress line or not (carriage returns are its progress redraws). */
+function lastLine(diagnostic: string): string {
+ return plain(diagnostic.split(/[\r\n]+/).map(line => line.trim()).filter(Boolean).at(-1) ?? '')
+}
+/** Why git says it failed: its last `fatal:` or `error:` line, else nothing. Six first starts on 11-05 failed with "Could not
+ * clone the repository" and no way to tell GitHub's 5xx from a DNS failure. */
+function gitsReason(diagnostic: string): string {
+ const lines = diagnostic.split(/[\r\n]+/).map(line => /^(?:fatal|error):\s*(.+)$/i.exec(line.trim())?.[1]).filter((line): line is string => !!line)
+ return plain(lines.at(-1) ?? '')
+}
+
/** What git's diagnostic of a failed clone becomes. A private GitHub repository answers "not found" without access. */
export function cloneFailure(diagnostic: string): ProjectFolderError {
// First: ssh's warning about a changed key also says "Password authentication is disabled".
@@ -351,7 +369,7 @@ export function cloneFailure(diagnostic: string): ProjectFolderError {
}
return /authentication|permission denied|could not read username|repository not found/i.test(diagnostic)
? new RepositoryAccessError('CLONE_FAILED', 'Could not access this repository. Check the URL and GitHub access on the selected machine.')
- : new ProjectFolderError('CLONE_FAILED', 'Could not clone the repository. Check the URL and connection, then retry.')
+ : new ProjectFolderError('CLONE_FAILED', `Could not clone the repository${gitsReason(diagnostic) ? ` (git said: ${gitsReason(diagnostic)})` : ''}. Check the URL and connection, then retry.`)
}
/** The same GitHub repository over the other transport, for parseProjectFolder's two forms; null for anything else. */
diff --git a/cli/src/superTabs/__snapshots__/route.answers.json b/cli/src/superTabs/__snapshots__/route.answers.json
index 6f11a46f7..29820ae34 100644
--- a/cli/src/superTabs/__snapshots__/route.answers.json
+++ b/cli/src/superTabs/__snapshots__/route.answers.json
@@ -67,52 +67,6 @@
"title": "Multiply · Claude sonnet medium · a",
"label": "Member Multiply · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (80% left, resets in 3h); weekly 4% of 90% · a · idle · same repo · on \"Fix the dial\" · in openharness, branch fix/dial · last active 20m ago · earlier here: Dial fix merged · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
- {
- "kind": "new",
- "machineId": "a",
- "machineName": "a",
- "engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "quota": {
- "known": true,
- "leftPercent": 80,
- "resetsAt": null,
- "windows": [
- {
- "name": "5-hour",
- "leftPercent": 80,
- "resetsAt": 1010800000
- },
- {
- "name": "weekly",
- "leftPercent": 90,
- "resetsAt": 1432000000
- }
- ],
- "account": "a"
- },
- "activity": "new",
- "known": true,
- "refusals": [],
- "notes": [],
- "fit": {
- "status": "fits",
- "coverage": 1.78,
- "effectiveCost": 3,
- "expiring": 0,
- "spend": {
- "5-hour": 45,
- "weekly": 6
- },
- "account": "a"
- },
- "id": "c1",
- "title": "New agent · Claude opus high · a",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (80% left, resets in 3h); weekly 6% of 90% · a · new · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
- },
{
"kind": "new",
"machineId": "a",
@@ -155,7 +109,7 @@
},
"account": "a"
},
- "id": "c2",
+ "id": "c1",
"title": "New agent · Claude sonnet medium · a",
"label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (60% left, resets in 3h); weekly 4% of 90% · a · new · quota 5-hour 60% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
@@ -201,7 +155,7 @@
},
"account": "b"
},
- "id": "c3",
+ "id": "c2",
"title": "New agent · Claude sonnet medium · b",
"label": "New agent · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (80% left, resets in 3h); weekly 4% of 90% · b · new · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
},
@@ -253,7 +207,7 @@
},
"account": "b"
},
- "id": "c4",
+ "id": "c3",
"title": "Elsewhere · Claude sonnet medium · b",
"label": "Member Elsewhere · Claude sonnet medium · strength 2, cost 2 · fits: needs about 30% of the 5-hour window (80% left, resets in 3h); weekly 4% of 90% · It works in another repository, so it would build this in that repository's worktree. A new agent starts in this one. · b · idle · different repo · activity unknown · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)"
}
@@ -296,7 +250,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "a"
+ "account": "a",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -304,29 +260,6 @@
"kind": "new",
"machineId": "a",
"engine": "claude",
- "model": "opus",
- "effort": "high",
- "quality": 3,
- "cost": 3,
- "title": "New agent · Claude opus high · a",
- "label": "New agent · Claude opus high · strength 3, cost 3 · fits: needs about 45% of the 5-hour window (80% left, resets in 3h); weekly 6% of 90% · a · new · quota 5-hour 80% left (resets in 3h), weekly 90% left (resets in 5 days)",
- "fit": {
- "status": "fits",
- "coverage": 1.78,
- "effectiveCost": 3,
- "expiring": 0,
- "spend": {
- "5-hour": 45,
- "weekly": 6
- },
- "account": "a"
- }
- },
- {
- "id": "c2",
- "kind": "new",
- "machineId": "a",
- "engine": "claude",
"model": "sonnet",
"effort": "medium",
"quality": 2,
@@ -342,11 +275,13 @@
"5-hour": 30,
"weekly": 4
},
- "account": "a"
+ "account": "a",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
- "id": "c3",
+ "id": "c2",
"kind": "new",
"machineId": "b",
"engine": "claude",
@@ -365,11 +300,13 @@
"5-hour": 30,
"weekly": 4
},
- "account": "b"
+ "account": "b",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
- "id": "c4",
+ "id": "c3",
"kind": "member",
"agentId": "m2",
"machineId": "b",
@@ -389,7 +326,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "b"
+ "account": "b",
+ "left": 90,
+ "resetsAt": 1432000000
}
}
],
@@ -582,7 +521,9 @@
"5-hour": 75,
"weekly": 12
},
- "account": "A"
+ "account": "A",
+ "left": 50,
+ "resetsAt": 1432000000
}
},
{
@@ -605,7 +546,9 @@
"5-hour": 50,
"weekly": 8
},
- "account": "B"
+ "account": "B",
+ "left": 60,
+ "resetsAt": 1259200000
}
},
{
@@ -628,7 +571,9 @@
"5-hour": 50,
"weekly": 8
},
- "account": "C"
+ "account": "C",
+ "left": 90,
+ "resetsAt": 1518400000
}
}
],
@@ -817,7 +762,9 @@
"5-hour": 15,
"weekly": 1.5
},
- "account": "A"
+ "account": "A",
+ "left": 10,
+ "resetsAt": 1518400000
}
},
{
@@ -840,7 +787,9 @@
"5-hour": 15,
"weekly": 1.5
},
- "account": "B"
+ "account": "B",
+ "left": 80,
+ "resetsAt": 1172800000
}
},
{
@@ -863,7 +812,9 @@
"5-hour": 10,
"weekly": 1
},
- "account": "C"
+ "account": "C",
+ "left": 30,
+ "resetsAt": 1518400000
}
}
],
@@ -1010,7 +961,9 @@
"5-hour": 45,
"weekly": 6
},
- "account": "A"
+ "account": "A",
+ "left": 50,
+ "resetsAt": 1432000000
}
},
{
@@ -1033,7 +986,9 @@
"5-hour": 45,
"weekly": 6
},
- "account": "B"
+ "account": "B",
+ "left": 50,
+ "resetsAt": 1432000000
}
}
],
@@ -1223,7 +1178,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "a:codex"
+ "account": "a:codex",
+ "left": null,
+ "resetsAt": null
}
},
{
@@ -1246,7 +1203,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "b:codex"
+ "account": "b:codex",
+ "left": null,
+ "resetsAt": null
}
},
{
@@ -1269,7 +1228,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "c:codex"
+ "account": "c:codex",
+ "left": 40,
+ "resetsAt": 1007200000
}
},
{
@@ -1292,7 +1253,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "d:codex"
+ "account": "d:codex",
+ "left": 40,
+ "resetsAt": null
}
}
],
@@ -2037,7 +2000,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "acct0"
+ "account": "acct0",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2060,7 +2025,9 @@
"5-hour": 45,
"weekly": 6
},
- "account": "acct1"
+ "account": "acct1",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2083,7 +2050,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "acct2"
+ "account": "acct2",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2106,7 +2075,9 @@
"5-hour": 45,
"weekly": 6
},
- "account": "acct3"
+ "account": "acct3",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2129,7 +2100,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "acct4"
+ "account": "acct4",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2152,7 +2125,9 @@
"5-hour": 45,
"weekly": 6
},
- "account": "acct5"
+ "account": "acct5",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2175,7 +2150,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "acct6"
+ "account": "acct6",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2198,7 +2175,9 @@
"5-hour": 45,
"weekly": 6
},
- "account": "acct7"
+ "account": "acct7",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2221,7 +2200,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "acct8"
+ "account": "acct8",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2244,7 +2225,9 @@
"5-hour": 45,
"weekly": 6
},
- "account": "acct9"
+ "account": "acct9",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2267,7 +2250,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "acct10"
+ "account": "acct10",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2290,7 +2275,9 @@
"5-hour": 45,
"weekly": 6
},
- "account": "acct11"
+ "account": "acct11",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2313,7 +2300,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "acct12"
+ "account": "acct12",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2336,7 +2325,9 @@
"5-hour": 45,
"weekly": 6
},
- "account": "acct13"
+ "account": "acct13",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2359,7 +2350,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "acct14"
+ "account": "acct14",
+ "left": 90,
+ "resetsAt": 1432000000
}
}
],
@@ -2524,7 +2517,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "a"
+ "account": "a",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2547,7 +2542,9 @@
"5-hour": 30,
"weekly": 4
},
- "account": "d"
+ "account": "d",
+ "left": 90,
+ "resetsAt": 1432000000
}
}
],
@@ -2686,7 +2683,9 @@
"5-hour": 0,
"weekly": 0
},
- "account": "local:swarm-0123456789ab:kimi-k3"
+ "account": "local:swarm-0123456789ab:kimi-k3",
+ "left": null,
+ "resetsAt": null
},
"gridModel": "kimi-k3",
"gridName": "swarm-0123456789ab"
@@ -2711,7 +2710,9 @@
"5-hour": 0,
"weekly": 0
},
- "account": "local:swarm-0123456789ab:qwen3"
+ "account": "local:swarm-0123456789ab:qwen3",
+ "left": null,
+ "resetsAt": null
},
"gridModel": "qwen3",
"gridName": "swarm-0123456789ab"
@@ -2867,7 +2868,9 @@
"5-hour": 15,
"weekly": 2
},
- "account": "a"
+ "account": "a",
+ "left": 90,
+ "resetsAt": 1432000000
}
},
{
@@ -2890,7 +2893,9 @@
"5-hour": 15,
"weekly": 2
},
- "account": "c"
+ "account": "c",
+ "left": 90,
+ "resetsAt": 1432000000
}
}
],
@@ -3046,7 +3051,9 @@
"5-hour": 5,
"weekly": 0.5
},
- "account": "a"
+ "account": "a",
+ "left": 90,
+ "resetsAt": 1432000000
}
}
],
diff --git a/cli/src/superTabs/machineFit.spec.ts b/cli/src/superTabs/machineFit.spec.ts
index 7846a1c63..907f255fc 100644
--- a/cli/src/superTabs/machineFit.spec.ts
+++ b/cli/src/superTabs/machineFit.spec.ts
@@ -30,9 +30,9 @@ describe('the task says its heavy work and its CI', () => {
expect(parseAssessment({ ...base, needs: { heavy: ['build', 'e2e', 'build'], ci: { jobs: 4, macos: 2 } } }))
.toMatchObject({ needs: { tools: [], devices: [], heavy: ['build', 'e2e'], ci: { jobs: 4, macos: 2 } } })
expect(parseAssessment({ ...base, needs: { ci: { jobs: 1 } } })).toMatchObject({ needs: { ci: { jobs: 1, macos: 0 } } })
- // An empty list says nothing, and a request without either answers exactly as before.
- expect(parseAssessment({ ...base, needs: { heavy: [] } })).toEqual({ ...base, size: 'medium', needs: { tools: [], devices: [] } })
- expect(parseAssessment({ ...base, needs: {} })).toEqual({ ...base, size: 'medium', needs: { tools: [], devices: [] } })
+ // An empty list says nothing, and a request without either answers exactly as before (with no size given, `unsized`, task #3163).
+ expect(parseAssessment({ ...base, needs: { heavy: [] } })).toEqual({ ...base, size: 'medium', unsized: true, needs: { tools: [], devices: [] } })
+ expect(parseAssessment({ ...base, needs: {} })).toEqual({ ...base, size: 'medium', unsized: true, needs: { tools: [], devices: [] } })
})
it('explains what is wrong with them', () => {
const base = { difficulty: 'low', risk: 'low', why: 'x' }
diff --git a/cli/src/superTabs/projectFolder.spec.ts b/cli/src/superTabs/projectFolder.spec.ts
index dcbf4c944..da5519e9a 100644
--- a/cli/src/superTabs/projectFolder.spec.ts
+++ b/cli/src/superTabs/projectFolder.spec.ts
@@ -129,8 +129,9 @@ function hosted(answer: unknown = { github: true, token: TOKEN, repository: 'exa
})
const fetch = vi.fn(async (_cwd: string, _env: NodeJS.ProcessEnv) => true)
const revoke = vi.fn(async (_token: string) => {})
- return { ...f, row, start, backend, fetch, revoke,
- ready: (team = false) => prepareSwarmStart(f.core, row, start, { backend, team, prepare: f.prepare, fetch, revoke }) }
+ const sleep = vi.fn(async (_ms: number) => {})
+ return { ...f, row, start, backend, fetch, revoke, sleep,
+ ready: (team = false) => prepareSwarmStart(f.core, row, start, { backend, team, prepare: f.prepare, fetch, revoke, sleep }) }
}
describe('preparing another person\'s start with the Harness GitHub App', () => {
@@ -266,6 +267,31 @@ describe('preparing another person\'s start with the Harness GitHub App', () =>
await expect(f.ready()).rejects.toThrow('taken')
})
+ // 11-05: six first starts on four machines failed on one failed or stalled clone, which GitHub or the network often serves seconds later.
+ it('tries a failed or stalled first clone with the token once more, after a backoff, and never a refusal or another error', async () => {
+ for (const failure of [new ProjectFolderError('CLONE_FAILED', 'Could not clone the repository.'), new ProjectFolderError('CLONE_TIMEOUT', 'Cloning stopped.')]) {
+ const f = hosted()
+ f.prepare.mockRejectedValueOnce(failure)
+ expect(await f.ready()).toEqual({ requester: '[email protected]' })
+ expect(f.prepare).toHaveBeenCalledTimes(2)
+ expect(f.prepare.mock.calls[1]).toEqual(f.prepare.mock.calls[0])
+ expect(f.sleep).toHaveBeenCalledOnce()
+ expect(f.sleep.mock.calls[0]![0]).toBeGreaterThan(0)
+ }
+ const twice = hosted()
+ twice.prepare.mockRejectedValueOnce(new ProjectFolderError('CLONE_FAILED', 'first')).mockRejectedValueOnce(new ProjectFolderError('CLONE_FAILED', 'second: git said'))
+ await expect(twice.ready()).rejects.toThrow("could not clone the project repository with the Harness GitHub App's token: second: git said")
+ expect(twice.prepare).toHaveBeenCalledTimes(2)
+ for (const other of [new RepositoryAccessError('CLONE_FAILED', 'Could not access this repository.'), new ProjectFolderError('GIT_UNAVAILABLE', 'no git'),
+ new ProjectFolderError('PROJECT_EXISTS', 'taken'), new Error('disk full')]) {
+ const f = hosted()
+ f.prepare.mockRejectedValueOnce(other)
+ await expect(f.ready()).rejects.toThrow()
+ expect(f.prepare).toHaveBeenCalledTimes(1)
+ expect(f.sleep).not.toHaveBeenCalled()
+ }
+ })
+
// Local Team account run, 2026-10-28: the read-only token for the clone was never revoked and stayed good for its hour.
it('revokes the read-only token once the clone and the fetch are done, and when they fail', async () => {
const f = hosted()
diff --git a/cli/src/superTabs/projectFolder.ts b/cli/src/superTabs/projectFolder.ts
index 0fbfc71ca..226a2ceff 100644
--- a/cli/src/superTabs/projectFolder.ts
+++ b/cli/src/superTabs/projectFolder.ts
@@ -16,6 +16,9 @@ export interface StartGitHub { token: string; repository: string; requester: str
const NO_APP_ON_TEAM = 'This Harness server has no GitHub App, and a Harness Team account has no git login of its own, so it cannot fetch '
+ 'the project. Ask the server\'s administrator to set up the Harness GitHub App (docs/swarm-github-app.md).'
+/** How long a clone that failed or stalled waits before its one more try. */
+const CLONE_RETRY_MS = 5_000
+
/** A start this machine could not prepare yet, as the Harness server gave no answer (a timeout, a 5xx, no connection), which
* decides nothing: its host tries again on its next pass, and fails the start only once it has kept failing for as long as
* a refused start (superTabs/machines.ts). Diego's Mac, 2026-10-30: one backend timeout on the token call failed a start. */
@@ -70,7 +73,8 @@ async function revokeQuietly(token: string, revoke = revokeGitHubToken): Promise
* core/agents/launches.ts). Returns whom the work is for, for the start; null when this machine's own login is right for it.
*/
export async function prepareSwarmStart(core: CoreApi, row: Json, start: Json,
- deps: { backend: Backend; team: boolean; prepare?: typeof prepareProjectFolder; fetch?: typeof fetchStartBase; revoke?: (token: string) => Promise<void> }):
+ deps: { backend: Backend; team: boolean; prepare?: typeof prepareProjectFolder; fetch?: typeof fetchStartBase; revoke?: (token: string) => Promise<void>
+ sleep?: (ms: number) => Promise<void> }):
Promise<{ requester: string } | null> {
const request = object(start.request)
// A person's one Buddy has no project: its launch makes its folder from the checkouts already here and fetches nothing
@@ -79,7 +83,7 @@ export async function prepareSwarmStart(core: CoreApi, row: Json, start: Json,
const github = await startGitHub(core, row, start, deps)
const gitEnv = github ? swarmGitPrepareEnv(github.token) : undefined
try {
- if (object(row.machine).scope === 'swarm') await prepareSwarmProject(core, row, start, deps.prepare, gitEnv)
+ if (object(row.machine).scope === 'swarm') await prepareSwarmProject(core, row, start, deps.prepare, gitEnv, deps.sleep)
if (gitEnv && request.worktree === true && typeof request.cwd === 'string' && isAbsolute(request.cwd)) {
// The branch the start names, when it names one: a project clone has only the default branch (lib/projectFolder.ts).
await (deps.fetch ?? fetchStartBase)(resolve(request.cwd), gitEnv, ...(typeof request.branchRef === 'string' ? [request.branchRef] : []))
@@ -100,7 +104,8 @@ function sameFolder(requested: unknown, folder: unknown): boolean {
/** The owner granted a swarm workspace, not caller-selected filesystem paths.
* Prepare the queued project's repository there before reserving or launching. */
-export async function prepareSwarmProject(core: CoreApi, row: Json, start: Json, prepare = prepareProjectFolder, gitEnv?: NodeJS.ProcessEnv): Promise<void> {
+export async function prepareSwarmProject(core: CoreApi, row: Json, start: Json, prepare = prepareProjectFolder, gitEnv?: NodeJS.ProcessEnv,
+ sleep: (ms: number) => Promise<void> = ms => new Promise(done => setTimeout(done, ms))): Promise<void> {
const pool = object(row.machine)
if (pool.scope !== 'swarm' || start.dispatched) return
const request = object(start.request)
@@ -124,8 +129,18 @@ export async function prepareSwarmProject(core: CoreApi, row: Json, start: Json,
// With the app's token: over https alone, whatever address was shared, and no other way in if it is refused.
const ssh = '[email protected]:'
const https = source.repositoryUrl.startsWith(ssh) ? `https://github.com/${source.repositoryUrl.slice(ssh.length)}` : source.repositoryUrl
- try { cwd = await prepare({ ...source, repositoryUrl: https, name: project.id }, { root: expectedRoot, gitEnv }) }
- catch (error) {
+ const name = project.id
+ const clone = () => prepare({ ...source, repositoryUrl: https, name }, { root: expectedRoot, gitEnv })
+ try {
+ // One more try after a short wait, for a failed or stalled clone only: GitHub or the network often serves it seconds
+ // later (six first starts failed on 11-05). A refusal would fail again, and prepare removes its staging between tries.
+ try { cwd = await clone() }
+ catch (first) {
+ if (!(first instanceof ProjectFolderError) || first instanceof RepositoryAccessError || !['CLONE_FAILED', 'CLONE_TIMEOUT'].includes(first.code)) throw first
+ await sleep(CLONE_RETRY_MS)
+ cwd = await clone()
+ }
+ } catch (error) {
if (!(error instanceof ProjectFolderError) || !['CLONE_FAILED', 'CLONE_TIMEOUT'].includes(error.code)) throw error
throw new ProjectFolderError(error.code, `This machine could not clone the project repository with the Harness GitHub App's token: ${error.message}`)
}
diff --git a/cli/src/superTabs/route.spec.ts b/cli/src/superTabs/route.spec.ts
index 5375b0add..2705ae73a 100644
--- a/cli/src/superTabs/route.spec.ts
+++ b/cli/src/superTabs/route.spec.ts
@@ -1,7 +1,7 @@
// cli/src/superTabs/route.spec.ts
import { afterEach, describe, expect, it, vi } from 'vitest'
import { API_BUILDERS, CHOOSE_BY_INSTRUCTIONS, CODEX_DEFAULT_NOT_OFFERED, NONE_COVERS, catalogFrom, quotaBrief, catalogRow, choose, decide, gridStrength, LOCAL_NONE, OTHER_REPOSITORY, parseAssessment, quotaOf2, recordOf, repoMatch, repositoryKey, strengthOf,
- type Assessment, type Catalog, type Commitment, type MemberFrame, type Probe, type RoutePlugin, type TaskFolder } from './route.js'
+ tierOf, type Assessment, type Catalog, type Commitment, type MemberFrame, type Probe, type RoutePlugin, type TaskFolder } from './route.js'
const object = (v: unknown) => v as Record<string, unknown>
@@ -141,16 +141,16 @@ describe('choose', () => {
], policy, a(), NOW)
if ('error' in r) throw new Error('unexpected')
expect(r).toMatchObject({ floor: 1, belowFloor: false, excluded: [] })
- // A member in another repository would build in that repository's worktree: shown last, with why (#2377).
+ // A member in another repository would build in that repository's worktree: shown last, with why (#2377). Opus is the
+ // strong tier's model: this medium task's slot on remote-1 offers Sonnet (task #3163).
expect(r.shown.map(s => s.title)).toEqual([
'New agent · Claude sonnet medium · mac',
'Multiply · Claude sonnet medium · remote-1',
- 'New agent · Claude opus high · remote-1',
'New agent · Claude sonnet medium · remote-1',
'Elsewhere · Claude sonnet medium · remote-1',
])
- expect(r.shown.map(s => s.id)).toEqual(['c0', 'c1', 'c2', 'c3', 'c4'])
- expect(r.shown[4]!.label).toContain(OTHER_REPOSITORY)
+ expect(r.shown.map(s => s.id)).toEqual(['c0', 'c1', 'c2', 'c3'])
+ expect(r.shown[3]!.label).toContain(OTHER_REPOSITORY)
})
// Diego, 10-30: a member in another repository tied a new agent and the title decided, so Ada took the task in her own
// repository's worktree and Zed did not. Review of #2377: ranking it after a new agent was not enough, since what ranks
@@ -249,15 +249,16 @@ describe('strength, fit and effective cost', () => {
it('3. low, small: the account nearly spent for the week costs more in effect than the one with room', () => {
const A = windows([80, 4 * H], [2, 5 * D], 'A'), B = windows([60, 4 * H], [70, 5 * D], 'B')
const r = route([OPUS, SONNET, HAIKU].flatMap(row => [on(row, 'a', A), on(row, 'b', B)]), { difficulty: 'low', size: 'small' })
- expect(row(r, 'opus', 'a').fit.effectiveCost).toBeGreaterThan(row(r, 'opus', 'b').fit.effectiveCost)
+ // Small work is offered on Sonnet, not Opus (task #3163): the accounts compare the same on either.
+ expect(row(r, 'sonnet', 'a').fit.effectiveCost).toBeGreaterThan(row(r, 'sonnet', 'b').fit.effectiveCost)
// A's weekly budget is 0.4% a day; Haiku's 0.5% costs it 1 + 1 × 0.5 / 0.4.
expect(r.shown.find(s => s.model === 'haiku' && s.machineName === 'a')!.fit.effectiveCost).toBe(2.25)
})
- it('4. low, small: Opus high on the account whose 5-hour window resets in 20 minutes costs less in effect: it would otherwise go unused', () => {
+ it('4. low, small: Sonnet on the account whose 5-hour window resets in 20 minutes costs less in effect: it would otherwise go unused', () => {
const A = windows([60, 20 * M], [60, 2 * D], 'A'), B = windows([90, 4 * H], [80, 5 * D], 'B')
const r = route([OPUS, SONNET, HAIKU].flatMap(row => [on(row, 'a', A), on(row, 'b', B)]), { difficulty: 'low', size: 'small' })
- expect(row(r, 'opus', 'a').fit.expiring).toBeGreaterThan(0)
- expect(row(r, 'opus', 'a').fit.effectiveCost).toBeLessThan(row(r, 'opus', 'b').fit.effectiveCost)
+ expect(row(r, 'sonnet', 'a').fit.expiring).toBeGreaterThan(0)
+ expect(row(r, 'sonnet', 'a').fit.effectiveCost).toBeLessThan(row(r, 'sonnet', 'b').fit.effectiveCost)
})
it('5. a second high, medium route a minute after the first sees what the first one holds on its account', () => {
const probes = [on(OPUS, 'a', windows([60, 3 * H], [80, 5 * D], 'A')), on(OPUS, 'b', windows([58, 3 * H], [80, 5 * D], 'B'))]
@@ -466,7 +467,8 @@ describe('verdict and record', () => {
excluded: [], floor: 1, notes: false, pick: 'c0', via: 'order', p: null, belowFloor: false, why: v.why }
const { pick: _pick, ...unpicked } = v1
expect(recordOf(c, v, a())).toEqual({ ...unpicked, via: 'instructions', 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' } })) })
+ candidates: v1.candidates.map(x => ({ ...x, fit: { status: 'unknown', coverage: null, effectiveCost: 2, expiring: 0, spend: { '5-hour': 30, weekly: 4 }, account: 'm1:claude',
+ left: 50, resetsAt: 1000 } })) })
// The server stamps the instructions' revision; the route sends none (phase 4, decision 12).
expect(recordOf(c, v, a())).not.toHaveProperty('instructionsRevision')
// For a backend from before sizes and fit.
@@ -486,10 +488,10 @@ describe('edges', () => {
expect(parseAssessment({ difficulty: 'low', risk: 'urgent', why: 'x' })).toContain('risk')
expect(parseAssessment({ difficulty: 'low', risk: 'low', why: 7 })).toContain('why')
expect(parseAssessment({ difficulty: 'low', risk: 'low', why: 'x', needs: null }))
- .toEqual({ difficulty: 'low', risk: 'low', size: 'medium', why: 'x', needs: { tools: [], devices: [] } })
+ .toEqual({ difficulty: 'low', risk: 'low', size: 'medium', unsized: true, why: 'x', needs: { tools: [], devices: [] } })
expect(parseAssessment({ difficulty: 'low', risk: 'low', why: 'x', needs: { tools: 'git', devices: [1], cwd: 5 } })).toContain('absolute')
expect(parseAssessment({ difficulty: 'low', risk: 'low', why: 'x', needs: { devices: ['cam'], cwd: '/work' } }))
- .toEqual({ difficulty: 'low', risk: 'low', size: 'medium', why: 'x', needs: { tools: [], devices: ['cam'], cwd: '/work' } })
+ .toEqual({ difficulty: 'low', risk: 'low', size: 'medium', unsized: true, why: 'x', needs: { tools: [], devices: ['cam'], cwd: '/work' } })
})
it('keeps the tightest window whatever its order and drops an unusable reset', () => {
expect(quotaOf2({ known: true, windows: [{ usedPercent: 70, resetsAt: 1_800_000_000 }, { usedPercent: 20, resetsAt: null }] }))
@@ -988,10 +990,10 @@ describe('routing plug-ins', () => {
on('a', { model: 'haiku', effort: 'auto', quality: 1, cost: 1 }),
] }
const r = ok(choose(given, policy, a(), NOW, [], [], [], [sneaky]))
- // By machine, as without plug-ins.
- expect(r.shown.map(s => s.title)).toEqual(['New agent · Claude opus high · a', 'New agent · Claude sonnet medium · a', 'Kai · Claude opus high · k'])
+ // By machine, as without plug-ins; the added Sonnet is the model this medium task's slot on a offers (task #3163).
+ expect(r.shown.map(s => s.title)).toEqual(['New agent · Claude sonnet medium · a', 'Kai · Claude opus high · k'])
// The added Sonnet on a keeps a's note and quota reading, not its own.
- expect(r.shown[1]).toMatchObject({ notes: ['Its last task here was lost.'], quota: given[0]!.quota })
+ expect(r.shown[0]).toMatchObject({ notes: ['Its last task here was lost.'], quota: given[0]!.quota })
expect(r.excluded).toEqual([
{ title: 'New agent · Claude opus high · b', reason: 'Machine is offline.', machine: 'b' },
{ title: 'New agent · Claude sonnet medium · b', reason: 'Machine is offline.', machine: 'b' },
@@ -1022,7 +1024,8 @@ describe('routing plug-ins', () => {
on('x', { model: 'haiku', effort: 'auto', quality: 1, cost: 1 })].filter(() => probes.length > 0) }
const watch: RoutePlugin = { name: 'Watch', candidates: probes => { seen.push(probes.map(p => `${p.model} on ${p.machineId}`)); return [] } }
const r = ok(route(given, [extra, watch]))
- expect(r.shown.map(s => `${s.model} on ${s.machineName}`)).toEqual(['opus on a', 'opus on x', 'sonnet on x'])
+ // On x the slot offers Sonnet, this medium task's model, over the added Opus (task #3163).
+ expect(r.shown.map(s => `${s.model} on ${s.machineName}`)).toEqual(['opus on a', 'sonnet on x'])
expect(seen).toEqual([['opus on a', 'sonnet on x', 'opus on x', 'haiku on x']])
// A person naming a model still considers that model alone.
expect(titles(route(given, [extra], { model: 'haiku' }))).toEqual(['x'])
@@ -1073,3 +1076,141 @@ describe('routing plug-ins', () => {
expect(route([on('a', { refusals: ['Machine is offline.'] })], [broken])).toMatchObject({ error: 'NO_CANDIDATE', warnings: [expect.stringContaining('"Broken"')] })
})
})
+
+/** Task #3163 (Ken, 2026-11-05, production): each slot kept whichever candidate's title sorted first, so for small work Astra
+ * xhigh was offered 2,010 times against Sol high 67, and Opus high 2,356 against Sonnet high 127. The Routing rules call for
+ * Sonnet high or Sol high for small, low or medium work, and Opus high or Astra xhigh for big, hard, risky, security or review
+ * work. These run on the catalog's rows as served (backend superTabs/catalog.ts). */
+describe('the model the task\'s size calls for', () => {
+ const served: Catalog = { grid: { strength: 1, models: [{ model: 'kimi k3', strength: 2 }] }, models: [
+ { engine: 'claude', model: 'opus', effort: 'high', strength: 3, cost: 3, offered: true },
+ { engine: 'claude', model: 'opus', effort: 'xhigh', strength: 3, cost: 4, offered: true },
+ { engine: 'codex', model: 'gpt-6.1-sol', effort: 'high', strength: 3, cost: 2, offered: true, engineDefault: true },
+ { engine: 'codex', model: 'gpt-6-astra', effort: 'xhigh', strength: 3, cost: 5, offered: true },
+ { engine: 'claude', model: 'sonnet', effort: 'high', strength: 2, cost: 2, offered: true },
+ { engine: 'claude', model: 'haiku', effort: 'auto', strength: 1, cost: 1, offered: false },
+ ] }
+ /** Every row of the catalog as a new agent on [machine], one per engine it runs, as routeCommand.ts probes them. */
+ const rows = (machine: string, engines: Array<'claude' | 'codex'> = ['claude', 'codex']) => served.models.filter(m => engines.includes(m.engine))
+ .map(m => probe({ machineId: machine, machineName: machine, engine: m.engine, model: m.model, effort: m.effort, quality: m.strength, cost: m.cost,
+ quota: windows([80, 3 * H], [70, 4 * D], `${machine}-${m.engine}`) }))
+ const offers = (r: ReturnType<typeof choose>, kind: Probe['kind'] = 'new') => ok(r).shown.filter(s => s.kind === kind && !s.gridModel)
+ const models = (r: ReturnType<typeof choose>) => [...new Set(offers(r).map(s => `${s.engine} ${s.model} ${s.effort}`))].sort()
+ const machines = ['Gray.local', 'daniel-pc', 'Kay.local']
+
+ it('offers Sonnet high and Sol high for small, low or medium work, never Opus or Astra', () => {
+ for (const patch of [{ size: 'small', difficulty: 'low' }, { size: 'small', difficulty: 'medium', risk: 'medium' }, { size: 'medium', difficulty: 'medium' }] as const) {
+ const r = choose(machines.flatMap(m => rows(m)), served, a(patch), NOW)
+ expect(models(r), JSON.stringify(patch)).toEqual(['claude sonnet high', 'codex gpt-6.1-sol high'])
+ // Every machine keeps its row of each engine.
+ for (const m of machines) expect(offers(r).filter(s => s.machineName === m).map(s => s.engine).sort()).toEqual(['claude', 'codex'])
+ }
+ })
+ it('offers Opus high and Astra xhigh for big, hard, risky, security or review work', () => {
+ for (const patch of [{ size: 'large' }, { size: 'small', difficulty: 'high' }, { size: 'small', risk: 'high' }, { size: 'small', kind: 'security' }, { size: 'small', kind: 'review' }] as const) {
+ const r = choose(machines.flatMap(m => rows(m)), served, a({ difficulty: 'low', ...patch }), NOW)
+ // Under 12 rows the route fills with more rows of the same tier (Opus xhigh), never with Sonnet or Sol.
+ expect(models(r).filter(m => /sonnet|sol/.test(m)), JSON.stringify(patch)).toEqual([])
+ for (const m of machines) {
+ expect(offers(r).filter(s => s.machineName === m).map(s => `${s.engine} ${s.model} ${s.effort}`))
+ .toEqual(expect.arrayContaining(['claude opus high', 'codex gpt-6-astra xhigh']))
+ }
+ }
+ })
+ it('keeps both models of each slot when the task gives no size', () => {
+ const unsized = parseAssessment({ difficulty: 'low', risk: 'low', why: 'Older agent.' }) as Assessment
+ expect(unsized).toMatchObject({ size: 'medium', unsized: true })
+ // The marker is the route's own: the record sends the size as before.
+ expect(parseAssessment({ difficulty: 'low', risk: 'low', size: 'small', why: 'x' })).not.toHaveProperty('unsized')
+ const r = choose(machines.flatMap(m => rows(m)), served, unsized, NOW)
+ for (const m of machines) {
+ const here = offers(r).filter(s => s.machineName === m).map(s => `${s.engine} ${s.model} ${s.effort}`)
+ expect(here).toEqual(expect.arrayContaining(['claude opus high', 'claude sonnet high', 'codex gpt-6-astra xhigh', 'codex gpt-6.1-sol high']))
+ }
+ // An unsized task that is hard is still strong work.
+ expect(models(choose(machines.flatMap(m => rows(m)), served, { ...unsized, difficulty: 'high' }, NOW))).toEqual(['claude opus high', 'codex gpt-6-astra xhigh'])
+ })
+ // Review of #3117: the Routing rules move small work to Sonnet or Sol after a failed review, and to Opus or Astra after a
+ // second. The route counts the task's ended attempts (routeCommand.ts); one it could not read keeps both models.
+ it('offers Opus high and Astra xhigh to small work on its third attempt, and both when its attempts could not be read', () => {
+ const small = (ended: number | null) => models(choose(machines.flatMap(m => rows(m)), served, a({ size: 'small', difficulty: 'low', ended }), NOW))
+ expect(small(1)).toEqual(['claude sonnet high', 'codex gpt-6.1-sol high'])
+ expect(small(2)).toEqual(['claude opus high', 'codex gpt-6-astra xhigh'])
+ expect(small(null)).toEqual(['claude opus high', 'claude sonnet high', 'codex gpt-6-astra xhigh', 'codex gpt-6.1-sol high'])
+ expect([tierOf(a({ size: 'small', ended: 0 })), tierOf(a({ size: 'small', ended: 3 })), tierOf(a({ size: 'small', ended: null }))]).toEqual(['standard', 'strong', null])
+ })
+ it('keeps a slot whose machine offers neither model of the tier, on its first row', () => {
+ const only = served.models.filter(m => m.model === 'opus' && m.effort === 'xhigh')
+ .map(m => probe({ machineId: 'x', machineName: 'x', engine: m.engine, model: m.model, effort: m.effort, quality: m.strength, cost: m.cost }))
+ expect(offers(choose(only, served, a({ size: 'small', difficulty: 'low' }), NOW)).map(s => s.title)).toEqual(['New agent · Claude opus xhigh · x'])
+ })
+ it('prefers the idle member on the tier\'s model, reading a member\'s reported model through the catalog', () => {
+ const member = (agentId: string, model: string, effort: string) => probe({ kind: 'member', agentId, name: agentId, machineId: 'Gray.local', machineName: 'Gray.local',
+ engine: 'claude', model, effort, activity: 'idle' })
+ const members = [member('Cedar', 'claude-opus-4-7', 'high'), member('Ash', 'claude-sonnet-4-5', 'high')]
+ const small = choose([...rows('Gray.local'), ...members], served, a({ size: 'small', difficulty: 'low' }), NOW)
+ expect(offers(small, 'member').map(s => s.name)).toEqual(['Ash'])
+ const large = choose([...rows('Gray.local'), ...members], served, a({ size: 'large' }), NOW)
+ expect(offers(large, 'member').map(s => s.name)).toEqual(['Cedar'])
+ })
+ // The shape of an 11-05 route on production: 22 machines by their real names, some with Claude only, idle members on Opus,
+ // Sonnet and Astra, and a grid model on one.
+ it('over a real-shaped list, offers per model what the size calls for, on every machine', () => {
+ const names = ['2Apple-MK1-A3s-MacBook-Pro.local', 'daniel-pc', 'Darren-MacBook.local', 'Diego\'s Mac', 'Elvis-MacBook-Pro.local', 'Gray.local', 'Kay.local',
+ 'Mac 3', 'MacBook-Pro-TD.local', 'MacbookPro.local', 'MacBookPro2021.local', 'Mac-Studio.local', 'Mini-1.local', 'Mini-2.local', 'nam-mbp.local',
+ 'Phong-MacBook.local', 'remote-1', 'Tony-MacBook-Pro.local', 'tri-mac.local', 'Vinh-Air.local', 'Win-Rig', 'zeta-linux']
+ const claudeOnly = new Set(['Diego\'s Mac', 'Win-Rig'])
+ const fresh = names.flatMap(n => rows(n, claudeOnly.has(n) ? ['claude'] : ['claude', 'codex']))
+ const member = (agentId: string, machine: string, engine: 'claude' | 'codex', model: string, effort: string) =>
+ probe({ kind: 'member', agentId, name: agentId, machineId: machine, machineName: machine, engine, model, effort, activity: 'idle' })
+ const members = [member('Fir', 'daniel-pc', 'claude', 'claude-opus-4-7', 'high'), member('Cedar', 'Gray.local', 'claude', 'opus', 'medium'),
+ member('Guide', 'Gray.local', 'codex', 'gpt-6-astra', 'xhigh'), member('Rowan3', 'Elvis-MacBook-Pro.local', 'claude', 'opus', 'high'),
+ member('Elm', 'MacbookPro.local', 'claude', 'sonnet', 'high'), member('Ginkgo', 'MacBookPro2021.local', 'claude', 'opus', 'high'),
+ member('Wren', 'MacBookPro2021.local', 'claude', 'sonnet', 'high')]
+ const grid = probe({ machineId: 'Kay.local', machineName: 'Kay.local', engine: 'codex', model: 'default', effort: 'default', quality: 2, cost: 0,
+ gridModel: 'kimi-k3', gridName: 'Kimi K3', gridKind: 'local' })
+ const all = [...members, ...fresh, grid].reverse()
+ const count = (r: ReturnType<typeof choose>) => {
+ const by: Record<string, number> = {}
+ for (const s of offers(r)) by[`${s.model} ${s.effort}`] = (by[`${s.model} ${s.effort}`] ?? 0) + 1
+ return by
+ }
+ const codexMachines = names.length - claudeOnly.size
+ const small = choose(all, served, a({ size: 'small', difficulty: 'low' }), NOW)
+ expect(count(small)).toEqual({ 'sonnet high': names.length, 'gpt-6.1-sol high': codexMachines })
+ expect(ok(small).shown.length).toBeLessThanOrEqual(64)
+ // Members stay, one per machine and engine, on the tier's model where one is idle there.
+ expect(offers(small, 'member').map(s => s.name).sort()).toEqual(['Cedar', 'Elm', 'Fir', 'Guide', 'Rowan3', 'Wren'])
+ expect(ok(small).shown.filter(s => s.gridModel).map(s => s.machineName)).toEqual(['Kay.local'])
+ const big = choose(all, served, a({ size: 'large', difficulty: 'high' }), NOW)
+ expect(count(big)).toEqual({ 'opus high': names.length, 'gpt-6-astra xhigh': codexMachines })
+ expect(offers(big, 'member').map(s => s.name).sort()).toEqual(['Cedar', 'Elm', 'Fir', 'Ginkgo', 'Guide', 'Rowan3'])
+ })
+})
+
+/** Task #3163: since the record without a pick (#3010) only each candidate's account and spend were kept, so 3,905 of 3,915
+ * Codex candidates on production had no fit status, and quota at route time could not be measured. */
+describe('each candidate\'s quota in the record', () => {
+ const c = () => ok(choose([probe({ machineId: 'a', machineName: 'a', quota: windows([60, 2 * H], [42, 3 * D], 'A') }),
+ probe({ machineId: 'b', machineName: 'b', quota: { known: false, leftPercent: null, resetsAt: null } }),
+ probe({ machineId: 'c', machineName: 'c', quota: { known: true, leftPercent: 30, resetsAt: NOW + D } })], policy, a(), NOW))
+ const fits = (record: Record<string, unknown>) => (record.candidates as Array<{ fit?: Record<string, unknown> }>).map(x => x.fit)
+ it('records each candidate\'s fit status, weekly % left and reset', () => {
+ const choice = c()
+ expect(fits(recordOf(choice, decide(choice), a()))).toEqual([
+ expect.objectContaining({ status: 'fits', left: 42, resetsAt: NOW + 3 * D }),
+ expect.objectContaining({ status: 'unknown', left: null, resetsAt: null }),
+ // A reading with no windows named: its tightest, as quotaBrief reads it.
+ expect.objectContaining({ left: 30, resetsAt: NOW + D }),
+ ])
+ })
+ it('leaves them out for a backend from before them, which refuses them', () => {
+ const choice = c(), v = decide(choice)
+ const unquoted = recordOf(choice, v, a(), 'unquoted')
+ expect(unquoted).not.toHaveProperty('pick')
+ expect(unquoted.via).toBe('instructions')
+ for (const fit of fits(unquoted)) expect(Object.keys(fit!)).toEqual(['status', 'coverage', 'effectiveCost', 'expiring', 'spend', 'account'])
+ for (const fit of fits(recordOf(choice, v, a(), 'picked'))) expect(fit).not.toHaveProperty('left')
+ for (const fit of fits(recordOf(choice, v, a(), 'unkinded'))) expect(fit).not.toHaveProperty('resetsAt')
+ })
+})
diff --git a/cli/src/superTabs/route.ts b/cli/src/superTabs/route.ts
index 55c93c449..c21e70101 100644
--- a/cli/src/superTabs/route.ts
+++ b/cli/src/superTabs/route.ts
@@ -23,7 +23,11 @@ export type Size = 'small' | 'medium' | 'large'
export type HeavyWork = 'build' | 'e2e'
/** `access`: what the work needs to reach, by the names machines list it under (backend superTabs/machineAccess.ts, task #3047). */
export interface Needs { tools: string[]; devices: string[]; access?: string[]; cwd?: string; heavy?: HeavyWork[]; ci?: { jobs: number; macos: number } }
-export interface Assessment { difficulty: Level; risk: Level; size: Size; why: string; kind?: string; local?: boolean; model?: string; needs: Needs }
+/** `unsized`: the agent gave no size (one from before sizes), so the route keeps both models of each slot ([tierOf]). `ended`:
+ * how many of the task's attempts ended, as the route read them (routeCommand.ts endedAttempts), null when it could not. Both
+ * are the route's own: the record sends neither. */
+export interface Assessment { difficulty: Level; risk: Level; size: Size; why: string; kind?: string; local?: boolean; model?: string; needs: Needs; unsized?: true
+ ended?: number | null }
/** A model of the reviewed catalog (backend superTabs/catalog.ts): how strong it is, what it costs, and whether it is offered
* when nobody names it. */
export interface CatalogModel { engine: 'claude' | 'codex'; model: string; effort: string; strength: number; cost: number; offered: boolean; engineDefault?: true; note?: string }
@@ -254,7 +258,8 @@ export function parseAssessment(value: unknown): Assessment | string {
if (ci && (!count(ci.jobs, 100) || (ci.jobs as number) < 1 || (ci.macos !== undefined && !count(ci.macos, ci.jobs as number)))) {
return 'Set needs.ci to the CI jobs the work starts, as {"jobs": 1 to 100, "macos": how many of them run on macOS}.'
}
- return { difficulty: v.difficulty as Level, risk: v.risk as Level, size: size as Size, why, ...(v.kind ? { kind: v.kind as string } : {}),
+ return { difficulty: v.difficulty as Level, risk: v.risk as Level, size: size as Size, why, ...(v.size === undefined ? { unsized: true as const } : {}),
+ ...(v.kind ? { kind: v.kind as string } : {}),
...(v.local === true ? { local: true } : {}), ...(typeof v.model === 'string' ? { model: v.model.trim() } : {}),
needs: { tools: list(needs.tools), devices: list(needs.devices), ...(access.length ? { access } : {}), ...(cwd ? { cwd } : {}),
...(Array.isArray(heavy) && heavy.length ? { heavy: [...new Set(heavy as HeavyWork[])] } : {}),
@@ -502,13 +507,55 @@ function compare(x: Probe, y: Probe): number {
* between (an account, then whether to reuse an agent on it). */
export const slotOf = (p: Pick<Probe, 'machineId' | 'engine' | 'gridModel' | 'kind'>) => `${p.machineId}\0${p.gridModel ? 'grid' : p.engine}\0${p.kind}`
-/** The rows shown: the first new agent and the first member of every engine on every machine in the neutral order, up to
- * [RECORD_MAX], then the rest up to 12, all in that order. The agent choosing picks between accounts by the project's order;
- * one row a machine, cut at 12, hid a Claude account with 99% left behind its machine's used-up Codex (Ken, 2026-11-03). */
-function withEveryAccount<T extends Pick<Probe, 'machineId' | 'engine' | 'gridModel' | 'kind'>>(ranked: T[]): T[] {
- const keep = new Set<T>(), seen = new Set<string>()
- for (const p of ranked) if (!seen.has(slotOf(p)) && keep.size < RECORD_MAX) { seen.add(slotOf(p)); keep.add(p) }
- for (const p of ranked) if (keep.size < MAX_SHOWN) keep.add(p)
+/** The work a slot offers a model for, by the project's Routing rules (Models): `strong` for big, hard or risky work, security
+ * or a review, and for any work whose second attempt ended (small work steps up to Opus or Astra after a second failed
+ * review); `standard` for small, low or medium work; null, both, for a task with no size or whose attempts could not be read
+ * that nothing makes strong. */
+export type Tier = 'standard' | 'strong'
+export function tierOf(a: Assessment): Tier | null {
+ if (a.size === 'large' || a.difficulty === 'high' || a.risk === 'high' || /(^|-)(security|review)(-|$)/.test(a.kind ?? '')
+ || (a.ended ?? 0) >= 2) return 'strong'
+ return a.unsized || a.ended === null ? null : 'standard'
+}
+/** Each tier's model on each engine, as the Routing rules name them. */
+const TIER_MODELS: Record<Tier, Record<CatalogModel['engine'], { model: string; effort: string }>> = {
+ standard: { claude: { model: 'sonnet', effort: 'high' }, codex: { model: 'gpt-6.1-sol', effort: 'high' } },
+ strong: { claude: { model: 'opus', effort: 'high' }, codex: { model: 'gpt-6-astra', effort: 'xhigh' } },
+}
+const TIERS = Object.keys(TIER_MODELS) as Tier[]
+/** The tier whose model a candidate runs, at any effort: a member's reported model read through the catalog ([catalogRow]),
+ * so `claude-opus-4-7` is Opus. Null for a grid model or a model no tier names. */
+function modelTier(p: Probe, catalog: Catalog): Tier | null {
+ if (p.gridModel) return null
+ const model = p.kind === 'member' ? catalogRow(catalog, p.engine, p.model, p.effort)?.model ?? p.model : p.model
+ return TIERS.find(t => TIER_MODELS[t][p.engine].model === model) ?? null
+}
+/** How well a candidate fits [tier]: 0 on the tier's model and effort, 1 on neither tier's model or the tier's at another
+ * effort, 2 on the other tier's model. */
+function fitRank(p: Probe, catalog: Catalog, tier: Tier): 0 | 1 | 2 {
+ const runs = modelTier(p, catalog)
+ if (runs === null) return 1
+ if (runs !== tier) return 2
+ return p.effort === TIER_MODELS[tier][p.engine].effort ? 0 : 1
+}
+
+/** The rows shown: for every engine on every machine, as a new agent and as an idle member, the candidate that fits the task's
+ * tier best ([fitRank]), ties by the neutral order, up to [RECORD_MAX]; then more up to 12, none fitting worse than its slot's.
+ * With no tier, each slot keeps its first row of each tier's model, so both are offered. All come in the neutral order. The
+ * agent choosing picks between accounts by the project's order; one row a machine, cut at 12, hid a Claude account with 99%
+ * left behind its machine's used-up Codex (Ken, 2026-11-03). The first row of a slot by title offered Opus and Astra for
+ * small work 4,366 times against Sonnet and Sol 194 (Ken, 2026-11-05, task #3163). */
+function withEveryAccount<T extends Probe>(ranked: T[], catalog: Catalog, a: Assessment): T[] {
+ const tier = tierOf(a)
+ const rank = (p: T) => tier ? fitRank(p, catalog, tier) : 0
+ const slot = (p: T) => tier ? slotOf(p) : `${slotOf(p)}\0${modelTier(p, catalog) ?? ''}`
+ const best = new Map<string, T>()
+ for (const p of ranked) {
+ const held = best.get(slot(p))
+ if (!held ? best.size < RECORD_MAX : rank(p) < rank(held)) best.set(slot(p), p)
+ }
+ const keep = new Set<T>(best.values())
+ for (const p of ranked) if (keep.size < MAX_SHOWN && rank(p) <= rank(best.get(slot(p))!)) keep.add(p)
return ranked.filter(p => keep.has(p))
}
@@ -522,15 +569,21 @@ export function machineBrief(room: MachineRoom): string {
return [...slots, memory, ...disk].join(' · ')
}
+/** A quota's weekly window, the one the project's order compares: its percent left and reset, or a reading with no windows
+ * named as one; null left when it was not read. */
+function weekly(q: Quota): { left: number | null; resetsAt: number | null } {
+ const week = q.windows?.find(w => w.name === 'weekly')
+ const left = !q.known ? null : week ? week.leftPercent : q.windows?.length ? null : q.leftPercent
+ return { left, resetsAt: week ? week.resetsAt : q.resetsAt }
+}
+
/** What the agent choosing reads of a row's quota: its fit and its weekly window, the one the project's order compares. */
export function quotaBrief(p: Pick<Probe, 'quota' | 'gridModel'> & { fit: Pick<Fit, 'status'> }, now: number): string {
if (p.gridModel) return 'local model, no subscription'
if (p.quota.metered) return 'metered'
- const week = p.quota.windows?.find(w => w.name === 'weekly')
- const left = week ? week.leftPercent : p.quota.windows?.length ? null : p.quota.leftPercent
- const resetsAt = week ? week.resetsAt : p.quota.resetsAt
+ const { left, resetsAt } = weekly(p.quota)
// Why it is unknown says what would make it known (River, 2026-11-03): a Team account's reading its owner's machine relays.
- if (!p.quota.known || left === null) return `${p.fit.status}: ${p.quota.why ? cut(p.quota.why, 200) : 'weekly unknown'}`
+ if (left === null) return `${p.fit.status}: ${p.quota.why ? cut(p.quota.why, 200) : 'weekly unknown'}`
return `${p.fit.status}: weekly ${Math.round(left)}% left${resetsAt === null ? '' : `, resets in ${weeklyResetsIn(resetsAt, now)}`}`
}
@@ -600,7 +653,7 @@ export function choose(given: Probe[], catalog: Catalog, a: Assessment, now: num
return [{ ...p, notes: [...p.notes, ...reasons] }]
}).sort(compare)
if (!listed.length) return { error: 'NO_CANDIDATE', excluded, ...warned() }
- const shown = withEveryAccount(listed).map(({ tight, text, ...p }, i) => ({ ...p, id: `c${i}`, title: titleOf(p), label: labelOf({ ...p, tight, text }, now) }))
+ const shown = withEveryAccount(listed, catalog, a).map(({ tight, text, ...p }, i) => ({ ...p, id: `c${i}`, title: titleOf(p), label: labelOf({ ...p, tight, text }, now) }))
// With nothing first, only one thing is worth saying of quota beside each row's fit: that none of them covers the task.
const none = listed.every(p => p.fit.status === 'short')
return { shown, excluded, floor: 1, belowFloor: false, ...(none ? { short: NONE_COVERS } : {}),
@@ -618,23 +671,25 @@ export function decide(choice: Choice): Verdict {
: { via: 'instructions', p: null, why: choice.adjusted ? `${CHOOSE_BY_INSTRUCTIONS} Plug-ins' findings are in each candidate's notes.` : CHOOSE_BY_INSTRUCTIONS }
}
-/** The record in the shape a backend takes: `current` with the job's kind (what attempts are compared by, backend costs/read.ts)
- * and no pick (task #2901); `picked` for a backend from before that, which takes a record only with a pick, so `c0` stands in
- * for one by the old `order`; `unkinded` for a backend from before kinds too, and `v1` without size and fit as well, for one
- * from before phase 1. Each refuses the newer fields with its strict schema. There is no floor and no policy notes: `floor` 1,
+/** The record in the shape a backend takes: `current` with the job's kind (what attempts are compared by, backend costs/read.ts),
+ * no pick (task #2901) and each candidate's weekly % left and reset in its fit (task #3163: without them quota at route time
+ * could not be measured); `unquoted` the same without them, for a backend from before them; `picked` for a backend from before
+ * task #2901, which takes a record only with a pick, so `c0` stands in for one by the old `order`; `unkinded` for a backend
+ * from before kinds too, and `v1` without size and fit as well, for one from before phase 1. Each refuses the newer fields with its strict schema. There is no floor and no policy notes: `floor` 1,
* `belowFloor` and `notes` false. The server stamps the instructions' revision the decision relied on (phase 4, decision 12). */
-export type RecordShape = 'current' | 'picked' | 'unkinded' | 'v1'
+export type RecordShape = 'current' | 'unquoted' | 'picked' | 'unkinded' | 'v1'
export function recordOf(choice: Choice, verdict: Verdict, a: Assessment, shape: RecordShape = 'current'): Record<string, unknown> {
- const v1 = shape === 'v1', kinded = shape === 'current' || shape === 'picked'
+ const v1 = shape === 'v1', kinded = shape !== 'unkinded' && !v1, pickless = shape === 'current' || shape === 'unquoted'
+ const fitOf = (s: Shown) => shape === 'current' ? { ...s.fit, ...weekly(s.quota) } : s.fit
return {
assessment: { difficulty: a.difficulty, risk: a.risk, why: a.why, ...(v1 ? {} : { size: a.size }), ...(kinded && a.kind ? { kind: a.kind } : {}),
...(kinded && a.local ? { local: true } : {}), ...(kinded && a.model ? { model: a.model } : {}) },
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 }),
+ engine: s.engine, model: s.model, effort: s.effort, quality: s.quality, cost: s.cost, title: s.title, label: s.label, ...(v1 ? {} : { fit: fitOf(s) }),
...(s.gridModel && s.gridName ? { gridModel: s.gridModel, gridName: s.gridName } : {}) })),
excluded: choice.excluded.slice(0, 200).map(e => ({ title: e.title, reason: cut(e.reason, 500) })),
floor: 1, notes: false,
- ...(shape === 'current' ? { via: verdict.via } : { pick: choice.shown[0]!.id, via: verdict.via === 'only' ? 'only' : 'order' }),
+ ...(pickless ? { via: verdict.via } : { pick: choice.shown[0]!.id, via: verdict.via === 'only' ? 'only' : 'order' }),
p: verdict.p, belowFloor: false, why: cut(verdict.why, 300),
}
}
diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.ts
index a3584e0fb..6608bbc1e 100644
--- a/cli/src/superTabs/routeCommand.spec.ts
+++ b/cli/src/superTabs/routeCommand.spec.ts
@@ -710,14 +710,45 @@ describe('routeTask', () => {
expect((await routeWith(queued)).every(candidate => candidate.fit.status === 'short')).toBe(true)
expect((await routeWith({ ...queued, outcome: 'done' })).some(candidate => candidate.fit.status === 'fits')).toBe(true)
})
+ // Task #3163: each candidate's weekly % left and reset go with its fit; a backend from before them refuses them, and the
+ // decision is then recorded without them, still with no pick, before any older shape is tried.
+ it('records each candidate\'s quota, and without it for a backend that refuses it, still with no pick', async () => {
+ const s = scoped(), base = s.getMockImplementation()!
+ s.mockImplementation(async payload => payload.action === 'command' && JSON.stringify(payload.command).includes('"left"')
+ ? { error: 'VALIDATION_ERROR', detail: 'decision.candidates.0.fit: Unrecognized key: "left"', status: 400 } : base(payload))
+ expect(await routeTask(input, s, where as never, opener(), () => 'op')).toMatchObject({ ok: true, routeDecisionId: 'd1' })
+ const [quoted, unquoted, ...rest] = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0])
+ expect(rest).toEqual([])
+ expect(quoted.command.decision.candidates[0].fit).toHaveProperty('left')
+ expect(quoted.command.decision.candidates[0].fit).toHaveProperty('resetsAt')
+ expect(unquoted.operationId).toBe(quoted.operationId)
+ expect(unquoted.command.decision).not.toHaveProperty('pick')
+ expect(unquoted.command.decision.candidates[0].fit).not.toHaveProperty('left')
+ expect(unquoted.command.decision.candidates[0].fit).toHaveProperty('status')
+ })
+ // Review of #3117: small work steps up to Opus or Astra after its second failed attempt (Routing, Models). The route counts
+ // the task's ended attempts from the history it reads; when that read fails it keeps both models.
+ it('offers Opus to a small task once two of its attempts ended, and both models when its attempts cannot be read', async () => {
+ const small = { ...input, assessment: { ...input.assessment, size: 'small' } }
+ const offered = async (history: Answer) => {
+ const answer = await routeTask(small, scoped({ history }), where as never, opener(), () => 'op')
+ return [...new Set((answer.candidates as Array<{ kind: string; engine: string; model: string }>).filter(c => c.kind === 'new' && c.engine === 'claude').map(c => c.model))].sort()
+ }
+ const ended = (n: number) => Array.from({ length: n }, (_, i) => ({ id: `as-${i}`, agentId: `gone-${i}`, status: 'stopped', result: 'Review failed.' }))
+ expect(await offered({ ok: true, value: { decisions: [], attempts: ended(1) } })).toEqual(['sonnet'])
+ expect(await offered({ ok: true, value: { decisions: [], attempts: ended(2) } })).toEqual(['opus'])
+ expect(await offered({ error: 'BACKEND_UNAVAILABLE' })).toEqual(['opus', 'sonnet'])
+ })
it('records again in the shape an older backend knows when it refuses the new fields as invalid', async () => {
const s = scoped(), base = s.getMockImplementation()!
s.mockImplementation(async payload => payload.action === 'command' && JSON.stringify(payload.command).includes('"fit"')
? { error: 'VALIDATION_ERROR', detail: 'decision.candidates.0: Unrecognized key: "fit"', status: 400 } : base(payload))
expect(await routeTask(input, s, where as never, opener(), () => 'op')).toMatchObject({ ok: true, routeDecisionId: 'd1' })
- // With no pick, then with c0 standing in for one (task #2901), then in the shape from before phase 1.
- const [current, phase1, v1] = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0])
+ // With no pick, then without the candidates' quota (task #3163), then with c0 standing in for one (task #2901), then in the
+ // shape from before phase 1.
+ const [current, unquoted, phase1, v1] = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0])
expect(current.command.decision).not.toHaveProperty('pick')
+ expect(unquoted.command.decision).not.toHaveProperty('pick')
expect(phase1.command.decision).toMatchObject({ pick: 'c0', assessment: { size: 'medium' } })
expect(phase1.command.decision.candidates[0]).toHaveProperty('fit')
expect(v1.operationId).toBe(phase1.operationId)
@@ -742,15 +773,16 @@ describe('routeTask', () => {
const beforeKinds = refusing(['kind":"docs'])
expect(await routeTask(kinded, beforeKinds, where as never, opener(), () => 'op')).toMatchObject({ ok: true, routeDecisionId: 'd1' })
const kind = ['difficulty', 'risk', 'why', 'size', 'kind']
- // Each refusal of the record with no pick tries it once more with c0 as the pick, the shape a backend from before task #2901 takes.
- expect(commands(beforeKinds).map(a => Object.keys(a))).toEqual([kind, kind, ['difficulty', 'risk', 'why', 'size']])
+ // Each refusal of the record with no pick tries it without the candidates' quota (task #3163), then with c0 as the pick, the
+ // shape a backend from before task #2901 takes.
+ expect(commands(beforeKinds).map(a => Object.keys(a))).toEqual([kind, kind, 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([kind, kind, ['difficulty', 'risk', 'why', 'size'], ['difficulty', 'risk', 'why']])
+ expect(commands(beforePhase1).map(a => Object.keys(a))).toEqual([kind, kind, 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(3)
+ expect(commands(plain)).toHaveLength(4)
})
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())
@@ -899,11 +931,13 @@ describe('route answers with no pick (task #2901)', () => {
s.mockImplementation(async payload => payload.action === 'command' && !('pick' in payload.command.decision)
? { error: 'VALIDATION_ERROR', detail: 'decision.pick: Required', status: 400 } : base(payload))
expect(await routeTask(input, s, where as never, both(), () => 'op')).toMatchObject({ ok: true, routeDecisionId: 'd1', via: 'instructions' })
- const [current, picked] = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0])
+ const [current, unquoted, picked] = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0])
expect(current.command.decision).not.toHaveProperty('pick')
+ expect(unquoted.command.decision).not.toHaveProperty('pick')
expect(picked.command.decision).toMatchObject({ pick: 'c0', via: 'order' })
expect(picked.operationId).toBe(current.operationId)
- expect(picked.command.decision.candidates).toEqual(current.command.decision.candidates)
+ // The candidates as the record without their quota sent them (task #3163).
+ expect(picked.command.decision.candidates).toEqual(unquoted.command.decision.candidates)
})
})
@@ -1567,8 +1601,10 @@ describe('routing contributed capacity', () => {
const answer = await routeTask(input, s as never, where, opener())
expect(answer).toMatchObject({ ok: true, routeDecisionId: 'd1' })
const sent = s.mock.calls.filter(c => c[0].action === 'command').map(c => c[0].command.decision.candidates.length)
- // With no pick, then with c0 as the pick (a backend from before task #2901), then the first 12 of those.
- expect(sent).toEqual([16, 16, 12])
+ // With no pick, then without the candidates' quota, then with c0 as the pick (a backend from before task #2901), then the
+ // first 12 of those. The task gives no size, so each machine's Claude keeps both Opus and Sonnet (task #3163): 8 machines,
+ // 3 rows each.
+ expect(sent).toEqual([24, 24, 24, 12])
const recordedIds = new Set(s.mock.calls.filter(c => c[0].action === 'command').at(-1)![0].command.decision.candidates.map((c: { id: string }) => c.id))
for (const row of answer.candidates as Array<{ id: string }>) expect(recordedIds.has(row.id)).toBe(true)
})
diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.ts
index 2797e0607..5c3164b5f 100644
--- a/cli/src/superTabs/routeCommand.ts
+++ b/cli/src/superTabs/routeCommand.ts
@@ -291,6 +291,15 @@ function endedWork(conversations: Json[], decisions: Json[] | null, attempts: Js
}
return ended
}
+/** How many of the task's attempts ended: its earlier assignments the route read and its own last one, once each; null when its
+ * attempts could not be read. The route steps small work up after the second (route.ts tierOf). */
+function endedAttempts(group: Json, attempts: Json[] | null): number | null {
+ if (!attempts) return null
+ const ended = new Set(attempts.filter(a => typeof a.id === 'string' && !active(a)).map(a => a.id))
+ const current = object(group.assignment)
+ if (current.id && !active(current)) ended.add(current.id)
+ return ended.size
+}
/** The fields of a frame that say what the agent works on; an absent or malformed one says nothing. */
function frameOf(frame: Json): MemberFrame {
const project = object(frame.project), updatedAt = Date.parse(String(frame.updatedAt))
@@ -487,7 +496,7 @@ export async function routeTask(input: { tabId: string; conversationId: string;
// A model a host now offline served is left out with that reason, and a person naming it gets no stand-in (route.ts choose).
const offline = offlineModels(state)
const now = Date.now()
- const choice = choose(probes, catalog, assessment, now, working, heldLocalModels(state), offline, made.plugins)
+ const choice = choose(probes, catalog, { ...assessment, ended: endedAttempts(group, attempts) }, now, working, heldLocalModels(state), offline, made.plugins)
const skipped = [...made.warnings, ...(choice.warnings ?? [])]
choice.excluded.push(...offline, ...(catalog.models.length ? [] : [{ title: 'New agents', reason: CATALOG_UNREADABLE }]))
// The task stays in the agent's queue rather than going where it cannot be done.
@@ -504,6 +513,8 @@ export async function routeTask(input: { tabId: string; conversationId: string;
const record = (shape: RecordShape) => scoped({ action: 'command', operationId,
command: { type: 'route.record', conversationId: input.conversationId, decision: recordOf({ ...choice, shown: offered }, verdict, assessment, shape) } })
let recorded = await record('current')
+ // A backend from before task #3163 refuses each candidate's weekly % left and reset: the same decision without them.
+ if (recorded.error === 'VALIDATION_ERROR') recorded = await record('unquoted')
// A backend from before task #2901 takes a record only with a pick: c0 stands in for one, so its decision log and the starts
// linked to it still work (route.ts recordOf).
if (recorded.error === 'VALIDATION_ERROR') recorded = await record('picked')
diff --git a/desktop/README.md b/desktop/README.md
index 7013793cb..64cdc136c 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -241,6 +241,23 @@ Offline and shared harnesses expose their state without offering process control
Errors remain beside the affected row, and an uncertain resume checks its original
receipt rather than starting the process twice.
+## Speed marks
+
+Desktop writes `speed` lines to its app log (`~/.harness/logs/app-YYYYMMDD.log`): launch steps in
+milliseconds since the app started (ending at `first_chat_painted`), each first-page and scroll-up
+message read of a chat (rows, request time, total time), and each picture shown in a chat (bytes and
+fetch time, or a failure). A line holds no name, path, address or message text. To measure a build:
+open the app, open a large chat and scroll back through it, open an image-heavy chat, then run
+
+```bash
+dart run tool/speed_report.dart # today's and yesterday's logs, or pass log files
+```
+
+It prints the table and names the three slowest launch steps and message reads. The clock starts when
+Dart's `main` runs, so the engine's own start before it is not counted; compare with the process start
+time (`ps -o lstart= -p PID`) when that matters. The launch table counts each step from the one before it as logged; steps that run side by side (the daemon check and the saved tabs) show a gap, not a duration of their own. Keep the "before" table with each speed task and run
+the same steps for its "after".
+
## Open media from agent output
Hold **⌘ and click** on macOS, or **Ctrl and click** on Linux, to open an
diff --git a/desktop/lib/app_shell.dart b/desktop/lib/app_shell.dart
index 49a7ec509..313607316 100644
--- a/desktop/lib/app_shell.dart
+++ b/desktop/lib/app_shell.dart
@@ -3,6 +3,7 @@ import 'core/app_version.dart';
import 'dart:async';
import 'measurement/product_runtime_health.dart';
+import 'measurement/speed_marks.dart';
import 'dart:ui' show AppExitResponse;
@@ -85,6 +86,7 @@ Future<void> startHarness({
/// [TerminalTransportPlugin]); the desktop passes none.
TerminalTransportPluginFactory? transportPlugins,
}) async {
+ speedMarks.start();
if (!kIsWeb) ProductRuntimeHealth.launched();
// Share links and OAuth own the browser URL. Flutter's default hash routing would
// erase the share's pinned identity on the first navigation or window resize.
@@ -101,10 +103,12 @@ Future<void> startHarness({
// Keyboard configuration has its own file and watchers. It can load beside
// the appearance, but both must be ready before the window becomes usable.
await Future.wait([loadPersistedSettings(), keymap.start()]);
+ speedMarks.launch('settings loaded');
// Match macOS repaints the app when the computer's own setting flips.
appearancePrefsStore.followSystemBrightness();
// Apply the saved palette to native chrome as well as the Flutter theme.
await configureDesktopWindow(palette: appearancePrefsStore.value.palette);
+ speedMarks.launch('window configured');
runApp(
ProviderScope(
child: HarnessApp(
diff --git a/desktop/lib/main.dart b/desktop/lib/main.dart
index 68216a578..e92ac7968 100644
--- a/desktop/lib/main.dart
+++ b/desktop/lib/main.dart
@@ -5,6 +5,7 @@ import 'package:flutter/widgets.dart';
import 'app_shell.dart';
import 'core/connected_semantics.dart';
import 'core/native_webview_runtime.dart';
+import 'measurement/speed_marks.dart';
import 'ws/ws_conn.dart' show rememberAppVersionForSockets;
import 'update/started_marker.dart';
import 'desktop_workspace.dart'
@@ -27,6 +28,11 @@ Future<void> main() async {
frame: appFrame,
transportPlugins: terminalTransportPlugins,
);
+ unawaited(
+ WidgetsBinding.instance.waitUntilFirstFrameRasterized.then(
+ (_) => speedMarks.launch('first frame'),
+ ),
+ );
unawaited(
markStartedAfterFirstFrame(
firstFrame: WidgetsBinding.instance.waitUntilFirstFrameRasterized,
diff --git a/desktop/lib/measurement/speed_marks.dart b/desktop/lib/measurement/speed_marks.dart
new file mode 100644
index 000000000..4aef12cb9
--- /dev/null
+++ b/desktop/lib/measurement/speed_marks.dart
@@ -0,0 +1,131 @@
+import 'package:flutter/foundation.dart' show visibleForTesting;
+
+import '../logging/app_log.dart';
+
+/// Where Desktop's speed is read (task #3176): how long opening the app takes
+/// to reach a painted chat, how long a large chat takes to load and page
+/// back, and what each picture costs. One line per mark goes to the app log
+/// (`~/.harness/logs/app-YYYYMMDD.log`, category `speed`) and `speed_report.dart`
+/// turns those lines into a table.
+///
+/// A line carries a step name from a fixed vocabulary, a kind, counts,
+/// milliseconds and bytes — never a name, id, path or address — and nothing
+/// here can throw into the code it observes.
+class SpeedMarks {
+ SpeedMarks({
+ void Function(String line)? sink,
+ Duration Function()? elapsed,
+ AppLog Function()? log,
+ }) : // A private field cannot be a named parameter.
+ // ignore: prefer_initializing_formals
+ _sink = sink,
+ _log = log ?? _installedLog,
+ _injected = elapsed;
+
+ static AppLog _installedLog() => appLog;
+
+ /// Most lines held while the real log is not installed yet: `main` starts
+ /// the marks before `installFileLogs()`, and a launch has a dozen.
+ static const _heldMost = 64;
+
+ final void Function(String line)? _sink;
+ final AppLog Function() _log;
+ final _held = <String>[];
+ // A test reads its own clock; the app reads [_watch].
+ final Duration Function()? _injected;
+ final _watch = Stopwatch();
+ final _steps = <String>{};
+
+ /// Marks the launch at zero. Called once, first thing in [startHarness].
+ void start() {
+ if (!_watch.isRunning) _watch.start();
+ _begin();
+ }
+
+ /// Begins the launch steps again from zero. The app starts once per process,
+ /// so only tests call this.
+ @visibleForTesting
+ void restart() {
+ _watch
+ ..reset()
+ ..start();
+ _begin();
+ }
+
+ void _begin() {
+ _steps
+ ..clear()
+ ..add('started');
+ _write('launch step=started ms=0');
+ }
+
+ /// A launch step reached, once, in milliseconds since [start].
+ void launch(String step) {
+ final name = _clean(step);
+ if (!_steps.add(name)) return;
+ _write('launch step=$name ms=${_now()}');
+ }
+
+ /// False once the first chat has been marked, so a row's build can skip
+ /// asking for another frame callback.
+ bool get awaitingFirstChat => !_steps.contains('first_chat_painted');
+
+ /// The first chat row built on screen. Once per launch.
+ void firstChat() => launch('first chat painted');
+
+ /// A page of messages read: [kind] is `latest` (a chat opening) or `older`
+ /// (scrolling back); [requestMs] is the wait for the page, [totalMs] the
+ /// read through merging its rows.
+ void messages({
+ required String kind,
+ required int rows,
+ required int requestMs,
+ required int totalMs,
+ }) => _write(
+ 'messages kind=${_clean(kind)} rows=$rows '
+ 'request_ms=$requestMs total_ms=$totalMs',
+ );
+
+ /// A picture fetched: [bytes] is what arrived; null bytes is a failure.
+ void image({required int ms, int? bytes}) =>
+ _write('image ok=${bytes == null ? 0 : 1} bytes=${bytes ?? 0} ms=$ms');
+
+ int _now() => (_injected?.call() ?? _watch.elapsed).inMilliseconds;
+
+ void _write(String line) {
+ try {
+ final sink = _sink;
+ if (sink != null) {
+ sink(line);
+ return;
+ }
+ // DEBUG goes through the log's batched path (one write a second or 256
+ // lines), so a mark on the UI isolate is a buffer append, not a file
+ // write.
+ final log = _log();
+ if (log is NoopAppLog) {
+ if (_held.length < _heldMost) _held.add(line);
+ return;
+ }
+ for (final earlier in _held) {
+ log.debug('speed', earlier);
+ }
+ _held.clear();
+ log.debug('speed', line);
+ } catch (_) {
+ // Measurement never breaks what it measures.
+ }
+ }
+
+ /// Letters, digits, `-` and `_` only, so no address or path can ride a line.
+ static String _clean(String text) {
+ final cleaned = text
+ .toLowerCase()
+ .replaceAll(RegExp(r'\s+'), '_')
+ .replaceAll(RegExp(r'[^a-z0-9_-]'), '');
+ return cleaned.length > 32 ? cleaned.substring(0, 32) : cleaned;
+ }
+}
+
+/// The app's one recorder.
+final SpeedMarks speedMarks = SpeedMarks();
diff --git a/desktop/lib/measurement/speed_report.dart b/desktop/lib/measurement/speed_report.dart
new file mode 100644
index 000000000..ddb90b116
--- /dev/null
+++ b/desktop/lib/measurement/speed_report.dart
@@ -0,0 +1,190 @@
+/// Reads the `speed` lines [SpeedMarks] wrote to the app log and answers the
+/// three questions of the speed plan (task #3176). Pure Dart, so
+/// `tool/speed_report.dart` runs it outside the app.
+library;
+
+class LaunchStep {
+ const LaunchStep(this.name, this.atMs, this.tookMs);
+ final String name;
+
+ /// Milliseconds since the app started.
+ final int atMs;
+
+ /// Milliseconds since the step before it.
+ final int tookMs;
+}
+
+class MessageRead {
+ const MessageRead(this.kind, this.rows, this.requestMs, this.totalMs);
+ final String kind;
+ final int rows;
+ final int requestMs;
+ final int totalMs;
+}
+
+class ImageFetch {
+ const ImageFetch(this.ok, this.bytes, this.ms);
+ final bool ok;
+ final int bytes;
+ final int ms;
+}
+
+class SpeedReport {
+ SpeedReport(this.launch, this.reads, this.images);
+
+ /// The last launch in the log, in the order its steps were reached.
+ final List<LaunchStep> launch;
+ final List<MessageRead> reads;
+ final List<ImageFetch> images;
+
+ static final _line = RegExp(
+ r'(?:^|[\s\[])speed\]?\s+(launch|messages|image)\s+(.+?)\s*$',
+ );
+
+ static SpeedReport parse(Iterable<String> lines) {
+ var steps = <(String, int)>[];
+ final reads = <MessageRead>[];
+ final images = <ImageFetch>[];
+ for (final text in lines) {
+ final match = _line.firstMatch(text);
+ if (match == null) continue;
+ final fields = {
+ for (final pair in match.group(2)!.split(' '))
+ if (pair.contains('='))
+ pair.substring(0, pair.indexOf('=')): pair.substring(
+ pair.indexOf('=') + 1,
+ ),
+ };
+ int? number(String key) => int.tryParse(fields[key] ?? '');
+ switch (match.group(1)) {
+ case 'launch':
+ final step = fields['step'];
+ final ms = number('ms');
+ if (step == null || ms == null) continue;
+ if (step == 'started') {
+ // A new launch: what an earlier one read is not this one's.
+ steps = [];
+ reads.clear();
+ images.clear();
+ }
+ steps.add((step, ms));
+ case 'messages':
+ final rows = number('rows');
+ final request = number('request_ms');
+ final total = number('total_ms');
+ if (fields['kind'] == null ||
+ rows == null ||
+ request == null ||
+ total == null) {
+ continue;
+ }
+ reads.add(MessageRead(fields['kind']!, rows, request, total));
+ case 'image':
+ final ms = number('ms');
+ final bytes = number('bytes');
+ if (ms == null || bytes == null) continue;
+ images.add(ImageFetch(fields['ok'] == '1', bytes, ms));
+ }
+ }
+ final launch = <LaunchStep>[];
+ var before = 0;
+ for (final (name, at) in steps) {
+ launch.add(LaunchStep(name, at, at - before));
+ before = at;
+ }
+ return SpeedReport(launch, reads, images);
+ }
+
+ /// The three steps of launch that took longest after the step before.
+ List<LaunchStep> get slowestLaunch {
+ // Launch ends at the first chat on screen; later steps are not part of it.
+ final end = launch.indexWhere((s) => s.name == 'first_chat_painted');
+ final steps = end < 0 ? launch : launch.sublist(0, end + 1);
+ return ([
+ ...steps,
+ ]..sort((a, b) => b.tookMs.compareTo(a.tookMs))).take(3).toList();
+ }
+
+ /// The three message reads that took longest, whole.
+ List<MessageRead> get slowestReads => ([
+ ...reads,
+ ]..sort((a, b) => b.totalMs.compareTo(a.totalMs))).take(3).toList();
+
+ /// Opening the app to the first chat on screen, or null if never reached.
+ int? get launchToFirstChatMs => launch
+ .where((s) => s.name == 'first_chat_painted')
+ .map((s) => s.atMs)
+ .firstOrNull;
+
+ int get imageBytes =>
+ images.where((i) => i.ok).fold(0, (n, i) => n + i.bytes);
+
+ static int _percentile(List<int> sorted, double p) =>
+ sorted.isEmpty ? 0 : sorted[((sorted.length - 1) * p).round()];
+
+ String markdown() {
+ final out = StringBuffer();
+ final first = launchToFirstChatMs;
+ out.writeln('| Measure | Value |');
+ out.writeln('| --- | --- |');
+ out.writeln(
+ '| Open the app to a painted chat | '
+ '${first == null ? 'not reached' : '$first ms'} |',
+ );
+ final firsts = reads.where((r) => r.kind == 'latest').toList();
+ final older = reads.where((r) => r.kind == 'older').toList();
+ if (firsts.isEmpty) {
+ out.writeln('| Chat first page | not read |');
+ } else {
+ final slowest = firsts.reduce((a, b) => b.totalMs > a.totalMs ? b : a);
+ out.writeln(
+ '| Chat first page | ${firsts.length} chats opened, slowest '
+ '${slowest.totalMs} ms (${slowest.rows} rows, request ${slowest.requestMs} ms) |',
+ );
+ }
+ if (older.isNotEmpty) {
+ final times = older.map((r) => r.totalMs).toList()..sort();
+ out.writeln(
+ '| Big chat, scroll-up pages | ${older.length} pages, '
+ 'median ${_percentile(times, .5)} ms, slowest ${times.last} ms |',
+ );
+ }
+ final ok = images.where((i) => i.ok).toList();
+ final ms = ok.map((i) => i.ms).toList()..sort();
+ out.writeln(
+ '| Images | ${ok.length} loaded'
+ '${images.length > ok.length ? ', ${images.length - ok.length} failed' : ''}'
+ ', $imageBytes bytes'
+ '${ok.isEmpty ? '' : ', median ${_percentile(ms, .5)} ms, p95 ${_percentile(ms, .95)} ms, slowest ${ms.last} ms'} |',
+ );
+ out.writeln();
+ out.writeln('Every chat opened (first page):');
+ out.writeln();
+ out.writeln('| Kind | Rows | Request | Total |');
+ out.writeln('| --- | --- | --- | --- |');
+ for (final r in firsts) {
+ out.writeln(
+ '| ${r.kind} | ${r.rows} | ${r.requestMs} ms | ${r.totalMs} ms |',
+ );
+ }
+ out.writeln();
+ out.writeln('Three slowest launch steps (time since the step before):');
+ out.writeln();
+ out.writeln('| Step | Took | At |');
+ out.writeln('| --- | --- | --- |');
+ for (final s in slowestLaunch) {
+ out.writeln('| ${s.name} | ${s.tookMs} ms | ${s.atMs} ms |');
+ }
+ out.writeln();
+ out.writeln('Three slowest message reads:');
+ out.writeln();
+ out.writeln('| Kind | Rows | Request | Total |');
+ out.writeln('| --- | --- | --- | --- |');
+ for (final r in slowestReads) {
+ out.writeln(
+ '| ${r.kind} | ${r.rows} | ${r.requestMs} ms | ${r.totalMs} ms |',
+ );
+ }
+ return out.toString();
+ }
+}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index d6029573c..f2935a033 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -1,6 +1,7 @@
import '../core/home_dir.dart';
import '../usage/usage_account_key.dart';
import '../measurement/product_measurement.dart';
+import '../measurement/speed_marks.dart';
import '../measurement/product_runtime_health.dart';
import '../measurement/product_connections.dart';
import '../core/crash_log.dart';
@@ -7025,6 +7026,7 @@ class AppNotifier extends ChangeNotifier {
final _startupTimings = <String, int>{};
final _startupClock = Stopwatch();
void _markStartup(String step) {
+ speedMarks.launch(step);
if (_startupClock.isRunning)
_startupTimings[step] = _startupClock.elapsedMilliseconds;
}
@@ -7664,6 +7666,7 @@ class AppNotifier extends ChangeNotifier {
}
try {
await refreshMachines();
+ speedMarks.launch('machines listed');
} catch (error) {
if (!_authWorkCurrent(revision)) return;
_reportMachineLoadError(error);
diff --git a/desktop/lib/super_tabs/attachment_viewer.dart b/desktop/lib/super_tabs/attachment_viewer.dart
index c76fcc340..6a4eeeba1 100644
--- a/desktop/lib/super_tabs/attachment_viewer.dart
+++ b/desktop/lib/super_tabs/attachment_viewer.dart
@@ -9,6 +9,7 @@ import 'package:flutter/material.dart';
import '../core/open_in_browser.dart';
import '../finder/finder_file_kind.dart';
+import '../measurement/speed_marks.dart';
import '../widgets/desktop_chrome.dart';
import 'attachment_upload.dart' show kSuperTabFormAttachmentMaxBytes;
import 'file_links.dart';
@@ -39,6 +40,24 @@ ImageProvider attachmentPicture(Uri url) => attachmentImage(url);
Future<Uint8List> readAttachment(Uri url, {int? maxBytes}) =>
attachmentFetcher(url, maxBytes: maxBytes);
+/// A picture shown in place, read through [attachmentFetcher] and timed: its
+/// bytes and milliseconds (or its failure) go to the speed marks
+/// (`measurement/speed_marks.dart`), never its address.
+Future<Uint8List> readPicture(Uri url) async {
+ final clock = Stopwatch()..start();
+ try {
+ final bytes = await readAttachment(
+ url,
+ maxBytes: kSuperTabFormAttachmentMaxBytes,
+ );
+ speedMarks.image(ms: clock.elapsedMilliseconds, bytes: bytes.length);
+ return bytes;
+ } catch (_) {
+ speedMarks.image(ms: clock.elapsedMilliseconds);
+ rethrow;
+ }
+}
+
/// A file past the text viewer's limit; it opens in the browser instead.
class AttachmentTooLarge implements Exception {
const AttachmentTooLarge();
@@ -246,11 +265,8 @@ class AttachmentImage extends ImageProvider<AttachmentImage> {
// No more than a picture shown in place may weigh, whatever its row says:
// a larger one fails to draw rather than being read whole.
- Future<ui.Codec> _decode(ImageDecoderCallback decode) async => decode(
- await ui.ImmutableBuffer.fromUint8List(
- await readAttachment(url, maxBytes: kSuperTabFormAttachmentMaxBytes),
- ),
- );
+ Future<ui.Codec> _decode(ImageDecoderCallback decode) async =>
+ decode(await ui.ImmutableBuffer.fromUint8List(await readPicture(url)));
@override
bool operator ==(Object other) =>
diff --git a/desktop/lib/super_tabs/controller.dart b/desktop/lib/super_tabs/controller.dart
index 451f70ac3..6b6c08e8e 100644
--- a/desktop/lib/super_tabs/controller.dart
+++ b/desktop/lib/super_tabs/controller.dart
@@ -9,6 +9,7 @@ import 'package:dio/dio.dart' show CancelToken, DioException, DioExceptionType;
import 'package:flutter/foundation.dart';
import '../logging/app_log.dart';
+import '../measurement/speed_marks.dart';
import '../state/harness_attachments.dart';
import 'attachment_upload.dart';
import 'avatar_upload.dart';
@@ -27,7 +28,12 @@ import 'local_time_zone.dart';
import 'task_steps.dart';
/// A messages read started beside a state read, and what it asked for.
-typedef _EarlyRead = ({String query, Future<Map<String, dynamic>> page});
+typedef _EarlyRead = ({
+ String query,
+ Future<Map<String, dynamic>> page,
+ // Running since the page was asked for, so its wait is measured whole.
+ Stopwatch clock,
+});
typedef SuperTabRequest = Future<Map<String, dynamic>> Function(
String method,
@@ -3807,8 +3813,10 @@ class SuperTabController extends ChangeNotifier {
// A conversation the state already has takes its answer as it comes, so
// a reply shows without waiting for the state.
final messagesRead = early != null && snapshot != null
- ? (_readMessages(earlyId, early: (query: earlyQuery!, page: early))
- ..ignore())
+ ? (_readMessages(
+ earlyId,
+ early: (query: earlyQuery!, page: early, clock: took),
+ )..ignore())
: null;
try {
final heldSaved = _parts != null && stateReads == 0;
@@ -3822,6 +3830,7 @@ class SuperTabController extends ChangeNotifier {
_graceEnd?.cancel();
_firstReadRetry?.cancel();
stateReads++;
+ speedMarks.launch('swarm state read');
// How long the Swarm took to answer, and nothing it said: the log shows a slow or failing
// backend, which the sidebar's ages and the machines' states otherwise only hint at.
appLog.debug(
@@ -3959,7 +3968,7 @@ class SuperTabController extends ChangeNotifier {
: _readMessages(
selectedId,
early: selectedId == earlyId && early != null
- ? (query: earlyQuery!, page: early)
+ ? (query: earlyQuery!, page: early, clock: took)
: null,
));
} else {
@@ -4741,6 +4750,9 @@ class SuperTabController extends ChangeNotifier {
// A light check asks only for new messages, which wait while holding.
if (light && _holding(id)) return;
final generation = _heldGeneration[id];
+ // A first page asked for beside the state has been out since then.
+ final readClock = early?.clock ?? (Stopwatch()..start());
+ var requestMs = 0;
// How far the Swarm's state said the conversation went when this read
// was asked for.
final askedUpTo = snapshot!.conversation(id)!.lastMessageSequence;
@@ -4761,6 +4773,7 @@ class SuperTabController extends ChangeNotifier {
(Object _) => request('GET', '${_messagesPath(id)}$query'),
)
: await request('GET', '${_messagesPath(id)}$query');
+ requestMs = readClock.elapsedMilliseconds;
final arrived =
!older &&
!holding &&
@@ -4979,6 +4992,16 @@ class SuperTabController extends ChangeNotifier {
if (id == selectedId) _viewVersion++;
_changed();
}
+ // Speed marks (task #3176): a chat opening and each page read back; a
+ // poll for new messages is not one of them.
+ if (older || replacing || (tail == null && incoming.isNotEmpty)) {
+ speedMarks.messages(
+ kind: older ? 'older' : 'latest',
+ rows: incoming.length,
+ requestMs: requestMs,
+ totalMs: readClock.elapsedMilliseconds,
+ );
+ }
} catch (failure) {
if (!older) _settleHeld(id, read: false);
// The state read waits for a machine within the grace: so do these.
diff --git a/desktop/lib/super_tabs/view.dart b/desktop/lib/super_tabs/view.dart
index 6e53b87ff..b55990e6d 100644
--- a/desktop/lib/super_tabs/view.dart
+++ b/desktop/lib/super_tabs/view.dart
@@ -9,6 +9,7 @@ import 'package:flutter/rendering.dart'
import 'package:flutter/scheduler.dart' show SchedulerBinding, SchedulerPhase;
import 'package:flutter/services.dart';
+import '../measurement/speed_marks.dart';
import '../shared/theme/app_icons.dart';
import '../shared/theme/app_theme.dart' as grid;
import '../shared/widgets/app_dialog.dart';
@@ -5653,6 +5654,12 @@ class _BuiltRowState extends State<_BuiltRow> {
@override
Widget build(BuildContext context) {
widget.rows[widget.id] = context;
+ // The first chat on screen after launch: marked once the frame is out.
+ if (speedMarks.awaitingFirstChat) {
+ WidgetsBinding.instance.addPostFrameCallback(
+ (_) => speedMarks.firstChat(),
+ );
+ }
return widget.child;
}
}
diff --git a/desktop/test/speed_hooks_test.dart b/desktop/test/speed_hooks_test.dart
new file mode 100644
index 000000000..0518fce7d
--- /dev/null
+++ b/desktop/test/speed_hooks_test.dart
@@ -0,0 +1,165 @@
+import 'dart:typed_data';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/logging/app_log.dart';
+import 'package:harness/measurement/speed_marks.dart';
+import 'package:harness/super_tabs/attachment_viewer.dart';
+import 'package:harness/super_tabs/view.dart';
+
+import 'support/super_tab_fixture.dart';
+
+// Task #3176: the places that call the speed recorder. Each risk the task names
+// has a test that fails without its hook: message reads (first page and
+// scroll-up pages), image fetches, and a poll that must stay out of the log.
+
+class _Recorder implements AppLog {
+ final lines = <String>[];
+ final levels = <AppLogLevel>{};
+ @override
+ void record(
+ AppLogLevel level,
+ String category,
+ String message, {
+ Object? error,
+ StackTrace? stackTrace,
+ }) {
+ if (category != 'speed') return;
+ levels.add(level);
+ lines.add(message);
+ }
+}
+
+void main() {
+ late _Recorder log;
+ late AppLog before;
+
+ setUp(() {
+ before = appLog;
+ appLog = log = _Recorder();
+ });
+ tearDown(() => appLog = before);
+
+ test('marks go through the log\'s batched debug path, not a write each', () {
+ speedMarks.restart();
+ speedMarks.launch('tools');
+ speedMarks.messages(kind: 'latest', rows: 1, requestMs: 1, totalMs: 1);
+ speedMarks.image(ms: 1, bytes: 1);
+
+ expect(log.levels, {AppLogLevel.debug});
+ });
+
+ group('message reads', () {
+ test('the first page and each scroll-up page are recorded', () async {
+ final server = ConversationServer()..messagePage = 2;
+ for (final text in ['one', 'two', 'three', 'four', 'five']) {
+ server.append(text);
+ }
+ final c = server.controller();
+ await c.refresh();
+ expect(
+ log.lines.where((l) => l.startsWith('messages kind=latest rows=2 ')),
+ hasLength(1),
+ );
+
+ await c.loadMessages('lead', older: true);
+ await c.loadMessages('lead', older: true);
+ expect(
+ log.lines.where((l) => l.startsWith('messages kind=older ')),
+ hasLength(2),
+ );
+ expect(
+ log.lines.where((l) => l.startsWith('messages ')),
+ everyElement(
+ matches(r'^messages kind=\w+ rows=\d+ request_ms=\d+ total_ms=\d+$'),
+ ),
+ );
+ });
+
+ test('a poll that finds nothing new records nothing', () async {
+ final server = ConversationServer()..messagePage = 2;
+ for (final text in ['one', 'two']) {
+ server.append(text);
+ }
+ final c = server.controller();
+ await c.refresh();
+ log.lines.clear();
+
+ await c.loadMessages('lead');
+
+ expect(log.lines.where((l) => l.startsWith('messages ')), isEmpty);
+ });
+ });
+
+ group('first chat', () {
+ testWidgets('is marked once, when a chat row is built', (tester) async {
+ speedMarks.restart();
+ final server = ConversationServer()..append('hello');
+ final c = server.controller();
+ await c.refresh();
+ await tester.binding.setSurfaceSize(const Size(1100, 800));
+ addTearDown(() => tester.binding.setSurfaceSize(null));
+ expect(log.lines.where((l) => l.contains('first_chat_painted')), isEmpty);
+
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: SuperTabView(
+ controller: c,
+ onInvite: () {},
+ onAddAgent: (_) {},
+ onOpenTerminal: (_) {},
+ machineName: (_) => 'Test Mac',
+ ),
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ server.append('again');
+ await c.refresh();
+ await tester.pumpAndSettle();
+
+ expect(
+ log.lines.where((l) => l.contains('step=first_chat_painted')),
+ hasLength(1),
+ );
+ await tester.pumpWidget(const SizedBox());
+ await c.flush();
+ c.dispose();
+ });
+ });
+
+ group('images', () {
+ late Future<Uint8List> Function(Uri, {int? maxBytes}) fetcher;
+ setUp(() => fetcher = attachmentFetcher);
+ tearDown(() => attachmentFetcher = fetcher);
+
+ test('a fetched picture records its bytes and time', () async {
+ attachmentFetcher = (url, {maxBytes}) async => Uint8List(4321);
+
+ final bytes = await readPicture(Uri.parse('https://files.example/a.png'));
+
+ expect(bytes, hasLength(4321));
+ expect(log.lines, [matches(r'^image ok=1 bytes=4321 ms=\d+$')]);
+ });
+
+ test('a failed picture records ok=0 and still throws', () async {
+ attachmentFetcher = (url, {maxBytes}) async => throw StateError('404');
+
+ await expectLater(
+ readPicture(Uri.parse('https://files.example/a.png')),
+ throwsStateError,
+ );
+ expect(log.lines, [matches(r'^image ok=0 bytes=0 ms=\d+$')]);
+ });
+
+ test('the line holds no address', () async {
+ attachmentFetcher = (url, {maxBytes}) async => Uint8List(1);
+
+ await readPicture(Uri.parse('https://files.example/secret-name.png'));
+
+ expect(log.lines.single, isNot(contains('secret')));
+ expect(log.lines.single, isNot(contains('files.example')));
+ });
+ });
+}
diff --git a/desktop/test/speed_marks_test.dart b/desktop/test/speed_marks_test.dart
new file mode 100644
index 000000000..2aeb0aa95
--- /dev/null
+++ b/desktop/test/speed_marks_test.dart
@@ -0,0 +1,282 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/logging/app_log.dart';
+import 'package:harness/measurement/speed_marks.dart';
+import 'package:harness/measurement/speed_report.dart';
+
+// Task #3176: the numbers that pick the speed work and stay as its "before".
+
+void main() {
+ late Duration now;
+ late List<String> written;
+ late SpeedMarks marks;
+
+ setUp(() {
+ now = Duration.zero;
+ written = [];
+ marks = SpeedMarks(sink: written.add, elapsed: () => now);
+ });
+
+ group('SpeedMarks', () {
+ test('a launch step is kept once, in milliseconds since launch', () {
+ marks.start();
+ now = const Duration(milliseconds: 120);
+ marks.launch('first frame');
+ now = const Duration(milliseconds: 900);
+ marks.launch('first frame');
+ marks.launch('saved tabs');
+
+ expect(written, [
+ 'launch step=started ms=0',
+ 'launch step=first_frame ms=120',
+ 'launch step=saved_tabs ms=900',
+ ]);
+ });
+
+ test('the first chat is marked once, however many rows are built', () {
+ marks.start();
+ now = const Duration(milliseconds: 1500);
+ marks.firstChat();
+ now = const Duration(milliseconds: 1700);
+ marks.firstChat();
+
+ expect(written.where((l) => l.contains('first_chat_painted')), [
+ 'launch step=first_chat_painted ms=1500',
+ ]);
+ });
+
+ test('a messages read keeps its kind, rows and both times', () {
+ marks.messages(kind: 'older', rows: 50, requestMs: 180, totalMs: 240);
+
+ expect(written, [
+ 'messages kind=older rows=50 request_ms=180 total_ms=240',
+ ]);
+ });
+
+ test('an image keeps its bytes and time, a failed one says so', () {
+ marks.image(ms: 95, bytes: 48213);
+ marks.image(ms: 3000);
+
+ expect(written, [
+ 'image ok=1 bytes=48213 ms=95',
+ 'image ok=0 bytes=0 ms=3000',
+ ]);
+ });
+
+ test('a line carries no name, id, path or address', () {
+ marks.start();
+ marks.launch('Sign in as [email protected] /Users/huy');
+ marks.messages(kind: 'latest', rows: 3, requestMs: 1, totalMs: 2);
+ marks.image(ms: 1, bytes: 2);
+
+ for (final line in written) {
+ expect(line, isNot(contains('@')));
+ expect(line, isNot(contains('/')));
+ expect(line, isNot(contains(' as ')));
+ }
+ });
+
+ test('a sink that throws never reaches the caller', () {
+ final broken = SpeedMarks(
+ sink: (_) => throw StateError('disk full'),
+ elapsed: () => now,
+ );
+ expect(() => broken.start(), returnsNormally);
+ expect(() => broken.launch('x'), returnsNormally);
+ expect(
+ () =>
+ broken.messages(kind: 'latest', rows: 1, requestMs: 1, totalMs: 1),
+ returnsNormally,
+ );
+ expect(() => broken.image(ms: 1, bytes: 1), returnsNormally);
+ });
+
+ test('a second launch in one process starts the steps over', () {
+ marks.start();
+ marks.launch('tools');
+ marks.restart();
+ marks.launch('tools');
+
+ expect(written.where((l) => l.contains('step=tools')), hasLength(2));
+ });
+ });
+
+ group('before the log is installed', () {
+ test('marks wait for the real log and then arrive in order', () {
+ // main() starts the marks before installFileLogs() has replaced the
+ // no-op log: the launch line must not be lost with it.
+ AppLog current = const NoopAppLog();
+ final seen = <String>[];
+ final early = SpeedMarks(log: () => current, elapsed: () => now);
+ early.start();
+ now = const Duration(milliseconds: 40);
+ early.launch('settings loaded');
+
+ current = _Seen(seen);
+ now = const Duration(milliseconds: 90);
+ early.launch('window configured');
+
+ expect(seen, [
+ 'launch step=started ms=0',
+ 'launch step=settings_loaded ms=40',
+ 'launch step=window_configured ms=90',
+ ]);
+ });
+
+ test('a log that never comes holds only the first 64 lines', () {
+ AppLog current = const NoopAppLog();
+ final seen = <String>[];
+ final early = SpeedMarks(log: () => current, elapsed: () => now);
+ for (var i = 0; i < 500; i++) {
+ early.image(ms: 1, bytes: 1);
+ }
+ current = _Seen(seen);
+ early.image(ms: 1, bytes: 1);
+
+ expect(seen, hasLength(65));
+ });
+ });
+
+ group('SpeedReport', () {
+ const stamp = '2026-11-05T09:00:00.000 INFO speed ';
+ List<String> lines(List<String> raw) => [
+ '2026-11-05T08:59:00.000 INFO app launched',
+ for (final r in raw) '$stamp$r',
+ ];
+
+ test('names the three slowest launch steps by the time each took', () {
+ final report = SpeedReport.parse(
+ lines([
+ 'launch step=started ms=0',
+ 'launch step=settings ms=40',
+ 'launch step=first_frame ms=300',
+ 'launch step=tools ms=350',
+ 'launch step=signed-in_check ms=1950',
+ 'launch step=daemon ms=2250',
+ 'launch step=window ms=2300',
+ 'launch step=first_chat_painted ms=3300',
+ ]),
+ );
+
+ expect(report.slowestLaunch.map((s) => s.name), [
+ 'signed-in_check',
+ 'first_chat_painted',
+ 'daemon',
+ ]);
+ expect(report.slowestLaunch.first.tookMs, 1600);
+ expect(report.launchToFirstChatMs, 3300);
+ });
+
+ test('only the last launch in the log is reported', () {
+ final report = SpeedReport.parse(
+ lines([
+ 'launch step=started ms=0',
+ 'launch step=first_chat_painted ms=9000',
+ 'launch step=started ms=0',
+ 'launch step=first_chat_painted ms=2000',
+ ]),
+ );
+ expect(report.launchToFirstChatMs, 2000);
+ });
+
+ test('names the three slowest message reads and sums the images', () {
+ final report = SpeedReport.parse(
+ lines([
+ 'messages kind=latest rows=50 request_ms=300 total_ms=380',
+ 'messages kind=older rows=50 request_ms=900 total_ms=1000',
+ 'messages kind=older rows=50 request_ms=200 total_ms=250',
+ 'messages kind=older rows=50 request_ms=500 total_ms=560',
+ 'image ok=1 bytes=1000 ms=100',
+ 'image ok=1 bytes=3000 ms=300',
+ 'image ok=0 bytes=0 ms=3000',
+ ]),
+ );
+
+ expect(report.slowestReads.map((r) => r.totalMs), [1000, 560, 380]);
+ expect(report.images.where((i) => i.ok), hasLength(2));
+ expect(report.imageBytes, 4000);
+ });
+
+ test('reads and images before the last launch are not reported', () {
+ final report = SpeedReport.parse(
+ lines([
+ 'launch step=started ms=0',
+ 'messages kind=latest rows=50 request_ms=9000 total_ms=9500',
+ 'messages kind=older rows=50 request_ms=9000 total_ms=9500',
+ 'image ok=1 bytes=99999 ms=9000',
+ 'launch step=started ms=0',
+ 'launch step=first_chat_painted ms=2000',
+ 'messages kind=latest rows=3 request_ms=100 total_ms=120',
+ 'messages kind=latest rows=50 request_ms=300 total_ms=380',
+ 'image ok=1 bytes=1000 ms=100',
+ ]),
+ );
+
+ // Both first pages of this launch (the chat shown at launch and the big
+ // chat opened after it), none of the earlier launch.
+ expect(report.reads.map((r) => r.totalMs), [120, 380]);
+ expect(report.images, hasLength(1));
+ expect(report.imageBytes, 1000);
+ final table = report.markdown();
+ expect(table, contains('| latest | 3 |'));
+ expect(table, contains('| latest | 50 |'));
+ expect(table, isNot(contains('9500')));
+ });
+
+ test('steps after the first chat are not among the slowest of launch', () {
+ final report = SpeedReport.parse(
+ lines([
+ 'launch step=started ms=0',
+ 'launch step=tools ms=500',
+ 'launch step=first_chat_painted ms=1500',
+ 'launch step=machines_listed ms=9000',
+ ]),
+ );
+
+ expect(report.slowestLaunch.map((s) => s.name), [
+ 'first_chat_painted',
+ 'tools',
+ 'started',
+ ]);
+ });
+
+ test('the table has launch, big-chat and image rows', () {
+ final table = SpeedReport.parse(
+ lines([
+ 'launch step=started ms=0',
+ 'launch step=first_chat_painted ms=2000',
+ 'messages kind=latest rows=50 request_ms=300 total_ms=380',
+ 'image ok=1 bytes=1000 ms=100',
+ ]),
+ ).markdown();
+
+ expect(table, contains('| Open the app to a painted chat | 2000 ms |'));
+ expect(table, contains('latest'));
+ expect(table, contains('Images'));
+ });
+
+ test('lines that are not speed marks are ignored', () {
+ final report = SpeedReport.parse([
+ '2026-11-05T09:00:00.000 INFO ws connected',
+ 'speed junk',
+ '${stamp}messages kind=latest rows=x request_ms=1 total_ms=2',
+ ]);
+ expect(report.reads, isEmpty);
+ expect(report.launch, isEmpty);
+ });
+ });
+}
+
+class _Seen implements AppLog {
+ _Seen(this.lines);
+ final List<String> lines;
+ @override
+ void record(
+ AppLogLevel level,
+ String category,
+ String message, {
+ Object? error,
+ StackTrace? stackTrace,
+ }) {
+ if (category == 'speed') lines.add(message);
+ }
+}
diff --git a/desktop/test/startup_order_test.dart b/desktop/test/startup_order_test.dart
index c8ac93874..1c666ab5b 100644
--- a/desktop/test/startup_order_test.dart
+++ b/desktop/test/startup_order_test.dart
@@ -9,6 +9,8 @@ import 'package:harness/bootstrap/environment_provisioner.dart';
import 'package:harness/core/config.dart';
import 'package:harness/core/local_key_value_store.dart';
import 'package:harness/core/models.dart';
+import 'package:harness/logging/app_log.dart';
+import 'package:harness/measurement/speed_marks.dart';
import 'package:harness/state/app_state.dart';
import 'package:harness/state/pane_layout_store.dart';
import 'package:harness/ws/local_cli_discovery.dart';
@@ -245,6 +247,33 @@ void main() {
expect(app.lastError, contains('no daemon'));
});
+ test(
+ 'every startup step also reaches the speed marks, since launch',
+ () async {
+ final before = appLog;
+ final seen = <String>[];
+ appLog = _Speed(seen);
+ addTearDown(() => appLog = before);
+ speedMarks.restart();
+
+ await make(_Cli([() async => _in]), _Environment()).bootstrap();
+
+ for (final step in [
+ 'signed-in_check',
+ 'tools',
+ 'saved_tabs',
+ 'daemon',
+ 'window',
+ ]) {
+ expect(
+ seen,
+ contains(matches('^launch step=$step ms=\\d+\$')),
+ reason: step,
+ );
+ }
+ },
+ );
+
test('keeps a stopwatch of the startup steps', () async {
final app = make(_Cli([() async => _in]), _Environment());
await app.bootstrap();
@@ -272,3 +301,18 @@ extension on List<_App> {
return out;
}
}
+
+class _Speed implements AppLog {
+ _Speed(this.lines);
+ final List<String> lines;
+ @override
+ void record(
+ AppLogLevel level,
+ String category,
+ String message, {
+ Object? error,
+ StackTrace? stackTrace,
+ }) {
+ if (category == 'speed') lines.add(message);
+ }
+}
diff --git a/desktop/tool/speed_report.dart b/desktop/tool/speed_report.dart
new file mode 100644
index 000000000..d7739cbf0
--- /dev/null
+++ b/desktop/tool/speed_report.dart
@@ -0,0 +1,50 @@
+// ignore_for_file: avoid_print
+// Prints the speed table from the app log (task #3176): the time from opening
+// Desktop to a painted chat, a large chat's first page and scroll-up pages,
+// and each picture's time and bytes, with the three slowest steps of launch
+// and of message load named.
+//
+// dart run tool/speed_report.dart [app-log-file ...]
+//
+// Without arguments it reads today's and yesterday's `~/.harness/logs/app-*.log`.
+// Open the app, open the big chat, scroll up through its history, scroll an
+// image-heavy chat, then run this. It reads `speed` lines only: counts,
+// milliseconds and bytes, never a name, path or message.
+import 'dart:io';
+
+import 'package:harness/measurement/speed_report.dart';
+
+void main(List<String> args) {
+ final files = args.isNotEmpty
+ ? args.map(File.new).toList()
+ : _recentLogs(Platform.environment['HOME'] ?? '.');
+ if (files.isEmpty) {
+ print('No app log found. Open Desktop first.');
+ exitCode = 1;
+ return;
+ }
+ final lines = <String>[];
+ for (final file in files) {
+ if (file.existsSync()) lines.addAll(file.readAsLinesSync());
+ }
+ final report = SpeedReport.parse(lines);
+ if (report.launch.isEmpty && report.reads.isEmpty && report.images.isEmpty) {
+ print('No speed lines in ${files.length} log file(s).');
+ exitCode = 1;
+ return;
+ }
+ print(report.markdown());
+}
+
+List<File> _recentLogs(String home) {
+ final dir = Directory('$home/.harness/logs');
+ if (!dir.existsSync()) return const [];
+ final logs =
+ dir
+ .listSync()
+ .whereType<File>()
+ .where((f) => RegExp(r'app-\d{8}\.log$').hasMatch(f.path))
+ .toList()
+ ..sort((a, b) => a.path.compareTo(b.path));
+ return logs.length > 2 ? logs.sublist(logs.length - 2) : logs;
+}
diff --git a/docs/plans/2026-11-05-first-clone-reliable-plan.md b/docs/plans/2026-11-05-first-clone-reliable-plan.md
new file mode 100644
index 000000000..47637a290
--- /dev/null
+++ b/docs/plans/2026-11-05-first-clone-reliable-plan.md
@@ -0,0 +1,46 @@
+# A first start on a new machine clones the repository reliably: plan
+
+**Goal:** An agent start on a machine with no checkout yet clones the project, or says exactly why it could not, and a
+failed clone never suspends the engine there (task #3096, requested by Ken).
+
+**Architecture:** 11-05: six starts failed on four machines without a checkout, "could not clone the project repository
+with the Harness GitHub App's token: Could not clone the repository" or "Cloning stopped making progress", and each pair of
+failures suspended the engine on that machine for up to 6 hours. The clone is already partial (`--filter=blob:none
+--single-branch`, `lib/projectFolder.ts cloneRepository`) and already ends a clone with 120 s of git silence, so what is
+missing is: git's own reason (`cloneFailure` throws it away), a second try (a clone that fails once on GitHub or the
+network often works seconds later), and the engine count (`engineHealth.ts counts` treats a clone failure as the engine's
+fault). The three changes:
+
+1. `cloneFailure` and the stall timeout carry git's last `fatal:`/`error:` line (credentials cut, bounded).
+2. `prepareSwarmProject` with the App's token retries a failed or stalled clone once after a short backoff; a refusal, a
+ changed folder or a missing git is never retried.
+3. `engineHealth.ts` does not count a start whose reason is a clone failure.
+
+**Tech Stack:** TypeScript (cli, backend), vitest.
+
+**Spec:** task #3096 brief.
+
+## Global Constraints
+
+- Swarm code stays out of cli/src/core. Tests use fakes and temp folders; no real sign-in is touched.
+- Git's words reach the message only after credentials and tokens are cut.
+
+## Review Focus
+
+- A retry never leaves a staging folder or a second clone running (`prepareProjectFolder` removes its staging each try).
+- The engine count still counts a real engine failure; only a clone failure is excluded.
+
+## Task 1: git's reason in a failed clone
+**Files:** cli/src/lib/projectFolder.ts, cli/src/lib/projectFolder.spec.ts
+- [ ] Failing tests: a failed clone's message names git's last fatal line without credentials; a stalled clone's names its last output.
+- [ ] Implement `gitsWords`.
+
+## Task 2: one retry of the first clone
+**Files:** cli/src/superTabs/projectFolder.ts, cli/src/superTabs/projectFolder.spec.ts
+- [ ] Failing tests: a failed or stalled token clone is tried once more after the backoff; a second failure is the error; a refusal or other error is not retried.
+- [ ] Implement the retry.
+
+## Task 3: a clone failure does not suspend the engine
+**Files:** backend/src/superTabs/engineHealth.ts, backend/src/superTabs/engineHealth.test.ts
+- [ ] Failing test: two clone failures in a row suspend nothing; two engine failures still do.
+- [ ] Implement in `notTheEngine`.
diff --git a/docs/plans/2026-11-05-phone-push-plan.md b/docs/plans/2026-11-05-phone-push-plan.md
index c48c687a6..13025299e 100644
--- a/docs/plans/2026-11-05-phone-push-plan.md
+++ b/docs/plans/2026-11-05-phone-push-plan.md
@@ -67,7 +67,10 @@ for who is told.
app is signed out, so a push it gets opens the welcome screen and shows no content beyond the notice. The next person
signing in on that phone takes the token over (1), and Apple or Google calling it dead deletes it. Tested by (1).
3. A development build (Xcode) has a sandbox token: production APNs answers `BadDeviceToken`, and the server retries once
- on the sandbox host and remembers it. Test in Task 3.
+ on the sandbox host and remembers it. Test in Task 3. Apple's keys are per environment (Ken, 11-05): the production key
+ (`APNS_KEY_ID`, `APNS_PRIVATE_KEY`) signs for the production host alone, an optional sandbox key (`APNS_SANDBOX_KEY_ID`,
+ `APNS_SANDBOX_PRIVATE_KEY`) for the sandbox host alone; with no sandbox key nothing goes to the sandbox host, the push
+ is skipped (`unconfigured`, logged without the token) and the token kept.
4. A push while the app is in front must not show twice (push and local notice): iOS presents nothing for a remote Swarm
push in the foreground, FCM does not draw a notification message in the foreground. And a push already in the tray is
not posted again by the app when it comes back: the app marks the keys of delivered pushes told (Task 7 test).
@@ -125,7 +128,7 @@ for who is told.
**Interfaces:**
- Produces: `interface PhoneNotice { personId: string; key: string; title: string; subtitle: string; body: string; link: string }`;
- `type SendOutcome = 'sent' | 'gone' | 'sandbox' | 'failed'`; `interface SendResult { outcome: SendOutcome; reason?: string }`;
+ `type SendOutcome = 'sent' | 'gone' | 'sandbox' | 'failed' | 'unconfigured'`; `interface SendResult { outcome: SendOutcome; reason?: string }`;
`interface Sender { send(device: PushDevice, notice: PhoneNotice): Promise<SendResult> }`;
`apnsSender(keys: ApnsKeys, options?: { transport?; now?; timeoutMs? }): Sender`; `fcmSender(account: FcmAccount, options?: { fetcher?; now?; timeoutMs? }): Sender`;
`pushKeysFromEnv(env): { apns: ApnsKeys | null; fcm: FcmAccount | null }` (throws a message without the key on a bad one).
diff --git a/docs/plans/2026-11-05-route-size-fits-model-plan.md b/docs/plans/2026-11-05-route-size-fits-model-plan.md
new file mode 100644
index 000000000..20dfead77
--- /dev/null
+++ b/docs/plans/2026-11-05-route-size-fits-model-plan.md
@@ -0,0 +1,103 @@
+# The route offers the model the task's size calls for, and records each candidate's quota (task #3163) Implementation Plan
+
+> Implemented by the task's Engineer task by task, each failing test committed before its code (project instructions,
+> Engineer). One independent review on the pull request.
+
+**Goal:** within each slot (a machine's engine, as a new agent or an idle member) the route offers the model the
+project's Routing rules call for: Claude Sonnet high or Codex GPT-6.1 Sol high for small, low or medium work; Claude
+Opus high or Codex GPT-6 Astra xhigh for big, hard, risky, security or review work. Until now the slot kept whichever
+candidate's title sorted first, so Opus and Astra were offered for small work (Ken, 2026-11-05, production: Astra xhigh
+offered 2,010 times for small work against Sol high 67; Opus high 2,356 against Sonnet high 127). The route decision
+also stores each candidate's quota fit again (status, weekly % left, reset), which the record without a pick
+(#3010/#3045) had cut to account and spend: 3,905 of 3,915 Codex candidates have no `fit.status`.
+
+**Architecture:**
+
+- CLI `cli/src/superTabs/route.ts`.
+ - `tierOf(assessment)`: `strong` when the size is large, the difficulty or risk high, or the kind names security or
+ review; otherwise `standard`; `null` when the assessment gave no size (an older agent) and nothing makes it strong.
+ `parseAssessment` marks a missing size `unsized: true`; it is never sent to the backend.
+ - `TIER_MODELS`: the Routing rules' four rows, `standard` Claude sonnet high and Codex gpt-6.1-sol high, `strong`
+ Claude opus high and Codex gpt-6-astra xhigh. A candidate ranks 0 when it runs its tier's row, 2 when it runs the
+ other tier's model at any effort, else 1. A member's reported model is read through the catalog (`catalogRow`), so
+ `claude-opus-4-7` counts as opus.
+ - `withEveryAccount` keeps, per slot, the candidate of lowest rank, ties by the neutral order (machine, engine, title),
+ up to `RECORD_MAX`. The fill up to `MAX_SHOWN` adds no rank-2 row. With no tier, a slot keeps its first row of each
+ tier (both models), within the same caps. The rows still come out in the neutral order; nothing else is ranked.
+ - `recordOf` adds `left` and `resetsAt` to each candidate's fit: the weekly window's percent left and reset (the
+ tightest reading's when no weekly window is read), as `quotaBrief` shows them. A new shape `unquoted` leaves them out
+ for a backend from before this change; `picked`, `unkinded` and `v1` leave them out too.
+- CLI `routeCommand.ts`: a record refused as invalid is tried as `unquoted` before `picked`.
+- Backend `backend/src/superTabs/routeRecord.ts`: the fit schema takes optional `left` (0–100, nullable) and `resetsAt`
+ (epoch ms, nullable). `storedRecord`, for a record without a pick, keeps each candidate's `status`, `left` and
+ `resetsAt` beside `account` and `spend`. `KeptFit` gains them as optional, since rows written before lack them.
+
+**Tech Stack:** TypeScript, vitest (CLI specs, backend unit tests), zod.
+
+**Spec:** task #3163's brief (conversation e690160e2ccbc0a06052f89c); the project instructions' Routing, Models.
+
+## Global Constraints
+
+- No new settings. The tier rows mirror the Routing rules as constants in `route.ts`; a catalog without them leaves the
+ slot to its neutral first row, as before.
+- Swarm code stays out of `cli/src/core`. CLI specs run with a scratchpad `TMPDIR` (mktemp -d).
+- Backend: run the backend unit suite (`npm test` in `backend/`) since `routeRecord.ts` changes; the Super Tab
+ integration suite runs in PR CI.
+- Owned files: `cli/src/superTabs/route.ts`, `cli/src/superTabs/routeCommand.ts`, `backend/src/superTabs/routeRecord.ts`
+ and their specs.
+
+## Design
+
+- growth: no new collection or row. Each stored candidate gains `status`, `left` and `resetsAt`, about 50 bytes; a
+ 64-candidate decision grows by about 3 KB. `SuperTabRouteDecision` keeps its existing removal (unchanged here).
+- concurrency: N/A because the record is written once per route, as before.
+- read cost: N/A because no reader or query changes; readers read the same row.
+- scale: at 10x routes the decision rows grow linearly; the collection's data size is the metric that warns first, as
+ for #2769.
+- compatibility: a backend from before this refuses `left`/`resetsAt` (strict schema); the CLI then records the
+ `unquoted` shape, which it accepts. Old rows lack the fields; `KeptFit` marks them optional and no reader requires
+ them.
+- migration + rollback: none; rolling back the CLI stops sending the fields, rolling back the backend refuses them and
+ the CLI falls back.
+- audience: unchanged; the route log's readers are as before.
+- identity: N/A because no login is used.
+- failure: a refused record falls back shape by shape as before and the route still answers.
+- platforms: CLI on macOS, Linux and Windows; the change is pure TypeScript.
+
+## Review Focus
+
+- The tier rule matches the Routing rules: small/low/medium vs big/hard/risky/security/review.
+- No slot loses its only row: a slot with no tier row keeps its neutral first row.
+- The record shape fallback order and that an older backend still records a decision.
+
+## Tasks
+
+### Task 1: each slot offers the model the task's size calls for
+
+**Files:** `cli/src/superTabs/route.ts`, `cli/src/superTabs/route.spec.ts`
+
+**Interfaces:** `Assessment.unsized?: true`; `choose` unchanged in signature.
+
+- [ ] Red: a small task over machines offering Opus high, Opus xhigh, Sonnet high, Astra xhigh and Sol high shows
+ Sonnet high and Sol high on every machine, never Opus or Astra.
+- [ ] Red: a large task, a high-risk task and a security/review kind show Opus high and Astra xhigh.
+- [ ] Red: an unsized task keeps both models of each slot.
+- [ ] Red: a real-shaped list (production machine names, members on Opus and Sonnet, grid rows, 20+ machines) gives the
+ counts per model the rules call for.
+- [ ] Commit the red tests; watch them fail.
+- [ ] Green: `tierOf`, `TIER_MODELS`, rank in `withEveryAccount`, `unsized` in `parseAssessment`. Run route specs.
+
+### Task 2: each candidate's quota fit is stored in the route decision
+
+**Files:** `cli/src/superTabs/route.ts`, `cli/src/superTabs/routeCommand.ts`, `cli/src/superTabs/route.spec.ts`,
+`cli/src/superTabs/routeCommand.spec.ts`, `backend/src/superTabs/routeRecord.ts`, `backend/src/superTabs/routeRecord.test.ts`
+
+**Interfaces:** record fit `left: number | null`, `resetsAt: number | null`; `RecordShape` adds `unquoted`.
+
+- [ ] Red: `recordOf` carries each candidate's status, weekly % left and reset; `unquoted` and older shapes do not.
+- [ ] Red: the backend schema accepts them and `storedRecord` keeps status, left and reset of every candidate of a
+ record without a pick.
+- [ ] Red: routeCommand retries a refused record as `unquoted` before `picked`.
+- [ ] Commit the red tests; watch them fail.
+- [ ] Green: schema, `storedRecord`, `KeptFit`, `recordOf`, the fallback. Run route, routeCommand and routeRecord tests,
+ then the backend unit suite.
diff --git a/docs/plans/2026-11-05-speed-marks-plan.md b/docs/plans/2026-11-05-speed-marks-plan.md
new file mode 100644
index 000000000..ae2514775
--- /dev/null
+++ b/docs/plans/2026-11-05-speed-marks-plan.md
@@ -0,0 +1,37 @@
+# Speed marks: launch, big-chat load and image load — Plan
+
+**Goal:** A repeatable measurement of the three things Huy's speed plan (A) needs before any B or C change: the time from opening Desktop to a painted chat, the time to load messages in a large chat (first page and scroll-up pages), and the time and bytes of each image in an image-heavy chat.
+**Architecture:** One small recorder (`SpeedMarks`, `lib/measurement/speed_marks.dart`) that the launch path, the Swarm chat controller and the attachment image provider call. It writes one `speed` line per mark to the app log that Desktop already keeps (`~/.harness/logs/app-YYYYMMDD.log`), counts and milliseconds only. A pure-Dart report builder (`speed_report.dart`) turns those lines into the table with the three slowest steps, and `tool/speed_report.dart` prints it from the real log.
+**Tech Stack:** Flutter/Dart (Desktop), `flutter_test`.
+**Spec:** Task #3176 (Huy, 2026-11-05: before and after numbers for each speed task).
+
+## Design
+- growth: marks are logged to the daily app log (DEBUG, the log's batched path), pruned after 14 days like every other line; a launch step is logged once per launch, messages only for first-page and scroll-up reads (polls are not logged), images once per fetch; the report reads only the last launch.
+- concurrency: single UI isolate; no locks.
+- read cost: no reads at runtime; the report tool reads the log files on request.
+- scale: 10x chat size changes row counts, not the number of lines per read; the log line rate is bounded by pages read and images shown.
+- compatibility: a new log category only; old tools ignore it.
+- migration + rollback: none; remove the calls to roll back.
+- audience: local file on the person's own Mac; no network, nothing is reported.
+- identity: no ids, names or paths in a line (steps, kinds, counts, milliseconds and bytes only).
+- failure: a failed logging call is swallowed and never blocks the product; a failed image records `failed`.
+- platforms: all native targets; the web build records in memory only.
+
+## Global Constraints
+- No new settings. Measurement never carries content, paths or identifiers, and never blocks or slows the product (ENGINEERING.md).
+- Tests use a memory store and a fake sign-in; nothing signs the real CLI in or out.
+- Swarm code stays out of cli/src/core.
+
+## Review Focus
+- Marks never change behavior (a mark call that throws must not break a read or a paint).
+- Nothing identifying in a line.
+- The report names the three slowest steps from real log lines.
+
+## Tasks
+- [ ] 1. `SpeedMarks` recorder: test — a launch step is kept once, in order, in milliseconds since launch; a messages mark keeps kind, rows, request ms and total ms; an image mark keeps bytes and ms; every line names no id; a sink that throws is swallowed.
+- [ ] 2. Report builder: test — lines in, table out; the three slowest launch steps and the three slowest message reads are named by the time each step took after the one before it.
+- [ ] 3. Hook the launch path (`app_shell.dart`, `main.dart`, `AppNotifier._markStartup`) and the first painted chat row (`super_tabs/view.dart`): test — `_markStartup` steps reach the recorder; a built chat row marks first chat once.
+- [ ] 4. Hook message reads (`super_tabs/controller.dart` `_loadMessages`): test — a latest-page read and an older-page read each record rows and times; a poll that adds nothing records none.
+- [ ] 5. Hook image fetches (`super_tabs/attachment_viewer.dart` `AttachmentImage`): test — a fetched picture records its bytes and time; a failed one records `failed`.
+- [ ] 6. `tool/speed_report.dart` prints the report from `~/.harness/logs`; document the run in `desktop/README.md`.
+- [ ] 7. Run it on a real Mac and post the table in the task's conversation.
diff --git a/docs/plans/2026-11-05-workspace-invitation-revoke-plan.md b/docs/plans/2026-11-05-workspace-invitation-revoke-plan.md
new file mode 100644
index 000000000..73f3a5062
--- /dev/null
+++ b/docs/plans/2026-11-05-workspace-invitation-revoke-plan.md
@@ -0,0 +1,80 @@
+# Workspace removal is final, and a pending Workspace invitation can be revoked (task #3173) Plan
+
+> Worked by the Engineer, test first (superpowers test-driven-development): each task's failing test is committed and
+> seen red before the code that passes it.
+
+**Goal:** A person removed from a Workspace cannot come back on an invitation sent before the removal, and owners and
+admins can withdraw a pending Workspace invitation.
+
+**Architecture:** `SwarmWorkspaces.remove` deletes the removed person's `SwarmWorkspaceInvitation` in the removal's
+transaction. `SwarmWorkspaces.accept` also refuses an invitation sent before the person's latest removal from that
+Workspace (an invitation pending from before this fix). A new `SwarmWorkspaces.revokeInvitation`, served by
+`POST /api/super-tabs/workspaces/:workspaceId/invitations/revoke`, deletes a pending invitation for owners and admins,
+limited to roles they may give (`mayAssignRole`).
+
+**Tech Stack:** TypeScript, Fastify, Prisma on MongoDB, vitest with a real Mongo replica set (`npm run test:super-tabs`).
+
+**Spec:** task #3173 brief; docs/plans/2026-10-27-swarm-workspaces.md (Growth: "accepted or revoked: deleted").
+
+## Global Constraints
+
+- Owned files only: `backend/src/superTabs/workspaceStore.ts`, `backend/src/routes/superTabs.ts`,
+ `backend/integration/superTabWorkspaces.test.ts` (and this plan).
+- No schema change. The invitation has no creation time; it is derived from `expiresAt - INVITATION_MS`, which is
+ exact because `invite` sets (and every resend moves) `expiresAt` to send time plus `INVITATION_MS`.
+- A POST, not a DELETE: Desktop reaches the backend through the daemon, which forwards only GET and POST.
+- Access control is under the two-security-review rule.
+
+## Design
+
+- growth: no new record; revoke and removal delete an invitation (the plan's Growth row "accepted or revoked: deleted").
+- concurrency: each action is one Mongo transaction. Remove's invitation delete and a concurrent invite's upsert write
+ the same document, so Mongo aborts one as a write conflict. An invitation sent after the removal is a new, deliberate
+ one and is accepted; one sent before it is refused at accept even if it survived (pending from before this fix).
+- read cost: accept reads one more document (the newest removal of that person in that Workspace, by the
+ `workspaceId, userId, finishedAt` index prefix); revoke reads one invitation by id.
+- scale: unchanged at 10x; per-person reads only.
+- compatibility: old clients never call revoke; accept answers 404 as for any unavailable invitation.
+- migration + rollback: none. Rolling back restores today's behaviour; deleted invitations stay deleted (they were
+ either withdrawn or belonged to a removed person).
+- audience: the server checks the Workspace role (`workspace.invite`) and `mayAssignRole` for the invitation's role.
+- identity: the signed-in person (`personOnly`), never the machine owner's login.
+- failure: refusals answer 404 (no such pending invitation) or 403 (role), with a message.
+- platforms: backend only; Desktop and phone Revoke buttons are a follow-up.
+
+## Review Focus
+
+- `revokeInvitation`: a member or guest gets 403, an outsider 404, an admin cannot revoke an admin invitation.
+- `accept`: the removal-time comparison, and that an invitation for someone never removed is accepted as before.
+- `remove`: the delete is in the same transaction as `removedAt`.
+
+## Task 1: Removal deletes the pending invitation, and accept refuses one sent before the removal
+
+**Files:** `backend/integration/superTabWorkspaces.test.ts`, `backend/src/superTabs/workspaceStore.ts`
+
+**Interfaces:** none new.
+
+- [ ] Test: invite a member's address again as admin (pending), remove the member, accept answers 404, the member row
+ keeps `removedAt`, and no invitation is left.
+- [ ] Test: an invitation pending from before the fix (written back after the removal, as an old removal left it)
+ answers 404 at accept; a new invitation sent after the removal is accepted.
+- [ ] Test: an invitation for someone never removed is accepted as today.
+- [ ] Run them red: `npm run test:super-tabs -- integration/superTabWorkspaces.test.ts`.
+- [ ] Code: `remove` deletes `${workspaceId}:${target.email}` in its transaction; `accept` reads the person's newest
+ removal and refuses an invitation sent before it.
+- [ ] Run them green.
+
+## Task 2: Owners and admins revoke a pending invitation
+
+**Files:** `backend/integration/superTabWorkspaces.test.ts`, `backend/src/superTabs/workspaceStore.ts`,
+`backend/src/routes/superTabs.ts`
+
+**Interfaces:** `SwarmWorkspaces.revokeInvitation(user, workspaceId, email): Promise<{ email: string; revoked: true }>`;
+`POST /api/super-tabs/workspaces/:workspaceId/invitations/revoke` with body `{ email }`.
+
+- [ ] Test: owner revokes an admin invitation, it leaves the people list's invitations and accept answers 404; a member
+ and a guest get 403, an outsider 404; an admin gets 403 on an admin invitation and 200 on a guest one; revoking
+ a missing invitation answers 404.
+- [ ] Run red.
+- [ ] Code: the method and the route.
+- [ ] Run green, then the backend unit suite (`npm test`).