Skip to content

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

Batch: 15 reviewed PRs (#1868 #1869 #1871 #1878 #1879 #1883 #1884 #1885 #1886 #1887 #1890 #1893 #1894 #1895 #1896) (#1891)

0xken15fefeeb602277
diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml
index c99679691..b03753cf8 100644
--- a/.github/workflows/windows.yml
+++ b/.github/workflows/windows.yml
@@ -168,7 +168,7 @@ jobs:
# serialWindows.spec.ts runs the real harness-serial.exe, placed beside the host by the payload step.
HARNESS_SERIAL_BIN: ${{ github.workspace }}\pty\target\${{ matrix.target }}\release\harness-serial.exe
run: |
- $paths = @('src/lib/ptyHostBackend.contract.spec.ts', 'src/lib/ptyHost', 'src/lib/windows', 'src/scripts/windowsCiChecks.spec.ts', 'src/lib/uninstall', 'src/engines/kit/hookRemoval.spec.ts', 'src/engines/kit/windowsHooks.spec.ts', 'src/engines/kit/windowsFiles.spec.ts', 'src/engines/kit/nativePaths.windows.spec.ts', 'src/engines/kit/launchExecutable.windows.spec.ts', 'src/engines/removeHooks.spec.ts', 'src/engines/windowsHomes.spec.ts', 'src/cable/windowsSerial.spec.ts', 'src/cable/serialWindows.spec.ts')
+ $paths = @('src/lib/ptyHostBackend.contract.spec.ts', 'src/lib/ptyHost', 'src/lib/windows', 'src/scripts/windowsCiChecks.spec.ts', 'src/lib/uninstall', 'src/engines/kit/hookRemoval.spec.ts', 'src/engines/kit/windowsHooks.spec.ts', 'src/engines/kit/windowsFiles.spec.ts', 'src/engines/kit/nativePaths.windows.spec.ts', 'src/engines/kit/launchExecutable.windows.spec.ts', 'src/dsh/runtime.windows.spec.ts', 'src/engines/removeHooks.spec.ts', 'src/engines/windowsHomes.spec.ts', 'src/cable/windowsSerial.spec.ts', 'src/cable/serialWindows.spec.ts')
npx vitest run @paths --maxWorkers=1
# Two real builds (sub-project G): the rollover from the previous host to this one (hostMove.real.spec.ts, and
# drain.spec.ts's two-build case), and the payload install (the bin\ replacement, and install.ps1 in Windows
diff --git a/backend/Dockerfile.k8s b/backend/Dockerfile.k8s
index defea1630..177a12b39 100644
--- a/backend/Dockerfile.k8s
+++ b/backend/Dockerfile.k8s
@@ -79,7 +79,8 @@ USER backend
EXPOSE 8085 8087
# `exec` replaces the shell, so node ends up as PID 1 and receives SIGTERM directly; both entry
-# points shut down on it (server.ts closes the listeners, then DRAINS open websockets with a 1012
-# close + ~4s grace before quitting Redis, so give the api terminationGracePeriodSeconds >= 10 too;
+# points shut down on it (server.ts answers /api/ready 503 and keeps serving for DRAIN_DELAY_MS, then
+# closes the listeners and DRAINS open websockets with a 1012 close + ~4s grace before quitting Redis,
+# so give the api terminationGracePeriodSeconds >= DRAIN_DELAY_MS + 10s; see README.md for the probes;
# worker.ts stops the billing loop and hard-exits after 5s, so the job also needs >= 10).
CMD ["sh", "-c", "case \"$APP\" in api) exec node dist/server.js ;; job) exec node dist/worker.js ;; *) echo \"FATAL: unknown APP='$APP' (expected 'api' or 'job')\" >&2; exit 1 ;; esac"]
diff --git a/backend/README.md b/backend/README.md
index f3610f8ce..1308e76b4 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -100,6 +100,48 @@ Redis side set it to at least `64mb 16mb 60` and alert on `client_recent_max_out
app-proxy channels ride their own subscriber connection (`appSub` in `bus.ts`), so a disconnect there
cannot take the chat / presence subscriptions down with it.
+### Liveness, readiness and drain
+
+`/api/health` is liveness: the process answers, with no dependency calls, so a Mongo or Redis outage
+never makes Kubernetes restart pods. `/api/ready` is readiness (`src/lib/readiness.ts`): 200 while Mongo
+answers a `ping` and Redis a `PING` (Redis only where `REDIS_URL` is set), each within 1 s; 503 naming
+the failed or timed-out one otherwise. One answer serves every probe for 1 s, so probes add at most one
+ping per dependency per second per process. From the moment a process gets SIGTERM, `/api/ready` answers
+503 `draining`, and it keeps serving for `DRAIN_DELAY_MS` (default 0, closing at once as before) before it
+closes its listeners, drains its WebSockets and disconnects Mongo and Redis.
+
+Set `DRAIN_DELAY_MS` only on the Kubernetes image (`Dockerfile.k8s`), never under pm2: in cluster mode a probe
+reaches whichever worker the master picks, so one worker's 503 says nothing, and pm2 kills a worker that has not
+exited within `kill_timeout` (10 s, `ecosystem.config.cjs`).
+
+Settings for the `api` Deployment (the `job` Deployment serves no HTTP and has no probes):
+
+```yaml
+terminationGracePeriodSeconds: 30 # DRAIN_DELAY_MS + up to ~10 s of socket drain and close, plus margin
+containers:
+ - name: backend
+ env:
+ - name: DRAIN_DELAY_MS
+ value: "15000" # readiness needs up to 10 s to fail, then the ingress a few more to drop
+ # the pod. No preStop sleep: the process keeps serving on its own
+ startupProbe:
+ httpGet: { path: /api/health, port: 8085 }
+ periodSeconds: 2
+ timeoutSeconds: 2
+ failureThreshold: 30 # up to 60 s to start listening
+ livenessProbe:
+ httpGet: { path: /api/health, port: 8085 }
+ periodSeconds: 10
+ timeoutSeconds: 3
+ failureThreshold: 3 # restart only after ~30 s without an answer (a stuck event loop)
+ readinessProbe:
+ httpGet: { path: /api/ready, port: 8085 }
+ periodSeconds: 5
+ timeoutSeconds: 2 # above the 1 s dependency timeout
+ successThreshold: 1
+ failureThreshold: 2 # out of rotation within ~10 s of an outage or a drain
+```
+
## Connector gateway
`routes/connectors.ts`, `lib/connectorGateway.ts`: sign-in to GitHub, Slack, Asana, HubSpot, Gmail,
diff --git a/backend/integration/bench/README.md b/backend/integration/bench/README.md
index c80035328..5e9d7bb6e 100644
--- a/backend/integration/bench/README.md
+++ b/backend/integration/bench/README.md
@@ -43,6 +43,16 @@ NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
DATABASE_URL=mongodb://127.0.0.1:1/bench-never-used npx tsx integration/bench/pollDatabaseBytes.ts
```
+To see what a migrated Swarm's kept old state (`SuperTab.legacyState`, about 1 MB in production) costs each read, run
+the old state diagnostic. It gives the benchmark's Swarm a 1 MB old state, then times the Lead's status, a host's delivery
+poll with nothing waiting (the empty read) and one post, 30 times each, with the old state kept and once it is removed,
+and prints the median time and what MongoDB sent the backend per read. It takes the same options:
+
+```bash
+NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= \
+ DATABASE_URL=mongodb://127.0.0.1:1/bench-never-used npx tsx integration/bench/oldStateReads.ts
+```
+
The bench's own tests (helpers, plus a short run of the whole scenario), and its typecheck:
```bash
diff --git a/backend/integration/bench/oldStateReads.ts b/backend/integration/bench/oldStateReads.ts
new file mode 100644
index 000000000..a6fb3dbb7
--- /dev/null
+++ b/backend/integration/bench/oldStateReads.ts
@@ -0,0 +1,77 @@
+import { performance } from 'node:perf_hooks'
+import { SuperTabStore } from '../../src/superTabs/store.js'
+import { SWEEP_EVERY_MS } from '../../src/superTabs/liveness.js'
+import * as parts from '../../src/superTabs/parts/index.js'
+import { AttemptCounter } from './attempts.js'
+import { DRIVERS } from './bench.js'
+import { parseArgs } from './config.js'
+import { seedAccounts } from './fixtures.js'
+import { localDatabase } from './mongo.js'
+import { plan } from './plan.js'
+import { bytesOut } from './probe.js'
+import { seedSwarm } from './seed.js'
+
+/** A migrated production Swarm keeps its whole old state beside its parts, about 1 MB (roadmap, Stability 2.1). */
+const OLD_STATE_BYTES = 1_000_000
+const RUNS = 30
+
+/**
+ * What an up-to-date read of a migrated Swarm costs while its row still keeps the old state from before parts (design
+ * 6.1: `SuperTab.legacyState`), and once that state is gone. Seeds the benchmark's Swarm on its own loopback replica set,
+ * gives its row a 1 MB old state built from copies of its own state, then times each read alone, RUNS times, as the store
+ * serves it: the Lead's status, a host's full delivery poll with nothing waiting (the empty read), and one post. Prints
+ * the median time and what MongoDB sent the backend per read. Takes the benchmark's options. From `backend/`:
+ *
+ * NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= \
+ * DATABASE_URL=mongodb://127.0.0.1:1/bench-never-used npx tsx integration/bench/oldStateReads.ts
+ */
+async function main() {
+ const { config, driver: driverName } = parseArgs(process.argv.slice(2))
+ const database = await localDatabase()
+ const { db } = database
+ try {
+ const people = await seedAccounts(db, config.machines)
+ const driver = await DRIVERS[driverName]!(new AttemptCounter().wrap(db), () => people)
+ const { swarm } = await seedSwarm(driver, config, plan(config), people)
+ await driver.close()
+ // Each delivery poll is a full one: the store answers a poll repeated within SWEEP_EVERY_MS from one indexed read.
+ let now = Date.now()
+ const store = new SuperTabStore(db, () => now)
+ const lead = people[0]!, worker = swarm.workers[0]!, host = people[worker.machine]!
+ const state = parts.toLegacyState(parts.reassemble(await db.$transaction(tx => parts.loadAll(tx, swarm.tabId))))
+ const copies = Math.ceil(OLD_STATE_BYTES / JSON.stringify(state).length)
+ const oldState = JSON.parse(JSON.stringify({ copies: Array.from({ length: copies }, () => state) }))
+ const before = await bytesOut(db)
+ const ownReply = await bytesOut(db) - before
+ let posts = 0
+ const reads: Array<[string, () => Promise<unknown>]> = [
+ ['Lead status', () => store.read(lead, swarm.tabId, swarm.leadId)],
+ ['empty read: delivery poll, nothing waiting', () => { now += SWEEP_EVERY_MS; return store.deliveries(host, swarm.tabId, worker.id) }],
+ ['one post', () => store.execute(lead, swarm.tabId, { operationId: `old-state-post-${++posts}`,
+ command: { type: 'message.send', conversationId: worker.group, text: 'One post.', replyTo: null, recipientIds: [] } })],
+ ]
+ const median = (values: number[]) => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)]!
+ for (const [kept, legacyState] of [['old state kept', oldState], ['old state removed', null]] as const) {
+ await db.superTab.update({ where: { id: swarm.tabId }, data: { legacyState } })
+ for (const [label, read] of reads) {
+ await read()
+ const ms: number[] = [], bytes: number[] = []
+ for (let i = 0; i < RUNS; i++) {
+ const start = await bytesOut(db), started = performance.now()
+ await read()
+ ms.push(performance.now() - started)
+ bytes.push(Math.max(0, await bytesOut(db) - start - ownReply))
+ }
+ process.stdout.write(`${JSON.stringify({ kept, read: label, oldStateBytes: legacyState ? JSON.stringify(legacyState).length : 0,
+ medianMs: Number(median(ms).toFixed(2)), medianDatabaseKB: Number((median(bytes) / 1024).toFixed(1)) })}\n`)
+ }
+ }
+ } finally {
+ await database.stop()
+ }
+}
+
+main().catch(error => {
+ process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`)
+ process.exitCode = 1
+})
diff --git a/backend/integration/bench/probe.ts b/backend/integration/bench/probe.ts
index bea0d859b..1f26acb07 100644
--- a/backend/integration/bench/probe.ts
+++ b/backend/integration/bench/probe.ts
@@ -20,7 +20,8 @@ function count(value: unknown): number {
throw new Error(`Not a number: ${JSON.stringify(value)}`)
}
-async function bytesOut(db: PrismaClient): Promise<number> {
+/** What MongoDB has sent its clients so far (`serverStatus` network bytes out). */
+export async function bytesOut(db: PrismaClient): Promise<number> {
const status = await db.$runCommandRaw({ serverStatus: 1 }) as { network: { bytesOut: unknown } }
return count(status.network.bytesOut)
}
diff --git a/backend/integration/shareRaces.test.ts b/backend/integration/shareRaces.test.ts
new file mode 100644
index 000000000..ff456217b
--- /dev/null
+++ b/backend/integration/shareRaces.test.ts
@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'
+import Fastify, { type FastifyInstance } from 'fastify'
+import type { PrismaClient } from '@prisma/client'
+
+// Telling other apps goes through Redis; nothing here depends on it being told.
+vi.mock('../src/lib/bus.js', () => ({ publishAgentMessageShareChanged: vi.fn(async () => 0), publishDeskChanged: vi.fn(async () => 0),
+ publishDeviceMachineListChanged: vi.fn(async () => 0), publishMachineShareChanged: vi.fn(async () => 0) }))
+
+// A fresh loopback replica set, created here. This suite never reads an existing database: the app's own Prisma client
+// is pointed at it before anything imports it.
+let replica: MongoMemoryReplSet
+let db: PrismaClient
+let app: FastifyInstance
+const owner = { sub: '6a0000000000000000000a01', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
+const guest = { sub: '6a0000000000000000000a02', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
+const TRIES = 40
+
+beforeAll(async () => {
+ replica = await MongoMemoryReplSet.create({ binary: { version: '7.0.24', downloadDir: join(tmpdir(), 'harness-super-tab-mongodb-binaries') },
+ replSet: { count: 1, ip: '127.0.0.1', storageEngine: 'wiredTiger' } })
+ const uri = replica.getUri(`share_races_${randomUUID().replaceAll('-', '_')}`)
+ await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], {
+ env: { ...process.env, DATABASE_URL: uri }, timeout: 60000,
+ })
+ process.env.DATABASE_URL = uri
+ vi.resetModules()
+ db = (await import('../src/lib/prisma.js')).prisma
+ const { errorHandler } = await import('../src/middlewares/errorHandler.js')
+ const { agentMessagesRoutes } = await import('../src/routes/agentMessages.js')
+ const { machineShareRoutes } = await import('../src/routes/machineShares.js')
+ for (const each of [owner, guest]) await db.user.create({ data: { id: each.sub, externalId: `fixture-${each.sub}`, email: each.email, autonomousEnv: 'prod' } })
+ app = Fastify()
+ app.setErrorHandler(errorHandler)
+ app.addHook('onRequest', async (request, reply) => {
+ const found = [owner, guest].find(u => `Bearer ${u.sub}` === request.headers.authorization)
+ if (!found) return reply.code(401).send({ success: false })
+ request.user = found as never
+ })
+ await app.register(agentMessagesRoutes)
+ await app.register(machineShareRoutes)
+ await app.ready()
+}, 120000)
+afterAll(async () => {
+ await app?.close()
+ await db?.$disconnect()
+ await replica?.stop()
+})
+
+const send = (as: typeof owner, method: 'POST' | 'PUT', url: string, payload?: unknown) =>
+ app.inject({ method, url, payload: payload as never, headers: { authorization: `Bearer ${as.sub}` } })
+/** The same request, sent TRIES times at once. */
+const together = (request: () => ReturnType<typeof send>) => Promise.all(Array.from({ length: TRIES }, request))
+
+/** A shared conversation tab of the owner's, on a machine of theirs. */
+async function sharedTab() {
+ const machineId = randomUUID().replaceAll('-', '')
+ await db.machine.create({ data: { machineId, userId: owner.sub, apiKey: 'fixture-only', managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })
+ const put = await send(owner, 'PUT', `/api/agent-messages/shares/tab-${randomUUID().slice(0, 8)}/roster`, { machineId, version: 1, roster: { body: '{"name":"Race"}', signature: 's' } })
+ expect(put.statusCode).toBe(200)
+ return { machineId, sharedTabId: put.json().data.sharedTabId as string }
+}
+
+describe('identical requests at the same moment', () => {
+ it('inviting the same address to a shared tab answers one invitation to every request', async () => {
+ const { sharedTabId } = await sharedTab()
+ const answers = await together(() => send(owner, 'POST', `/api/agent-messages/shares/${sharedTabId}/invites`, { email: guest.email, days: 7 }))
+ expect(answers.map(a => a.statusCode)).toEqual(Array(TRIES).fill(200))
+ const ids = new Set(answers.map(a => a.json().data.id))
+ expect(ids.size).toBe(1)
+ expect(await db.agentMessageInvite.count({ where: { shareId: sharedTabId } })).toBe(1)
+ })
+
+ it('accepting the same invitation twice makes one member and answers every request', async () => {
+ const { sharedTabId } = await sharedTab()
+ const id = (await send(owner, 'POST', `/api/agent-messages/shares/${sharedTabId}/invites`, { email: guest.email, days: 7 })).json().data.id
+ const answers = await together(() => send(guest, 'POST', `/api/agent-messages/invites/${id}/accept`))
+ // Each answers the shared tab, or that the invitation was already used; none is a 500.
+ for (const answer of answers) expect([200, 404]).toContain(answer.statusCode)
+ expect(answers.filter(a => a.statusCode === 200).length).toBeGreaterThanOrEqual(1)
+ for (const ok of answers.filter(a => a.statusCode === 200)) expect(ok.json().data).toEqual({ sharedTabId })
+ expect(await db.agentMessageMember.count({ where: { shareId: sharedTabId, removedAt: null } })).toBe(1)
+ })
+
+ it('adding yourself to a machine shared with your domain adds you once and answers every request', async () => {
+ const machineId = randomUUID().replaceAll('-', '')
+ await db.machine.create({ data: { machineId, userId: owner.sub, apiKey: 'fixture-only', managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })
+ expect((await send(owner, 'PUT', `/api/machines/${machineId}/share`, { emails: [], sameDomain: true })).statusCode).toBe(200)
+ const answers = await together(() => send(guest, 'POST', `/api/machine-shares/${machineId}/add`))
+ expect(answers.map(a => a.statusCode)).toEqual(Array(TRIES).fill(200))
+ for (const answer of answers) expect(answer.json().data).toEqual({ added: true })
+ expect(await db.machineShareAdd.count({ where: { machineId, userId: guest.sub } })).toBe(1)
+ })
+})
diff --git a/backend/integration/superTabLegacyDrop.test.ts b/backend/integration/superTabLegacyDrop.test.ts
new file mode 100644
index 000000000..f4f0a1c8c
--- /dev/null
+++ b/backend/integration/superTabLegacyDrop.test.ts
@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'
+import { PrismaClient } from '@prisma/client'
+import * as parts from '../src/superTabs/parts/index.js'
+import { migrateSwarm } from '../src/superTabs/migration/migrate.js'
+import { dropLegacyStates } from '../src/superTabs/migration/dropLegacy.js'
+import { writeLegacySwarm } from '../scripts/swarm-parts/legacy.js'
+import { NOW, richSwarm } from '../src/superTabs/read/fixture.test-support.js'
+
+// A fresh loopback replica set, created here. This suite never reads DATABASE_URL or an existing database. Each test
+// starts from an empty database: the script's first check spans every Swarm.
+let replica: MongoMemoryReplSet
+let db: PrismaClient
+
+beforeAll(async () => {
+ replica = await MongoMemoryReplSet.create({ binary: { version: '7.0.24', downloadDir: join(tmpdir(), 'harness-super-tab-mongodb-binaries') },
+ replSet: { count: 1, ip: '127.0.0.1', storageEngine: 'wiredTiger' } })
+ const uri = replica.getUri(`swarm_legacy_drop_test_${randomUUID().replaceAll('-', '_')}`)
+ await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], {
+ env: { ...process.env, DATABASE_URL: uri }, timeout: 60000,
+ })
+ db = new PrismaClient({ datasources: { db: { url: uri } } })
+})
+afterAll(async () => {
+ await db?.$disconnect()
+ await replica?.stop()
+})
+
+/** One kept old state of a known size: a document holding one 100,000-character string. */
+const OLD_STATE = { padding: 'x'.repeat(100_000) }
+/** Its BSON size by hand: length 4, then the field (type 1, "padding" and its 0: 8, string length 4, the string and its 0:
+ * 100,001), then the closing 0. */
+const OLD_STATE_BYTES = 4 + 1 + 8 + 4 + 100_001 + 1
+
+async function legacySwarm() {
+ const state = structuredClone(richSwarm().state)
+ state.id = `tab-${randomUUID()}`
+ await writeLegacySwarm(db, { state, revision: 500 })
+ return state.id
+}
+/** A Swarm split into parts that still keeps its old state, as production Swarms do since the migration. */
+async function migratedSwarm() {
+ const tabId = await legacySwarm()
+ expect((await migrateSwarm(db, tabId, { now: () => NOW })).ok).toBe(true)
+ await db.superTab.update({ where: { id: tabId }, data: { legacyState: OLD_STATE } })
+ return tabId
+}
+async function empty() {
+ for (const model of [db.superTab, db.superTabMessage, db.swarmHead, db.swarmMember, db.swarmAgent, db.swarmGroup, db.swarmMachine,
+ db.swarmStart, db.swarmProgress] as unknown as Array<{ deleteMany(args: unknown): Promise<unknown> }>) await model.deleteMany({})
+}
+const kept = async (tabId: string) => (await db.superTab.findUnique({ where: { id: tabId }, select: { legacyState: true } }))!.legacyState
+
+describe('removing the old state migrated Swarms keep (Stability 2.1)', () => {
+ it('refuses while any Swarm is still in one row, even to remove, and writes nothing', async () => {
+ await empty()
+ const migrated = await migratedSwarm()
+ await legacySwarm()
+
+ for (const apply of [false, true]) {
+ expect(await dropLegacyStates(db, { apply })).toEqual({ ok: false, swarms: 2, unmigrated: 1, kept: 1, keptBytes: OLD_STATE_BYTES, removed: 0, batches: 0, writeErrors: 0 })
+ }
+ expect(await kept(migrated)).toEqual(OLD_STATE)
+ })
+
+ it('counts a Swarm whose row predates the format field as not migrated', async () => {
+ await empty()
+ await migratedSwarm()
+ const old = await legacySwarm()
+ await db.$runCommandRaw({ update: 'SuperTab', updates: [{ q: { _id: old }, u: { $unset: { format: '' } } }] })
+
+ expect(await dropLegacyStates(db, { apply: true })).toMatchObject({ ok: false, unmigrated: 1, removed: 0 })
+ })
+
+ it('by default only reports how many Swarms keep an old state and its size, and writes nothing', async () => {
+ await empty()
+ const [first, second] = [await migratedSwarm(), await migratedSwarm()]
+ await db.superTab.create({ data: { id: `tab-${randomUUID()}`, ownerId: 'owner', autonomousEnv: 'prod', format: 2, state: { version: 2 } } })
+
+ expect(await dropLegacyStates(db)).toEqual({ ok: true, swarms: 3, unmigrated: 0, kept: 2, keptBytes: 2 * OLD_STATE_BYTES, removed: 0, batches: 0, writeErrors: 0 })
+ expect([await kept(first), await kept(second)]).toEqual([OLD_STATE, OLD_STATE])
+ })
+
+ it('stops at the first batch the database refuses, and counts its refused writes', async () => {
+ await empty()
+ const ids = [await migratedSwarm(), await migratedSwarm()]
+ // A validator that refuses any row without an old state, so every removal comes back as a write error.
+ await db.$runCommandRaw({ collMod: 'SuperTab', validator: { legacyState: { $exists: true } }, validationAction: 'error' })
+ try {
+ expect(await dropLegacyStates(db, { apply: true, batch: 1 })).toEqual({ ok: true, swarms: 2, unmigrated: 0, kept: 2, keptBytes: 2 * OLD_STATE_BYTES,
+ removed: 0, batches: 1, writeErrors: 1 })
+ } finally {
+ await db.$runCommandRaw({ collMod: 'SuperTab', validator: {}, validationLevel: 'off' })
+ }
+ expect(await Promise.all(ids.map(kept))).toEqual([OLD_STATE, OLD_STATE])
+ }, 10_000)
+
+ it('removes every kept old state in batches, leaving each Swarm\'s row and parts as they were', async () => {
+ await empty()
+ const ids = [await migratedSwarm(), await migratedSwarm(), await migratedSwarm()]
+ const snapshot = () => Promise.all(ids.map(async id => ({
+ row: await db.superTab.findUnique({ where: { id }, select: { format: true, revision: true, state: true, memberIds: true, migratedAt: true } }),
+ parts: await db.$transaction(tx => parts.loadAll(tx, id)) })))
+ const before = await snapshot()
+
+ expect(await dropLegacyStates(db, { apply: true, batch: 2 })).toEqual({ ok: true, swarms: 3, unmigrated: 0, kept: 3, keptBytes: 3 * OLD_STATE_BYTES, removed: 3, batches: 2, writeErrors: 0 })
+ expect(await db.$runCommandRaw({ count: 'SuperTab', query: { legacyState: { $exists: true } } })).toMatchObject({ n: 0 })
+ expect(await Promise.all(ids.map(kept))).toEqual([null, null, null])
+ expect(await snapshot()).toEqual(before)
+ // Run again, it finds nothing left.
+ expect(await dropLegacyStates(db, { apply: true })).toEqual({ ok: true, swarms: 3, unmigrated: 0, kept: 0, keptBytes: 0, removed: 0, batches: 0, writeErrors: 0 })
+ })
+})
diff --git a/backend/integration/superTabRead.test.ts b/backend/integration/superTabRead.test.ts
index 1d53448f2..c5bc2c8e7 100644
--- a/backend/integration/superTabRead.test.ts
+++ b/backend/integration/superTabRead.test.ts
@@ -333,6 +333,14 @@ describe('Swarm list and old routes (design 4.9, 4.11)', () => {
expect(body.data.tabs).toContainEqual({ id: s.tabId, name: 'Pilot', ownerId: owner.sub, workspaceId: null, paused: false, lastChangedAt: MIGRATED })
})
+ it('reads each Swarm\'s newest change over all its parts, without a groupBy (it once panicked the engine on Mongo)', async () => {
+ const [a, b] = [await scene(), await scene()]
+ await writeGroup(b.tabId, b.web, MIGRATED + 5_000, group => { group.title = 'Web, renamed' })
+ const newest = await db.$transaction(tx => parts.lastChangedAt(tx, [a.tabId, b.tabId, 'tab-with-no-parts']))
+ expect(Object.fromEntries(newest)).toEqual({ [a.tabId]: MIGRATED, [b.tabId]: MIGRATED + 5_000 })
+ expect((await db.$transaction(tx => parts.lastChangedAt(tx, []))).size).toBe(0)
+ })
+
it.each(['/api/super-tabs', '/api/super-tabs/TAB', '/api/super-tabs/hosts/host', '/api/super-tabs/hosts/host/pools', '/api/super-tabs/hosts/host/assignments'])(
'answers %s with 426 Update required', async url => {
const s = await scene()
@@ -1024,18 +1032,21 @@ describe('what a read costs the database (group 3b)', () => {
const s = await scene(f => { f.contribute(machineId, 'swarm') }, machineId)
const ops: string[] = []
const client = db.$extends({ query: { $allModels: { async $allOperations({ model, operation, args, query }) {
- ops.push(`${model}.${operation}`)
+ ops.push(`${model}.${operation}${operation === 'aggregateRaw' && JSON.stringify(args).includes('"$max"') ? ':max' : ''}`)
return query(args)
} } } }) as unknown as PrismaClient
const hosts = new HostReads(new SuperTabStore(client), { now: () => clock })
clock = Date.now()
+ // The newest change is one Mongo `$group` per part kind, and never a Prisma groupBy.
+ const newestReads = () => ops.filter(op => /^Swarm(Head|Member|Agent|Group|Machine|Start|Progress)\.aggregateRaw:max$/.test(op))
const first = await hosts.changes(owner, machineId, { full: true })
- expect(ops.filter(op => op.endsWith('.groupBy'))).toHaveLength(7)
+ expect(newestReads()).toHaveLength(7)
+ expect(ops.filter(op => op.endsWith('.groupBy'))).toEqual([])
ops.length = 0
clock = Date.now()
const idle = await hosts.changes(owner, machineId, { cursor: first.cursor })
expect(idle.tabs).toEqual([])
- expect(ops.filter(op => op.endsWith('.groupBy'))).toEqual([])
+ expect(newestReads()).toEqual([])
await new SuperTabStore(db).execute(owner, s.tabId, { operationId: randomUUID(),
command: { type: 'message.send', conversationId: s.web, text: 'Busy', replyTo: null, recipientIds: [] } })
clock = Date.now()
diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.ts
index fd07581b6..0da3aed59 100644
--- a/backend/integration/superTabs.test.ts
+++ b/backend/integration/superTabs.test.ts
@@ -3531,3 +3531,48 @@ describe('Swarm parts under concurrent writes', () => {
expect((await store.routeDecision(owner, tab, routeDecisionId)).final).toMatchObject({ kind: 'new', startId })
})
})
+
+describe('a migrated Swarm\'s kept old state (Stability 2.1)', () => {
+ /** About the 1 MB a production Swarm kept from before its split into parts (design 6.1: `SuperTab.legacyState`). */
+ const OLD_STATE = { conversations: Array.from({ length: 2_000 }, (_, i) => ({ id: `old-${i}`, title: 'x'.repeat(480) })) }
+ /** Far below the old state: a read that fetched it would send at least 1 MB. */
+ const READ_LIMIT = 200_000
+ const bytesOut = async () => Number(((await db.$runCommandRaw({ serverStatus: 1 })) as { network: { bytesOut: unknown } }).network.bytesOut)
+
+ it('is never fetched by a command, a read, the owner\'s lists, an invitation list or a host\'s terminal pickup', async () => {
+ const { tab, lead } = await fixture()
+ const invited: AuthUser = { sub: '100000000000000000000009', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
+ await run(tab, { type: 'invite.create', email: invited.email, role: 'viewer', conversationId: 'lead' })
+ const group = (await run(tab, { type: 'conversation.create', title: 'Terminal', brief: 'Answer the prompt', checks: [] })).result.conversationId as string
+ const worker = (await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: randomUUID(),
+ name: 'Terminal Engineer', configuration: config, lead: false })).result.agentId as string
+ await db.superTab.update({ where: { id: tab }, data: { legacyState: OLD_STATE } })
+
+ const fetched: string[] = []
+ /** Runs `body`, and names it when MongoDB sent this backend enough for the old state while it ran (bench/probe.ts). */
+ async function measured<T>(name: string, body: () => Promise<T>): Promise<T> {
+ const before = await bytesOut(), ownReply = await bytesOut() - before
+ const start = await bytesOut()
+ const result = await body()
+ if (await bytesOut() - start - ownReply >= READ_LIMIT) fetched.push(name)
+ return result
+ }
+ expect((await measured('command', () => run(tab, message('After the split')))).result.messageId).toBeTruthy()
+ expect((await measured('read', () => store.read(owner, tab))).state.agents.map(a => a.id).sort()).toEqual([lead, worker].sort())
+ expect(await measured('invitations', () => store.invitations(invited))).toEqual([expect.objectContaining({ tabId: tab, name: 'Pilot', role: 'viewer' })])
+ // The owner's lists read each of the owner's Swarms: an owner of this one alone, as the shared owner has many here.
+ const solo: AuthUser = { sub: '10000000000000000000000a', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
+ const own = (await store.create(solo, randomUUID(), 'Solo')).id
+ await db.superTab.update({ where: { id: own }, data: { legacyState: OLD_STATE } })
+ expect((await measured('list', () => store.list(solo))).tabs).toEqual([expect.objectContaining({ id: own, name: 'Solo', ownerId: solo.sub })])
+ expect(await measured('host grids', () => store.hostGrids(solo))).toEqual([expect.objectContaining({ tabId: own, enabled: true })])
+ expect(await measured('archive', () => store.archiveFinished(tab, group, []))).toBe(false)
+ const requestId = (await run(tab, { type: 'agent.screen', agentId: worker, scrollback: 20 }, host, lead)).result.requestId as string
+ expect((await measured('terminal pickup', () => store.hostTerminal(host, 'test-host'))).filter(row => row.tabId === tab).map(row => row.request.id))
+ .toEqual([requestId])
+ expect(fetched).toEqual([])
+
+ // Reads and writes leave it in place: only the maintenance script removes it.
+ for (const id of [tab, own]) expect((await db.superTab.findUnique({ where: { id }, select: { legacyState: true } }))!.legacyState).toEqual(OLD_STATE)
+ })
+})
diff --git a/backend/scripts/swarm-parts/drop-legacy-state.ts b/backend/scripts/swarm-parts/drop-legacy-state.ts
new file mode 100644
index 000000000..07014d195
--- /dev/null
+++ b/backend/scripts/swarm-parts/drop-legacy-state.ts
@@ -0,0 +1,34 @@
+/**
+ * Removes the old state every migrated Swarm still keeps beside its parts (Stability 2.1; src/superTabs/migration/dropLegacy.ts).
+ * It first checks that every Swarm is in parts and refuses otherwise. By default it only counts: how many Swarms keep an old
+ * state and how large it is. It prints counts and sizes only. Removing needs a database backup first, and both flags:
+ *
+ * DATABASE_URL=… node --import tsx scripts/swarm-parts/drop-legacy-state.ts # count only
+ * DATABASE_URL=… node --import tsx scripts/swarm-parts/drop-legacy-state.ts --apply --backup-confirmed [--batch 100]
+ */
+import { PrismaClient } from '@prisma/client'
+import { dropLegacyStates, dropOptions } from '../../src/superTabs/migration/dropLegacy.js'
+
+async function main() {
+ const options = dropOptions(process.argv.slice(2))
+ if (!process.env.DATABASE_URL) throw new Error('Set DATABASE_URL to the database to clean up.')
+ const db = new PrismaClient()
+ try {
+ const report = await dropLegacyStates(db, options)
+ console.log(JSON.stringify({ mode: options.apply ? 'apply' : 'dry run', ...report, keptMB: Number((report.keptBytes / 1_048_576).toFixed(1)) }))
+ if (!report.ok) {
+ console.error(`Refused: ${report.unmigrated} of ${report.swarms} Swarms are not in parts yet. Nothing was removed.`)
+ process.exitCode = 1
+ } else if (report.writeErrors) {
+ console.error(`Stopped: the database refused ${report.writeErrors} removals. ${report.removed} old states were removed before that.`)
+ process.exitCode = 1
+ } else if (!options.apply) console.log('Dry run: nothing was removed. After a backup, add --apply --backup-confirmed to remove them.')
+ } finally {
+ await db.$disconnect()
+ }
+}
+
+main().catch(error => {
+ console.error(error instanceof Error ? error.message : String(error))
+ process.exitCode = 1
+})
diff --git a/backend/src/analytics/dailyProductReview.test.ts b/backend/src/analytics/dailyProductReview.test.ts
index 201221c09..c83a237ee 100644
--- a/backend/src/analytics/dailyProductReview.test.ts
+++ b/backend/src/analytics/dailyProductReview.test.ts
@@ -203,3 +203,17 @@ it('zero-fills absent pairing and skip counters and uses the existing complete s
not_signed_in: 0, viewer: 0, card_showing: 0, no_storage: 0, account_changed: 0, read_limit: 0 },
})
})
+
+it('says why Desktop sign-ins that did not go through ended, beside the signed-out sign-in flow', () => {
+ const r = dailyProductReview([
+ row('2026-10-12', 'setup_desktop_sign_in_started', 6), row('2026-10-12', 'setup_desktop_sign_in_failed', 3),
+ row('2026-10-12', 'setup_desktop_sign_in_reason_no_result', 2), row('2026-10-12', 'setup_desktop_sign_in_reason_cancelled', 1),
+ row('2026-10-12', 'setup_desktop_sign_in_reason_timeout', 1), row('2026-10-11', 'setup_desktop_sign_in_reason_no_result', 1),
+ row('2026-10-12', 'setup_desktop_sign_in_reason_PRIVATE_CANARY', 9),
+ ], new Date('2026-10-13T12:00:00Z'))
+ const signIn = r.flows.find(f => f.channel === 'setup' && f.surface === 'desktop' && f.flow === 'sign_in')
+ expect(signIn).toMatchObject({ endReasons: { no_result: 3, cancelled: 1, timeout: 1, cli_unavailable: 0, other: 0 } })
+ expect(r.flows.find(f => f.channel === 'setup' && f.surface === 'phone' && f.flow === 'sign_in')).not.toHaveProperty('endReasons')
+ expect(r.flows.find(f => f.channel === 'setup' && f.surface === 'desktop' && f.flow === 'setup')).not.toHaveProperty('endReasons')
+ expect(JSON.stringify(r)).not.toContain('PRIVATE_CANARY')
+})
diff --git a/backend/src/analytics/dailyProductReview.ts b/backend/src/analytics/dailyProductReview.ts
index 4590d206c..93b11f1ef 100644
--- a/backend/src/analytics/dailyProductReview.ts
+++ b/backend/src/analytics/dailyProductReview.ts
@@ -1,4 +1,4 @@
-import { LAUNCH_ERROR_CODES, LAUNCH_ERROR_FAMILIES, PRODUCT_FEEDBACK, PRODUCT_FEEDBACK_REASONS, PRODUCT_FEEDBACK_OUTCOMES, PRODUCT_USAGE_ACTIONS, PRODUCT_USAGE_ADD_PHONE_OPENINGS, PRODUCT_USAGE_AUTOMATIC_ACTIONS, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_LONG_FLOWS, PRODUCT_USAGE_LONG_MEASURES, PRODUCT_USAGE_ONBOARDING_MARKS, PRODUCT_USAGE_PHONE_OFFER_SKIP_REASONS, PRODUCT_USAGE_SETUP_FLOWS, PRODUCT_USAGE_SURFACES, PRODUCT_USAGE_UI_SURFACES, PRODUCT_USAGE_USER_OPENED_ACTIONS } from '../types/productUsage.js'
+import { LAUNCH_ERROR_CODES, LAUNCH_ERROR_FAMILIES, PRODUCT_FEEDBACK, PRODUCT_FEEDBACK_REASONS, PRODUCT_FEEDBACK_OUTCOMES, PRODUCT_USAGE_ACTIONS, PRODUCT_USAGE_ADD_PHONE_OPENINGS, PRODUCT_USAGE_AUTOMATIC_ACTIONS, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_LONG_FLOWS, PRODUCT_USAGE_LONG_MEASURES, PRODUCT_USAGE_ONBOARDING_MARKS, PRODUCT_USAGE_PHONE_OFFER_SKIP_REASONS, PRODUCT_USAGE_SETUP_FLOWS, PRODUCT_USAGE_SIGN_IN_END_REASONS, PRODUCT_USAGE_SURFACES, PRODUCT_USAGE_UI_SURFACES, PRODUCT_USAGE_USER_OPENED_ACTIONS } from '../types/productUsage.js'
import { DAILY_PRODUCT_METRICS } from './dailyProductUsage.js'
type Row = { dayUtc: Date; metric: string; value: number }
@@ -114,6 +114,9 @@ export function dailyProductReview(rows: Row[], now: Date) {
...(channel === 'ui' && surface === 'phone' && (PRODUCT_USAGE_LONG_FLOWS as readonly string[]).includes(flow)
? { over1mBuckets: Object.fromEntries(PRODUCT_USAGE_LONG_MEASURES.map(bucket => [bucket, c[`${prefix}${bucket}`] ?? (started ? 0 : null)])) } : {}),
...(channel === 'ui' ? marksOf(prefix) : {}),
+ // Beside the Desktop's signed-out sign-in: why each one that did not go through ended.
+ ...(channel === 'setup' && surface === 'desktop' && flow === 'sign_in'
+ ? { endReasons: Object.fromEntries(PRODUCT_USAGE_SIGN_IN_END_REASONS.map(reason => [reason, c[`setup_desktop_sign_in_reason_${reason}`] ?? 0])) } : {}),
// Beside the Desktop's card: openings, new phones by opening, and reasons a card did not show.
...(channel === 'ui' && surface === 'desktop' && flow === 'phone_offer'
? { addPhoneOpenings: Object.fromEntries(PRODUCT_USAGE_ADD_PHONE_OPENINGS.map(opening => [opening, c[`ui_desktop_add_phone_${opening}`] ?? 0])),
diff --git a/backend/src/config/env.ts b/backend/src/config/env.ts
index 1f3659c95..096174c47 100644
--- a/backend/src/config/env.ts
+++ b/backend/src/config/env.ts
@@ -39,6 +39,11 @@ const envSchema = z.object({
// Base internal port; each worker binds MESH_PORT_BASE + NODE_APP_INSTANCE (distinct per worker).
MESH_PORT_BASE: z.string().default('8095').transform(Number),
+ // On SIGTERM the API answers /api/ready with 503 at once, then keeps serving this long before it closes its
+ // listeners, so the load balancer stops sending new connections first. 0 (the default) closes at once, as before;
+ // Kubernetes sets it, with probes and grace period, as backend/README.md describes.
+ DRAIN_DELAY_MS: z.coerce.number().int().min(0).max(60_000).default(0),
+
// Remote-terminal WebRTC is STUN-only: successful ICE bypasses the backend data relay; failed ICE
// keeps using the existing WebSocket route. Enabled by default; percentage 0 is the kill switch.
TERMINAL_P2P_ROLLOUT_PERCENT: z.coerce.number().int().min(0).max(100).default(100),
diff --git a/backend/src/lib/agentMessageShares.test.ts b/backend/src/lib/agentMessageShares.test.ts
index 4bc62ac4d..fd37deeae 100644
--- a/backend/src/lib/agentMessageShares.test.ts
+++ b/backend/src/lib/agentMessageShares.test.ts
@@ -283,6 +283,26 @@ describe('agent message shares', () => {
expect(p.agentMessageMember.upsert).not.toHaveBeenCalled()
})
+ it('answers the invitation a racing identical invite just made, not a duplicate-key error', async () => {
+ p.agentMessageShare.findFirst.mockResolvedValue({ id: S, ownerMachineId: 'm1' })
+ p.agentMessageMember.count.mockResolvedValue(1); p.agentMessageInvite.count.mockResolvedValue(0)
+ p.agentMessageInvite.upsert.mockRejectedValueOnce(p2002()).mockResolvedValueOnce({ id: 'i-raced' })
+ expect(await inv()).toEqual({ id: 'i-raced' })
+ expect(p.agentMessageInvite.upsert).toHaveBeenCalledTimes(2)
+ p.agentMessageInvite.upsert.mockRejectedValue(new Error('down'))
+ await expect(inv()).rejects.toThrow('down')
+ })
+
+ it('answers the shared tab when a racing accept of the same invitation made the member first', async () => {
+ p.agentMessageShare.findFirst.mockResolvedValue({ id: S })
+ p.agentMessageInvite.findFirst.mockResolvedValue(row())
+ p.agentMessageMember.upsert.mockRejectedValueOnce(p2002()).mockResolvedValueOnce({})
+ expect(await accept({ sub: 'bob', email: '[email protected]', autonomousEnv: 'prod' }, 'i1', now)).toEqual({ sharedTabId: S })
+ expect(p.agentMessageMember.upsert).toHaveBeenCalledTimes(2)
+ p.agentMessageMember.upsert.mockRejectedValue(new Error('down'))
+ await expect(accept({ sub: 'bob', email: '[email protected]', autonomousEnv: 'prod' }, 'i1', now)).rejects.toThrow('down')
+ })
+
it('accepts an invitation and (re)activates the member', async () => {
p.agentMessageShare.findFirst.mockResolvedValue({ id: S })
p.agentMessageInvite.findFirst.mockResolvedValue(row())
diff --git a/backend/src/lib/agentMessageShares.ts b/backend/src/lib/agentMessageShares.ts
index 8241c73ed..051aae6d9 100644
--- a/backend/src/lib/agentMessageShares.ts
+++ b/backend/src/lib/agentMessageShares.ts
@@ -1,6 +1,7 @@
import { createHash, randomUUID } from 'node:crypto'
import { Prisma } from '@prisma/client'
import { prisma, machineAlive } from './prisma.js'
+import { upsertRacing } from './upsertRace.js'
/**
* Shared tabs across accounts: the owner's signed roster, stored and never read; invitations by email; and who
@@ -96,12 +97,12 @@ export async function invite(input: { ownerUserId: string; ownerEmail: string; s
prisma.agentMessageInvite.count({ where: { shareId: share.id, acceptedAt: null, revokedAt: null, expiresAt: { gt: new Date() } } }),
])
if (members + pending >= MAX_MEMBERS) return { error: 'TAB_FULL' as const }
- const row = await prisma.agentMessageInvite.upsert({
+ const row = await upsertRacing(() => prisma.agentMessageInvite.upsert({
where: { shareId_email: { shareId: share.id, email } },
create: { id: randomUUID(), shareId: share.id, ownerUserId: input.ownerUserId, ownerMachineId: share.ownerMachineId,
email, autonomousEnv: input.autonomousEnv, expiresAt: input.expiresAt, acceptedAt: null, acceptedBy: null, revokedAt: null },
update: { expiresAt: input.expiresAt, revokedAt: null, acceptedAt: null, acceptedBy: null },
- })
+ }))
return { id: row.id }
}
@@ -147,9 +148,9 @@ export async function accept(user: { sub: string; email: string; autonomousEnv:
if (row.expiresAt <= now) return { error: 'EXPIRED' as const }
await prisma.agentMessageInvite.update({ where: { id: row.id }, data: { acceptedBy: user.sub, acceptedAt: now } })
const id = memberId(row.shareId, user.sub)
- await prisma.agentMessageMember.upsert({ where: { id },
+ await upsertRacing(() => prisma.agentMessageMember.upsert({ where: { id },
create: { id, shareId: row.shareId, userId: user.sub, email: row.email, inviteId: row.id, acceptedAt: now, removedAt: null },
- update: { removedAt: null, inviteId: row.id, acceptedAt: now } })
+ update: { removedAt: null, inviteId: row.id, acceptedAt: now } }))
return { sharedTabId: row.shareId }
}
diff --git a/backend/src/lib/prisma.test.ts b/backend/src/lib/prisma.test.ts
new file mode 100644
index 000000000..f59a24379
--- /dev/null
+++ b/backend/src/lib/prisma.test.ts
@@ -0,0 +1,12 @@
+import { expect, it, vi } from 'vitest'
+import { prisma } from './prisma.js'
+
+it('leaves the database connected on a shutdown signal, for the process to close after its drain', () => {
+ const disconnect = vi.spyOn(prisma, '$disconnect').mockResolvedValue()
+ try {
+ // Only the listeners registered in this test process: nothing is signalled for real.
+ process.emit('SIGTERM')
+ process.emit('SIGINT')
+ expect(disconnect).not.toHaveBeenCalled()
+ } finally { disconnect.mockRestore() }
+})
diff --git a/backend/src/lib/prisma.ts b/backend/src/lib/prisma.ts
index 6d37616c8..9ce3110b9 100644
--- a/backend/src/lib/prisma.ts
+++ b/backend/src/lib/prisma.ts
@@ -1,6 +1,5 @@
import { PrismaClient, type Prisma } from '@prisma/client'
import { env } from '../config/env.js'
-import { logger } from '../utils/logger.js'
// The Prisma CLI (db push) reads env("DATABASE_URL"); keep it in sync for any manual run.
process.env.DATABASE_URL ??= env.DATABASE_URL
@@ -21,10 +20,5 @@ export const machineAlive: Prisma.MachineWhereInput = { OR: [{ deletedAt: null }
* counter added to an existing collection needs a one-time raw `$set` backfill for legacy rows
* before any code increments it (see lib/db/migrate.ts backfillMachinePresenceTurnsStarted). */
-const gracefulShutdown = async () => {
- logger.info('Disconnecting Prisma client...')
- await prisma.$disconnect().catch(() => { /* ignore */ })
-}
-
-process.on('SIGINT', gracefulShutdown)
-process.on('SIGTERM', gracefulShutdown)
+// No signal handler here: each entry point disconnects in its own shutdown, the API only after its drain (server.ts),
+// so requests it still serves while draining keep their database.
diff --git a/backend/src/lib/productUsage.test.ts b/backend/src/lib/productUsage.test.ts
index 1383b26a8..c3309b9f8 100644
--- a/backend/src/lib/productUsage.test.ts
+++ b/backend/src/lib/productUsage.test.ts
@@ -218,6 +218,13 @@ describe('aggregate ingestion', () => {
expect(vi.mocked(delay).mock.calls[0][0]).toBeGreaterThanOrEqual(25)
expect(vi.mocked(delay).mock.calls[0][0]).toBeLessThan(75)
})
+ it('retries a Mongo lock wait like a conflict, with the same receipt', async () => {
+ db.$runCommandRaw.mockRejectedValueOnce(new Error('Error code 24 (LockTimeout): Unable to acquire IX lock, labels: {"TransientTransactionError"}'))
+ expect(await ingestProductUsage('a', report, now)).toEqual({ accepted: true })
+ expect(db.$transaction).toHaveBeenCalledTimes(2)
+ expect(db.productUsageReceipt.create.mock.calls[0]).toEqual(db.productUsageReceipt.create.mock.calls[1])
+ expect(delay).toHaveBeenCalledOnce()
+ })
it('rechecks a sharing-off choice before retrying the transaction', async () => {
db.$runCommandRaw.mockRejectedValueOnce({ code: 'P2034' })
db.productUsagePreference.findUnique.mockResolvedValueOnce({ enabled: true, revision: 0 })
diff --git a/backend/src/lib/productUsage.ts b/backend/src/lib/productUsage.ts
index 2e6442a91..51f9b4ff9 100644
--- a/backend/src/lib/productUsage.ts
+++ b/backend/src/lib/productUsage.ts
@@ -122,7 +122,9 @@ async function ingestCounters(report: SetupUsageReport & { revision?: number; co
if (code === 'P2002'
&& await prisma.productUsageReceipt.findUnique({ where: { id: report.id }, select: { id: true } })) return { accepted: true }
const pause = 25 * 2 ** attempt + Math.floor(Math.random() * 50)
- if ((code !== 'P2034' && code !== 'P2002') || attempt >= 3
+ // A Mongo lock wait comes without a Prisma code, labelled transient, as Swarm's do (superTabs/store.ts).
+ const transient = error instanceof Error && error.message.includes('TransientTransactionError')
+ if ((code !== 'P2034' && code !== 'P2002' && !transient) || attempt >= 3
|| performance.now() - started + pause >= 1000) throw error
await delay(pause)
if (performance.now() - started >= 1000) throw error
diff --git a/backend/src/lib/readiness.test.ts b/backend/src/lib/readiness.test.ts
new file mode 100644
index 000000000..a029bcfd6
--- /dev/null
+++ b/backend/src/lib/readiness.test.ts
@@ -0,0 +1,130 @@
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import { backendReadinessChecks, createDrain, createReadiness, drainBeforeClosing } from './readiness.js'
+
+beforeEach(() => vi.useFakeTimers())
+afterEach(() => vi.useRealTimers())
+
+const never = (): Promise<never> => new Promise(() => {})
+
+it('is ready when every dependency answers', async () => {
+ const readiness = createReadiness({ mongo: async () => 1, redis: async () => 'PONG' })
+ expect(await readiness.probe()).toEqual({ ready: true, draining: false, checks: { mongo: 'ok', redis: 'ok' } })
+})
+
+it('is not ready when one dependency fails, and names which', async () => {
+ const readiness = createReadiness({
+ mongo: async () => 1,
+ redis: async () => { throw new Error('connect ECONNREFUSED redis://:[email protected]') },
+ })
+ expect(await readiness.probe()).toEqual({ ready: false, draining: false, checks: { mongo: 'ok', redis: 'failed' } })
+})
+
+it('counts a check that throws before returning a promise as failed', async () => {
+ const readiness = createReadiness({ mongo: () => { throw new Error('client closed') }, redis: async () => 'PONG' })
+ expect(await readiness.probe()).toEqual({ ready: false, draining: false, checks: { mongo: 'failed', redis: 'ok' } })
+})
+
+it('gives up on a dependency that does not answer within 1 s', async () => {
+ const readiness = createReadiness({ mongo: never, redis: async () => 'PONG' })
+ const report = readiness.probe()
+ await vi.advanceTimersByTimeAsync(999)
+ let settled = false
+ void report.then(() => { settled = true })
+ await Promise.resolve()
+ expect(settled).toBe(false)
+ await vi.advanceTimersByTimeAsync(1)
+ expect(await report).toEqual({ ready: false, draining: false, checks: { mongo: 'timeout', redis: 'ok' } })
+})
+
+it('reuses one answer for 1 s, then asks the dependencies again', async () => {
+ const mongo = vi.fn(async () => 1)
+ const readiness = createReadiness({ mongo })
+ await readiness.probe()
+ await vi.advanceTimersByTimeAsync(999)
+ await readiness.probe()
+ expect(mongo).toHaveBeenCalledTimes(1)
+ await vi.advanceTimersByTimeAsync(1)
+ await readiness.probe()
+ expect(mongo).toHaveBeenCalledTimes(2)
+})
+
+it('shares one ping among probes that arrive while it is still running', async () => {
+ let answer!: () => void
+ const mongo = vi.fn(() => new Promise<void>((resolve) => { answer = resolve }))
+ const readiness = createReadiness({ mongo })
+ const first = readiness.probe(), second = readiness.probe()
+ answer()
+ expect(await first).toEqual({ ready: true, draining: false, checks: { mongo: 'ok' } })
+ expect(await second).toEqual({ ready: true, draining: false, checks: { mongo: 'ok' } })
+ expect(mongo).toHaveBeenCalledTimes(1)
+})
+
+it('keeps a slow ping shared until it settles, even past the cache window', async () => {
+ const mongo = vi.fn(never)
+ const readiness = createReadiness({ mongo }, { timeoutMs: 1000, cacheMs: 500 })
+ const first = readiness.probe()
+ await vi.advanceTimersByTimeAsync(600)
+ const second = readiness.probe()
+ expect(mongo).toHaveBeenCalledTimes(1)
+ await vi.advanceTimersByTimeAsync(400)
+ expect(await first).toEqual(await second)
+})
+
+it('answers not ready without pinging anything once draining starts', async () => {
+ const mongo = vi.fn(async () => 1)
+ const drain = createDrain()
+ const readiness = createReadiness({ mongo }, { drain })
+ expect((await readiness.probe()).ready).toBe(true)
+ drain.start()
+ // The cached "ready" from a moment ago must not outlive the drain.
+ expect(await readiness.probe()).toEqual({ ready: false, draining: true, checks: {} })
+ await vi.advanceTimersByTimeAsync(5_000)
+ expect(await readiness.probe()).toEqual({ ready: false, draining: true, checks: {} })
+ expect(mongo).toHaveBeenCalledTimes(1)
+})
+
+it('answers draining even for a probe whose ping started before the drain', async () => {
+ let answer!: () => void
+ const drain = createDrain()
+ const readiness = createReadiness({ mongo: () => new Promise<void>((resolve) => { answer = resolve }) }, { drain })
+ const report = readiness.probe()
+ drain.start()
+ answer()
+ expect(await report).toEqual({ ready: false, draining: true, checks: {} })
+})
+
+it('follows this process\' drain unless given another', async () => {
+ // A fresh copy of the module, so this process' drain starts undrained and the other tests never see it drained.
+ vi.resetModules()
+ const fresh = await import('./readiness.js')
+ const readiness = fresh.createReadiness({ mongo: async () => 1 })
+ expect(fresh.processDrain.draining).toBe(false)
+ expect((await readiness.probe()).draining).toBe(false)
+ fresh.processDrain.start()
+ expect(fresh.processDrain.draining).toBe(true)
+ expect((await readiness.probe()).draining).toBe(true)
+})
+
+it('marks draining at once, then keeps serving for the delay before closing may begin', async () => {
+ const drain = createDrain()
+ let finished = false
+ void drainBeforeClosing(drain, 3_000).then(() => { finished = true })
+ expect(drain.draining).toBe(true)
+ await vi.advanceTimersByTimeAsync(2_999)
+ expect(finished).toBe(false)
+ await vi.advanceTimersByTimeAsync(1)
+ expect(finished).toBe(true)
+})
+
+it('closes at once after marking draining when no delay is set', async () => {
+ const drain = createDrain()
+ await drainBeforeClosing(drain, 0)
+ expect(drain.draining).toBe(true)
+})
+
+it('checks Redis only where it is configured, and Mongo always', async () => {
+ const deps = { mongo: async () => 1, redis: async () => 'PONG' }
+ expect(Object.keys(backendReadinessChecks({ REDIS_URL: 'redis://redis:6379' }, deps))).toEqual(['mongo', 'redis'])
+ expect(Object.keys(backendReadinessChecks({}, deps))).toEqual(['mongo'])
+ expect(Object.keys(backendReadinessChecks({ REDIS_URL: '' }, deps))).toEqual(['mongo'])
+})
diff --git a/backend/src/lib/readiness.ts b/backend/src/lib/readiness.ts
new file mode 100644
index 000000000..68b56c1de
--- /dev/null
+++ b/backend/src/lib/readiness.ts
@@ -0,0 +1,89 @@
+/**
+ * Readiness: whether this process should receive new traffic. Liveness (`/api/health`) only says the process is
+ * alive and never touches a dependency, so a Mongo or Redis outage cannot make the orchestrator restart every pod.
+ * Readiness (`/api/ready`) pings them, so a pod is not sent traffic before it can serve it, and answers "draining"
+ * from the moment a shutdown signal lands, so it is taken out of rotation before its listeners close.
+ */
+
+export type DependencyCheck = () => unknown
+export type CheckResult = 'ok' | 'failed' | 'timeout'
+export interface ReadinessReport { ready: boolean; draining: boolean; checks: Record<string, CheckResult> }
+
+export interface Drain {
+ readonly draining: boolean
+ start(): void
+}
+
+export function createDrain(): Drain {
+ let draining = false
+ return {
+ get draining() { return draining },
+ start() { draining = true },
+ }
+}
+
+/** This process' drain. Under pm2 each cluster worker is its own process and gets its own signal, so each marks only
+ * itself. Shutdown starts it first (server.ts); anything that must stop taking work while draining reads it. */
+export const processDrain = createDrain()
+
+/** Mark draining, then keep serving for `delayMs` so the load balancer sees readiness fail and stops sending new
+ * connections before the listeners close. */
+export async function drainBeforeClosing(drain: Drain, delayMs: number): Promise<void> {
+ drain.start()
+ if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs))
+}
+
+/** The backend's dependencies. Redis only where one is configured: local and self-hosted backends may run without. */
+export function backendReadinessChecks(
+ environment: Record<string, string | undefined>,
+ deps: { mongo: DependencyCheck; redis: DependencyCheck },
+): Record<string, DependencyCheck> {
+ return environment.REDIS_URL ? { mongo: deps.mongo, redis: deps.redis } : { mongo: deps.mongo }
+}
+
+async function run(check: DependencyCheck, timeoutMs: number): Promise<CheckResult> {
+ let timer: NodeJS.Timeout | undefined
+ const timeout = new Promise<CheckResult>((resolve) => { timer = setTimeout(() => resolve('timeout'), timeoutMs) })
+ try {
+ // A check that throws before returning a promise is a failure too, not a crashed probe.
+ const answered = (async (): Promise<CheckResult> => { await check(); return 'ok' })().catch((): CheckResult => 'failed')
+ return await Promise.race([answered, timeout])
+ } finally { clearTimeout(timer) }
+}
+
+const DRAINING: ReadinessReport = { ready: false, draining: true, checks: {} }
+
+/**
+ * One ping per dependency at most every `cacheMs`, however often the probes come: probes that arrive while a ping
+ * is running, or within `cacheMs` of its start, share its answer. Error text never leaves here: a failed check is
+ * only named, since a driver's message can carry a connection string.
+ */
+export function createReadiness(
+ checks: Record<string, DependencyCheck>,
+ { timeoutMs = 1_000, cacheMs = 1_000, drain = processDrain }: { timeoutMs?: number; cacheMs?: number; drain?: Drain } = {},
+): { probe(): Promise<ReadinessReport> } {
+ let last: { startedAt: number; settled: boolean; report: Promise<ReadinessReport> } | null = null
+
+ const ping = async (): Promise<ReadinessReport> => {
+ const names = Object.keys(checks)
+ const results = await Promise.all(names.map((name) => run(checks[name], timeoutMs)))
+ const report: ReadinessReport['checks'] = {}
+ names.forEach((name, i) => { report[name] = results[i] })
+ return { ready: results.every((r) => r === 'ok'), draining: false, checks: report }
+ }
+
+ return {
+ async probe() {
+ if (drain.draining) return DRAINING
+ const now = Date.now()
+ if (!last || (last.settled && now - last.startedAt >= cacheMs)) {
+ const entry = { startedAt: now, settled: false, report: ping() }
+ void entry.report.finally(() => { entry.settled = true })
+ last = entry
+ }
+ const report = await last.report
+ // A drain that began while the ping ran wins over its answer.
+ return drain.draining ? DRAINING : report
+ },
+ }
+}
diff --git a/backend/src/lib/teamSession.test.ts b/backend/src/lib/teamSession.test.ts
index 8cdaad239..ccc37e0a3 100644
--- a/backend/src/lib/teamSession.test.ts
+++ b/backend/src/lib/teamSession.test.ts
@@ -54,6 +54,7 @@ import { machineRoutes } from '../routes/machines.js'
import { SsoAuthError, type AuthUser } from './ssoAuth.js'
import type { SuperTabStore } from '../superTabs/store.js'
import { TEAM_ROUTES } from './teamSession.js'
+import { createReadiness } from './readiness.js'
const OWNER_COMPUTER = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
const TEAM_COMPUTER = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'
@@ -378,7 +379,7 @@ describe('the allowlist', () => {
for (const method of [route.method].flat()) seen.add(`${method} ${route.url}`)
})
const { registerControlRoutes } = await import('../routes/control.js')
- await registerControlRoutes(probe, { daemons: { on: true, users: null } as never, count: async () => 0 })
+ await registerControlRoutes(probe, { daemons: { on: true, users: null } as never, count: async () => 0, readiness: createReadiness({}) })
await probe.ready()
const named = TEAM_ROUTES.map(r => `${r.method} ${r.url}`)
expect(new Set(named).size).toBe(named.length)
diff --git a/backend/src/lib/upsertRace.ts b/backend/src/lib/upsertRace.ts
new file mode 100644
index 000000000..c63b0bb1e
--- /dev/null
+++ b/backend/src/lib/upsertRace.ts
@@ -0,0 +1,11 @@
+/**
+ * Prisma runs an upsert on Mongo as a read, then an insert: an identical request between the two inserts first, and
+ * this one fails on the unique key (P2002). Run once more, the read finds that row and the upsert updates it, so both
+ * requests get the same answer instead of a conflict.
+ */
+export async function upsertRacing<T>(write: () => Promise<T>): Promise<T> {
+ try { return await write() } catch (error) {
+ if ((error as { code?: unknown } | null)?.code !== 'P2002') throw error
+ return write()
+ }
+}
diff --git a/backend/src/lib/webWs.test.ts b/backend/src/lib/webWs.test.ts
index a8e85dec7..b151679dc 100644
--- a/backend/src/lib/webWs.test.ts
+++ b/backend/src/lib/webWs.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it } from 'vitest'
-import { BACKEND_ONLY_DOWN_TYPES, declaredClient } from './webWs.js'
+import { BACKEND_ONLY_DOWN_TYPES, declaredClient, sendWhenAwake } from './webWs.js'
+import type { HubClient } from './hub.js'
/**
* `handleFrame` forwards anything it does not recognise straight to the adapter
@@ -47,3 +48,32 @@ describe('who a per-user socket says it is', () => {
expect(declared('client=desktop&release=1.0.8')).toEqual({ surface: null, build: {} })
})
})
+
+/** A frame waits for its machine to wake before it goes down (2026-10-28 prod: "Cannot read properties of null (reading
+ * 'sendDown')", once the person deselected the machine during that wait). */
+describe('a frame sent once its machine is awake', () => {
+ const hubClient = () => { const sent: unknown[] = []; return { sent, client: { sendDown: (frame: unknown) => { sent.push(frame) } } as unknown as HubClient } }
+ const frame = { type: 'message', payload: { text: 'hi' } }
+
+ it('goes to the client still selected', async () => {
+ const a = hubClient()
+ await sendWhenAwake(() => a.client, async () => {}, frame)
+ expect(a.sent).toEqual([frame])
+ })
+
+ it('is dropped when the machine was deselected, or another selected, during the wake', async () => {
+ const a = hubClient(), b = hubClient()
+ let selected: HubClient | null = a.client
+ await sendWhenAwake(() => selected, async () => { selected = null }, frame)
+ selected = a.client
+ await sendWhenAwake(() => selected, async () => { selected = b.client }, frame)
+ expect(a.sent).toEqual([])
+ expect(b.sent).toEqual([])
+ })
+
+ it('sends nothing when the wake fails, and says why', async () => {
+ const a = hubClient()
+ await expect(sendWhenAwake(() => a.client, async () => { throw new Error('Machine could not be started') }, frame)).rejects.toThrow('Machine could not be started')
+ expect(a.sent).toEqual([])
+ })
+})
diff --git a/backend/src/lib/webWs.ts b/backend/src/lib/webWs.ts
index 9fe3a035c..521e7a26f 100644
--- a/backend/src/lib/webWs.ts
+++ b/backend/src/lib/webWs.ts
@@ -92,6 +92,16 @@ export function declaredClient(query: URLSearchParams): { surface: 'mobile' | 'w
return { surface, build: surface === 'mobile' ? { release: query.get('release'), debug: query.get('debug') === '1' } : {} }
}
+/** Sends `frame` down once `wake` has made sure its machine runs, to the client still selected then. A deselect, another
+ * machine's select or the socket's close during the wait leaves no client for it, and the frame is dropped: it was meant
+ * for that machine (2026-10-28 prod: "Cannot read properties of null (reading 'sendDown')"). A failed wake sends nothing. */
+export async function sendWhenAwake(selected: () => HubClient | null, wake: () => Promise<void>, frame: Frame): Promise<void> {
+ const target = selected()
+ if (!target) return
+ await wake()
+ if (selected() === target) target.sendDown(frame)
+}
+
/** HTTP upgrade hook for `/api/web-ws`. Subprotocol = SSO access token or legacy agent apiKey. */
export function handleWebUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void {
const cred = extractKey(req)
@@ -523,18 +533,19 @@ function attachUserClient(ws: WebSocket, user: AuthUser, surface: 'mobile' | 'we
return
}
if (client && currentBinding) {
+ const binding = currentBinding
// A selected machine can idle-stop while the tab remains open. Turn-producing messages always
// refresh the wake lease; other frames wake only when presence says the node is down.
try {
- if ((isTerminal && terminalFrameNeedsWake(type!)) || (!isTerminal && (type === 'message' || !(await presentRecently(currentBinding.machineId))))) {
- await ensureMachineReady(currentBinding)
- }
+ await sendWhenAwake(() => client, async () => {
+ if ((isTerminal && terminalFrameNeedsWake(type!)) || (!isTerminal && (type === 'message' || !(await presentRecently(binding.machineId))))) {
+ await ensureMachineReady(binding)
+ }
+ }, frame)
} catch (err) {
const message = err instanceof Error ? err.message : 'Machine could not be started'
send({ type: 'error', payload: { message } })
- return
}
- client.sendDown(frame)
return
}
// No agent selected: fast-fail RPCs (echo the requestId) so wsClient.request doesn't burn its
diff --git a/backend/src/middlewares/authMiddleware.ts b/backend/src/middlewares/authMiddleware.ts
index b60fbe6a6..224d62e63 100644
--- a/backend/src/middlewares/authMiddleware.ts
+++ b/backend/src/middlewares/authMiddleware.ts
@@ -21,6 +21,8 @@ export function shouldSkipAuth(url: string): boolean {
const path = url.split('?')[0]
return (
path === '/api/health' ||
+ // Readiness probe: the orchestrator carries no token, and the answer names only dependencies and their state.
+ path === '/api/ready' ||
// Explicitly enabled, credential-free setup totals; its own schema and workload budget apply.
path === '/api/product-usage/setup' ||
// Hub totals the website's server forwards with cookies and auth stripped; same rules as setup.
diff --git a/backend/src/middlewares/errorHandler.test.ts b/backend/src/middlewares/errorHandler.test.ts
new file mode 100644
index 000000000..ed174e168
--- /dev/null
+++ b/backend/src/middlewares/errorHandler.test.ts
@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import Fastify, { type FastifyInstance } from 'fastify'
+import { Prisma } from '@prisma/client'
+import { errorHandler } from './errorHandler.js'
+import { SuperTabError } from '../superTabs/model.js'
+import { logger } from '../utils/logger.js'
+
+const prismaError = (code: string, message: string) => new Prisma.PrismaClientKnownRequestError(message, { code, clientVersion: 'test' })
+
+describe('the shared error handler', () => {
+ let app: FastifyInstance
+ let thrown: unknown
+ beforeEach(async () => {
+ app = Fastify()
+ app.setErrorHandler(errorHandler)
+ app.get('/fails', async () => { throw thrown })
+ await app.ready()
+ })
+ afterEach(async () => { await app.close(); vi.restoreAllMocks() })
+
+ it('answers a busy Swarm thrown outside the Super Tab routes as 503 with Retry-After, not 500', async () => {
+ // The harness-shares list checks each share through the Swarm store (2026-10-28 prod: ten 500s).
+ thrown = new SuperTabError('SWARM_BUSY', 'This Swarm is busy. Try again in a moment.', 503)
+ const res = await app.inject({ method: 'GET', url: '/fails' })
+ expect(res.statusCode).toBe(503)
+ expect(res.headers['retry-after']).toBe('2')
+ expect(res.json()).toEqual({ success: false, error: { code: 'SWARM_BUSY', message: 'This Swarm is busy. Try again in a moment.' } })
+ })
+
+ it('asks a migrating Swarm\'s caller to retry too', async () => {
+ thrown = new SuperTabError('SWARM_MIGRATING', 'This Swarm is being updated. Try again in a moment.', 503)
+ const res = await app.inject({ method: 'GET', url: '/fails' })
+ expect(res.statusCode).toBe(503)
+ expect(res.headers['retry-after']).toBe('2')
+ })
+
+ it('sends no Retry-After with a 503 that waiting does not change', async () => {
+ thrown = new SuperTabError('ATTACHMENTS_UNAVAILABLE', 'File attachments are not available on this server.', 503)
+ const res = await app.inject({ method: 'GET', url: '/fails' })
+ expect(res.statusCode).toBe(503)
+ expect(res.headers['retry-after']).toBeUndefined()
+ expect(res.json().error.code).toBe('ATTACHMENTS_UNAVAILABLE')
+ })
+
+ it('answers any other Swarm refusal with its own status', async () => {
+ thrown = new SuperTabError('FORBIDDEN', 'Not yours.', 403)
+ const res = await app.inject({ method: 'GET', url: '/fails' })
+ expect(res.statusCode).toBe(403)
+ expect(res.headers['retry-after']).toBeUndefined()
+ expect(res.json().error.code).toBe('FORBIDDEN')
+ })
+
+ it('answers an expired or unstartable database transaction as a retryable 503', async () => {
+ for (const message of ['Transaction API error: Transaction already closed: A query cannot be executed on an expired transaction. The timeout for this transaction was 15000 ms, however 15412 ms passed since the start of the transaction.',
+ 'Transaction API error: Unable to start a transaction in the given time.']) {
+ thrown = prismaError('P2028', message)
+ const res = await app.inject({ method: 'GET', url: '/fails' })
+ expect(res.statusCode).toBe(503)
+ expect(res.headers['retry-after']).toBe('2')
+ // The database's own wording stays in the log.
+ expect(res.json().error).toEqual({ code: 'BUSY', message: 'The server is busy. Try again in a moment.' })
+ }
+ })
+
+ it('answers a genuine duplicate key as 409 in its own words, not 500', async () => {
+ thrown = prismaError('P2002', 'Unique constraint failed on the constraint: `SwarmGroup_pkey`')
+ const res = await app.inject({ method: 'GET', url: '/fails' })
+ expect(res.statusCode).toBe(409)
+ expect(res.headers['retry-after']).toBeUndefined()
+ expect(res.json().error).toEqual({ code: 'DUPLICATE', message: 'This already exists, so nothing new was saved.' })
+ })
+
+ it('keeps anything else a 500 and logs its stack', async () => {
+ const error = vi.spyOn(logger, 'error').mockImplementation(() => {})
+ thrown = new TypeError("Cannot read properties of null (reading 'sendDown')")
+ const res = await app.inject({ method: 'GET', url: '/fails' })
+ expect(res.statusCode).toBe(500)
+ expect(res.json().error.code).toBe('INTERNAL_ERROR')
+ expect(error).toHaveBeenCalledTimes(1)
+ const context = error.mock.calls[0]![2] as Record<string, unknown>
+ expect(context.trace).toEqual(expect.stringContaining('TypeError: Cannot read properties of null'))
+ expect(context.trace).toEqual(expect.stringContaining('errorHandler.test.ts'))
+ })
+})
diff --git a/backend/src/middlewares/errorHandler.ts b/backend/src/middlewares/errorHandler.ts
index a2e6bfb9e..d058f8f4c 100644
--- a/backend/src/middlewares/errorHandler.ts
+++ b/backend/src/middlewares/errorHandler.ts
@@ -2,6 +2,25 @@ import type { FastifyError, FastifyReply, FastifyRequest } from 'fastify'
import { AppError } from '../errors/index.js'
import { sendError } from '../utils/response.js'
import { logger } from '../utils/logger.js'
+import { SuperTabError } from '../superTabs/model.js'
+
+/** The Swarm 503s that waiting fixes. Others (no attachment store, no picture uploads) are this server's setup. */
+const RETRYABLE_SWARM_CODES = new Set(['SWARM_BUSY', 'SWARM_MIGRATING'])
+
+/** How long a busy answer asks the caller to wait: just past the Swarm transaction's longest backoff (1.5 s). */
+const BUSY_RETRY_AFTER_SECONDS = 2
+
+/** A 503 the caller should simply try again: it carries Retry-After. Every client retries a 5xx (store.ts `transaction`). */
+function sendBusy(reply: FastifyReply, message: string, code: string): void {
+ reply.header('Retry-After', String(BUSY_RETRY_AFTER_SECONDS))
+ sendError(reply, message, code, 503)
+}
+
+/** Prisma's own failure code, when the error is one. */
+const prismaCode = (error: unknown): string | null => {
+ const code = error && typeof error === 'object' && 'code' in error ? (error as { code: unknown }).code : null
+ return typeof code === 'string' && /^P\d{4}$/.test(code) ? code : null
+}
export async function errorHandler(
error: FastifyError,
@@ -20,6 +39,27 @@ export async function errorHandler(
return
}
+ // A Swarm refusal or busy answer thrown outside the Super Tab routes (the harness-shares list asks the Swarm store).
+ if (error instanceof SuperTabError) {
+ if (RETRYABLE_SWARM_CODES.has(error.code)) {
+ logger.warn('Swarm busy', { code: error.code, path: request.url, method: request.method })
+ return sendBusy(reply, error.message, error.code)
+ }
+ return sendError(reply, error.message, error.code, error.status)
+ }
+
+ // A database transaction that expired or could not start (P2028) is load, not a fault: the caller retries.
+ // A unique key still taken after the retries (P2002) is a genuine duplicate: a conflict, never a 500.
+ const prisma = prismaCode(error)
+ if (prisma === 'P2028') {
+ logger.warn('Database transaction expired or could not start', { path: request.url, method: request.method, message: error.message })
+ return sendBusy(reply, 'The server is busy. Try again in a moment.', 'BUSY')
+ }
+ if (prisma === 'P2002') {
+ logger.warn('Duplicate key', { path: request.url, method: request.method, message: error.message })
+ return sendError(reply, 'This already exists, so nothing new was saved.', 'DUPLICATE', 409)
+ }
+
if (error.validation) {
sendError(reply, error.validation[0]?.message || 'Validation failed', 'VALIDATION_ERROR', 400)
return
@@ -37,7 +77,8 @@ export async function errorHandler(
return
}
- logger.error('Unhandled error', error, { name: error.name, path: request.url, method: request.method })
+ // The stack always, production too: an unhandled 500 is a bug, and its message alone rarely says where.
+ logger.error('Unhandled error', error, { name: error.name, path: request.url, method: request.method, trace: error.stack })
// Only hide the real message in explicit production. Local dev often has NODE_ENV unset, and masking
// there just surfaces a useless "internal server error" to the caller (e.g. the UI toast).
const hideDetail = process.env.NODE_ENV === 'production'
diff --git a/backend/src/middlewares/index.ts b/backend/src/middlewares/index.ts
index ca03270c7..37e677667 100644
--- a/backend/src/middlewares/index.ts
+++ b/backend/src/middlewares/index.ts
@@ -1,3 +1,4 @@
export * from './authMiddleware.js'
export * from './errorHandler.js'
export * from './validation.js'
+export * from './securityHeaders.js'
diff --git a/backend/src/middlewares/securityHeaders.ts b/backend/src/middlewares/securityHeaders.ts
new file mode 100644
index 000000000..c5843de77
--- /dev/null
+++ b/backend/src/middlewares/securityHeaders.ts
@@ -0,0 +1,18 @@
+import type { FastifyInstance } from 'fastify'
+import { env } from '../config/env.js'
+
+/**
+ * The headers every answer carries. Header-only onSend hooks stay synchronous (`done`): with two async ones, an async
+ * handler that sends without returning its reply is still being sent when it returns, and Fastify sends it again
+ * ("Cannot write headers after they are sent to the client", the community feed, 2026-10-28).
+ */
+export function registerSecurityHeaders(app: FastifyInstance): void {
+ app.addHook('onSend', (_request, reply, payload, done) => {
+ reply.header('X-Content-Type-Options', 'nosniff')
+ reply.header('Referrer-Policy', 'strict-origin-when-cross-origin')
+ if (env.NODE_ENV === 'production') {
+ reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
+ }
+ done(null, payload)
+ })
+}
diff --git a/backend/src/routes/community.test.ts b/backend/src/routes/community.test.ts
index 963da794b..7bf673356 100644
--- a/backend/src/routes/community.test.ts
+++ b/backend/src/routes/community.test.ts
@@ -92,6 +92,8 @@ import { communityNotificationRoutes } from './communityNotifications.js'
import { communityReportRoutes, resetReportRateLimits } from './communityReports.js'
import { communityEditRoutes, resetEditRateLimits } from './communityEdit.js'
import { registerAuthMiddleware } from '../middlewares/authMiddleware.js'
+import { registerSecurityHeaders } from '../middlewares/securityHeaders.js'
+import { logger } from '../utils/logger.js'
import { errorHandler } from '../middlewares/errorHandler.js'
import { communityStarters, isPublicCommunityRead } from '../lib/communityAccess.js'
@@ -109,7 +111,8 @@ async function publish(token = 'alice', payload = sample, env = 'prod') {
beforeEach(async () => {
for (const model of [db.communityHarness, db.communityLike, db.communityComment, db.communityFollow, db.communityReport, db.communityHidden, db.communityNotification]) model.rows.splice(0)
vi.clearAllMocks(); resetEditRateLimits(); resetReportRateLimits()
- app = Fastify(); app.setErrorHandler(errorHandler)
+ // The server's own headers too (server.ts): with them, every answer here runs two onSend hooks, as in production.
+ app = Fastify(); app.setErrorHandler(errorHandler); registerSecurityHeaders(app)
registerAuthMiddleware(app, async (token, autonomousEnv = 'prod') => {
if (!['alice', 'bob', 'carol', 'dave', 'admin'].includes(token)) throw new Error('Invalid token')
return { sub: token, email: `${token}@example.com`, role: token === 'admin' ? 'admin' : 'user', autonomousEnv }
@@ -119,6 +122,21 @@ beforeEach(async () => {
afterEach(async () => app.close())
describe('publications and access', () => {
+ // 2026-10-28 prod, twice: "Cannot write headers after they are sent to the client" on the feed. An async handler that
+ // sends without returning its reply, while two async onSend hooks still run, is sent a second time by Fastify.
+ it('answers the feed and a publication once, with no second send reaching the error handler', async () => {
+ const failed = vi.spyOn(logger, 'error').mockImplementation(() => {})
+ const id = await publish()
+ for (const path of ['harnesses', `harnesses/${id}`, 'harnesses?sort=popular']) {
+ const response = await call('GET', path)
+ expect(response.statusCode).toBe(200)
+ expect(response.headers['cache-control']).toBe('no-store')
+ expect(response.headers['x-content-type-options']).toBe('nosniff')
+ }
+ expect(failed.mock.calls.map(c => c[1] instanceof Error ? c[1].message : c[1])).toEqual([])
+ failed.mockRestore()
+ })
+
it('shows feed engagement and gives the creator a place to find and reply to comments', async () => {
const id = await publish()
await call('PUT', `harnesses/${id}/like`, 'bob', { liked: true })
diff --git a/backend/src/routes/community.ts b/backend/src/routes/community.ts
index e615c57ea..baad7e352 100644
--- a/backend/src/routes/community.ts
+++ b/backend/src/routes/community.ts
@@ -165,7 +165,8 @@ async function origin(forkedFrom: string | null, autonomousEnv: string) {
}
export async function communityRoutes(app: FastifyInstance): Promise<void> {
- app.addHook('onSend', async (_req, reply) => { reply.header('Cache-Control', 'no-store') })
+ // Synchronous, as every header-only hook (middlewares/securityHeaders.ts).
+ app.addHook('onSend', (_req, reply, payload, done) => { reply.header('Cache-Control', 'no-store'); done(null, payload) })
// A gzipped body unpacks to at most what a raw one may carry (the snapshot and its envelope).
acceptGzipJson(app, 6_100_000)
diff --git a/backend/src/routes/communityNotifications.ts b/backend/src/routes/communityNotifications.ts
index 16c279926..f282b4d3b 100644
--- a/backend/src/routes/communityNotifications.ts
+++ b/backend/src/routes/communityNotifications.ts
@@ -13,7 +13,8 @@ import { sendSuccess } from '../utils/response.js'
import { environment } from './community.js'
export async function communityNotificationRoutes(app: FastifyInstance): Promise<void> {
- app.addHook('onSend', async (_req, reply) => { reply.header('Cache-Control', 'no-store') })
+ // Synchronous, as every header-only hook (middlewares/securityHeaders.ts).
+ app.addHook('onSend', (_req, reply, payload, done) => { reply.header('Cache-Control', 'no-store'); done(null, payload) })
const unread = (autonomousEnv: string, userId: string) => prisma.communityNotification.count({ where: { autonomousEnv, userId, readAt: null } })
app.get('/api/community/notifications', async (req, reply) => {
diff --git a/backend/src/routes/control.test.ts b/backend/src/routes/control.test.ts
index 647e018ca..457d32adb 100644
--- a/backend/src/routes/control.test.ts
+++ b/backend/src/routes/control.test.ts
@@ -58,6 +58,7 @@ import { errorHandler } from '../middlewares/errorHandler.js'
import { redeemHandoff, startHandoff } from '../lib/harnessSession.js'
import { TEAM_ROUTES } from '../lib/teamSession.js'
import { registerControlRoutes } from './control.js'
+import { createReadiness } from '../lib/readiness.js'
let app: FastifyInstance
let token: string
@@ -72,7 +73,7 @@ beforeAll(async () => {
for (const method of [route.method].flat()) if (method !== 'HEAD' && method !== 'OPTIONS') routes.push({ method, url: route.url })
})
registerAuthMiddleware(app)
- await registerControlRoutes(app, { daemons: { on: true, users: null }, count: async () => 0 })
+ await registerControlRoutes(app, { daemons: { on: true, users: null }, count: async () => 0, readiness: createReadiness({}) })
await app.ready()
})
afterAll(async () => { await app?.close() })
diff --git a/backend/src/routes/control.ts b/backend/src/routes/control.ts
index 8c00d070a..344aaaa1e 100644
--- a/backend/src/routes/control.ts
+++ b/backend/src/routes/control.ts
@@ -1,6 +1,7 @@
import type { FastifyInstance } from 'fastify'
import type { DaemonsSwitch } from '../lib/daemonsSwitch.js'
import type { JevRouteOptions } from './jevRoute.js'
+import type { ReadinessReport } from '../lib/readiness.js'
import { cursorRoutes } from './cursor.js'
import { voiceRoutes } from './voice.js'
import { harnessShareRoutes } from './harnessShares.js'
@@ -30,8 +31,12 @@ import { healthRoutes, authRoutes, userRoutes, machineRoutes, planRoutes, gridRo
* list, so what is checked against the route table — a team session's deny-by-default sweep (routes/control.test.ts)
* — is the table production serves.
*/
-export async function registerControlRoutes(app: FastifyInstance, opts: { daemons: DaemonsSwitch; count: JevRouteOptions['count'] }): Promise<void> {
- await app.register(healthRoutes)
+export async function registerControlRoutes(app: FastifyInstance, opts: {
+ daemons: DaemonsSwitch
+ count: JevRouteOptions['count']
+ readiness: { probe(): Promise<ReadinessReport> }
+}): Promise<void> {
+ await app.register(healthRoutes, { readiness: opts.readiness })
await app.register(authRoutes)
await app.register(userRoutes)
await app.register(machineRoutes)
diff --git a/backend/src/routes/health.test.ts b/backend/src/routes/health.test.ts
index 7ea4d72b1..3c330b8e3 100644
--- a/backend/src/routes/health.test.ts
+++ b/backend/src/routes/health.test.ts
@@ -1,8 +1,19 @@
import Fastify from 'fastify'
import { afterEach, expect, it, vi } from 'vitest'
+import { createDrain, createReadiness, type DependencyCheck } from '../lib/readiness.js'
+import { registerAuthMiddleware } from '../middlewares/authMiddleware.js'
import { healthRoutes } from './health.js'
afterEach(() => vi.unstubAllEnvs())
+
+async function serve(checks: Record<string, DependencyCheck>, drain = createDrain()) {
+ const app = Fastify({ logger: false })
+ // The real sign-in gate: probes carry no token. It must never be asked to authenticate one.
+ registerAuthMiddleware(app, async () => { throw new Error('a probe must not need a sign-in') })
+ await app.register(healthRoutes, { readiness: createReadiness(checks, { drain }) })
+ return app
+}
+
it.each([
['v1.2.72_backend', 'a'.repeat(40), { version: 'v1.2.72_backend', sha: 'a'.repeat(40) }],
['', '', null],
@@ -10,12 +21,59 @@ it.each([
['v1.2.72_backend', 'PRIVATE_CANARY', null],
])('exposes only validated public build coordinates', async (tag, sha, build) => {
vi.stubEnv('BUILD_TAG', tag); vi.stubEnv('BUILD_SHA', sha)
- const app = Fastify({ logger: false })
+ const app = await serve({ mongo: async () => 1 })
try {
- await app.register(healthRoutes)
const response = await app.inject('/api/health')
expect(response.statusCode).toBe(200)
expect(response.json()).toEqual({ success: true, data: { status: 'ok', build } })
expect(response.body).not.toContain('PRIVATE_CANARY')
} finally { await app.close() }
})
+
+it('keeps liveness up while dependencies are down and the process drains, so nothing restarts it for that', async () => {
+ const mongo = vi.fn(async () => { throw new Error('down') })
+ const drain = createDrain()
+ const app = await serve({ mongo }, drain)
+ try {
+ drain.start()
+ const response = await app.inject('/api/health')
+ expect(response.statusCode).toBe(200)
+ expect(response.json().data.status).toBe('ok')
+ expect(mongo).not.toHaveBeenCalled()
+ } finally { await app.close() }
+})
+
+it('is ready without a sign-in when Mongo and Redis answer', async () => {
+ const app = await serve({ mongo: async () => 1, redis: async () => 'PONG' })
+ try {
+ const response = await app.inject('/api/ready')
+ expect(response.statusCode).toBe(200)
+ expect(response.headers['cache-control']).toBe('no-store')
+ expect(response.json()).toEqual({ success: true, data: { status: 'ready', checks: { mongo: 'ok', redis: 'ok' } } })
+ } finally { await app.close() }
+})
+
+it('answers 503 naming the failed dependency, without its error text', async () => {
+ const app = await serve({
+ mongo: async () => 1,
+ redis: async () => { throw new Error('NOAUTH redis://:[email protected]:6379') },
+ })
+ try {
+ const response = await app.inject('/api/ready')
+ expect(response.statusCode).toBe(503)
+ expect(response.json()).toEqual({ success: false, data: { status: 'not_ready', checks: { mongo: 'ok', redis: 'failed' } } })
+ expect(response.body).not.toContain('PRIVATE_CANARY')
+ } finally { await app.close() }
+})
+
+it('answers 503 draining once shutdown starts, though the dependencies are fine', async () => {
+ const drain = createDrain()
+ const app = await serve({ mongo: async () => 1, redis: async () => 'PONG' }, drain)
+ try {
+ expect((await app.inject('/api/ready')).statusCode).toBe(200)
+ drain.start()
+ const response = await app.inject('/api/ready')
+ expect(response.statusCode).toBe(503)
+ expect(response.json()).toEqual({ success: false, data: { status: 'draining', checks: {} } })
+ } finally { await app.close() }
+})
diff --git a/backend/src/routes/health.ts b/backend/src/routes/health.ts
index c2d64f90d..9832ffa8b 100644
--- a/backend/src/routes/health.ts
+++ b/backend/src/routes/health.ts
@@ -1,13 +1,22 @@
import type { FastifyInstance } from 'fastify'
+import type { ReadinessReport } from '../lib/readiness.js'
-export async function healthRoutes(app: FastifyInstance): Promise<void> {
+export async function healthRoutes(app: FastifyInstance, opts: { readiness: { probe(): Promise<ReadinessReport> } }): Promise<void> {
// Public release coordinates only. Deployment verification must not rely on an image build
// succeeding while the live API still runs an older image, or expose arbitrary environment text.
const version = process.env.BUILD_TAG ?? '', sha = process.env.BUILD_SHA ?? ''
const build = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(_backend)?$/.test(version)
&& /^[a-f0-9]{40}$/.test(sha) ? { version, sha } : null
+ // Liveness: the process answers. No dependency calls, so an outage never makes the orchestrator restart pods.
app.get('/api/health', async () => ({
success: true,
data: { status: 'ok', build },
}))
+ // Readiness: send this process traffic only while Mongo and Redis answer and it is not shutting down (lib/readiness.ts).
+ app.get('/api/ready', async (_request, reply) => {
+ const { ready, draining, checks } = await opts.readiness.probe()
+ reply.header('Cache-Control', 'no-store')
+ if (ready) return { success: true, data: { status: 'ready', checks } }
+ return reply.code(503).send({ success: false, data: { status: draining ? 'draining' : 'not_ready', checks } })
+ })
}
diff --git a/backend/src/routes/machineShares.test.ts b/backend/src/routes/machineShares.test.ts
index 1faaada16..90722e995 100644
--- a/backend/src/routes/machineShares.test.ts
+++ b/backend/src/routes/machineShares.test.ts
@@ -160,6 +160,15 @@ describe('sharing a machine', () => {
expect(mocks.listChanged.mock.calls.map(c => c[0])).toEqual(['dee', 'kim'])
})
+ it('answers added when a racing identical add stored it first', async () => {
+ mocks.prisma.machineShare.findUnique.mockResolvedValue(row({ emails: [] }))
+ mocks.prisma.machineShareAdd.upsert.mockRejectedValueOnce(Object.assign(new Error('Unique constraint failed'), { code: 'P2002' })).mockResolvedValueOnce({})
+ const res = await add()
+ expect(res.statusCode).toBe(200)
+ expect(res.json().data).toEqual({ added: true })
+ expect(mocks.prisma.machineShareAdd.upsert).toHaveBeenCalledTimes(2)
+ })
+
it('needs no add for a named address', async () => {
mocks.prisma.machineShare.findUnique.mockResolvedValue(row({ emails: ['[email protected]'], domain: null }))
expect((await add()).statusCode).toBe(200)
diff --git a/backend/src/routes/machineShares.ts b/backend/src/routes/machineShares.ts
index 2f3803606..aa4f64566 100644
--- a/backend/src/routes/machineShares.ts
+++ b/backend/src/routes/machineShares.ts
@@ -15,6 +15,7 @@ import { nextMachineShareGrants } from '../lib/machineSharePolicy.js'
import type { MachineShare } from '@prisma/client'
import { z } from 'zod'
import { prisma, machineAlive } from '../lib/prisma.js'
+import { upsertRacing } from '../lib/upsertRace.js'
import { publishDeviceMachineListChanged, publishMachineShareChanged } from '../lib/bus.js'
import { machinesSharedWith, shareMembers, sharedVia } from '../lib/machineAccess.js'
import { emailDomain, isPublicEmailDomain } from '../lib/publicEmailDomains.js'
@@ -145,8 +146,8 @@ export async function machineShareRoutes(app: FastifyInstance): Promise<void> {
const via = share && machine ? sharedVia(share, user.email) : null
if (!share || !via) return sendError(reply, 'This machine is not shared with you.', 'NOT_SHARED', 404)
if (via === 'domain') {
- await prisma.machineShareAdd.upsert({ where: { machineId_userId: { machineId, userId: user.sub } },
- create: { machineId, userId: user.sub }, update: {} })
+ await upsertRacing(() => prisma.machineShareAdd.upsert({ where: { machineId_userId: { machineId, userId: user.sub } },
+ create: { machineId, userId: user.sub }, update: {} }))
}
// The owner's daemon reads who uses the machine again and trusts this account's machines.
await Promise.all([share.ownerId, user.sub].map(id => publishDeviceMachineListChanged(id, { reason: 'updated' }))).catch(() => [])
diff --git a/backend/src/routes/productUsage.test.ts b/backend/src/routes/productUsage.test.ts
index eeb514bb2..22ae909cb 100644
--- a/backend/src/routes/productUsage.test.ts
+++ b/backend/src/routes/productUsage.test.ts
@@ -57,23 +57,49 @@ it('does not reflect a database error or report contents', async () => {
expect(response.statusCode).toBe(503)
expect(response.body).not.toContain('PRIVATE_CANARY')
})
+/** A busy answer says when to come back: whole seconds, spread over 30 to 120 so a refused fleet does not return at once. */
+function expectRetryAfter(response: { headers: Record<string, unknown> }) {
+ const seconds = Number(response.headers['retry-after'])
+ expect(Number.isInteger(seconds)).toBe(true)
+ expect(seconds).toBeGreaterThanOrEqual(30)
+ expect(seconds).toBeLessThanOrEqual(120)
+}
it('returns retryable backpressure without admitting another database write', async () => {
methods.ingestProductUsage.mockRejectedValue({ code: 'USAGE_BUSY', message: 'PRIVATE_CANARY' })
const response = await submit(good)
expect(response.statusCode).toBe(429)
expect(response.json().error.code).toBe('USAGE_BUSY')
+ expectRetryAfter(response)
expect(response.body).not.toContain('PRIVATE_CANARY')
})
+// Contention that outlasted its retries is load, not an outage: try later, with the cause kept apart.
it.each([['P2034', 'USAGE_WRITE_CONFLICT'], ['P2002', 'USAGE_WRITE_CONFLICT'],
- ['P2028', 'USAGE_TRANSACTION_FAILED'], ['PRIVATE_CANARY', 'USAGE_UNAVAILABLE']])(
- 'returns only the fixed delivery category for storage error %s', async (code, expected) => {
+ ['P2028', 'USAGE_TRANSACTION_FAILED'], ['P2024', 'USAGE_BUSY']])(
+ 'answers busy storage error %s with 429, its fixed category and a Retry-After', async (code, expected) => {
methods.ingestProductUsage.mockRejectedValue(Object.assign(new Error('PRIVATE_CANARY'), { code, meta: 'PRIVATE_CANARY' }))
const response = await submit(good)
- expect(response.statusCode).toBe(503)
+ expect(response.statusCode).toBe(429)
expect(response.json().error.code).toBe(expected)
+ expectRetryAfter(response)
expect(response.body).not.toContain('PRIVATE_CANARY')
},
)
+it('answers a Mongo lock wait that outlasted its retries as busy', async () => {
+ methods.ingestProductUsage.mockRejectedValue(new Error('PRIVATE_CANARY Error code 24 (LockTimeout): Unable to acquire IX lock, labels: {"TransientTransactionError"}'))
+ const response = await submit(good)
+ expect(response.statusCode).toBe(429)
+ expect(response.json().error.code).toBe('USAGE_BUSY')
+ expectRetryAfter(response)
+ expect(response.body).not.toContain('PRIVATE_CANARY')
+})
+// An outage stays 503, so the counters still show storage down.
+it.each(['P1001', 'PRIVATE_CANARY'])('answers storage error %s as unavailable, not busy', async code => {
+ methods.ingestProductUsage.mockRejectedValue(Object.assign(new Error('PRIVATE_CANARY'), { code }))
+ const response = await submit(good)
+ expect(response.statusCode).toBe(503)
+ expect(response.json().error.code).toBe('USAGE_UNAVAILABLE')
+ expect(response.body).not.toContain('PRIVATE_CANARY')
+})
it('accepts the same native Desktop report exercised through the real daemon proxy', async () => {
const report = JSON.parse(readFileSync(new URL('../../../tests/fixtures/desktop-product-usage-report.json', import.meta.url), 'utf8'))
expect((await submit(report)).statusCode).toBe(200)
@@ -205,6 +231,21 @@ it('keeps legacy explicit setup opt-in without credentials or account lookup', a
}
for (const headers of [{ authorization: 'fixture' }, { cookie: 'PRIVATE_CANARY' }]) expect((await sendSetup(setup, headers)).statusCode).toBe(400)
})
+it('accepts why a Desktop sign-in ended, from the fixed reasons only', async () => {
+ const counters = { setup_desktop_sign_in_started: 2, setup_desktop_sign_in_failed: 1, setup_desktop_sign_in_reason_no_result: 1,
+ setup_desktop_sign_in_reason_cancelled: 1 }
+ expect((await sendSetup({ ...setup, counters })).statusCode).toBe(200)
+ expect(methods.ingestSetupUsage).toHaveBeenCalledWith({ ...setup, counters })
+ methods.ingestSetupUsage.mockClear()
+ for (const reason of ['PRIVATE_CANARY', 'NO_RESULT']) {
+ const response = await sendSetup({ ...setup, counters: { [`setup_desktop_sign_in_reason_${reason}`]: 1 } })
+ expect(response.statusCode).toBe(400)
+ expect(response.body).not.toContain('PRIVATE_CANARY')
+ }
+ // Only Desktop signs in through the CLI; the phone counts its sign-in by button.
+ expect((await sendSetup({ ...setup, counters: { setup_phone_sign_in_reason_timeout: 1 } })).statusCode).toBe(400)
+ expect(methods.ingestSetupUsage).not.toHaveBeenCalled()
+})
it('accepts default-on sharing only for Desktop or phone setup, one at a time, without asserting consent', async () => {
const { consent: _, ...fields } = setup
const report = { ...fields, sharing: 'default' }
@@ -238,7 +279,9 @@ it('bounds untrusted setup writes independently of signed-in reports', async ()
methods.ingestSetupUsage.mockReturnValue(done)
const pending = Array.from({ length: 4 }, () => sendSetup().then((r: { statusCode: number }) => r.statusCode))
await vi.waitFor(() => expect(methods.ingestSetupUsage).toHaveBeenCalledTimes(4))
- expect((await sendSetup()).statusCode).toBe(429)
+ const busy = await sendSetup()
+ expect(busy.statusCode).toBe(429)
+ expectRetryAfter(busy)
expect((await submit(good)).statusCode).toBe(200)
finish({ accepted: true })
expect(await Promise.all(pending)).toEqual([200, 200, 200, 200])
@@ -276,6 +319,20 @@ it('refuses Hub reports with credentials, foreign or malformed counters, or extr
expect((await submit({ ...good, counters: { hub_fork: 1 } })).statusCode).toBe(400)
expect((await sendSetup({ ...setup, counters: { hub_fork: 1 } })).statusCode).toBe(400)
})
+it('answers busy storage behind setup and Hub reports as 429 with a Retry-After, and an outage as 503', async () => {
+ for (const send of [() => sendSetup(), () => sendHub()]) {
+ methods.ingestSetupUsage.mockRejectedValueOnce(Object.assign(new Error('PRIVATE_CANARY'), { code: 'P2034' }))
+ const busy = await send()
+ expect(busy.statusCode).toBe(429)
+ expect(busy.json().error.code).toBe('USAGE_UNAVAILABLE')
+ expectRetryAfter(busy)
+ expect(busy.body).not.toContain('PRIVATE_CANARY')
+ methods.ingestSetupUsage.mockRejectedValueOnce(Object.assign(new Error('PRIVATE_CANARY'), { code: 'P1001' }))
+ const down = await send()
+ expect(down.statusCode).toBe(503)
+ expect(down.headers['retry-after']).toBeUndefined()
+ }
+})
it('does not reflect a Hub storage error', async () => {
methods.ingestSetupUsage.mockRejectedValue(new Error('PRIVATE_CANARY'))
const response = await sendHub()
@@ -291,6 +348,7 @@ it('bounds Hub writes with a budget of their own, so they never starve setup mea
const busy = await sendHub()
expect(busy.statusCode).toBe(429)
expect(busy.json().error.code).toBe('USAGE_UNAVAILABLE')
+ expectRetryAfter(busy)
const setupWhileHubBusy = sendSetup()
await vi.waitFor(() => expect(methods.ingestSetupUsage).toHaveBeenCalledTimes(5))
finish({ accepted: true })
diff --git a/backend/src/routes/productUsage.ts b/backend/src/routes/productUsage.ts
index 84426a6d2..412b347f9 100644
--- a/backend/src/routes/productUsage.ts
+++ b/backend/src/routes/productUsage.ts
@@ -1,4 +1,4 @@
-import type { FastifyInstance } from 'fastify'
+import type { FastifyInstance, FastifyReply } from 'fastify'
import { z } from 'zod'
import { ingestProductUsage, ingestSetupUsage, productUsageChoice, setProductUsageChoice } from '../lib/productUsage.js'
import { PRODUCT_FEEDBACK, PRODUCT_USAGE_MAX_COUNT, PRODUCT_USAGE_METRICS, PRODUCT_USAGE_SETUP_METRICS } from '../types/productUsage.js'
@@ -58,6 +58,24 @@ function writeBudget(perMinute: number, inFlight: number) {
}
}
+/** Busy answers send their client back after 30 to 120 seconds, at random: a fleet refused together does not
+ * return together. The CLI's report backoff honours it (cli/src/gateway/productUsage.ts). */
+function sendBusy(reply: FastifyReply, message: string, code: string): void {
+ reply.header('Retry-After', String(30 + Math.floor(Math.random() * 91)))
+ sendError(reply, message, code, 429)
+}
+/** Storage under load that outlasted its retries, by fixed category: write conflicts on the shared daily totals
+ * (on 2026-10-27, 194 of 223 rejected health reports), a transaction that could not start or finish in time, every
+ * pooled connection in use, a Mongo lock wait. Null for anything else: an outage stays 503, so it still shows. */
+function busyCategory(error: unknown): string | null {
+ const code = (error as { code?: unknown } | null)?.code
+ if (code === 'USAGE_BUSY' || code === 'P2024') return 'USAGE_BUSY'
+ if (code === 'P2034' || code === 'P2002') return 'USAGE_WRITE_CONFLICT'
+ if (code === 'P2028') return 'USAGE_TRANSACTION_FAILED'
+ if (error instanceof Error && error.message.includes('TransientTransactionError')) return 'USAGE_BUSY'
+ return null
+}
+
const REPORT_METRICS = new Set<string>(PRODUCT_USAGE_METRICS)
const SETUP_METRICS = new Set<string>(PRODUCT_USAGE_SETUP_METRICS)
/** A client a release ahead of this backend can name a counter the contract here does not have yet.
@@ -91,9 +109,12 @@ export async function productUsageRoutes(app: FastifyInstance): Promise<void> {
if (!parsed.success) return sendError(reply, 'Invalid setup report', 'INVALID_SETUP_REPORT', 400)
try {
const result = await setupBudget(() => ingestSetupUsage(parsed.data))
- if (result === 'busy') return sendError(reply, 'Setup measurement busy', 'USAGE_UNAVAILABLE', 429)
+ if (result === 'busy') return sendBusy(reply, 'Setup measurement busy', 'USAGE_UNAVAILABLE')
return sendSuccess(reply, result)
- } catch { return sendError(reply, 'Setup measurement unavailable', 'USAGE_UNAVAILABLE', 503) }
+ } catch (error) {
+ if (busyCategory(error)) return sendBusy(reply, 'Setup measurement busy', 'USAGE_UNAVAILABLE')
+ return sendError(reply, 'Setup measurement unavailable', 'USAGE_UNAVAILABLE', 503)
+ }
})
// The same unlinked receipt, atomic totals and today-or-yesterday rule as setup; no account lookup.
app.post('/api/product-usage/hub', { bodyLimit: 4096 }, async (req, reply) => {
@@ -102,9 +123,12 @@ export async function productUsageRoutes(app: FastifyInstance): Promise<void> {
if (!parsed.success) return sendError(reply, 'Invalid Hub report', 'INVALID_HUB_REPORT', 400)
try {
const result = await hubBudget(() => ingestSetupUsage(parsed.data))
- if (result === 'busy') return sendError(reply, 'Hub measurement busy', 'USAGE_UNAVAILABLE', 429)
+ if (result === 'busy') return sendBusy(reply, 'Hub measurement busy', 'USAGE_UNAVAILABLE')
return sendSuccess(reply, result)
- } catch { return sendError(reply, 'Hub measurement unavailable', 'USAGE_UNAVAILABLE', 503) }
+ } catch (error) {
+ if (busyCategory(error)) return sendBusy(reply, 'Hub measurement busy', 'USAGE_UNAVAILABLE')
+ return sendError(reply, 'Hub measurement unavailable', 'USAGE_UNAVAILABLE', 503)
+ }
})
app.get('/api/product-usage/settings', async (req, reply) => {
if (!req.user?.sub) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)
@@ -138,11 +162,9 @@ export async function productUsageRoutes(app: FastifyInstance): Promise<void> {
try { return sendSuccess(reply, await ingestProductUsage(req.user.sub, parsed.data)) }
catch (error) {
// A fixed category can diagnose delivery without exposing database errors or report contents.
- const storageCode = (error as { code?: unknown } | null)?.code
- if (storageCode === 'USAGE_BUSY') return sendError(reply, 'Usage measurement busy', 'USAGE_BUSY', 429)
- const code = storageCode === 'P2034' || storageCode === 'P2002' ? 'USAGE_WRITE_CONFLICT'
- : storageCode === 'P2028' ? 'USAGE_TRANSACTION_FAILED' : 'USAGE_UNAVAILABLE'
- return sendError(reply, 'Usage report unavailable', code, 503)
+ const busy = busyCategory(error)
+ if (busy) return sendBusy(reply, 'Usage measurement busy', busy)
+ return sendError(reply, 'Usage report unavailable', 'USAGE_UNAVAILABLE', 503)
}
})
}
diff --git a/backend/src/routes/superTabs.test.ts b/backend/src/routes/superTabs.test.ts
new file mode 100644
index 000000000..5407aff82
--- /dev/null
+++ b/backend/src/routes/superTabs.test.ts
@@ -0,0 +1,52 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import Fastify, { type FastifyInstance } from 'fastify'
+import { Prisma } from '@prisma/client'
+import { errorHandler } from '../middlewares/errorHandler.js'
+import { SuperTabError } from '../superTabs/model.js'
+import { superTabRoutes } from './superTabs.js'
+
+describe('Super Tab route failures', () => {
+ let app: FastifyInstance
+ let thrown: unknown
+ beforeEach(async () => {
+ app = Fastify()
+ app.setErrorHandler(errorHandler)
+ app.addHook('onRequest', async request => { request.user = { sub: 'u1', email: '[email protected]', autonomousEnv: 'prod', role: 'user' } as never })
+ const store = { hostGrids: async () => { throw thrown }, native: { append: async () => { throw thrown } } }
+ await app.register(superTabRoutes, { store: store as never, github: null, reads: {} as never, hosts: {} as never })
+ await app.ready()
+ })
+ afterEach(async () => { await app.close() })
+
+ it('answers a busy Swarm with Retry-After', async () => {
+ thrown = new SuperTabError('SWARM_BUSY', 'This Swarm is busy. Try again in a moment.', 503)
+ const res = await app.inject({ method: 'GET', url: '/api/super-tabs/grids' })
+ expect(res.statusCode).toBe(503)
+ expect(res.headers['retry-after']).toBe('2')
+ expect(res.json().error.code).toBe('SWARM_BUSY')
+ })
+
+ it('answers a refusal with its own status and no Retry-After', async () => {
+ thrown = new SuperTabError('FORBIDDEN', 'Not yours.', 403)
+ const res = await app.inject({ method: 'GET', url: '/api/super-tabs/grids' })
+ expect(res.statusCode).toBe(403)
+ expect(res.headers['retry-after']).toBeUndefined()
+ })
+
+ it('answers an expired transaction as a retryable 503, not 500', async () => {
+ thrown = new Prisma.PrismaClientKnownRequestError('Transaction API error: Transaction already closed', { code: 'P2028', clientVersion: 'test' })
+ const res = await app.inject({ method: 'GET', url: '/api/super-tabs/grids' })
+ expect(res.statusCode).toBe(503)
+ expect(res.headers['retry-after']).toBe('2')
+ })
+
+ it('answers a terminal recording\'s duplicate key as busy, so the host keeps recording and retries', async () => {
+ // The host stops a recording for good on a 409 (cli superTabs/native.ts); a duplicate that outlived every retry is
+ // not the recording's fault.
+ thrown = new Prisma.PrismaClientKnownRequestError('Unique constraint failed', { code: 'P2002', clientVersion: 'test' })
+ const res = await app.inject({ method: 'POST', url: '/api/super-tabs/tab-1/native/ctx-1', payload: { turnId: 'turn-1', kind: 'prompt', previousEventId: null, text: 'hi', truncated: false, interrupted: false } })
+ expect(res.statusCode).toBe(503)
+ expect(res.headers['retry-after']).toBe('2')
+ expect(res.json().error.code).toBe('SWARM_BUSY')
+ })
+})
diff --git a/backend/src/routes/superTabs.ts b/backend/src/routes/superTabs.ts
index 152523aca..b93636abd 100644
--- a/backend/src/routes/superTabs.ts
+++ b/backend/src/routes/superTabs.ts
@@ -85,11 +85,19 @@ const githubStartToken = z.object({ always: z.boolean().optional() }).strict()
async function respond(reply: FastifyReply, action: () => Promise<unknown>) {
try { sendSuccess(reply, await action()) } catch (error) {
if (error instanceof GitHubAppError) return sendError(reply, error.message, error.code, error.status, error.details)
- if (!(error instanceof SuperTabError)) throw error
- sendError(reply, error.message, error.code, error.status)
+ // A Swarm refusal, a busy Swarm (503 with Retry-After), an expired transaction or a duplicate key: the shared
+ // error handler answers each deliberately, and every other failure stays a 500 with its stack logged.
+ throw error
}
}
+/** A terminal recording's host stops recording for good on a 409 (cli superTabs/native.ts). A duplicate key that outlived
+ * every transaction retry is not the recording's fault, so it answers busy, which the host retries. */
+function busyOnDuplicate(error: unknown): never {
+ if ((error as { code?: unknown } | null)?.code === 'P2002') fail('SWARM_BUSY', 'This Swarm is busy. Try again in a moment.', 503)
+ throw error
+}
+
/** Uses the normal authenticated control API. It never accepts caller-provided host/contributor identities.
* `github` is the Harness GitHub App (github/tokens.ts): read from the environment unless given, null when off. */
/** Full-state reads of clients from before Swarms were stored by parts (design 4.11): every old client reads one of them
@@ -154,7 +162,7 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
(req, reply) => respond(reply, () => store.native.read(req.user!, req.params.tabId, req.params.contextId)))
app.post<{ Params: z.infer<typeof nativeParams>; Body: z.infer<typeof nativeEventSchema> }>('/api/super-tabs/:tabId/native/:contextId',
{ preHandler: [validateParams(nativeParams), validateBody(nativeEventSchema)] },
- (req, reply) => respond(reply, () => store.native.append(req.user!, req.params.tabId, req.params.contextId, req.body)))
+ (req, reply) => respond(reply, () => store.native.append(req.user!, req.params.tabId, req.params.contextId, req.body).catch(busyOnDuplicate)))
app.get('/api/super-tabs/routing-policy', (req, reply) => respond(reply, () => store.accountPolicy(req.user!)))
app.post<{ Body: z.infer<typeof savePolicy> }>('/api/super-tabs/routing-policy', { preHandler: validateBody(savePolicy) },
(req, reply) => respond(reply, () => store.saveAccountPolicy(req.user!, req.body.revision, req.body.policy)))
diff --git a/backend/src/server.ts b/backend/src/server.ts
index bb3765b31..6677faa06 100644
--- a/backend/src/server.ts
+++ b/backend/src/server.ts
@@ -17,8 +17,11 @@ import { handleWebUpgrade } from './lib/webWs.js'
import { handleManagerUpgrade } from './lib/managerWs.js'
import { handleAdapterUpgrade } from './lib/adapterWs.js'
import { logger } from './utils/logger.js'
+import { registerSecurityHeaders } from './middlewares/securityHeaders.js'
import { startTurnCredentialRefresh } from './lib/turnCredentials.js'
-import { closeBus, redisCount, redisSsoProfileStore } from './lib/bus.js'
+import { closeBus, pub, redisCount, redisSsoProfileStore } from './lib/bus.js'
+import { prisma } from './lib/prisma.js'
+import { backendReadinessChecks, createReadiness, drainBeforeClosing, processDrain } from './lib/readiness.js'
import { useSharedSsoProfileStore } from './lib/ssoAuth.js'
import { selfProfileFromEnv } from './lib/selfProfile.js'
import { drainAllSockets, openSocketCount, RELEASE_UPGRADE_SLOT, type SlotSocket } from './lib/wsServer.js'
@@ -126,13 +129,7 @@ async function start(): Promise<void> {
registerJsonBodyParser(app)
- app.addHook('onSend', async (_request, reply) => {
- reply.header('X-Content-Type-Options', 'nosniff')
- reply.header('Referrer-Policy', 'strict-origin-when-cross-origin')
- if (env.NODE_ENV === 'production') {
- reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
- }
- })
+ registerSecurityHeaders(app)
// Allow all origins (reflect the request origin so credentialed requests work too). Methods +
// headers are reflected (allowedHeaders omitted → echoes Access-Control-Request-Headers), so any
@@ -150,7 +147,12 @@ async function start(): Promise<void> {
// SSO access-token gate for the control API (data-plane auth happens before Fastify).
registerAuthMiddleware(app)
- await registerControlRoutes(app, { daemons: DAEMONS, count: redisCount })
+ // Mongo always; Redis where one is configured. Each answers within 1 s or counts as down (lib/readiness.ts).
+ const readiness = createReadiness(backendReadinessChecks(process.env, {
+ mongo: () => prisma.$runCommandRaw({ ping: 1 }),
+ redis: () => pub.ping(),
+ }))
+ await registerControlRoutes(app, { daemons: DAEMONS, count: redisCount, readiness })
logger.info(describeDaemonsSwitch(DAEMONS))
// Dedicated public subdomain app-proxy on its own port (Host-header routed → tunnelled to the node app).
@@ -164,6 +166,9 @@ async function start(): Promise<void> {
shuttingDown = true
logger.info(`Received ${signal}, shutting down...`, { openSockets: openSocketCount() })
try {
+ // Readiness answers 503 from here on. On a signal, keep serving for DRAIN_DELAY_MS first so the load balancer
+ // takes this process out of rotation before its listeners close; a crash closes at once.
+ await drainBeforeClosing(processDrain, exitCode === 0 ? env.DRAIN_DELAY_MS : 0)
appProxyServer.close()
meshServer?.close()
// Start Fastify's close (it tells the http server to stop accepting new connections) but DON'T await
@@ -177,9 +182,10 @@ async function start(): Promise<void> {
// handlers clear presence/owner keys as fire-and-forget Redis writes. Let them land before closeBus
// quits the connection, else a half-open socket's key survives on TTL alone.
await new Promise((resolve) => setTimeout(resolve, 250))
- // Bounded wait for Fastify to finish (onClose hooks, Prisma disconnect); never block shutdown on it.
+ // Bounded wait for Fastify to finish its onClose hooks; never block shutdown on it.
await Promise.race([fastifyClosed, new Promise((resolve) => setTimeout(resolve, 5_000))])
- await closeBus()
+ // The database stays connected through the drain, for the requests still being served (lib/prisma.ts).
+ await Promise.allSettled([prisma.$disconnect(), closeBus()])
process.exit(exitCode)
} catch (err) {
logger.error('Error during shutdown', err)
diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.ts
index 90f973c8d..13158252f 100644
--- a/backend/src/superTabs/commands.test.ts
+++ b/backend/src/superTabs/commands.test.ts
@@ -880,6 +880,14 @@ it('accepts POSIX, Windows drive and UNC folders and refuses relative, drive-rel
const refused = contribute('relative')
expect(!refused.success && refused.error.issues[0]!.message).toBe('Use a full folder path, such as /home/me/work or C:\\Users\\me\\work.')
})
+it('lets a big machine offer more than 16 agents and refuses only counts that are not whole, positive and sane', () => {
+ const f = fixture()
+ const contribute = (maxAgents: number) => commandSchema.safeParse({ type: 'machine.contribute', machineId: 'host', name: 'Studio', cwd: '/repo', engines: ['claude'], maxAgents })
+ for (const maxAgents of [1, 17, 96, 1024]) expect(contribute(maxAgents).success, String(maxAgents)).toBe(true)
+ for (const maxAgents of [0, -1, 2.5, 1025]) expect(contribute(maxAgents).success, String(maxAgents)).toBe(false)
+ f.run(contribute(96).data!, owner, { contribution: { machineOwnerId: 'owner', contributorId: 'owner' } })
+ expect(f.state.machines![0]!.maxAgents).toBe(96)
+})
it('restricts recording a legacy project to the owner or controlling lead', () => {
const f = fixture(); f.invite()
const command: Command = { type: 'tab.project', machineId: 'host', project: { cwd: '/repo', repositoryUrl: null } }
@@ -1648,6 +1656,23 @@ describe('a failed start\'s reason', () => {
// The start keeps the raw reason for those who may read it.
expect(f.state.starts![0]!.error).toBe(RAW)
})
+ // Ken's MacBook Pro, 2026-10-28: a start refused for memory read as a broken machine. Members see a machine's free memory in
+ // the Machines view, so that reason, and only its numbers, is told as it is.
+ it('tells the group a memory shortage with its numbers, and keeps every other reason hidden, even one that starts like it', () => {
+ const f = fixture(); f.invite()
+ failed(f)
+ const memory = 'Not enough free memory: 1.8 GiB free, 2 GiB needed. 6 GiB more is set aside for agents still starting.'
+ expect(f.run({ type: 'agent.startFailed', startId: 's1', error: memory }, owner).messages[0]!.text)
+ .toBe('Could not start Builder: its machine has only 1.8 GiB of memory free, and it needs 2 GiB.')
+ // A member who did not make the start reads the same, never the rest of the host's reason.
+ f.state.starts![0]!.actorKey = 'person:someone'
+ expect(visibleState(f.state, owner).starts![0]!.error).toBe('Its machine has only 1.8 GiB of memory free, and it needs 2 GiB.')
+ for (const error of ['Not enough free memory on /Users/ken: 1.8 GiB free, 2 GiB needed.', 'Not enough free memory: lots free, 2 GiB needed.', RAW]) {
+ failed(f)
+ expect(f.run({ type: 'agent.startFailed', startId: 's1', error }, owner).messages[0]!.text)
+ .toBe('Could not start Builder: its machine could not prepare or launch it. The Lead and the machine owner can read why.')
+ }
+ })
it('hands the raw reason on the start only to its Lead and the machine owner', () => {
const f = fixture(); f.invite()
const lead = f.add('lead-agent', 'owner', 'lead', true), worker = f.add('worker', 'owner')
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index b5a0b3266..db534d168 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -50,6 +50,9 @@ const repositoryUrl = z.string().max(4096).refine(value => {
} catch { return false }
}, 'Share a repository URL without credentials.')
const project = z.object({ cwd: path, repositoryUrl: repositoryUrl.nullable() }).strict()
+// How many agents a machine offers is its owner's choice: the CLI suggests at most its total RAM / 2 GB (192 GB offers 96).
+// The 16 this once was held the Mac Studio far below that (Ken, 2026-10-28); 1024 only refuses a number no machine could run.
+const maxAgents = z.number().int().min(1).max(1024)
// Copied Default roles keep the ids lead, dev and review; a role the owner adds gets 12 random hex characters from the client.
const roleId = z.string().regex(/^([0-9a-f]{12}|lead|dev|review)$/)
const role = z.object({ id: roleId, name: z.string().trim().min(1).max(40), kind: z.enum(['lead', 'builder', 'reviewer']),
@@ -75,7 +78,7 @@ const task = z.object({
}).strict()
export const commandSchema = z.discriminatedUnion('type', [
- z.object({ type: z.literal('machine.contribute'), machineId: id, name: title, cwd: path, scope: z.literal('swarm').optional(), engines: z.array(swarmEngine).min(1).max(2), maxAgents: z.number().int().min(1).max(16),
+ z.object({ type: z.literal('machine.contribute'), machineId: id, name: title, cwd: path, scope: z.literal('swarm').optional(), engines: z.array(swarmEngine).min(1).max(2), maxAgents,
ifMissing: z.literal(true).optional() }).strict(),
z.object({ type: z.literal('machine.pause'), machineId: id, paused: z.boolean() }).strict(),
z.object({ type: z.literal('machine.remove'), machineId: id }).strict(),
diff --git a/backend/src/superTabs/migration/dropLegacy.test.ts b/backend/src/superTabs/migration/dropLegacy.test.ts
new file mode 100644
index 000000000..3aea7163d
--- /dev/null
+++ b/backend/src/superTabs/migration/dropLegacy.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import { dropOptions } from './dropLegacy.js'
+
+describe('the old state removal script\'s options', () => {
+ it('only counts by default', () => {
+ expect(dropOptions([])).toEqual({ apply: false, batch: 100 })
+ })
+
+ it('removes only when the backup is confirmed too', () => {
+ expect(() => dropOptions(['--apply'])).toThrow('--backup-confirmed')
+ expect(dropOptions(['--apply', '--backup-confirmed'])).toEqual({ apply: true, batch: 100 })
+ expect(dropOptions(['--backup-confirmed', '--apply', '--batch', '25'])).toEqual({ apply: true, batch: 25 })
+ })
+
+ it('refuses a batch that is not a positive whole number, and unknown options', () => {
+ for (const batch of ['0', '-1', '2.5', 'many']) expect(() => dropOptions(['--batch', batch])).toThrow('--batch')
+ expect(() => dropOptions(['--batch'])).toThrow('--batch')
+ expect(() => dropOptions(['--force'])).toThrow('--force')
+ })
+})
diff --git a/backend/src/superTabs/migration/dropLegacy.ts b/backend/src/superTabs/migration/dropLegacy.ts
new file mode 100644
index 000000000..cf97ee2e9
--- /dev/null
+++ b/backend/src/superTabs/migration/dropLegacy.ts
@@ -0,0 +1,69 @@
+/**
+ * Removes the old state each migrated Swarm keeps (`SuperTab.legacyState`, design 6.1: about 1 MB for a busy Swarm) once
+ * every Swarm is in parts. Without it, `rollbackLegacy` refuses that Swarm; `rollbackFromParts`, which every Swarm written
+ * since its migration needs anyway, rebuilds the old state from the parts. Run by scripts/swarm-parts/drop-legacy-state.ts.
+ */
+import type { PrismaClient } from '@prisma/client'
+
+export interface DropOptions {
+ /** Removes the old states; otherwise only counts them. */
+ apply?: boolean
+ /** Swarms per write. */
+ batch?: number
+}
+/** Counts and sizes only: nothing that names a Swarm or shows its content. */
+export interface DropReport {
+ ok: boolean; swarms: number; unmigrated: number; kept: number; keptBytes: number; removed: number; batches: number
+ /** Removals the database refused. The run stops at the first batch with one, or that removes nothing. */
+ writeErrors: number
+}
+
+export const DEFAULT_BATCH = 100
+/** Not in parts: format 1, or a row from before the field, which reads as 1. */
+const UNMIGRATED = { format: { $ne: 2 } }
+const KEPT = { format: 2, legacyState: { $type: 'object' } }
+
+interface Batch<T> { cursor: { firstBatch: T[] } }
+async function count(db: PrismaClient, query: object): Promise<number> {
+ return Number((await db.$runCommandRaw({ count: 'SuperTab', query }) as { n: unknown }).n)
+}
+
+export async function dropLegacyStates(db: PrismaClient, { apply = false, batch = DEFAULT_BATCH }: DropOptions = {}): Promise<DropReport> {
+ const [swarms, unmigrated] = [await count(db, {}), await count(db, UNMIGRATED)]
+ const [size] = (await db.$runCommandRaw({ aggregate: 'SuperTab', cursor: {}, pipeline: [{ $match: KEPT },
+ { $group: { _id: null, kept: { $sum: 1 }, keptBytes: { $sum: { $bsonSize: '$legacyState' } } } }] }) as unknown as Batch<{ kept: number; keptBytes: number }>).cursor.firstBatch
+ const report = { ok: unmigrated === 0, swarms, unmigrated, kept: size?.kept ?? 0, keptBytes: size?.keptBytes ?? 0, removed: 0, batches: 0, writeErrors: 0 }
+ if (!report.ok || !apply) return report
+ for (;;) {
+ const ids = (await db.$runCommandRaw({ find: 'SuperTab', filter: KEPT, projection: { _id: 1 }, limit: batch }) as unknown as Batch<{ _id: string }>)
+ .cursor.firstBatch.map(row => row._id)
+ if (!ids.length) return report
+ // Only rows still in parts: one rolled back meanwhile keeps whatever it holds.
+ const updated = await db.$runCommandRaw({ update: 'SuperTab', updates: [{ q: { _id: { $in: ids }, ...KEPT }, u: { $unset: { legacyState: '' } }, multi: true }] }) as
+ { nModified: unknown; writeErrors?: unknown[] }
+ const removed = Number(updated.nModified)
+ report.removed += removed
+ report.writeErrors += updated.writeErrors?.length ?? 0
+ report.batches++
+ // The same rows would come back from the next find: a refused or empty batch would repeat for ever.
+ if (!removed || updated.writeErrors?.length) return report
+ }
+}
+
+/** `--apply` removes, and only with `--backup-confirmed`: removing cannot be undone without a backup. `--batch N`. */
+export function dropOptions(argv: readonly string[]): Required<DropOptions> {
+ const options = { apply: false, batch: DEFAULT_BATCH }
+ let backupConfirmed = false
+ for (let i = 0; i < argv.length; i++) {
+ const flag = argv[i]
+ if (flag === '--apply') options.apply = true
+ else if (flag === '--backup-confirmed') backupConfirmed = true
+ else if (flag === '--batch') {
+ const value = Number(argv[++i])
+ if (!Number.isInteger(value) || value < 1) throw new Error('--batch needs a positive whole number')
+ options.batch = value
+ } else throw new Error(`Unknown option ${flag}`)
+ }
+ if (options.apply && !backupConfirmed) throw new Error('Removing the old states cannot be undone. Back up the database first, then add --backup-confirmed.')
+ return options
+}
diff --git a/backend/src/superTabs/parts/light.ts b/backend/src/superTabs/parts/light.ts
index 68f0eec23..cc3d0bcfd 100644
--- a/backend/src/superTabs/parts/light.ts
+++ b/backend/src/superTabs/parts/light.ts
@@ -36,7 +36,7 @@ const LIGHT_GROUP = {
}
/** A date as `aggregateRaw` returns it: Extended JSON. */
-function ms(value: unknown): number {
+export function ms(value: unknown): number {
const date = (value as { $date?: unknown } | null)?.$date ?? value
if (typeof date === 'string') return Date.parse(date)
if (typeof date === 'number') return date
diff --git a/backend/src/superTabs/parts/load.ts b/backend/src/superTabs/parts/load.ts
index 846a73a25..0ad9c3b4a 100644
--- a/backend/src/superTabs/parts/load.ts
+++ b/backend/src/superTabs/parts/load.ts
@@ -2,6 +2,7 @@ import type { Prisma } from '@prisma/client'
import { delegate, extracted, partId, type PartRow } from './write.js'
import type { GroupData, HeadData, Part, PartKind, SwarmParts } from './types.js'
import { PART_KINDS } from './types.js'
+import { ms } from './light.js'
type Transaction = Prisma.TransactionClient
type Where = Record<string, unknown>
@@ -83,14 +84,18 @@ export async function loadDormant(tx: Transaction, tabId: string,
return rows.map(row => toPart<GroupData>('group', row as unknown as PartRow))
}
-/** The newest data change of each Swarm, over all its parts (design section 3.7). A touch does not count. */
+/** The newest data change of each Swarm, over all its parts (design section 3.7). A touch does not count.
+ * One `$group` with `$max` per part kind, run by Mongo itself: Prisma's groupBy here can panic its engine on Mongo, which
+ * then fails every later query of the process (as groupBy on SuperTabDecision did, 2026-10-27). */
export async function lastChangedAt(tx: Transaction, tabIds: string[]): Promise<Map<string, number>> {
const newest = new Map<string, number>()
if (!tabIds.length) return newest
for (const kind of PART_KINDS) {
- for (const row of await delegate(tx, kind).groupBy({ by: ['tabId'], where: { tabId: { in: tabIds } }, _max: { changedAt: true } })) {
- const at = row._max.changedAt?.getTime() ?? 0
- if (at > (newest.get(row.tabId) ?? 0)) newest.set(row.tabId, at)
+ const rows = await delegate(tx, kind).aggregateRaw({ pipeline: [{ $match: { tabId: { $in: tabIds } } },
+ { $group: { _id: '$tabId', at: { $max: '$changedAt' } } }] }) as Array<{ _id: string; at: unknown }>
+ for (const row of rows) {
+ const at = row.at ? ms(row.at) : 0
+ if (at > (newest.get(row._id) ?? 0)) newest.set(row._id, at)
}
}
return newest
diff --git a/backend/src/superTabs/parts/write.ts b/backend/src/superTabs/parts/write.ts
index 34df859b5..448331b03 100644
--- a/backend/src/superTabs/parts/write.ts
+++ b/backend/src/superTabs/parts/write.ts
@@ -39,7 +39,7 @@ export function delegate(tx: Transaction, kind: PartKind) {
create(args: { data: Record<string, unknown> }): Promise<unknown>
createMany(args: { data: Record<string, unknown>[] }): Promise<unknown>
updateMany(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<{ count: number }>
- groupBy(args: unknown): Promise<Array<{ tabId: string; _max: { changedAt: Date | null } }>>
+ aggregateRaw(args: { pipeline: Record<string, unknown>[] }): Promise<unknown>
}
}
export interface PartRow { id: string; tabId: string; key: string; version: number; changedAt: Date; deleted: boolean; ordinal: number; data: unknown
diff --git a/backend/src/superTabs/startFailure.ts b/backend/src/superTabs/startFailure.ts
index 0573ebab4..9245fb19a 100644
--- a/backend/src/superTabs/startFailure.ts
+++ b/backend/src/superTabs/startFailure.ts
@@ -18,8 +18,15 @@ const TIMEOUTS: Array<[string, string]> = [[TIMED_OUT_SUFFIX, TIMED_OUT],
export const MACHINE_REMOVED = 'Its machine was removed from the Swarm.'
export const ABANDONED = 'Abandoned before it started.'
+/** A host's refusal for memory (cli superTabs/capacity.ts memoryShort): its numbers alone, which members already see in the
+ * Machines view. Read only at the start of the reason, so nothing else a host wrote is ever told (Ken's MacBook Pro,
+ * 2026-10-28, where "could not prepare or launch it" sent people looking for a fault). */
+const MEMORY_SHORT = /^Not enough free memory: (\d+(?:\.\d)? GiB) free, (\d+(?:\.\d)? GiB) needed\./
+
export function publicReason(error: string): string {
if (error === MACHINE_REMOVED || error === ABANDONED) return error
+ const memory = MEMORY_SHORT.exec(error)
+ if (memory) return `Its machine has only ${memory[1]} of memory free, and it needs ${memory[2]}.`
return TIMEOUTS.find(([suffix]) => error.endsWith(suffix))?.[1] ?? MACHINE_FAILED
}
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index 112c89756..0c7931afa 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -1,6 +1,6 @@
import { contributedEngines, expireRemovals, LASTING_TEAM_REFUSALS, machineContribution, machineObservationSchema, machineSlots, observedPrivacy, recordAgentPresence, removalPreview, startPreparing, swarmGridRow, teamAccountRequired, teamWorkRefusal, type MachineObservation } from './machines.js'
import { createHash } from 'node:crypto'
-import type { Prisma, PrismaClient, SuperTab, SuperTabDelivery, SuperTabMessage } from '@prisma/client'
+import type { Prisma, PrismaClient, SuperTabDelivery, SuperTabMessage } from '@prisma/client'
import type { AuthUser } from '../lib/ssoAuth.js'
import { machineAlive } from '../lib/prisma.js'
import { isTeamSession, teamMachine, TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE } from '../lib/teamSession.js'
@@ -52,14 +52,18 @@ type SendCommand = Extract<Command, { type: 'message.send' }>
// Prisma on MongoDB: `usedBy: null` alone misses rows that never had the field.
const unused = { OR: [{ usedBy: null }, { usedBy: { isSet: false } }] }
const hash = (value: unknown): string => createHash('sha256').update(JSON.stringify(value)).digest('hex')
+/** The fields of a Swarm's row the store reads. A migrated row still keeps its whole old state (`legacyState`, about 1 MB
+ * for a busy Swarm) until the maintenance script removes it, and every command and read loads this row. */
+const SWARM_ROW = { id: true, ownerId: true, revision: true, format: true } satisfies Prisma.SuperTabSelect
+export type SwarmRow = Prisma.SuperTabGetPayload<{ select: typeof SWARM_ROW }>
/** A Swarm whose state still waits for its split into parts (design section 6.1) is not served until it is split. */
-function requireParts(row: SuperTab): SuperTab {
+function requireParts(row: SwarmRow): SwarmRow {
if (row.format !== 2) fail('SWARM_MIGRATING', 'This Swarm is being updated. Try again in a moment.', 503)
return row
}
/** What a command or read works on: the index row, the parts it loaded, and the state reassembled from them. */
-export interface Loaded { row: SuperTab; parts: SwarmParts; state: SuperTabState }
+export interface Loaded { row: SwarmRow; parts: SwarmParts; state: SuperTabState }
/** Groups, agents, projects and starts a command names, loaded even when dormant or finished (design section 3.1). */
export interface Named { groupIds?: string[]; agentIds?: string[]; projectIds?: string[]; startIds?: string[]; startAgentIds?: string[]; allGroups?: boolean; includeRecentStarts?: boolean }
@@ -111,7 +115,7 @@ function deliveryTouches(delivery: SuperTabDelivery): Touch[] {
/** Loads one Swarm's parts and the state commands run on. Reads never write (design ruling R8); the migration rebuilt
* every group's link list from its history. */
-export async function loadRow(tx: Transaction, row: SuperTab, named: Named = {}): Promise<Loaded> {
+export async function loadRow(tx: Transaction, row: SwarmRow, named: Named = {}): Promise<Loaded> {
const parts = await loadActive(tx, row.id, named)
const state = reassemble(parts)
parkLaterConversations(state)
@@ -134,9 +138,10 @@ export async function transaction<T>(db: Pick<PrismaClient, '$transaction'>, bod
for (let attempt = 1; ; attempt++) {
try { return await db.$transaction(body, TRANSACTION_OPTIONS) } catch (error) {
if (!retryable(error)) throw error
- if (attempt >= TRANSACTION_ATTEMPTS) {
+ // An expired or unstartable transaction (P2028) is load: one more try, then the client retries after Retry-After.
+ if (attempt >= (errorCode(error) === 'P2028' ? EXPIRED_TRANSACTION_ATTEMPTS : TRANSACTION_ATTEMPTS)) {
// A unique key still taken after every retry is a real duplicate, not contention.
- if ((error as { code?: unknown }).code === 'P2002') throw error
+ if (errorCode(error) === 'P2002') throw error
fail('SWARM_BUSY', 'This Swarm is busy. Try again in a moment.', 503)
}
await sleep(Math.random() * Math.min(TRANSACTION_BACKOFF_CAP_MS, TRANSACTION_BACKOFF_MS * 2 ** (attempt - 1)))
@@ -149,12 +154,13 @@ const OPEN_DELIVERY = ['queued', 'claimed', 'uncertain'] as const
/** Callers kept for the quiet delivery poll before the stale ones are dropped. */
const POLLED_CAP = 5_000
const TRANSACTION_ATTEMPTS = 8
+const EXPIRED_TRANSACTION_ATTEMPTS = 2
const TRANSACTION_BACKOFF_MS = 50
const TRANSACTION_BACKOFF_CAP_MS = 1_500
+const errorCode = (error: unknown): unknown => error && typeof error === 'object' && 'code' in error ? error.code : null
function retryable(error: unknown): boolean {
if (!error || typeof error !== 'object') return false
- const code = 'code' in error ? error.code : null
- return code === 'P2034' || code === 'P2002' || (error instanceof Error && error.message.includes('TransientTransactionError'))
+ return ['P2034', 'P2002', 'P2028'].includes(errorCode(error) as string) || (error instanceof Error && error.message.includes('TransientTransactionError'))
}
/** A Lead's start dispatches within seconds of being recorded; one still undispatched after this long was given up. */
@@ -331,7 +337,7 @@ export class SuperTabStore {
/** Shared with the read API (superTabs/read, design section 7.2). */
async row(tx: Transaction, user: AuthUser, tabId: string) {
- return requireParts(await tx.superTab.findFirst({ where: { id: tabId, autonomousEnv: user.autonomousEnv } }) ??
+ return requireParts(await tx.superTab.findFirst({ where: { id: tabId, autonomousEnv: user.autonomousEnv }, select: SWARM_ROW }) ??
fail('NOT_FOUND', 'This Super Tab is unavailable.', 404))
}
@@ -488,7 +494,7 @@ export class SuperTabStore {
async list(user: AuthUser, after?: string) {
this.personOnly(user)
const rows = await this.db.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, memberIds: { has: user.sub },
- ...(after ? { id: { gt: after } } : {}) }, orderBy: { id: 'asc' }, take: 101 })
+ ...(after ? { id: { gt: after } } : {}) }, orderBy: { id: 'asc' }, take: 101, select: SWARM_ROW })
const heads = await this.heads(rows.slice(0, 100))
return { tabs: rows.slice(0, 100).flatMap(row => {
const head = heads.get(row.id)
@@ -536,7 +542,7 @@ export class SuperTabStore {
async invitations(user: AuthUser) {
this.personOnly(user)
const email = user.email.trim().toLowerCase()
- const rows = await this.db.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, invitedEmails: { has: email } }, take: 100 })
+ const rows = await this.db.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, invitedEmails: { has: email } }, take: 100, select: SWARM_ROW })
const heads = await this.heads(rows)
return rows.flatMap(row => {
const state = heads.get(row.id)
@@ -547,7 +553,7 @@ export class SuperTabStore {
}
/** The heads of Swarms already split into parts, by id. */
- private async heads(rows: SuperTab[]): Promise<Map<string, HeadData>> {
+ private async heads(rows: SwarmRow[]): Promise<Map<string, HeadData>> {
const heads = await this.db.swarmHead.findMany({ where: { id: { in: rows.filter(r => r.format === 2).map(r => `${r.id}:head`) } } })
return new Map(heads.map(head => [head.tabId, head.data as unknown as HeadData]))
}
@@ -689,7 +695,7 @@ export class SuperTabStore {
if (command?.type === 'agent.startDispatch' && hostMachineId && error instanceof SuperTabError && LASTING_TEAM_REFUSALS.includes(error.code)) {
// Only one never launched: a repeated dispatch of a launched start is admitted again too, and its agent may be starting.
const start = await transaction(this.db, async tx => {
- const row = await tx.superTab.findFirst({ where: { id: tabId, autonomousEnv: user.autonomousEnv } })
+ const row = await tx.superTab.findFirst({ where: { id: tabId, autonomousEnv: user.autonomousEnv }, select: SWARM_ROW })
return row?.format === 2 ? (await loadRow(tx, row, { startIds: [command.startId] })).state.starts?.find(s => s.id === command.startId) : undefined
})
if (start && !start.dispatched && !start.harnessId && !start.error) {
@@ -1368,7 +1374,7 @@ export class SuperTabStore {
const result = []
for (const row of rows) {
if (!states.has(row.tabId)) {
- const tab = await tx.superTab.findFirst({ where: { id: row.tabId, autonomousEnv: user.autonomousEnv } })
+ const tab = await tx.superTab.findFirst({ where: { id: row.tabId, autonomousEnv: user.autonomousEnv }, select: SWARM_ROW })
states.set(row.tabId, tab?.format === 2 ? (await loadRow(tx, tab)).state : null)
}
const refusal = now - row.createdAt.getTime() > TERMINAL_PICKUP_MS
@@ -1603,7 +1609,7 @@ export class SuperTabStore {
/** The owner's Swarms with the Local models add-on: what the owner's computer creates on grid and keeps in step. */
async hostGrids(user: AuthUser) {
this.personOnly(user)
- const rows = await this.db.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, ownerId: user.sub, format: 2 }, take: 100 })
+ const rows = await this.db.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, ownerId: user.sub, format: 2 }, take: 100, select: SWARM_ROW })
return transaction(this.db, async tx => {
const grids = []
for (const row of rows) { const grid = swarmGridRow(row.id, (await loadRow(tx, row)).state); if (grid) grids.push(grid) }
@@ -1894,7 +1900,7 @@ export class SuperTabStore {
* queued deliveries are kept for when it reopens, as a person's archive keeps them. True when it archived. */
async archiveFinished(tabId: string, groupId: string, checked: readonly string[]): Promise<boolean> {
return transaction(this.db, async tx => {
- const row = await tx.superTab.findUnique({ where: { id: tabId } })
+ const row = await tx.superTab.findUnique({ where: { id: tabId }, select: SWARM_ROW })
if (!row) return false
const loaded = await loadRow(tx, requireParts(row), { groupIds: [groupId] }), state = structuredClone(loaded.state)
const group = state.conversations.find(c => c.id === groupId)
diff --git a/backend/src/superTabs/sweeps.ts b/backend/src/superTabs/sweeps.ts
index 833ec2014..b14d85b8a 100644
--- a/backend/src/superTabs/sweeps.ts
+++ b/backend/src/superTabs/sweeps.ts
@@ -105,7 +105,7 @@ async function expireInvitations(db: PrismaClient, now: number): Promise<number>
await db.$transaction(async tx => {
await guardedWrite(tx, head.tabId, { op: 'update', kind: 'head', key: 'head', seen: head.version, data: { ...data, invitations: kept },
head: { groupCounter: head.groupCounter, visibilityEpoch: head.visibilityEpoch, sequenceBase: head.sequenceBase } }, clock.next())
- const row = await tx.superTab.findUniqueOrThrow({ where: { id: head.tabId } })
+ const row = await tx.superTab.findUniqueOrThrow({ where: { id: head.tabId }, select: { revision: true } })
const updated = await tx.superTab.updateMany({ where: { id: head.tabId, revision: row.revision },
data: { revision: row.revision + 1, invitedEmails: kept.map(i => i.email) } })
if (!updated.count) throw new PartConflict('head', 'index')
diff --git a/backend/src/superTabs/transaction.test.ts b/backend/src/superTabs/transaction.test.ts
index 97fd1e72a..6082fcaac 100644
--- a/backend/src/superTabs/transaction.test.ts
+++ b/backend/src/superTabs/transaction.test.ts
@@ -42,6 +42,18 @@ describe('Swarm transactions', () => {
expect(Math.max(...waits)).toBeLessThanOrEqual(1_500)
})
+ it('tries an expired or unstartable transaction once more, then says the Swarm is busy', async () => {
+ // 2026-10-28 prod: host changes reads expired after 15.4 s. Running a body that slow eight times would hold a
+ // request for two minutes and add the load that made it slow; one more try, then the client retries later.
+ const expired = () => Object.assign(new Error('Transaction API error: Transaction already closed'), { code: 'P2028' })
+ const once = flaky(expired())
+ expect(await transaction(once as never, async () => 'done', async () => {})).toBe('done')
+ expect(once.$transaction).toHaveBeenCalledTimes(2)
+ const twice = flaky(expired(), expired(), expired())
+ await expect(transaction(twice as never, async () => 1, async () => {})).rejects.toMatchObject({ code: 'SWARM_BUSY', status: 503 })
+ expect(twice.$transaction).toHaveBeenCalledTimes(2)
+ })
+
it('rethrows a unique key still taken after every attempt, and anything else at once', async () => {
const taken = () => Object.assign(new Error('Unique constraint failed'), { code: 'P2002' })
const duplicate = flaky(...Array.from({ length: 8 }, taken))
diff --git a/backend/src/types/productUsage.ts b/backend/src/types/productUsage.ts
index 7f1303c23..766b589f2 100644
--- a/backend/src/types/productUsage.ts
+++ b/backend/src/types/productUsage.ts
@@ -101,6 +101,16 @@ export const PRODUCT_USAGE_FLOW_MEASURES = ['started', 'ok', 'failed', 'cancelle
'under_1s', '1s_to_10s', '10s_to_1m', 'over_1m'] as const
export const PRODUCT_USAGE_UI_METRICS = PRODUCT_USAGE_UI_SURFACES.flatMap(surface =>
PRODUCT_USAGE_FLOWS.flatMap(flow => PRODUCT_USAGE_FLOW_MEASURES.map(measure => `ui_${surface}_${flow}_${measure}` as const)))
+/** Why a Desktop sign-in that did not go through ended, once per sign-in beside its outcome
+ * (desktop/lib/measurement/product_measurement.dart `SignInEndReason`): the CLI's own result code from
+ * `harness login --json`, lower-cased, or what the app saw instead. `cancelled` is the person (Cancel, the other
+ * button, the app closing); `timeout` is a browser page nobody came back from in five minutes, which the person
+ * may have left or finished with a callback that never arrived, so the outcome is `unknown`, not `cancelled`;
+ * `no_result` is a CLI that ended without a result line; `cli_unavailable` one that could not be started.
+ * Until 2026-10-28 Desktop counted every one of these as `failed` (compare releases separately). */
+export const PRODUCT_USAGE_SIGN_IN_END_REASONS = ['cancelled', 'timeout', 'expired', 'denied', 'cli_unavailable',
+ 'cli_too_old', 'no_result', 'callback_error', 'exchange_failed', 'backend_error', 'auth_error', 'daemon_busy',
+ 'daemon_did_not_stop', 'ticket_invalid', 'unavailable', 'other'] as const
export const PRODUCT_USAGE_SETUP_DOWNLOADS = ['opencode', 'codex', 'claude'] as const
export const PRODUCT_USAGE_SETUP_DOWNLOAD_MEASURES = ['started', 'ok', 'failed', 'under_1m', '1m_to_5m', 'over_5m'] as const
// A signed-out report is explicitly enabled on this app. It cannot carry account/work metrics.
@@ -113,6 +123,8 @@ export const PRODUCT_USAGE_SETUP_METRICS = [...PRODUCT_USAGE_SURFACES.flatMap(su
// A step's tool was not installed yet when Desktop checked, so setup installed it: once per step per
// setup, beside the step's own outcome. Signed-out only (a signed-in report passes an older CLI).
...(['setup_harness', 'setup_tmux', 'setup_clipboard'] as const).map(flow => `setup_desktop_${flow}_missing` as const),
+ // Why a Desktop sign-in did not go through. Signed-out only, like `_missing`: a signed-in report passes an older CLI.
+ ...PRODUCT_USAGE_SIGN_IN_END_REASONS.map(reason => `setup_desktop_sign_in_reason_${reason}` as const),
// The agents a new computer downloads beside setup (desktop/lib/bootstrap/agent_prefetch.dart): whether each
// download put its agent in place, and how long it took. Engine names only, never a path or log line.
...PRODUCT_USAGE_SETUP_DOWNLOADS.flatMap(engine => PRODUCT_USAGE_SETUP_DOWNLOAD_MEASURES
diff --git a/backend/vitest.super-tabs.config.ts b/backend/vitest.super-tabs.config.ts
index af549c240..3265fcaeb 100644
--- a/backend/vitest.super-tabs.config.ts
+++ b/backend/vitest.super-tabs.config.ts
@@ -2,5 +2,5 @@ import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { include: ['integration/superTabs.test.ts', 'integration/superTabSharing.test.ts', 'integration/superTabGithub.test.ts', 'integration/superTabTeam.test.ts', 'integration/superTabWorkspaces.test.ts',
'integration/superTabRead.test.ts', 'integration/superTabLeaderboard.test.ts', 'integration/superTabMigration.test.ts', 'integration/superTabLiveness.test.ts', 'integration/superTabTidy.test.ts',
- 'integration/superTabProfile.test.ts'], hookTimeout: 120000, testTimeout: 30000,
+ 'integration/superTabProfile.test.ts', 'integration/superTabLegacyDrop.test.ts', 'integration/shareRaces.test.ts'], hookTimeout: 120000, testTimeout: 30000,
fileParallelism: false, env: { NODE_ENV: 'test', HARNESS_CREDENTIAL_ENCRYPTION_KEY: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' } } })
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index 60452563a..033a833b0 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -827,7 +827,8 @@ describe('BackendSocket outbound queue', () => {
// … but once the handshake is abandoned, the ordinary backoff schedules a fresh attempt.
ws1.handshakeTimeout()
expect(socket.isConnected()).toBe(false)
- await vi.advanceTimersByTimeAsync(1_000)
+ // The first redial lands at random between 1 and 2 s.
+ await vi.advanceTimersByTimeAsync(2_000)
expect(wsMock.instances).toHaveLength(2)
const ws2 = wsMock.instances[1]
expect(ws2.options?.handshakeTimeout).toBe(15_000)
@@ -918,7 +919,10 @@ describe('BackendSocket outbound queue', () => {
expect(statuses).toEqual([true, false])
expect(calls).toEqual([{ force: true, failedToken: 'stale-token' }])
expect(revoked).not.toHaveBeenCalled()
- // And the refresh, not a backoff timer, opened the next socket — with the new token.
+ // The next socket waits out the backoff like any other drop (1–2 s for the first), then dials
+ // once, with the new token.
+ expect(wsMock.instances).toHaveLength(1)
+ await vi.advanceTimersByTimeAsync(2_000)
expect(wsMock.instances).toHaveLength(2)
expect(wsMock.instances[1].protocols).toEqual(['fresh-token'])
await vi.advanceTimersByTimeAsync(60_000)
@@ -939,8 +943,8 @@ describe('BackendSocket outbound queue', () => {
await vi.advanceTimersByTimeAsync(0)
expect(revoked).not.toHaveBeenCalled()
expect(wsMock.instances).toHaveLength(1)
- await vi.advanceTimersByTimeAsync(1_000)
- expect(wsMock.instances).toHaveLength(2) // the ordinary backoff, session intact
+ await vi.advanceTimersByTimeAsync(2_000)
+ expect(wsMock.instances).toHaveLength(2) // the ordinary backoff (1–2 s for the first), session intact
await socket.stop()
})
@@ -974,7 +978,7 @@ describe('BackendSocket outbound queue', () => {
;(gatewayOf(socket) as any).sendTo('conn-1', { type: 'e2e_rekey', payload: { n: 1 } })
expect(ws1.sent).toHaveLength(0)
- await vi.advanceTimersByTimeAsync(1_000)
+ await vi.advanceTimersByTimeAsync(2_000)
const ws2 = wsMock.instances[1]
ws2.open()
const sent = parseSent(ws2)
@@ -3425,7 +3429,7 @@ describe('agent_create with a prompt, a name and a named agent', () => {
it('refuses a prompt for an engine with no documented mechanism, naming the engine', async () => {
const { seen, reply } = await create({ engine: 'cursor', prompt: 'Start a local model on this machine' })
- expect(reply).toMatchObject({ error: 'PROMPT_UNSUPPORTED', detail: expect.stringContaining('cursor') })
+ expect(reply).toMatchObject({ error: 'PROMPT_UNSUPPORTED', detail: expect.stringContaining('Cursor cannot start with a first message') })
expect(seen).toHaveLength(0)
})
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 1aa5254f5..277d588f0 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -49,7 +49,7 @@ import { infoBlockFooter } from './lib/infoBlockFooter.js'
import { flashCommand } from './lib/flash.js'
import { awaitLoginCallback, extractCallbackParams, LOGIN_TIMEOUT_MESSAGE, type LoginCallbackParams } from './lib/loginCallback.js'
import { ancestorsOnce, removeSignIn, SIGN_OUT_BUTTON_FLAG, signOutAsked, type Asker, type SignOutAsked } from './lib/signOut.js'
-import { AUTH_DIR, AuthSessionError, AuthSessionManager, knownSsoClientId, newSignInEpoch, readAuthSession, readSignedOut, ssoClientIdFor, writeAuthSession, type AuthSession } from './lib/authSession.js'
+import { AUTH_DIR, AuthSessionError, AuthSessionManager, knownSsoClientId, newSignInEpoch, readAuthSession, readSignedOut, ssoClientIdFor, updateAuthSession, writeAuthSession, type AuthSession } from './lib/authSession.js'
import { handOffToGrid } from './lib/gridHandoff.js'
import { claimTicket, qrSignIn, type QrSignInTokens } from './lib/qrSignIn.js'
import { pickSignInMethod, signInMethodFlag, signInProviderName, withSignInProvider, type SignInMethod, type SignInProvider } from './lib/signInMethodPicker.js'
@@ -290,13 +290,10 @@ async function resolveComputerMachine(signal?: AbortSignal): Promise<AuthSession
const machineId = result.machine?.machineId
if (!machineId) throw new Error('Backend did not return a machine id for this computer')
// Refresh can atomically replace the session while this request is in flight. Always merge the
- // machine id into the newest file so a stale caller never rolls its rotated refresh token back.
- const latest = readAuthSession()
- if (!latest) throw new Error('SSO session disappeared while resolving this computer')
- const next = latest.machineId === machineId
- ? latest
- : { ...latest, machineId, updatedAt: Date.now() }
- if (next !== latest) writeAuthSession(next)
+ // machine id into the newest file, under the lock, so a stale caller never rolls its rotated refresh
+ // token back nor writes over a signed-out mark.
+ const next = await updateAuthSession((latest) => latest.machineId === machineId ? null : { ...latest, machineId, updatedAt: Date.now() })
+ if (!next) throw new Error('SSO session disappeared while resolving this computer')
return next
}
@@ -315,9 +312,8 @@ async function recordSignInAccount(accessToken: string, signInEpoch: string, aut
authorization: `Bearer ${accessToken}`, 'x-autonomous-env': autonomousEnv,
})
const acct = me?.user?.id
- const latest = readAuthSession()
- if (typeof acct !== 'string' || !acct || latest?.signInEpoch !== signInEpoch) return
- writeAuthSession({ ...latest, signInAcct: acct })
+ if (typeof acct !== 'string' || !acct) return
+ await updateAuthSession((latest) => latest.signInEpoch === signInEpoch ? { ...latest, signInAcct: acct } : null)
} catch { /* no account recorded */ }
}
diff --git a/cli/src/core/agents/adopt.spec.ts b/cli/src/core/agents/adopt.spec.ts
index 4a1a63a52..2936c8f31 100644
--- a/cli/src/core/agents/adopt.spec.ts
+++ b/cli/src/core/agents/adopt.spec.ts
@@ -25,6 +25,13 @@ describe('core admission from search observations', () => {
expect(choose(answer({ session: { ...fact, cwd: join(cwd, 'gone') } }))).toMatchObject({ error: 'SESSION_FOLDER_GONE' })
expect(adoptionDecision('conversation', 'claude', null, externalUnavailable(), () => false)).toMatchObject({ error: 'SEARCH_UNAVAILABLE' })
})
+ // 15 refusals on Oct 22 and 26: the old text only said what was wrong, not what to do.
+ it('says to open the harness that already has the conversation', () => {
+ const detail = 'This conversation is already open in a harness on this machine. Open that harness instead.'
+ expect(choose(answer(), null, () => true)).toMatchObject({ error: 'SESSION_IN_HARNESS', detail })
+ expect(choose(answer({ session: { ...fact, aliases: ['reserved'] } }), null, id => id === 'reserved')).toMatchObject({ detail })
+ expect(choose(answer({ owner: { ...owner, harness: true } }), 'now')).toMatchObject({ detail })
+ })
it('preserves metadata and profile arguments when no other process holds it', () => {
expect(choose()).toEqual({ ok: true, cwd, title: '', owner: null, busy: false, launchArgs: [] })
expect(choose(answer({ session: { ...fact, title: 'Named', launchArgs: [] } }))).toMatchObject({ title: 'Named', launchArgs: [] })
diff --git a/cli/src/core/agents/adopt.ts b/cli/src/core/agents/adopt.ts
index cdd83304e..ff925675b 100644
--- a/cli/src/core/agents/adopt.ts
+++ b/cli/src/core/agents/adopt.ts
@@ -5,6 +5,9 @@ import { engineLabel } from '../../lib/agentNames.js'
import { externalSessionRequest, externalUnavailable, type ExternalSessionAnswer, type ExternalSessionRequest } from '../../lib/externalSessionWire.js'
import type { SessionOwner } from '../../lib/sessionSearch/external.js'
+/** Said for every SESSION_IN_HARNESS, with what to do: 15 refusals on Oct 22 and 26 only said what was wrong. */
+const IN_HARNESS = 'This conversation is already open in a harness on this machine. Open that harness instead.'
+
export interface AdoptDeps {
inspect(request: ExternalSessionRequest): Promise<ExternalSessionAnswer>
held(id: string): boolean
@@ -12,12 +15,12 @@ export interface AdoptDeps {
export function adoptionDecision(sessionId: string, engine: AgentEngine, takeOver: 'idle' | 'now' | 'wait' | null, answer: ExternalSessionAnswer, held: (id: string) => boolean): { ok: true; cwd: string; title: string; owner: SessionOwner | null; busy: boolean; launchArgs: readonly string[] } | { ok: false; error: string; detail: string } {
if (held(sessionId)) {
- return { ok: false, error: 'SESSION_IN_HARNESS', detail: 'This conversation is already a harness here.' }
+ return { ok: false, error: 'SESSION_IN_HARNESS', detail: IN_HARNESS }
}
if (!answer.ok) return answer
const found = answer.session
if (found && [found.sessionId, ...found.aliases ?? []].some(held)) {
- return { ok: false, error: 'SESSION_IN_HARNESS', detail: 'This conversation is already a harness here.' }
+ return { ok: false, error: 'SESSION_IN_HARNESS', detail: IN_HARNESS }
}
if (!found) return { ok: false, error: 'SESSION_NOT_FOUND', detail: 'This conversation is no longer on this machine.' }
if (found.engine !== engine) return { ok: false, error: 'INVALID_ENGINE', detail: `This is a ${found.engine} conversation.` }
@@ -38,7 +41,7 @@ export function adoptionDecision(sessionId: string, engine: AgentEngine, takeOve
if (!owner) return { ok: true, cwd: found.cwd, title, owner: null, busy: false, launchArgs }
const engineName = engineLabel(engine)
// A process in one of Harness's own panes is an agent the daemon is still binding: never stopped.
- if (owner.harness) return { ok: false, error: 'SESSION_IN_HARNESS', detail: 'This conversation is already a harness here.' }
+ if (owner.harness) return { ok: false, error: 'SESSION_IN_HARNESS', detail: IN_HARNESS }
// Started on it, as its arguments say, and perhaps moved on since — or in a pane nobody could check
// was not Harness's own: not opened twice, never stopped.
if (owner.fromArgs || owner.unverified) {
diff --git a/cli/src/dsh/runtime.spec.ts b/cli/src/dsh/runtime.spec.ts
index fe5b30d4a..9a3e23e11 100644
--- a/cli/src/dsh/runtime.spec.ts
+++ b/cli/src/dsh/runtime.spec.ts
@@ -299,6 +299,16 @@ describe('runtime validation and file ownership', () => {
rmSync(join(pkg.realDir, 'skills/draw/SKILL.md'))
expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('Harness skill is missing')
})
+
+ // An exact string compare refused a link to the same folder written another way as "already occupied".
+ it('relaunches over its own skill link however the link writes the same folder', () => {
+ const launch = prepareHarnessLaunch(pkg, ws, 'codex', 'key')
+ const skill = join(launch.env.HARNESS_SKILLS_DIR!, 'draw')
+ unlinkSync(skill)
+ symlinkSync(`${join(pkg.realDir, 'skills/draw')}/`, skill)
+ expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).not.toThrow()
+ expect(readFileSync(join(skill, 'SKILL.md'), 'utf8')).toContain('# Draw')
+ })
})
describe('non-destructive legacy migration', () => {
diff --git a/cli/src/dsh/runtime.ts b/cli/src/dsh/runtime.ts
index 81f237d25..50adf9b48 100644
--- a/cli/src/dsh/runtime.ts
+++ b/cli/src/dsh/runtime.ts
@@ -5,7 +5,7 @@
import { ignoreHarnessRuntime } from '../lib/harnessRuntimeIgnore.js'
import { createHash, randomUUID } from 'node:crypto'
import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
-import { basename, join, resolve } from 'node:path'
+import { basename, join, relative, resolve, sep } from 'node:path'
import { z } from 'zod'
import { PROCESS_ENGINES, type AgentEngine } from '../engines/types.js'
import { instructionFileOf, launchContract } from '../engines/launches.js'
@@ -34,7 +34,9 @@ export function harnessRuntimeDir(workspace: string, key: string): string {
function ensureRuntimeDir(workspace: string, dir: string): void {
const root = resolve(workspace)
let path = root
- for (const part of dir.slice(root.length + 1).split('/')) {
+ // By the platform's separator: split on '/', a Windows path was one part, and its non-recursive mkdir failed with
+ // ENOENT on every first launch in a workspace (dsh_runtime_failed from Oct 22, the day after Windows shipped).
+ for (const part of relative(root, dir).split(sep)) {
path = join(path, part)
if (existsSync(path) || isLink(path)) {
const stat = lstatSync(path)
@@ -185,8 +187,11 @@ export function prepareHarnessLaunch(dsh: InstalledDsh, workspace: string, engin
if (!existsSync(join(skill.dir, 'SKILL.md'))) throw new Error(`Harness skill is missing: ${skill.dir}; repair the harness installation.`)
const link = join(skillsDir, skill.name)
if (existsSync(link) || isLink(link)) {
- if (!isLink(link) || readlinkSync(link) !== skill.dir) throw new Error(`Harness skill path is already occupied: ${link}`)
- } else symlinkSync(skill.dir, link)
+ // Compared resolved, so a link that writes the same folder another way (a trailing separator) is still its own.
+ if (!isLink(link) || resolve(readlinkSync(link)) !== resolve(skill.dir)) throw new Error(`Harness skill path is already occupied: ${link}`)
+ // A junction on Windows: a directory symlink needs Developer Mode or an administrator (EPERM), a junction
+ // neither. Other platforms ignore the type.
+ } else symlinkSync(skill.dir, link, 'junction')
}
migrateHarnessInstructions(ws, dsh)
installBootstrap(ws, engine)
diff --git a/cli/src/dsh/runtime.windows.spec.ts b/cli/src/dsh/runtime.windows.spec.ts
new file mode 100644
index 000000000..518829ce9
--- /dev/null
+++ b/cli/src/dsh/runtime.windows.spec.ts
@@ -0,0 +1,38 @@
+// A harness launch on real Windows (the Windows workflow runs it). From Oct 22, the day after Harness on Windows
+// shipped, launches failed with dsh_runtime_failed: the runtime folder was split on '/', so a fresh workspace's
+// first launch failed in mkdir, and skill links were directory symlinks, which need Developer Mode or an
+// administrator. The runner is an administrator, so this proves the junction works, not that a symlink would not.
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { InstalledDsh } from './installed.js'
+import { forkRuntimeKey, prepareHarnessLaunch } from './runtime.js'
+
+let root: string
+let ws: string
+let pkg: InstalledDsh
+beforeEach(() => {
+ root = realpathSync(mkdtempSync(join(tmpdir(), 'windows harness-')))
+ ws = join(root, 'project with spaces')
+ mkdirSync(ws)
+ const dir = join(root, 'package')
+ mkdirSync(join(dir, 'skills', 'draw'), { recursive: true })
+ writeFileSync(join(dir, 'AGENTS.md'), '# Make a drawing\n')
+ writeFileSync(join(dir, 'skills', 'draw', 'SKILL.md'), '# Draw\n')
+ pkg = { id: 'acme/draw', dir, realDir: dir, source: dir, ref: null, commit: null, linked: true, installedAt: 1,
+ manifest: { spec: 1, id: 'acme/draw', name: 'Drawing', engine: 'claude', agent: { instructions: 'AGENTS.md', skills: ['skills'] } } }
+})
+afterEach(() => { rmSync(root, { recursive: true, force: true }) })
+
+describe.runIf(process.platform === 'win32')('a harness launch on Windows', () => {
+ it('launches in a fresh workspace, relaunches over its own skill link, and forks', () => {
+ const first = prepareHarnessLaunch(pkg, ws, 'claude', 'session')
+ expect(readFileSync(first.env.HARNESS_CONTEXT_FILE!, 'utf8')).toContain('# Make a drawing')
+ expect(readFileSync(join(first.env.HARNESS_SKILLS_DIR!, 'draw', 'SKILL.md'), 'utf8')).toBe('# Draw\n')
+ const again = prepareHarnessLaunch(pkg, ws, 'claude', 'session')
+ expect(again.env.HARNESS_SKILLS_DIR).toBe(first.env.HARNESS_SKILLS_DIR)
+ const fork = prepareHarnessLaunch(pkg, ws, 'claude', 'fork', {}, forkRuntimeKey({ cwd: ws, agentId: 'session', dshRuntime: 'session' }))
+ expect(readFileSync(join(fork.env.HARNESS_SKILLS_DIR!, 'draw', 'SKILL.md'), 'utf8')).toBe('# Draw\n')
+ })
+})
diff --git a/cli/src/engines/__fixtures__/native-launch-compatibility.golden.json b/cli/src/engines/__fixtures__/native-launch-compatibility.golden.json
index e261b1f4a..acd92d046 100644
--- a/cli/src/engines/__fixtures__/native-launch-compatibility.golden.json
+++ b/cli/src/engines/__fixtures__/native-launch-compatibility.golden.json
@@ -76,7 +76,7 @@
],
"cursor first": {
"refused": "FirstPromptUnsupportedError",
- "detail": "cursor has no documented way to start with a first prompt, so the agent was not created."
+ "detail": "Cursor cannot start with a first message. Start it without one and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one."
},
"opencode fresh": [
"opencode"
@@ -118,7 +118,7 @@
],
"pi first": {
"refused": "FirstPromptUnsupportedError",
- "detail": "pi has no documented way to start with a first prompt, so the agent was not created."
+ "detail": "Pi cannot start with a first message. Start it without one and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one."
},
"omp fresh": [
"omp"
@@ -178,7 +178,7 @@
],
"commandcode first": {
"refused": "FirstPromptUnsupportedError",
- "detail": "commandcode has no documented way to start with a first prompt, so the agent was not created."
+ "detail": "Command Code cannot start with a first message. Start it without one and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one."
},
"devin fresh": [
"devin"
@@ -198,7 +198,7 @@
],
"devin first": {
"refused": "FirstPromptUnsupportedError",
- "detail": "devin has no documented way to start with a first prompt, so the agent was not created."
+ "detail": "Devin cannot start with a first message. Start it without one and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one."
},
"muse fresh": [
"muse"
@@ -218,7 +218,7 @@
],
"muse first": {
"refused": "FirstPromptUnsupportedError",
- "detail": "muse has no documented way to start with a first prompt, so the agent was not created."
+ "detail": "Muse cannot start with a first message. Start it without one and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one."
},
"amp fresh": [
"amp"
@@ -239,7 +239,7 @@
],
"amp first": {
"refused": "FirstPromptUnsupportedError",
- "detail": "amp has no documented way to start with a first prompt, so the agent was not created."
+ "detail": "Amp cannot start with a first message. Start it without one and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one."
},
"kilo fresh": [
"kilo"
@@ -259,7 +259,7 @@
],
"kilo first": {
"refused": "FirstPromptUnsupportedError",
- "detail": "kilo has no documented way to start with a first prompt, so the agent was not created."
+ "detail": "Kilo cannot start with a first message. Start it without one and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one."
},
"grok fresh": [
"grok"
@@ -279,7 +279,7 @@
],
"grok first": {
"refused": "FirstPromptUnsupportedError",
- "detail": "grok has no documented way to start with a first prompt, so the agent was not created."
+ "detail": "Grok cannot start with a first message. Start it without one and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one."
},
"agy fresh": [
"agy"
@@ -299,7 +299,7 @@
],
"agy first": {
"refused": "FirstPromptUnsupportedError",
- "detail": "agy has no documented way to start with a first prompt, so the agent was not created."
+ "detail": "Antigravity cannot start with a first message. Start it without one and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one."
},
"copilot fresh": [
"copilot"
@@ -319,7 +319,7 @@
],
"copilot first": {
"refused": "FirstPromptUnsupportedError",
- "detail": "copilot has no documented way to start with a first prompt, so the agent was not created."
+ "detail": "Copilot cannot start with a first message. Start it without one and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one."
},
"installation installed": {
"code": 0,
diff --git a/cli/src/gateway/productUsage.spec.ts b/cli/src/gateway/productUsage.spec.ts
index 75a931f75..f40510620 100644
--- a/cli/src/gateway/productUsage.spec.ts
+++ b/cli/src/gateway/productUsage.spec.ts
@@ -746,6 +746,27 @@ describe('when reports go', () => {
expect(posts).toEqual([at(10_000), at(640_000), at(2_440_000)])
})
+ it('holds a report the busy backend refused with Retry-After, then sends that same report, counting the cause', async () => {
+ start(() => 0)
+ await usage.sync(false); usage.counter('search_requests')
+ answers = [{ status: 429, body: { success: false, error: { code: 'USAGE_WRITE_CONFLICT' } }, retryAfterMs: 90_000 }]
+ await vi.advanceTimersByTimeAsync(10_000)
+ expect(posts).toEqual([at(10_000)])
+ // Ticks every 45 s here; the one at 55 s is inside the 90 s asked, the one at 100 s is not.
+ await vi.advanceTimersByTimeAsync(90_000 - 1)
+ expect(posts).toHaveLength(1)
+ await vi.advanceTimersByTimeAsync(1)
+ expect(posts).toEqual([at(10_000), at(100_000)])
+ // Not lost: the same receipt and counts again, which the backend's receipt makes count once.
+ expect(sent[1]).toEqual(sent[0])
+ expect(JSON.parse(readFileSync(file, 'utf8')).pending).toBeNull()
+ // The refusal's own counts go in the next report.
+ await vi.advanceTimersByTimeAsync(45_000)
+ expect(posts).toHaveLength(3)
+ expect(totals().health_cli_report_failure_write_conflict).toBe(1)
+ expect(totals().health_cli_report_failure_rate_limited).toBeUndefined()
+ })
+
it('stops ticking once stopped', async () => {
start(() => 0)
await usage.sync(false); usage.counter('search_requests')
diff --git a/cli/src/gateway/reportFailure.spec.ts b/cli/src/gateway/reportFailure.spec.ts
index 951840099..6a92ed6c8 100644
--- a/cli/src/gateway/reportFailure.spec.ts
+++ b/cli/src/gateway/reportFailure.spec.ts
@@ -8,6 +8,9 @@ it.each([
[409, 'ACCOUNT_CHANGED', 'auth'], [429, 'PRIVATE_CANARY', 'rate_limited'],
[504, 'BACKEND_TIMEOUT', 'timeout'], [502, 'BACKEND_UNREACHABLE', 'unreachable'],
[503, 'USAGE_WRITE_CONFLICT', 'write_conflict'], [503, 'USAGE_TRANSACTION_FAILED', 'transaction'],
+ // A busy backend answers 429 and keeps the cause; its auth service down is auth, not storage.
+ [429, 'USAGE_WRITE_CONFLICT', 'write_conflict'], [429, 'USAGE_TRANSACTION_FAILED', 'transaction'],
+ [429, 'USAGE_BUSY', 'rate_limited'], [503, 'AUTH_SERVICE_UNAVAILABLE', 'auth'],
[503, 'USAGE_UNAVAILABLE', 'server'], [504, 'PRIVATE_CANARY', 'server'],
[200, 'PRIVATE_CANARY', 'other'], [409, 'PRIVATE_CANARY', 'other'], [404, 'PRIVATE_CANARY', 'other'],
])('reduces status %i and known code %s to %s', (status, code, expected) => {
@@ -16,8 +19,10 @@ it.each([
expect(CLI_REPORT_FAILURES).toContain(result)
})
-it('tolerates missing or malformed error bodies without exporting them', () => {
- for (const body of [{}, { error: null }, { error: 'PRIVATE_CANARY' }, { error: ['PRIVATE_CANARY'] }]) {
- expect(reportFailure({ status: 502, body })).toBe('server')
+// A 5xx without the backend's own answer came from the proxy or Cloudflare in front of it: the backend was not
+// reached. `server` stays the backend's own failure, so it still shows when storage is down.
+it('tolerates missing or malformed error bodies without exporting them, as a backend not reached', () => {
+ for (const status of [502, 503, 520]) for (const body of [{}, { error: null }, { error: 'PRIVATE_CANARY' }, { error: ['PRIVATE_CANARY'] }]) {
+ expect(reportFailure({ status, body })).toBe('unreachable')
}
})
diff --git a/cli/src/gateway/reportFailure.ts b/cli/src/gateway/reportFailure.ts
index 298a57e53..f1c706201 100644
--- a/cli/src/gateway/reportFailure.ts
+++ b/cli/src/gateway/reportFailure.ts
@@ -5,12 +5,15 @@ export function reportFailure(answer: { status: number; body: Record<string, unk
const code = (answer.body?.error as { code?: unknown } | null)?.code
if (answer.status === 504 && code === 'BACKEND_TIMEOUT') return 'timeout'
if (answer.status === 502 && code === 'BACKEND_UNREACHABLE') return 'unreachable'
- if (answer.status === 401 || answer.status === 403 || code === 'AUTH_UNAVAILABLE' || code === 'ACCOUNT_CHANGED') return 'auth'
+ if (answer.status === 401 || answer.status === 403 || code === 'AUTH_UNAVAILABLE' || code === 'AUTH_SERVICE_UNAVAILABLE'
+ || code === 'ACCOUNT_CHANGED') return 'auth'
if (answer.status === 400) return 'invalid'
if (answer.status === 413) return 'too_large'
+ // A busy backend answers these 429 since 2026-10-28 (503 before): the cause is kept either way.
+ if ((answer.status === 429 || answer.status === 503) && code === 'USAGE_WRITE_CONFLICT') return 'write_conflict'
+ if ((answer.status === 429 || answer.status === 503) && code === 'USAGE_TRANSACTION_FAILED') return 'transaction'
if (answer.status === 429) return 'rate_limited'
- if (answer.status === 503 && code === 'USAGE_WRITE_CONFLICT') return 'write_conflict'
- if (answer.status === 503 && code === 'USAGE_TRANSACTION_FAILED') return 'transaction'
- if (answer.status >= 500 && answer.status < 600) return 'server'
+ // Without the backend's own answer, a 5xx came from the proxy or Cloudflare in front of it.
+ if (answer.status >= 500 && answer.status < 600) return typeof code === 'string' ? 'server' : 'unreachable'
return 'other'
}
diff --git a/cli/src/gateway/upstream.spec.ts b/cli/src/gateway/upstream.spec.ts
new file mode 100644
index 000000000..bb501200f
--- /dev/null
+++ b/cli/src/gateway/upstream.spec.ts
@@ -0,0 +1,212 @@
+import { EventEmitter, once } from 'node:events'
+import type { AddressInfo } from 'node:net'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { WebSocketServer, type WebSocket } from 'ws'
+import { env } from '../config/env.js'
+import { AuthSessionError } from '../lib/authSession.js'
+import { UpstreamLink } from './upstream.js'
+
+// A stand-in backend on loopback. `onConnection` decides what each accepted link gets; `refuse` answers
+// every upgrade with that HTTP status instead.
+async function backend(opts: { onConnection?: (ws: WebSocket) => void; refuse?: number } = {}) {
+ const wss = new WebSocketServer({
+ port: 0,
+ host: '127.0.0.1',
+ ...(opts.refuse ? { verifyClient: (_info: unknown, done: (ok: boolean, code?: number) => void) => done(false, opts.refuse) } : {}),
+ })
+ await once(wss, 'listening')
+ const links: WebSocket[] = []
+ wss.on('connection', (ws) => { links.push(ws); opts.onConnection?.(ws) })
+ return { wss, links, url: `ws://127.0.0.1:${(wss.address() as AddressInfo).port}` }
+}
+
+type Auth = { accessToken(opts?: { force?: boolean }): Promise<string> }
+
+function upstream(auth: Auth) {
+ const signals = new EventEmitter()
+ const link = new UpstreamLink({
+ machineId: 'upstream-spec',
+ auth,
+ events: {
+ down: () => {},
+ binary: () => {},
+ up: () => {},
+ gone: () => {},
+ status: (connected) => { signals.emit(connected ? 'up' : 'down') },
+ revoked: () => { signals.emit('revoked') },
+ busy: () => {},
+ localClients: () => ({ desktop: 0, tui: 0 }),
+ },
+ })
+ return { link, signals }
+}
+
+const token: Auth = { accessToken: async () => 'token' }
+
+// How long the link waits before it dials again: the one timer it left pending, read off the fake clock.
+function nextRedialMs(): number {
+ expect(vi.getTimerCount()).toBe(1)
+ const before = Date.now()
+ vi.advanceTimersToNextTimer()
+ return Date.now() - before
+}
+
+async function untilATimerIsPending(): Promise<void> {
+ for (let turn = 0; turn < 1_000 && vi.getTimerCount() === 0; turn++) await new Promise((resolve) => setImmediate(resolve))
+}
+
+describe('UpstreamLink reconnect backoff', () => {
+ const originalUrl = env.BACKEND_WS_URL
+ let servers: WebSocketServer[] = []
+ let links: UpstreamLink[] = []
+
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date'] })
+ vi.spyOn(console, 'log').mockImplementation(() => {})
+ vi.spyOn(console, 'error').mockImplementation(() => {})
+ // Halfway through each wait's window, so every wait is one exact number.
+ vi.spyOn(Math, 'random').mockReturnValue(0.5)
+ })
+
+ afterEach(async () => {
+ for (const link of links) link.stop()
+ links = []
+ vi.useRealTimers()
+ env.BACKEND_WS_URL = originalUrl
+ await Promise.all(servers.map((wss) => {
+ for (const client of wss.clients) client.terminate()
+ return new Promise((resolve) => wss.close(resolve))
+ }))
+ servers = []
+ // A dial the stop cut short reports its error a turn later; keep it out of the test output.
+ await new Promise((resolve) => setImmediate(resolve))
+ vi.restoreAllMocks()
+ })
+
+ async function serve(opts: Parameters<typeof backend>[0] = {}) {
+ const server = await backend(opts)
+ servers.push(server.wss)
+ env.BACKEND_WS_URL = server.url
+ return server
+ }
+
+ function open(auth: Auth = token) {
+ const made = upstream(auth)
+ links.push(made.link)
+ return made
+ }
+
+ it('spreads each redial at random between one second and its step, and keeps the 30 s cap, while a link drops as soon as it opens', async () => {
+ // A draining pod: the upgrade is answered, then the socket is cut at once.
+ await serve({ onConnection: (ws) => ws.terminate() })
+ const { link, signals } = open()
+
+ const waits: number[] = []
+ let dropped = once(signals, 'down')
+ link.connect()
+ for (let i = 0; i < 6; i++) {
+ await dropped
+ dropped = once(signals, 'down')
+ waits.push(nextRedialMs())
+ }
+
+ // Steps 2, 4, 8, 16, 30, 30 s, each waited halfway between 1 s and the step.
+ expect(waits).toEqual([1_500, 2_500, 4_500, 8_500, 15_500, 15_500])
+ })
+
+ it('starts the backoff over only once a link has stayed up for 30 s', async () => {
+ const server = await serve()
+ const { link, signals } = open()
+
+ let up = once(signals, 'up')
+ link.connect()
+ await up
+ vi.advanceTimersByTime(29_000)
+ let dropped = once(signals, 'down')
+ server.links.at(-1)!.terminate()
+ await dropped
+ up = once(signals, 'up')
+ // 29 s up was not stable: the first wait stays in place and the next one grows.
+ expect(nextRedialMs()).toBe(1_500)
+ await up
+ dropped = once(signals, 'down')
+ server.links.at(-1)!.terminate()
+ await dropped
+ up = once(signals, 'up')
+ expect(nextRedialMs()).toBe(2_500)
+ await up
+
+ vi.advanceTimersByTime(30_000)
+ dropped = once(signals, 'down')
+ server.links.at(-1)!.terminate()
+ await dropped
+ expect(nextRedialMs()).toBe(1_500)
+ })
+
+ it('backs off a token refresh the backend cannot answer instead of asking again every second', async () => {
+ await serve()
+ const unavailable: Auth = { accessToken: async () => { throw new AuthSessionError('refresh unavailable', 'UNAVAILABLE') } }
+ const { link, signals } = open(unavailable)
+
+ const waits: number[] = []
+ let failed = once(signals, 'down')
+ link.connect()
+ for (let i = 0; i < 3; i++) {
+ await failed
+ failed = once(signals, 'down')
+ waits.push(nextRedialMs())
+ }
+
+ expect(waits).toEqual([1_500, 2_500, 4_500])
+ })
+
+ it('backs off a redial after a refused token whose refresh failed', async () => {
+ await serve({ refuse: 401 })
+ const forced: boolean[] = []
+ const auth: Auth = {
+ accessToken: async (opts) => {
+ forced.push(Boolean(opts?.force))
+ if (opts?.force) throw new AuthSessionError('refresh unavailable', 'UNAVAILABLE')
+ return 'token'
+ },
+ }
+ const { link } = open(auth)
+
+ link.connect()
+ await untilATimerIsPending()
+
+ expect(forced).toEqual([false, true])
+ expect(nextRedialMs()).toBe(1_500)
+ })
+
+ it('backs off redials while the backend refuses every token, even though each refresh succeeds', async () => {
+ await serve({ refuse: 401 })
+ let refreshes = 0
+ const auth: Auth = { accessToken: async (opts) => { if (opts?.force) refreshes++; return 'token' } }
+ const { link } = open(auth)
+
+ const waits: number[] = []
+ link.connect()
+ for (let i = 0; i < 3; i++) {
+ await untilATimerIsPending()
+ waits.push(nextRedialMs())
+ }
+
+ expect(waits).toEqual([1_500, 2_500, 4_500])
+ expect(refreshes).toBe(3)
+ })
+
+ it.each(['stop', 'close'] as const)('cancels a pending redial on %s', async (end) => {
+ await serve({ onConnection: (ws) => ws.terminate() })
+ const { link, signals } = open()
+
+ const dropped = once(signals, 'down')
+ link.connect()
+ await dropped
+ expect(vi.getTimerCount()).toBe(1)
+
+ link[end]()
+
+ expect(vi.getTimerCount()).toBe(0)
+ })
+})
diff --git a/cli/src/gateway/upstream.ts b/cli/src/gateway/upstream.ts
index 0a6b4daf6..0da120df6 100644
--- a/cli/src/gateway/upstream.ts
+++ b/cli/src/gateway/upstream.ts
@@ -8,7 +8,7 @@
* - `up` { t:'up', frame } → normalized claude events + `<x>_result` RPC replies
* - `down` { t:'down', connId, frame } → web chat/control + data-plane RPC requests
*
- * Mirrors the hosted runtime’s managerSocket: idempotent connect, exponential backoff (1s→30s),
+ * Mirrors the hosted runtime’s managerSocket: idempotent connect, jittered exponential backoff (1s→30s),
* WS liveness (`lib/wsLiveness.ts`: ping every 20s, 60s deadline on silence) + a 15s app-level
* `{t:'ping'}` that refreshes the backend presence key, and a bounded FIFO queue for client-facing
* outbound frames.
@@ -38,10 +38,25 @@ const APP_PRESENCE_UP_MS = 60_000
const HANDSHAKE_TIMEOUT_MS = 15_000
const BASE_DELAY_MS = 1_000
const MAX_DELAY_MS = 30_000
+// How long a link must stay up before its backoff starts over. Resetting on 'open' alone let a pod that
+// answers the upgrade and then drains cut every machine back to a 1 s redial, again and again; production
+// showed 76% of relay sockets living under a second (#1795). A link that outlived the longest wait was
+// a real connection.
+const STABLE_MS = MAX_DELAY_MS
const QUEUE_MAX = 2_000
export type OutboundEnvelope = Record<string, unknown>
+/**
+ * The wait before redial `attempt` (0 for the first): at random between the 1 s floor and that attempt's
+ * step (2, 4, 8, 16, then 30 s). Without the spread, every machine a draining pod dropped redialed at the
+ * same moment and the next pod took them all at once. The floor keeps a redial no sooner than before.
+ */
+function reconnectDelay(attempt: number): number {
+ const step = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** Math.min(attempt + 1, 5))
+ return Math.round(BASE_DELAY_MS + Math.random() * (step - BASE_DELAY_MS))
+}
+
interface QueueItem {
id: number
data: string
@@ -96,6 +111,10 @@ export class UpstreamLink {
private readonly testToken?: string
private readonly url: string
private attempts = 0
+ /** When the current socket opened (0 while none is open): how the backoff knows the link was stable. */
+ private openedAt = 0
+ /** The pending redial, kept so a stop cancels it rather than leaving the process waiting up to 30 s. */
+ private redialTimer: NodeJS.Timeout | null = null
private closed = false
private queue: QueueItem[] = []
private draining = false
@@ -154,8 +173,11 @@ export class UpstreamLink {
} catch (err) {
this.connecting = false
this.events.status(false)
- const delay = err instanceof AuthSessionError && err.code === 'INVALID_REFRESH' ? MAX_DELAY_MS : BASE_DELAY_MS
- if (!this.closed) setTimeout(() => this.connect(), delay)
+ // Anything but a rejected refresh token (the backend down, another process refreshing) re-enters
+ // the backoff: a flat second had every signed-in machine asking /api/auth/refresh once a second
+ // for as long as the backend was away.
+ const delay = err instanceof AuthSessionError && err.code === 'INVALID_REFRESH' ? MAX_DELAY_MS : reconnectDelay(this.attempts++)
+ if (!this.closed) this.redialIn(delay)
return
}
if (this.closed) { this.connecting = false; return }
@@ -166,7 +188,7 @@ export class UpstreamLink {
this.connecting = false
ws.on('open', () => {
- this.attempts = 0
+ this.openedAt = Date.now()
console.log(`[backend] connected → ${this.url}`)
this.events.status(true)
this.drainQueue()
@@ -214,6 +236,8 @@ export class UpstreamLink {
const onGone = (why: string): void => {
if (this.ws !== ws) return
this.ws = null
+ if (this.openedAt && Date.now() - this.openedAt >= STABLE_MS) this.attempts = 0
+ this.openedAt = 0
if (this.heartbeat) { this.heartbeat.stop(); this.heartbeat = null }
if (this.appPing) { clearInterval(this.appPing); this.appPing = null }
this.draining = false
@@ -223,9 +247,9 @@ export class UpstreamLink {
// A 401 refresh owns the next connect (see the error handler below): no competing backoff timer,
// or two sockets would race for the one machine claim.
if (this.retryingAuth) { console.log(`[backend] disconnected (${why}) — refreshing the token before reconnecting`); return }
- const delay = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** Math.min(this.attempts++, 5))
+ const delay = reconnectDelay(this.attempts++)
console.log(`[backend] disconnected (${why}) — retrying in ${Math.round(delay / 1000)}s (attempt ${this.attempts})`)
- setTimeout(() => this.connect(), delay)
+ this.redialIn(delay)
}
ws.on('close', (code) => onGone(`close ${code}`))
ws.on('error', (err) => {
@@ -243,10 +267,16 @@ export class UpstreamLink {
void this.auth.accessToken({ force: true, failedToken: token })
.then(() => {
this.retryingAuth = false
+ if (this.closed) return
// onGone has normally run by now (the close lands long before a network round trip
// returns); if this socket is somehow still ours, let go of it before dialing again.
if (this.ws === ws) { this.ws = null; try { ws.terminate() } catch { /* ignore */ } }
- this.connect()
+ // The fresh token goes through the backoff like any other drop: a backend that refuses every
+ // token while the refresh keeps succeeding (an auth outage) was redialed as fast as the
+ // round trips allowed.
+ const delay = reconnectDelay(this.attempts++)
+ console.log(`[backend] token refreshed — retrying in ${Math.round(delay / 1000)}s (attempt ${this.attempts})`)
+ this.redialIn(delay)
})
.catch((error: unknown) => {
this.retryingAuth = false
@@ -258,9 +288,9 @@ export class UpstreamLink {
}
if (this.closed) return
if (this.ws === ws) { this.ws = null; try { ws.terminate() } catch { /* ignore */ } }
- const delay = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** Math.min(this.attempts++, 5))
+ const delay = reconnectDelay(this.attempts++)
console.log(`[backend] token refresh failed (${error instanceof Error ? error.message : String(error)}) — retrying in ${Math.round(delay / 1000)}s (attempt ${this.attempts})`)
- setTimeout(() => this.connect(), delay)
+ this.redialIn(delay)
})
} else if (/Unexpected server response: 40[13]\b/.test(msg)) {
this.closed = true
@@ -276,11 +306,21 @@ export class UpstreamLink {
})
}
+ private redialIn(delay: number): void {
+ this.cancelRedial()
+ this.redialTimer = setTimeout(() => { this.redialTimer = null; this.connect() }, delay)
+ }
+
/** Stop for good: no reconnect, whatever the socket does next (a `machine_revoked`). */
- close(): void { this.closed = true }
+ close(): void { this.closed = true; this.cancelRedial() }
+
+ private cancelRedial(): void {
+ if (this.redialTimer) { clearTimeout(this.redialTimer); this.redialTimer = null }
+ }
stop(): void {
this.closed = true
+ this.cancelRedial()
if (this.heartbeat) this.heartbeat.stop()
if (this.appPing) clearInterval(this.appPing)
try { this.ws?.close() } catch { /* ignore */ }
diff --git a/cli/src/lib/authSession.spec.ts b/cli/src/lib/authSession.spec.ts
index 152b951d1..ae4520e73 100644
--- a/cli/src/lib/authSession.spec.ts
+++ b/cli/src/lib/authSession.spec.ts
@@ -1,4 +1,5 @@
import { afterAll, afterEach, describe, expect, it, vi } from 'vitest'
+import type { AuthSession } from './authSession.js'
import { mkdtemp, readFile, rm, stat, writeFile } from 'fs/promises'
import { tmpdir } from 'os'
@@ -18,6 +19,7 @@ const {
readAuthSession,
readSignedOut,
releaseHeldAuthLock,
+ updateAuthSession,
signInOf,
writeAuthSession,
} = await import('./authSession.js')
@@ -325,6 +327,46 @@ describe('AuthSessionManager', () => {
expect(readSignedOut()).toMatchObject({ reason: 'revoked' })
})
+ // Follow-up to the review of #1866: a rewrite that read the session before another process marked it
+ // wrote it back without the mark.
+ it('a rewrite never writes over a mark that landed after it read the session', async () => {
+ writeAuthSession(baseSession())
+
+ const written = await updateAuthSession((latest) => {
+ // Another process marks it while this one works out its change.
+ writeAuthSession({ ...latest, signedOut: { at: 1, reason: 'revoked' } } as typeof latest)
+ return { ...latest, machineId: 'machine-2' }
+ })
+
+ expect(written).toBeNull()
+ expect(readSignedOut()).toMatchObject({ reason: 'revoked' })
+ })
+
+ it('a rewrite of a marked sign-in writes nothing', async () => {
+ writeAuthSession(baseSession())
+ await markSignedOut('revoked')
+ const change = vi.fn((latest: AuthSession): AuthSession => ({ ...latest, machineId: 'machine-2' }))
+
+ expect(await updateAuthSession(change)).toBeNull()
+
+ expect(change).not.toHaveBeenCalled()
+ expect(readSignedOut()).toMatchObject({ reason: 'revoked' })
+ })
+
+ // Follow-up to the review of #1866: a revoke whose lock stayed busy stopped the daemon unmarked, and the
+ // core that came back used the revoked sign-in until it was refused again.
+ it('a revoke marks even when the lock cannot be had', async () => {
+ writeAuthSession(baseSession())
+ const busy = async (): Promise<never> => {
+ throw new AuthSessionError('Another Harness process is refreshing SSO credentials. Please retry.', 'UNAVAILABLE')
+ }
+
+ await markSignedOut('revoked', Date.now(), busy)
+
+ expect(readSignedOut()).toMatchObject({ reason: 'revoked' })
+ expect(readAuthSession()).toBeNull()
+ })
+
it('a new sign-in replaces one marked signed out', async () => {
writeAuthSession(baseSession())
await markSignedOut('revoked')
diff --git a/cli/src/lib/authSession.ts b/cli/src/lib/authSession.ts
index 4fa8639af..72f2f5715 100644
--- a/cli/src/lib/authSession.ts
+++ b/cli/src/lib/authSession.ts
@@ -176,10 +176,38 @@ export type SignedOutReason = 'refresh-refused' | 'revoked'
* it. Only a person deletes it (lib/signOut.ts `removeSignIn`). A refused refresh is tried again
* ([AuthSessionManager.retrySignedOut]); a revoked one is not.
*/
-export function markSignedOut(reason: SignedOutReason, at = Date.now()): Promise<void> {
+export function markSignedOut(reason: SignedOutReason, at = Date.now(), lock: Lock = withLock): Promise<void> {
// Under the refresh lock: a refresh another process has under way saves its session when it is done, and a
// mark written before that save was written over by it, and the revoked sign-in used again (review of #1866).
- return withLock(async () => markSignedOutHeld(reason, at))
+ // A lock that cannot be had (another process holding it past its stale time) still marks: a revoke left
+ // unmarked stopped the daemon, and the core that came back used the revoked sign-in until it was refused
+ // again (follow-up to the review of #1866).
+ return lock(async () => markSignedOutHeld(reason, at)).catch((error: unknown) => {
+ if (!(error instanceof AuthSessionError) || error.code !== 'UNAVAILABLE') throw error
+ markSignedOutHeld(reason, at)
+ })
+}
+
+/** How [markSignedOut] and [updateAuthSession] take the refresh lock; a spec's own in place of [withLock]. */
+export type Lock = <T>(action: () => Promise<T>) => Promise<T>
+
+/**
+ * Rewrites this computer's sign-in from the newest one on disk: [change] gives the new one, or null (or the
+ * same one) to leave it. Under the refresh lock, so a refresh's rotated tokens and a signed-out mark are never
+ * written over, and it is read again just before the write: a sign-in marked meanwhile is left marked (follow-up
+ * to the review of #1866). The sign-in written; null when there was none, or it is marked signed out.
+ */
+export function updateAuthSession(change: (latest: AuthSession) => AuthSession | null): Promise<AuthSession | null> {
+ if (!readAuthSession()) return Promise.resolve(null)
+ return withLock(async () => {
+ const latest = readAuthSession()
+ if (!latest) return null
+ const next = change(latest)
+ if (!next || next === latest) return latest
+ if (readStored()?.signedOut) return null
+ writeAuthSession(next)
+ return next
+ })
}
/** The first wait before a refused refresh is tried again, and the longest. The app asks `auth status` often,
@@ -405,9 +433,7 @@ export class AuthSessionManager {
})
}
- updateMachineId(machineId: string): void {
- const current = readAuthSession()
- if (!current || current.machineId === machineId) return
- writeAuthSession({ ...current, machineId, updatedAt: Date.now() })
+ async updateMachineId(machineId: string): Promise<void> {
+ await updateAuthSession((current) => current.machineId === machineId ? null : { ...current, machineId, updatedAt: Date.now() })
}
}
diff --git a/cli/src/lib/engineLaunch.spec.ts b/cli/src/lib/engineLaunch.spec.ts
index d18d334ae..e8d1b7df9 100644
--- a/cli/src/lib/engineLaunch.spec.ts
+++ b/cli/src/lib/engineLaunch.spec.ts
@@ -28,6 +28,7 @@ import {
permissionFlagToVerify,
permissionModeFlags,
refusePermissionFlagIfUnsupported,
+ engineUpdateCommand,
unsupportedLaunchModelFlag,
resetCommandFlagSupportCache,
engineFallbackPrelude,
@@ -996,7 +997,13 @@ describe('a first prompt on launch', () => {
try { buildEngineCommandArgv('cursor', { firstPrompt: PROMPT }) } catch (error) { refusal = error }
expect(refusal).toBeInstanceOf(FirstPromptUnsupportedError)
expect((refusal as FirstPromptUnsupportedError).code).toBe('PROMPT_UNSUPPORTED')
- expect((refusal as FirstPromptUnsupportedError).message).toContain('cursor')
+ expect((refusal as FirstPromptUnsupportedError).message).toContain('Cursor')
+ })
+
+ // prompt_unsupported, 4 in the Oct 21–27 report: the refusal named the engine but not what to do instead.
+ it('says what to do instead: leave the first message out, or use an agent that takes one', () => {
+ expect(new FirstPromptUnsupportedError('cursor').message).toBe('Cursor cannot start with a first message. Start it without one '
+ + 'and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one.')
})
it('leaves the argv unchanged with no prompt, or an empty one', () => {
@@ -1210,6 +1217,22 @@ describe('the permission gates', () => {
expect(refusal?.detail).toContain('--auto')
})
+ // The install lines are POSIX shell: on Windows only an npm line runs as written (in PowerShell too).
+ it('names an update command only where it runs as written', () => {
+ expect(engineUpdateCommand('opencode', 'darwin')).toBe('curl -fsSL https://opencode.ai/install | bash')
+ expect(engineUpdateCommand('opencode', 'win32')).toBeNull()
+ expect(engineUpdateCommand('codex', 'win32')).toBe('npm install -g @openai/codex')
+ expect(engineUpdateCommand('terminal', 'darwin')).toBeNull()
+ })
+
+ // codex_cli_too_old, 2–4 a day: "Update opencode" did not say how.
+ it('gives the command that updates the engine', async () => {
+ const shell = withFakeOpencode('--auto-update')
+ const refusal = await refusePermissionFlagIfUnsupported('opencode', { permissionMode: 'auto' }, shell)
+ expect(refusal?.detail).toBe('The opencode CLI on this machine does not support --auto, which Harness uses for this permission mode. '
+ + 'Update opencode by running curl -fsSL https://opencode.ai/install | bash, then try again, or choose Ask permissions for this harness.')
+ })
+
it('lets a create through when the flag is there, and when there is no flag to check', async () => {
const shell = withFakeOpencode('--auto')
await expect(refusePermissionFlagIfUnsupported('opencode', { permissionMode: 'auto' }, shell)).resolves.toBeNull()
@@ -1235,7 +1258,7 @@ describe('the permission gates', () => {
}
// A create in Ask is told to update, never to choose the Ask it chose.
const refusal = await refusePermissionFlagIfUnsupported('claude', { permissionMode: 'ask' }, shell)
- expect(refusal?.detail).toContain('Update claude and try again.')
+ expect(refusal?.detail).toContain('Update claude by running npm install -g @anthropic-ai/claude-code, then try again.')
expect(refusal?.detail).not.toContain('choose Ask')
})
diff --git a/cli/src/lib/engineLaunch.ts b/cli/src/lib/engineLaunch.ts
index 778b6e657..e92876ee6 100644
--- a/cli/src/lib/engineLaunch.ts
+++ b/cli/src/lib/engineLaunch.ts
@@ -12,7 +12,7 @@ import { env } from '../config/env.js'
import { launchContract, launchField } from '../engines/launches.js'
import { startupFunctions, startupNeedsScript, startupRuns } from '../engines/kit/launchStartup.js'
import { screenArgs, screenEnvPrefix, screenPrelude, screenVariables } from '../engines/kit/launchScreen.js'
-import { isTerminalEngine, type AgentEngine } from '../engines/types.js'
+import { isTerminalEngine, PROCESS_ENGINES, type AgentEngine } from '../engines/types.js'
import { isOpencodeV2 } from '../engines/opencode/contract.js'
import { binaryOnPath, resolveBinaryOnPath } from './binaryOnPath.js'
import { windowsEngineArgv } from './windows/launch.js'
@@ -20,7 +20,7 @@ import { nativeLaunchConfirmed, windowsHeldPaneArgv, windowsStartupArgs } from '
import { defaultWindowsShell } from './windows/shell.js'
import { engineBin } from './engineBin.js'
import { launchModelArgs, type LaunchModel } from './launchModel.js'
-import { engineInstallPaths, npmEnginePrefix, type EngineInstallRecipe } from './engineInstall.js'
+import { engineInstallPaths, engineInstallRecipe, npmEnginePrefix, type EngineInstallRecipe } from './engineInstall.js'
import { engineLabel } from './agentNames.js'
import { GRID_NO_UPDATE_CHECK_VAR, gridBinaryPath } from './gridBinary.js'
import { loginShellEnvironment } from './loginShellEnv.js'
@@ -129,7 +129,10 @@ export const MAX_FIRST_PROMPT_CHARS = 2000
export class FirstPromptUnsupportedError extends Error {
readonly code = 'PROMPT_UNSUPPORTED' as const
constructor(readonly engine: AgentEngine) {
- super(`${engine} has no documented way to start with a first prompt, so the agent was not created.`)
+ // What to do instead, not only what is missing (prompt_unsupported, Oct 21–27).
+ const takers = PROCESS_ENGINES.filter(supportsFirstPrompt).map(engineLabel)
+ super(`${engineLabel(engine)} cannot start with a first message. Start it without one and type the message once it opens, `
+ + `or choose ${takers.slice(0, -1).join(', ')} or ${takers.at(-1)} to start with one.`)
this.name = 'FirstPromptUnsupportedError'
}
}
@@ -1537,6 +1540,13 @@ export async function unsupportedLaunchModelFlag(engine: AgentEngine, launchMode
return null
}
+/** The line that updates [engine]: its install line, which fetches the latest. Those are POSIX shell lines, so on
+ * Windows only an npm one, which PowerShell runs as written, is named. */
+export function engineUpdateCommand(engine: AgentEngine, platform: NodeJS.Platform = process.platform): string | null {
+ const command = engineInstallRecipe(engine)?.command
+ return command && (platform !== 'win32' || command.startsWith('npm ')) ? command : null
+}
+
/**
* For a launch somebody is waiting on — create, fork. Refusing is kinder than opening a pane that
* the engine will fill with its own help text and leave: the person is here, and Ask works today.
@@ -1560,10 +1570,13 @@ export async function refusePermissionFlagIfUnsupported(
}
const flag = native ? permissionFlagToVerify(engine, choice) : await unsupportedPermissionFlag(engine, choice, shell)
if (!flag) return null
+ const update = engineUpdateCommand(engine)
return {
error: 'CODEX_CLI_TOO_OLD',
detail: `The ${engine} CLI on this machine does not support ${flag}, which Harness uses for this permission mode. `
- + `Update ${engine} and try again${choice.permissionMode === 'ask' ? '.' : ', or choose Ask permissions for this harness.'}`,
+ // How to update, not only that it is needed (codex_cli_too_old, 2–4 a day).
+ + `Update ${engine}${update ? ` by running ${update}, then try again` : ' and try again'}`
+ + `${choice.permissionMode === 'ask' ? '.' : ', or choose Ask permissions for this harness.'}`,
}
}
diff --git a/cli/src/lib/gitProject.spec.ts b/cli/src/lib/gitProject.spec.ts
index 1c3347044..1da23d383 100644
--- a/cli/src/lib/gitProject.spec.ts
+++ b/cli/src/lib/gitProject.spec.ts
@@ -241,6 +241,15 @@ describe('launch Git preparation', { timeout: 30_000 }, () => {
}
})
+ // Desktop makes the name up before the start and keeps it; the person never chose it, so taken is no refusal.
+ it('gives a made-up worktree branch name that is already taken the next free number', async () => {
+ await git('branch', 'quiet-owl')
+ await git('branch', 'quiet-owl-2')
+ const made = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-owl', branchMode: 'placeholder' })
+ expect(await current(made)).toBe('quiet-owl-3')
+ expect(await git('config', '--get', 'branch.quiet-owl-3.harness')).toBe('placeholder')
+ })
+
it('makes a new branch for the folder itself, keeping its uncommitted work, and refuses one that exists', async () => {
await writeFile(join(repo, 'src', 'value'), 'in progress')
expect(await prepare('branch', 'refs/heads/login-fix', repo, { branchName: 'login-fix' })).toBe(repo)
diff --git a/cli/src/lib/gitProject.ts b/cli/src/lib/gitProject.ts
index 4b3a11d2a..574d654aa 100644
--- a/cli/src/lib/gitProject.ts
+++ b/cli/src/lib/gitProject.ts
@@ -329,8 +329,11 @@ export async function prepareGitProject(source: string, options: GitProjectOptio
// Grouped by repository, so the leaf only needs the branch.
const repository = trees[0]?.usable ? basename(trees[0].path) : basename(root)
const taken = new Set((await git(source, ['for-each-ref', '--format=%(refname)', 'refs/heads']).catch(() => '')).split('\n'))
- const branch = options.branchName ?? placeholderBranch(taken, options.pick)
const placeholder = !options.branchName || options.placeholder === true
+ let branch = options.branchName ?? placeholderBranch(taken, options.pick)
+ // A name made up before the start (Desktop keeps its pick) may be taken by then; nobody chose it, so the next
+ // free number is taken instead of refusing with BRANCH_EXISTS.
+ if (placeholder && !existing) for (let suffix = 2, base = branch; taken.has(`refs/heads/${branch}`); suffix++) branch = `${base}-${suffix}`
if (existing) {
if (!taken.has(`refs/heads/${branch}`)) throw new GitProjectError('GIT_PROJECT_UNAVAILABLE', 'That branch is no longer available. Choose another branch.')
if (trees.some(tree => tree.ref === `refs/heads/${branch}`)) {
diff --git a/cli/src/lib/newCommand.spec.ts b/cli/src/lib/newCommand.spec.ts
index c1e553cc2..9eb98ea84 100644
--- a/cli/src/lib/newCommand.spec.ts
+++ b/cli/src/lib/newCommand.spec.ts
@@ -354,6 +354,14 @@ describe('harness new: the daemon', () => {
expect(refused.err[0]).toBe('Install it first: harness dsh install acme/typst')
})
+ // prompt_unsupported, 4 in the Oct 21–27 report, came from `harness new <engine> --task`: say which flag to drop.
+ it('tells a first message the engine cannot take to leave out --task', async () => {
+ const refused = deps(['cursor', '--task', 'fix it'], new FakeSocket((frame) => frame.type === 'agent_create'
+ ? { creationId: 'c1', state: 'failed', failure: { code: 'PROMPT_UNSUPPORTED' } } : null))
+ expect(await newCommand(refused)).toBe(1)
+ expect(refused.err[0]).toBe('That agent cannot be started with a first message. Run it again without --task.')
+ })
+
it('says a launch the machine refused or could not confirm failed, never "Created"', async () => {
const failed = deps(['codex'], new FakeSocket((frame) => frame.type === 'agent_create'
? { creationId: 'c1', state: 'failed', failure: { code: 'SPAWN_FAILED', detail: 'no codex' } } : null))
diff --git a/cli/src/lib/newCommand.ts b/cli/src/lib/newCommand.ts
index 1950d5384..120a3f384 100644
--- a/cli/src/lib/newCommand.ts
+++ b/cli/src/lib/newCommand.ts
@@ -386,7 +386,7 @@ const ERRORS: Record<string, string> = {
INVALID_ENGINE: 'That agent is not one this machine knows.',
INVALID_DSH: 'That harness is not in the machine\'s catalog, or does not run on that engine.',
PROJECT_EXISTS: 'A project with that name already exists. Choose another name, or name its folder to start in it.',
- PROMPT_UNSUPPORTED: 'That agent cannot be started with a first message.',
+ PROMPT_UNSUPPORTED: 'That agent cannot be started with a first message. Run it again without --task.',
PROMPT_TOO_LONG: 'A first message holds at most 2,000 characters. Put the rest in a file and name the file in it.',
SPAWN_FAILED: 'The agent could not be started.',
// Recorded as a refusal only where a launch cannot be held (a new project's folder): its detail says what it waited for.
diff --git a/cli/src/lib/productUsageContract.ts b/cli/src/lib/productUsageContract.ts
index 7f1303c23..766b589f2 100644
--- a/cli/src/lib/productUsageContract.ts
+++ b/cli/src/lib/productUsageContract.ts
@@ -101,6 +101,16 @@ export const PRODUCT_USAGE_FLOW_MEASURES = ['started', 'ok', 'failed', 'cancelle
'under_1s', '1s_to_10s', '10s_to_1m', 'over_1m'] as const
export const PRODUCT_USAGE_UI_METRICS = PRODUCT_USAGE_UI_SURFACES.flatMap(surface =>
PRODUCT_USAGE_FLOWS.flatMap(flow => PRODUCT_USAGE_FLOW_MEASURES.map(measure => `ui_${surface}_${flow}_${measure}` as const)))
+/** Why a Desktop sign-in that did not go through ended, once per sign-in beside its outcome
+ * (desktop/lib/measurement/product_measurement.dart `SignInEndReason`): the CLI's own result code from
+ * `harness login --json`, lower-cased, or what the app saw instead. `cancelled` is the person (Cancel, the other
+ * button, the app closing); `timeout` is a browser page nobody came back from in five minutes, which the person
+ * may have left or finished with a callback that never arrived, so the outcome is `unknown`, not `cancelled`;
+ * `no_result` is a CLI that ended without a result line; `cli_unavailable` one that could not be started.
+ * Until 2026-10-28 Desktop counted every one of these as `failed` (compare releases separately). */
+export const PRODUCT_USAGE_SIGN_IN_END_REASONS = ['cancelled', 'timeout', 'expired', 'denied', 'cli_unavailable',
+ 'cli_too_old', 'no_result', 'callback_error', 'exchange_failed', 'backend_error', 'auth_error', 'daemon_busy',
+ 'daemon_did_not_stop', 'ticket_invalid', 'unavailable', 'other'] as const
export const PRODUCT_USAGE_SETUP_DOWNLOADS = ['opencode', 'codex', 'claude'] as const
export const PRODUCT_USAGE_SETUP_DOWNLOAD_MEASURES = ['started', 'ok', 'failed', 'under_1m', '1m_to_5m', 'over_5m'] as const
// A signed-out report is explicitly enabled on this app. It cannot carry account/work metrics.
@@ -113,6 +123,8 @@ export const PRODUCT_USAGE_SETUP_METRICS = [...PRODUCT_USAGE_SURFACES.flatMap(su
// A step's tool was not installed yet when Desktop checked, so setup installed it: once per step per
// setup, beside the step's own outcome. Signed-out only (a signed-in report passes an older CLI).
...(['setup_harness', 'setup_tmux', 'setup_clipboard'] as const).map(flow => `setup_desktop_${flow}_missing` as const),
+ // Why a Desktop sign-in did not go through. Signed-out only, like `_missing`: a signed-in report passes an older CLI.
+ ...PRODUCT_USAGE_SIGN_IN_END_REASONS.map(reason => `setup_desktop_sign_in_reason_${reason}` as const),
// The agents a new computer downloads beside setup (desktop/lib/bootstrap/agent_prefetch.dart): whether each
// download put its agent in place, and how long it took. Engine names only, never a path or log line.
...PRODUCT_USAGE_SETUP_DOWNLOADS.flatMap(engine => PRODUCT_USAGE_SETUP_DOWNLOAD_MEASURES
diff --git a/cli/src/lib/resumeStoppedAgent.spec.ts b/cli/src/lib/resumeStoppedAgent.spec.ts
index 3c2f2a9c0..6901b17b5 100644
--- a/cli/src/lib/resumeStoppedAgent.spec.ts
+++ b/cli/src/lib/resumeStoppedAgent.spec.ts
@@ -255,6 +255,13 @@ describe('resume refusal and readiness edge cases', () => {
const deps = fixture(); deps.saved.mockReturnValue(null as any)
expect(await resumeStoppedAgent(deps)).toMatchObject({ error: 'AGENT_NOT_FOUND' })
})
+ // 4 on Oct 26: an app resumed from a list that still showed a deleted harness, or one whose conversation another
+ // harness had taken over (stoppedAgents `supersede`). The conversation is still found by search.
+ it('says where to find the conversation when the saved harness is gone', async () => {
+ const deps = fixture(); deps.saved.mockReturnValue(null as any)
+ expect(await resumeStoppedAgent(deps)).toMatchObject({ error: 'AGENT_NOT_FOUND', detail: 'This harness is no longer on this '
+ + 'machine: it was deleted, or another harness now has its conversation. Search for the conversation to open it where it is now.' })
+ })
it('opens a shell without a conversation id', async () => {
const deps = fixture(); const shell = { ...saved, engine: 'terminal' as const, sessionId: '' }; deps.saved.mockReturnValue(shell)
expect(await resumeStoppedAgent(deps)).toMatchObject({ ok: true }); expect(deps.launch).toHaveBeenCalledWith(shell, undefined)
diff --git a/cli/src/lib/resumeStoppedAgent.ts b/cli/src/lib/resumeStoppedAgent.ts
index 30d5871f0..091670df6 100644
--- a/cli/src/lib/resumeStoppedAgent.ts
+++ b/cli/src/lib/resumeStoppedAgent.ts
@@ -67,7 +67,12 @@ export async function resumeStoppedAgent(deps: ResumeStoppedDeps): Promise<Resta
}
}
if (!deps.current()) return resumeChanged
- if (!saved) return { ok: false, error: 'AGENT_NOT_FOUND', detail: 'The saved harness is no longer available.' }
+ // An app's list can still show a deleted harness, or one whose conversation another harness took over (4 on Oct 26);
+ // search finds the conversation wherever it is now.
+ if (!saved) {
+ return { ok: false, error: 'AGENT_NOT_FOUND', detail: 'This harness is no longer on this machine: it was deleted, or another '
+ + 'harness now has its conversation. Search for the conversation to open it where it is now.' }
+ }
// No engine is refused here any more. An engine with a resume argv and a recorded id comes back
// where it left off; one with neither still comes back — same pane, same folder, same name — as a
// new conversation, which `resumed: false` and the client's wording say out loud. Refusing the
diff --git a/cli/src/lib/sessionSearch/__fixtures__/external-shapes.golden.json b/cli/src/lib/sessionSearch/__fixtures__/external-shapes.golden.json
index bf7124ed5..e6a66323f 100644
--- a/cli/src/lib/sessionSearch/__fixtures__/external-shapes.golden.json
+++ b/cli/src/lib/sessionSearch/__fixtures__/external-shapes.golden.json
@@ -373,22 +373,22 @@
"harness/null": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"harness/idle": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"harness/now": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"harness/wait": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"harness/heldBy": "other",
"unverified/open": {
@@ -508,22 +508,22 @@
"owned/null": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"owned/idle": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"owned/now": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"owned/wait": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"owned/heldBy": "free",
"saved-alias/open": {},
@@ -532,22 +532,22 @@
"saved-alias/null": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"saved-alias/idle": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"saved-alias/now": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"saved-alias/wait": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"saved-alias/heldBy": "free",
"profile/open": {},
@@ -983,22 +983,22 @@
"harness/null": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"harness/idle": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"harness/now": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"harness/wait": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"harness/heldBy": "other",
"unverified/open": {
@@ -1118,22 +1118,22 @@
"owned/null": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"owned/idle": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"owned/now": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"owned/wait": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"owned/heldBy": "free",
"saved-alias/open": {},
@@ -1142,22 +1142,22 @@
"saved-alias/null": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"saved-alias/idle": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"saved-alias/now": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"saved-alias/wait": {
"ok": false,
"error": "SESSION_IN_HARNESS",
- "detail": "This conversation is already a harness here."
+ "detail": "This conversation is already open in a harness on this machine. Open that harness instead."
},
"saved-alias/heldBy": "free",
"profile/open": {},
diff --git a/cli/src/superTabs/capacity.spec.ts b/cli/src/superTabs/capacity.spec.ts
index 74a5ee881..6e41616fa 100644
--- a/cli/src/superTabs/capacity.spec.ts
+++ b/cli/src/superTabs/capacity.spec.ts
@@ -55,3 +55,9 @@ it('distinguishes a missing tool from a failed probe and keeps the failure detai
expect(admission(unverified, { installed: true }, quotaOf({}, 'codex', false), { ...requirements, devices: [] }).reasons)
.toEqual(expect.arrayContaining([expect.stringMatching(/Required tool not verified: git.*interactive shell timed out/)]))
})
+it('says how much memory is free and how much a start needs, in GiB', () => {
+ const GiB = 1024 ** 3
+ const capacity = { resources: { cpuPercent: 10, memoryTotalBytes: 32 * GiB, memoryUsedBytes: 32 * GiB - 1.85 * GiB, projectDiskFreeBytes: 500 }, tools: { git: true }, devices: {} }
+ expect(admission(capacity, { installed: true }, quotaOf({}, 'codex', false), { ...requirements, memoryBytes: 2 * GiB, devices: [] }).reasons)
+ .toEqual(['Not enough free memory: 1.8 GiB free, 2 GiB needed.'])
+})
diff --git a/cli/src/superTabs/capacity.ts b/cli/src/superTabs/capacity.ts
index b77a03a58..d8f2bea87 100644
--- a/cli/src/superTabs/capacity.ts
+++ b/cli/src/superTabs/capacity.ts
@@ -69,6 +69,18 @@ export async function readCapabilities(input: Json, deps = {
}
const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v)
+const GiB = 1024 ** 3
+/** One decimal, rounded down, so a refusal never reads "2 GiB free, 2 GiB needed". */
+export const gibibytes = (bytes: number) => `${Math.floor(Math.max(0, bytes) / GiB * 10) / 10} GiB`
+/** The refusal for memory, the one start-failure reason every Swarm member may read (backend startFailure.ts): it says
+ * only numbers they already see in the Machines view. */
+export const memoryShort = (freeBytes: number, neededBytes: number) =>
+ `Not enough free memory: ${gibibytes(freeBytes)} free, ${gibibytes(neededBytes)} needed.`
+/** The free and needed amounts of a `memoryShort` reason at the start of a host's raw reason, or null for any other. */
+export function memoryShortIn(reason: unknown): { free: string; needed: string } | null {
+ const match = typeof reason === 'string' ? /^Not enough free memory: (\d+(?:\.\d)? GiB) free, (\d+(?:\.\d)? GiB) needed\./.exec(reason) : null
+ return match ? { free: match[1]!, needed: match[2]! } : null
+}
/** Only measured windows leave the account reader. No credentials, emails or
* invented token counts; an unreported/custom-profile allowance is unknown. */
export function quotaOf(reply: Json, engine: string, customAccount: boolean) {
@@ -108,7 +120,7 @@ export function admission(capacity: Json, engine: Json, quota: ReturnType<typeof
['Project disk space', resources.projectDiskFreeBytes, requirements.diskBytes],
] as const) {
if (!finite(value)) { unknown.push(`${label} is unknown.`); if (needed > 0) reasons.push(`${label} could not be verified.`) }
- else if (value < needed) reasons.push(`${label} is ${value} bytes; this work requires ${needed}.`)
+ else if (value < needed) reasons.push(label === 'Available memory' ? memoryShort(value, needed) : `${label} is ${value} bytes; this work requires ${needed}.`)
}
if (!finite(resources.cpuPercent)) {
unknown.push('CPU use is unknown.')
diff --git a/cli/src/superTabs/command.spec.ts b/cli/src/superTabs/command.spec.ts
index c96f38362..7b1264c1b 100644
--- a/cli/src/superTabs/command.spec.ts
+++ b/cli/src/superTabs/command.spec.ts
@@ -229,6 +229,36 @@ it('refuses to remove a machine for an agent: a Swarm agent\'s pane, an outside
}
expect(request.mock.calls.some(c => c[0] === 'super_tabs')).toBe(false)
})
+it('lets a machine owner set how many agents it offers, as the person, from their own terminal', async () => {
+ const print = vi.fn(), close = vi.fn()
+ const request = vi.fn(async (type: string, _payload?: Record<string, unknown>) => (type === 'agents_list' ? { agents: [] }
+ : { ok: true, machineId: 'studio', maxAgents: 96, maximum: 96 }) as Record<string, unknown>)
+ const deps = { where: () => where, open: async () => ({ request, close, machineId: 'machine' }), print, pane: '%99', env: {} }
+ expect(await superTabCommand(['--tab', 'tab', 'set-agents', 'studio', '96'], deps)).toBe(0)
+ expect(request).toHaveBeenLastCalledWith('super_tabs', expect.objectContaining({ action: 'setMachineAgents', tabId: 'tab', machineId: 'studio', maxAgents: 96 }), 30_000)
+ expect(JSON.parse(print.mock.calls.at(-1)![0])).toMatchObject({ ok: true, maxAgents: 96 })
+ request.mockResolvedValue({ error: 'ABOVE_MACHINE_MAXIMUM', detail: 'Mac Studio can offer at most 96 agents: one for every 2 GB of its memory, and at least 4.' })
+ expect(await superTabCommand(['--tab', 'tab', 'set-agents', 'studio', '97'], deps)).toBe(1)
+ expect(print.mock.calls.at(-1)![0]).toContain('at most 96 agents')
+ for (const argv of [['--tab', 'tab', 'set-agents', 'studio'], ['--tab', 'tab', 'set-agents', 'studio', '0'], ['--tab', 'tab', 'set-agents', 'studio', '2.5'],
+ ['--tab', 'tab', 'set-agents', 'studio', 'many'], ['--tab', 'tab', 'set-agents', '../x', '8'], ['--tab', 'tab', 'set-agents', 'studio', '8', '--yes']]) {
+ expect(() => parseSuperTabArgs(argv, where)).toThrow('set-agents MACHINE_ID COUNT')
+ }
+})
+it('refuses to set a machine\'s agents for an agent: a Swarm agent\'s pane, an outside agent\'s shell, or --agent', async () => {
+ const print = vi.fn(), close = vi.fn()
+ const request = vi.fn(async (type: string) => type === 'agents_list' ? { agents: [{ id: 'worker', engine: 'claude', tmuxPane: '%7', status: 'active' }] } : { ok: true })
+ const deps = { where: () => where, open: async () => ({ request, close, machineId: 'machine' }), print }
+ for (const [argv, extra] of [
+ [['--tab', 'tab', 'set-agents', 'studio', '96'], { pane: '%7', env: {} }],
+ [['--tab', 'tab', 'set-agents', 'studio', '96'], { pane: '%99', env: { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 'session' } }],
+ [['--tab', 'tab', '--agent', 'agent', 'set-agents', 'studio', '96'], { pane: '%99', env: {} }],
+ ] as const) {
+ expect(await superTabCommand(argv, { ...deps, ...extra })).toBe(1)
+ expect(print.mock.calls.at(-1)![0]).toContain('Set a machine\'s agents from your own terminal or from Desktop, not from an agent.')
+ }
+ expect(request.mock.calls.some(c => c[0] === 'super_tabs')).toBe(false)
+})
// Lead mentions (spec 2026-10-24-lead-mentions): each --mention names a person by id or email; the service maps them.
it('passes each --mention as written, and leaves a post without one unchanged', () => {
expect(parseSuperTabArgs([...prefix, 'post', 'lead', 'Please confirm', 'op-1', '--mention', '[email protected]', '--reply-to', 'm1', '--mention', 'person-2'], where).payload.command)
diff --git a/cli/src/superTabs/command.ts b/cli/src/superTabs/command.ts
index 1cfea03c1..798efd916 100644
--- a/cli/src/superTabs/command.ts
+++ b/cli/src/superTabs/command.ts
@@ -10,7 +10,7 @@ import { uploadAttachments } from './attach.js'
import { keyName } from './terminal.js'
import { randomUUID } from 'node:crypto'
-const USAGE = 'harness super-tab --tab ID [--agent ID] [--port N --machine ID] status | messages GROUP | message GROUP MESSAGE_ID | decisions [--answered] | post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... [--mention PERSON]... | command OPERATION_ID JSON | start OPERATION_ID JSON | resume START_ID | capacity MACHINE_ID JSON | route GROUP JSON | plan [JSON] | remove-machine MACHINE_ID [--yes] | screen AGENT [--scrollback N] | type AGENT [TEXT] [--key K]... | help'
+const USAGE = 'harness super-tab --tab ID [--agent ID] [--port N --machine ID] status | messages GROUP | message GROUP MESSAGE_ID | decisions [--answered] | post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... [--mention PERSON]... | command OPERATION_ID JSON | start OPERATION_ID JSON | resume START_ID | capacity MACHINE_ID JSON | route GROUP JSON | plan [JSON] | remove-machine MACHINE_ID [--yes] | set-agents MACHINE_ID COUNT | screen AGENT [--scrollback N] | type AGENT [TEXT] [--key K]... | help'
export function parseSuperTabArgs(argv: readonly string[], where: Where) {
const positional: string[] = []
let tabId = '', agentId = ''
@@ -61,6 +61,9 @@ export function parseSuperTabArgs(argv: readonly string[], where: Where) {
? { action: 'backend', method: 'POST', path: `/api/super-tabs/${tabId}/commands`,
body: { operationId: `machine-remove-${randomUUID()}`, command: { type: 'machine.remove', machineId: first } } }
: { action: 'backend', method: 'GET', path: `/api/super-tabs/${tabId}/machines/${first}/removal` })
+ } else if (action === 'set-agents' && identifier(first) && /^[1-9][0-9]{0,3}$/.test(second ?? '') && positional.length === 3) {
+ // The machine's owner, as the person: how many Swarm agents may run on it at once (contribution.ts setMachineAgents).
+ Object.assign(payload, { action: 'setMachineAgents', machineId: first, maxAgents: Number(second) })
} else if (action === 'route' && identifier(first) && second && positional.length === 3) {
Object.assign(payload, { conversationId: first, assessment: JSON.parse(second) })
} else if (action === 'plan' && positional.length <= 2) {
@@ -98,17 +101,20 @@ export async function superTabCommand(argv: readonly string[], deps: {
const request = parseSuperTabArgs(argv, (deps.where ?? (() => whereFor(process.env.TMUX_PANE)))())
operationId = request.payload.operationId
daemon = await (deps.open ?? openDaemon)(request.where)
- if (request.payload.action === 'backend') {
- // The owner's own act: it deletes this machine's Swarm folders, so neither a Swarm agent on it (its pane, or --agent)
- // nor an outside agent's shell may run it with the owner's authority.
+ const owners = request.payload.action === 'backend' || request.payload.action === 'setMachineAgents'
+ if (owners) {
+ // The owner's own acts: removal deletes this machine's Swarm folders, and no agent raises its own machine's room
+ // (Lead, 2026-10-28). So neither a Swarm agent on it (its pane, or --agent) nor an outside agent's shell may run
+ // them with the owner's authority.
const listed = request.payload.agentId || outsideCaller(deps.env ?? process.env, request.where.machineId) ? null : await daemon.request('agents_list')
if (!listed || callerOf(Array.isArray(listed.agents) ? listed.agents as Frame[] : [], deps.pane ?? process.env.TMUX_PANE, request.where.machineId)) {
- throw new Error('Remove a machine from your own terminal or from Desktop, not from an agent.')
+ throw new Error(request.payload.action === 'backend' ? 'Remove a machine from your own terminal or from Desktop, not from an agent.'
+ : 'Set a machine\'s agents from your own terminal or from Desktop, not from an agent.')
}
}
// Help names the caller when it can, so a Lead also reads its own options; outside a harness it is the plain help.
const help = request.payload.action === 'help'
- if (request.payload.action !== 'backend' && !request.payload.agentId && (!help || request.payload.tabId)) {
+ if (!owners && !request.payload.agentId && (!help || request.payload.tabId)) {
const listed = await daemon.request('agents_list')
const frames = Array.isArray(listed.agents) ? listed.agents as Frame[] : []
const caller = callerOf(frames, deps.pane ?? process.env.TMUX_PANE, request.where.machineId)
diff --git a/cli/src/superTabs/contribution.spec.ts b/cli/src/superTabs/contribution.spec.ts
index 8173304e3..bd22767f7 100644
--- a/cli/src/superTabs/contribution.spec.ts
+++ b/cli/src/superTabs/contribution.spec.ts
@@ -1,6 +1,7 @@
import { describe, expect, it, vi } from 'vitest'
import { fakeCore } from '../testing/fakeCore.js'
-import { ContributionPreparations, prepareContribution, prepareTeamContribution } from './contribution.js'
+import { ContributionPreparations, prepareContribution, prepareTeamContribution, setMachineAgents } from './contribution.js'
+import { SuperTabHostError } from './wire.js'
import { mkdtemp, rm, stat } from 'node:fs/promises'
import { homedir, tmpdir } from 'node:os'
import { join } from 'node:path'
@@ -87,8 +88,14 @@ describe('one-field machine preparation', () => {
it.each([
{ totalGiB: 32, usedGiB: 30, maxAgents: 8, maxAvailableAgents: 16 },
{ totalGiB: 16, usedGiB: 15, maxAgents: 4, maxAvailableAgents: 8 },
- { totalGiB: 64, usedGiB: 63, maxAgents: 16, maxAvailableAgents: 16 },
- { totalGiB: 2, usedGiB: 1, maxAgents: 1, maxAvailableAgents: 1 },
+ { totalGiB: 64, usedGiB: 63, maxAgents: 16, maxAvailableAgents: 32 },
+ // The Mac Studio: every 2 GB may run an agent, while the starting suggestion stays at today's 16 (Ken, 2026-10-28).
+ { totalGiB: 192, usedGiB: 100, maxAgents: 16, maxAvailableAgents: 96 },
+ // Every machine may offer 4, whatever its RAM; a small one still starts at what it suggested before.
+ { totalGiB: 8, usedGiB: 7, maxAgents: 2, maxAvailableAgents: 4 },
+ { totalGiB: 2, usedGiB: 1, maxAgents: 1, maxAvailableAgents: 4 },
+ // The server refuses more than 1024 (backend superTabs/commands.ts).
+ { totalGiB: 4096, usedGiB: 1, maxAgents: 16, maxAvailableAgents: 1024 },
])('suggests $maxAgents of $maxAvailableAgents slots from $totalGiB GiB total RAM', async ({ totalGiB, usedGiB, maxAgents, maxAvailableAgents }) => {
const f = fixture()
f.deps.capacity.mockResolvedValueOnce({ ok: true, resources: {
@@ -183,3 +190,74 @@ describe('this Mac\'s Harness Team account preparing through the relay', () => {
expect(slow.close).toHaveBeenCalledOnce()
})
})
+
+describe('the owner setting how many agents a machine offers, from a terminal', () => {
+ function owned(totalGiB: number | null, machine: Record<string, unknown> = {}) {
+ const core = fakeCore()
+ const state: Record<string, unknown> = { machines: [{ machineId: 'studio', name: 'Mac Studio', contributorId: 'ken', cwd: '/Users/ken/harnesses/swarms/tab', scope: 'swarm',
+ // A machine added before Swarms ran only Claude Code and Codex lists every engine it had; the server takes only those two.
+ engines: ['claude', 'codex', 'opencode'], maxAgents: 16, paused: false,
+ ...(totalGiB === null ? {} : { observation: { generation: 'g1', resources: { memoryTotalBytes: totalGiB * GiB, memoryUsedBytes: GiB } } }), ...machine }] }
+ const sent: Record<string, unknown>[] = []
+ const backend = vi.fn(async (_core: unknown, method: string, path: string, body?: unknown) => {
+ if (method === 'GET') return swarmReply(path, state)
+ sent.push(body as Record<string, unknown>)
+ return { result: {} }
+ })
+ const set = (maxAgents: number) => setMachineAgents(core, { tabId: 'tab', machineId: 'studio', maxAgents }, { backend } as never)
+ return { set, sent, backend }
+ }
+
+ it('changes only the number, keeping the machine\'s name, folder and engines', async () => {
+ const f = owned(192)
+ expect(await f.set(96)).toEqual({ ok: true, machineId: 'studio', maxAgents: 96, maximum: 96 })
+ expect(f.sent).toHaveLength(1)
+ expect(f.sent[0]!.command).toEqual({ type: 'machine.contribute', machineId: 'studio', name: 'Mac Studio', cwd: '/Users/ken/harnesses/swarms/tab',
+ scope: 'swarm', engines: ['claude', 'codex'], maxAgents: 96 })
+ expect(String(f.sent[0]!.operationId)).toMatch(/^machine-agents-/)
+ })
+ it('refuses a number above the machine\'s maximum, and says what the maximum is', async () => {
+ const big = owned(192)
+ expect(await big.set(97)).toEqual({ error: 'ABOVE_MACHINE_MAXIMUM', detail: 'Mac Studio can offer at most 96 agents: one for every 2 GB of its memory, and at least 4.' })
+ const small = owned(8)
+ expect(await small.set(5)).toMatchObject({ error: 'ABOVE_MACHINE_MAXIMUM', detail: expect.stringContaining('at most 4 agents') })
+ expect([...big.sent, ...small.sent]).toEqual([])
+ // Every machine may offer 4, whatever its memory.
+ expect(await owned(2).set(4)).toMatchObject({ ok: true, maxAgents: 4, maximum: 4 })
+ })
+ it('refuses a machine that is not in the Swarm, or whose memory it has not reported', async () => {
+ const f = owned(192, { machineId: 'other' })
+ expect(await f.set(8)).toEqual({ error: 'MACHINE_NOT_FOUND', detail: 'This machine is not in this Swarm. Add it from Desktop first.' })
+ const unread = owned(null)
+ expect(await unread.set(8)).toEqual({ error: 'MACHINE_MEMORY_UNKNOWN', detail: 'Mac Studio has not reported its memory yet. Try again once it is online.' })
+ expect([...f.sent, ...unread.sent]).toEqual([])
+ })
+ it('refuses a paused machine, which the server would resume with its new number', async () => {
+ const f = owned(192, { paused: true })
+ expect(await f.set(32)).toEqual({ error: 'MACHINE_PAUSED', detail: 'Mac Studio is paused. Resume it first: changing its agents would also resume it.' })
+ expect(f.sent).toEqual([])
+ })
+ it('passes on the server\'s refusal, such as another person\'s machine', async () => {
+ const f = owned(192)
+ const read = f.backend.getMockImplementation()!
+ f.backend.mockImplementation(async (core: unknown, method: string, path: string, body?: unknown) => {
+ if (method === 'GET') return read(core, method, path, body)
+ throw new SuperTabHostError('OWNER_REQUIRED', 'Only the machine owner can contribute it.', 403)
+ })
+ await expect(f.set(8)).rejects.toMatchObject({ code: 'OWNER_REQUIRED', status: 403 })
+ })
+ it('says so when an older server could only take 16', async () => {
+ const f = owned(192)
+ f.backend.mockImplementation(async (_core: unknown, method: string, path: string, body?: unknown) => {
+ if (method === 'GET') return swarmReply(path, { machines: [{ machineId: 'studio', name: 'Mac Studio', cwd: '/w', scope: 'swarm', engines: ['claude'], maxAgents: 2,
+ observation: { resources: { memoryTotalBytes: 192 * GiB } } }] })
+ const command = (body as { command: { maxAgents: number } }).command
+ if (command.maxAgents > 16) throw new SuperTabHostError('VALIDATION_ERROR', 'command.maxAgents: Too big: expected number to be <=16', 400)
+ f.sent.push(body as Record<string, unknown>)
+ return { result: {} }
+ })
+ expect(await f.set(96)).toEqual({ ok: true, machineId: 'studio', maxAgents: 16, maximum: 96,
+ notice: 'This Swarm\'s server takes at most 16 agents per machine, so Mac Studio now offers 16. Update the server to offer more.' })
+ expect(f.sent.map(b => (b.command as { maxAgents: number }).maxAgents)).toEqual([16])
+ })
+})
diff --git a/cli/src/superTabs/contribution.ts b/cli/src/superTabs/contribution.ts
index 85afa6f15..079856479 100644
--- a/cli/src/superTabs/contribution.ts
+++ b/cli/src/superTabs/contribution.ts
@@ -2,7 +2,7 @@ import type { CoreApi } from '../core/api.js'
import { openDaemon } from '../agentClient/daemon.js'
import { parseProjectFolder, prepareProjectFolder } from '../lib/projectFolder.js'
import { readCapabilities, START_REQUIREMENTS } from './capacity.js'
-import { backend, identifier, object } from './host.js'
+import { backend, identifier, object, SuperTabHostError } from './host.js'
import { mkdir } from 'node:fs/promises'
import { readAuthSession } from '../lib/authSession.js'
import { randomUUID } from 'node:crypto'
@@ -18,6 +18,53 @@ interface ContributionDeps {
}
const CONTRIBUTION_DEPS = { backend, open: openDaemon, prepare: prepareProjectFolder, capacity: readCapabilities }
+/** The most agents a machine may offer: one for every 2 GB of total RAM, and 4 whatever its RAM (Ken, 2026-10-28: the cap
+ * of 16 held a 192 GB Mac Studio to a sixth of that). 1024 is the most the server accepts (backend superTabs/commands.ts). */
+export const machineMaximum = (memoryTotalBytes: number): number =>
+ Math.min(1024, Math.max(4, Math.floor(memoryTotalBytes / START_REQUIREMENTS.memoryBytes)))
+
+/** The owner's own request to the server, as Desktop and `harness super-tab set-agents` send it. A server from before 1024
+ * (2026-10-28) refuses a machine offered with more than 16 agents; that machine is offered with 16 instead of not at all.
+ * The server checks the number before it records the operation, so the second send under the same operation is still
+ * the first that counts. `offered16` says it happened. */
+export async function ownerRequest(core: CoreApi, method: string, path: string, body: unknown, send: typeof backend = backend): Promise<{ value: unknown; offered16: boolean }> {
+ try { return { value: await send(core, method, path, body), offered16: false } } catch (error) {
+ const command = object(object(body).command)
+ if (method !== 'POST' || !/^\/api\/super-tabs\/[A-Za-z0-9_-]+\/commands$/.test(path) || command.type !== 'machine.contribute'
+ || typeof command.maxAgents !== 'number' || command.maxAgents <= 16 || !(error instanceof SuperTabHostError)
+ || error.status !== 400 || error.code !== 'VALIDATION_ERROR' || !/^command\.maxAgents: .*\b16\b/.test(error.message)) throw error
+ return { value: await send(core, method, path, { ...object(body), command: { ...command, maxAgents: 16 } }), offered16: true }
+ }
+}
+
+/** `harness super-tab set-agents`: the owner sets how many Swarm agents may run on one of their machines at once, without
+ * Desktop. Only the number changes; the machine's name, folder and engines are sent again as the Swarm has them, since
+ * the server takes a machine's settings whole. The server checks that the person owns the machine. */
+export async function setMachineAgents(core: CoreApi, input: { tabId: string; machineId: string; maxAgents: number },
+ deps: { backend: typeof backend; reads?: SwarmReads } = { backend }): Promise<Json> {
+ const { state } = await (deps.reads ?? new SwarmReads(core, { backend: deps.backend })).read(input.tabId)
+ const machine = (Array.isArray(state.machines) ? state.machines.map(object) : []).find(m => m.machineId === input.machineId)
+ if (!machine) return { error: 'MACHINE_NOT_FOUND', detail: 'This machine is not in this Swarm. Add it from Desktop first.' }
+ const name = typeof machine.name === 'string' ? machine.name : input.machineId
+ // The server takes a machine's settings whole and a new contribution starts unpaused (backend superTabs/commands.ts).
+ if (machine.paused === true) return { error: 'MACHINE_PAUSED', detail: `${name} is paused. Resume it first: changing its agents would also resume it.` }
+ const total = object(object(machine.observation).resources).memoryTotalBytes
+ if (typeof total !== 'number') return { error: 'MACHINE_MEMORY_UNKNOWN', detail: `${name} has not reported its memory yet. Try again once it is online.` }
+ const maximum = machineMaximum(total)
+ if (input.maxAgents > maximum) {
+ return { error: 'ABOVE_MACHINE_MAXIMUM', detail: `${name} can offer at most ${maximum} agents: one for every 2 GB of its memory, and at least 4.` }
+ }
+ // A machine added before Swarms ran only Claude Code and Codex still lists every engine it had; the server takes those two.
+ const engines = (Array.isArray(machine.engines) ? machine.engines : []).filter(e => e === 'claude' || e === 'codex')
+ if (!engines.length) return { error: 'NO_SWARM_ENGINE', detail: `${name} runs neither Claude Code nor Codex. Configure it from Desktop.` }
+ const command = { type: 'machine.contribute', machineId: input.machineId, name, cwd: machine.cwd,
+ ...(machine.scope === 'swarm' ? { scope: 'swarm' } : {}), engines, maxAgents: input.maxAgents }
+ const sent = await ownerRequest(core, 'POST', `/api/super-tabs/${input.tabId}/commands`,
+ { operationId: `machine-agents-${randomUUID()}`, command }, deps.backend)
+ return { ok: true, machineId: input.machineId, maxAgents: sent.offered16 ? 16 : input.maxAgents, maximum,
+ ...(sent.offered16 ? { notice: `This Swarm's server takes at most 16 agents per machine, so ${name} now offers 16. Update the server to offer more.` } : {}) }
+}
+
/** Owner-only setup. Reuses the regular checkout preparation and engine probe;
* it neither launches an agent nor grants the team access to the computer. */
export async function prepareContribution(core: CoreApi, input: Json, given: Partial<ContributionDeps> = {}): Promise<Json> {
@@ -62,7 +109,8 @@ export async function prepareContribution(core: CoreApi, input: Json, given: Par
const total = typeof resources.memoryTotalBytes === 'number' ? resources.memoryTotalBytes : 0
// Free memory is checked again for every start. It must not shrink the machine's
// configured limit just because other work happens to be running during setup.
- const maxAvailableAgents = Math.max(1, Math.min(16, Math.floor(total / START_REQUIREMENTS.memoryBytes)))
+ // The suggestion keeps its 16, so a machine that joins by itself still sends what a server from before 1024 accepts.
+ const maxAvailableAgents = machineMaximum(total)
const maxAgents = Math.max(1, Math.min(16, Math.floor(total / (2 * START_REQUIREMENTS.memoryBytes))))
return { ok: true, state: 'ready', cwd, engines: [...new Set(engines)], maxAgents, maxAvailableAgents, ...(swarm ? { scope: 'swarm' } : {}) }
} finally { connection.close() }
diff --git a/cli/src/superTabs/reservations.spec.ts b/cli/src/superTabs/reservations.spec.ts
index f0c33c8e5..077f01f01 100644
--- a/cli/src/superTabs/reservations.spec.ts
+++ b/cli/src/superTabs/reservations.spec.ts
@@ -23,12 +23,80 @@ function setup() {
gone: vi.fn(async key => gone.has(key)),
} })
const resources: MachineResources = { cpuPercent: 20, memoryTotalBytes: 150, memoryUsedBytes: 50 }
+ // The live agents' start times (registeredAt) and their measured memory, by harness id.
+ const live = new Map<string, number>(), measured = new Map<string, number>()
+ const clock = { now: Date.UTC(2026, 9, 28, 4) }
+ vi.mocked(core.agents.byAgent).mockImplementation(key => live.has(key) ? { agentId: key, registeredAt: live.get(key)! } as never : undefined)
const deps = { resources: vi.fn(async () => resources),
disk: vi.fn(async (cwd: string) => ({ freeBytes: 100, volume: cwd === '/second-volume' ? 'second' : 'first', path: cwd })),
- sqlite: () => builtinSqlite() as never }
+ sqlite: () => builtinSqlite() as never, now: () => clock.now, agentMemory: vi.fn(async () => new Map(measured)) }
const open = () => { const book = new CapacityReservations(core, 'machine-1', deps); books.push(book); return book }
- return { directory, file: join(directory, 'super-tabs/capacity.sqlite'), core, native, stopped, gone, resources, deps, open }
+ /** The start reserved as `n` launched as harness `agent-n` at this moment. */
+ const launch = (n: number) => { native.set(id(n), { creationId: id(n), state: 'created', agentId: `agent-${n}` }); live.set(`agent-${n}`, clock.now) }
+ return { directory, file: join(directory, 'super-tabs/capacity.sqlite'), core, native, stopped, gone, resources, deps, open, live, measured, clock, launch }
}
+const GiB = 1024 ** 3, MINUTE = 60_000
+const free = (f: ReturnType<typeof setup>, bytes: number) => { f.resources.memoryTotalBytes = 32 * GiB; f.resources.memoryUsedBytes = 32 * GiB - Math.round(bytes) }
+const agentInput = (n: number) => input(n, 2 * GiB, 0)
+
+// Ken's MacBook Pro, 2026-10-28: 7.85 GiB free of 32 and three settled builders using about 0.4 GiB together, yet a start was
+// refused with 1.85 GiB "left". Free memory (vm_stat) already counts what a running agent uses, so its 2 GiB was taken twice.
+it("counts a start's memory only during its start window, so settled agents do not block more starts", async () => {
+ const f = setup(), book = f.open()
+ free(f, 30 * GiB)
+ for (const n of [1, 2, 3]) { expect(await book.reserve(agentInput(n))).toMatchObject({ ok: true }); f.launch(n); f.measured.set(`agent-${n}`, 0.13 * GiB) }
+ f.clock.now += 5 * MINUTE
+ free(f, 7.85 * GiB)
+ for (const n of [4, 5, 6]) { expect(await book.reserve(agentInput(n))).toMatchObject({ ok: true }); f.launch(n) }
+ expect(await book.reserve(agentInput(7))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE',
+ detail: 'Not enough free memory: 1.8 GiB free, 2 GiB needed. 6 GiB more is set aside for agents still starting.' })
+ // The first of the three new agents settles: its own use is in free memory now, and its window no longer holds.
+ f.clock.now += 5 * MINUTE - 1
+ expect(await book.reserve(agentInput(7))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
+ f.clock.now += 1
+ expect(await book.reserve(agentInput(7))).toMatchObject({ ok: true })
+})
+
+it('ends a start window early once the agent measures its whole reservation', async () => {
+ const f = setup(), book = f.open()
+ free(f, 3 * GiB)
+ expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
+ f.launch(1)
+ f.measured.set('agent-1', 2 * GiB - 1)
+ expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
+ f.measured.set('agent-1', 2 * GiB)
+ expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
+})
+
+it('keeps holding a start that has not launched, and times a launched agent the core no longer lists from its reservation', async () => {
+ const f = setup(), book = f.open()
+ free(f, 3 * GiB)
+ expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
+ f.clock.now += 60 * MINUTE
+ expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
+ // Launched, but not in the core's live list (a reconnect in between): its window ran from the reservation and is over.
+ f.native.set(id(1), { creationId: id(1), state: 'created', agentId: 'agent-1' })
+ expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
+})
+
+it('holds every launched start in its window when its memory cannot be measured', async () => {
+ const f = setup(), book = f.open()
+ free(f, 3 * GiB)
+ expect(await book.reserve(agentInput(1))).toMatchObject({ ok: true })
+ f.launch(1)
+ f.deps.agentMemory.mockRejectedValue(new Error('ps failed'))
+ expect(await book.reserve(agentInput(2))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE' })
+ f.clock.now += 5 * MINUTE
+ expect(await book.reserve(agentInput(2))).toMatchObject({ ok: true })
+})
+
+it('still refuses a truly full machine with no other start pending, and says how much memory is free', async () => {
+ const f = setup(), book = f.open()
+ free(f, 1.5 * GiB)
+ expect(await book.reserve(agentInput(1))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: 'Not enough free memory: 1.5 GiB free, 2 GiB needed.' })
+ free(f, 20 * GiB); f.resources.memoryPressure = 'critical'
+ expect(await book.reserve(agentInput(1))).toMatchObject({ error: 'CAPACITY_UNAVAILABLE', detail: expect.stringContaining('critical memory pressure') })
+})
it('serializes simultaneous starts across books and accounts for their declared budgets', async () => {
const f = setup(), a = f.open(), b = f.open()
diff --git a/cli/src/superTabs/reservations.ts b/cli/src/superTabs/reservations.ts
index db8a92b15..c362c1c58 100644
--- a/cli/src/superTabs/reservations.ts
+++ b/cli/src/superTabs/reservations.ts
@@ -6,7 +6,9 @@ import { builtinSqlite } from '../lib/sqliteBuiltin.js'
import { hardenPrivateStateFileIfPresent, readPrivateStateFile, secureStateDirectory } from '../lib/secureState.js'
import { creationObservation, type CreationObservation } from '../lib/creationObservation.js'
import { readMachineResources } from '../lib/machineResources.js'
+import { createHarnessResourcesReader } from '../lib/harnessResources.js'
import { readCapacityDisk } from './disk.js'
+import { gibibytes, memoryShort } from './capacity.js'
import { object } from './wire.js'
type Json = Record<string, unknown>
@@ -19,7 +21,7 @@ interface Database { exec(sql: string): void; prepare(sql: string): Statement; c
type DatabaseConstructor = new (path: string) => Database
interface Reservation {
creation_id: string; fingerprint: string; memory_bytes: number; disk_bytes: number
- volume: string; harness_id: string | null; released: number
+ volume: string; harness_id: string | null; released: number; created_at: number
}
export interface ReservationBook {
reserve(input: Json, closed?: AbortSignal): Promise<Json>
@@ -31,6 +33,9 @@ interface Dependencies {
resources: typeof readMachineResources
disk: typeof readCapacityDisk
sqlite: () => DatabaseConstructor | null
+ now?: () => number
+ /** Each live agent's measured memory, by harness id. */
+ agentMemory?: () => Promise<Map<string, number>>
}
const MAX_ACTIVE = 256
const MAX_FILE_BYTES = 32 * 1024 * 1024
@@ -39,6 +44,14 @@ const creationIdValid = (v: unknown): v is string => typeof v === 'string' && /^
const bytes = (v: unknown): v is number => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0
const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v)
const unavailable = (detail: string): Json => ({ error: 'CAPACITY_UNAVAILABLE', detail })
+/** How long a launched agent's reservation still counts. Free memory (vm_stat) already counts what a running agent uses,
+ * so a reservation held past its start counted the agent twice: on Ken's MacBook Pro (2026-10-28) three settled builders
+ * using about 0.4 GiB held 6 GiB, and a start was refused with 7.85 GiB free. The window covers an agent still loading. */
+export const START_WINDOW_MS = 5 * 60_000
+const memoryOf = (core: CoreApi) => {
+ const read = createHarnessResourcesReader(() => core.agents.live())
+ return async () => new Map((await read()).agents.flatMap(row => row.memoryBytes === null ? [] : [[row.agentId, row.memoryBytes] as const]))
+}
/** All Super Tabs on this host share one ledger. SQLite serializes admission
* across service restarts/overlap; no asynchronous work runs inside its write
@@ -48,6 +61,8 @@ export class CapacityReservations implements ReservationBook {
private readonly file: string
private readonly identity: { dev: number; ino: number }
private stopped = false
+ private readonly now: () => number
+ private readonly agentMemory: () => Promise<Map<string, number>>
constructor(private readonly core: CoreApi, private readonly machineId: string,
private readonly deps: Dependencies = { resources: readMachineResources, disk: readCapacityDisk,
@@ -70,6 +85,8 @@ export class CapacityReservations implements ReservationBook {
} catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error }
hardenPrivateStateFileIfPresent(this.file, MAX_FILE_BYTES)
}
+ this.now = deps.now ?? Date.now
+ this.agentMemory = deps.agentMemory ?? memoryOf(core)
this.identity = lstatSync(this.file)
this.db = new Database(this.file)
try {
@@ -150,6 +167,15 @@ export class CapacityReservations implements ReservationBook {
}
}
+ /** What a reservation still holds: all of it until its agent launched, then until its window closes or the agent measures
+ * as much itself. A launched agent the core no longer lists is timed from its reservation. */
+ private held(row: Reservation, measured: Map<string, number> | null, now: number): number {
+ if (!row.harness_id) return row.memory_bytes
+ const started = this.core.agents.byAgent(row.harness_id)?.registeredAt
+ if (now - (finite(started) ? started : row.created_at) >= START_WINDOW_MS) return 0
+ return (measured?.get(row.harness_id) ?? 0) >= row.memory_bytes ? 0 : row.memory_bytes
+ }
+
async observe(creationId: unknown, closed?: AbortSignal): Promise<Json> {
if (!creationIdValid(creationId)) return { error: 'INVALID_REQUEST' }
this.check(closed)
@@ -183,8 +209,9 @@ export class CapacityReservations implements ReservationBook {
this.check(closed)
const existing = this.db.prepare('SELECT released, volume FROM reservations WHERE creation_id = ?').get(creationId)
if (existing?.released === 1) return { error: 'START_FINISHED', detail: 'This native start has ended. Create a new start request.' }
- const [native, resources, destination] = await Promise.all([
+ const [native, resources, destination, measured] = await Promise.all([
this.native(creationId), this.deps.resources().catch(() => null), this.deps.disk(cwd, input.worktree === true).catch(() => null),
+ memory > 0 ? this.agentMemory().catch(() => null) : null,
])
this.check(closed)
if (!destination || !bytes(destination.freeBytes) || !destination.volume) return unavailable('The destination disk capacity could not be verified.')
@@ -207,12 +234,14 @@ export class CapacityReservations implements ReservationBook {
: { error: 'CAPACITY_RECEIPT_CONFLICT', detail: 'This native start already has a different or finished capacity reservation.' }
const active = this.rows()
if (active.length >= MAX_ACTIVE) return unavailable('Reconcile pending starts on this machine before starting more agents.')
- const memoryHeld = active.reduce((sum, row) => sum + row.memory_bytes, 0)
+ const now = this.now(), memoryHeld = active.reduce((sum, row) => sum + this.held(row, measured, now), 0)
const diskHeld = active.filter(row => row.volume === destination.volume).reduce((sum, row) => sum + row.disk_bytes, 0)
- if (memory > 0 && (!finite(freeMemory) || memory > freeMemory - memoryHeld)) return unavailable('Available memory is already in use or reserved for other agents. Choose another machine or wait for work to finish.')
+ if (memory > 0 && !finite(freeMemory)) return unavailable('The free memory on this machine could not be read.')
+ if (memory > 0 && memory > freeMemory! - memoryHeld) return unavailable(memoryShort(freeMemory! - memoryHeld, memory)
+ + (memoryHeld > 0 ? ` ${gibibytes(memoryHeld)} more is set aside for agents still starting.` : ''))
if (disk > destination.freeBytes - diskHeld) return unavailable('Destination disk space is already in use or reserved for other agents. Choose another machine or free space before retrying.')
this.db.prepare(`INSERT INTO reservations (creation_id, fingerprint, memory_bytes, disk_bytes, volume, created_at)
- VALUES (?, ?, ?, ?, ?, ?)`).run(creationId, fingerprint, memory, disk, destination.volume, Date.now())
+ VALUES (?, ?, ?, ?, ?, ?)`).run(creationId, fingerprint, memory, disk, destination.volume, now)
return { ok: true, reservationId: creationId }
}, closed)
}
diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.ts
index 436ba29a0..20b923c38 100644
--- a/cli/src/superTabs/service.spec.ts
+++ b/cli/src/superTabs/service.spec.ts
@@ -25,7 +25,7 @@ const leads = (state: Record<string, unknown>, agentId: unknown) => {
const swarmData = (agent: Record<string, unknown>, path: string, state: Record<string, unknown> = { agents: [agent] }): unknown =>
path.includes('/hosts/') ? hostForm([{ tabId: 'tab', agent, lead: leads(state, agent.id) }], { tabs: ['tab'] })
: /^\/api\/super-tabs\/tab\/(parts|changes)/.test(path) ? swarmReply(path, state) : { state }
-function setup(options: { prepareContribution?: typeof import('./contribution.js').prepareContribution } = {}) {
+function setup(options: { prepareContribution?: typeof import('./contribution.js').prepareContribution; setMachineAgents?: typeof import('./contribution.js').setMachineAgents } = {}) {
const agentId = createHash('sha256').update(JSON.stringify(['machine-1', 'native'])).digest('hex').slice(0, 24)
const agent = { id: agentId, machineId: 'machine-1', harnessId: 'native' }
const call = vi.fn<CoreApi['account']['backend']>(async (_method, path) => ({ status: 200, body: { success: true, data: swarmData(agent, path) } }))
@@ -191,6 +191,44 @@ it('limits the owner proxy to Super Tab endpoints and preserves backend failures
vi.mocked(t.core.account.backend).mockResolvedValueOnce({ status: 403, body: { success: false, error: { code: 'FORBIDDEN', message: 'Access withdrawn' } } })
expect(await t.ask({ action: 'backend', method: 'GET', path: '/api/super-tabs/tab' }, owner)).toEqual({ error: 'FORBIDDEN', detail: 'Access withdrawn', status: 403 })
})
+it('sets a machine\'s agents only for the person at this computer, and says what the number means', async () => {
+ const setMachineAgents = vi.fn(async () => ({ ok: true, machineId: 'studio', maxAgents: 96, maximum: 96 }))
+ const t = setup({ setMachineAgents })
+ const ask = { action: 'setMachineAgents', tabId: 'tab', machineId: 'studio', maxAgents: 96 }
+ for (const asker of [visitor, { local: false, owner: true, accountOwner: true }]) expect(await t.ask(ask, asker)).toEqual({ error: 'OWNER_REQUIRED' })
+ expect(setMachineAgents).not.toHaveBeenCalled()
+ for (const maxAgents of [0, 2.5, '96', 1025]) expect(await t.ask({ ...ask, maxAgents }, owner)).toMatchObject({ error: 'INVALID_REQUEST' })
+ expect(await t.ask(ask, owner)).toEqual({ ok: true, machineId: 'studio', maxAgents: 96, maximum: 96 })
+ expect(setMachineAgents).toHaveBeenCalledWith(t.core, { tabId: 'tab', machineId: 'studio', maxAgents: 96 })
+ const help = (await t.ask({ action: 'help' }, owner) as { help: Record<string, string> }).help
+ expect(help.setAgents).toContain('how many Swarm agents may run on that machine at once')
+})
+describe('a machine offered with more than 16 agents', () => {
+ const contribute = (maxAgents: number) => ({ action: 'backend', method: 'POST', path: '/api/super-tabs/tab/commands', body: { operationId: 'add-studio',
+ command: { type: 'machine.contribute', machineId: 'studio', name: 'Studio', cwd: '/swarm', scope: 'swarm', engines: ['claude'], maxAgents } } })
+ // What a server from before 1024 answers (backend middlewares/validation.ts, zod 4's message for .max(16)).
+ const refuse = (message: string) => ({ status: 400, body: { success: false, error: { code: 'VALIDATION_ERROR', message } } })
+ it('is offered with 16 when an older server refuses more, under the same operation', async () => {
+ const t = setup()
+ t.call.mockResolvedValueOnce(refuse('command.maxAgents: Too big: expected number to be <=16'))
+ t.call.mockResolvedValueOnce({ status: 200, body: { success: true, data: { result: { machineId: 'studio' } } } })
+ expect(await t.ask(contribute(96), owner)).toEqual({ ok: true, value: { result: { machineId: 'studio' } } })
+ expect(t.call.mock.calls.map(([method, path, body]) => [method, path, object(object(body).command).maxAgents, object(body).operationId])).toEqual([
+ ['POST', '/api/super-tabs/tab/commands', 96, 'add-studio'],
+ ['POST', '/api/super-tabs/tab/commands', 16, 'add-studio'],
+ ])
+ })
+ it('keeps every other refusal as the server gave it', async () => {
+ const t = setup()
+ t.call.mockResolvedValueOnce(refuse('command.cwd: Use a full folder path, such as /home/me/work or C:\\Users\\me\\work.'))
+ expect(await t.ask(contribute(96), owner)).toMatchObject({ error: 'VALIDATION_ERROR', status: 400 })
+ t.call.mockResolvedValueOnce(refuse('command.maxAgents: Too big: expected number to be <=1024'))
+ expect(await t.ask(contribute(2048), owner)).toMatchObject({ error: 'VALIDATION_ERROR', status: 400 })
+ t.call.mockResolvedValueOnce(refuse('command.maxAgents: Too big: expected number to be <=16'))
+ expect(await t.ask(contribute(16), owner)).toMatchObject({ error: 'VALIDATION_ERROR', status: 400 })
+ expect(t.call).toHaveBeenCalledTimes(3)
+ })
+})
it('documents how a lead shares its project repository for other machines', async () => {
const t = setup()
const answer = await t.ask({ action: 'help' }, owner) as { help: { commands: Array<Record<string, unknown>> } }
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index 1f95e59f5..8b0bcfecb 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -10,7 +10,7 @@ import { within } from './wire.js'
import { machineChoices } from '../lib/newCommand.js'
import { START_REQUIREMENTS } from './capacity.js'
import { CapacityReservations, type ReservationBook } from './reservations.js'
-import { ContributionPreparations, prepareContribution } from './contribution.js'
+import { ContributionPreparations, ownerRequest, prepareContribution, setMachineAgents } from './contribution.js'
import { messageIdOf } from './attach.js'
import { cardId, SwarmCards } from './cards.js'
import { GitHubTokenRefresher, githubToken } from './github.js'
@@ -43,6 +43,9 @@ const HELP = {
start: 'start OPERATION_ID JSON: create one agent in a conversation on a machine in this Swarm\'s Machines list; to use another machine, a person adds it to the Swarm first. Repeat exactly after an interruption; it follows the same native creation receipt. It does not assign work. With worktree true, the agent starts from the repository\'s default branch, fetched first, unless you set branchRef (refs/heads/BRANCH, or refs/remotes/origin/BRANCH to fetch it first) to start from another branch, such as the one this work builds on. Set role "reviewer" to start a Reviewer; leave role out for a Builder. The role is kept for the session. On Custom skills, add "roleId" to the start request to start the agent in that role of its kind (a builder or reviewer role from status); without it the agent takes the first role of its kind. A Reviewer runs on claude or codex and is assigned only review groups (conversation.create with reviewOf naming the group it reviews); a review group is assigned only to a Reviewer. Add the Reviewer to the reviewed group with conversation.agent so it is told when that work is ready for review and can pass its independent check. Start one with a routeDecisionId like any agent.',
release: 'When a Builder finishes, decide reuse, keep or stop; prefer stop unless more work is coming soon. Reuse assigns new work; agent.release records keep or requests stop. Wait for the execution host to confirm a stop. A person can withdraw a stuck stop; the session cannot receive new work in that Swarm. Its native capacity stays reserved until its host confirms stopping. Other Swarms wait up to two minutes for an in-flight close, then may reuse it.',
resume: 'resume START_ID: finish a pending start without creating another agent.',
+ // A person's own command, for the machines they added; an agent's terminal is refused (command.ts), so no agent raises its
+ // own machine's room (Lead, 2026-10-28).
+ setAgents: 'set-agents MACHINE_ID COUNT: for a machine\'s owner, from their own terminal, not an agent\'s: how many Swarm agents may run on that machine at once. Each agent still needs free memory when it starts. A machine may offer one agent for every 2 GB of its memory, and at least 4; a larger number is refused.',
route: 'route GROUP JSON: before you start an agent or assign work to another agent, choose who does it. Work you do yourself is not routed. JSON: {"difficulty":"low|medium|high","risk":"low|medium|high","size":"small|medium|large","why":"one sentence","kind":"optional word such as ui or docs","local":"optional true, only when a person asked for a local model","model":"optional: the model a person named, in their words; only it is offered","needs":{"tools":[],"devices":[],"cwd":"/absolute/repo"}}. size is how long the work runs: small about 20 minutes, medium about an hour, large about three hours. Candidates that break the owner\'s hard rules are left out, and so are machines that cannot take a teammate\'s project: it runs only on Team machines (a Mac\'s Harness Team account whose privacy check passed, or a machine used only for agents), and the route says why the others were left out. Soft rules (a preferred engine for the kind, idle agents first) rank the rest. A group whose task requires machines or devices (task "requires":{"machines":["MACHINE"],"devices":["/dev/…"]}, set with conversation.create or work.define) is offered only those machines; while none can take it the route answers NO_CANDIDATE with "waiting":true, so keep it queued and route it again later. A pick on a model served on the Swarm\'s grid starts with gridModel and gridName in place of model and effort. Start or assign the pick with its routeDecisionId; to choose otherwise, pass overrideReason. An agent\'s start or work.assign without a routeDecisionId is refused, so route first; a person can still start and assign by hand.',
screen: 'screen AGENT [--scrollback N]: read a worker\'s terminal as plain text, with up to 200 lines of scrollback. Only its project\'s Lead may. Use it when a worker seems stuck.',
type: 'type AGENT [TEXT] [--key K]...: type text, then keys (Enter, Esc, Tab, Up, Down, Left, Right, Ctrl-C, 0-9), into a worker\'s terminal. Answer prompts within its task; ask the owner before approving anything risky.',
@@ -179,6 +182,7 @@ export async function sharedSwarm(sources: SwarmSources): Promise<boolean> {
export interface SuperTabServiceOptions {
prepareContribution?: typeof prepareContribution
+ setMachineAgents?: typeof setMachineAgents
capacity?: typeof readCapabilities
host?: (core: CoreApi, machineId: string, options: SuperTabHostOptions) => SuperTabHost
reservations?: (core: CoreApi, machineId: string) => ReservationBook
@@ -318,6 +322,15 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
return { ok: true, role: grant ? grant.role : grant, ...(grant ? { mode: grant.mode } : {}) }
}
if (payload.action === 'prepareContribution') return preparations.read(payload)
+ // `harness super-tab set-agents`, typed by the person at this computer; never through the relay.
+ if (payload.action === 'setMachineAgents') {
+ if (!asker.local) return { error: 'OWNER_REQUIRED' }
+ const { maxAgents } = payload
+ if (!identifier(payload.tabId) || !identifier(payload.machineId) || typeof maxAgents !== 'number' || !Number.isInteger(maxAgents) || maxAgents < 1 || maxAgents > 1024) {
+ return { error: 'INVALID_REQUEST', detail: 'Name the Swarm, the machine and a whole number of agents from 1 to 1024.' }
+ }
+ return await (options.setMachineAgents ?? setMachineAgents)(core, { tabId: payload.tabId, machineId: payload.machineId, maxAgents })
+ }
// The devices' (core/devicesLink.ts): a Harness Pro that shows the Swarm cards is attached or gone, wants a Lead's recap, or
// has one open. They read the account's Swarms as the person, and need no agent.
// Only this computer's own devices ask: an account owner on another machine does not make this one read the Swarms.
@@ -344,8 +357,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =
|| !/^\/api\/super-tabs(?:\/[A-Za-z0-9_-]+)*(?:\?[A-Za-z0-9_=&%-]+)?$/.test(path)) {
return { error: 'INVALID_REQUEST', detail: 'Choose a Super Tab endpoint.' }
}
- const value = await backend(core, method as string, path, payload.body)
- return { ok: true, value }
+ return { ok: true, value: (await ownerRequest(core, method as string, path, payload.body)).value }
}
const named = identifier(payload.agentId) ? payload.agentId : null
const hashed = identifier(payload.harnessId) ? createHash('sha256').update(JSON.stringify([core.daemon.machineId(), payload.harnessId])).digest('hex').slice(0, 24) : null
diff --git a/cli/src/superTabs/start.spec.ts b/cli/src/superTabs/start.spec.ts
index 29684637c..088cb7e9f 100644
--- a/cli/src/superTabs/start.spec.ts
+++ b/cli/src/superTabs/start.spec.ts
@@ -924,7 +924,9 @@ describe('a Lead\'s start that fails before its agent exists', () => {
/** What happens to the retry's start: the backend refuses it, or its reply is lost after or before the backend recorded it. */
retry?: 'refused' | 'lost' | 'lostUnrecorded'
/** Machines off the contributed list: the Lead's own start launches there, and this one refuses for its owner's sharing. */
- direct?: string[] } = {}) {
+ direct?: string[]
+ /** Why a failing machine's host fails the start; the app token problem unless set. */
+ error?: string } = {}) {
const starts = new Map<string, Record<string, unknown>>()
const fails = new Set(options.fails ?? ['mac-one'])
const commands: Record<string, unknown>[] = []
@@ -934,7 +936,7 @@ describe('a Lead\'s start that fails before its agent exists', () => {
if (!start) return { error: 'NOT_FOUND', detail: 'This agent start is unavailable.' }
// The host readies a queued start on its next pass: a machine whose app token cannot be had fails it there.
const request = start.request as Record<string, unknown>
- if (start.read && fails.has(String(request.machineId))) start.error = TOKEN
+ if (start.read && fails.has(String(request.machineId))) start.error = options.error ?? TOKEN
start.read = true
return { ok: true, value: structuredClone(start) }
}
@@ -1069,6 +1071,15 @@ describe('a Lead\'s start that fails before its agent exists', () => {
expect(result).toMatchObject({ error: 'START_BLOCKED', startId: 'first-start', detail: expect.stringContaining(TOKEN) })
})
+ // Ken's MacBook Pro, 2026-10-28: the group read "until that machine is fixed" when the machine was only short of memory.
+ it('names a memory shortage and the machine in the notice, and leaves out the rest of the raw reason', async () => {
+ const reason = 'Not enough free memory: 1.8 GiB free, 2 GiB needed. 6 GiB more is set aside for agents still starting.'
+ const b = backend({ candidates: [candidate('c0', 'mac-one')], error: reason })
+ expect(await b.lead(b.first)).toMatchObject({ error: 'START_BLOCKED', detail: expect.stringContaining(reason) })
+ expect(b.of('message.send')).toMatchObject([{ text: 'Builder could not start on Mac One: not enough free memory (1.8 GiB free, 2 GiB needed), '
+ + 'and no other machine allowed for this task could take it. This task has no worker until memory frees up on that machine or another one is added.' }])
+ })
+
it('reports instead of trying a third machine when the retry fails as well', async () => {
const b = backend({ fails: ['mac-one', 'mac-two'] })
const result = await b.lead(b.first)
diff --git a/cli/src/superTabs/start.ts b/cli/src/superTabs/start.ts
index 27e0abe32..5b717cb1a 100644
--- a/cli/src/superTabs/start.ts
+++ b/cli/src/superTabs/start.ts
@@ -2,7 +2,7 @@ import { encodeRuntimeProfile } from '../engines/kit/runtime.js'
import { parseRuntimeProfile } from '../lib/runtimeProfileWire.js'
import { createHash, randomUUID } from 'node:crypto'
import { openDaemon, type Daemon, type Where } from '../agentClient/daemon.js'
-import { admission, quotaOf, type Requirements } from './capacity.js'
+import { admission, memoryShortIn, quotaOf, type Requirements } from './capacity.js'
import { groupSkillMode, identifier, object } from './host.js'
import { permissionModeFlags } from '../lib/engineLaunch.js'
import type { AgentEngine } from '../engines/types.js'
@@ -147,14 +147,19 @@ async function startElsewhere(input: Json, failed: Json, scoped: ScopedRequest,
const requester = identifier(group?.requesterId) ? [group.requesterId] : []
// People read why in the failure row the backend wrote; this one says only what it means, never the raw error. A task's
// requirement names no machine at all: the one it failed on is a required one, which a reader may not see (backend
- // model.ts TaskRequirement; review of #1847).
+ // model.ts TaskRequirement; review of #1847). A memory shortage is named, with only the numbers members see in the Machines
+ // view: "until that machine is fixed" sent people looking for a fault on Ken's MacBook Pro (2026-10-28).
+ const short = memoryShortIn(on.error)
requireSuccess(await scoped({ action: 'command', operationId: derived('start-blocked', String(on.id)), command: { type: 'message.send',
conversationId: request.conversationId, replyTo: null, recipientIds: [], ...(requester.length ? { mentions: requester } : {}),
text: required
? `${String(request.name)} could not start. This task needs a particular machine or device, so it was not moved to another machine. `
+ 'It has no worker until a machine that has what it needs can start it.'
- : `${String(request.name)} could not start on ${machineName(object(on.request).machineId)}, and no other machine allowed for this task could take it. `
- + 'This task has no worker until that machine is fixed or another one is added.' } }))
+ : short
+ ? `${String(request.name)} could not start on ${machineName(object(on.request).machineId)}: not enough free memory (${short.free} free, ${short.needed} needed), `
+ + 'and no other machine allowed for this task could take it. This task has no worker until memory frees up on that machine or another one is added.'
+ : `${String(request.name)} could not start on ${machineName(object(on.request).machineId)}, and no other machine allowed for this task could take it. `
+ + 'This task has no worker until that machine is fixed or another one is added.' } }))
return { error: 'START_BLOCKED', startId: on.id, detail: `${String(on.error)} ${required
? 'This task requires its machine or device, so it was not moved; the group was told.'
: 'No other machine allowed for this task could start it; the group was told.'}` }
diff --git a/cli/src/team/command.spec.ts b/cli/src/team/command.spec.ts
index 2d1784f99..3005e3d52 100644
--- a/cli/src/team/command.spec.ts
+++ b/cli/src/team/command.spec.ts
@@ -48,7 +48,12 @@ function fake(over: Partial<TeamCommandDeps> & { adminResult?: Awaited<ReturnTyp
out: (line) => out.push(line), err: (line) => err.push(line),
user: () => 'owner-placeholder', home: () => OWNER_HOME, uid: () => 501, hostname: () => 'Mac-placeholder',
env: {}, interactive: false, ask: vi.fn(async () => 'y'), now: () => now, sleep: vi.fn(async (ms: number) => { now += ms }),
- session: () => session, writeSession: vi.fn((s: AuthSession) => { session = s }), signOutAsked: (flags) => signOutAsked({ interactive: over.interactive ?? false, flags, ancestors: () => [], isApp: () => false }),
+ session: () => session, writeSession: vi.fn((s: AuthSession) => { session = s }),
+ updateSession: vi.fn(async (change: (latest: AuthSession) => AuthSession | null) => {
+ const next = session ? change(session) : null
+ if (next) session = next
+ return next ?? session
+ }), signOutAsked: (flags) => signOutAsked({ interactive: over.interactive ?? false, flags, ancestors: () => [], isApp: () => false }),
removeSignIn: vi.fn(() => { session = null }),
auth: vi.fn(async () => ({ session: session!, headers: { authorization: 'Bearer x' } })), post: post as never,
get: vi.fn(async (path: string) => path === '/api/machines' ? { machines: MACHINES } : { user: { id: 'user-placeholder-1' } }) as never,
diff --git a/cli/src/team/command.ts b/cli/src/team/command.ts
index 235477b10..219256651 100644
--- a/cli/src/team/command.ts
+++ b/cli/src/team/command.ts
@@ -79,6 +79,9 @@ export interface TeamCommandDeps {
session(): AuthSession | null
writeSession(session: AuthSession): void
+ /** Rewrites the newest sign-in under the refresh lock, leaving a signed-out mark alone (lib/authSession.ts
+ * `updateAuthSession`): [change] gives the new one, or null to leave it. */
+ updateSession(change: (latest: AuthSession) => AuthSession | null): Promise<AuthSession | null>
/** How a person asked for this computer's sign-in to go, or null when nothing says one did (lib/signOut.ts). */
signOutAsked(flags: readonly string[]): SignOutAsked | null
/** Takes the sign-in away, logged with who asked (lib/signOut.ts `removeSignIn`). */
@@ -516,9 +519,9 @@ async function recordTeamMachine(deps: TeamCommandDeps, label: string, log: (lin
const machineId = answer?.machine?.machineId
if (typeof machineId !== 'string' || !machineId) throw new Error('Harness answered without a machine id')
// A refresh may have rewritten the session meanwhile: the machine id goes into the newest one.
- const latest = deps.session()
- if (latest?.kind !== 'team' || latest.computerId !== session.computerId) return
- if (latest.machineId !== machineId) deps.writeSession({ ...latest, machineId, updatedAt: deps.now() })
+ const kept = await deps.updateSession((latest) => latest.kind !== 'team' || latest.computerId !== session.computerId
+ || latest.machineId === machineId ? null : { ...latest, machineId, updatedAt: deps.now() })
+ if (kept?.kind !== 'team' || kept.computerId !== session.computerId) return
log(`runs as machine ${machineId}`)
} catch (error) {
log(`could not look up this account's machine yet (${(error as Error).message}); the next start tries again`)
diff --git a/cli/src/team/deps.ts b/cli/src/team/deps.ts
index b53f792b7..803623cb1 100644
--- a/cli/src/team/deps.ts
+++ b/cli/src/team/deps.ts
@@ -4,7 +4,7 @@ import { homedir, hostname, userInfo } from 'node:os'
import { dirname, join } from 'node:path'
import { createInterface } from 'node:readline'
import { env } from '../config/env.js'
-import { readAuthSession, writeAuthSession } from '../lib/authSession.js'
+import { readAuthSession, updateAuthSession, writeAuthSession } from '../lib/authSession.js'
import { controlPlaneAuth, postJson, requestJson } from '../lib/controlPlane.js'
import { computerId } from '../lib/daemonState.js'
import { peekIdentity } from '../lib/e2ee/store.js'
@@ -56,6 +56,7 @@ export function teamCommandDeps(options: {
sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
session: readAuthSession,
writeSession: writeAuthSession,
+ updateSession: updateAuthSession,
signOutAsked: (flags) => signOutAsked({ interactive: process.stdin.isTTY === true, flags, ancestors: chain }),
removeSignIn: (asked) => removeSignIn('team off', asked, chain),
auth: controlPlaneAuth,
diff --git a/desktop/lib/auth/cli_login.dart b/desktop/lib/auth/cli_login.dart
index 82f181ca4..d2a5f9fc3 100644
--- a/desktop/lib/auth/cli_login.dart
+++ b/desktop/lib/auth/cli_login.dart
@@ -222,6 +222,11 @@ class CliLogin implements SignInClient, PhoneSignInClient {
if (onQr != null && code != null) {
throw PhoneSignInException(code, text);
}
+ // A browser one says so too, for the count of why sign-ins did not go through. A CLI that
+ // ended without a result line crashed or was killed: that is a reason of its own.
+ if (onQr == null && (code != null || !gotResult)) {
+ throw SignInException(code ?? 'NO_RESULT', text);
+ }
throw StateError(text);
}
} finally {
diff --git a/desktop/lib/auth/sign_in_client.dart b/desktop/lib/auth/sign_in_client.dart
index 8a25468bd..c306eefb8 100644
--- a/desktop/lib/auth/sign_in_client.dart
+++ b/desktop/lib/auth/sign_in_client.dart
@@ -19,3 +19,16 @@ abstract interface class SignInClient {
Future<void> logout();
}
+
+/// Why a browser sign-in did not finish, as the CLI coded its result line (`harness login --json`):
+/// `TIMEOUT` (nobody came back from the page within five minutes), `CANCELLED` (the app that
+/// started it stopped it), `CALLBACK_ERROR`, `EXCHANGE_FAILED`, `BACKEND_ERROR`, `DAEMON_BUSY`, ….
+class SignInException implements Exception {
+ const SignInException(this.code, this.message);
+
+ final String code;
+ final String message;
+
+ @override
+ String toString() => message;
+}
diff --git a/desktop/lib/measurement/product_measurement.dart b/desktop/lib/measurement/product_measurement.dart
index 538c9d65a..5691b8331 100644
--- a/desktop/lib/measurement/product_measurement.dart
+++ b/desktop/lib/measurement/product_measurement.dart
@@ -80,6 +80,47 @@ enum ProductFlow {
enum ProductOutcome { ok, failed, cancelled, unknown }
+/// Why a Desktop sign-in that did not go through ended (`setup_desktop_sign_in_reason_<wire>`), once
+/// per sign-in beside its outcome: the CLI's own result code, or what the app saw instead. Fixed
+/// names only; the backend refuses any other (`PRODUCT_USAGE_SIGN_IN_END_REASONS`).
+enum SignInEndReason {
+ /// The person pressed Cancel, chose the other button, or the app closed meanwhile.
+ cancelled('cancelled'),
+
+ /// Nobody came back from the browser page within the CLI's five minutes: the person left, or
+ /// finished there and the callback never reached the CLI.
+ timeout('timeout'),
+
+ /// The phone's QR ran out unscanned.
+ expired('expired'),
+
+ /// Turned down on the phone.
+ denied('denied'),
+
+ /// The CLI could not be started at all.
+ cliUnavailable('cli_unavailable'),
+
+ /// The CLI is too old for this way in.
+ cliTooOld('cli_too_old'),
+
+ /// The CLI ended without a result line: it crashed or was killed.
+ noResult('no_result'),
+ callbackError('callback_error'),
+ exchangeFailed('exchange_failed'),
+ backendError('backend_error'),
+ authError('auth_error'),
+ daemonBusy('daemon_busy'),
+ daemonDidNotStop('daemon_did_not_stop'),
+ ticketInvalid('ticket_invalid'),
+ unavailable('unavailable'),
+
+ /// A code not named here, or an error with none.
+ other('other');
+
+ const SignInEndReason(this.wire);
+ final String wire;
+}
+
/// Where Add Phone was opened from, counted each time it opens
/// (`ui_desktop_add_phone_<wire>`): which way in, nothing else.
enum AddPhoneOpening {
@@ -738,6 +779,17 @@ class ProductMeasurement extends ChangeNotifier {
}
}
+ /// Why a sign-in that did not go through ended. A signed-out setup count only, like
+ /// [_countSetupMissing]: the reasons are names an older CLI's report proxy does not know.
+ void signInEnded(SignInEndReason reason) {
+ if (sharing || !_setupAllowed || surface != 'desktop' || _disposed) return;
+ _count(
+ 'setup',
+ _now().toUtc().toIso8601String().substring(0, 10),
+ 'setup_${surface}_sign_in_reason_${reason.wire}',
+ );
+ }
+
/// How many new computers needed a tool installed: a signed-out setup count only, because a
/// signed-in report goes through the local CLI, whose copy of the contract may be older.
void _countSetupMissing(ProductFlow flow) {
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 7bfa27f6a..3b02f9228 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -7809,6 +7809,7 @@ class AppNotifier extends ChangeNotifier {
Future<void> login([SignInProvider? provider]) async {
if (_disposed || signingIn || signingOut || signOutError != null) return;
final measureSignIn = productMeasurement.begin(ProductFlow.signIn);
+ var signedInHere = false;
final wasGuest = isGuest;
final revision = _invalidateAuthWork();
_closedHistory.clear();
@@ -7841,6 +7842,7 @@ class AppNotifier extends ChangeNotifier {
);
if (!_authWorkCurrent(revision)) return;
measureSignIn(ProductOutcome.ok);
+ signedInHere = true;
_loginAuthorized = true;
pendingAuthorizeUrl = null;
_resetLoginBrowser();
@@ -7859,7 +7861,7 @@ class AppNotifier extends ChangeNotifier {
// The first sign-in on this computer offers Add Phone; a later one does not.
unawaited(_offerPhoneAfterSignIn(revision));
} catch (error) {
- measureSignIn(ProductOutcome.failed);
+ if (!signedInHere) _measureSignInEnd(measureSignIn, error, revision);
if (!_authWorkCurrent(revision)) return;
status = wasGuest ? AppStatus.authenticated : AppStatus.unauthenticated;
_lastError = error.toString();
@@ -7888,6 +7890,37 @@ class AppNotifier extends ChangeNotifier {
if (_authWorkCurrent(revision)) notifyListeners();
}
+ /// A sign-in that did not go through: its outcome, and why. The person moving on — Cancel, the
+ /// other button, the app closing ([_authWorkCurrent] no longer) or turning it down on the phone —
+ /// is `cancelled`, not `failed`. A page nobody came back from in time, or a QR nobody scanned, is
+ /// `unknown`: they may have left, or finished and the callback never arrived, which only the
+ /// reason (`timeout`, `expired`) tells apart from the rest. Everything else is `failed`.
+ void _measureSignInEnd(
+ void Function(ProductOutcome) finish,
+ Object error,
+ int revision,
+ ) {
+ final reason = !_authWorkCurrent(revision)
+ ? SignInEndReason.cancelled
+ : switch (error) {
+ SignInException(:final code) || PhoneSignInException(:final code) =>
+ SignInEndReason.values.firstWhere(
+ (reason) => reason.wire == code.toLowerCase(),
+ orElse: () => SignInEndReason.other,
+ ),
+ CliNotAvailableException() => SignInEndReason.cliUnavailable,
+ _ => SignInEndReason.other,
+ };
+ finish(switch (reason) {
+ SignInEndReason.cancelled ||
+ SignInEndReason.denied => ProductOutcome.cancelled,
+ SignInEndReason.timeout ||
+ SignInEndReason.expired => ProductOutcome.unknown,
+ _ => ProductOutcome.failed,
+ });
+ productMeasurement.signInEnded(reason);
+ }
+
/// The failed sign-in again, to the account the person chose the first time.
Future<void> retryLogin() => login(signInProvider);
@@ -8402,6 +8435,7 @@ class AppNotifier extends ChangeNotifier {
return;
}
final finish = productMeasurement.begin(ProductFlow.signIn);
+ var signedInHere = false;
final wasGuest = isGuest;
final revision = _invalidateAuthWork();
previousAccountEmail = currentUser?.email;
@@ -8435,6 +8469,7 @@ class AppNotifier extends ChangeNotifier {
);
if (!_authWorkCurrent(revision)) return;
finish(ProductOutcome.ok);
+ signedInHere = true;
_loginAuthorized = true;
_clearPhoneSignIn();
notifyListeners();
@@ -8445,7 +8480,7 @@ class AppNotifier extends ChangeNotifier {
}
_guestDeskRestorePending = false;
} catch (error) {
- finish(ProductOutcome.failed);
+ if (!signedInHere) _measureSignInEnd(finish, error, revision);
if (!_authWorkCurrent(revision)) return;
status = wasGuest ? AppStatus.authenticated : AppStatus.unauthenticated;
_lastError = error.toString();
diff --git a/desktop/lib/super_tabs/leaderboard/goal_line.dart b/desktop/lib/super_tabs/leaderboard/goal_line.dart
index c2302f46e..20cbe4177 100644
--- a/desktop/lib/super_tabs/leaderboard/goal_line.dart
+++ b/desktop/lib/super_tabs/leaderboard/goal_line.dart
@@ -1,12 +1,13 @@
import 'package:flutter/material.dart';
+import '../../shared/theme/app_theme.dart' as grid;
import '../../widgets/desktop_chrome.dart';
import 'format.dart';
import 'model.dart';
-/// The shared reward on one line at the top of Humans: what shipped in the
-/// week shown, everyone's points together and the project's open requests.
-/// The week before and the median time to ship are on hover.
+/// The shared reward at the top of Humans: a small "🚀 N shipped" chip for
+/// the week shown (Dee, 2026-10-28: no open count). The week before and the
+/// median time to ship are on hover.
class LeaderboardGoalLine extends StatelessWidget {
const LeaderboardGoalLine({
super.key,
@@ -22,23 +23,27 @@ class LeaderboardGoalLine extends StatelessWidget {
Widget build(BuildContext context) {
final now = goal.thisWeek, before = goal.lastWeek;
final earlier = weekName == 'this week' ? 'last week' : 'the week before';
- final line =
- 'Team goal: ${now.shipped} shipped · ${now.points} pts · ${goal.openRequests} open';
final median = _median(now.medianAskToShipMs, before.medianAskToShipMs);
return Padding(
padding: const EdgeInsets.fromLTRB(16, 0, 16, 4),
- child: Tooltip(
- message: [
- line,
- '${before.shipped} shipped $earlier',
- ?median,
- ].join('\n'),
- child: Text(
- line,
- key: const ValueKey('leaderboard-goal'),
- maxLines: 1,
- overflow: TextOverflow.ellipsis,
- style: DesktopChrome.metadata(),
+ child: Align(
+ alignment: Alignment.centerLeft,
+ child: Tooltip(
+ message: ['${before.shipped} shipped $earlier', ?median].join('\n'),
+ child: Container(
+ key: const ValueKey('leaderboard-goal'),
+ padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
+ decoration: BoxDecoration(
+ color: grid.AppSurface.hoverFill,
+ borderRadius: BorderRadius.circular(10),
+ ),
+ child: Text(
+ '🚀 ${now.shipped} shipped $weekName',
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: DesktopChrome.metadata(color: DesktopChrome.foreground),
+ ),
+ ),
),
),
);
diff --git a/desktop/lib/super_tabs/leaderboard/model.dart b/desktop/lib/super_tabs/leaderboard/model.dart
index f17925161..6f32070ed 100644
--- a/desktop/lib/super_tabs/leaderboard/model.dart
+++ b/desktop/lib/super_tabs/leaderboard/model.dart
@@ -11,6 +11,8 @@ Map<String, dynamic> _map(Object? value) =>
value is Map ? value.cast<String, dynamic>() : const {};
List<Map<String, dynamic>> _list(Object? value) =>
value is List ? value.whereType<Map>().map(_map).toList() : const [];
+String? _text(Object? value) =>
+ value is String && value.isNotEmpty ? value : null;
class SuperTabLeaderboard {
SuperTabLeaderboard.fromJson(Map<String, dynamic> json)
@@ -62,7 +64,12 @@ class SuperTabPersonScore {
medianAnswerMs = _optional(_map(json['unblocked'])['medianAnswerMs']),
lentMachines = _int(_map(json['lent'])['machines']),
lentMs = _int(_map(json['lent'])['agentMs']),
- streakDays = _int(json['streakDays']);
+ streakDays = _int(json['streakDays']),
+ displayName = _text(json['displayName']),
+ prevWeekPoints = _optional(json['prevWeekPoints']),
+ details = json['details'] is Map
+ ? SuperTabPersonDetails.fromJson(_map(json['details']))
+ : null;
final String personId;
final int points, rank;
@@ -72,6 +79,59 @@ class SuperTabPersonScore {
/// Agent time the person's answers freed, and agent time run on their machines.
final int unblockedMs, lentMs;
final int? medianAskToShipMs, medianAnswerMs;
+
+ /// The profile name, else the email's local part; null from a server before names.
+ final String? displayName;
+
+ /// The same scoring for the week before; null from a server before it.
+ final int? prevWeekPoints;
+
+ /// What the numbers are made of; null from a server before details.
+ final SuperTabPersonDetails? details;
+}
+
+/// A person's week item by item, each list newest first and only what the
+/// reader can read. An item without a title is left out.
+class SuperTabPersonDetails {
+ SuperTabPersonDetails.fromJson(Map<String, dynamic> json)
+ : shipped = [
+ for (final item in _list(json['shipped']))
+ if (_text(item['title']) case final title?)
+ (title: title, prUrl: _text(item['prUrl'])),
+ ],
+ unblocked = [
+ for (final item in _list(json['unblocked']))
+ if (_text(item['title']) case final title?)
+ (
+ title: title,
+ conversationId: _text(item['conversationId']),
+ kind: _text(item['kind']),
+ waitedMinutes: _int(item['waitedMinutes']),
+ ),
+ ],
+ lent = [
+ for (final item in _list(json['lent']))
+ if (_text(item['machineName']) case final machineName?)
+ (
+ machineName: machineName,
+ busyHours: item['busyHours'] is num
+ ? (item['busyHours'] as num).toDouble()
+ : 0.0,
+ ),
+ ];
+
+ /// Pull requests that merged.
+ final List<({String title, String? prUrl})> shipped;
+
+ /// Questions answered: decision, approval, needs_human or tag_reply, and
+ /// how long the agent waited.
+ final List<
+ ({String title, String? conversationId, String? kind, int waitedMinutes})
+ >
+ unblocked;
+
+ /// Machines whose agents ran, and for how long.
+ final List<({String machineName, double busyHours})> lent;
}
class SuperTabWaitingPerson {
diff --git a/desktop/lib/super_tabs/leaderboard/person_row.dart b/desktop/lib/super_tabs/leaderboard/person_row.dart
index ad86f71b6..812bdd4e6 100644
--- a/desktop/lib/super_tabs/leaderboard/person_row.dart
+++ b/desktop/lib/super_tabs/leaderboard/person_row.dart
@@ -1,6 +1,9 @@
import 'package:clock/clock.dart';
import 'package:flutter/material.dart';
+import 'package:url_launcher/url_launcher.dart';
+import '../../shared/theme/app_icons.dart';
+import '../../shared/theme/app_theme.dart' as grid;
import '../../widgets/desktop_chrome.dart';
import '../../widgets/finger_target.dart';
import '../identity.dart';
@@ -16,10 +19,37 @@ const _nameInset = 32.0;
TextStyle _figures(TextStyle style) =>
style.copyWith(fontFeatures: const [FontFeature.tabularFigures()]);
-/// One person in the Humans section: avatar, name, status and this week's
-/// points in fixed columns, with Shipped, Unblocked and Lent on a quiet line
-/// beneath. Without a [score] (no board yet, or a server without one) only the
-/// name and status.
+/// A person as the leaderboard names them: the board's display name, else the
+/// email's first part, as before the board had names.
+String leaderboardName(SuperTabPerson person, SuperTabPersonScore? score) =>
+ score?.displayName ?? superTabPersonName(person.email);
+
+/// "Up 6 from last week", "down 7 …"; null when level, or from a server
+/// without last week.
+String? leaderboardTrend(SuperTabPersonScore score) {
+ final before = score.prevWeekPoints;
+ if (before == null || before == score.points) return null;
+ final change = score.points - before;
+ return '${change > 0 ? 'up' : 'down'} ${change.abs()} from last week';
+}
+
+/// The cup's colour and name, by place.
+(Color, String) _cup(SuperTabMedal medal) => switch (medal) {
+ SuperTabMedal.gold => (grid.AppPalette.brandBolt, 'Gold cup: 1st'),
+ SuperTabMedal.silver => (
+ grid.AppTheme.pick(const Color(0xFF6E7681), const Color(0xFFC0C6CF)),
+ 'Silver cup: 2nd',
+ ),
+ SuperTabMedal.bronze => (
+ grid.AppTheme.pick(const Color(0xFF8C5A2B), const Color(0xFFD08A4E)),
+ 'Bronze cup: 3rd',
+ ),
+};
+
+/// One person in the Humans section: avatar, name, status, their cup and
+/// their change against last week, and this week's points in fixed columns,
+/// with Shipped, Unblocked and Lent as icons on a quiet line beneath. Without
+/// a [score] (no board yet, or a server without one) only the name and status.
class LeaderboardPersonRow extends StatelessWidget {
const LeaderboardPersonRow({
super.key,
@@ -36,15 +66,23 @@ class LeaderboardPersonRow extends StatelessWidget {
final scale = MediaQuery.textScalerOf(context);
final score = this.score;
final quiet = _figures(DesktopChrome.metadata());
- Widget cell(double width, String text) => SizedBox(
+ Widget cell(double width, String text, String label) => SizedBox(
width: scale.scale(width),
- child: Text(
- text,
- maxLines: 1,
- overflow: TextOverflow.ellipsis,
- style: quiet,
+ child: Align(
+ alignment: Alignment.centerLeft,
+ child: Tooltip(
+ message: label,
+ child: Text(
+ text,
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: quiet,
+ ),
+ ),
),
);
+ final medal = score?.medal;
+ final trend = score == null ? null : leaderboardTrend(score);
return InkWell(
key: ValueKey('super-person-${person.id}'),
onTap: onTap,
@@ -71,7 +109,7 @@ class LeaderboardPersonRow extends StatelessWidget {
until: person.status?.until,
builder: (context) => Text.rich(
TextSpan(
- text: superTabPersonName(person.email),
+ text: leaderboardName(person, score),
children: [
if (person.statusAt(clock.now())
case final status?)
@@ -88,6 +126,14 @@ class LeaderboardPersonRow extends StatelessWidget {
),
),
),
+ if (medal != null) ...[
+ const SizedBox(width: 6),
+ _Cup(personId: person.id, medal: medal),
+ ],
+ if (trend != null && score != null) ...[
+ const SizedBox(width: 6),
+ _Trend(personId: person.id, score: score, trend: trend),
+ ],
if (score != null)
SizedBox(
width: scale.scale(64),
@@ -105,15 +151,20 @@ class LeaderboardPersonRow extends StatelessWidget {
padding: const EdgeInsets.only(left: _nameInset, top: 2),
child: Row(
children: [
- cell(72, '${score.shipped} shipped'),
- cell(88, '${score.unblocked} unblocked'),
- Expanded(
- child: Text(
- '${leaderboardHours(score.lentMs)} h lent',
- maxLines: 1,
- overflow: TextOverflow.ellipsis,
- style: quiet,
- ),
+ cell(
+ 56,
+ '🚀 ${score.shipped}',
+ '${score.shipped} shipped',
+ ),
+ cell(
+ 56,
+ '🔓 ${score.unblocked}',
+ '${score.unblocked} unblocked',
+ ),
+ cell(
+ 72,
+ '💻 ${leaderboardHours(score.lentMs)} h',
+ '${leaderboardHours(score.lentMs)} agent-hours lent',
),
],
),
@@ -126,14 +177,140 @@ class LeaderboardPersonRow extends StatelessWidget {
}
}
-/// A person's week, shown when their name is tapped: the medians, the time
-/// freed and lent, and their shipping streak.
+/// A top-three cup in its place's colour; #1's sparkles once as the board
+/// opens, never with Reduce Motion.
+class _Cup extends StatelessWidget {
+ const _Cup({required this.personId, required this.medal});
+ final String personId;
+ final SuperTabMedal medal;
+
+ @override
+ Widget build(BuildContext context) {
+ final (color, name) = _cup(medal);
+ final cup = Icon(AppIcons.trophy, size: 14, color: color);
+ return Tooltip(
+ key: ValueKey('leaderboard-cup-$personId'),
+ message: '$name this week',
+ excludeFromSemantics: true,
+ child: Semantics(
+ label: '$name this week',
+ child:
+ medal == SuperTabMedal.gold &&
+ !MediaQuery.disableAnimationsOf(context)
+ ? _Sparkle(color: color, child: cup)
+ : cup,
+ ),
+ );
+ }
+}
+
+/// A light sparkle over [child] that plays once and then is gone.
+class _Sparkle extends StatefulWidget {
+ const _Sparkle({required this.color, required this.child});
+ final Color color;
+ final Widget child;
+
+ @override
+ State<_Sparkle> createState() => _SparkleState();
+}
+
+class _SparkleState extends State<_Sparkle>
+ with SingleTickerProviderStateMixin {
+ late final _controller = AnimationController(
+ vsync: this,
+ duration: const Duration(milliseconds: 1400),
+ )..forward();
+
+ @override
+ void dispose() {
+ _controller.dispose();
+ super.dispose();
+ }
+
+ @override
+ Widget build(BuildContext context) => AnimatedBuilder(
+ animation: _controller,
+ child: widget.child,
+ builder: (context, child) {
+ if (_controller.isCompleted) return child!;
+ // Up and back down: a glint, not a blink.
+ final t = Curves.easeInOut.transform(_controller.value);
+ final glint = 1 - (2 * t - 1).abs();
+ return Stack(
+ clipBehavior: Clip.none,
+ children: [
+ child!,
+ Positioned(
+ right: -7,
+ top: -7,
+ child: Opacity(
+ key: const ValueKey('leaderboard-sparkle'),
+ opacity: glint,
+ child: Transform.scale(
+ scale: .6 + .4 * glint,
+ child: Icon(AppIcons.sparkles, size: 11, color: widget.color),
+ ),
+ ),
+ ),
+ ],
+ );
+ },
+ );
+}
+
+/// An arrow and the change against last week: up in green, down quietly.
+class _Trend extends StatelessWidget {
+ const _Trend({
+ required this.personId,
+ required this.score,
+ required this.trend,
+ });
+ final String personId;
+ final SuperTabPersonScore score;
+ final String trend;
+
+ @override
+ Widget build(BuildContext context) {
+ final up = score.points > score.prevWeekPoints!;
+ final color = up ? grid.AppPalette.online : DesktopChrome.muted;
+ return Tooltip(
+ key: ValueKey('leaderboard-trend-$personId'),
+ message: capitalized(trend),
+ excludeFromSemantics: true,
+ child: Semantics(
+ label: capitalized(trend),
+ excludeSemantics: true,
+ child: Row(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Icon(
+ up ? AppIcons.arrowUp : AppIcons.arrowDown,
+ size: 12,
+ color: color,
+ ),
+ Text(
+ '${(score.points - score.prevWeekPoints!).abs()}',
+ style: _figures(DesktopChrome.metadata(color: color)),
+ ),
+ ],
+ ),
+ ),
+ );
+ }
+}
+
+/// A person's week, shown when their name is tapped: what they shipped, what
+/// they unblocked and what they lent, item by item. From a server without
+/// details, the medians, the time freed and lent, and their shipping streak.
class LeaderboardPersonWeek extends StatelessWidget {
const LeaderboardPersonWeek({super.key, required this.score});
final SuperTabPersonScore score;
@override
Widget build(BuildContext context) {
+ if (score.details case final details?) {
+ return _LeaderboardPersonDetails(score: score, details: details);
+ }
String median(int? ms, String what) =>
ms == null ? '' : ' · median ${leaderboardDuration(ms)}$what';
final rows = [
@@ -195,3 +372,107 @@ class LeaderboardPersonWeek extends StatelessWidget {
);
}
}
+
+/// The three lists behind a person's numbers, each saying so when empty. A
+/// long week scrolls inside the window.
+class _LeaderboardPersonDetails extends StatelessWidget {
+ const _LeaderboardPersonDetails({required this.score, required this.details});
+ final SuperTabPersonScore score;
+ final SuperTabPersonDetails details;
+
+ @override
+ Widget build(BuildContext context) {
+ final trend = leaderboardTrend(score);
+ final quiet = DesktopChrome.metadata();
+ Widget section(String title, String empty, List<Widget> items) => Padding(
+ padding: const EdgeInsets.only(top: 12),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(
+ title,
+ style: DesktopChrome.control(
+ color: DesktopChrome.foreground,
+ medium: true,
+ ),
+ ),
+ const SizedBox(height: 4),
+ if (items.isEmpty) Text(empty, style: quiet) else ...items,
+ ],
+ ),
+ );
+ Widget item(Widget title, String trailing) => Padding(
+ padding: const EdgeInsets.symmetric(vertical: 3),
+ child: Row(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Expanded(child: title),
+ if (trailing.isNotEmpty) ...[
+ const SizedBox(width: 12),
+ Text(trailing, style: _figures(quiet)),
+ ],
+ ],
+ ),
+ );
+ final text = DesktopChrome.control();
+ return ConstrainedBox(
+ constraints: BoxConstraints(
+ maxHeight: MediaQuery.sizeOf(context).height * .5,
+ ),
+ child: SizedBox(
+ width: 380,
+ child: SingleChildScrollView(
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(
+ trend == null
+ ? '${score.points} pts'
+ : '${score.points} pts · $trend',
+ style: quiet,
+ ),
+ section('🚀 Shipped', 'No pull requests merged yet', [
+ for (final shipped in details.shipped)
+ item(switch (Uri.tryParse(shipped.prUrl ?? '')) {
+ // Only a web page opens: a link from the server is data,
+ // and any other scheme could open a file or an app.
+ final link?
+ when const {'http', 'https'}.contains(link.scheme) =>
+ Semantics(
+ link: true,
+ child: InkWell(
+ onTap: () => launchUrl(
+ link,
+ mode: LaunchMode.externalApplication,
+ ),
+ child: Text(
+ shipped.title,
+ style: text.copyWith(color: DesktopChrome.accent),
+ ),
+ ),
+ ),
+ _ => Text(shipped.title, style: text),
+ }, ''),
+ ]),
+ section('🔓 Unblocked', 'No questions answered yet', [
+ for (final unblocked in details.unblocked)
+ item(
+ Text(unblocked.title, style: text),
+ 'waited ${leaderboardDuration(unblocked.waitedMinutes * 60000)}',
+ ),
+ ]),
+ section('💻 Lent', 'No machines lent yet', [
+ for (final lent in details.lent)
+ item(
+ Text(superTabMachineName(lent.machineName), style: text),
+ '${leaderboardDuration((lent.busyHours * 3600000).round())} busy',
+ ),
+ ]),
+ ],
+ ),
+ ),
+ ),
+ );
+ }
+}
diff --git a/desktop/lib/super_tabs/machines.dart b/desktop/lib/super_tabs/machines.dart
index d8816e064..4f9280fe7 100644
--- a/desktop/lib/super_tabs/machines.dart
+++ b/desktop/lib/super_tabs/machines.dart
@@ -39,7 +39,13 @@ export 'machine_status.dart';
/// The backend's upper bound. A machine's own total RAM may set a lower one.
const _agentSlotsMin = 1;
-const _agentSlotsMax = 16;
+const _agentSlotsMax = 1024;
+
+/// Every machine may offer this many, whatever its RAM, and the suggestion
+/// never starts above [_suggestedSlotsMax]: the CLI's own figures
+/// (`prepareContribution`, `cli/src/superTabs/contribution.ts`).
+const _agentSlotsFloor = 4;
+const _suggestedSlotsMax = 16;
/// What one more agent needs to start, the CLI's own figure
/// (`START_REQUIREMENTS.memoryBytes`, `cli/src/superTabs/capacity.ts`).
@@ -49,17 +55,25 @@ int _clampAgentSlots(num value) =>
value.toInt().clamp(_agentSlotsMin, _agentSlotsMax);
/// The machine's total-RAM limit and its half-sized starting suggestion.
-/// The suggestion is capped separately, so 64 GiB suggests 16 of 16 slots.
+/// Every 2 GiB may run an agent and every machine may offer four, with no cap
+/// of 16 (Ken, 2026-10-28: it held a 192 GiB Mac Studio to a sixth of its
+/// room). The suggestion keeps its 16, so 192 GiB suggests 16 of 96 slots.
int? _maxAgentSlots(MachineResources? resources) {
final total = resources?.memoryTotalBytes;
if (total == null) return null;
- return _clampAgentSlots((total / _agentMemoryBytes).floor());
+ final byMemory = (total / _agentMemoryBytes).floor();
+ return _clampAgentSlots(
+ byMemory < _agentSlotsFloor ? _agentSlotsFloor : byMemory,
+ );
}
int? _suggestedAgentSlots(MachineResources? resources) {
final total = resources?.memoryTotalBytes;
if (total == null) return null;
- return _clampAgentSlots((total / (2 * _agentMemoryBytes)).floor());
+ return (total / (2 * _agentMemoryBytes)).floor().clamp(
+ _agentSlotsMin,
+ _suggestedSlotsMax,
+ );
}
class SuperTabMachines extends StatefulWidget {
diff --git a/desktop/lib/super_tabs/project_sidebar.dart b/desktop/lib/super_tabs/project_sidebar.dart
index 098291f6f..a51273f94 100644
--- a/desktop/lib/super_tabs/project_sidebar.dart
+++ b/desktop/lib/super_tabs/project_sidebar.dart
@@ -1,6 +1,8 @@
import 'dart:async';
+import 'package:collection/collection.dart' show mergeSort;
import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
import '../core/machine_resources.dart';
import '../shared/theme/app_icons.dart';
@@ -155,8 +157,8 @@ class ProjectSidebar extends StatelessWidget {
? onOpenPmChat!(projectId)
: unawaited(controller.openPmChat(projectId));
- /// A project row opens the project's chat and shows its workgroups; clicked
- /// again while open, it hides them. It has no chevron (Dee, 2026-10-27).
+ /// A project row's name opens the project's chat; only the chevron at its
+ /// right end shows or hides its conversations (Dee, 2026-10-28).
Widget _row(
SuperTabConversation group, {
SuperTabProject? project,
@@ -182,127 +184,213 @@ class ProjectSidebar extends StatelessWidget {
);
final expanded =
project != null && controller.expandedProjects.contains(project.id);
+ // A collapsed project shows as selected while one of its conversations it
+ // hides is open; its Chat with PM has a row of its own.
+ final highlighted =
+ selected ||
+ (project != null &&
+ !expanded &&
+ !devicesSelected &&
+ !notificationsSelected &&
+ controller.selected?.projectId == project.id &&
+ controller.selectedId != pmChat?.id);
final style = DesktopChrome.control(
- medium: unread || selected,
- color: selected || unread || project != null || label != null
+ medium: unread || highlighted,
+ color: highlighted || unread || project != null || label != null
? DesktopChrome.foreground
: DesktopChrome.muted,
);
return Padding(
padding: const EdgeInsets.only(bottom: 2),
child: Material(
- color: selected ? grid.AppSurface.selectedFill : Colors.transparent,
+ color: highlighted ? grid.AppSurface.selectedFill : Colors.transparent,
borderRadius: BorderRadius.circular(DesktopChrome.rowRadius),
clipBehavior: Clip.antiAlias,
- child: InkWell(
- key: ValueKey(key ?? 'super-group-${group.id}'),
- onTap: project == null
- ? () => onSelect(group.id)
- : () {
- if (selected || !expanded) {
- controller.toggleProject(project.id);
- }
- if (!selected) onSelect(group.id);
- },
- hoverColor: grid.AppSurface.hoverFill,
- focusColor: grid.AppSurface.hoverFill,
- borderRadius: BorderRadius.circular(DesktopChrome.rowRadius),
- child: Row(
- children: [
- SizedBox(width: SuperTabSectionHeading.indentFor(0)),
- SizedBox(
- width: _iconColumn,
- child: project != null || label != null ? _channelMark() : null,
- ),
- Expanded(
- child: Semantics(
- label: project?.isPrivate == true ? 'Private project' : null,
- selected: selected,
- expanded: project == null ? null : expanded,
- child: Tooltip(
- message:
- label ??
- project?.name ??
- SuperTabWorkgroupName.plain(group),
- child: ConstrainedBox(
- constraints: const BoxConstraints(minHeight: 36),
- child: Padding(
- padding: const EdgeInsets.symmetric(vertical: 8),
- child: Row(
- children: [
- Expanded(
- child: label == null && project == null
- ? SuperTabWorkgroupName(group, style: style)
- : Text(
- label ?? project!.name,
- maxLines: 1,
- overflow: TextOverflow.ellipsis,
- style: style,
+ // The chevron stands beside the row's own click, not inside it: the
+ // name opens and the chevron toggles.
+ child: Row(
+ children: [
+ Expanded(
+ child: _arrowToggles(
+ project,
+ expanded: expanded,
+ child: InkWell(
+ key: ValueKey(key ?? 'super-group-${group.id}'),
+ onTap: () => onSelect(group.id),
+ hoverColor: grid.AppSurface.hoverFill,
+ focusColor: grid.AppSurface.hoverFill,
+ borderRadius: BorderRadius.circular(DesktopChrome.rowRadius),
+ child: Row(
+ children: [
+ SizedBox(width: SuperTabSectionHeading.indentFor(0)),
+ SizedBox(
+ width: _iconColumn,
+ child: project != null || label != null
+ ? _channelMark()
+ : null,
+ ),
+ Expanded(
+ child: Semantics(
+ label: project?.isPrivate == true
+ ? 'Private project'
+ : null,
+ selected: selected,
+ child: Tooltip(
+ message:
+ label ??
+ project?.name ??
+ SuperTabWorkgroupName.plain(group),
+ child: ConstrainedBox(
+ constraints: const BoxConstraints(minHeight: 36),
+ child: Padding(
+ padding: const EdgeInsets.symmetric(
+ vertical: 8,
+ ),
+ child: Row(
+ children: [
+ Expanded(
+ child: label == null && project == null
+ ? SuperTabWorkgroupName(
+ group,
+ style: style,
+ )
+ : Text(
+ label ?? project!.name,
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: style,
+ ),
),
- ),
- if (project?.isPrivate == true) ...[
- const SizedBox(width: 8),
- Tooltip(
- message: 'Private project',
- child: Icon(
- AppIcons.lock,
- size: 14,
- color: DesktopChrome.muted,
+ if (project?.isPrivate == true) ...[
+ const SizedBox(width: 8),
+ Tooltip(
+ message: 'Private project',
+ child: Icon(
+ AppIcons.lock,
+ size: 14,
+ color: DesktopChrome.muted,
+ ),
+ ),
+ ],
+ ],
),
),
- ],
- ],
- ),
- ),
- ),
- ),
- ),
- ),
- if (projectPmUnread > 0)
- Padding(
- padding: const EdgeInsets.only(left: 4),
- child: SuperTabPmUnread(
- projectPmUnread,
- key: ValueKey('super-project-pm-unread-${project!.id}'),
- onTap: () => _openPmChat(project.id),
- ),
- ),
- SizedBox(
- width: _iconColumn,
- child: Center(
- child: waiting
- ? Tooltip(
- message: 'Needs a human',
- child: Text(
- '?',
- style: DesktopChrome.control(
- color: grid.AppPalette.warn,
- medium: true,
),
),
- )
- : unread
- ? Semantics(
- label: 'Unread messages',
- child: Container(
- width: _dotSize,
- height: _dotSize,
- decoration: BoxDecoration(
- shape: BoxShape.circle,
- color: DesktopChrome.accent,
+ ),
+ ),
+ if (projectPmUnread > 0)
+ Padding(
+ padding: const EdgeInsets.only(left: 4),
+ child: SuperTabPmUnread(
+ projectPmUnread,
+ key: ValueKey(
+ 'super-project-pm-unread-${project!.id}',
),
+ onTap: () => _openPmChat(project.id),
),
- )
- : null,
+ ),
+ SizedBox(
+ width: _iconColumn,
+ child: Center(
+ child: waiting
+ ? Tooltip(
+ message: 'Needs a human',
+ child: Text(
+ '?',
+ style: DesktopChrome.control(
+ color: grid.AppPalette.warn,
+ medium: true,
+ ),
+ ),
+ )
+ : unread
+ ? Semantics(
+ label: 'Unread messages',
+ child: Container(
+ width: _dotSize,
+ height: _dotSize,
+ decoration: BoxDecoration(
+ shape: BoxShape.circle,
+ color: DesktopChrome.accent,
+ ),
+ ),
+ )
+ : null,
+ ),
+ ),
+ ],
+ ),
),
),
- ],
- ),
+ ),
+ // At the far right edge, since it is always there and the dot
+ // beside it comes and goes (Dee, 2026-10-28).
+ if (project != null) _toggle(project, expanded: expanded),
+ ],
),
),
);
}
+ /// On a focused project name, → shows its conversations and ← hides them.
+ /// An arrow that would change nothing moves focus as it does elsewhere.
+ Widget _arrowToggles(
+ SuperTabProject? project, {
+ required bool expanded,
+ required Widget child,
+ }) => project == null
+ ? child
+ : Focus(
+ canRequestFocus: false,
+ skipTraversal: true,
+ onKeyEvent: (node, event) {
+ final keyboard = HardwareKeyboard.instance;
+ final toggles =
+ event is! KeyUpEvent &&
+ !keyboard.isShiftPressed &&
+ !keyboard.isControlPressed &&
+ !keyboard.isAltPressed &&
+ !keyboard.isMetaPressed &&
+ (event.logicalKey == LogicalKeyboardKey.arrowRight
+ ? !expanded
+ : event.logicalKey == LogicalKeyboardKey.arrowLeft &&
+ expanded);
+ if (!toggles) return KeyEventResult.ignored;
+ controller.toggleProject(project.id);
+ return KeyEventResult.handled;
+ },
+ child: child,
+ );
+
+ /// The chevron that shows or hides a project's conversations: '>' while
+ /// they are hidden, 'v' while shown. Focused, Enter or Space toggles it; on
+ /// the focused name, → shows them and ← hides them.
+ Widget _toggle(SuperTabProject project, {required bool expanded}) =>
+ Semantics(
+ button: true,
+ expanded: expanded,
+ child: InkWell(
+ key: ValueKey('super-project-toggle-${project.id}'),
+ onTap: () => controller.toggleProject(project.id),
+ hoverColor: grid.AppSurface.hoverFill,
+ focusColor: grid.AppSurface.hoverFill,
+ borderRadius: BorderRadius.circular(DesktopChrome.rowRadius),
+ child: Tooltip(
+ message: expanded ? 'Hide conversations' : 'Show conversations',
+ child: SizedBox(
+ width: _iconColumn,
+ height: 36,
+ child: Icon(
+ expanded ? AppIcons.chevronDown : AppIcons.chevronRight,
+ size: AppIcons.inlineSize,
+ color: DesktopChrome.muted,
+ ),
+ ),
+ ),
+ ),
+ );
+
/// A project's "Closed (N)" row and, when it is open, the closed groups under it: archived ones and finished
/// ones that left the active set, as read for the project so far.
List<Widget> _closed(SuperTabProject project) {
@@ -419,15 +507,72 @@ class ProjectSidebar extends StatelessWidget {
);
}
- List<Widget> _workgroups(SuperTabProject project) {
+ /// A project's open conversations, newest first: the most recently created
+ /// has the highest number, and one without a number predates numbering.
+ List<SuperTabConversation> _newestFirst(SuperTabProject project) {
final pmChat = controller.pmChat(project.id)?.id;
- final groups = controller.snapshot!.conversations.where(
- (g) =>
- g.projectId == project.id &&
- g.id != project.leadConversationId &&
- g.id != pmChat &&
- !g.closed,
+ final groups = controller.snapshot!.conversations
+ .where(
+ (g) =>
+ g.projectId == project.id &&
+ g.id != project.leadConversationId &&
+ g.id != pmChat &&
+ !g.closed,
+ )
+ .toList();
+ // A stable sort keeps the backend's order among unnumbered ones.
+ mergeSort(
+ groups,
+ compare: (a, b) => (b.number ?? 0).compareTo(a.number ?? 0),
);
+ return groups;
+ }
+
+ /// The "… N more" row under a project's newest conversations.
+ Widget _moreRow(SuperTabProject project, int hidden, VoidCallback onTap) =>
+ Padding(
+ padding: const EdgeInsets.only(bottom: 2),
+ child: Material(
+ color: Colors.transparent,
+ borderRadius: BorderRadius.circular(DesktopChrome.rowRadius),
+ clipBehavior: Clip.antiAlias,
+ child: Semantics(
+ button: true,
+ child: InkWell(
+ key: ValueKey('super-project-more-${project.id}'),
+ onTap: onTap,
+ hoverColor: grid.AppSurface.hoverFill,
+ focusColor: grid.AppSurface.hoverFill,
+ borderRadius: BorderRadius.circular(DesktopChrome.rowRadius),
+ child: Row(
+ children: [
+ SizedBox(width: SuperTabSectionHeading.indentFor(0)),
+ const SizedBox(width: _iconColumn),
+ Expanded(
+ child: ConstrainedBox(
+ constraints: const BoxConstraints(minHeight: 36),
+ child: Align(
+ alignment: Alignment.centerLeft,
+ child: Text(
+ '… $hidden more',
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: DesktopChrome.control(
+ color: DesktopChrome.muted,
+ ),
+ ),
+ ),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ),
+ );
+
+ List<Widget> _workgroups(SuperTabProject project) {
+ final groups = _newestFirst(project);
return groups.isEmpty
? [
Padding(
@@ -446,7 +591,22 @@ class ProjectSidebar extends StatelessWidget {
),
),
]
- : [for (final group in groups) _row(group)];
+ : [
+ _NewestConversations(
+ key: ValueKey('super-project-list-${project.id}'),
+ rows: [for (final group in groups) (group.id, _row(group))],
+ // Never behind "… N more": the open one, and those with
+ // something to read or answer.
+ kept: {
+ if (!devicesSelected && !notificationsSelected)
+ controller.selectedId,
+ for (final group in groups)
+ if (controller.unread(group) || needsHuman(group) > 0)
+ group.id,
+ },
+ more: (hidden, onTap) => _moreRow(project, hidden, onTap),
+ ),
+ ];
}
/// Every project with its workgroups, and the Product Managers'
@@ -460,6 +620,7 @@ class ProjectSidebar extends StatelessWidget {
(
project.name,
Column(
+ key: ValueKey('super-project-${project.id}'),
mainAxisSize: MainAxisSize.min,
children: [
_row(lead, project: project),
@@ -574,3 +735,56 @@ class ProjectSidebar extends StatelessWidget {
);
}
}
+
+/// A project's open conversations, newest first: the first
+/// [_NewestConversations.shown] and the [_NewestConversations.kept] ones, then
+/// a "… N more" row that shows the rest. Showing the rest lasts until the
+/// project is collapsed.
+class _NewestConversations extends StatefulWidget {
+ const _NewestConversations({
+ super.key,
+ required this.rows,
+ required this.kept,
+ required this.more,
+ });
+
+ static const shown = 8;
+
+ /// Each conversation's id and row, newest first.
+ final List<(String, Widget)> rows;
+
+ /// Listed even when older than the newest.
+ final Set<String> kept;
+ final Widget Function(int hidden, VoidCallback onTap) more;
+
+ @override
+ State<_NewestConversations> createState() => _NewestConversationsState();
+}
+
+class _NewestConversationsState extends State<_NewestConversations> {
+ bool _all = false;
+
+ @override
+ Widget build(BuildContext context) {
+ final rows = widget.rows;
+ final visible = _all || rows.length <= _NewestConversations.shown
+ ? rows
+ : [
+ for (final (index, row) in rows.indexed)
+ if (index < _NewestConversations.shown ||
+ widget.kept.contains(row.$1))
+ row,
+ ];
+ return Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ for (final (_, row) in visible) row,
+ if (visible.length < rows.length)
+ widget.more(
+ rows.length - visible.length,
+ () => setState(() => _all = true),
+ ),
+ ],
+ );
+ }
+}
diff --git a/desktop/lib/super_tabs/pull_requests.dart b/desktop/lib/super_tabs/pull_requests.dart
index afd856101..bcf3ab29e 100644
--- a/desktop/lib/super_tabs/pull_requests.dart
+++ b/desktop/lib/super_tabs/pull_requests.dart
@@ -270,6 +270,7 @@ class _SuperTabPullRequestsState extends State<SuperTabPullRequests> {
}
}
_unsupported = unsupported;
+ if (!unsupported) _localUnavailable = false;
if (error == 'GH_MISSING' || error == 'GH_SIGNED_OUT') {
// A changed login must not leave yesterday's private titles under today's account.
_entries.clear();
diff --git a/desktop/lib/super_tabs/roster.dart b/desktop/lib/super_tabs/roster.dart
index 7572993bb..62ec526a8 100644
--- a/desktop/lib/super_tabs/roster.dart
+++ b/desktop/lib/super_tabs/roster.dart
@@ -247,7 +247,7 @@ class _SuperTabRosterState extends State<SuperTabRoster> {
showAppDialog<void>(
context: context,
builder: (context) => AlertDialog(
- title: Text(superTabPersonName(person.email)),
+ title: Text(leaderboardName(person, score)),
content: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
@@ -574,7 +574,7 @@ class _SuperTabRosterState extends State<SuperTabRoster> {
final person = state?.people.where((p) => p.id == id).firstOrNull;
return person == null
? 'Former member'
- : superTabPersonName(person.email);
+ : leaderboardName(person, scores[id]);
},
onAnswer: widget.onAnswer,
),
diff --git a/desktop/test/cli_login_test.dart b/desktop/test/cli_login_test.dart
index 30a3fafe4..9f153be87 100644
--- a/desktop/test/cli_login_test.dart
+++ b/desktop/test/cli_login_test.dart
@@ -4,6 +4,7 @@ import 'dart:io';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/auth/cli_login.dart';
+import 'package:harness/auth/sign_in_client.dart';
import 'package:harness/auth/sign_in_provider.dart';
import 'package:harness/core/harness_cli_runner.dart';
@@ -277,6 +278,56 @@ void main() {
},
);
+ test(
+ 'a coded CLI refusal reaches the app with its code and sentence',
+ () async {
+ final runner = _Runner();
+ final cli = CliLogin(runner: runner);
+ final login = cli.login(onAuthorizeUrl: (_) {});
+ final process = _Process();
+ runner.starts.single.complete(process);
+ process.emit({
+ 'type': 'result',
+ 'status': 'error',
+ 'code': 'TIMEOUT',
+ 'message': 'SSO login timed out',
+ });
+ process.finish(1);
+ await expectLater(
+ login,
+ throwsA(
+ isA<SignInException>()
+ .having((e) => e.code, 'code', 'TIMEOUT')
+ .having((e) => e.toString(), 'sentence', 'SSO login timed out'),
+ ),
+ );
+ },
+ );
+
+ test(
+ 'a CLI that ends without a result line is reported as no result',
+ () async {
+ final runner = _Runner();
+ final cli = CliLogin(runner: runner);
+ final login = cli.login(onAuthorizeUrl: (_) {});
+ final process = _Process();
+ runner.starts.single.complete(process);
+ process.finish(1);
+ await expectLater(
+ login,
+ throwsA(
+ isA<SignInException>()
+ .having((e) => e.code, 'code', 'NO_RESULT')
+ .having(
+ (e) => e.toString(),
+ 'sentence',
+ 'Sign-in was cancelled.',
+ ),
+ ),
+ );
+ },
+ );
+
group('CliAuthStatus.fromJson', () {
test('parses a full logged-in payload', () {
final status = CliAuthStatus.fromJson({
diff --git a/desktop/test/product_measurement_test.dart b/desktop/test/product_measurement_test.dart
index bb43a72f1..89766e898 100644
--- a/desktop/test/product_measurement_test.dart
+++ b/desktop/test/product_measurement_test.dart
@@ -77,6 +77,47 @@ void main() {
});
},
);
+ test(
+ 'why a sign-in did not go through is a signed-out setup count',
+ () async {
+ usage.begin(ProductFlow.signIn)(ProductOutcome.failed);
+ usage.signInEnded(SignInEndReason.noResult);
+ await usage.flush();
+ expect(setup.single['counters'], {
+ 'setup_desktop_sign_in_started': 1,
+ 'setup_desktop_sign_in_failed': 1,
+ 'setup_desktop_sign_in_under_1s': 1,
+ 'setup_desktop_sign_in_reason_no_result': 1,
+ });
+ },
+ );
+ test('a signed-in report carries no sign-in reason', () async {
+ await account();
+ usage.signInEnded(SignInEndReason.timeout);
+ await usage.flush();
+ expect(setup, isEmpty);
+ expect(
+ reports.expand((r) => (r['counters'] as Map? ?? {}).keys),
+ isNot(contains(startsWith('setup_desktop_sign_in_reason'))),
+ );
+ });
+ test('the phone and the browser count no sign-in reason', () async {
+ for (final surface in ['phone', 'web']) {
+ final other = ProductMeasurement(
+ surface: surface,
+ automatic: false,
+ now: () => now,
+ sendSetup: (r) async {
+ setup.add(jsonDecode(jsonEncode(r)));
+ return {'accepted': true};
+ },
+ );
+ other.signInEnded(SignInEndReason.timeout);
+ await other.flush();
+ other.dispose();
+ }
+ expect(setup, isEmpty);
+ });
test('UTC-day counts survive before local midnight', () async {
now = DateTime.utc(2026, 10, 19, 4);
usage.begin(ProductFlow.signIn)(ProductOutcome.ok);
diff --git a/desktop/test/sign_in_measurement_test.dart b/desktop/test/sign_in_measurement_test.dart
new file mode 100644
index 000000000..772bd9914
--- /dev/null
+++ b/desktop/test/sign_in_measurement_test.dart
@@ -0,0 +1,239 @@
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/auth/auth_session.dart';
+import 'package:harness/auth/cli_login.dart';
+import 'package:harness/auth/phone_sign_in.dart';
+import 'package:harness/auth/sign_in_client.dart';
+import 'package:harness/auth/sign_in_provider.dart';
+import 'package:harness/core/config.dart';
+import 'package:harness/measurement/product_measurement.dart';
+import 'package:harness/state/app_state.dart';
+import 'package:harness/state/pane_layout_store.dart';
+
+import 'support/memory_key_value_store.dart';
+
+/// A sign-in the test ends by hand. Never runs the real CLI: a real `harness login` or `logout`
+/// here would sign this computer's own CLI in or out.
+class _Cli extends CliLogin {
+ final attempts = <Completer<void>>[];
+
+ @override
+ Future<void> login({
+ required void Function(String) onAuthorizeUrl,
+ SignInProvider? provider,
+ }) {
+ final attempt = Completer<void>();
+ attempts.add(attempt);
+ return attempt.future;
+ }
+
+ @override
+ Future<void> loginWithPhone({
+ required void Function(String link, int expiresIn) onQr,
+ required Future<bool> Function(String email) onConfirm,
+ }) {
+ final attempt = Completer<void>();
+ attempts.add(attempt);
+ return attempt.future;
+ }
+
+ /// What the real one does to the attempt it stops: the process is killed and its wait throws.
+ @override
+ void cancel() {
+ for (final attempt in attempts) {
+ if (!attempt.isCompleted) {
+ attempt.completeError(StateError('Sign-in was cancelled.'));
+ }
+ }
+ }
+}
+
+/// The sign-in flow's ends as they would be counted: the first outcome of each observation, and
+/// each reason a sign-in that did not go through gave.
+class _Recorder extends ProductMeasurement {
+ _Recorder()
+ : super(surface: 'desktop', automatic: false, sendSetup: (_) async => {});
+
+ final ended = <String>[];
+ final reasons = <SignInEndReason>[];
+
+ @override
+ void Function(ProductOutcome) begin(ProductFlow flow) {
+ var done = false;
+ return (outcome) {
+ if (done || flow != ProductFlow.signIn) return;
+ done = true;
+ ended.add(outcome.name);
+ };
+ }
+
+ @override
+ void signInEnded(SignInEndReason reason) => reasons.add(reason);
+}
+
+/// Signed in, then the saved workspace cannot be read back.
+class _UnreadableLayout extends MemoryKeyValueStore {
+ @override
+ Future<String?> read(String key) async => throw StateError('disk gone');
+}
+
+AppNotifier _bootstrapFails(_Cli cli, _Recorder usage) => AppNotifier(
+ config: AppConfig.dev,
+ authSession: AuthSession(),
+ configStore: null,
+ cliLogin: cli,
+ productMeasurement: usage,
+ paneLayoutStore: PaneLayoutStore(storage: _UnreadableLayout()),
+)..status = AppStatus.unauthenticated;
+
+AppNotifier _app(_Cli cli, _Recorder usage) => AppNotifier(
+ config: AppConfig.dev,
+ authSession: AuthSession(),
+ configStore: null,
+ cliLogin: cli,
+ productMeasurement: usage,
+)..status = AppStatus.unauthenticated;
+
+Future<_Recorder> _browserSignInEnding(Object error) async {
+ final cli = _Cli(), usage = _Recorder();
+ final app = _app(cli, usage);
+ final login = app.login(SignInProvider.google);
+ await pumpEventQueue();
+ cli.attempts.single.completeError(error);
+ await login;
+ app.dispose();
+ return usage;
+}
+
+Future<_Recorder> _phoneSignInEnding(Object error) async {
+ final cli = _Cli(), usage = _Recorder();
+ final app = _app(cli, usage);
+ final login = app.loginWithPhone();
+ await pumpEventQueue();
+ cli.attempts.single.completeError(error);
+ await login;
+ app.dispose();
+ return usage;
+}
+
+void main() {
+ test(
+ 'Cancel during a browser sign-in counts as cancelled, not failed',
+ () async {
+ final cli = _Cli(), usage = _Recorder();
+ final app = _app(cli, usage);
+ final login = app.login(SignInProvider.google);
+ await pumpEventQueue();
+ app.cancelLogin();
+ await login;
+ app.dispose();
+ expect(usage.ended, ['cancelled']);
+ expect(usage.reasons, [SignInEndReason.cancelled]);
+ },
+ );
+
+ test(
+ 'switching to the other button cancels the first sign-in, not fails it',
+ () async {
+ final cli = _Cli(), usage = _Recorder();
+ final app = _app(cli, usage);
+ unawaited(app.signInFromStep(SignInProvider.google));
+ await pumpEventQueue();
+ unawaited(app.signInFromStep(SignInProvider.apple));
+ await pumpEventQueue();
+ expect(usage.ended, ['cancelled']);
+ expect(cli.attempts, hasLength(2));
+ app.cancelLogin();
+ await pumpEventQueue();
+ app.dispose();
+ },
+ );
+
+ test(
+ 'a browser page that never came back is unknown, with its reason',
+ () async {
+ // The person may have left, or finished in the browser and the callback never arrived.
+ final usage = await _browserSignInEnding(
+ const SignInException('TIMEOUT', 'SSO login timed out'),
+ );
+ expect(usage.ended, ['unknown']);
+ expect(usage.reasons, [SignInEndReason.timeout]);
+ },
+ );
+
+ test('the CLI stopping a sign-in its app left counts as cancelled', () async {
+ final usage = await _browserSignInEnding(
+ const SignInException('CANCELLED', 'Sign-in was cancelled.'),
+ );
+ expect(usage.ended, ['cancelled']);
+ expect(usage.reasons, [SignInEndReason.cancelled]);
+ });
+
+ final failures = {
+ const SignInException('EXCHANGE_FAILED', 'invalid_grant'):
+ SignInEndReason.exchangeFailed,
+ const SignInException('CALLBACK_ERROR', 'SSO login failed: x'):
+ SignInEndReason.callbackError,
+ const SignInException('BACKEND_ERROR', 'down'):
+ SignInEndReason.backendError,
+ const SignInException('DAEMON_BUSY', 'busy'): SignInEndReason.daemonBusy,
+ const SignInException('NO_RESULT', 'Sign-in did not complete.'):
+ SignInEndReason.noResult,
+ const SignInException('SOMETHING_NEW', 'new'): SignInEndReason.other,
+ CliNotAvailableException('no harness'): SignInEndReason.cliUnavailable,
+ StateError('anything else'): SignInEndReason.other,
+ };
+ failures.forEach((error, reason) {
+ test(
+ 'a browser sign-in that broke ($error) counts as failed, by its reason',
+ () async {
+ final usage = await _browserSignInEnding(error);
+ expect(usage.ended, ['failed']);
+ expect(usage.reasons, [reason]);
+ },
+ );
+ });
+
+ test(
+ 'a sign-in that went through stays ok when opening the workspace fails',
+ () async {
+ final cli = _Cli(), usage = _Recorder();
+ final app = _bootstrapFails(cli, usage);
+ final login = app.login(SignInProvider.google);
+ await pumpEventQueue();
+ cli.attempts.single.complete();
+ await login;
+ app.dispose();
+ expect(usage.ended, ['ok']);
+ expect(usage.reasons, isEmpty);
+ },
+ );
+
+ test('Cancel during a phone sign-in counts as cancelled', () async {
+ final cli = _Cli(), usage = _Recorder();
+ final app = _app(cli, usage);
+ final login = app.loginWithPhone();
+ await pumpEventQueue();
+ app.cancelLogin();
+ await login;
+ app.dispose();
+ expect(usage.ended, ['cancelled']);
+ expect(usage.reasons, [SignInEndReason.cancelled]);
+ });
+
+ final phoneEnds = {
+ 'DENIED': ('cancelled', SignInEndReason.denied),
+ 'CANCELLED': ('cancelled', SignInEndReason.cancelled),
+ 'EXPIRED': ('unknown', SignInEndReason.expired),
+ 'BACKEND_ERROR': ('failed', SignInEndReason.backendError),
+ 'CLI_TOO_OLD': ('failed', SignInEndReason.cliTooOld),
+ };
+ phoneEnds.forEach((code, end) {
+ test('a phone sign-in ended $code counts as ${end.$1}', () async {
+ final usage = await _phoneSignInEnding(PhoneSignInException(code, 'x'));
+ expect(usage.ended, [end.$1]);
+ expect(usage.reasons, [end.$2]);
+ });
+ });
+}
diff --git a/desktop/test/store_controller_test.dart b/desktop/test/store_controller_test.dart
index c4755845d..ca3e9dcd8 100644
--- a/desktop/test/store_controller_test.dart
+++ b/desktop/test/store_controller_test.dart
@@ -511,6 +511,49 @@ void main() {
expect(store.reviews['autonomous/marp']!.mine!.id, 'mine');
expect(store.reviewsLoading, isEmpty);
});
+
+ test('remove re-reads reviews while a load is pending', () async {
+ final api = _Held();
+ final store = StoreController(api);
+ addTearDown(store.dispose);
+ final opened = store.loadReviews('autonomous/marp');
+
+ final removed = store.remove('autonomous/marp');
+ await pumpEventQueue();
+ // Asked before the delete, the first read still has the review.
+ api.reads.first.complete(api.page(mine: api.posted));
+ await pumpEventQueue();
+ expect(api.reads, hasLength(2), reason: 'the delete is read back');
+ expect(store.reviews['autonomous/marp'], isNull);
+
+ api.reads.last.complete(api.page());
+ expect(await removed, isNull);
+ await opened;
+ expect(store.reviews['autonomous/marp']!.mine, isNull);
+ expect(store.reviewsLoading, isEmpty);
+ });
+
+ test(
+ 'a failed read from before the post gives way to the read-back',
+ () async {
+ final api = _Held();
+ final store = StoreController(api);
+ addTearDown(store.dispose);
+ final opened = store.loadReviews('autonomous/marp');
+
+ final posted = store.submit('autonomous/marp', rating: 5);
+ await pumpEventQueue();
+ api.reads.first.completeError(StateError('socket closed'));
+ await pumpEventQueue();
+ expect(api.reads, hasLength(2), reason: 'a failure is no read-back');
+
+ api.reads.last.complete(api.page(mine: api.posted));
+ expect(await posted, isNull);
+ await opened;
+ expect(store.reviewsError, isEmpty);
+ expect(store.reviews['autonomous/marp']!.mine!.id, 'mine');
+ },
+ );
});
}
diff --git a/desktop/test/super_tab_chat_test.dart b/desktop/test/super_tab_chat_test.dart
index 5312bb9e7..adb0fa368 100644
--- a/desktop/test/super_tab_chat_test.dart
+++ b/desktop/test/super_tab_chat_test.dart
@@ -324,7 +324,7 @@ void main() {
);
expect(c.unread(c.selected!), isFalse);
expect(projectDot(), findsOneWidget);
- await tester.tap(find.byKey(const ValueKey('super-group-lead')));
+ await tester.tap(find.byKey(const ValueKey('super-project-toggle-lead')));
await tester.pumpAndSettle();
await tester.tap(find.byKey(const ValueKey('super-group-offline')));
await tester.pumpAndSettle();
diff --git a/desktop/test/super_tab_closed_groups_test.dart b/desktop/test/super_tab_closed_groups_test.dart
index 5d91ad55d..decd8f44e 100644
--- a/desktop/test/super_tab_closed_groups_test.dart
+++ b/desktop/test/super_tab_closed_groups_test.dart
@@ -107,7 +107,9 @@ void main() {
final sidebar = find.byType(ProjectSidebar);
Finder inside(Finder f) => find.descendant(of: sidebar, matching: f);
if (closedRow.evaluate().isEmpty) {
- await tester.tap(find.byKey(const ValueKey('super-group-lead')));
+ await tester.tap(
+ find.byKey(const ValueKey('super-project-toggle-lead')),
+ );
await tester.pumpAndSettle();
}
@@ -186,7 +188,9 @@ void main() {
await tester.pumpWidget(_app(server, controller));
await tester.pumpAndSettle();
if (closedRow.evaluate().isEmpty) {
- await tester.tap(find.byKey(const ValueKey('super-group-lead')));
+ await tester.tap(
+ find.byKey(const ValueKey('super-project-toggle-lead')),
+ );
await tester.pumpAndSettle();
}
expect(find.text('Closed (1)'), findsOneWidget);
diff --git a/desktop/test/super_tab_humans_test.dart b/desktop/test/super_tab_humans_test.dart
index f44d2db4d..197b82e0a 100644
--- a/desktop/test/super_tab_humans_test.dart
+++ b/desktop/test/super_tab_humans_test.dart
@@ -1,4 +1,5 @@
import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/shared/theme/app_theme.dart' as grid;
import 'package:harness/super_tabs/controller.dart';
@@ -8,9 +9,11 @@ import 'support/humans_fixture.dart';
import 'support/super_tab_fixture.dart';
/// The leaderboard lives in the right pane's Humans section (Dee, 2026-10-27):
-/// the team goal on one line with a small week picker, then everyone, most
-/// points first, each one aligned row with a quiet line of their three numbers.
-/// There is no separate leaderboard view.
+/// a small "🚀 N shipped" chip with a small week picker, then everyone, most
+/// points first, by display name, each one aligned row with a quiet line of
+/// their three numbers as icons. The top three have cups, #1 a sparkle as the
+/// board opens, and each an arrow against last week; a tap shows what the
+/// numbers are made of (Dee, 2026-10-28). There is no separate leaderboard view.
void main() {
Finder person(String id) => find.byKey(ValueKey('super-person-$id'));
@@ -18,6 +21,8 @@ void main() {
WidgetTester tester,
ConversationServer server, {
Size size = const Size(1300, 900),
+ bool settle = true,
+ bool reduceMotion = false,
}) async {
await tester.binding.setSurfaceSize(size);
addTearDown(() => tester.binding.setSurfaceSize(null));
@@ -29,6 +34,11 @@ void main() {
await tester.pumpWidget(
MaterialApp(
theme: grid.buildAppTheme(brightness: Brightness.light),
+ builder: (context, child) => MediaQuery(
+ data: MediaQuery.of(context)
+ .copyWith(disableAnimations: reduceMotion),
+ child: child!,
+ ),
home: Scaffold(
body: SuperTabView(
controller: controller,
@@ -40,7 +50,14 @@ void main() {
),
),
);
- await tester.pumpAndSettle();
+ if (settle) {
+ await tester.pumpAndSettle();
+ } else {
+ // The board's read lands; the rows' first frame.
+ for (var i = 0; i < 5; i++) {
+ await tester.pump();
+ }
+ }
return controller;
}
@@ -79,23 +96,27 @@ void main() {
Finder within(String id, String text) =>
find.descendant(of: person(id), matching: find.text(text));
expect(within('peer', '21 pts'), findsOneWidget);
- expect(within('peer', '6 shipped'), findsOneWidget);
- expect(within('peer', '3 unblocked'), findsOneWidget);
- expect(within('peer', '0 h lent'), findsOneWidget);
+ expect(within('peer', '🚀 6'), findsOneWidget);
+ expect(within('peer', '🔓 3'), findsOneWidget);
+ expect(within('peer', '💻 0 h'), findsOneWidget);
expect(within('owner', '13 pts'), findsOneWidget);
- expect(within('owner', '20 h lent'), findsOneWidget);
+ expect(within('owner', '💻 20 h'), findsOneWidget);
+ // Each icon says what it counts on hover.
+ expect(find.byTooltip('6 shipped'), findsOneWidget);
+ expect(find.byTooltip('3 unblocked'), findsOneWidget);
+ expect(find.byTooltip('20 agent-hours lent'), findsOneWidget);
// Fixed columns: points end at one edge, and each number starts where
// the one above it does.
final right = tester.getTopRight(within('peer', '21 pts')).dx;
expect(tester.getTopRight(within('owner', '13 pts')).dx, right);
expect(tester.getTopRight(within('huy', '0 pts')).dx, right);
expect(
- tester.getTopLeft(within('owner', '4 unblocked')).dx,
- tester.getTopLeft(within('peer', '3 unblocked')).dx,
+ tester.getTopLeft(within('owner', '🔓 4')).dx,
+ tester.getTopLeft(within('peer', '🔓 3')).dx,
);
expect(
- tester.getTopLeft(within('owner', '20 h lent')).dx,
- tester.getTopLeft(within('peer', '0 h lent')).dx,
+ tester.getTopLeft(within('owner', '💻 20 h')).dx,
+ tester.getTopLeft(within('peer', '💻 0 h')).dx,
);
// A long name is cut short rather than pushing the points out.
final name = tester.widget<Text>(
@@ -114,30 +135,122 @@ void main() {
},
);
- testWidgets('puts the team goal on one line above the people', (
+ testWidgets(
+ 'puts a small shipped chip above the people, with no open count',
+ (tester) async {
+ final controller = await show(tester, humansSwarm());
+ final goal = find.byKey(const ValueKey('leaderboard-goal'));
+ expect(
+ find.descendant(
+ of: goal,
+ matching: find.text('🚀 7 shipped this week'),
+ ),
+ findsOneWidget,
+ );
+ expect(find.textContaining('open'), findsNothing);
+ expect(find.textContaining('Team goal'), findsNothing);
+ // The week before and the median are on hover.
+ expect(
+ find.byTooltip('4 shipped last week\nMedian ask to ship 2 h'),
+ findsOneWidget,
+ );
+ expect(
+ tester.getTopLeft(goal).dy,
+ lessThan(tester.getTopLeft(person('peer')).dy),
+ );
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets(
+ "names each person by display name, else their email's first part",
+ (tester) async {
+ final controller = await show(tester, humansSwarm());
+ Finder within(String id, String text) =>
+ find.descendant(of: person(id), matching: find.text(text));
+ expect(within('peer', 'Dee'), findsOneWidget);
+ expect(within('owner', 'Ken'), findsOneWidget);
+ // A server from before names: the email's first part, as before.
+ expect(within('scholes', 'scholes'), findsOneWidget);
+ expect(find.text('dee'), findsNothing);
+ // The email stays on hover.
+ expect(find.byTooltip('[email protected]'), findsOneWidget);
+ // Who agents wait on reads the same name.
+ expect(find.text('Dee 1'), findsOneWidget);
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets(
+ 'shows an up or down arrow against last week, and none when level or unknown',
+ (tester) async {
+ final controller = await show(tester, humansSwarm());
+ Finder trend(String id) => find.byKey(ValueKey('leaderboard-trend-$id'));
+ // Dee 21 from 15, Ken 13 from 20.
+ expect(
+ find.descendant(of: trend('peer'), matching: find.text('6')),
+ findsOneWidget,
+ );
+ expect(find.byTooltip('Up 6 from last week'), findsOneWidget);
+ expect(
+ find.descendant(of: trend('owner'), matching: find.text('7')),
+ findsOneWidget,
+ );
+ expect(find.byTooltip('Down 7 from last week'), findsOneWidget);
+ // Tony level at 6; Scholes from a server without last week.
+ expect(trend('tony'), findsNothing);
+ expect(trend('scholes'), findsNothing);
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets('gives the top three gold, silver and bronze cups', (
tester,
) async {
final controller = await show(tester, humansSwarm());
- final goal = find.byKey(const ValueKey('leaderboard-goal'));
+ Finder cup(String id) => find.byKey(ValueKey('leaderboard-cup-$id'));
expect(
- tester.widget<Text>(goal).data,
- 'Team goal: 7 shipped · 46 pts · 9 open',
- );
- expect(tester.widget<Text>(goal).maxLines, 1);
- // The week before and the median are on hover.
- expect(
- find.byTooltip(
- 'Team goal: 7 shipped · 46 pts · 9 open\n4 shipped last week\nMedian ask to ship 2 h',
- ),
+ find.descendant(of: person('peer'), matching: cup('peer')),
findsOneWidget,
);
- expect(
- tester.getTopLeft(goal).dy,
- lessThan(tester.getTopLeft(person('peer')).dy),
- );
+ expect(find.byTooltip('Gold cup: 1st this week'), findsOneWidget);
+ expect(find.byTooltip('Silver cup: 2nd this week'), findsOneWidget);
+ expect(find.byTooltip('Bronze cup: 3rd this week'), findsOneWidget);
+ expect({
+ for (final id in ['peer', 'owner', 'tony'])
+ tester
+ .widget<Icon>(
+ find.descendant(of: cup(id), matching: find.byType(Icon)),
+ )
+ .color,
+ }, hasLength(3));
+ expect(cup('scholes'), findsNothing);
await close(tester, controller);
});
+ testWidgets(
+ 'sparkles #1 once as the board opens, and never with Reduce Motion',
+ (tester) async {
+ final sparkle = find.byKey(const ValueKey('leaderboard-sparkle'));
+ var controller = await show(tester, humansSwarm(), settle: false);
+ expect(
+ find.descendant(of: person('peer'), matching: sparkle),
+ findsOneWidget,
+ );
+ await tester.pumpAndSettle();
+ expect(sparkle, findsNothing);
+ await close(tester, controller);
+ controller = await show(
+ tester,
+ humansSwarm(),
+ settle: false,
+ reduceMotion: true,
+ );
+ expect(sparkle, findsNothing);
+ await close(tester, controller);
+ },
+ );
+
testWidgets('reads another week from the small week picker', (tester) async {
final server = humansSwarm();
final controller = await show(tester, server);
@@ -163,24 +276,148 @@ void main() {
await close(tester, controller);
});
- testWidgets("shows a person's week when their name is tapped", (
+ testWidgets(
+ 'shows what shipped, what was unblocked and what was lent when a person is tapped',
+ (tester) async {
+ const channel = MethodChannel('plugins.flutter.io/url_launcher');
+ final launches = <String>[];
+ tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(channel, (
+ call,
+ ) async {
+ if (call.method == 'launch') {
+ launches.add((call.arguments as Map)['url'] as String);
+ }
+ return true;
+ });
+ addTearDown(
+ () => tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(
+ channel,
+ null,
+ ),
+ );
+ final controller = await show(tester, humansSwarm());
+ await tester.tap(person('peer'));
+ await tester.pumpAndSettle();
+ final dialog = find.byType(AlertDialog);
+ Finder inDialog(String text) =>
+ find.descendant(of: dialog, matching: find.text(text));
+ expect(inDialog('Dee'), findsOneWidget);
+ expect(inDialog('21 pts · up 6 from last week'), findsOneWidget);
+ expect(inDialog('🚀 Shipped'), findsOneWidget);
+ expect(inDialog('🔓 Unblocked'), findsOneWidget);
+ expect(inDialog('💻 Lent'), findsOneWidget);
+ expect(inDialog('Which sign-in page ships first?'), findsOneWidget);
+ expect(inDialog('waited 1.6 h'), findsOneWidget);
+ // Dee lent nothing this week.
+ expect(inDialog('No machines lent yet'), findsOneWidget);
+ // A pull request title opens the pull request; one without a link is text.
+ await tester.tap(
+ inDialog('Desktop: a machine shows its agents as one count'),
+ );
+ await tester.pumpAndSettle();
+ expect(launches, [
+ 'https://github.com/autonomous-ai/openharness/pull/1824',
+ ]);
+ await tester.tap(inDialog('Swarm digest pauses with the Swarm'));
+ await tester.pumpAndSettle();
+ expect(launches, hasLength(1));
+ await tester.tap(find.text('Close'));
+ await tester.pumpAndSettle();
+
+ await tester.tap(person('owner'));
+ await tester.pumpAndSettle();
+ expect(inDialog('13 pts · down 7 from last week'), findsOneWidget);
+ expect(inDialog('No pull requests merged yet'), findsOneWidget);
+ expect(inDialog('No questions answered yet'), findsOneWidget);
+ // The machine as it calls itself, without .local.
+ expect(inDialog('MACs-Mac-Studio'), findsOneWidget);
+ expect(inDialog('12.5 h busy'), findsOneWidget);
+ expect(inDialog('7 h busy'), findsOneWidget);
+ expect(tester.takeException(), isNull);
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets(
+ "shows a person's week as before where the server has no details",
+ (tester) async {
+ final controller = await show(tester, humansSwarm());
+ await tester.tap(person('scholes'));
+ await tester.pumpAndSettle();
+ final dialog = find.byType(AlertDialog);
+ Finder inDialog(String text) =>
+ find.descendant(of: dialog, matching: find.text(text));
+ expect(inDialog('scholes'), findsOneWidget);
+ expect(inDialog('Nothing landed yet'), findsOneWidget);
+ expect(inDialog('🚀 Shipped'), findsNothing);
+ expect(find.textContaining('last week'), findsNothing);
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets('opens only web links, and shows any other link as plain text', (
tester,
) async {
- final controller = await show(tester, humansSwarm());
+ const channel = MethodChannel('plugins.flutter.io/url_launcher');
+ final launches = <String>[];
+ tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(channel, (
+ call,
+ ) async {
+ if (call.method == 'launch') {
+ launches.add((call.arguments as Map)['url'] as String);
+ }
+ return true;
+ });
+ addTearDown(
+ () => tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(
+ channel,
+ null,
+ ),
+ );
+ final server = humansSwarm();
+ final dee = (server.leaderboard!['people'] as List).first as Map;
+ (dee['details'] as Map)['shipped'] = [
+ {'title': 'A file', 'prUrl': 'file:///etc/hosts'},
+ {'title': 'A script', 'prUrl': 'javascript:alert(1)'},
+ {'title': 'An app', 'prUrl': 'x-harness://open'},
+ {'title': 'Plain web', 'prUrl': 'http://example.com/pull/1'},
+ ];
+ final controller = await show(tester, server);
await tester.tap(person('peer'));
await tester.pumpAndSettle();
- final dialog = find.byType(AlertDialog);
+ for (final title in ['A file', 'A script', 'An app', 'Plain web']) {
+ await tester.tap(find.text(title));
+ await tester.pumpAndSettle();
+ }
+ expect(launches, ['http://example.com/pull/1']);
+ // Only the web link reads as a link.
expect(
- find.descendant(
- of: dialog,
- matching: find.text('6 asks landed · median 2 h to ship'),
- ),
- findsOneWidget,
+ find.ancestor(of: find.text('A file'), matching: find.byType(InkWell)),
+ findsNothing,
);
- expect(
- find.descendant(of: dialog, matching: find.text('6 days shipping')),
- findsOneWidget,
+ await close(tester, controller);
+ });
+
+ testWidgets('keeps a long list of details inside the window', (tester) async {
+ final server = humansSwarm();
+ final dee = (server.leaderboard!['people'] as List).first as Map;
+ (dee['details'] as Map)['shipped'] = [
+ for (var i = 0; i < 20; i++)
+ {'title': 'Pull request $i', 'prUrl': 'https://example.com/$i'},
+ ];
+ final controller = await show(tester, server, size: const Size(1300, 600));
+ await tester.tap(person('peer'));
+ await tester.pumpAndSettle();
+ expect(tester.takeException(), isNull);
+ await tester.scrollUntilVisible(
+ find.text('No machines lent yet'),
+ 100,
+ scrollable: find.descendant(
+ of: find.byType(AlertDialog),
+ matching: find.byType(Scrollable),
+ ),
);
+ expect(find.text('No machines lent yet'), findsOneWidget);
await close(tester, controller);
});
diff --git a/desktop/test/super_tab_leaderboard_shots_test.dart b/desktop/test/super_tab_leaderboard_shots_test.dart
new file mode 100644
index 000000000..ccf3b4f04
--- /dev/null
+++ b/desktop/test/super_tab_leaderboard_shots_test.dart
@@ -0,0 +1,77 @@
+import 'dart:io';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/super_tabs/view.dart';
+
+import 'support/capture.dart';
+import 'support/humans_fixture.dart';
+
+/// Set to a folder to write the Humans leaderboard's screenshots there: the
+/// real right pane over the in-memory Swarm, never a backend or the live app.
+final shots = Platform.environment['SUPER_TAB_LEADERBOARD_SHOTS'];
+
+Future<void> showHumans(
+ WidgetTester tester,
+ Brightness brightness, {
+ bool settle = true,
+}) async {
+ await tester.binding.setSurfaceSize(const Size(1300, 900));
+ addTearDown(() => tester.binding.setSurfaceSize(null));
+ // The app sets the design tokens' brightness from its theme at startup.
+ grid.AppTheme.brightness.value = brightness;
+ addTearDown(() => grid.AppTheme.brightness.value = Brightness.dark);
+ final c = humansSwarm().controller(
+ account: 'peer',
+ initial: {'tabId': 'tab', 'accountId': 'peer', 'selectedId': 'lead'},
+ );
+ addTearDown(c.dispose);
+ await c.refresh();
+ await tester.pumpWidget(
+ MaterialApp(
+ debugShowCheckedModeBanner: false,
+ theme: grid.buildAppTheme(brightness: brightness),
+ home: Scaffold(
+ body: SuperTabView(
+ controller: c,
+ onInvite: () {},
+ onAddAgent: (_) {},
+ onOpenTerminal: (_) {},
+ machineName: (_) => 'Mac Studio',
+ ),
+ ),
+ ),
+ );
+ if (settle) {
+ await tester.pumpAndSettle();
+ return;
+ }
+ // The board's read lands, and #1's sparkle is at its brightest.
+ for (var i = 0; i < 5; i++) {
+ await tester.pump();
+ }
+ await tester.pump(const Duration(milliseconds: 650));
+}
+
+void main() {
+ setUpAll(() => loadCaptureFonts(shots));
+
+ testWidgets('screenshots for review', (tester) async {
+ for (final (brightness, name) in [
+ (Brightness.light, 'light'),
+ (Brightness.dark, 'dark'),
+ ]) {
+ await showHumans(tester, brightness);
+ await captureWindow(tester, shots, 'humans-$name');
+ await tester.tap(find.byKey(const ValueKey('super-person-peer')));
+ await tester.pumpAndSettle();
+ await captureWindow(tester, shots, 'person-$name');
+ await tester.pumpWidget(const SizedBox());
+ await showHumans(tester, brightness, settle: false);
+ await captureWindow(tester, shots, 'humans-$name-sparkle');
+ await tester.pumpAndSettle();
+ await tester.pumpWidget(const SizedBox());
+ }
+ }, skip: shots == null);
+}
diff --git a/desktop/test/super_tab_leaderboard_test.dart b/desktop/test/super_tab_leaderboard_test.dart
index b8d1f5c68..8ece32ec5 100644
--- a/desktop/test/super_tab_leaderboard_test.dart
+++ b/desktop/test/super_tab_leaderboard_test.dart
@@ -144,6 +144,96 @@ void main() {
]);
});
+ test(
+ 'parses the display name, last week and what each number is made of',
+ () {
+ final board = SuperTabLeaderboard.fromJson({
+ ...answer(),
+ 'people': [
+ {
+ ...score('ken', points: 42, rank: 1, shipped: 1),
+ 'displayName': 'Ken Tran',
+ 'prevWeekPoints': 30,
+ 'details': {
+ 'shipped': [
+ {
+ 'title': 'Desktop: a machine shows one count',
+ 'prUrl': 'https://github.com/o/r/pull/1824',
+ 'mergedAt': '2026-10-27T10:00:00.000Z',
+ },
+ ],
+ 'unblocked': [
+ {
+ 'title': 'Which sign-in page?',
+ 'conversationId': 'g1',
+ 'kind': 'decision',
+ 'waitedMinutes': 95,
+ },
+ ],
+ 'lent': [
+ {'machineName': 'MACs-Mac-Studio.local', 'busyHours': 12.5},
+ ],
+ },
+ },
+ ],
+ });
+ final ken = board.people.single;
+ expect(ken.displayName, 'Ken Tran');
+ expect(ken.prevWeekPoints, 30);
+ final details = ken.details!;
+ expect(details.shipped.map((s) => (s.title, s.prUrl)), [
+ (
+ 'Desktop: a machine shows one count',
+ 'https://github.com/o/r/pull/1824',
+ ),
+ ]);
+ expect(
+ details.unblocked.map(
+ (u) => (u.title, u.conversationId, u.kind, u.waitedMinutes),
+ ),
+ [('Which sign-in page?', 'g1', 'decision', 95)],
+ );
+ expect(details.lent.map((l) => (l.machineName, l.busyHours)), [
+ ('MACs-Mac-Studio.local', 12.5),
+ ]);
+ },
+ );
+
+ test(
+ 'reads a server from before names, last week and details as unknown',
+ () {
+ final ken = SuperTabLeaderboard.fromJson(answer()).people.first;
+ expect(ken.displayName, isNull);
+ expect(ken.prevWeekPoints, isNull);
+ expect(ken.details, isNull);
+ },
+ );
+
+ test('skips detail items with no title rather than drawing them blank', () {
+ final ken = SuperTabLeaderboard.fromJson({
+ ...answer(),
+ 'people': [
+ {
+ ...score('ken', points: 1, rank: 1),
+ 'displayName': '',
+ 'details': {
+ 'shipped': [
+ {'prUrl': 'https://github.com/o/r/pull/1'},
+ {'title': 'Kept', 'prUrl': 7},
+ ],
+ 'unblocked': 'not a list',
+ },
+ },
+ ],
+ }).people.single;
+ expect(ken.displayName, isNull);
+ expect(ken.details!.shipped.map((s) => (s.title, s.prUrl)), [
+ ('Kept', null),
+ ]);
+ expect(ken.details!.unblocked, isEmpty);
+ expect(ken.details!.lent, isEmpty);
+ });
+
test('asks for the project and, once chosen, the week', () async {
final requests = FakeRequests();
final reader = SuperTabLeaderboardReader(
diff --git a/desktop/test/super_tab_leads_test.dart b/desktop/test/super_tab_leads_test.dart
index caf50da91..118025806 100644
--- a/desktop/test/super_tab_leads_test.dart
+++ b/desktop/test/super_tab_leads_test.dart
@@ -235,7 +235,7 @@ void main() {
});
final controller = await show(tester, server, account: 'viewer');
// "This project" chosen in a workgroup does not follow into it.
- await tester.tap(find.byKey(const ValueKey('super-group-lead')));
+ await tester.tap(find.byKey(const ValueKey('super-project-toggle-lead')));
await tester.pumpAndSettle();
await tester.tap(find.byKey(const ValueKey('super-group-offline')));
await tester.pumpAndSettle();
diff --git a/desktop/test/super_tab_machines_test.dart b/desktop/test/super_tab_machines_test.dart
index c134b4a47..47d4bfc2d 100644
--- a/desktop/test/super_tab_machines_test.dart
+++ b/desktop/test/super_tab_machines_test.dart
@@ -2722,11 +2722,15 @@ void main() {
},
);
+ // Every 2 GiB of total RAM may run an agent, and every machine may offer
+ // four; the suggestion keeps its 16 (Ken, 2026-10-28).
for (final (totalGiB, suggested, maximum) in [
(32.0, 8, 16),
(16.0, 4, 8),
- (64.0, 16, 16),
- (2.0, 1, 1),
+ (64.0, 16, 32),
+ (192.0, 16, 96),
+ (8.0, 2, 4),
+ (2.0, 1, 4),
]) {
testWidgets(
'Add machine with $totalGiB GiB total offers $suggested of $maximum slots',
@@ -2759,6 +2763,41 @@ void main() {
);
}
+ testWidgets('Configure lets a 192 GiB machine offer 96 agents', (
+ tester,
+ ) async {
+ final f = SuperTabLaunchFixture();
+ f.app.bindSuperTab(f.app.activeSwarmId, tabId, 'Pilot');
+ f.connection.server.state['machines'] = [
+ {'machineId': 'm', 'contributorId': 'owner', 'maxAgents': 16},
+ ];
+ final c = await f.app.superTabs.open(tabId);
+ await c.refresh();
+ await _openConfigureDialog(
+ tester,
+ f,
+ c,
+ readLocal: (_) async => _reading(totalGiB: 192, freeGiB: 100),
+ );
+
+ expect(_agentSlots(tester), '16');
+ for (var slot = 16; slot < 96; slot++) {
+ await tester.tap(_slotsStep('more'));
+ await tester.pump();
+ }
+ expect(_agentSlots(tester), '96');
+ expect(_slotsButton(tester, 'more').onPressed, isNull);
+ await tester.tap(find.widgetWithText(FilledButton, 'Save'));
+ await _settleSave(tester);
+ expect(f.connection.server.posts.single['command']!['maxAgents'], 96);
+ expect(tester.takeException(), isNull);
+
+ await tester.pumpWidget(const SizedBox());
+ await c.flush();
+ f.app.superTabs.dispose();
+ await tester.pump();
+ });
+
testWidgets(
'Configure keeps the owner’s 12 slots even when total RAM offers eight',
(tester) async {
diff --git a/desktop/test/super_tab_project_rows_shots_test.dart b/desktop/test/super_tab_project_rows_shots_test.dart
new file mode 100644
index 000000000..2ee8ad32a
--- /dev/null
+++ b/desktop/test/super_tab_project_rows_shots_test.dart
@@ -0,0 +1,76 @@
+import 'dart:io';
+
+import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/super_tabs/view.dart';
+
+import 'support/capture.dart';
+import 'support/humans_fixture.dart';
+
+/// Set to a folder to write the project rows' pictures there: a project
+/// collapsed and expanded, in both themes.
+final shots = Platform.environment['SUPER_TAB_SIDEBAR_SHOTS'];
+
+void main() {
+ setUpAll(() => loadCaptureFonts(shots));
+
+ for (final brightness in Brightness.values) {
+ testWidgets('project rows in ${brightness.name}', (tester) async {
+ if (shots == null) return;
+ final previous = grid.AppTheme.brightness.value;
+ grid.AppTheme.brightness.value = brightness;
+ addTearDown(() => grid.AppTheme.brightness.value = previous);
+ tester.view.devicePixelRatio = 2;
+ tester.view.physicalSize = const Size(2000, 1400);
+ addTearDown(tester.view.reset);
+ final server = humansSwarm();
+ addNumberedWorkgroups(server, 11);
+ final controller = server.controller(
+ account: 'peer',
+ initial: {'tabId': 'tab', 'accountId': 'peer', 'selectedId': 'lead'},
+ );
+ await controller.refresh();
+ // Unread, so the project's dot shows beside its chevron.
+ server.append('New work', conversationId: 'g11');
+ await controller.refresh();
+ final picture = GlobalKey();
+ await tester.pumpWidget(
+ MaterialApp(
+ debugShowCheckedModeBanner: false,
+ theme: grid.buildAppTheme(brightness: brightness),
+ home: RepaintBoundary(
+ key: picture,
+ child: Scaffold(
+ body: SuperTabView(
+ controller: controller,
+ onInvite: () {},
+ onAddAgent: (_) {},
+ onOpenTerminal: (_) {},
+ machineName: (_) => 'Studio',
+ ),
+ ),
+ ),
+ ),
+ );
+ Future<void> take(String name) async {
+ await tester.pumpAndSettle();
+ await captureBoundary(
+ tester,
+ picture.currentContext!.findRenderObject()! as RenderRepaintBoundary,
+ shots,
+ 'project-rows-$name-${brightness.name}',
+ );
+ }
+
+ controller.expandedProjects.clear();
+ await take('collapsed');
+ controller.toggleProject('lead');
+ await take('expanded');
+ await tester.pumpWidget(const SizedBox());
+ await controller.flush();
+ controller.dispose();
+ }, variant: TargetPlatformVariant.only(TargetPlatform.macOS));
+ }
+}
diff --git a/desktop/test/super_tab_pull_requests_test.dart b/desktop/test/super_tab_pull_requests_test.dart
index dea3baee3..1449ae212 100644
--- a/desktop/test/super_tab_pull_requests_test.dart
+++ b/desktop/test/super_tab_pull_requests_test.dart
@@ -381,6 +381,43 @@ void main() {
expect(find.textContaining('View status on GitHub'), findsNothing);
await tester.pumpWidget(const SizedBox());
});
+ testWidgets('the fallback stays on screen while GitHub is asked again', (
+ tester,
+ ) async {
+ final retry = Completer<Map<String, dynamic>>();
+ var reads = 0;
+ await mount(tester, prServer([1]), (_) async {
+ reads++;
+ return reads == 1 ? {'error': 'LOCAL_GITHUB_UNAVAILABLE'} : retry.future;
+ });
+ await tester.pump(const Duration(seconds: 60));
+ await tester.pump();
+ expect(reads, 2);
+ expect(find.textContaining('View status on GitHub'), findsOneWidget);
+ retry.complete({
+ 'rows': [prRow(1)],
+ });
+ await tester.pumpAndSettle();
+ expect(find.text('Pull request 1'), findsOneWidget);
+ await tester.pumpWidget(const SizedBox());
+ });
+ testWidgets('a retry that learns GitHub cannot be read stops asking', (
+ tester,
+ ) async {
+ var reads = 0;
+ await mount(tester, prServer([1]), (_) async {
+ reads++;
+ return {'error': reads == 1 ? 'LOCAL_GITHUB_UNAVAILABLE' : 'UNSUPPORTED'};
+ });
+ await tester.pump(const Duration(seconds: 60));
+ await tester.pumpAndSettle();
+ expect(reads, 2);
+ await tester.pump(const Duration(seconds: 60));
+ await tester.pumpAndSettle();
+ expect(reads, 2);
+ expect(find.textContaining('View status on GitHub'), findsOneWidget);
+ await tester.pumpWidget(const SizedBox());
+ });
testWidgets('a computer that cannot read PR status is not asked again', (
tester,
) async {
diff --git a/desktop/test/super_tab_sidebar_rows_test.dart b/desktop/test/super_tab_sidebar_rows_test.dart
index 8d15dd46e..d11f8b9de 100644
--- a/desktop/test/super_tab_sidebar_rows_test.dart
+++ b/desktop/test/super_tab_sidebar_rows_test.dart
@@ -1,5 +1,6 @@
import 'package:flutter/gestures.dart';
import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/shared/theme/app_icons.dart';
import 'package:harness/shared/theme/app_theme.dart' as grid;
@@ -10,15 +11,17 @@ import 'package:harness/super_tabs/view.dart';
import 'support/humans_fixture.dart';
import 'support/super_tab_fixture.dart';
-/// The sidebar's rows without chevrons (Dee, 2026-10-27): a direct message
-/// click highlights only that row; a project click opens its chat and shows
-/// its workgroups, and a second click hides them; a machine click expands it,
+/// The sidebar's rows: a direct message click highlights only that row; a
+/// project's name opens its chat and only the chevron at its right end shows
+/// or hides its conversations (Dee, 2026-10-28); a machine click expands it,
/// and its details are in the right-click menu.
void main() {
final dm = find.byKey(const ValueKey('super-pm-chat-lead'));
final project = find.byKey(const ValueKey('super-group-lead'));
final workgroup = find.byKey(const ValueKey('super-group-offline'));
final machine = find.byKey(const ValueKey('super-machine-studio'));
+ final toggle = find.byKey(const ValueKey('super-project-toggle-lead'));
+ final more = find.byKey(const ValueKey('super-project-more-lead'));
Future<SuperTabController> show(
WidgetTester tester,
@@ -99,29 +102,307 @@ void main() {
);
testWidgets(
- 'a project click opens its chat and shows its workgroups; a second click hides them',
+ 'a project name click opens its chat and leaves its list as it was',
(tester) async {
final controller = await show(tester, humansSwarm());
await controller.openPmChat('lead');
controller.expandedProjects.clear();
await tester.pumpAndSettle();
- expect(chevronIn(project), findsNothing);
- await tester.tap(project);
+ await tester.tap(find.text('Pilot'));
await tester.pumpAndSettle();
expect(controller.selectedId, 'lead');
+ expect(controller.expandedProjects, isEmpty);
+ expect(workgroup, findsNothing);
+
+ // Open, and the chat left for a direct message: the name comes back to
+ // it without closing the list.
+ await tester.tap(toggle);
+ await tester.tap(dm);
+ await tester.pumpAndSettle();
+ await tester.tap(find.text('Pilot'));
+ await tester.pumpAndSettle();
+ expect(controller.selectedId, 'lead');
+ expect(controller.expandedProjects, {'lead'});
+ expect(workgroup, findsOneWidget);
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets(
+ 'the chevron at the far right of a project toggles its list and leaves the chat open',
+ (tester) async {
+ final controller = await show(tester, humansSwarm());
+ await controller.openPmChat('lead');
+ controller.expandedProjects.clear();
+ await tester.tap(dm);
+ await tester.pumpAndSettle();
+ final chat = controller.selectedId;
+ Icon chevron() => tester.widget<Icon>(chevronIn(toggle));
+ expect(chevron().icon, AppIcons.chevronRight);
+ expect(
+ tester.getCenter(toggle).dx,
+ greaterThan(tester.getRect(project).right),
+ );
+
+ await tester.tap(toggle);
+ await tester.pumpAndSettle();
expect(controller.expandedProjects, {'lead'});
expect(workgroup, findsOneWidget);
+ expect(chevron().icon, AppIcons.chevronDown);
+ expect(controller.selectedId, chat);
- await tester.tap(project);
+ await tester.tap(toggle);
await tester.pumpAndSettle();
- expect(controller.selectedId, 'lead');
expect(controller.expandedProjects, isEmpty);
expect(workgroup, findsNothing);
+ expect(controller.selectedId, chat);
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets('an unread project shows its dot just left of the chevron', (
+ tester,
+ ) async {
+ // Not "Offline editing": it waits for a person, which shows "?" there.
+ final server = humansSwarm();
+ addNumberedWorkgroups(server, 1);
+ final controller = await show(tester, server);
+ server.append('New work', conversationId: 'g1');
+ await controller.refresh();
+ await tester.pumpAndSettle();
+ final dot = find.descendant(
+ of: project,
+ matching: find.byWidgetPredicate(
+ (w) => w is Semantics && w.properties.label == 'Unread messages',
+ ),
+ );
+ expect(dot, findsOneWidget);
+ expect(tester.getCenter(dot).dx, lessThan(tester.getRect(toggle).left));
+ await close(tester, controller);
+ });
+
+ testWidgets(
+ 'projects start collapsed, and each account keeps its own choice',
+ (tester) async {
+ final server = humansSwarm();
+ var controller = await show(tester, server);
+ expect(controller.expandedProjects, isEmpty);
+ expect(workgroup, findsNothing);
+ await tester.tap(toggle);
+ await tester.pumpAndSettle();
+ await close(tester, controller);
+
+ Future<SuperTabController> reopen(String account) async {
+ final next = server.controller(account: account, initial: server.saved);
+ await next.refresh();
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: SuperTabView(
+ controller: next,
+ onInvite: () {},
+ onAddAgent: (_) {},
+ onOpenTerminal: (_) {},
+ machineName: (_) => 'Studio',
+ ),
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ return next;
+ }
+
+ controller = await reopen('peer');
+ expect(workgroup, findsOneWidget);
+ expect(tester.widget<Icon>(chevronIn(toggle)).icon, AppIcons.chevronDown);
+ await close(tester, controller);
+
+ controller = await reopen('owner');
+ expect(workgroup, findsNothing);
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets(
+ 'an open project lists its 8 newest conversations, and "… N more" shows the rest',
+ (tester) async {
+ final server = humansSwarm();
+ addNumberedWorkgroups(server, 11);
+ final controller = await show(tester, server);
+ await tester.tap(toggle);
+ await tester.pumpAndSettle();
+
+ Finder row(String id) => find.byKey(ValueKey('super-group-$id'));
+ final shown = [for (var n = 11; n >= 4; n--) row('g$n')];
+ for (final finder in shown) {
+ expect(finder, findsOneWidget);
+ }
+ for (var i = 1; i < shown.length; i++) {
+ expect(
+ tester.getTopLeft(shown[i]).dy,
+ greaterThan(tester.getTopLeft(shown[i - 1]).dy),
+ );
+ }
+ // #3, #2, #1 and the unnumbered "Offline editing" wait behind the row.
+ expect(row('g3'), findsNothing);
+ expect(workgroup, findsNothing);
+ expect(more, findsOneWidget);
+ expect(find.text('… 4 more'), findsOneWidget);
+ expect(
+ tester.getTopLeft(more).dy,
+ greaterThan(tester.getTopLeft(row('g4')).dy),
+ );
+
+ await tester.tap(more);
+ await tester.pumpAndSettle();
+ expect(more, findsNothing);
+ for (final id in ['g3', 'g2', 'g1', 'offline']) {
+ expect(row(id), findsOneWidget);
+ }
+ expect(
+ tester.getTopLeft(workgroup).dy,
+ greaterThan(tester.getTopLeft(row('g1')).dy),
+ );
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets('an older conversation that is open stays listed', (
+ tester,
+ ) async {
+ final server = humansSwarm();
+ addNumberedWorkgroups(server, 11);
+ final controller = await show(tester, server);
+ await controller.select('g1');
+ await tester.pumpAndSettle();
+ expect(find.byKey(const ValueKey('super-group-g1')), findsOneWidget);
+ expect(find.byKey(const ValueKey('super-group-g2')), findsNothing);
+ expect(find.text('… 3 more'), findsOneWidget);
+ await close(tester, controller);
+ });
+
+ testWidgets(
+ 'unread and waiting conversations older than the 8 newest stay listed',
+ (tester) async {
+ final server = humansSwarm();
+ addNumberedWorkgroups(server, 11);
+ // #2 waits for a person to answer its Engineer.
+ (server.state['conversations'] as List)
+ .cast<Map<String, dynamic>>()
+ .firstWhere((g) => g['id'] == 'g2')
+ ..['agentIds'] = ['lead-agent']
+ ..['assignment'] = {'agentId': 'lead-agent', 'status': 'needs_human'};
+ final controller = await show(tester, server);
+ server.append('New work', conversationId: 'g1');
+ await controller.refresh();
+ await tester.tap(toggle);
+ await tester.pumpAndSettle();
+ expect(find.byKey(const ValueKey('super-group-g1')), findsOneWidget);
+ expect(find.byKey(const ValueKey('super-group-g2')), findsOneWidget);
+ expect(find.byKey(const ValueKey('super-group-g3')), findsNothing);
+ expect(find.text('… 2 more'), findsOneWidget);
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets(
+ 'a collapsed project holding the open conversation shows as selected',
+ (tester) async {
+ final server = humansSwarm();
+ addNumberedWorkgroups(server, 1);
+ final controller = await show(tester, server);
+ Color? projectFill() => tester
+ .widget<Material>(
+ find.ancestor(of: project, matching: find.byType(Material)).first,
+ )
+ .color;
+ await controller.select('g1');
+ await tester.pumpAndSettle();
+ expect(projectFill(), Colors.transparent);
+
+ await tester.tap(toggle);
+ await tester.pumpAndSettle();
+ expect(controller.selectedId, 'g1');
+ expect(projectFill(), grid.AppSurface.selectedFill);
+
+ await tester.tap(toggle);
+ await tester.pumpAndSettle();
+ expect(projectFill(), Colors.transparent);
+ await close(tester, controller);
+ },
+ );
+
+ testWidgets('an arrow a project name cannot use moves focus as usual', (
+ tester,
+ ) async {
+ final controller = await show(tester, humansSwarm());
+ await tester.tap(toggle);
+ await tester.pumpAndSettle();
+ expect(controller.expandedProjects, {'lead'});
+ Focus.of(tester.element(find.text('Pilot'))).requestFocus();
+ await tester.pumpAndSettle();
+
+ // Already open: → goes on to the chevron beside the name.
+ await tester.sendKeyEvent(LogicalKeyboardKey.arrowRight);
+ await tester.pumpAndSettle();
+ expect(controller.expandedProjects, {'lead'});
+ expect(
+ primaryFocus?.context?.findAncestorWidgetOfExactType<InkWell>()?.key,
+ const ValueKey('super-project-toggle-lead'),
+ );
+ await close(tester, controller);
+ });
+
+ testWidgets(
+ 'Enter on a project name opens it; → and ← show and hide its conversations',
+ (tester) async {
+ final controller = await show(tester, humansSwarm());
+ await controller.openPmChat('lead');
+ controller.expandedProjects.clear();
+ await tester.tap(dm);
+ await tester.pumpAndSettle();
+ Future<void> focusName() async {
+ Focus.of(tester.element(find.text('Pilot'))).requestFocus();
+ await tester.pumpAndSettle();
+ }
+
+ await focusName();
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pumpAndSettle();
+ expect(controller.selectedId, 'lead');
+ expect(controller.expandedProjects, isEmpty);
+
+ // Opening the chat moved focus into it.
+ await focusName();
+ await tester.sendKeyEvent(LogicalKeyboardKey.arrowRight);
+ await tester.pumpAndSettle();
+ expect(controller.expandedProjects, {'lead'});
+ await tester.sendKeyEvent(LogicalKeyboardKey.arrowLeft);
+ await tester.pumpAndSettle();
+ expect(controller.expandedProjects, isEmpty);
+ expect(controller.selectedId, 'lead');
await close(tester, controller);
},
);
+ testWidgets('the focused chevron toggles with Enter and with Space', (
+ tester,
+ ) async {
+ final controller = await show(tester, humansSwarm());
+ controller.expandedProjects.clear();
+ await tester.pumpAndSettle();
+ Focus.of(tester.element(chevronIn(toggle))).requestFocus();
+ await tester.pumpAndSettle();
+ await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+ await tester.pumpAndSettle();
+ expect(controller.expandedProjects, {'lead'});
+ await tester.sendKeyEvent(LogicalKeyboardKey.space);
+ await tester.pumpAndSettle();
+ expect(controller.expandedProjects, isEmpty);
+ await close(tester, controller);
+ });
+
testWidgets(
'a machine click expands and collapses it; Details is in its right-click menu',
(tester) async {
diff --git a/desktop/test/super_tab_sidebar_test.dart b/desktop/test/super_tab_sidebar_test.dart
index aa26ae834..c3b624ec1 100644
--- a/desktop/test/super_tab_sidebar_test.dart
+++ b/desktop/test/super_tab_sidebar_test.dart
@@ -156,6 +156,9 @@ void main() {
await tester.pumpAndSettle();
expect(controller.selectedId, 'lead');
expect(inRow('super-group-lead', find.text('#')), findsOneWidget);
+ final toggle = find.byKey(const ValueKey('super-project-toggle-lead'));
+ await tester.tap(toggle);
+ await tester.pumpAndSettle();
final work = find.byKey(const ValueKey('super-group-offline'));
expect(work, findsOneWidget);
final textX = tester
@@ -170,17 +173,20 @@ void main() {
]) {
expect(tester.getTopLeft(label).dx, textX, reason: '$label');
}
+ // A workgroup's dot is in the rows' right status column; a project's
+ // chevron takes that column and its dot sits just left of it.
expect(
tester.getCenter(unreadDot('offline')).dx,
+ tester.getCenter(toggle).dx,
+ );
+ expect(
tester.getCenter(unreadDot('lead')).dx,
+ tester.getCenter(toggle).dx - tester.getSize(toggle).width,
);
for (final row in [newProject, devices, work]) {
final bounds = tester.getRect(row);
- final projectBounds = tester.getRect(
- find.byKey(const ValueKey('super-group-lead')),
- );
- expect(bounds.left, projectBounds.left);
- expect(bounds.right, projectBounds.right);
+ expect(bounds.left, tester.getRect(project).left);
+ expect(bounds.right, tester.getRect(toggle).right);
}
await tester.tap(work);
@@ -189,10 +195,16 @@ void main() {
await tester.tap(empty);
await tester.pumpAndSettle();
expect(controller.selectedId, 'empty-lead');
+ expect(find.text('No workgroups yet'), findsNothing);
+ final emptyToggle = find.byKey(
+ const ValueKey('super-project-toggle-empty'),
+ );
+ await tester.tap(emptyToggle);
+ await tester.pumpAndSettle();
expect(find.text('No workgroups yet'), findsOneWidget);
expect(tester.getTopLeft(find.text('No workgroups yet')).dx, textX);
- // A second click on the open project hides its workgroups again.
- await tester.tap(empty);
+ // A second click on its chevron hides them again.
+ await tester.tap(emptyToggle);
await tester.pumpAndSettle();
expect(controller.selectedId, 'empty-lead');
expect(find.text('No workgroups yet'), findsNothing);
@@ -332,8 +344,9 @@ void main() {
}
expect(
tester.getCenter(find.byTooltip('New project')).dx,
- tester.getRect(find.byKey(const ValueKey('super-group-lead'))).right -
- 16,
+ tester
+ .getCenter(find.byKey(const ValueKey('super-project-toggle-lead')))
+ .dx,
);
expect(tester.takeException(), isNull);
}
diff --git a/desktop/test/super_tab_view_test.dart b/desktop/test/super_tab_view_test.dart
index 2ce5b381a..294911928 100644
--- a/desktop/test/super_tab_view_test.dart
+++ b/desktop/test/super_tab_view_test.dart
@@ -209,7 +209,7 @@ void main() {
await tester.tap(find.byTooltip('Conversations'));
await tester.pumpAndSettle();
}
- await tester.tap(find.byKey(const ValueKey('super-group-lead')));
+ await tester.tap(find.byKey(const ValueKey('super-project-toggle-lead')));
await tester.pumpAndSettle();
await tester.tap(find.byKey(const ValueKey('super-group-offline')));
await tester.pumpAndSettle();
@@ -298,7 +298,7 @@ void main() {
expect(server.posts, isEmpty);
await tester.tap(find.byTooltip('Conversations'));
await tester.pumpAndSettle();
- await tester.tap(find.byKey(const ValueKey('super-group-lead')));
+ await tester.tap(find.byKey(const ValueKey('super-project-toggle-lead')));
await tester.pumpAndSettle();
await tester.tap(find.byKey(const ValueKey('super-group-offline')));
await tester.pumpAndSettle();
diff --git a/desktop/test/support/humans_fixture.dart b/desktop/test/support/humans_fixture.dart
index 71af622a5..fefbf08b6 100644
--- a/desktop/test/support/humans_fixture.dart
+++ b/desktop/test/support/humans_fixture.dart
@@ -2,6 +2,8 @@ import 'pm_chat_fixture.dart';
import 'super_tab_fixture.dart';
/// Seven people, so a cut-off list would hide some, with this week's scores.
+/// Dee, Ken and Tony carry the newer fields (display name, last week, details);
+/// the rest read as a server from before them.
ConversationServer humansSwarm() {
final server = pmChatSwarm();
(server.state['agents'] as List).first['displayName'] = 'River';
@@ -49,9 +51,49 @@ ConversationServer humansSwarm() {
'lastWeek': {'shipped': 4, 'points': 20, 'medianAskToShipMs': null},
},
'people': [
- score('peer', 21, 1, 6, 3, 0),
- score('owner', 13, 2, 1, 4, 2),
- score('tony', 6, 3, 2, 0, 0),
+ {
+ ...score('peer', 21, 1, 6, 3, 0),
+ 'displayName': 'Dee',
+ 'prevWeekPoints': 15,
+ 'details': {
+ 'shipped': [
+ {
+ 'title': 'Desktop: a machine shows its agents as one count',
+ 'prUrl': 'https://github.com/autonomous-ai/openharness/pull/1824',
+ 'mergedAt': '2026-10-28T03:00:00.000Z',
+ },
+ {'title': 'Swarm digest pauses with the Swarm', 'prUrl': null},
+ ],
+ 'unblocked': [
+ {
+ 'title': 'Which sign-in page ships first?',
+ 'conversationId': 'offline',
+ 'kind': 'decision',
+ 'waitedMinutes': 95,
+ },
+ ],
+ 'lent': <Map<String, dynamic>>[],
+ },
+ },
+ {
+ ...score('owner', 13, 2, 1, 4, 2),
+ 'displayName': 'Ken',
+ 'prevWeekPoints': 20,
+ 'details': {
+ 'shipped': <Map<String, dynamic>>[],
+ 'unblocked': <Map<String, dynamic>>[],
+ 'lent': [
+ {'machineName': 'MACs-Mac-Studio.local', 'busyHours': 12.5},
+ {'machineName': 'Build box', 'busyHours': 7},
+ ],
+ },
+ },
+ {
+ ...score('tony', 6, 3, 2, 0, 0),
+ 'displayName': 'Tony',
+ 'prevWeekPoints': 6,
+ },
+ // From a server before names, last week and details.
score('scholes', 4, 4, 0, 2, 1),
score('diego', 2, 5, 0, 1, 1),
score('huy', 0, 6, 0, 0, 0),
@@ -70,3 +112,14 @@ ConversationServer humansSwarm() {
};
return server;
}
+
+/// Adds workgroups #1 to #[count] to the Pilot project, created in that order.
+void addNumberedWorkgroups(ConversationServer server, int count) {
+ final conversations = server.state['conversations'] as List;
+ for (var number = 1; number <= count; number++) {
+ conversations.add({
+ ...conversationFixture('g$number', 'Workgroup $number'),
+ 'number': number,
+ });
+ }
+}
diff --git a/desktop/test/swarm_projects_test.dart b/desktop/test/swarm_projects_test.dart
index b76451fef..660079e8d 100644
--- a/desktop/test/swarm_projects_test.dart
+++ b/desktop/test/swarm_projects_test.dart
@@ -80,6 +80,9 @@ void main() {
await tester.tap(find.byKey(const ValueKey('super-group-lead')));
await tester.pumpAndSettle();
expect(c.selectedId, 'lead');
+ expect(find.text('12 Offline editing'), findsNothing);
+ await tester.tap(find.byKey(const ValueKey('super-project-toggle-lead')));
+ await tester.pumpAndSettle();
expect(find.text('12 Offline editing'), findsOneWidget);
await tester.tap(find.byKey(const ValueKey('super-group-offline')));
await tester.pumpAndSettle();
@@ -87,7 +90,7 @@ void main() {
await tester.tap(find.byKey(const ValueKey('super-group-design-lead')));
await tester.pumpAndSettle();
expect(c.selectedId, 'design-lead');
- expect(c.expandedProjects, {'lead', 'design'});
+ expect(c.expandedProjects, {'lead'});
await tester.tap(find.byKey(const ValueKey('super-group-lead')));
await tester.pumpAndSettle();
expect(c.selectedId, 'lead');
@@ -108,19 +111,29 @@ void main() {
of: project,
matching: find.text('Lamp OS'),
);
- // Enter on the open project shows its workgroups.
+ // Enter on the project opens its chat; → shows its workgroups.
Focus.of(tester.element(projectName)).requestFocus();
await tester.pump();
await tester.sendKeyEvent(LogicalKeyboardKey.enter);
await tester.pumpAndSettle();
- expect(c.expandedProjects, {'lead'});
+ expect(c.expandedProjects, isEmpty);
expect(c.selectedId, 'lead');
+ Focus.of(tester.element(projectName)).requestFocus();
+ await tester.pump();
+ await tester.sendKeyEvent(LogicalKeyboardKey.arrowRight);
+ await tester.pumpAndSettle();
+ expect(c.expandedProjects, {'lead'});
final workgroup = find.byKey(const ValueKey('super-group-offline'));
final projectBounds = tester.getRect(project);
final workgroupBounds = tester.getRect(workgroup);
expect(workgroupBounds.left, projectBounds.left);
- expect(workgroupBounds.right, projectBounds.right);
+ expect(
+ workgroupBounds.right,
+ tester
+ .getRect(find.byKey(const ValueKey('super-project-toggle-lead')))
+ .right,
+ );
// Workgroups share the project name column in the compact sidebar.
expect(
tester.getTopLeft(find.text('12 Offline editing')).dx,
@@ -132,7 +145,7 @@ void main() {
await tester.pumpAndSettle();
expect(c.selectedId, 'offline');
// From a workgroup, the project row opens the project's chat and keeps
- // its workgroups shown; once more, Space hides them.
+ // its workgroups shown; ← hides them.
Focus.of(tester.element(projectName)).requestFocus();
await tester.pump();
await tester.sendKeyEvent(LogicalKeyboardKey.enter);
@@ -141,7 +154,7 @@ void main() {
expect(c.expandedProjects, {'lead'});
Focus.of(tester.element(projectName)).requestFocus();
await tester.pump();
- await tester.sendKeyEvent(LogicalKeyboardKey.space);
+ await tester.sendKeyEvent(LogicalKeyboardKey.arrowLeft);
await tester.pumpAndSettle();
expect(c.selectedId, 'lead');
expect(c.expandedProjects, isEmpty);
diff --git a/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c b/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
index 591ad6106..3df4771f9 100644
--- a/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
+++ b/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
@@ -593,6 +593,7 @@ enum { SUPERTAB_RECAP_GET, SUPERTAB_OPEN, SUPERTAB_SELECT };
static EXT_RAM_BSS_ATTR ht_supertabs_t swarm;
static EXT_RAM_BSS_ATTR struct {
char tab[ID_MAX], lead[ID_MAX]; // the Swarm the dial is in ("" in a desk tab) and the Lead on its face
+ char desk[ID_MAX]; // the desk tab that Swarm is listed at, "" when none (entered from the inbox)
int at; // that Lead's place, where the face lands when the Lead goes
bool retried; // its recap was asked for a second time
struct { char tab[ID_MAX], lead[ID_MAX]; } focus[HT_SUPERTABS_MAX]; // the Lead the desktop last showed, per Swarm
@@ -664,10 +665,15 @@ static void swarm_leave(void)
{
if (!swarm_mode()) return;
swarm_send(SUPERTAB_OPEN, sw.tab, "");
- sw.tab[0] = sw.lead[0] = 0; sw.at = 0;
+ sw.tab[0] = sw.lead[0] = sw.desk[0] = 0; sw.at = 0;
ht_supertabs_recap_open(&swarm, "", "", ms());
change();
}
+static void swarm_desk_note(void)
+{
+ const ht_supertab_t *t = swarm_here();
+ if (t && t->tab[0] && workspace_index(t->tab) >= 0) COPY(sw.desk, t->tab);
+}
static const char *swarm_remembered(const char *tab)
{
for (int i = 0; i < HT_SUPERTABS_MAX; i++) if (!strcmp(sw.focus[i].tab, tab)) return sw.focus[i].lead;
@@ -682,41 +688,31 @@ static void swarm_enter(const ht_supertab_t *t, const char *lead, bool select)
if (workspace.phase != HT_WORKSPACE_IDLE) ht_workspace_cancel_request(&workspace);
s.loading = false;
COPY(sw.tab, t->id);
+ sw.desk[0] = 0; swarm_desk_note();
int i = swarm_lead_index(t, lead);
if (i < 0) i = swarm_lead_index(t, swarm_remembered(t->id));
swarm_show(t, i < 0 ? 0 : i, select);
view(HOME);
}
/*
- * TABS lists the desk tabs, then every Swarm the desktop has not opened, in the `supertabs` order. A desk tab linked
- * to a Swarm keeps its place and name and enters that Swarm; a Swarm whose desk tab is not listed counts as unopened.
+ * TABS lists exactly the desk tabs, as the desktop shows them (Diego, 2026-10-27). A desk tab linked to a Swarm keeps
+ * its place and name and enters that Swarm. A Swarm with no desk tab is not listed, with or without a window: the
+ * desktop opens a tab for every Super Tab its owner has not closed, so it is a closed one, and listing it kept a
+ * closed tab on the dial ("PR merge").
*/
-static bool swarm_unopened(const ht_supertab_t *t)
-{
- return !t->tab[0] || workspace_index(t->tab) < 0;
-}
static const ht_supertab_t *tab_swarm(int i)
{
- if (i < 0) return NULL;
- if (i < s.tab_count) return ht_supertabs_for_desk(&swarm, s.tabs[i].id);
- for (int k = 0, n = s.tab_count;; k++) {
- const ht_supertab_t *t = ht_supertabs_at(&swarm, k);
- if (!t) return NULL;
- if (swarm_unopened(t) && n++ == i) return t;
- }
+ return i >= 0 && i < s.tab_count ? ht_supertabs_for_desk(&swarm, s.tabs[i].id) : NULL;
}
static int tabs_total(void)
{
- int n = s.tab_count;
- for (int k = 0; ht_supertabs_at(&swarm, k); k++) n += swarm_unopened(ht_supertabs_at(&swarm, k));
- return n;
+ return s.tab_count;
}
-// The page of a desk tab or Swarm id, -1 when neither is listed.
+// The page of a desk tab or the Swarm it is linked to, -1 when neither is listed.
static int tab_index_of(const char *id)
{
int i = workspace_index(id);
if (i >= 0 || !id || !*id) return i;
- for (i = s.tab_count; i < tabs_total(); i++) if (!strcmp(tab_swarm(i)->id, id)) return i;
for (i = 0; i < s.tab_count; i++) {
const ht_supertab_t *t = tab_swarm(i);
if (t && !strcmp(t->id, id)) return i;
@@ -725,7 +721,7 @@ static int tab_index_of(const char *id)
}
static const char *tab_id_at(int i)
{
- return i >= 0 && i < s.tab_count ? s.tabs[i].id : tab_swarm(i) ? tab_swarm(i)->id : "";
+ return i >= 0 && i < s.tab_count ? s.tabs[i].id : "";
}
static int swarm_notice(const char *lead);
static void swarm_notice_drop(const char *lead);
@@ -1930,7 +1926,7 @@ static void focus_carousel(ht_scene_t *f, const ht_tab_carousel_t *c, int count,
static const char *tab_label(int i)
{
// A Swarm's page is drawn as any tab's (decision 1): its name, nothing else.
- const char *name = i < s.tab_count ? s.tabs[i].name : tab_swarm(i) ? tab_swarm(i)->name : "";
+ const char *name = i >= 0 && i < s.tab_count ? s.tabs[i].name : "";
return name[0] ? name : "Untitled";
}
static void render_focus_tabs(ht_scene_t *f)
@@ -4832,6 +4828,13 @@ static void swarms_apply(void)
s.tab_count=bounded;
if (bounded) memcpy(s.tabs,rows,(size_t)bounded*sizeof *rows);
COPY(s.selected_tab,selected);
+ // The desktop closed the desk tab of the Swarm on the face: the dial leaves it too, for TABS on the app's tab.
+ if (swarm_mode() && sw.desk[0] && workspace_index(sw.desk) < 0) {
+ swarm_leave();
+ if (s.view == HOME || s.view == AGENT || s.view == AGENTS) tabs_open();
+ } else {
+ swarm_desk_note();
+ }
changed = changed || total_before != tabs_total();
if (s.view == TABS && (changed || (selected_changed && !browsing))) {
int index = browsing ? tab_index_of(focused) : tab_index_here();
@@ -4939,7 +4942,7 @@ void ui_supertabs_ids(const char ids[][ID_MAX], int n)
swarm_events(ev, count);
if (swarm_mode() && !swarm_here()) {
// The Swarm on the face is gone: back to the list.
- sw.tab[0] = sw.lead[0] = 0;
+ sw.tab[0] = sw.lead[0] = sw.desk[0] = 0;
ht_supertabs_recap_open(&swarm, "", "", ms());
if (s.view == HOME || s.view == AGENT || s.view == AGENTS) tabs_open();
}
diff --git a/devices/harness-device/firmware/test/test_touch_ui.py b/devices/harness-device/firmware/test/test_touch_ui.py
index 8df0f0eff..93dd93f96 100644
--- a/devices/harness-device/firmware/test/test_touch_ui.py
+++ b/devices/harness-device/firmware/test/test_touch_ui.py
@@ -1356,14 +1356,18 @@ static void openharness_card(void) {
card_lead("L4", "backend", "cursor", "", "work", 4, -1);
card_lead("L1", "Round dial firmware release candidate", "claude", "h1", "done", 1, -1);
}
-static void swarm_setup(void) {
- reset(); ht_character_select(&character, HT_CHARACTER_FOCUS); fake_ms = 100000;
+// The desktop's three tabs, the window open on "Harness repo".
+static void desk_open(void) {
static cable_swarm_t rows[3];
memset(rows, 0, sizeof rows);
COPY(rows[0].id, "t0"); COPY(rows[0].name, "Harness repo"); rows[0].agents = 1;
COPY(rows[1].id, "t1"); COPY(rows[1].name, "openharness"); rows[1].agents = 0;
COPY(rows[2].id, "t2"); COPY(rows[2].name, "Research"); rows[2].agents = 1;
ui_swarms_replace(rows, 3, "t0");
+}
+static void swarm_setup(void) {
+ reset(); ht_character_select(&character, HT_CHARACTER_FOCUS); fake_ms = 100000;
+ desk_open();
const char ids[3][ID_MAX] = {"s1", "s3", "s2"};
ui_supertabs_ids(ids, 3);
openharness_card(); card_send();
@@ -1378,6 +1382,47 @@ static const ht_run_t *big_run(void) {
}
static void tabs_at(int index) { dispatch((action_t){.kind = A_TABS}); ht_tab_carousel_reset(&tab_carousel, tabs_total(), index); scene_take(); }
static void swarm_tabs_checks(const char *dir) {
+ // TABS is the desktop's tabs and nothing else, with or without a window (Diego, 2026-10-27). The desktop opens every
+ // Super Tab its owner has not closed, so a Swarm without a desk tab is one closed there ("PR merge" closed and still
+ // on the dial).
+ swarm_setup();
+ assert(tabs_total() == 3 && tab_index_of("s2") < 0 && tab_index_of("s3") < 0);
+ {
+ // Desk tabs [A, S linked], Swarms [S, X, Y]: exactly A and S.
+ reset(); static cable_swarm_t rows[2]; memset(rows, 0, sizeof rows);
+ COPY(rows[0].id, "t0"); COPY(rows[0].name, "Harness repo"); rows[0].agents = 1;
+ COPY(rows[1].id, "t1"); COPY(rows[1].name, "openharness"); rows[1].agents = 0;
+ ui_swarms_replace(rows, 2, "t0");
+ const char ids[3][ID_MAX] = {"s1", "s3", "s2"}; ui_supertabs_ids(ids, 3);
+ openharness_card(); card_send(); card_begin("s2", "", "playground"); card_send(); card_begin("s3", "", "studio"); card_send();
+ assert(tabs_total() == 2 && !strcmp(tab_id_at(0), "t0") && !strcmp(tab_id_at(1), "t1"));
+ assert(!strcmp(tab_label(0), "Harness repo") && !strcmp(tab_label(1), "openharness") && tab_index_of("s1") == 1);
+ // The S desk tab closed: the next `swarms` frame drops S.
+ ui_swarms_replace(rows, 1, "t0");
+ assert(tabs_total() == 1 && tab_index_of("s1") < 0);
+ // No window: no desk tab, so nothing is listed, not X, not Y.
+ ui_swarms_replace(NULL, 0, NULL);
+ assert(tabs_total() == 0 && tab_index_of("s1") < 0 && tab_index_of("s2") < 0 && tab_index_of("s3") < 0);
+ }
+ {
+ // The dial in openharness when its desk tab closes on the desktop: it leaves the Swarm (saying so) for TABS,
+ // on the app's current tab. A `swarms` frame that keeps the desk tab keeps the dial in.
+ static cable_swarm_t rows[2]; memset(rows, 0, sizeof rows);
+ COPY(rows[0].id, "t0"); COPY(rows[0].name, "Harness repo"); rows[0].agents = 1;
+ COPY(rows[1].id, "t2"); COPY(rows[1].name, "Research"); rows[1].agents = 1;
+ swarm_setup(); tabs_at(1); dispatch((action_t){.kind = A_TAB_DONE}); assert(swarm_mode() && !strcmp(sw.tab, "s1"));
+ desk_open(); assert(swarm_mode() && s.view == HOME);
+ swarm_sent = 0; ui_swarms_replace(rows, 2, "t2");
+ assert(!swarm_mode() && s.view == TABS && ht_tab_carousel_index(&tab_carousel) == 1 && !strcmp(tab_id_at(1), "t2"));
+ assert(swarm_sent == 1 && !strcmp(swarm_wire[0], "open s1 "));
+ // No window at all: the same, onto the empty list.
+ swarm_setup(); tabs_at(1); dispatch((action_t){.kind = A_TAB_DONE}); assert(swarm_mode());
+ ui_swarms_replace(NULL, 0, NULL); assert(!swarm_mode() && s.view == TABS && tabs_total() == 0);
+ // A Swarm entered from the inbox with no desk tab is not one the desktop closed: `swarms` frames leave it be.
+ swarm_setup(); swarm_enter(ht_supertabs_find(&swarm, "s2"), "P0", true); scene_take();
+ desk_open(); ui_swarms_replace(rows, 2, "t2"); ui_swarms_replace(NULL, 0, NULL);
+ assert(swarm_mode() && !strcmp(sw.tab, "s2") && s.view == HOME);
+ }
// A desk tab linked to a Swarm keeps its place and name, listed with no agents; it was hidden before the link came.
swarm_setup();
assert(s.tab_count == 3 && !strcmp(s.tabs[1].id, "t1") && !strcmp(s.tabs[1].name, "openharness"));
@@ -1388,36 +1433,29 @@ static void swarm_tabs_checks(const char *dir) {
const char ids[1][ID_MAX] = {"s1"}; ui_supertabs_ids(ids, 1); openharness_card(); card_send();
assert(s.tab_count == 2 && !strcmp(s.tabs[1].id, "t1"));
}
- // The unopened Swarms follow the desk tabs in the `supertabs` order, not the order their cards came in.
+ // Decision 1: a Swarm's page is drawn as any tab's. The centred name of the linked "openharness" and of the desk tab
+ // "Research" share font and ink.
swarm_setup();
- assert(tabs_total() == 5 && !strcmp(tab_label(3), "studio") && !strcmp(tab_label(4), "playground"));
- assert(!strcmp(tab_id_at(1), "t1") && !strcmp(tab_id_at(3), "s3") && !strcmp(tab_id_at(4), "s2"));
- // Decision 1: a Swarm's page is drawn as any tab's. The centred name of the unopened "playground" and of the desk
- // tab "Research" share font and ink.
tabs_at(2); const ht_run_t desk = *big_run();
- tabs_at(4); const ht_run_t far = *big_run();
- assert(!strcmp(far.text, "playground") && far.font == desk.font && far.fg == desk.fg && far.bg == desk.bg);
- // 1a in "Harness repo", openharness at the right edge; 1b dragging; 1c on openharness; 1d the unopened playground.
+ tabs_at(1); const ht_run_t linked = *big_run();
+ assert(!strcmp(linked.text, "openharness") && linked.font == desk.font && linked.fg == desk.fg && linked.bg == desk.bg);
+ // 1a in "Harness repo", openharness at the right edge; 1b dragging; 1c on openharness.
swarm_setup(); tabs_at(0); FOCUS_PAGE("swarm-tabs-1a");
tab_carousel.position = HT_TAB_PITCH / 2; FOCUS_PAGE("swarm-tabs-1b");
tabs_at(1); assert(!strcmp(big_run()->text, "openharness")); FOCUS_PAGE("swarm-tabs-1c");
- tabs_at(4); FOCUS_PAGE("swarm-tabs-1d");
- // A tap on an unopened Swarm's name enters it: no workspace handshake, no switching view, then select and open
- // for its first Lead by order.
+ // A tap on the Swarm's name enters it: no workspace handshake, no switching view, then select and open for its
+ // first Lead by order ("mobile").
int switched = tab_switches;
tap(5000, 233, 233);
- assert(s.view == HOME && swarm_mode() && !strcmp(sw.tab, "s2") && !strcmp(sw.lead, "P0"));
+ assert(s.view == HOME && swarm_mode() && !strcmp(sw.tab, "s1") && !strcmp(sw.lead, "L0"));
assert(tab_switches == switched && workspace.phase == HT_WORKSPACE_IDLE && !s.loading);
- assert(swarm_sent == 3 && !strcmp(swarm_wire[0], "select s2 P0") && !strcmp(swarm_wire[1], "open s2 P0") &&
- !strcmp(swarm_wire[2], "recap.get s2 P0"));
- // Done on a Swarm the desktop last showed at a Lead opens on that Lead; the Swarm the dial left is closed.
- ui_supertab_focus("s3", "K1"); assert(!strcmp(sw.tab, "s2"));
- tabs_at(3); swarm_sent = 0; dispatch((action_t){.kind = A_TAB_DONE});
- assert(!strcmp(sw.tab, "s3") && !strcmp(sw.lead, "K1") && s.view == HOME && tab_switches == switched);
- assert(!strcmp(swarm_wire[0], "open s2 ") && !strcmp(swarm_wire[1], "select s3 K1") && !strcmp(swarm_wire[2], "open s3 K1"));
- // The desk tab linked to openharness enters the Swarm too, at its first project by order ("mobile").
- tabs_at(1); dispatch((action_t){.kind = A_TAB_DONE});
- assert(!strcmp(sw.tab, "s1") && !strcmp(sw.lead, "L0") && tab_switches == switched);
+ assert(swarm_sent == 3 && !strcmp(swarm_wire[0], "select s1 L0") && !strcmp(swarm_wire[1], "open s1 L0") &&
+ !strcmp(swarm_wire[2], "recap.get s1 L0"));
+ // Done on a Swarm the desktop last showed at a Lead opens on that Lead.
+ swarm_leave(); ui_supertab_focus("s1", "L3"); assert(!swarm_mode());
+ tabs_at(1); swarm_sent = 0; dispatch((action_t){.kind = A_TAB_DONE});
+ assert(!strcmp(sw.tab, "s1") && !strcmp(sw.lead, "L3") && s.view == HOME && tab_switches == switched);
+ assert(!strcmp(swarm_wire[0], "select s1 L3") && !strcmp(swarm_wire[1], "open s1 L3"));
// Hold on a Swarm's face opens TABS on that Swarm.
s.view = HOME; scene_take();
habitat_touch(true, 233, 230, 9000); habitat_touch(true, 233, 230, 9700);
@@ -1427,7 +1465,7 @@ static void swarm_tabs_checks(const char *dir) {
swarm_sent = 0; ht_tab_carousel_reset(&tab_carousel, tabs_total(), 2); scene_take();
dispatch((action_t){.kind = A_TAB_DONE});
assert(!swarm_mode() && !strcmp(tab_target, "t2") && tab_switches > switched && !strcmp(swarm_wire[0], "open s1 "));
- puts("Swarm tabs: linked desk tab kept with no agents, unopened Swarms after the desk tabs in list order, same font and ink, entered with no handshake, remembered Lead, hold to TABS, desk tabs unchanged PASS");
+ puts("Swarm tabs: exactly the desk tabs (closed Swarms never listed, with or without a window), closing the face's desk tab leaves the Swarm, linked desk tab kept with no agents, same font and ink, entered with no handshake, remembered Lead, hold to TABS, desk tabs unchanged PASS");
}
// Every run's text joined, and the first sprite (the pet's frame): what a face says and which pose it holds.
diff --git a/docs/product-measurement.md b/docs/product-measurement.md
index 9d25fb66c..dff55a8cf 100644
--- a/docs/product-measurement.md
+++ b/docs/product-measurement.md
@@ -18,7 +18,7 @@ automatically proven improvement. Changes still need review, tests and a deliber
| Why are Desktop frames long, and on how many computers? | One in 60 rendered frames by duration; a sample of 50 ms or more also by its longest phase (`frame_slow_wait`, `frame_slow_build`, `frame_slow_raster`); once per collector day, the first sample over 250 ms (`frame_long_collector`) | Wait is the UI thread busy before the frame could start (on macOS and Linux the platform's main thread: timers, channel and native callbacks, synchronous IO, AppKit or GTK); build is the framework's build, layout and paint; raster is drawing. The phases add up to the samples of 50 ms or more counted beside them. `frame_long_collector` over `collector_days` is the share of collector days with a long sample: many long samples on few such days are a few computers, not a broad problem. Counted only once the computer's CLI has announced them (below), so not before a run's first report answer or behind an older CLI; compare releases separately. |
| Which features get tried and used again? | First measured installations and daily first/repeat feature reach | Locally deduplicated installation-days, not unique accounts. Reads the apps make on their own (history, history paging, Store list, model list; `PRODUCT_USAGE_AUTOMATIC_ACTIONS`) count reliability only. The Store and model lists get reach only from the request an app marks `userAction` when a person opens them (`<action>_user_*`, `PRODUCT_USAGE_USER_OPENED_ACTIONS`); history has none. |
-| Where do app flows break? | Setup, Harness/tmux/clipboard steps, sign-in, workspace/remote connections, computer linking, viewer-pane opening and manual update checking/staging; a setup step whose tool was missing at a check (`setup_desktop_setup_<step>_missing`); the agents a new computer downloads beside setup (`setup_desktop_agent_download_<opencode\|codex\|claude>_started`, `_ok`, `_failed`, with under 1 min, 1–5 min and over 5 min) | Fixed started/ok/failed/cancelled/unknown counts and coarse duration buckets. Opening a viewer pane is not rendering its content; staging an update is not a successful relaunch. A setup step stays open from the first check until its tool is in place, so a tool that was missing and then installed is one ok step and one `_missing` mark; only a setup that ends failed fails its step. Earlier Desktop releases counted every check that found a tool missing as a failed step (on 2026-10-16 the Harness step read 72 failed of 221 while 0 setups failed): compare releases separately. `_missing` is any tool a check found absent or out of date (a Harness CLI older than this Desktop needs, on a computer already in use, counts too), not only new computers. A step left waiting (the review, a Linux Terminal handoff, manual mode, someone who walks away) now ends `unknown` at the 15-minute observation bound instead of `failed`, so expect `setup_*_unknown` to rise, mostly on Linux. `_missing` and the download counts are anonymous setup counts only. A download whose prerequisite (curl, Harness's Node) never arrived counts as started and failed; `ok` means the agent's program is in place, judged per engine. |
+| Where do app flows break? | Setup, Harness/tmux/clipboard steps, sign-in, workspace/remote connections, computer linking, viewer-pane opening and manual update checking/staging; a setup step whose tool was missing at a check (`setup_desktop_setup_<step>_missing`); the agents a new computer downloads beside setup (`setup_desktop_agent_download_<opencode\|codex\|claude>_started`, `_ok`, `_failed`, with under 1 min, 1–5 min and over 5 min) | Fixed started/ok/failed/cancelled/unknown counts and coarse duration buckets. Opening a viewer pane is not rendering its content; staging an update is not a successful relaunch. A setup step stays open from the first check until its tool is in place, so a tool that was missing and then installed is one ok step and one `_missing` mark; only a setup that ends failed fails its step. Earlier Desktop releases counted every check that found a tool missing as a failed step (on 2026-10-16 the Harness step read 72 failed of 221 while 0 setups failed): compare releases separately. `_missing` is any tool a check found absent or out of date (a Harness CLI older than this Desktop needs, on a computer already in use, counts too), not only new computers. A step left waiting (the review, a Linux Terminal handoff, manual mode, someone who walks away) now ends `unknown` at the 15-minute observation bound instead of `failed`, so expect `setup_*_unknown` to rise, mostly on Linux. `_missing` and the download counts are anonymous setup counts only. A download whose prerequisite (curl, Harness's Node) never arrived counts as started and failed; `ok` means the agent's program is in place, judged per engine. Desktop sign-in: `cancelled` is the person moving on (Cancel, the other button, the app closing, a phone that turned it down); `unknown` is a browser page nobody came back from in the CLI's five minutes, or a QR nobody scanned, which may be someone who left or a callback that never arrived; `failed` is the rest. Each sign-in that did not go through also counts why (`setup_desktop_sign_in_reason_<reason>`, signed-out only): the CLI's own result code lower-cased (`timeout`, `callback_error`, `exchange_failed`, `backend_error`, `daemon_busy`, …), `cancelled`, `no_result` (the CLI ended without a result line), `cli_unavailable` (it could not be started) or `other`. Until the Desktop release after 2026-10-28 every one of these was `failed` (Oct 26–27 2026: 8 and 13 a day, nearly all within 10 s): compare releases separately. |
| Where does the phone's onboarding stall? | After sign-in: waiting for the first computer, opening its session, the first message, the notification prompt. A sign-in that went through, by button, counted again under the account's sharing. Waits past a minute split into 1–5 min, 5–15 min, 15 min–1 h and over 1 h for the computer and the first message. Once per step per sign-in: `resumed` (reopened in a run that did not sign in), "Not you? Sign out", the address sent from the share sheet, a joining computer that wants its password or is offline, `joined_after_leaving` (the computer turned up after the app left the wait), `new_account` (a sign-in that created the account). Once per install: `first_open` (signed out `setup_phone_first_open`, signed in `ui_phone_first_open`) | Stage totals per day, not a linked funnel. A wait's `ok` is a computer that turned up while its screen was open: add `joined_after_leaving` for the computers that came while the app was away (16–19 October 2026: 5 `ok` in 49 fresh waits, while 91% of the phone's people had a computer on the same account). `new_account` is an account minutes old at sign-in, its first Harness sign-in anywhere. `first_open` is set once per install by a local flag that is never sent: the step between a store's download and a sign-in. Subtract `resumed` from starts for fresh starts; an unmatched start is a closed app or a step still waiting. A resumed step's duration starts at the reopening. Signed-in sign-in counts are successes only; failures and cancels before an account remain the signed-out counts', but a success is marked `retried` (a failed or cancelled try came first in that app run) or `switched` (another button was tried first). Phone reports carry release and iOS/Android, so every phone count also splits by those two margins (above 20 collector days); debug builds are not kept. A chosen sign-out sends what is queued first (up to 2 s), so "Not you? Sign out" reaches the totals. The first message is the first line sent after the hand-over in any session, or a task typed into New Harness; before 2026-10-20 only the session the hand-over opened counted and leaving it cancelled the step (compare releases separately). Each step of a sign-in that created its account is marked `new_account` when counted and `new_account_ok` when it ends ok, so new people's funnel reads apart. The phone sends what it queued as it leaves the screen, since iOS can end a suspended app with its counts still in RAM. |
| How fast does the phone get back to work? | A launch that came back signed in, to its first computer answering (`app_start`); a dial the person asked for ("Try again", `connect_user`) apart from the app's own (`connect_auto`), beside the unchanged `remote_connect`; a stopped harness resumed from the phone, to its first live turn (`resume_recovery`) | A launch that signs in is the onboarding's and is not counted; one that leaves the screen before a computer answers (the app hidden, at the latest sent to the background) is `unknown`, one whose computers never answer stays started. What a launch waited on is counted beside it, once each, until a computer answers or the app leaves the screen (`ui_phone_app_start_<why>`): `no_computer` and `list_failed` (the account's list had none, or could not be read), `offline` (it said every computer was offline), `locked` (a computer wanted the phone's password), `connect_failed` (a dial to a computer said to be online failed) and `waited_1m` (a minute on screen); a launch can name several. An asked-for dial fails at 12 s, as Desktop Connect does. A phone dial is `failed` only when the phone knows why (locked or offline), `unknown` otherwise; the reasons (`connect_error_*`) are Desktop health counters. The phone's `remote_connect` is one computer's socket dialling, from connecting or reconnecting until it connects (`ok`) or drops (`failed`). `cancelled` is a dial still going when the app went to the background (the pause, not the app switcher or a system sheet): a suspended app never hears the socket's answer, so the dial ends there rather than staying without an outcome, and a dial after the app is back is a new count. The two dials beside it end the same way: a `connect_auto` or `connect_user` dial still going at the pause is `cancelled`, an asked-for dial's 12 s deadline goes with it, and the socket's answer after the pause counts nothing more. From build 72, the release after 1.0.8 (71), a `remote_connect`, `connect_auto` or `connect_user` dial still in progress when the app goes to the background ends `cancelled`; earlier builds, 1.0.8 (71) included, left it without an outcome (79 of the 252 `remote_connect` dials on 2026-10-20): compare releases separately. |
| Are the phone's side pages used? | Find and Computers opens, by a sideways swipe on the terminal or by a button (Computers' row in Settings, its link on a long wait at home) | Which page and which way, nothing more. Find's key and screen-reader actions are not counted; a swipe that lets Find go back opened nothing. |
diff --git a/docs/superpowers/specs/2026-10-23-round-swarm-tab-design.md b/docs/superpowers/specs/2026-10-23-round-swarm-tab-design.md
index 5a863f4ff..1e4c82bd6 100644
--- a/docs/superpowers/specs/2026-10-23-round-swarm-tab-design.md
+++ b/docs/superpowers/specs/2026-10-23-round-swarm-tab-design.md
@@ -41,7 +41,10 @@ answering or posting to a Lead on another machine; answering a Super Tab wait on
1. **The Swarm tab looks like any tab.** Same font and colour in TABS. No badge, capsule or colour of its own; people
tell it apart by its name (1a–1c).
-2. **Swarms not open on the desktop are listed too**, after the desktop's tabs (1d).
+2. **TABS mirrors the desktop's tabs exactly.** A Swarm with no desk tab is never listed, with or without a desktop
+ window. Changed 2026-10-27 (Diego), replacing "Swarms not open on the desktop are listed too" (1d): the desktop
+ opens a tab for every Super Tab its owner has not closed, so a Swarm with no desk tab is a closed one, and the dial
+ kept showing closed tabs ("PR merge"; 2 app tabs gave about 5 dial tabs). Screen 1d is dropped.
3. **Projects keep a fixed order**: the Swarm's project order, the same as in the app, never sorted by state. Swiping
never jumps (2a–2h, 3a–3c).
4. **A Lead on another machine that needs you, or is stuck, also beeps** (2e′, 4e).
@@ -101,7 +104,6 @@ under the 512-token guard on both dials. The Pro reads Lead fields by name (`pro
| Screen | Data | On the wire today? |
| --- | --- | --- |
| 1a–1c Swarm in TABS | `swarms` rows (desk tabs) + `supertab.tab` linking a Swarm to its desk tab | Yes |
-| 1d Swarm not open | `supertabs.ids` + `supertab.tab:""` | Yes; firmware rule (§3) |
| 2a–2h Swarm pane | `supertab.leads[i]` {project, engine, owner, local, state, since} | Yes |
| 2, 3 Fixed order | `leads[i].order` | **New** (daemon) |
| 2 Recap card | `supertab.recap` ← `supertab.recap.get`, pushed for the Lead named by `supertab.open` | Yes |
@@ -127,17 +129,23 @@ It lives in PSRAM (`EXT_RAM_BSS_ATTR`, like the UI state `s`). The worst case is
about 54 KB, plus one 1.5 KB recap. A `supertab` frame for an id not in the last `supertabs` list is dropped. A
`supertabs` list drops the records whose ids left it.
-### 3. TABS (screens 1a–1d)
+### 3. TABS (screens 1a–1c)
The TABS carousel lists, in order:
1. The desk tabs, as today, from `swarms`. A desk tab linked to a Swarm (some Swarm's `tab` equals its id) stays at its
desk position and keeps its name. It is listed even when its `agents` is 0 (today `ui_swarms_replace` hides such a
tab; a Swarm tab whose selected project's Lead runs elsewhere may report 0).
-2. Then every Swarm whose `tab` is empty, in `supertabs.ids` order (1d), drawn with the Swarm's `name`.
+2. Nothing else (decision 2). A Swarm whose `tab` is empty or names no listed desk tab is not listed; with no desktop
+ window (an empty `swarms` list) TABS is empty. The `supertabs` and `supertab` frames are unchanged: the dial still
+ needs the cards to enter a Swarm from its desk tab and to follow the desktop.
+
+When the desktop closes the desk tab of the Swarm on the dial's face, the dial leaves that Swarm (`supertab.open` with
+no Lead) for TABS, on the app's current tab, or onto the empty list with no window. A Swarm entered from the inbox (§5)
+that has no desk tab is not one the desktop closed, and stays on the face.
Every entry uses the same `tab_name`/`tab_split` drawing, the same ink and the same fade (decision 1). The list can
-hold 24 desk tabs + 16 Swarms; the carousel takes the count and needs no paging.
+hold 24 desk tabs; the carousel takes the count and needs no paging.
Opening a tab (tap on its name, or ✓):
@@ -298,7 +306,6 @@ is no reply path in v1 (decision 5).
| Mockup | Section |
| --- | --- |
| 1a, 1b, 1c | §3 TABS, decision 1 |
-| 1d | §3 item 2, decision 2 |
| 2a | §4 face (work, local) |
| 2b, 2g | §4 face (done, recap), §2 recap slot |
| 2c | §4 face (ask, local), §5 wait text |