The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Merge batch 11-03 b2205: #2824 #2837 (#2841)
0xken150cd30799134c
diff --git a/backend/AGENTS.md b/backend/AGENTS.mdnew file mode 100644index 000000000..ef1609951--- /dev/null+++ b/backend/AGENTS.md@@ -0,0 +1,34 @@+# The Harness backend: MongoDB rules++Read this before changing anything under `backend/` that stores data: `prisma/schema.prisma`, a collection, an index, a+query, an aggregation or a maintenance job. The repository-wide rules are in [../AGENTS.md](../AGENTS.md) and+[../ENGINEERING.md](../ENGINEERING.md). Read MongoDB's skills first, as the project's instructions say:+[schema design](https://raw.githubusercontent.com/mongodb/agent-skills/main/skills/mongodb-schema-design/SKILL.md) and+[query optimization](https://raw.githubusercontent.com/mongodb/agent-skills/main/skills/mongodb-query-optimizer/SKILL.md).++These five rules come from production. On 2026-11-03 four collections were growing with nothing removing them+(task #2488): operation receipts at 14k a day, route decisions at 21 KB a row, and 4M usage receipts whose sweep had been+waiting on a permission, quietly, for five days.++1. **Every collection names what removes it**, in its model's comment in `prisma/schema.prisma`: a TTL index, a sweep,+ a delete on write, or "kept forever" and why. A new model without that line is not done. Check the size of a row+ too: `SuperTabRouteDecision` doubled when the route started listing every engine on every machine. Keep what a reader+ reads (`routeRecord.ts storedRecord`).+2. **Receipt and log rows get a TTL index.** Declare it in Prisma with `map:` so `db push` keeps it, and make it with+ its expiry through `ensureIndex` (`src/lib/db/indexes.ts`). Production's app user may not run `collMod` (10-29), so a+ TTL index new to a collection that already exists is made *before* the push (`src/lib/db/schemaRelease.ts`,+ `superTabs/operations.ts`). A push would build it without its expiry, and `collMod` would then be refused.+ `integration/schemaRelease.test.ts` lists every expiry index and checks this.+3. **One index per query, checked with explain.** Each new or changed query gets an integration test that reads its plan:+ `IXSCAN` on the index meant for it, and documents examined close to documents returned+ (`integration/plans.test-support.ts`, `integration/workerIndexPlans.test.ts`). Prisma sends `in` and some filters as+ `$expr`, which no index bounds. Use a plain `aggregateRaw` `$match` for those (`superTabs/routeDecisions.ts+ recentDecisions`).+4. **A maintenance job that cannot run says so, loudly and every time it tries.** Log an error with what it waits on and+ what happens if nobody acts (`lib/productUsageReceiptSweep.ts`: every hour, with the date the receipts expire by+ themselves). A single warning at start is missed. A job that can never finish stops itself once its work is gone.+5. **Measure on the read-only production database before and after**, and put the numbers in the pull request: row+ count, data and index size, growth per day, and the size of a row's parts. Read it through its environment file only+ (`~/.harness-ro-prod-db`, loaded in the same command that reads it) and never print its address. A TTL index or any+ other index change is a production write made by the backend release's schema step. It ships with the release owner's+ go, in the day window, with backend CPU and latency watched before and after.diff --git a/backend/CLAUDE.md b/backend/CLAUDE.mdnew file mode 100644index 000000000..6a4029179--- /dev/null+++ b/backend/CLAUDE.md@@ -0,0 +1,2 @@+<!-- One set of rules for every agent: Codex reads AGENTS.md, and Claude Code reads it through this import. Claude Code reads AGENTS.md by itself only from v2.1.277, and only when no CLAUDE.md is in the working directory or above it, so without this a session started in a folder with a CLAUDE.md would miss these rules. -->diff --git a/backend/integration/productUsageReceipts.test.ts b/backend/integration/productUsageReceipts.test.tsindex 2e52f8743..55112e8e6 100644--- a/backend/integration/productUsageReceipts.test.ts+++ b/backend/integration/productUsageReceipts.test.ts@@ -217,33 +217,44 @@ it('a failed pass is logged and the next minute\'s pass carries on', async () =>expect(await left()).toEqual(KEPT.filter(id => !id.startsWith('old-2026-10-30')).sort())})-it('a database user that may not install the rule gets one warning and an hourly check, then the sweep runs once it may (prod 10-29)', async () => {- const lines: string[] = []- const log = { info: (message: string) => lines.push(message), warn: (message: string) => lines.push(message) }- await db.productUsageReceipt.deleteMany({ where: { id: { startsWith: 'old-2026-10-30' } } })- let refused = true, installs = 0, clock = now.getTime()- // As Prisma reports Mongo's refusal (code 13) of collMod to production's app user.- const refusing = new Proxy(db, { get: (target, key) => key === '$runCommandRaw'+/** A client that refuses collMod as Mongo refuses production's app user (code 13) while [refused] says so, counting the tries. */+function refusingCollMod(refused: () => boolean) {+ const tries = { installs: 0 }+ const client = new Proxy(db, { get: (target, key) => key === '$runCommandRaw'? (command: Record<string, unknown>) => {if (!('collMod' in command)) return target.$runCommandRaw(command as never)- installs++- return refused ? Promise.reject(new Error('Raw query failed. Code: `13`. Message: `not authorized on harness to execute command { collMod: "product_usage_receipts" }`'))+ tries.installs+++ return refused() ? Promise.reject(new Error('Raw query failed. Code: `13`. Message: `not authorized on harness to execute command { collMod: "product_usage_receipts" }`')): target.$runCommandRaw(command as never)}: Reflect.get(target, key) })- const stop = sweep.startReceiptSweep(refusing, { everyMs: 20, chunk: 50, chunks: 1, pauseMs: 0, now: () => new Date(clock), log })+ return { client, tries }+}+/** Each line the sweep logs, with its level. */+const levels = (lines: string[]) => ({ info: (message: string) => lines.push(`info ${message}`), warn: (message: string) => lines.push(`warn ${message}`),+ error: (message: string) => lines.push(`error ${message}`) })+const STUCK = 'error [usage-receipts] stuck: the database user may not install the receipt rule (collMod), so nothing is removed. The old receipts ' ++ 'expire by themselves by 2026-12-04; grant collMod to finish sooner. Checking hourly.'++it('a database user that may not install the rule gets an error every hourly check, then the sweep runs once it may (prod 10-29, task #2488)', async () => {+ const lines: string[] = []+ await db.productUsageReceipt.deleteMany({ where: { id: { startsWith: 'old-2026-10-30' } } })+ let refused = true, clock = now.getTime()+ const { client, tries } = refusingCollMod(() => refused)+ const stop = sweep.startReceiptSweep(client, { everyMs: 20, chunk: 50, chunks: 1, pauseMs: 0, now: () => new Date(clock), log: levels(lines) })try {- await vi.waitFor(() => expect(installs).toBe(1), { timeout: 5000 })- // Many minutes' passes later, within the hour: no second try, no second warning.+ await vi.waitFor(() => expect(tries.installs).toBe(1), { timeout: 5000 })+ // Many minutes' passes later, within the hour: no second try, no second line.await new Promise(resolve => setTimeout(resolve, 200))- expect(installs).toBe(1)- expect(lines).toEqual(['[usage-receipts] waiting: the database user may not install the receipt rule (collMod); nothing is removed, checking hourly'])+ expect(tries.installs).toBe(1)+ expect(lines).toEqual([STUCK])expect((await left()).length).toBe(109)clock += 3_600_000- await vi.waitFor(() => expect(installs).toBe(2), { timeout: 5000 })+ await vi.waitFor(() => expect(tries.installs).toBe(2), { timeout: 5000 })await new Promise(resolve => setTimeout(resolve, 200))- expect(installs).toBe(2)- expect(lines).toHaveLength(1)+ expect(tries.installs).toBe(2)+ // Every hour it is stuck says so again: one quiet warning at start was missed for days (#2245).+ expect(lines).toEqual([STUCK, STUCK])// Ken grants collMod: the next hourly check installs the rule and the sweep carries on, without a restart.refused = falseclock += 3_600_000@@ -252,6 +263,22 @@ it('a database user that may not install the rule gets one warning and an hourlyexpect(await left()).toEqual(KEPT.filter(id => !id.startsWith('old-2026-10-30')).sort())})+it('a refused sweep stops by itself once its old receipts have expired, and asks for collMod no more (task #2488)', async () => {+ const lines: string[] = []+ // Mongo's expiry has removed every old receipt the sweep would have: those it never touches (within 5 days) are left.+ await db.productUsageReceipt.deleteMany({ where: { id: { startsWith: 'old-' }, expiresAt: { gt: at('2026-11-02', 5) } } })+ let clock = now.getTime()+ const { client, tries } = refusingCollMod(() => true)+ const stop = sweep.startReceiptSweep(client, { everyMs: 20, chunk: 50, chunks: 1, pauseMs: 0, now: () => new Date(clock), log: levels(lines) })+ try {+ await vi.waitFor(() => expect(lines.at(-1)).toMatch(/done/), { timeout: 5000 })+ clock += 3 * 3_600_000+ await new Promise(resolve => setTimeout(resolve, 200))+ } finally { stop() }+ expect(lines).toEqual(['info [usage-receipts] done: no old receipts left'])+ expect(tries.installs).toBeLessThanOrEqual(1)+})+it('counting stays exact: a report inside the window counts once across the sweep, an older one adds nothing', async () => {const context = { surface: 'cli', release: '0.4.92', platform: 'macos', channel: 'production' } as constconst report = { schemaVersion: 1 as const, revision: 0, id: randomUUID(), day: '2026-11-01', context, counters: { turns_ended: 2 } }diff --git a/backend/integration/schemaRelease.test.ts b/backend/integration/schemaRelease.test.tsindex 538b5b0f9..52ea69ca9 100644--- a/backend/integration/schemaRelease.test.ts+++ b/backend/integration/schemaRelease.test.ts@@ -27,6 +27,7 @@ const EXPIRY: Array<[string, string, Record<string, number>, number]> = [...['SwarmWorkspace', 'SwarmWorkspaceMember', 'SwarmWorkspaceRemoval'].map(c => [c, 'workspace_purge', { purgeAt: 1 }, 0] as [string, string, Record<string, number>, number]),['SwarmWorkspaceInvitation', 'workspace_invitation_expiry', { expiresAt: 1 }, 0],['SuperTabMention', 'mention_expiry', { createdAt: 1 }, 30 * DAY],+ ['SuperTabOperation', 'operation_expiry', { createdAt: 1 }, 30 * DAY],['SuperTabTerminalRequest', 'terminal_request_expiry', { createdAt: 1 }, 120],['product_usage_receipts', 'product_usage_expiry', { expiresAt: 1 }, 0],['product_usage_totals', 'product_usage_expiry', { dayUtc: 1 }, 396 * DAY],@@ -141,6 +142,26 @@ describe('a release\'s schema step', () => {expect(await expiryIndexes(db)).toEqual(EXPIRY)await db.$disconnect()}, 240_000)++ it('gives an existing collection its new expiry index when the database user may not run collMod (prod 10-29)', async () => {+ const { db, target } = await database()+ // Production before this release: the operations collection, with receipts, and no expiry index.+ const before = await schemaWith(schema => schema.replace(/\n *\/\/\/[^\n]*\n *@@index\(\[createdAt\], map: "operation_expiry"\)/, ''))+ await releaseSchema(db, { ...target, schema: before })+ await db.$runCommandRaw({ dropIndexes: 'SuperTabOperation', index: 'operation_expiry' }).catch(() => {})+ await db.superTabOperation.create({ data: { id: 'receipt', tabId: 't', actorKey: 'agent:a', requestHash: 'h', revision: 0, result: {} } })+ // As Prisma reports Mongo's refusal (code 13) of collMod to production's app user; db push runs as its own process.+ const refusing = new Proxy(db, { get: (held, key) => key === '$runCommandRaw'+ ? (command: Record<string, unknown>) => 'collMod' in command+ ? Promise.reject(new Error('Raw query failed. Code: `13`. Message: `not authorized on harness to execute command { collMod: "SuperTabOperation" }`'))+ : held.$runCommandRaw(command as never)+ : Reflect.get(held, key) })+ const since = new Date()+ await releaseSchema(refusing, target)+ expect((await indexChanges(db, since)).filter(change => change.includes('SuperTabOperation'))).toEqual(['createIndexes SuperTabOperation operation_expiry'])+ expect(await expiryIndexes(db)).toEqual(EXPIRY)+ await db.$disconnect()+ }, 240_000)})describe('the usage receipt rule (lib/productUsageReceiptSweep.ts)', () => {diff --git a/backend/integration/superTabAutoJoin.test.ts b/backend/integration/superTabAutoJoin.test.tsindex 4f837c0cd..6e13e2d17 100644--- a/backend/integration/superTabAutoJoin.test.ts+++ b/backend/integration/superTabAutoJoin.test.ts@@ -434,6 +434,63 @@ describe('A Workspace removal is final for auto-join', () => {})})+// Task #2510 (Diego's Buddy, 11-03): once the purge deleted the removed person's member row, a tokenless domain join link to+// another domain-shared Swarm of the same Workspace readmitted them in one click, and addMember then cleared the Workspace's+// decline, so auto-join added them to every other auto-join Swarm too. Someone the Workspace removed comes back only by an+// invitation (design, Roles).+describe('A Workspace removal is final for join links', () => {+ const domainShared = async () => {+ const tab = await create()+ await save(tab, { mode: 'domain', domain: current.email.split('@')[1]!, role: 'collaborator' })+ return tab+ }+ /** [person] in the Workspace of a first auto-join Swarm, then removed from it and the removal purged. */+ const removedAndPurged = async (person: AuthUser) => {+ const first = await create()+ await turnOn(first)+ expect(await listed(person)).toContain(first)+ const { workspaceId } = await storedState(first)+ await store.workspaces.remove(current, workspaceId!, person.sub)+ // What the purge leaves: no member row and no removal row.+ await db.swarmWorkspaceMember.deleteMany({ where: { workspaceId: workspaceId!, userId: person.sub } })+ await db.swarmWorkspaceRemoval.deleteMany({ where: { workspaceId: workspaceId!, userId: person.sub } })+ return workspaceId!+ }++ it('refuses the removed person a join link and its preview after the purge, keeps the decline, and auto-join adds them nowhere', async () => {+ const { fired } = await org('twenty', ['fired'])+ const workspaceId = await removedAndPurged(fired)+ const linked = await domainShared()+ await expect(store.join(fired, linked, { operationId: randomUUID() })).rejects.toMatchObject({ code: 'WORKSPACE_ACCESS_REVOKED',+ message: expect.stringContaining('Ask its owner to invite you.') })+ await expect(store.previewJoin(fired, linked)).rejects.toMatchObject({ code: 'WORKSPACE_ACCESS_REVOKED' })+ expect(await personIn(linked, fired)).toBeUndefined()+ expect((await db.swarmWorkspace.findUniqueOrThrow({ where: { id: workspaceId } })).autoJoinDeclined).toContain(fired.sub)+ const third = await create()+ await turnOn(third)+ later()+ expect(await listed(fired)).not.toContain(third)+ })++ it('lets a person the Workspace never removed preview and join a domain-shared Swarm by its link', async () => {+ const { newcomer } = await org('twentyone', ['newcomer'])+ const linked = await domainShared()+ expect(await store.previewJoin(newcomer, linked)).toMatchObject({ alreadyMember: false })+ expect(await store.join(newcomer, linked, { operationId: randomUUID() })).toMatchObject({ alreadyMember: false })+ expect(await personIn(linked, newcomer)).toBeDefined()+ })++ it('lets a removed person invited back to the Workspace join by link again', async () => {+ const { returning } = await org('twentytwo', ['returning'])+ const workspaceId = await removedAndPurged(returning)+ await store.workspaces.invite(current, workspaceId, returning.email, 'member')+ await store.workspaces.accept(returning, workspaceId)+ const linked = await domainShared()+ expect(await store.join(returning, linked, { operationId: randomUUID() })).toMatchObject({ alreadyMember: false })+ expect(await personIn(linked, returning)).toBeDefined()+ })+})+describe('What readers see', () => {it('tells every member auto-join is on, marks who came by domain, and never shows the declines or the sharing', async () => {const { joiner, leaver } = await org('fifteen', ['joiner', 'leaver'])diff --git a/backend/integration/superTabCosts.test.ts b/backend/integration/superTabCosts.test.tsindex 9f9890745..bfe8fa162 100644--- a/backend/integration/superTabCosts.test.ts+++ b/backend/integration/superTabCosts.test.ts@@ -230,3 +230,40 @@ describe('route decision reads', () => {} finally { await app.close() }})})++describe('a route decision as stored (task #2488)', () => {+ // As production's routes were on 2026-11-03: every engine on every machine, 13 candidates with labels of ~540 characters and+ // 47 exclusions of 5 reasons, ~20 KB a row. Only the pick's label and each reason once are kept; readers get the record whole.+ it('keeps the pick\'s label and each exclusion reason once, reads back every candidate and exclusion, and still links its start', async () => {+ const f = await swarm()+ const long = (text: string, size: number) => `${text} ${'·'.repeat(Math.max(0, size - text.length - 1))}`+ const fit = { status: 'fits', coverage: 1.5, effectiveCost: 3, expiring: 0, spend: { '5-hour': 30, weekly: 4 }, account: 'k'.repeat(64) }+ const candidates = [+ { id: 'c0', kind: 'member', agentId: f.worker, machineId: 'test-host', engine: 'claude', model: 'opus', effort: 'high', quality: 3, cost: 3,+ title: 'Worker · Claude opus high · Worker Mac', label: long('Worker · strength 3, cost 3 · fits: weekly 4% of 69%', 540), fit },+ ...Array.from({ length: 12 }, (_, i) => ({ id: `c${i + 1}`, kind: 'new', machineId: 'test-host', engine: 'claude', model: `model-${i}`, effort: 'high',+ quality: 2, cost: 2, title: `New agent · Claude model-${i} high · Worker Mac`, label: long(`New agent · strength 2, cost 2 · candidate ${i}`, 540), fit })),+ ]+ const reasons = Array.from({ length: 5 }, (_, i) => long(`Reason ${i}: Machine is offline or unreachable, or its engine is suspended.`, 100))+ const excluded = Array.from({ length: 47 }, (_, i) => ({ title: long(`New agent · Codex default default · machine-${i}`, 80), reason: reasons[i % 5]! }))+ const decision = { assessment: { difficulty: 'medium', risk: 'low', why: 'Parser work.', size: 'medium', kind: 'parser' },+ candidates, excluded, floor: 1, notes: false, pick: 'c0', via: 'order', p: null, belowFloor: false, why: 'First by strength.' }+ const id = String((await f.execute({ type: 'route.record', conversationId: f.group, decision } as Command, host, f.lead)).result.routeDecisionId)+ const [sizes] = (await db.$runCommandRaw({ aggregate: 'SuperTabRouteDecision', pipeline: [{ $match: { _id: id } },+ { $project: { stored: { $bsonSize: '$record' }, sent: { $bsonSize: { $literal: decision } } } }], cursor: {} }) as+ { cursor: { firstBatch: Array<{ stored: number; sent: number }> } }).cursor.firstBatch+ expect(sizes!.sent).toBeGreaterThan(19_000)+ expect(sizes!.stored, JSON.stringify(sizes)).toBeLessThan(sizes!.sent * 0.6)+ for (const read of [await f.store.routeDecision(owner, f.tab, id), await f.store.routeDecision(host, f.tab, id, f.lead)]) {+ const record = read.record as unknown as typeof decision+ expect(record.candidates.map(c => c.id)).toEqual(candidates.map(c => c.id))+ expect(record.candidates.map(c => c.label)).toEqual([candidates[0]!.label, ...Array(12).fill(undefined)])+ expect(record.candidates.map(({ label: _label, ...c }) => c)).toEqual(candidates.map(({ label: _label, ...c }) => c))+ expect(record.excluded).toHaveLength(47)+ expect(new Set(record.excluded.map(e => JSON.stringify(e)))).toEqual(new Set(excluded.map(e => JSON.stringify(e))))+ expect(read).not.toHaveProperty('record.unavailable')+ }+ await f.assign(id)+ expect(await f.decision(id)).toMatchObject({ final: { kind: 'member', agentId: f.worker }, override: null })+ })+})diff --git a/backend/integration/workerIndexPlans.test.ts b/backend/integration/workerIndexPlans.test.tsindex 6656f6564..4b5309d36 100644--- a/backend/integration/workerIndexPlans.test.ts+++ b/backend/integration/workerIndexPlans.test.ts@@ -151,3 +151,41 @@ describe('the pending-upload sweep', () => {}})})++describe('the operation receipts\' expiry (superTabs/operations.ts)', () => {+ // Mongo's TTL monitor deletes by the expiry index's key, about once a minute: receipts past their 30 days, never a scan.+ it('finds the receipts past their 30 days by the operation_expiry index, reading only those', async () => {+ const { OPERATION_EXPIRY_MS } = await import('../src/superTabs/operations.js')+ const row = (ageMs: number) => ({ id: randomUUID(), tabId: 'tab', actorKey: 'agent:a', requestHash: 'h', revision: 0, result: {}, createdAt: new Date(Date.now() - ageMs) })+ await db.superTabOperation.createMany({ data: [...Array.from({ length: 40 }, () => row(DAY)), ...Array.from({ length: 3 }, () => row(40 * DAY))] })+ const cutoff = new Date(Date.now() - OPERATION_EXPIRY_MS).toISOString()+ const answer = await db.$runCommandRaw({ explain: { find: 'SuperTabOperation', filter: { createdAt: { $lt: { $date: cutoff } } } }, verbosity: 'executionStats' }) as+ { queryPlanner: { winningPlan: unknown }; executionStats: { nReturned: number; totalDocsExamined: number } }+ const winning = JSON.stringify(answer.queryPlanner.winningPlan)+ expect(winning).toMatch(/"stage":"IXSCAN"/)+ expect(winning).toMatch(/"indexName":"operation_expiry"/)+ expect(answer.executionStats.nReturned).toBe(3)+ expect(answer.executionStats.totalDocsExamined).toBe(3)+ })+})++describe('the usage-receipt sweep\'s stuck check (lib/productUsageReceiptSweep.ts lastOldReceipt)', () => {+ // backend/AGENTS.md rule 3: its hourly read while the rule is refused takes one key of the expiry index, never a scan of millions.+ it('reads the newest old receipt by one key of the product_usage_expiry index', async () => {+ const { lastOldReceipt } = await import('../src/lib/productUsageReceiptSweep.js')+ const now = new Date('2026-11-02T03:00:00Z')+ // New receipts (4-day life) and old ones (36-day life): a read the index does not bound examines them all.+ await db.productUsageReceipt.createMany({ data: [+ ...Array.from({ length: 30 }, (_, i) => ({ id: `new-${i}`, expiresAt: new Date(now.getTime() + (i % 4) * DAY), life: 4 })),+ ...Array.from({ length: 30 }, (_, i) => ({ id: `old-${i}`, expiresAt: new Date(now.getTime() + (6 + i) * DAY) })),+ ] })+ let newest: Date | null = null+ const entries = await profiled(db, async () => { newest = await lastOldReceipt(db, now) })+ expect(newest).toEqual(new Date(now.getTime() + 35 * DAY))+ const rows = reads(entries, 'product_usage_receipts', ['expiresAt'])+ expect(rows, JSON.stringify(plan(rows))).toHaveLength(1)+ expect(rows[0]!.planSummary, JSON.stringify(plan(rows))).toMatch(/IXSCAN \{ expiresAt: 1/)+ expect(rows[0]!.keysExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(1)+ expect(rows[0]!.docsExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(1)+ })+})diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prismaindex 3afd618df..40e9a4a7b 100644--- a/backend/prisma/schema.prisma+++ b/backend/prisma/schema.prisma@@ -556,7 +556,8 @@ model ProductUsageTotal {@@index([dayUtc], map: "product_usage_expiry")}-/// Random report receipt, used only to prevent retries counting twice. No identity or report body.+/// Random report receipt, used only to prevent retries counting twice. No identity or report body. Removed at expiresAt by a TTL index+/// (product_usage_expiry); the old 36-day receipts go by 2026-12-04, sooner if the sweep may install its rule (lib/productUsageReceiptSweep.ts).model ProductUsageReceipt {id String @id @map("_id")expiresAt DateTime@@ -1358,6 +1359,7 @@ model SuperTabUploadAllowance {at DateTime}+/// One command's receipt, so a repeat of the same request gets the same answer. Removed 30 days after createdAt by a TTL index.model SuperTabOperation {id String @id @map("_id")tabId String@@ -1370,6 +1372,9 @@ model SuperTabOperation {createdAt DateTime @default(now())@@index([tabId])+ /// A receipt goes 30 days after createdAt (superTabs/operations.ts ensureOperationExpiry). Declared so db push keeps the index; the+ /// schema step makes it, with its expiry, before the push.+ @@index([createdAt], map: "operation_expiry")}// A conversation-scoped provenance receipt. It grants no terminal access.@@ -1485,7 +1490,8 @@ model SuperTabAttempt {@@index([tabId, conversationId, createdAt])}-/// One `harness super-tab route` decision (superTabs/routeRecord.ts). Pruned after 90 days on write.+/// One `harness super-tab route` decision (superTabs/routeRecord.ts). Deleted 90 days after createdAt on each write (routeDecisions.ts+/// RETENTION_MS; the costs report reads 90 days). Stored trimmed (routeRecord.ts storedRecord).model SuperTabRouteDecision {id String @id @map("_id")tabId Stringdiff --git a/backend/src/lib/db/schemaRelease.ts b/backend/src/lib/db/schemaRelease.tsindex 0a6820a6e..d244e95ed 100644--- a/backend/src/lib/db/schemaRelease.ts+++ b/backend/src/lib/db/schemaRelease.ts@@ -6,11 +6,16 @@ import { ensureTerminalExpiry } from '../../superTabs/terminal.js'import { ensureMentionExpiry } from '../../superTabs/mentions.js'import { ensureReadMarkExpiry } from '../../superTabs/readMarks.js'import { ensurePartExpiry } from '../../superTabs/sweeps.js'+import { ensureOperationExpiry } from '../../superTabs/operations.js'import { ensureSchema, type SchemaTarget } from './migrate.js'/** The index work of a release, run by the singleton worker at startup once the legacy unique indexes are gone: the* Prisma schema, then the indexes Prisma cannot describe (expiry, and the keys that must hold before the push). */export async function releaseSchema(db: PrismaClient = prisma, target: SchemaTarget = {}): Promise<void> {+ // Before the push: an expiry index new to a collection that already exists. Built here, by createIndexes, it has its expiry+ // at once and the push keeps it; built by the push, it would need collMod for its expiry, which production's app user may+ // not run (10-29). The indexes below were made before they were declared, so the push has always found them.+ await ensureOperationExpiry(db)await ensureSchema(target)await ensureProductUsageExpiry(db)await ensureHarnessSessionExpiry(db)diff --git a/backend/src/lib/productUsageReceiptSweep.ts b/backend/src/lib/productUsageReceiptSweep.tsindex bf5acaac5..4c682c6a0 100644--- a/backend/src/lib/productUsageReceiptSweep.ts+++ b/backend/src/lib/productUsageReceiptSweep.ts@@ -60,15 +60,27 @@ export async function ensureReceiptRule(db: PrismaClient): Promise<void> {}}-async function anyReceipt(db: PrismaClient, filter: Record<string, unknown>): Promise<boolean> {- const answer = await db.$runCommandRaw({ find: COLLECTION, filter, projection: { _id: 1 }, limit: 1, singleBatch: true } as never) as- { cursor: { firstBatch: unknown[] } }- return answer.cursor.firstBatch.length > 0+/** Old receipts are those past [PRODUCT_USAGE_RECEIPT_EXPIRY_DAYS] + 1 days from today: no new receipt expires that late. */+const oldFloor = (now: Date) => date(startOfDay(now) + (PRODUCT_USAGE_RECEIPT_EXPIRY_DAYS + 1) * DAY)+/** A date as `$runCommandRaw` answers it (extended JSON), or as a Date. */+const dateOf = (value: unknown): Date => {+ const raw = value && typeof value === 'object' && '$date' in value ? (value as { $date: unknown }).$date : value+ const inner = raw && typeof raw === 'object' && '$numberLong' in raw ? Number((raw as { $numberLong: string }).$numberLong) : raw+ return new Date(inner as string | number | Date)+}++/** When the newest old receipt expires by itself: one key of the expiry index, never a count of the millions. Null once no old+ * receipt is left, which is when this sweep has nothing more to do, with or without its rule. */+export async function lastOldReceipt(db: PrismaClient, now: Date): Promise<Date | null> {+ const answer = await db.$runCommandRaw({ find: COLLECTION, filter: { expiresAt: { $gt: oldFloor(now) } }, projection: { _id: 0, expiresAt: 1 },+ sort: { expiresAt: -1 }, hint: 'product_usage_expiry', limit: 1, singleBatch: true } as never) as { cursor: { firstBatch: Array<{ expiresAt: unknown }> } }+ const newest = answer.cursor.firstBatch[0]+ return newest ? dateOf(newest.expiresAt) : null}/** One chunk: up to [chunk] old receipts in expiresAt order, then exactly those, their range checked again. */async function removeChunk(db: PrismaClient, now: Date, chunk: number): Promise<number> {- const range = { expiresAt: { $gt: date(startOfDay(now) + (PRODUCT_USAGE_RECEIPT_EXPIRY_DAYS + 1) * DAY),+ const range = { expiresAt: { $gt: oldFloor(now),$lte: date(now.getTime() + (OLD_EXPIRY_DAYS - PRODUCT_USAGE_RECEIPT_EXPIRY_DAYS) * DAY) } }const found = await db.$runCommandRaw({ find: COLLECTION, filter: range, projection: { _id: 1 }, sort: { expiresAt: 1 },hint: 'product_usage_expiry', limit: chunk, singleBatch: true } as never) as { cursor: { firstBatch: Array<{ _id: string }> } }@@ -90,16 +102,17 @@ export async function sweepOldReceipts(db: PrismaClient, now = new Date(), optioremoved += nif (n < options.chunk) break}- const done = !await anyReceipt(db, { expiresAt: { $gt: date(startOfDay(now) + (PRODUCT_USAGE_RECEIPT_EXPIRY_DAYS + 1) * DAY) } })- return { removed, done }+ return { removed, done: !await lastOldReceipt(db, now) }}/** Runs a pass a minute in the singleton worker until nothing is left to remove, then stops; a restart checks once more.- * While the database refuses the rule, nothing is removed: it says so once and asks again every [refusedEveryMs]. */+ * While the database refuses the rule, nothing is removed: each hourly check logs an error saying so and when the old receipts+ * expire by themselves (a single warning at start went unseen from 10-29 to 11-03, task #2488), and once none is left the+ * sweep stops, rule or not: Mongo's expiry has done its work. */export function startReceiptSweep(db: PrismaClient, settings: Partial<SweepOptions & { everyMs: number; refusedEveryMs: number;- now: () => Date; log: Pick<typeof logger, 'info' | 'warn'> }> = {}): () => void {+ now: () => Date; log: Pick<typeof logger, 'info' | 'warn' | 'error'> }> = {}): () => void {const { everyMs, refusedEveryMs, now, log, ...options } = { ...RECEIPT_SWEEP, now: () => new Date(), log: logger, ...settings }- let running = false, total = 0, refusedUntil = 0, warned = false+ let running = false, total = 0, refusedUntil = 0const run = async () => {if (running || now().getTime() < refusedUntil) returnrunning = true@@ -114,8 +127,13 @@ export function startReceiptSweep(db: PrismaClient, settings: Partial<SweepOptio} catch (error) {if (error instanceof ReceiptRuleRefused) {refusedUntil = now().getTime() + refusedEveryMs- if (!warned) log.warn('[usage-receipts] waiting: the database user may not install the receipt rule (collMod); nothing is removed, checking hourly')- warned = true+ const last = await lastOldReceipt(db, now()).catch(() => undefined)+ if (last === null) {+ stop()+ log.info('[usage-receipts] done: no old receipts left', { removedSinceStart: total })+ return+ }+ log.error(`[usage-receipts] stuck: the database user may not install the receipt rule (collMod), so nothing is removed. The old receipts expire by themselves by ${last ? last.toISOString().slice(0, 10) : 'a date it could not read'}; grant collMod to finish sooner. Checking hourly.`)return}log.warn('[usage-receipts] pass failed; retrying next minute', { error: error instanceof Error ? error.message : String(error) })diff --git a/backend/src/superTabs/operations.ts b/backend/src/superTabs/operations.tsnew file mode 100644index 000000000..633a2c330--- /dev/null+++ b/backend/src/superTabs/operations.ts@@ -0,0 +1,15 @@+/** Operation receipts (SuperTabOperation): one per command, terminal event and recovery, read back only to answer a repeat of+ * the same request, to pair a terminal prompt with its answer, and to date a start. None of those needs a receipt older than+ * a prompt left waiting, so a TTL index removes each 30 days after it was written (task #2488, Ken 2026-11-03: ~14k a day). */+import type { PrismaClient } from '@prisma/client'+import { ensureIndex } from '../lib/db/indexes.js'++/** A receipt is kept this long: long enough for a prompt waiting on its answer, and for any repeat of an interrupted request. */+export const OPERATION_EXPIRY_MS = 30 * 24 * 60 * 60_000++/** Run by the release's schema step before db push (lib/db/schemaRelease.ts), so the index is built with its expiry by+ * createIndexes, which production's app user may run, rather than built plain by the push and given its expiry by collMod,+ * which it may not (10-29). */+export async function ensureOperationExpiry(db: PrismaClient): Promise<void> {+ await ensureIndex(db, 'SuperTabOperation', { key: { createdAt: 1 }, name: 'operation_expiry', expireAfterSeconds: OPERATION_EXPIRY_MS / 1000 })+}diff --git a/backend/src/superTabs/routeDecisions.test.ts b/backend/src/superTabs/routeDecisions.test.tsindex 75deed58f..6f5cfd0c1 100644--- a/backend/src/superTabs/routeDecisions.test.ts+++ b/backend/src/superTabs/routeDecisions.test.ts@@ -1,5 +1,11 @@import { describe, expect, it } from 'vitest'import { closeAssignment, recordAttempts, writeRouteEffects } from './routeDecisions.js'+import type { RouteRecord } from './routeRecord.js'++/** A record as route.record validates it (routeRecord.ts routeRecordSchema): both lists are always there. */+const RECORD: RouteRecord = { assessment: { difficulty: 'low', risk: 'low', why: 'Fixture.' }, candidates: [{ id: 'c0', kind: 'new', machineId: 'machine',+ engine: 'claude', model: 'opus', effort: 'high', quality: 3, cost: 3, title: 'New agent', label: 'New agent' }], excluded: [], floor: 1, notes: false,+ pick: 'c0', via: 'only', p: null, belowFloor: false, why: 'Only candidate.' }type Row = Record<string, unknown> & { id: string; tabId: string; conversationId: string; outcome?: string | null }@@ -51,7 +57,7 @@ describe('route decision persistence', () => {{ id: 'other-group', tabId: 'tab', conversationId: 'other', final: null, assignmentId: null, outcome: null },]const tx = memoryTx(rows)- await writeRouteEffects(tx, 'tab', [{ op: 'create', id: 'next', conversationId: 'group', record: {} as never }], now)+ await writeRouteEffects(tx, 'tab', [{ op: 'create', id: 'next', conversationId: 'group', record: RECORD }], now)const outcome = (id: string) => rows.find(row => row.id === id)?.outcome ?? nullexpect(outcome('proposal')).toBe('superseded')expect(outcome('unset-proposal')).toBe('superseded')diff --git a/backend/src/superTabs/routeDecisions.ts b/backend/src/superTabs/routeDecisions.tsindex 51c85654a..f028b3b2f 100644--- a/backend/src/superTabs/routeDecisions.ts+++ b/backend/src/superTabs/routeDecisions.ts@@ -5,7 +5,7 @@ import { readBy } from './parts/indexed.js'import type { SuperTabState } from './model.js'import { attemptChanges, endRun, startRun, type RouteRun } from './costs/attempts.js'import type { TokensByModel } from './costs/tokens.js'-import { finalMatches, type RouteDecision, type RouteDecisionEffect, type RouteFinal, type RouteOverride, type RouteRecord } from './routeRecord.js'+import { finalMatches, readRecord, storedRecord, type RouteDecision, type RouteDecisionEffect, type RouteFinal, type RouteOverride, type RouteRecord } from './routeRecord.js'type Tx = Prisma.TransactionClientconst json = (value: unknown): Prisma.InputJsonValue => JSON.parse(JSON.stringify(value)) as Prisma.InputJsonValue@@ -14,7 +14,7 @@ const open: Prisma.SuperTabRouteDecisionWhereInput = { OR: [{ outcome: null }, {export const RETENTION_MS = 90 * 24 * 60 * 60_000export const decisionOf = (row: SuperTabRouteDecision): RouteDecision => ({- id: row.id, conversationId: row.conversationId, record: row.record as unknown as RouteRecord,+ id: row.id, conversationId: row.conversationId, record: readRecord(row.record as unknown as RouteRecord),final: (row.final ?? null) as unknown as RouteFinal | null, override: (row.override ?? null) as unknown as RouteOverride | null,assignmentId: row.assignmentId, outcome: row.outcome, run: (row.run ?? null) as unknown as RouteRun | null,})@@ -73,7 +73,7 @@ export async function writeRouteEffects(tx: Tx, tabId: string, effects: RouteDecif (unusedIds.length) await tx.superTabRouteDecision.updateMany({ where: { tabId, conversationId: effect.conversationId,id: { in: unusedIds }, ...open }, data: { outcome: 'superseded', outcomeAt: new Date(now) } })await tx.superTabRouteDecision.create({ data: { id: effect.id, tabId, conversationId: effect.conversationId,- record: json(effect.record), createdAt: new Date(now) } })+ record: json(storedRecord(effect.record)), createdAt: new Date(now) } })await tx.superTabRouteDecision.deleteMany({ where: { tabId, createdAt: { lt: new Date(now - RETENTION_MS) } } })} else if (effect.op === 'override') {await tx.superTabRouteDecision.update({ where: { id: effect.id }, data: { override: json(effect.override) } })diff --git a/backend/src/superTabs/routeRecord.test.ts b/backend/src/superTabs/routeRecord.test.tsindex e975b71d3..4c8b14bc7 100644--- a/backend/src/superTabs/routeRecord.test.ts+++ b/backend/src/superTabs/routeRecord.test.ts@@ -1,5 +1,5 @@import { describe, expect, it } from 'vitest'-import { routeRecordSchema } from './routeRecord.js'+import { readRecord, routeRecordSchema, storedRecord, type RouteRecord } from './routeRecord.js'const candidate = (i: number) => ({ id: `c${i}`, kind: 'new', machineId: `m${i}`, engine: 'claude', model: 'opus', effort: 'high', quality: 3, cost: 3,title: `New agent · Claude opus high · m${i}`, label: `New agent · Claude opus high · m${i}` })@@ -15,3 +15,48 @@ describe('route.record', () => {expect(routeRecordSchema.safeParse(record(65)).success).toBe(false)})})++describe('a route decision as stored (task #2488: ~20 KB a row since every engine on every machine)', () => {+ const routed = () => {+ const r = record(3) as unknown as RouteRecord+ r.pick = 'c1'+ r.candidates = r.candidates.map(c => ({ ...c, label: `${c.title} · strength 3, cost 3 · fits: weekly 4% of 69%`,+ fit: { status: 'fits' as const, coverage: 2, effectiveCost: 3, expiring: 0, spend: { weekly: 1 } } }))+ r.excluded = [['a', 'offline'], ['b', 'suspended'], ['c', 'offline'], ['d', 'offline'], ['e', 'suspended'], ['f', 'offline']]+ .map(([machine, reason]) => ({ title: `New agent · Codex default default · ${machine}`, reason: reason === 'offline' ? 'Machine is offline or unreachable.' : 'Codex is suspended on this machine.' }))+ return r+ }++ it('keeps the label of the pick only, and every other candidate field', () => {+ const r = routed(), stored = storedRecord(r)+ expect(stored.candidates.map(c => c.label)).toEqual([undefined, r.candidates[1]!.label, undefined])+ expect(stored.candidates.map(({ label: _label, ...c }) => c)).toEqual(r.candidates.map(({ label: _label, ...c }) => c))+ })++ it('keeps each exclusion reason once, with its titles in order', () => {+ const stored = storedRecord(routed())+ expect(stored.excluded).toBeUndefined()+ expect(stored.unavailable).toEqual([+ { reason: 'Machine is offline or unreachable.', titles: ['a', 'c', 'd', 'f'].map(m => `New agent · Codex default default · ${m}`) },+ { reason: 'Codex is suspended on this machine.', titles: ['b', 'e'].map(m => `New agent · Codex default default · ${m}`) },+ ])+ })++ it('reads back as the record readers get, its exclusions grouped by reason', () => {+ const r = routed()+ const back = readRecord(storedRecord(r))+ expect(back.candidates).toEqual(storedRecord(r).candidates)+ expect(back.excluded.map(e => e.title.slice(-1))).toEqual(['a', 'c', 'd', 'f', 'b', 'e'])+ expect(new Set(back.excluded.map(e => JSON.stringify(e)))).toEqual(new Set(r.excluded.map(e => JSON.stringify(e))))+ expect(back).not.toHaveProperty('unavailable')+ })++ it('reads a record written before as it is, and stores a record with no exclusions with none', () => {+ const old = routed()+ expect(readRecord(old)).toEqual(old)+ const none = { ...routed(), excluded: [] }+ expect(storedRecord(none)).not.toHaveProperty('unavailable')+ expect(storedRecord(none).excluded).toEqual([])+ expect(readRecord(storedRecord(none)).excluded).toEqual([])+ })+})diff --git a/backend/src/superTabs/routeRecord.ts b/backend/src/superTabs/routeRecord.tsindex fdb0eb75c..0cd83905e 100644--- a/backend/src/superTabs/routeRecord.ts+++ b/backend/src/superTabs/routeRecord.ts@@ -73,6 +73,32 @@ export const routeRecordSchema = z.object({}).strict().refine(d => d.candidates.some(c => c.id === d.pick), 'The pick must be one of the candidates.').refine(d => new Set(d.candidates.map(c => c.id)).size === d.candidates.length, 'Candidate ids must be unique.')+/** A record as stored (routeDecisions.ts): the pick keeps its label, and the exclusions are kept once per reason. On production+ * (2026-11-03) labels were 5.4 KB of a 20.9 KB row and exclusions 8.9 KB, 47 of them sharing ~5 reasons (task #2488). Rows+ * written before keep `excluded` and no `unavailable`. */+export interface StoredRouteRecord extends Omit<RouteRecord, 'excluded'> {+ excluded?: RouteRecord['excluded']+ unavailable?: Array<{ reason: string; titles: string[] }>+}++/** What a decision keeps of [record]: a label only on the pick (the route showed the others when it ran; Desktop's Details shows+ * a candidate's label only when it has one), and each exclusion reason once, with its titles in order. */+export function storedRecord(record: RouteRecord): StoredRouteRecord {+ const { excluded, ...rest } = record+ const candidates = record.candidates.map(({ label, ...c }) => c.id === record.pick ? { ...c, label } : c) as RouteCandidate[]+ const byReason = new Map<string, string[]>()+ for (const { title, reason } of excluded) byReason.set(reason, [...byReason.get(reason) ?? [], title])+ return { ...rest, candidates, ...byReason.size ? { unavailable: [...byReason].map(([reason, titles]) => ({ reason, titles })) } : { excluded: [] } }+}++/** Either stored form back as readers get a record: `unavailable` expanded into `excluded`, reason by reason in the order each+ * first appeared. A record written before this is returned as it is. */+export function readRecord(stored: StoredRouteRecord | RouteRecord): RouteRecord {+ if (!('unavailable' in stored) || !stored.unavailable) return stored as RouteRecord+ const { unavailable, ...rest } = stored+ return { ...rest, excluded: unavailable.flatMap(({ reason, titles }) => titles.map(title => ({ title, reason }))) } as RouteRecord+}+/*** Whether a started agent is the candidate's: the same machine, engine, and the model and effort that were* requested. After a failed switch `final` holds what ran, so the request is the one that names the candidate.diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex cfcf8923d..dc23b081e 100644--- a/backend/src/superTabs/store.ts+++ b/backend/src/superTabs/store.ts@@ -64,7 +64,7 @@ import { freeze, readStamps, stampOwed, swarmReadCache, swarmTransaction, type Cimport { countReport, DEADLINE_CAP_MS, localReportMemory, RECORD_TTL_MS, type ReportMemory, type ReportRecord } from './machineReports.js'import { DIRECT, readLastChangedAt, readParts, type ReadNamed } from './cachedReads.js'import { revokeNativeContexts, SuperTabNativeStore } from './native.js'-import { activeMember, addMember, autoJoinDeclinedBy, hasWorkspaceAccess, listWorkspaces, memberId, WORKSPACE_ACCESS_REVOKED, workspaceForNewSwarm, requireWorkspaceAccess, requireWorkspaceRole, SwarmWorkspaces } from './workspaceStore.js'+import { activeMember, addMember, hasWorkspaceAccess, listWorkspaces, memberId, removedFromWorkspace, WORKSPACE_ACCESS_REVOKED, workspaceForNewSwarm, requireWorkspaceAccess, requireWorkspaceRole, SwarmWorkspaces } from './workspaceStore.js'import { WORKSPACE_LABEL, type WorkspaceRole } from './workspaces.js'import { STATUS_LABELS,activeWork, actorKey, agent, agentOnly, appendPullRequestUrls, author, conversation, createSuperTab, fail, person, stableId, visibleState, finishWorker,@@ -292,6 +292,11 @@ const addsAgent = (state: SuperTabState, actor: Actor, command: Command): booleareturn !group || [actor.agentId, ...command.recipientIds].some(id => !group.agentIds.includes(id))}+/** A join by link or its preview, refused to someone the Workspace removed (removedFromWorkspace). */+function failRemovedFromWorkspace(): never {+ fail(WORKSPACE_ACCESS_REVOKED, `You were removed from this Swarm's ${WORKSPACE_LABEL}. Ask its owner to invite you.`, 403)+}+/** Starts on a not-yet-contributed machine that never dispatched, dated by their own operation receipt (starts carry no* time of their own). A dispatched start may have a native session coming, so it is never counted. */async function abandonedStarts(tx: Transaction, tabId: string, state: SuperTabState, machineId: string, now: number) {@@ -1070,10 +1075,9 @@ export class SuperTabStore {state.autoJoinDeclined?.includes(user.sub) || state.people.length >= AUTO_JOIN_CAP) return 'skipped' as constconst stamp = clock.next(), generation = stableId('auto-join', tabId, user.sub, String(stamp))if (state.workspaceId) {- // As a link join: a guest of the Workspace, never higher; someone active there keeps their role (addMember).- const prior = await tx.swarmWorkspaceMember.findUnique({ where: { id: memberId(state.workspaceId, user.sub) } })- // Removed from the Workspace: its row says so until purged, and the Workspace's own decline after that.- if (prior?.removedAt || (!prior && await autoJoinDeclinedBy(tx, state.workspaceId, user.sub))) return 'revoked' as const+ // As a link join: a guest of the Workspace, never higher; someone active there keeps their role (addMember). Someone the+ // Workspace removed is never added back this way (removedFromWorkspace).+ if (await removedFromWorkspace(tx, state.workspaceId, user.sub)) return 'revoked' as constawait addMember(tx, state.workspaceId, { id: user.sub, email }, 'guest', state.ownerId, generation)}state.people.push({ id: user.sub, email, role: state.sharing!.access.role, generation, joinedVia: 'domain' })@@ -1191,6 +1195,8 @@ export class SuperTabStore {const { state } = await this.load(tx, user, tabId)const sharing = authorizeSwarmJoin(state, user.email, token, user.sub)const member = state.people.find(p => p.id === user.sub)+ // What join refuses, its preview refuses alike: it never offers a join that cannot happen.+ if (!member && state.workspaceId && await removedFromWorkspace(tx, state.workspaceId, user.sub)) failRemovedFromWorkspace()return { id: tabId, name: state.name, role: member?.role ?? sharing.access.role, alreadyMember: !!member }})}@@ -1217,9 +1223,8 @@ export class SuperTabStore {const alreadyMember = !!memberif (!member && state.workspaceId) {// A link or an email domain makes a guest of the Workspace, never higher. Someone the Workspace removed comes back only by- // an invitation, never by a general link (design, Roles).- const prior = await tx.swarmWorkspaceMember.findUnique({ where: { id: memberId(state.workspaceId, user.sub) } })- if (prior?.removedAt) fail(WORKSPACE_ACCESS_REVOKED, `You were removed from this Swarm's ${WORKSPACE_LABEL}. Ask its owner to invite you.`, 403)+ // an invitation, never by a general link (design, Roles), also once the purge deleted their member row (task #2510).+ if (await removedFromWorkspace(tx, state.workspaceId, user.sub)) failRemovedFromWorkspace()await addMember(tx, state.workspaceId, { id: user.sub, email: user.email }, 'guest', state.ownerId, receiptId)}if (!member) {diff --git a/backend/src/superTabs/workspaceStore.ts b/backend/src/superTabs/workspaceStore.tsindex a21c6bdb3..de84a5049 100644--- a/backend/src/superTabs/workspaceStore.ts+++ b/backend/src/superTabs/workspaceStore.ts@@ -85,6 +85,14 @@ export async function autoJoinDeclinedBy(tx: Transaction, workspaceId: string, ureturn !!workspace?.autoJoinDeclined.includes(userId)}+/** Whether this Workspace removed `userId` and nothing brought them back: their member row says so until it is purged, and the+ * Workspace's decline after that (autoJoinDeclinedBy, never purged). Such a person comes back only by an invitation, never by+ * a link or an email domain (design, Roles; task #2510). */+export async function removedFromWorkspace(tx: Transaction, workspaceId: string, userId: string): Promise<boolean> {+ const prior = await tx.swarmWorkspaceMember.findUnique({ where: { id: memberId(workspaceId, userId) } })+ return !!prior?.removedAt || (!prior && await autoJoinDeclinedBy(tx, workspaceId, userId))+}+async function clearAutoJoinDecline(tx: Transaction, workspaceId: string, userId: string): Promise<void> {const workspace = await tx.swarmWorkspace.findUnique({ where: { id: workspaceId }, select: { autoJoinDeclined: true } })if (workspace?.autoJoinDeclined.includes(userId)) {diff --git a/docs/plans/2026-11-03-database-retention-plan.md b/docs/plans/2026-11-03-database-retention-plan.mdnew file mode 100644index 000000000..6b2e4926c--- /dev/null+++ b/docs/plans/2026-11-03-database-retention-plan.md@@ -0,0 +1,223 @@+# Database retention: every growing collection names what removes it — implementation plan++> Worked by this project's instructions (Engineer role), by the writing-plans and test-driven-development skills: this+> plan is the pull request's first commit. Then each task is done test first (a commit with the failing test, then the+> commit that passes it), by one Engineer, with one Review step on the pull request against MongoDB's schema-design and+> query-optimizer skills. Steps use checkbox (`- [x]`) syntax.++**Goal:** the four collections Ken measured growing with nothing removing them each name what does: operation receipts+expire after 30 days, a route decision keeps about a third of what it keeps now, the stuck usage-receipt sweep says so+every hour until its receipts are gone, and backend/AGENTS.md holds the rules that keep the next collection from growing+the same way.++**Architecture:** a TTL index `operation_expiry` on `SuperTabOperation.createdAt` (30 days), made by the release's schema+step *before* `prisma db push`, so it is built with its expiry by `createIndexes`, which production's app user may run,+instead of built plain by the push and then refused its expiry by `collMod`, which it may not (10-29). A route decision is+trimmed where it is written (`routeDecisions.ts writeRouteEffects`, by a pure `storedRecord` in `routeRecord.ts`): only+the pick keeps its candidate label, and the exclusions are kept once per reason; every read (`decisionOf`) expands them+back, so each reader sees the shape it reads today. The usage-receipt sweep, while the database refuses its rule, logs an+error each hourly check with when its old receipts expire on their own, and stops once none are left.++**Tech Stack:** backend TypeScript, Prisma 5 on MongoDB 7, vitest (unit tests in `src/`, integration tests in+`integration/` on a loopback `mongodb-memory-server` replica set; the Super Tab suite runs in PR CI, four shards).++**Spec:** task #2488 brief (Ken, through the PM, 2026-11-03). Measured on the read-only production database at the start+(2026-11-03 13:15 UTC):++| Collection | Rows | Data | Index | Growth | Removed by |+| --- | --- | --- | --- | --- | --- |+| SuperTabOperation | 120,014 | 48.2 MB (401 B a row) | 6.0 MB | 14,037 in the last day | nothing |+| SuperTabRouteDecision | 5,518 | 67.6 MB (20.9 KB a row in the last 2 days) | 0.8 MB | 628 in the last day | delete past 90 days, on write |+| product_usage_receipts | 5,156,191 | 376.4 MB | 614.7 MB (`_id_` 576 MB) | ~275k a day, live 4 days | TTL `product_usage_expiry` (expireAfterSeconds 0) |++- Operations: oldest 2026-10-19; none older than 30 days, 235 older than 14 days. In the last 7 days 97,897 were agent+ commands, 4,932 person commands and 138 native terminal events.+- Route decisions (last 2 days, average bytes): record 20,018, of which candidate labels 5,360 (13 candidates, up to 31),+ candidate fits 2,147, exclusions 8,883 (47 entries a row, 4.8 distinct reasons; the distinct reasons are 578 bytes);+ run 202, evidence 255. Largest row 42.5 KB.+- Usage receipts: the TTL index is there and works (2 past expiry at the time of reading); 4,054,561 receipts carry no+ `life` (written while a receipt lived 36 days) and the last of them expires 2026-12-04. The collection has no rule+ (`options: {}`), so the sweep from #2145 has removed nothing: it waits on `collMod`, which the app user may not run.++## Global Constraints++- PR body first line: "Requested by [email protected] through Harness."+- Database work follows MongoDB's schema-design and query-optimizer skills; the Reviewer checks against them.+- Measure on the read-only production database before and after, through its environment file only, never printed.+- The TTL index is a production write made by the backend release's schema step: it ships only with Ken's go for that+ release, in the day window (09:00–18:00 VN), watching backend CPU and latency before and after. No forced bulk delete+ anywhere: the usage receipts expire by themselves.+- The full Super Tab integration suite runs in PR CI; nobody runs it locally. Merge goes through the PM's batch.+- Out of scope: messages (kept forever), finished deliveries (already compacted after 14 days).+- Swarm code stays out of cli/src/core. Temp files only in mktemp -d folders. Stop only processes I started, by id.++## Review Focus++- The order of the schema step: the new expiry index must exist, with its expiry, after a release run by a database user+ who may not run `collMod`; and a release with nothing changed must change no index (schemaRelease.test.ts).+- 30 days against every reader of an operation receipt (below): none needs one older than a waiting prompt.+- A trimmed route decision still answers every reader as before: start/assign matching (`startedAs`, `finalMatches`), the+ person's override, costs, Desktop's Details. Old rows (untrimmed) read unchanged.+- The sweep's error is loud but not a flood: once an hour, one line.++## Design++- **Growth — what deletes it:** operations: the TTL index, 30 days after `createdAt` (~14k a day → ~420k rows, ~170 MB+ data at steady state). Route decisions: still the 90-day delete on write (the costs report reads 90 days, `costs/read.ts+ MAX_DAYS`, so a 30-day prune would cut it), now at ~12.9 KB a row instead of ~24.5 KB (the trim applied to the last+ day's 622 production rows, read-only, 2026-11-03): ~0.7 GB at 90 days instead of ~1.35 GB. Usage+ receipts: their TTL; the 4.05M old ones are gone by 2026-12-04, sweep or not.+- **Concurrency — lock level:** the TTL monitor deletes as ordinary document deletes (document-level locks). The index+ build takes the collection's exclusive lock only to begin and to finish (Mongo 4.2+ hybrid build), over 120k rows of+ ~400 B (seconds). Every command reads its receipt in a transaction, which waits at most 5 ms for a lock: a command+ caught at either moment fails transiently and the store's `transaction()` retries it, as the 10-28 test of the schema+ step shows for Swarm reads. The route decision trim happens in the same write as today, no new lock.+- **Read cost — read only what changed:** no new read. The sweep's hourly stuck check reads one index key (the newest old+ receipt, by `product_usage_expiry`), never a count of millions.+- **Scale — 10x, and the metric that warns first:** at 10x operations (140k a day), 1.4M rows and ~1.7 GB at 30 days:+ the `SuperTabOperation` data size in dbStats warns first; the TTL deletes ~100 a minute, well within the monitor's pace.+ At 10x route decisions, 4 GB at 90 days: its collection size warns first; the next step is compacting rows older than+ N days (as deliveries are), not cutting the costs window.+- **Compatibility — old and new clients:** clients read decisions through the backend, which expands the stored form, so+ Desktop, the CLI and the phone see `record.excluded[]` and `record.candidates[]` as before; a non-pick candidate has no+ `label`, which Desktop already treats as optional (`route_row.dart`: `if (c['label'] case final String label)`), and the+ CLI never reads a stored label. Rows written before this keep their full form and read unchanged.+- **Migration + rollback:** no data migration; the TTL index is made by the release. Rolled back, an older backend reads a+ trimmed decision with no `excluded` (the Details of Desktop, `route_row.dart`, and the phone, `swarm_special_rows.dart`, then+ list no unavailable machines; nothing else reads it) and+ db push of the older schema drops `operation_expiry` (receipts then grow again, nothing breaks).+- **Audience — the server enforces it:** unchanged: decisions are read by the same readable-conversation filter.+- **Identity:** N/A because no identity is read or written.+- **Failure — nothing breaks without saying so:** if the index cannot be made, `createIndexes` fails the schema step as any+ index does today (loud). If an expiry change is refused, `ensureIndex` warns, as today. The stuck sweep logs an error+ every hour it cannot run, with the date its receipts expire by.+- **Platforms:** backend only (Linux containers); no client change.++### Who reads an operation receipt, and after how long++| Reader | Reads | Without a receipt older than 30 days |+| --- | --- | --- |+| Command replay (`store.ts` execute, agent and person) | its own receipt, by operation id | a request repeated 30 days later runs as new (an operation id is reused only to repeat an interrupted request) |+| Swarm create, sharing, join (`store.ts`) | same | same; a Swarm create repeated after 30 days fails on its existing id instead of answering it |+| Native terminal events (`native.ts append`) | the event's own receipt; an answer's prompt receipt | a prompt answered more than 30 days later is refused as missing (NATIVE_PROMPT_MISSING): the CLI then stops recording that terminal until someone reopens it from the conversation (`cli/src/superTabs/native.ts`) |+| Native recovery (`native.ts recovery`) | one per incident | an incident reported again after 30 days alarms again |+| Abandoned starts (`store.ts abandonedStarts`) | a start's receipt, for its time | an unknown time counts as old: a start 30 days old is abandoned, as it should be |+| Migration fingerprint (`migration/fingerprint.ts`) | a count, before and after, in one transaction | the snapshot is one transaction's, so a TTL delete between them does not show |++## File Structure++- `backend/prisma/schema.prisma` — declare `@@index([createdAt], map: "operation_expiry")` on SuperTabOperation; name what+ removes each of the three collections in its model comment.+- `backend/src/superTabs/operations.ts` (new) — `OPERATION_EXPIRY_MS` and `ensureOperationExpiry(db)`.+- `backend/src/lib/db/schemaRelease.ts` — run the expiry indexes of collections that exist before their index (today:+ operations) *before* `ensureSchema`.+- `backend/src/superTabs/routeRecord.ts` — `storedRecord(record)` and `readRecord(stored)`.+- `backend/src/superTabs/routeDecisions.ts` — write `storedRecord`, read through `readRecord` in `decisionOf`.+- `backend/src/lib/productUsageReceiptSweep.ts` — the loud refusal and the self-stop.+- `backend/AGENTS.md` (new) — the five MongoDB rules; `backend/CLAUDE.md` imports it, as `cli/` and `desktop/` do.+- Tests: `backend/integration/schemaRelease.test.ts`, `backend/integration/workerIndexPlans.test.ts`,+ `backend/src/superTabs/routeRecord.test.ts`, `backend/integration/superTabCosts.test.ts` (it records routes through the+ store and reads them back; `superTabRouteDecisions.test.ts` writes rows directly),+ `backend/integration/productUsageReceipts.test.ts`.++## Task 1: operation receipts expire after 30 days++**Files:** `backend/prisma/schema.prisma`, `backend/src/superTabs/operations.ts`, `backend/src/lib/db/schemaRelease.ts`,+`backend/integration/schemaRelease.test.ts`, `backend/integration/workerIndexPlans.test.ts`.++**Interfaces:**++```ts+// backend/src/superTabs/operations.ts+/** A command's receipt is kept this long: long enough for a prompt waiting on its answer, and for any repeat of an interrupted request. */+export const OPERATION_EXPIRY_MS = 30 * 24 * 60 * 60_000+/** Run by the release's schema step before db push, so the index is built with its expiry (createIndexes) rather than given it later (collMod). */+export async function ensureOperationExpiry(db: PrismaClient): Promise<void>+// = ensureIndex(db, 'SuperTabOperation', { key: { createdAt: 1 }, name: 'operation_expiry', expireAfterSeconds: OPERATION_EXPIRY_MS / 1000 })+```++- [x] In `schemaRelease.test.ts`, add `['SuperTabOperation', 'operation_expiry', { createdAt: 1 }, 30 * DAY]` to `EXPIRY`,+ and add the test "gives an existing collection its new expiry index when the database user may not run collMod (prod+ 10-29)": release with the schema as it was (the declared `operation_expiry` line removed, by `schemaWith`), insert an+ operation, then release the current schema through a client whose `$runCommandRaw` refuses `collMod` with Mongo's code+ 13 (as `productUsageReceipts.test.ts` does); expect `operation_expiry` with `expireAfterSeconds` 2,592,000, and+ `indexChanges` to be exactly `['createIndexes SuperTabOperation operation_expiry']` (built once, by the worker).+- [x] In `workerIndexPlans.test.ts`, add "the operation expiry reads receipts by their age": seed operations a day and 40+ days old, `explain` the TTL monitor's shape `find({ createdAt: { $lt: cutoff } })` and expect `IXSCAN { createdAt: 1 }`+ on `operation_expiry`, with docsExamined equal to the old rows.+- [x] Run both files; watch them fail (no such index). Commit "test: operation receipts expire after 30 days (red)".+- [x] Add `operations.ts`, the schema line with its comment, and `ensureOperationExpiry` first in `releaseSchema`, before+ `ensureSchema`, with a comment saying why. Run both files and `npm test -- src/lib/db`; green. Commit.++## Task 2: a route decision keeps the pick's label and each exclusion reason once++**Files:** `backend/src/superTabs/routeRecord.ts`, `backend/src/superTabs/routeDecisions.ts`,+`backend/src/superTabs/routeRecord.test.ts`, `backend/integration/superTabCosts.test.ts`.++**Interfaces:**++```ts+// backend/src/superTabs/routeRecord.ts+/** The record as stored: a label on the pick only, and exclusions grouped by reason. */+export interface StoredRouteRecord extends Omit<RouteRecord, 'excluded'> { excluded?: RouteRecord['excluded']; unavailable?: Array<{ reason: string; titles: string[] }> }+export function storedRecord(record: RouteRecord): StoredRouteRecord+/** Either form back to the record readers get: `unavailable` expanded into `excluded` (grouped order: by first appearance of+ * each reason, then the titles in their order). A record with `excluded` (written before) is returned as it is. */+export function readRecord(stored: StoredRouteRecord | RouteRecord): RouteRecord+```++- [x] `routeRecord.test.ts`: a record with 3 candidates (pick `c1`) and 6 exclusions of 2 reasons: `storedRecord` keeps+ `label` on `c1` only, every other candidate field intact; `unavailable` has 2 entries; `readRecord(storedRecord(r))`+ equals `r` with the non-pick labels removed and the exclusions in grouped order (the read record is not checked+ against the input schema, which requires every label: nothing parses a stored record with it); `readRecord` of an old record returns it+ unchanged; a record with no exclusions stores none.+- [x] `superTabCosts.test.ts`: record a route of 13 candidates and 47 exclusions of 5 reasons, sized like+ production's (labels of ~540 characters, reasons of ~100, titles of ~80); the stored record's `$bsonSize` is under 60%+ of the record sent, the decision read by `GET /route-decisions/:id` lists all 31 candidates and all 47 exclusions with their titles+ and reasons, and starting the pick still links to it (`final` set, no override).+- [x] Run both; watch them fail. Commit the red tests.+- [x] Implement `storedRecord` and `readRecord`; write `storedRecord(effect.record)` in `writeRouteEffects`, read+ `readRecord(row.record)` in `decisionOf`. Run both, `npm test -- src/superTabs/routeRecord.test.ts`, and the route and+ costs integration files; green. Commit.++## Task 3: the stuck usage sweep says so every hour, and stops once nothing is left++**Files:** `backend/src/lib/productUsageReceiptSweep.ts`, `backend/integration/productUsageReceipts.test.ts`.++**Interfaces:**++```ts+// backend/src/lib/productUsageReceiptSweep.ts+/** The newest old receipt's expiry (one index key by product_usage_expiry), or null when none is left. */+export async function lastOldReceipt(db: PrismaClient, now: Date): Promise<Date | null>+// startReceiptSweep's log gains `error`; while refused, each hourly check:+// null → stop; info '[usage-receipts] done: no old receipts left'+// date → error '[usage-receipts] stuck: the database user may not install the receipt rule (collMod); nothing is removed. The old receipts expire by themselves by <ISO date>; grant collMod to finish sooner.'+```++- [x] Change the existing refusal test ("a database user that may not install the rule gets one warning…") to expect one+ error line per hourly check (two after an hour), naming 2026-… the newest old receipt's expiry, and none between checks;+ add "a refused sweep stops by itself once its old receipts have expired": no old receipt left → one `done` line, no+ further `collMod` tries.+- [x] Run the file; watch them fail. Commit the red tests.+- [x] Implement. Run the file and `npm test -- src/lib`; green. Commit.++## Task 4: backend/AGENTS.md++**Files:** `backend/AGENTS.md` (new), the three model comments in `backend/prisma/schema.prisma`.++- [x] Write the five rules, short, each with its reason and an example from this task: (1) every collection names what+ removes it, in its model comment (a TTL, a sweep, a delete on write, or "kept forever: why"); (2) receipt and log rows get+ a TTL index, made by the schema step before db push (`ensureIndex`, the operations example); (3) one index per query,+ checked with explain in an integration test (`plans.test-support.ts`); (4) a maintenance job that cannot run says so,+ loudly and repeatedly, with what it is waiting on; (5) measure on the read-only production database before and after+ (its environment file only, never printed), and put the numbers in the pull request.+- [x] Docs need no test; check that each model of the three names what removes it. Commit.++## After the tasks++- [ ] Push; mark Ready; post red/green evidence (each red commit's failing run, each green run) and the before numbers in a+ PR comment; add the Review step (a Reviewer by Routing, against MongoDB's two skills).+- [ ] After Ken's go and the release, measure again on the read-only production database: the `operation_expiry` index and+ its expiry, operations older than 30 days (0 once the monitor has run), the average size of route decisions written since,+ and the sweep's hourly line in the worker log; put the after numbers in the PR.