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 10-29 ai: 2 reviewed PRs (#2213, #2198) (#2236)
0xken150d3855e99189
diff --git a/backend/integration/plans.test-support.ts b/backend/integration/plans.test-support.tsindex 36ef5f865..ed45e0fd5 100644--- a/backend/integration/plans.test-support.ts+++ b/backend/integration/plans.test-support.ts@@ -8,14 +8,14 @@ import { PrismaClient } from '@prisma/client'import { PROFILE_STAGES, profileEntry, queryShape, type ProfileEntry } from './bench/profile.js'/** A fresh loopback replica set with the schema pushed; never DATABASE_URL. */-export async function planDatabase(prefix: string): Promise<{ replica: MongoMemoryReplSet; db: PrismaClient }> {+export async function planDatabase(prefix: string): Promise<{ replica: MongoMemoryReplSet; db: PrismaClient; uri: string }> {const 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(`${prefix}_${randomUUID().replaceAll('-', '_')}`)await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], {env: { ...process.env, DATABASE_URL: uri }, timeout: 60000,})- return { replica, db: new PrismaClient({ datasources: { db: { url: uri } } }) }+ return { replica, db: new PrismaClient({ datasources: { db: { url: uri } } }), uri }}/** Every operation `run` sends, as the profiler records it. */diff --git a/backend/integration/superTabCache.test.ts b/backend/integration/superTabCache.test.tsindex 557518356..7c9965c19 100644--- a/backend/integration/superTabCache.test.ts+++ b/backend/integration/superTabCache.test.ts@@ -100,6 +100,8 @@ describe('stamps after commit', () => {await swarmTransaction(db, tx => guardedWrite(tx, tabId, { op: 'update', kind: 'head', key: 'head', seen: head.version,data: { ...data, invitations: [{ id: 'i1', email: '[email protected]', role: 'viewer', conversationId: 'lead', expiresAt: 1 }] },head: { groupCounter: head.groupCounter, visibilityEpoch: head.visibilityEpoch, sequenceBase: head.sequenceBase } }, parts.clock.next()))+ // As a commit writes it (parts/commit.ts indexesOf): the sweep finds Swarms with invitations by this index.+ await db.superTab.update({ where: { id: tabId }, data: { invitedEmails: { set: ['[email protected]'] } } })await sweepSwarms(db)expect(bumpsOf(tabId)).toEqual([['main'], ['main'], ['main']])})diff --git a/backend/integration/superTabNamedReads.test.ts b/backend/integration/superTabNamedReads.test.tsindex b89748004..ea140c545 100644--- a/backend/integration/superTabNamedReads.test.ts+++ b/backend/integration/superTabNamedReads.test.ts@@ -255,6 +255,44 @@ describe('a conversation\'s page of messages', () => {})})+// #2168: what a page's rows name as their thread or reply-to but the page does not hold is read by id, so a reader is never+// pointed at a row it may not see. As Prisma's `id in` it was $expr, whose index the planner picks per read (here it happened+// to pick the id index); the read now names the id index, and this pins that it reads only the ids it names.+describe('the rows a page points at', () => {+ it('are read by id alone, by the id index, and only in this conversation', async () => {+ const me = await signedIn('pointer')+ const tabId = (await store.create(me, randomUUID(), 'Points')).id+ const conversationId = (await db.swarmGroup.findFirstOrThrow({ where: { tabId, deleted: false } })).key+ const author = { kind: 'person', id: me.sub, name: me.email, membershipGeneration: tabId }+ const message = (id: string, sequence: number, fields: Record<string, unknown> = {}) => ({ id: `${tabId}-${id}`, tabId, conversationId, sequence,+ text: id, author, recipientIds: [] as string[], mentions: [] as string[], ...fields })+ await db.superTabMessage.createMany({ data: [+ message('root', 1),+ // An agent-only note to someone else: the reply in its thread names nothing of it.+ message('note', 2, { source: { kind: 'note', recipientsOnly: true }, recipientIds: ['some-agent'] }),+ { ...message('elsewhere', 1), conversationId: 'another-conversation' },+ // Older messages a read bounded by the conversation alone examines too.+ ...Array.from({ length: 30 }, (_, i) => message(`old-${i}`, 3 + i)),+ message('r1', 40, { thread: `${tabId}-root`, replyTo: `${tabId}-root` }),+ message('r2', 41, { thread: `${tabId}-note` }),+ message('r3', 42, { replyTo: `${tabId}-elsewhere` }),+ ] })+ let page: Awaited<ReturnType<SuperTabStore['messages']>> | undefined+ const entries = await profiled(db, async () => { page = await store.messages(me, tabId, conversationId, { after: 39 }) })+ expect(page!.messages.map(m => m.text)).toEqual(['r1', 'r2', 'r3'])+ expect(page!.messages[0]).toMatchObject({ thread: `${tabId}-root`, replyTo: `${tabId}-root` })+ expect(page!.messages[1]!.thread).toBeNull()+ const rows = reads(entries, 'SuperTabMessage', ['_id', 'conversationId'], ['sequence', 'thread'])+ expect(rows, JSON.stringify(plan(rows))).toHaveLength(1)+ expect(rows[0]!.nreturned, JSON.stringify(plan(rows))).toBe(2)+ // Three ids named: at most one document each (the other conversation's examined and left out), and the index seek of+ // each id plus the key past it.+ expect(rows[0]!.docsExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(3)+ expect(rows[0]!.keysExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(2 * 3)+ expect(rows[0]!.command?.hint, JSON.stringify(plan(rows))).toEqual(NAMED_INDEX.SuperTabMessage.id)+ })+})+describe('who a named read answers', () => {it('a Swarm list leaves out a Swarm the person was removed from, and one of another environment', async () => {const me = await signedIn('removed')diff --git a/backend/integration/superTabReadMarks.test.ts b/backend/integration/superTabReadMarks.test.tsindex 00c827d5d..7b997aa0e 100644--- a/backend/integration/superTabReadMarks.test.ts+++ b/backend/integration/superTabReadMarks.test.ts@@ -16,6 +16,8 @@ import * as parts from '../src/superTabs/parts/index.js'import { swarmTransaction } from '../src/superTabs/cache.js'import { guardedWrite } from '../src/superTabs/parts/write.js'import { SwarmReads } from '../src/superTabs/read/service.js'+import { CATCH_UP_SCAN } from '../src/superTabs/catchUp.js'+import { stableId } from '../src/superTabs/model.js'import { HostReads } from '../src/superTabs/read/host.js'import type { Conversation, SuperTabState } from '../src/superTabs/model.js'import { writeLegacySwarm } from '../scripts/swarm-parts/legacy.js'@@ -28,6 +30,9 @@ let app: FastifyInstancelet clock = NOWconst user = (actor: { userId: string; email: string }): AuthUser => ({ sub: actor.userId, email: actor.email, autonomousEnv: 'prod', role: 'user' })const [owner, peer, outsider] = [ownerActor, peerActor, outsiderActor].map(user) as [AuthUser, AuthUser, AuthUser]+const ownerTeam: AuthUser = { ...owner, harnessSessionId: 'owner-team-session', harnessSessionKind: 'team' }+const signedIn = (authorization: string | undefined) =>+ authorization === 'Bearer team' ? ownerTeam : [owner, peer, outsider].find(u => `Bearer ${u.sub}` === authorization)const MIGRATED = NOW - 60_000beforeAll(async () => {@@ -44,7 +49,7 @@ beforeAll(async () => {app.setErrorHandler(errorHandler)// External SSO is replaced with fixture accounts; every permission and write below is real.app.addHook('onRequest', async (request, reply) => {- const found = [owner, peer, outsider].find(u => `Bearer ${u.sub}` === request.headers.authorization)+ const found = signedIn(request.headers.authorization)if (!found) return reply.code(401).send({ success: false })request.user = found})@@ -78,7 +83,8 @@ async function scene() {}const call = async (method: 'GET' | 'POST', url: string, as: AuthUser, payload?: unknown) => {- const response = await app.inject({ method, url, headers: { authorization: `Bearer ${as.sub}` }, ...(payload ? { payload } : {}) })+ const response = await app.inject({ method, url, headers: { authorization: as === ownerTeam ? 'Bearer team' : `Bearer ${as.sub}` },+ ...(payload ? { payload } : {}) })return { status: response.statusCode, body: response.json() as { data: any; error?: { code: string } } }}const mark = (tabId: string, conversationId: string, sequence: number, as: AuthUser = owner, query = '') =>@@ -160,3 +166,100 @@ describe('read marks (one per person and conversation)', () => {clock = NOW})})++describe('catch-up summary (what the reader missed since their mark)', () => {+ const lead = { kind: 'agent', id: 'lead-agent', name: 'Lead', displayName: 'River', membershipGeneration: 'g' }+ /** Rows written as the store writes them, numbered from 1 in `conversationId`; scenes repeat conversation ids, so the tab names them. */+ const write = (tabId: string, conversationId: string, rows: Array<{ text: string; source?: object; mentions?: string[]; recipientIds?: string[] }>) =>+ db.superTabMessage.createMany({ data: rows.map((row, i) => ({ id: `${tabId}-${conversationId}-m${i + 1}`, tabId, conversationId, sequence: i + 1, author: lead,+ text: row.text, recipientIds: row.recipientIds ?? [], mentions: row.mentions ?? [], ...(row.source ? { source: row.source } : {}) })) })+ const catchUp = (tabId: string, conversationId: string, after: number, as: AuthUser = owner, query = '') =>+ call('GET', `/api/super-tabs/${tabId}/conversations/${conversationId}/catch-up?after=${after}${query}`, as)+ const scenario = async () => {+ const s = await scene()+ await write(s.tabId, s.web, [+ { text: 'Read already', mentions: [owner.sub] },+ { text: '🎉 Shipped: Avatars. https://github.com/o/r/pull/7', source: { kind: 'ship', title: 'Avatars' } },+ { text: 'Owner, which colour?', mentions: [owner.sub] },+ { text: 'Peer, which font?', mentions: [peer.sub] },+ // An agent-only notice is its recipient's alone, tag and all.+ { text: 'Skill update for the Lead', source: { kind: 'agent-only' }, mentions: [owner.sub], recipientIds: ['lead-agent'] },+ { text: 'Stuck\n\nNo simulator on this Mac.', source: { kind: 'system' } },+ ])+ await write(s.tabId, s.secretGroup, [{ text: 'Secret question', mentions: [owner.sub] }])+ const decision = (id: string, personId: string, conversationId: string, answeredAt?: Date) => ({ id, tabId: s.tabId, batchId: id, projectId: 'p',+ conversationId, personId, askerAgentId: 'lead-agent', question: 'Which?', options: ['A', 'B'], recommended: 0, unblocks: 'Work', createdAt: new Date(NOW),+ ...(answeredAt ? { answeredAt } : {}) })+ await db.superTabDecision.createMany({ data: [decision(`${s.tabId}-d1`, owner.sub, s.web), decision(`${s.tabId}-d2`, peer.sub, s.web),+ decision(`${s.tabId}-d3`, owner.sub, s.web, new Date(NOW)), decision(`${s.tabId}-d4`, owner.sub, s.secretGroup)] })+ return s+ }++ it('lists what landed, what is blocked and what needs the reader, from the rows past the mark they may read', async () => {+ const s = await scenario()+ const { status, body } = await catchUp(s.tabId, s.web, 1)+ expect(status).toBe(200)+ expect(body.data).toEqual({ after: 1, through: 6, unread: 4, more: false, decisions: 1,+ landed: { total: 1, items: [{ messageId: `${s.tabId}-${s.web}-m2`, sequence: 2, author: 'River', text: 'Avatars' }] },+ blocked: { total: 1, items: [{ messageId: `${s.tabId}-${s.web}-m6`, sequence: 6, author: 'River', text: 'Stuck: No simulator on this Mac.' }] },+ needsYou: { total: 1, items: [{ messageId: `${s.tabId}-${s.web}-m3`, sequence: 3, author: 'River', text: 'Owner, which colour?' }] } })+ // Another reader's tags and decisions are their own.+ expect((await catchUp(s.tabId, s.web, 1, peer)).body.data).toMatchObject({ decisions: 1,+ needsYou: { total: 1, items: [{ text: 'Peer, which font?' }] } })+ })++ // The #2213 merge with main (#2177): a task chat's copy of a Lead's notice stored before such copies were marked, whose Lead+ // copy reached the Lead, is read by no one (pageReads.ts deliveredCopies). The summary leaves it out as the page does.+ it('leaves out a task chat copy of a Lead notice that its Lead copy delivered, as the page does', async () => {+ const s = await scene()+ await write(s.tabId, s.web, [+ { text: 'Read already' },+ { text: 'COPY: "Avatars" lost its task. Owner, who takes it?', source: { kind: 'work-lost' }, mentions: [owner.sub] },+ { text: 'Owner, which colour?', mentions: [owner.sub] },+ ])+ const copy = `${s.tabId}-${s.web}-m2`+ await db.superTabMessage.create({ data: { id: stableId(copy, 'lead'), tabId: s.tabId, conversationId: 'lead', sequence: 1, author: lead,+ text: 'COPY: "Avatars" lost its task.', recipientIds: ['lead-agent'], mentions: [], source: { kind: 'work-lost' } } })+ const { status, body } = await catchUp(s.tabId, s.web, 1)+ expect(status).toBe(200)+ expect(body.data).toMatchObject({ unread: 1, needsYou: { total: 1, items: [{ messageId: `${s.tabId}-${s.web}-m3` }] } })+ expect(JSON.stringify(body.data)).not.toContain('COPY')+ })++ it('says when the span is longer than one summary reads, and lists no status from its first part as current', async () => {+ const s = await scene()+ // A task stuck early in the span, working again and asking the reader past the cap.+ const rows = Array.from({ length: CATCH_UP_SCAN }, (_, i) => ({ text: i === 4 ? 'Stuck\n\nNo simulator.' : `Update ${i + 1}`,+ ...(i === 4 ? { source: { kind: 'system' } } : {}) }))+ await write(s.tabId, s.web, [...rows, { text: 'Working', source: { kind: 'system' } }, { text: 'Owner, which colour?', mentions: [owner.sub] }])+ const { body } = await catchUp(s.tabId, s.web, 0)+ expect(body.data).toMatchObject({ after: 0, through: CATCH_UP_SCAN, unread: CATCH_UP_SCAN, more: true,+ blocked: { total: 0 }, landed: { total: 0 }, needsYou: { total: 0 } })+ })++ it('refuses a conversation the reader cannot read, and one that does not exist', async () => {+ const s = await scenario()+ expect((await catchUp(s.tabId, s.secretGroup, 0, outsider)).status).toBe(404)+ expect((await catchUp(s.tabId, 'no-such-group', 0, outsider)).status).toBe(404)+ // Its owner reads it.+ expect((await catchUp(s.tabId, s.secretGroup, 0)).body.data).toMatchObject({ decisions: 1, needsYou: { total: 1 } })+ })++ it('stops summarizing a conversation once the reader can no longer read it', async () => {+ const s = await scenario()+ expect((await catchUp(s.tabId, s.web, 1, peer)).status).toBe(200)+ await swarmTransaction(db, async tx => {+ const current = (await parts.loadActive(tx, s.tabId, { groupIds: [s.web] })).groups.find(g => g.key === s.web)!+ const data = { ...structuredClone(current.data!), audience: { people: [{ id: owner.sub, generation: 0 }] } } as Conversation+ await guardedWrite(tx, s.tabId, { op: 'update', kind: 'group', key: s.web, seen: current.version, data }, clock)+ })+ expect((await catchUp(s.tabId, s.web, 1, peer)).status).toBe(404)+ })++ it('is for people reading as themselves: never an agent or a Team session', async () => {+ const s = await scenario()+ expect((await catchUp(s.tabId, s.web, 1, owner, '&asAgentId=lead-agent')).status).toBe(400)+ expect((await catchUp(s.tabId, s.web, 1, ownerTeam)).status).toBe(403)+ expect((await call('GET', `/api/super-tabs/${s.tabId}/conversations/${s.web}/catch-up`, owner)).status).toBe(400)+ })+})diff --git a/backend/integration/swarmSweepPlans.test.ts b/backend/integration/swarmSweepPlans.test.tsnew file mode 100644index 000000000..2689596bf--- /dev/null+++ b/backend/integration/swarmSweepPlans.test.ts@@ -0,0 +1,112 @@+import { randomUUID } from 'node:crypto'+import { afterAll, beforeAll, describe, expect, it } from 'vitest'+import type { MongoMemoryReplSet } from 'mongodb-memory-server-core'+import type { PrismaClient } from '@prisma/client'+import type { AuthUser } from '../src/lib/ssoAuth.js'+import { SuperTabStore } from '../src/superTabs/store.js'+import { listGroupIndexes } from '../src/superTabs/parts/indexed.js'+import { RETENTION_MS } from '../src/superTabs/parts/types.js'+import { sweepSwarms } from '../src/superTabs/sweeps.js'+import type { ProfileEntry } from './bench/profile.js'+import { planDatabase, plan, profiled, reads } from './plans.test-support.js'++// Roadmap Phase 3.6: the hourly Swarm sweeps read across every Swarm, so a sweep no index bounds reads every part of every+// Swarm. Each sweep's read here examines only the parts it changes. A fresh loopback replica set; never DATABASE_URL.+let replica: MongoMemoryReplSet+let db: PrismaClient+let store: SuperTabStore+const NOW = Date.parse('2026-10-29T08:00:00Z')+const DAY = 86_400_000+const OLD = new Date(NOW - 30 * DAY)+const maker: AuthUser = { sub: randomUUID().replaceAll('-', '').slice(0, 24), email: '[email protected]', autonomousEnv: 'prod', role: 'user' }+let tabs: string[]+let entries: ProfileEntry[]+let result: Awaited<ReturnType<typeof sweepSwarms>>+/** Parts that no sweep changes, in each collection a sweep reads: an unbounded sweep examines these too. */+const QUIET = 10++const part = (tabId: string, key: string, fields: Record<string, unknown> = {}) => ({ id: `${tabId}:${key}`, tabId, key, version: 1, changedAt: OLD,+ ordinal: 1, data: { id: key }, ...fields })++beforeAll(async () => {+ ({ replica, db } = await planDatabase('swarm_sweep_plans_test'))+ store = new SuperTabStore(db, () => NOW)+ await listGroupIndexes(db)+ await db.user.create({ data: { id: maker.sub, externalId: `fixture-${maker.sub}`, email: maker.email, autonomousEnv: 'prod' } })+ tabs = []+ for (let i = 0; i < 4; i++) tabs.push((await store.create(maker, randomUUID(), `Swept ${i}`)).id)+ const [tab] = tabs as [string]+ const due = new Date(NOW - DAY), later = new Date(NOW + DAY)+ // Tombstones of people, agents and machines: two past their purge time, one not yet, and quiet live parts.+ const agent = { machineId: 'm', machineOwnerId: maker.sub, contributorId: maker.sub }+ const machine = { machineId: 'm', cleanupOwnerIds: [] }+ for (const [model, extra] of [['swarmMember', {}], ['swarmAgent', agent], ['swarmMachine', machine]] as const) {+ await (db[model] as unknown as { createMany(args: unknown): Promise<unknown> }).createMany({ data: [+ part(tab, `${model}:due-1`, { ...extra, deleted: true, purgeAt: due }), part(tab, `${model}:due-2`, { ...extra, deleted: true, purgeAt: due }),+ part(tab, `${model}:later`, { ...extra, deleted: true, purgeAt: later }),+ // Compacted by an earlier sweep: its purge time is gone, and it is never compacted again.+ part(tab, `${model}:compacted`, { ...extra, deleted: true, purgeAt: null, data: {} }),+ ...Array.from({ length: QUIET }, (_, i) => part(tab, `${model}:live-${i}`, { ...extra, deleted: false, purgeAt: null })),+ ] })+ }+ // Starts: two finished past retention, finished ones already removed (tombstones until their purge), and running ones.+ const start = { machineId: 'm', conversationId: 'c', agentId: null }+ await db.swarmStart.createMany({ data: [+ part(tab, 'start:expired-1', { ...start, finishedAt: new Date(NOW - RETENTION_MS - DAY), deleted: false }),+ part(tab, 'start:expired-2', { ...start, finishedAt: new Date(NOW - RETENTION_MS - DAY), deleted: false }),+ ...Array.from({ length: QUIET }, (_, i) => part(tab, `start:removed-${i}`, { ...start, finishedAt: new Date(NOW - RETENTION_MS - DAY), deleted: true, purgeAt: later })),+ ...Array.from({ length: QUIET }, (_, i) => part(tab, `start:running-${i}`, { ...start, finishedAt: null, deleted: false })),+ ] })+ // One Swarm has an invitation that has expired, and its row's invitation index names it (parts/commit.ts).+ const head = await db.swarmHead.findUniqueOrThrow({ where: { id: `${tabs[1]}:head` } })+ await db.swarmHead.update({ where: { id: head.id }, data: { data: { ...head.data as object, invitations: [{ id: 'i1', email: '[email protected]', role: 'viewer',+ conversationId: 'lead', invitedBy: maker.sub, expiresAt: NOW - DAY }] } } })+ await db.superTab.update({ where: { id: tabs[1]! }, data: { invitedEmails: { set: ['[email protected]'] } } })+ entries = await profiled(db, async () => { result = await sweepSwarms(db, NOW) })+})+afterAll(async () => {+ await db?.$disconnect()+ await replica?.stop()+})++describe('the hourly sweeps', () => {+ it('compacts only tombstones past their purge time, each collection by its purge index', async () => {+ expect(result.tombstonesCompacted).toBe(6)+ for (const collection of ['SwarmMember', 'SwarmAgent', 'SwarmMachine']) {+ // The due tombstones are found by the purge index, then compacted by id.+ const found = reads(entries, collection, ['purgeAt']).filter(e => e.op !== 'update')+ expect(found, `${collection}: ${JSON.stringify(plan(found))}`).toHaveLength(1)+ expect(found[0]!.docsExamined, `${collection}: ${JSON.stringify(plan(found))}`).toBeLessThanOrEqual(2)+ expect(found[0]!.planSummary, collection).toMatch(/IXSCAN \{ purgeAt: 1 \}/)+ const written = reads(entries, collection, ['purgeAt']).filter(e => e.op === 'update')+ expect(written.map(e => e.docsExamined), `${collection}: ${JSON.stringify(plan(written))}`).toEqual([2])+ }+ const kept = await db.swarmMember.findUniqueOrThrow({ where: { id: `${tabs[0]}:swarmMember:later` } })+ expect(kept.data).toEqual({ id: 'swarmMember:later' })+ })++ it('never removes a start that has not finished', async () => {+ const running = await db.swarmStart.findMany({ where: { tabId: tabs[0]!, key: { startsWith: 'start:running-' } }, select: { key: true, deleted: true } })+ expect(running.filter(r => r.deleted).map(r => r.key)).toEqual([])+ })++ it('expires only finished starts past retention, never reading removed or running ones', async () => {+ expect(result.startsExpired).toBe(2)+ const rows = reads(entries, 'SwarmStart', ['finishedAt'])+ expect(rows, JSON.stringify(plan(rows))).toHaveLength(1)+ expect(rows[0]!.docsExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(2)+ expect(rows[0]!.command?.hint, `the read names its index: ${JSON.stringify(plan(rows))}`).toBeTruthy()+ })++ it('reads the heads of only the Swarms with invitations', async () => {+ expect(result.invitationsExpired).toBe(1)+ expect((await db.superTab.findUniqueOrThrow({ where: { id: tabs[1]! } })).invitedEmails).toEqual([])+ const heads = entries.filter(e => e.ns.endsWith('.SwarmHead') && e.op !== 'update')+ const examined = heads.reduce((sum, e) => sum + (e.docsExamined ?? 0), 0)+ // The invited Swarm's head, read once to expire and once by its guarded write; never the other three.+ expect(examined, JSON.stringify(plan(heads))).toBeLessThanOrEqual(2)+ const invited = reads(entries, 'SuperTab', ['invitedEmails'])+ expect(invited, JSON.stringify(plan(invited))).toHaveLength(1)+ expect(invited[0]!.docsExamined, JSON.stringify(plan(invited))).toBeLessThanOrEqual(1)+ })+})diff --git a/backend/integration/workerIndexPlans.test.ts b/backend/integration/workerIndexPlans.test.tsnew file mode 100644index 000000000..0b5ba6f8e--- /dev/null+++ b/backend/integration/workerIndexPlans.test.ts@@ -0,0 +1,70 @@+import { randomUUID } from 'node:crypto'+import { afterAll, beforeAll, describe, expect, it } from 'vitest'+import type { MongoMemoryReplSet } from 'mongodb-memory-server-core'+import type { PrismaClient } from '@prisma/client'+import { planDatabase, plan, profiled, reads } from './plans.test-support.js'++// Roadmap Phase 3.7: the worker's hourly people rollup and minute billing sync read through an index that bounds them. A+// fresh loopback replica set; the app's own Prisma client is pointed at it before anything imports it. Never DATABASE_URL.+let replica: MongoMemoryReplSet+let db: PrismaClient+let rollupPeople: typeof import('../src/services/ProductUsagePeopleRollupService.js')['rollupPeople']+let billing: typeof import('../src/services/MachineBillingWorkerService.js')['machineBillingWorkerService']+const DAY = 86_400_000+const NOW = Date.parse('2026-10-29T08:00:00Z')+const today = Math.floor(NOW / DAY) * DAY++beforeAll(async () => {+ let uri: string+ ({ replica, db, uri } = await planDatabase('worker_index_plans_test'))+ process.env.DATABASE_URL = uri+ rollupPeople = (await import('../src/services/ProductUsagePeopleRollupService.js')).rollupPeople+ billing = (await import('../src/services/MachineBillingWorkerService.js')).machineBillingWorkerService+})+afterAll(async () => {+ await (await import('../src/lib/prisma.js')).prisma.$disconnect()+ await db?.$disconnect()+ await replica?.stop()+})++describe('the hourly people rollup', () => {+ it('reads only the activity marks of the days it counts, by the day index', async () => {+ const mark = (subject: string, day: number) => ({ subject, dayUtc: new Date(day), expiresAt: new Date(day + 40 * DAY), surfaces: ['cli'], worked: true,+ signupDay: new Date(day), staff: false })+ // Marks of days long past, which a read not bounded by day examines too.+ await db.productUsageActivity.createMany({ data: [+ ...Array.from({ length: 20 }, (_, i) => mark(`old-${i}`, today - 30 * DAY)),+ mark('recent-a', today - DAY), mark('recent-b', today - 2 * DAY), mark('recent-c', today - 3 * DAY),+ ] })+ const entries = await profiled(db, () => rollupPeople(new Date(NOW)))+ const rows = reads(entries, 'product_usage_activity', ['dayUtc'])+ expect(rows, JSON.stringify(plan(rows))).toHaveLength(1)+ expect(rows[0]!.nreturned).toBe(3)+ expect(rows[0]!.docsExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(3)+ expect(rows[0]!.planSummary, JSON.stringify(plan(rows))).toMatch(/IXSCAN \{ dayUtc: 1/)+ })+})++describe('the minute billing sync', () => {+ // The (billingStatus, externalSubscriptionStatus, externalSubscriptionEndAt) index serves it although the status is not in the+ // filter: Mongo seeks to each status's end-time range, so it reads only the subscriptions it returns, and a few keys per+ // status. Another index on machines, rewritten on every 15 s report, would cost more than those keys (roadmap Phase 3.7).+ it('reads only the active subscriptions ending near now, by an index bounding the end time', async () => {+ const machine = (endAt: number, fields: Record<string, unknown> = {}) => ({ machineId: `m-${randomUUID()}`, userId: randomUUID().replaceAll('-', '').slice(0, 24),+ apiKey: `k-${randomUUID()}`, managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote', billingStatus: 'active', externalSubscriptionId: `s-${randomUUID()}`,+ externalSubscriptionEndAt: new Date(endAt), externalSubscriptionStatus: 2, deletedAt: null, ...fields })+ await db.machine.createMany({ data: [+ // Active subscriptions ending next month, of several provider statuses: a read the end time does not bound examines them.+ ...Array.from({ length: 20 }, (_, i) => machine(Date.now() + 30 * DAY, { externalSubscriptionStatus: i % 4 })),+ machine(Date.now() + 5 * 60_000), machine(Date.now() - 10 * 60_000, { externalSubscriptionStatus: 3 }),+ ] })+ const entries = await profiled(db, () => (billing as unknown as { findSyncCandidates(): Promise<unknown[]> }).findSyncCandidates())+ const rows = reads(entries, 'machines', ['externalSubscriptionEndAt', 'billingStatus'])+ expect(rows, JSON.stringify(plan(rows))).toHaveLength(1)+ expect(rows[0]!.nreturned).toBe(2)+ expect(rows[0]!.docsExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(2)+ // Four statuses among these machines: at most one key past each status's range, and one at each range's start.+ expect(rows[0]!.keysExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(2 + 2 * 4)+ expect(rows[0]!.planSummary).toMatch(/externalSubscriptionEndAt/)+ })+})diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prismaindex 354769f70..f78c22d89 100644--- a/backend/prisma/schema.prisma+++ b/backend/prisma/schema.prisma@@ -587,6 +587,8 @@ model ProductUsageActivity {@@map("product_usage_activity")/// Expires these rows (lib/productUsage.ts ensureProductUsageExpiry). Declared so db push keeps it; the worker sets its expiry.@@index([expiresAt], map: "product_usage_expiry")+ /// The hourly people rollup reads the marks of its last days (services/ProductUsagePeopleRollupService.ts).+ @@index([dayUtc])}/// Legacy individual counters. New ingestion is disabled; dayUtc TTL removes these after 35 days.@@ -1579,6 +1581,8 @@ model SwarmMember {@@unique([tabId, key])@@index([tabId, changedAt])+ /// Tombstones past their purge time, compacted by the hourly sweep (superTabs/sweeps.ts compactTombstones). Not a TTL: the tombstone stays.+ @@index([purgeAt])}/// One conversation: its work, checks, assignment, members and message counter.@@ -1650,6 +1654,8 @@ model SwarmAgent {@@index([tabId, contributorId])/// One agent's registrations in every Swarm (confidential.ts, sessionScope.ts): host rows read them on every changed tab.@@index([key, deleted])+ /// Tombstones past their purge time, compacted by the hourly sweep (superTabs/sweeps.ts compactTombstones). Not a TTL: the tombstone stays.+ @@index([purgeAt])}/// One machine the Swarm references, contributed or not: its contribution and observation, and its slot ledger.@@ -1678,6 +1684,8 @@ model SwarmMachine {@@index([machineId, deleted])/// Machines whose settings changed since a host's cursor (read/host.ts woken).@@index([tabId, hostChangedAt])+ /// Tombstones past their purge time, compacted by the hourly sweep (superTabs/sweeps.ts compactTombstones). Not a TTL: the tombstone stays.+ @@index([purgeAt])}model SwarmStart {@@ -1704,6 +1712,8 @@ model SwarmStart {@@index([tabId, agentId])/// Removed parts go at purgeAt (superTabs/sweeps.ts ensurePartExpiry). Declared so db push keeps the index; the worker sets its expiry.@@index([purgeAt], map: "part_purge")+ /// Live starts by finish time: the hourly sweep expires those finished 7 days ago (superTabs/sweeps.ts expireStarts).+ @@index([deleted, finishedAt])}/// One project's report watermark, and the fence a Lead's worker decisions serialize on.diff --git a/backend/src/routes/superTabs.ts b/backend/src/routes/superTabs.tsindex ec07fee63..e8ddd2aca 100644--- a/backend/src/routes/superTabs.ts+++ b/backend/src/routes/superTabs.ts@@ -65,6 +65,8 @@ const messageParams = tabParams.extend({ conversationId: id })// A person's own read mark (superTabs/readMarks.ts): no asAgentId, since agents keep none.const readMarkBody = z.object({ sequence: z.number().int().nonnegative().safe() }).strict()const noQuery = z.object({}).strict()+// The reader's own catch-up (superTabs/catchUp.ts): no asAgentId, since agents read every message as it comes.+const catchUpQuery = z.object({ after: z.coerce.number().int().nonnegative().safe() }).strict()// Pages by (sequence, id) (design 4.6): `afterId`/`beforeId` go with `after`/`before`, from the previous page's `next`.const messageQuery = agentQuery.extend({ after: z.coerce.number().int().nonnegative().safe().optional(),before: z.coerce.number().int().nonnegative().safe().optional(), messageId: id.optional(), afterId: id.optional(), beforeId: id.optional(),@@ -460,6 +462,9 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Suapp.post<{ Params: z.infer<typeof messageParams>; Querystring: z.infer<typeof noQuery>; Body: z.infer<typeof readMarkBody> }>('/api/super-tabs/:tabId/conversations/:conversationId/read',{ preHandler: [validateParams(messageParams), validateQuery(noQuery), validateBody(readMarkBody)] },(req, reply) => respond(reply, () => reads.markRead(req.user!, req.params.tabId, req.params.conversationId, req.body.sequence)))+ app.get<{ Params: z.infer<typeof messageParams>; Querystring: z.infer<typeof catchUpQuery> }>('/api/super-tabs/:tabId/conversations/:conversationId/catch-up',+ { preHandler: [validateParams(messageParams), validateQuery(catchUpQuery)] },+ (req, reply) => respond(reply, () => store.catchUp(req.user!, req.params.tabId, req.params.conversationId, req.query.after)))app.get<{ Params: z.infer<typeof messageParams>; Querystring: z.infer<typeof agentQuery> }>('/api/super-tabs/:tabId/conversations/:conversationId/attempts',{ preHandler: [validateParams(messageParams), validateQuery(agentQuery)] },(req, reply) => respond(reply, () => store.attempts(req.user!, req.params.tabId, req.params.conversationId, req.query.asAgentId)))diff --git a/backend/src/superTabs/catchUp.test.ts b/backend/src/superTabs/catchUp.test.tsnew file mode 100644index 000000000..404d4f34b--- /dev/null+++ b/backend/src/superTabs/catchUp.test.ts@@ -0,0 +1,102 @@+import { describe, expect, it } from 'vitest'+import { catchUpSummary, type CatchUpRow } from './catchUp.js'++const READER = 'reader-person'+const lead = { kind: 'agent' as const, id: 'lead-agent', name: 'Lead', displayName: 'River' }+const builder = { kind: 'agent' as const, id: 'builder-agent', name: 'Builder', displayName: 'Iris' }+const me = { kind: 'person' as const, id: READER, name: '[email protected]' }++let next = 0+/** One row as the store reads it, in the main stream unless a thread is given. */+function row(text: string, extra: Partial<CatchUpRow> = {}): CatchUpRow {+ const sequence = ++next+ return { id: `m${sequence}`, sequence, author: lead, source: null, text, thread: null, alsoInChat: null, mentions: [], ...extra }+}+const status = (text: string, author = builder) => row(text, { author, source: { kind: 'system' } })+const summary = (rows: CatchUpRow[], span: Partial<{ after: number; more: boolean; decisions: number }> = {}) =>+ catchUpSummary(rows, READER, { after: 0, more: false, decisions: 0, ...span })+const texts = (list: { items: Array<{ text: string }> }) => list.items.map(i => i.text)++describe('catch-up summary of the unread span', () => {+ it('lists a shipped row as landed, by its title, with a link to the row', () => {+ const shipped = row('🎉 Shipped: Avatars, built by Iris. https://github.com/o/r/pull/7', { source: { kind: 'ship', title: 'Avatars' } })+ const result = summary([row('Morning'), shipped])+ expect(result.landed).toEqual({ total: 1, items: [{ messageId: shipped.id, sequence: shipped.sequence, author: 'River', text: 'Avatars' }] })+ expect(result.blocked.total).toBe(0)+ })++ it('counts only the latest status: a task that moved on is no longer blocked', () => {+ expect(summary([status('Stuck\n\nNo simulator.'), status('Working')]).blocked.total).toBe(0)+ const stuck = summary([status('Working'), status('Stuck\n\nNo simulator on this Mac.\nMore detail.')])+ expect(texts(stuck.blocked)).toEqual(['Stuck: No simulator on this Mac.'])+ expect(texts(summary([status('Needs a human\n\nWhich colour?')]).blocked)).toEqual(['Needs a human: Which colour?'])+ })++ it('lists the latest Done as landed, with its result', () => {+ const result = summary([status('Stuck\n\nCI red.'), status('Done\n\nMerged #42.')])+ expect(texts(result.landed)).toEqual(['Done: Merged #42.'])+ expect(result.blocked.total).toBe(0)+ })++ it('reads a status only from a system row, not a message that says the same word', () => {+ expect(summary([row('Stuck')]).blocked.total).toBe(0)+ })++ it('lists messages that tag the reader, threads included, and not those tagging someone else', () => {+ const tagged = row('Dee, which colour?', { mentions: [READER] })+ const inThread = row('Dee, one more question', { mentions: [READER], thread: 'm1' })+ const result = summary([row('Ken, look', { mentions: ['someone-else'] }), tagged, inThread])+ expect(result.needsYou.items.map(i => i.messageId)).toEqual([tagged.id, inThread.id])+ expect(result.needsYou.items[0]).toMatchObject({ author: 'River', text: 'Dee, which colour?' })+ })++ it('counts unread main-stream messages from others only', () => {+ const result = summary([row('Mine', { author: me }), row('One'), row('Thread only', { thread: 'm1' }),+ row('Also in chat', { thread: 'm1', alsoInChat: true })])+ expect(result.unread).toBe(2)+ })++ it('starts after the reader\'s own newest message, since writing in a chat reads what came before', () => {+ const before = row('Before my answer', { mentions: [READER] })+ const stuck = status('Stuck\n\nOld.')+ const mine = row('My answer', { author: me })+ const after = row('After my answer', { mentions: [READER] })+ const result = summary([before, stuck, mine, after])+ expect(result.needsYou.items.map(i => i.messageId)).toEqual([after.id])+ expect(result.blocked.total).toBe(0)+ expect(result.unread).toBe(1)+ // A reply of the reader's own that lives only in a thread reads that thread, not the chat.+ expect(summary([before, row('Thread reply', { author: me, thread: 'm1' })]).needsYou.total).toBe(1)+ })++ it('keeps the five newest items of a list, oldest first, and counts them all', () => {+ const rows = Array.from({ length: 7 }, (_, i) => row(`Question ${i + 1}`, { mentions: [READER] }))+ const result = summary(rows)+ expect(result.needsYou.total).toBe(7)+ expect(texts(result.needsYou)).toEqual(['Question 3', 'Question 4', 'Question 5', 'Question 6', 'Question 7'])+ })++ it('past the cap, never lists a status as current: a later one may have replaced it; shipped rows and tags stand', () => {+ const shipped = row('🎉 Shipped: Avatars.', { source: { kind: 'ship', title: 'Avatars' } })+ const tagged = row('Dee, which colour?', { mentions: [READER] })+ const partial = summary([status('Stuck\n\nNo simulator.'), shipped, tagged], { more: true })+ expect(partial.blocked.total).toBe(0)+ expect(texts(partial.landed)).toEqual(['Avatars'])+ expect(texts(partial.needsYou)).toEqual(['Dee, which colour?'])+ expect(summary([status('Done\n\nMerged #42.')], { more: true }).landed.total).toBe(0)+ })++ it('shortens an item to its first line and 140 characters', () => {+ const [item] = summary([row(`${'a'.repeat(200)}\nsecond line`, { mentions: [READER] })]).needsYou.items+ expect(item!.text).toBe(`${'a'.repeat(139)}…`)+ })++ it('names a person by the start of their email, and answers the span it read', () => {+ const peer = { kind: 'person' as const, id: 'peer', name: '[email protected]' }+ const tagged = row('Dee?', { author: peer, mentions: [READER] })+ const result = summary([tagged], { after: 3, more: true, decisions: 2 })+ expect(result.needsYou.items[0]!.author).toBe('ken')+ expect(result).toMatchObject({ after: 3, through: tagged.sequence, more: true, decisions: 2 })+ expect(summary([], { after: 9 })).toMatchObject({ after: 9, through: 9, unread: 0 })+ })+})diff --git a/backend/src/superTabs/catchUp.ts b/backend/src/superTabs/catchUp.tsnew file mode 100644index 000000000..a99fef39a--- /dev/null+++ b/backend/src/superTabs/catchUp.ts@@ -0,0 +1,95 @@+/**+ * "While you were away" (Slack parity, 2026-10-29): what a person missed in one conversation since their read mark, in three+ * short lists that each link to their rows. Built from the rows Swarm writes in a fixed form, never from a model reading the+ * words: shipped rows (ship.ts), the status rows of `work.status` (commands.ts) and a Lead's tags (mentions.ts). Agents read+ * every message as it comes, so only people get one. The rows given are those the reader may read (store.ts catchUp).+ */+import { STATUS_LABELS } from './model.js'+import { SHIP_KIND } from './ship.js'++/** How many rows past the mark one summary reads at most; a longer span says so (`more`). */+export const CATCH_UP_SCAN = 1000+/** How many items each list shows: its newest. */+export const CATCH_UP_ITEMS = 5+const ITEM_CHARS = 140++export interface CatchUpRow { id: string; sequence: number; author: unknown; source: unknown; text: string; thread: string | null+ alsoInChat: boolean | null; mentions: string[] }+export interface CatchUpItem { messageId: string; sequence: number; author: string; text: string }+export interface CatchUpList { total: number; items: CatchUpItem[] }+export interface CatchUp {+ /** The mark the span starts after, and the newest row it read. */+ after: number+ through: number+ /** Main-stream messages from others past the reader's own newest one. */+ unread: number+ /** More rows past `through` than one summary reads: the lists and `unread` cover only the span up to `through`, and no+ * status is listed, since a later one past it may have replaced it. */+ more: boolean+ /** Decisions waiting for the reader in this conversation (decisions.ts). */+ decisions: number+ landed: CatchUpList+ blocked: CatchUpList+ needsYou: CatchUpList+}+export interface CatchUpSpan { after: number; more: boolean; decisions: number }++type RowAuthor = { kind?: unknown; id?: unknown; name?: unknown; displayName?: unknown }+const LANDED = new Set<string>([STATUS_LABELS.done])+const BLOCKED = new Set<string>([STATUS_LABELS.blocked, STATUS_LABELS.needs_human])+const LABELS = new Set<string>(Object.values(STATUS_LABELS))++const authorOf = (row: CatchUpRow) => (row.author ?? {}) as RowAuthor+const kindOf = (row: CatchUpRow) => (row.source as { kind?: unknown } | null)?.kind+/** A row of the chat itself: top-level, from before threads, or a reply also sent to the chat (threads.ts). */+const inMainStream = (row: CatchUpRow) => !row.thread || row.thread === row.id || !!row.alsoInChat+const own = (row: CatchUpRow, personId: string) => authorOf(row).kind === 'person' && authorOf(row).id === personId++function authorName(row: CatchUpRow): string {+ const { kind, name, displayName } = authorOf(row)+ if (typeof displayName === 'string' && displayName) return displayName+ const named = typeof name === 'string' ? name : ''+ return kind === 'person' ? named.split('@')[0]! : named+}++/** The first line of `text`, at most ITEM_CHARS long. */+function shortened(text: string): string {+ const line = text.trim().split('\n')[0]!.trim()+ return line.length > ITEM_CHARS ? `${line.slice(0, ITEM_CHARS - 1)}…` : line+}++/** A status row's label and its result's first line, or null for any other row. */+function statusOf(row: CatchUpRow): { label: string; text: string } | null {+ if (kindOf(row) !== 'system') return null+ const [label, ...rest] = row.text.split('\n')+ if (!LABELS.has(label!)) return null+ const result = shortened(rest.join('\n'))+ return { label: label!, text: result ? `${label}: ${result}` : label! }+}++const item = (row: CatchUpRow, text: string): CatchUpItem => ({ messageId: row.id, sequence: row.sequence, author: authorName(row), text: shortened(text) })+const list = (items: CatchUpItem[]): CatchUpList => ({ total: items.length, items: items.slice(-CATCH_UP_ITEMS) })++/**+ * The summary of `rows`, the reader's (`personId`) unread span in sequence order. As the New messages line does (Desktop+ * unread_line.dart), the reader's own newest main-stream message reads everything before it. Only the latest status counts,+ * so a task that was stuck and moved on is not listed as blocked; with more rows past the span (`more`), its latest status+ * is not known, so none is listed. Shipped rows and tags stand whatever came after them.+ */+export function catchUpSummary(rows: CatchUpRow[], personId: string, span: CatchUpSpan): CatchUp {+ const read = rows.reduce((at, row) => own(row, personId) && inMainStream(row) ? row.sequence : at, span.after)+ const unread = rows.filter(row => row.sequence > read && !own(row, personId))+ const shipped = unread.filter(row => kindOf(row) === SHIP_KIND).map(row => {+ const title = (row.source as { title?: unknown }).title+ return item(row, typeof title === 'string' && title ? title : row.text)+ })+ const latest = span.more ? undefined : unread.filter(inMainStream).flatMap(row => {+ const status = statusOf(row)+ return status ? [{ row, ...status }] : []+ }).at(-1)+ const landed = latest && LANDED.has(latest.label) ? [...shipped, item(latest.row, latest.text)].sort((a, b) => a.sequence - b.sequence) : shipped+ const blocked = latest && BLOCKED.has(latest.label) ? [item(latest.row, latest.text)] : []+ const needsYou = unread.filter(row => row.mentions.includes(personId)).map(row => item(row, row.text))+ return { after: span.after, through: rows.at(-1)?.sequence ?? span.after, unread: unread.filter(inMainStream).length, more: span.more,+ decisions: span.decisions, landed: list(landed), blocked: list(blocked), needsYou: list(needsYou) }+}diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex 4eaf979df..23b15d0da 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -5,7 +5,7 @@ import { z } from 'zod'import { tokensByModelSchema } from './costs/tokens.js'import {activeWork, actorKey, agent, agentRole, appendPullRequestUrls, author, conversation, crossProjectActive, fail, isLeads, person, stableId, syncLeads, numberConversations, nextConversationNumber, renderWorkTask,- finishWorker, requireWorkerDecisions, reviewing, seenMachineIds, swarmGridName, visibleState, AGENT_ONLY, forRecipients,+ finishWorker, requireWorkerDecisions, reviewing, seenMachineIds, swarmGridName, visibleState, AGENT_ONLY, STATUS_LABELS, forRecipients,type Actor, type AgentStartRequest, type WorkTask, type Agent, type Author, type CommandEffects, type Conversation, type SuperTabState,} from './model.js'import { jobKindOf } from './evidence/jobKind.js'@@ -2141,7 +2141,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma// Finished work shows the worker recovered from a task it lost before.if (command.status === 'done') delete state.agents.find(a => a.id === assignment.agentId)?.lostTaskif (changed) {- const label = { working: 'Working', needs_human: 'Needs a human', blocked: 'Stuck', review: 'Ready for review', done: 'Done', stopped: 'Stopped' }[command.status]+ const label = STATUS_LABELS[command.status]const lead = group.leadId// Stuck is the Lead's to hear as a human decision is: either way the work waits on someone.const tellLead = actor.kind === 'agent' && actor.agentId === assignment.agentId && lead && lead !== actor.agentId &&diff --git a/backend/src/superTabs/decisions.ts b/backend/src/superTabs/decisions.tsindex f1ce9cc90..e585d99b5 100644--- a/backend/src/superTabs/decisions.ts+++ b/backend/src/superTabs/decisions.ts@@ -134,6 +134,11 @@ export async function waitingIn(tx: Tx, tabId: string, conversationId: string):return !!await tx.superTabDecision.findFirst({ where: { tabId, conversationId, ...waiting }, select: { id: true } })}+/** How many decisions asked of `personId` in this conversation still wait for them (catchUp.ts). */+export async function waitingFor(tx: Tx, tabId: string, conversationId: string, personId: string): Promise<number> {+ return tx.superTabDecision.count({ where: { tabId, conversationId, personId, ...waiting } })+}+/** What makes an ask a repeat: the same asker, task, person, conversation, question, options, recommendation and what it* unblocks. Another asker, another task or other options with the same text is a decision of its own (review of #1753). */const repeatKey = (d: Pick<DecisionDraft, 'askerAgentId' | 'assignmentId' | 'personId' | 'conversationId' | 'question' | 'options' | 'recommended' | 'unblocks'>) =>diff --git a/backend/src/superTabs/hotFilters.allowed.json b/backend/src/superTabs/hotFilters.allowed.jsonnew file mode 100644index 000000000..ede6178eb--- /dev/null+++ b/backend/src/superTabs/hotFilters.allowed.json@@ -0,0 +1,36 @@+{+ "src/superTabs/confidential.ts swarmAgent.findMany": 1,+ "src/superTabs/decisions.ts superTabDecision.findMany": 1,+ "src/superTabs/mentions.ts superTabMessage.findMany": 1,+ "src/superTabs/migration/links.ts superTabAttempt.findMany": 1,+ "src/superTabs/migration/links.ts superTabMessage.findMany": 1,+ "src/superTabs/migration/workspaces.ts superTab.findMany": 1,+ "src/superTabs/migration/workspaces.ts swarmHead.findMany": 1,+ "src/superTabs/migration/workspaces.ts swarmMember.findMany": 1,+ "src/superTabs/native.ts superTabDelivery.updateMany": 2,+ "src/superTabs/read/host.ts superTab.findMany": 3,+ "src/superTabs/read/host.ts swarmGroup.findMany": 1,+ "src/superTabs/read/host.ts swarmMachine.findMany": 2,+ "src/superTabs/read/service.ts superTab.findMany": 1,+ "src/superTabs/read/service.ts swarmWorkspaceMember.findMany": 1,+ "src/superTabs/routeDecisions.ts superTabRouteDecision.updateMany": 1,+ "src/superTabs/sessionScope.ts superTabSessionScope.findMany": 1,+ "src/superTabs/sessionScope.ts superTabSessionScope.updateMany": 1,+ "src/superTabs/store.ts superTab.findMany": 1,+ "src/superTabs/store.ts superTabAttachment.findMany": 2,+ "src/superTabs/store.ts superTabAttachment.updateMany": 2,+ "src/superTabs/store.ts superTabDelivery.findFirst": 1,+ "src/superTabs/store.ts superTabDelivery.findMany": 2,+ "src/superTabs/store.ts superTabDelivery.updateMany": 11,+ "src/superTabs/store.ts superTabMessage.findMany": 1,+ "src/superTabs/store.ts superTabOperation.findMany": 1,+ "src/superTabs/store.ts superTabRoleText.deleteMany": 1,+ "src/superTabs/store.ts superTabRun.deleteMany": 1,+ "src/superTabs/store.ts superTabTerminalRequest.count": 1,+ "src/superTabs/store.ts swarmHead.findMany": 2,+ "src/superTabs/store.ts swarmMachine.findMany": 1,+ "src/superTabs/store.ts swarmMember.findMany": 1,+ "src/superTabs/workspaceStore.ts superTab.findMany": 1,+ "src/superTabs/workspaceStore.ts swarmHead.findMany": 1,+ "src/superTabs/workspaceStore.ts swarmWorkspace.findMany": 2+}diff --git a/backend/src/superTabs/hotFilters.test.ts b/backend/src/superTabs/hotFilters.test.tsnew file mode 100644index 000000000..daf956442--- /dev/null+++ b/backend/src/superTabs/hotFilters.test.ts@@ -0,0 +1,477 @@+import { readdirSync, readFileSync, writeFileSync } from 'node:fs'+import { join, posix, relative } from 'node:path'+import ts from 'typescript'+import { describe, expect, it } from 'vitest'++// Roadmap Phase 3 (database optimization, 2026-10-29): Prisma sends `in`, `notIn` and `has*` filters as $expr, which the+// planner bounds by an index's first field alone. On 28 Oct such reads on deliveries, native contexts and route decisions+// scanned 50 M documents for 220 k returned. Hot Swarm reads go through the named-index helpers instead (parts/indexed.ts+// readBy, invitedSwarms.ts, pageReads.ts, swarmRows.ts) with a plan test. This test finds every Prisma call on a hot Swarm+// collection (every SuperTab and Swarm model of the schema) whose filter uses one of those operators, also through a delegate+// alias. The ones there were when it was written are allowed (hotFilters.allowed.json) and that list may only shrink: a new+// one fails here. It reads source, not types: a call passes only when its receiver is proven another model's Prisma delegate+// (`db.machine` on a client typed or imported as one); any receiver it cannot tell is listed as `unresolved` for review rather+// than passed. A filter a helper function builds and returns (parts/load.ts `or`) is not followed.++const ROOT = join(import.meta.dirname, '..', '..')+const ALLOWED = join(import.meta.dirname, 'hotFilters.allowed.json')+const SCHEMA = join(ROOT, 'prisma', 'schema.prisma')++/** The Swarm models of a Prisma schema: every `SuperTab*` and `Swarm*` model. */+export function hotModels(schema: string): string[] {+ return [...schema.matchAll(/^model\s+((?:SuperTab|Swarm)\w*)\s*\{/gm)].map(match => match[1]!)+}++const MODELS = new Set(hotModels(readFileSync(SCHEMA, 'utf8')))+/** Their Prisma delegates (`db.swarmGroup`). */+const HOT = new Set([...MODELS].map(model => model[0]!.toLowerCase() + model.slice(1)))+/** `delegate(tx, kind)` (parts/write.ts) stands for any Swarm part collection. */+const PART_DELEGATE = 'delegate'+const METHODS = new Set(['findMany', 'findFirst', 'findFirstOrThrow', 'findUnique', 'findUniqueOrThrow', 'count', 'aggregate', 'groupBy', 'updateMany',+ 'deleteMany', 'update', 'delete', 'upsert'])+const OPERATORS = new Set(['in', 'notIn', 'has', 'hasSome', 'hasEvery'])++export interface HotFilter { file: string; line: number; call: string; operator: string }++const nameOf = (name: ts.PropertyName | ts.MemberName): string | undefined =>+ ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isPrivateIdentifier(name) ? name.text : undefined++/** Every model's delegate, hot or not: a receiver named one of these is known to be that collection. */+const DELEGATES = new Set([...readFileSync(SCHEMA, 'utf8').matchAll(/^model\s+(\w+)\s*\{/gm)].map(match => match[1]![0]!.toLowerCase() + match[1]!.slice(1)))+/** A receiver the lint cannot tell is a hot delegate or not: its calls are listed for review like a hot one's. */+const UNRESOLVED = 'unresolved'++/**+ * What a type says the value is: a hot delegate (`Prisma.SwarmGroupDelegate`, `typeof db.swarmGroup`,+ * `PrismaClient['swarmGroup']`), another model's Prisma delegate type (`Prisma.MachineDelegate`: undefined), or nothing it can+ * prove (UNRESOLVED).+ */+function typeReceiver(type: ts.TypeNode): string | undefined {+ let other = false+ for (const word of type.getText().match(/\w+/g) ?? []) {+ if (HOT.has(word)) return word+ const delegate = word.endsWith('Delegate') ? word[0]!.toLowerCase() + word.slice(1, -'Delegate'.length) : undefined+ if (delegate && HOT.has(delegate)) return delegate+ if (delegate && DELEGATES.has(delegate)) other = true+ }+ return other ? undefined : UNRESOLVED+}++/** Combines what the branches of a conditional may be: hot if any is, else unresolved if any is. */+const either = (...receivers: Array<string | undefined>) => receivers.find(r => r && r !== UNRESOLVED) ?? receivers.find(r => r === UNRESOLVED)++/** Type names that are a Prisma client themselves. */+const CLIENT_TYPES = new Set(['PrismaClient', 'TransactionClient'])+/** Wrappers that keep a client a client (`Pick<PrismaClient, '$transaction'>`). */+const CLIENT_WRAPPERS = new Set(['Pick', 'Omit', 'Readonly'])++/**+ * Whether a type is itself a Prisma client or transaction (`PrismaClient`, `Prisma.TransactionClient`, a type alias of one+ * declared in the same file, `Pick`/`Omit` of one, an intersection with one). A type that only holds one (`{ client:+ * PrismaClient }`) is not.+ */+function clientType(type: ts.TypeNode, seen = new Set<string>()): boolean {+ if (ts.isParenthesizedTypeNode(type)) return clientType(type.type, seen)+ if (ts.isIntersectionTypeNode(type)) return type.types.some(member => clientType(member, seen))+ if (ts.isUnionTypeNode(type)) return type.types.every(member => clientType(member, seen))+ if (!ts.isTypeReferenceNode(type)) return false+ const name = ts.isIdentifier(type.typeName) ? type.typeName.text : type.typeName.right.text+ if (CLIENT_TYPES.has(name)) return true+ if (CLIENT_WRAPPERS.has(name)) return !!type.typeArguments?.[0] && clientType(type.typeArguments[0], seen)+ if (!ts.isIdentifier(type.typeName) || seen.has(name)) return false+ seen.add(name)+ const alias = type.getSourceFile().statements.find((statement): statement is ts.TypeAliasDeclaration =>+ ts.isTypeAliasDeclaration(statement) && statement.name.text === name)+ return !!alias && clientType(alias.type, seen)+}++/**+ * Whether `node` is proven a Prisma client or transaction: a name typed as one, `new PrismaClient()`, the app's client+ * imported from lib/prisma, the callback parameter of a proven client's `$transaction`, or a class field that is one.+ */+function prismaClient(node: ts.Expression, seen = new Set<ts.Node>()): boolean {+ const inner = unwrap(node)+ if (seen.has(inner)) return false+ seen.add(inner)+ if (ts.isNewExpression(inner)) return ts.isIdentifier(inner.expression) && inner.expression.text === 'PrismaClient'+ if (ts.isConditionalExpression(inner)) return prismaClient(inner.whenTrue, seen) && prismaClient(inner.whenFalse, seen)+ if (ts.isBinaryExpression(inner)) return prismaClient(inner.left, seen) && prismaClient(inner.right, seen)+ const bound = ts.isIdentifier(inner) ? declaration(inner.text, inner)+ : ts.isPropertyAccessExpression(inner) && inner.expression.kind === ts.SyntaxKind.ThisKeyword ? classField(inner.name.text, inner) : undefined+ if (!bound) return ts.isIdentifier(inner) && importedClient(inner)+ if (ts.isBindingElement(bound)) return false+ if (bound.type) return clientType(bound.type)+ if (ts.isParameter(bound)) {+ const callback = bound.parent+ const call = callback.parent+ return (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)) && ts.isCallExpression(call)+ && ts.isPropertyAccessExpression(call.expression) && call.expression.name.text === '$transaction' && prismaClient(call.expression.expression, seen)+ }+ return !!bound.initializer && prismaClient(bound.initializer, seen)+}++/** Whether `name` is imported from the app's Prisma client module (src/lib/prisma.ts). */+function importedClient(name: ts.Identifier): boolean {+ return name.getSourceFile().statements.some(statement => ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)+ && posix.join(posix.dirname(name.getSourceFile().fileName), statement.moduleSpecifier.text).replace(/\.js$/, '') === 'src/lib/prisma'+ && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings)+ && statement.importClause.namedBindings.elements.some(element => element.name.text === name.text))+}++/** A delegate reached by name from `owner`: hot by its name, exempt only when `owner` is proven a Prisma client, else unresolved. */+function memberReceiver(owner: ts.Expression, name: string): string | undefined {+ if (HOT.has(name)) return name+ return DELEGATES.has(name) && prismaClient(owner) ? undefined : UNRESOLVED+}++/** What a declared name holds: by its delegate property when destructured, its type, else its initializer. */+function boundReceiver(bound: Binding | ts.PropertyDeclaration, seen: Set<ts.Node>): string | undefined {+ if (ts.isBindingElement(bound)) {+ const property = bound.propertyName ? nameOf(bound.propertyName as ts.PropertyName) : ts.isIdentifier(bound.name) ? bound.name.text : undefined+ if (bound.initializer) return either(property && HOT.has(property) ? property : undefined, hotReceiver(bound.initializer, seen))+ const owner = bound.parent.parent+ const from = ts.isObjectBindingPattern(bound.parent) && (ts.isVariableDeclaration(owner) || ts.isParameter(owner)) ? owner.initializer : undefined+ return property && from ? memberReceiver(from, property) : property && HOT.has(property) ? property : UNRESOLVED+ }+ if (bound.type) return typeReceiver(bound.type)+ return bound.initializer ? hotReceiver(bound.initializer, seen) : UNRESOLVED+}++/** The field `name` of the class holding `at`: a property, or a constructor parameter property. */+function classField(name: string, at: ts.Node): ts.PropertyDeclaration | ts.ParameterDeclaration | undefined {+ let owner: ts.Node | undefined = at.parent+ while (owner && !ts.isClassLike(owner)) owner = owner.parent+ if (!owner) return undefined+ for (const member of (owner as ts.ClassLikeDeclaration).members) {+ if (ts.isPropertyDeclaration(member) && nameOf(member.name) === name) return member+ if (ts.isConstructorDeclaration(member)) {+ const parameter = member.parameters.find(p => ts.isIdentifier(p.name) && p.name.text === name && ts.getModifiers(p)?.length)+ if (parameter) return parameter+ }+ }+ return undefined+}++/**+ * The hot collection a call's receiver is: `x.swarmGroup`, `x['swarmGroup']`, `delegate(tx, kind)`, or a name or field bound+ * to one (`const groups = db.swarmGroup`, `const { swarmGroup: groups } = db`, `this.groups`, a parameter typed as a hot+ * delegate), followed through aliases and conditionals. Undefined only when it is proven another model's Prisma delegate+ * (`db.machine` on a proven client, a name typed `Prisma.MachineDelegate`); UNRESOLVED otherwise (an imported name, another+ * object's field, a call's result, a computed key), so that call is listed for review rather than passed.+ */+function hotReceiver(receiver: ts.Expression, seen = new Set<ts.Node>()): string | undefined {+ const inner = unwrap(receiver)+ if (seen.has(inner)) return UNRESOLVED+ seen.add(inner)+ if (ts.isPropertyAccessExpression(inner)) {+ if (inner.expression.kind === ts.SyntaxKind.ThisKeyword) {+ const field = classField(inner.name.text, inner)+ return field ? boundReceiver(field, seen) : UNRESOLVED+ }+ return memberReceiver(inner.expression, inner.name.text)+ }+ if (ts.isElementAccessExpression(inner)) {+ return ts.isStringLiteralLike(inner.argumentExpression) ? memberReceiver(inner.expression, inner.argumentExpression.text) : UNRESOLVED+ }+ if (ts.isCallExpression(inner)) return ts.isIdentifier(inner.expression) && inner.expression.text === PART_DELEGATE ? 'part' : UNRESOLVED+ if (ts.isConditionalExpression(inner)) return either(hotReceiver(inner.whenTrue, seen), hotReceiver(inner.whenFalse, seen))+ if (ts.isBinaryExpression(inner)) return either(hotReceiver(inner.left, seen), hotReceiver(inner.right, seen))+ if (!ts.isIdentifier(inner)) return UNRESOLVED+ const bound = declaration(inner.text, inner)+ return bound ? boundReceiver(bound, seen) : UNRESOLVED+}++function unwrap(node: ts.Expression): ts.Expression {+ while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node)+ || ts.isTypeAssertionExpression(node)) node = node.expression+ return node+}++type Binding = ts.VariableDeclaration | ts.BindingElement | ts.ParameterDeclaration++/** A node that scopes the `const`/`let`/parameters declared directly in it. */+const scopes = (node: ts.Node): boolean => ts.isSourceFile(node) || ts.isBlock(node) || ts.isModuleBlock(node) || ts.isCaseBlock(node)+ || ts.isCatchClause(node) || ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node) || ts.isFunctionLike(node)+ || ts.isClassLike(node)+/** Where a `var` lands: its function, or the file. */+const hoists = (node: ts.Node): boolean => ts.isSourceFile(node) || ts.isFunctionLike(node) || ts.isModuleBlock(node)+const isVar = (node: Binding): boolean => !ts.isParameter(node) && !(ts.getCombinedNodeFlags(node) & ts.NodeFlags.BlockScoped)++/**+ * The nearest declaration of `name` (a `const`/`let`/`var`, a destructured name or a parameter) before `at` whose scope+ * encloses `at`: the scopes holding `at` are searched from the innermost out, each for its own declarations only, so a+ * declaration in a sibling block or a nested function never shadows the one in force at `at`. A `var` belongs to its+ * function (or the file), so a function searches its nested blocks for `var`s.+ */+function declaration(name: string, at: ts.Node): Binding | undefined {+ for (let scope: ts.Node | undefined = at.parent; scope; scope = scope.parent) {+ if (!scopes(scope)) continue+ let found: Binding | undefined+ const visit = (node: ts.Node, nested: boolean) => {+ if (node.pos > at.pos) return+ if ((ts.isVariableDeclaration(node) || ts.isBindingElement(node) || ts.isParameter(node)) && ts.isIdentifier(node.name) && node.name.text === name+ && node.end <= at.pos && (!nested || isVar(node))) found = node+ // An inner function's declarations are never in force here; an inner block's only when they are `var`s of this function.+ if (ts.isFunctionLike(node) || ts.isClassLike(node)) return+ if (scopes(node)) {+ if (!hoists(scope!)) return+ nested = true+ }+ ts.forEachChild(node, child => visit(child, nested))+ }+ ts.forEachChild(scope, child => visit(child, false))+ if (found) return found+ }+ return undefined+}++/** The initializer of the nearest `const`/`let`/`var` named `name` declared before `at`. */+function declared(name: string, at: ts.Node): ts.Expression | undefined {+ const bound = declaration(name, at)+ return bound && ts.isVariableDeclaration(bound) ? bound.initializer : undefined+}++/** Every filter operator `node` holds, following object literals, spreads, conditionals and local constants. */+function operatorsIn(node: ts.Expression, seen = new Set<ts.Node>()): Array<{ operator: string; node: ts.Node }> {+ const expr = unwrap(node)+ if (seen.has(expr)) return []+ seen.add(expr)+ if (ts.isObjectLiteralExpression(expr)) {+ return expr.properties.flatMap(property => {+ if (ts.isPropertyAssignment(property)) {+ const name = nameOf(property.name)+ return [...name && OPERATORS.has(name) ? [{ operator: name, node: property }] : [], ...operatorsIn(property.initializer, seen)]+ }+ if (ts.isShorthandPropertyAssignment(property)) {+ const value = declared(property.name.text, property)+ return value ? operatorsIn(value, seen) : []+ }+ if (ts.isSpreadAssignment(property)) return operatorsIn(property.expression, seen)+ return []+ })+ }+ if (ts.isConditionalExpression(expr)) return [...operatorsIn(expr.whenTrue, seen), ...operatorsIn(expr.whenFalse, seen)]+ if (ts.isBinaryExpression(expr)) return [...operatorsIn(expr.left, seen), ...operatorsIn(expr.right, seen)]+ if (ts.isArrayLiteralExpression(expr)) return expr.elements.flatMap(element => ts.isSpreadElement(element) ? operatorsIn(element.expression, seen) : operatorsIn(element, seen))+ if (ts.isIdentifier(expr)) {+ const value = declared(expr.text, expr)+ return value ? operatorsIn(value, seen) : []+ }+ return []+}++/** The hot filters of one source file. */+export function hotFilters(file: string, source: string): HotFilter[] {+ const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)+ const found: HotFilter[] = []+ const visit = (node: ts.Node) => {+ if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && METHODS.has(node.expression.name.text)) {+ const model = hotReceiver(node.expression.expression)+ const args = node.arguments[0] && unwrap(node.arguments[0])+ if (model && args) {+ // Only what selects rows: `where`, or the arguments themselves when they are built elsewhere.+ const where = ts.isObjectLiteralExpression(args)+ ? args.properties.flatMap(p => ts.isPropertyAssignment(p) && nameOf(p.name) === 'where' ? [p.initializer]+ : ts.isShorthandPropertyAssignment(p) && p.name.text === 'where' ? [p.name] : ts.isSpreadAssignment(p) ? [p.expression] : [])+ : [args]+ for (const filter of where) {+ for (const { operator, node: at } of operatorsIn(filter)) {+ found.push({ file, line: sf.getLineAndCharacterOfPosition(at.getStart(sf)).line + 1, call: `${model}.${node.expression.name.text}`, operator })+ }+ }+ }+ }+ ts.forEachChild(node, visit)+ }+ visit(sf)+ return found+}++function sources(dir: string): string[] {+ return readdirSync(dir, { withFileTypes: true }).flatMap(entry => {+ const path = join(dir, entry.name)+ if (entry.isDirectory()) return sources(path)+ return entry.name.endsWith('.ts') && !/\.test(-support)?\.ts$/.test(entry.name) && !entry.name.endsWith('.d.ts') ? [path] : []+ })+}++/** Uses by `file call` (file relative to backend/), counted. */+function counted(filters: HotFilter[]): Record<string, number> {+ const counts: Record<string, number> = {}+ for (const filter of filters) {+ const key = `${filter.file} ${filter.call}`+ counts[key] = (counts[key] ?? 0) + 1+ }+ return Object.fromEntries(Object.entries(counts).sort(([a], [b]) => a.localeCompare(b)))+}++/** Fixture source, after a proven Prisma client `db` and transaction `tx`. */+const lint = (source: string) => hotFilters('fixture.ts', `declare const db: PrismaClient\ndeclare const tx: Prisma.TransactionClient\n${source}`)++describe('no new Prisma in/has filter on a hot Swarm collection', () => {+ it('finds them through where, spreads, conditionals and local constants, and only on hot collections', () => {+ const found = lint(`+ const assignmentId = { in: ids }+ const open = cond ? { status: { in: OPEN } } : {}+ await tx.superTabDelivery.updateMany({ where: { tabId, assignmentId }, data: { status: 'cancelled' } })+ await db.swarmGroup.findMany({ where: { tabId, ...open, OR: [{ agentIds: { has: agentId } }] } })+ await delegate(tx, kind).findMany({ where: { tabId: { in: tabIds } } })+ await db.machine.findMany({ where: { machineId: { in: ids } } })+ await db.swarmGroup.updateMany({ where: { tabId }, data: { agentIds: { set: [] } } })+ await readBy(tx, 'SwarmGroup', 'agents', [{ $match: { tabId, agentIds: agentId } }])+ `)+ expect(found.map(f => [f.call, f.operator])).toEqual([+ ['superTabDelivery.updateMany', 'in'], ['swarmGroup.findMany', 'in'], ['swarmGroup.findMany', 'has'], ['part.findMany', 'in']])+ })++ it('follows a delegate through aliases, destructuring, element access and typed parameters', () => {+ const found = lint(`+ const groups = db.swarmGroup+ await groups.findMany({ where: { key: { in: ids } } })+ const again = groups+ await again.count({ where: { agentIds: { has: agentId } } })+ const { superTabDelivery: deliveries, swarmMember } = tx+ await deliveries.updateMany({ where: { status: { in: OPEN } }, data: {} })+ await swarmMember.findMany({ where: { memberId: { in: ids } } })+ await db['superTabRun'].findMany({ where: { id: { in: ids } } })+ const table = delegate(tx, kind)+ await table.deleteMany({ where: { id: { in: ids } } })+ const either = cond ? db.superTabConfiguration : tx.superTabConfiguration+ await either.findMany({ where: { tabId: { in: tabIds } } })+ async function read(roles: Prisma.SuperTabRoleTextDelegate, typed: typeof db.swarmAgent) {+ await roles.findMany({ where: { tabId: { in: tabIds } } })+ await typed.findFirst({ where: { agentId: { in: ids } } })+ }+ const machines = db.machine+ await machines.findMany({ where: { machineId: { in: ids } } })+ async function other(groups: Prisma.MachineDelegate) { await groups.findMany({ where: { machineId: { in: ids } } }) }+ `)+ expect(found.map(f => [f.call, f.operator])).toEqual([+ ['swarmGroup.findMany', 'in'], ['swarmGroup.count', 'has'], ['superTabDelivery.updateMany', 'in'], ['swarmMember.findMany', 'in'],+ ['superTabRun.findMany', 'in'], ['part.deleteMany', 'in'], ['superTabConfiguration.findMany', 'in'], ['superTabRoleText.findMany', 'in'],+ ['swarmAgent.findFirst', 'in']])+ })++ it('resolves a name to the declaration in force at the call, not one in a sibling block or nested function', () => {+ const found = lint(`+ const groups = db.swarmGroup+ if (flag) { const groups = db.machine }+ await groups.findMany({ where: { key: { in: ids } } })+ const ids2 = { in: ids }+ for (const x of xs) { const ids2 = {} }+ const run = () => { const groups = db.machine; return groups }+ await groups.count({ where: { key: ids2 } })+ if (flag) {+ const groups = db.machine+ await groups.findMany({ where: { machineId: { in: ids } } })+ }+ function inner(groups: Prisma.MachineDelegate) { return groups.findMany({ where: { machineId: { in: ids } } }) }+ const outer = db.machine+ { const outer = db.superTabMessage; await outer.findMany({ where: { id: { in: ids } } }) }+ await outer.findMany({ where: { id: { in: ids } } })+ `)+ expect(found.map(f => [f.call, f.operator])).toEqual([['swarmGroup.findMany', 'in'], ['swarmGroup.count', 'in'], ['superTabMessage.findMany', 'in']])+ })++ it('resolves a var to its function, also from a nested block', () => {+ const found = lint(`+ async function read() {+ { var groups = db.swarmGroup }+ await groups.findMany({ where: { key: { in: ids } } })+ if (flag) { var keys = { in: ids } }+ await db.swarmHead.findMany({ where: { key: keys } })+ }+ async function other() { await groups.count({ where: { key: { in: ids } } }) }+ function scoped() { { var machines = db.machine } return machines.findMany({ where: { machineId: { in: ids } } }) }+ `)+ expect(found.map(f => [f.call, f.operator])).toEqual([['swarmGroup.findMany', 'in'], ['swarmHead.findMany', 'in'], ['unresolved.count', 'in']])+ })++ it('lists a call on a receiver it cannot resolve for review, and passes one surely on another collection', () => {+ const found = lint(`+ import { groups } from './elsewhere'+ await groups.findMany({ where: { key: { in: ids } } })+ await repo.groups.findMany({ where: { key: { in: ids } } })+ await pick(tx).findMany({ where: { key: { in: ids } } })+ await db[model].findMany({ where: { key: { in: ids } } })+ async function typed(table: SomeTable) { await table.findMany({ where: { key: { in: ids } } }) }+ await groups.findMany({ where: { key } })+ class Store {+ private groups = db.swarmGroup+ constructor(private db: PrismaClient, private machines: Prisma.MachineDelegate, private runs: typeof db.superTabRun) {}+ async read() {+ await this.groups.findMany({ where: { key: { in: ids } } })+ await this.machines.findMany({ where: { machineId: { in: ids } } })+ await this.runs.count({ where: { id: { in: ids } } })+ await this.db.machine.findMany({ where: { machineId: { in: ids } } })+ await (flag ? this.db.machine : this.other).findMany({ where: { id: { in: ids } } })+ }+ }+ `)+ expect(found.map(f => [f.call, f.operator])).toEqual([+ ['unresolved.findMany', 'in'], ['unresolved.findMany', 'in'], ['unresolved.findMany', 'in'], ['unresolved.findMany', 'in'], ['unresolved.findMany', 'in'],+ ['swarmGroup.findMany', 'in'], ['superTabRun.count', 'in'], ['unresolved.findMany', 'in']])+ })++ it('passes a non-hot model name only on a proven Prisma client', () => {+ const found = lint(`+ class Store {+ private machine = db.swarmGroup+ read() { return this.machine.findMany({ where: { key: { in: ids } } }) }+ }+ await repo.machine.findMany({ where: { machineId: { in: ids } } })+ await db[name].findMany({ where: { machineId: { in: ids } } })+ await repo['machine'].findMany({ where: { machineId: { in: ids } } })+ await db['machine'].findMany({ where: { machineId: { in: ids } } })+ await db.machine.findMany({ where: { machineId: { in: ids } } })+ await prisma.machine.findMany({ where: { machineId: { in: ids } } })+ await db.$transaction(async t => t.machine.findMany({ where: { machineId: { in: ids } } }))+ async function run(client: Client) { await client.machine.findMany({ where: { machineId: { in: ids } } }) }+ type Client = Prisma.TransactionClient+ const { machine } = db+ await machine.findMany({ where: { machineId: { in: ids } } })+ const { machine: other } = repo+ await other.findMany({ where: { machineId: { in: ids } } })+ `)+ expect(found.map(f => [f.call, f.operator])).toEqual([['swarmGroup.findMany', 'in'], ['unresolved.findMany', 'in'], ['unresolved.findMany', 'in'],+ ['unresolved.findMany', 'in'], ['unresolved.findMany', 'in'], ['unresolved.findMany', 'in']])+ })++ it('takes neither a type holding a client nor any object\'s $transaction as proof', () => {+ const found = lint(`+ async function read(repo: { client: PrismaClient; machine: typeof db.swarmGroup }) {+ await repo.machine.findMany({ where: { key: { in: ids } } })+ }+ async function held(box: Box) { await box.machine.findMany({ where: { machineId: { in: ids } } }) }+ type Box = { client: PrismaClient }+ await repo.$transaction(async t => t.machine.findMany({ where: { machineId: { in: ids } } }))+ await db.$transaction(async t => t.machine.findMany({ where: { machineId: { in: ids } } }))+ async function picked(client: Pick<PrismaClient, 'machine'> & Prisma.TransactionClient) {+ await client.machine.findMany({ where: { machineId: { in: ids } } })+ }+ `)+ expect(found.map(f => [f.call, f.operator])).toEqual([['unresolved.findMany', 'in'], ['unresolved.findMany', 'in'], ['unresolved.findMany', 'in']])+ })++ it('covers every SuperTab and Swarm model in the schema', () => {+ const schema = readFileSync(SCHEMA, 'utf8')+ const models = hotModels(schema)+ const all = [...schema.matchAll(/^model\s+(\w+)\s*\{/gm)].map(match => match[1]!)+ expect(models).toEqual(all.filter(model => /^(SuperTab|Swarm)/.test(model)))+ expect(models).toEqual(expect.arrayContaining(['SuperTab', 'SuperTabConfiguration', 'SuperTabRoleText', 'SuperTabDelivery', 'SwarmGroup', 'SwarmWorkspace']))+ expect(hotModels('model SwarmNew {\n id String @id\n}\nmodel Machine {\n}\nmodel SuperTabLater {\n}\n')).toEqual(['SwarmNew', 'SuperTabLater'])+ const found = lint('await db.superTabRoleText.findMany({ where: { tabId: { in: ids } } })')+ expect(found.map(f => f.call)).toEqual(['superTabRoleText.findMany'])+ })++ it('allows only the uses already listed, and the list only shrinks', () => {+ const current = counted(sources(join(ROOT, 'src')).flatMap(path => hotFilters(relative(ROOT, path), readFileSync(path, 'utf8'))))+ if (process.env.UPDATE_HOT_FILTERS) writeFileSync(ALLOWED, `${JSON.stringify(current, null, 2)}\n`)+ const allowed = JSON.parse(readFileSync(ALLOWED, 'utf8')) as Record<string, number>+ const added = Object.entries(current).filter(([key, count]) => count > (allowed[key] ?? 0))+ .map(([key, count]) => `${key}: ${count} (allowed ${allowed[key] ?? 0})`)+ expect(added, 'A Prisma in/has filter on a hot Swarm collection is sent as $expr, which no index bounds. Read through a named index (parts/indexed.ts readBy) with a plan test instead. An `unresolved` call is one whose collection this test cannot tell: name the delegate (db.swarmGroup, or a parameter typed Prisma.XDelegate), or list it after checking it is not a hot collection.').toEqual([])+ const fewer = Object.entries(allowed).filter(([key, count]) => count > (current[key] ?? 0)).map(([key, count]) => `${key}: ${current[key] ?? 0} (listed ${count})`)+ expect(fewer, 'Fewer uses than listed: lower them in hotFilters.allowed.json (UPDATE_HOT_FILTERS=1 rewrites it).').toEqual([])+ })+})diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.tsindex 5846c17bb..d6ebc05a1 100644--- a/backend/src/superTabs/model.ts+++ b/backend/src/superTabs/model.ts@@ -144,6 +144,9 @@ export interface AgentStart {* says why). Both stay active work; the machine running the agent alerts its Harness Pro (cli/src/superTabs/attention.ts).* `lost`: its agent died, stalled or hit a limit (liveness.ts); no longer active, so the Lead assigns it again or cancels it. */export type WorkStatus = 'planned' | 'working' | 'needs_human' | 'blocked' | 'review' | 'done' | 'stopped' | 'cancelled' | 'reconciling' | 'lost'+/** The first line of the system row `work.status` writes for each status an agent sets (commands.ts); catchUp.ts reads it back. */+export const STATUS_LABELS = { working: 'Working', needs_human: 'Needs a human', blocked: 'Stuck', review: 'Ready for review', done: 'Done',+ stopped: 'Stopped' } as const satisfies Partial<Record<WorkStatus, string>>export interface Check {id: stringdescription: stringdiff --git a/backend/src/superTabs/pageReads.ts b/backend/src/superTabs/pageReads.tsindex c3afd78fd..94a8ed67a 100644--- a/backend/src/superTabs/pageReads.ts+++ b/backend/src/superTabs/pageReads.ts@@ -94,6 +94,22 @@ export async function messagesPast(tx: Transaction, at: { tabId: string; conversreturn [...same, ...await read(edge ? { [op]: edge.sequence } : undefined, undefined, limit - same.length)]}+/**+ * The messages of one conversation with these ids, by the id index: what a page's rows name as their thread or reply-to but+ * the page does not hold (store.ts messages), so what this reader may see of them can be checked. Named, not Prisma's `id in`,+ * which is sent as $expr and left to the planner (roadmap Phase 3; plan test in integration/superTabNamedReads.test.ts).+ */+export async function messagesById(tx: Transaction, tabId: string, conversationId: string, ids: string[]):+ Promise<Array<Pick<SuperTabMessage, 'id' | 'source' | 'recipientIds'>>> {+ if (!ids.length) return []+ const rows = await readBy(tx, 'SuperTabMessage', 'id', [{ $match: { _id: { $in: ids }, tabId, conversationId } },+ { $project: { source: 1, recipientIds: 1 } }])+ return rows.map(row => {+ const { id, source, recipientIds } = prismaRow<SuperTabMessage>('SuperTabMessage', row)+ return { id, source, recipientIds }+ })+}+/** The Lead's notices that leave a copy in a task's chat when the Lead hears them in its own chat (terminal.ts toLead). */const LEAD_COPY_KINDS = new Set<unknown>(['work-lost', 'work-resumed'])diff --git a/backend/src/superTabs/parts/indexed.ts b/backend/src/superTabs/parts/indexed.tsindex d04bdcfd2..e3c828f2d 100644--- a/backend/src/superTabs/parts/indexed.ts+++ b/backend/src/superTabs/parts/indexed.ts@@ -32,15 +32,19 @@ export const NAMED_INDEX = {SuperTab: {/** An owner's Swarms in id order: the grid poll. */owner: { autonomousEnv: 1, ownerId: 1, _id: 1 },+ /** The Swarms inviting each address (invitedSwarms.ts), and every Swarm with an invitation (the hourly sweep). */+ invited: { autonomousEnv: 1, invitedEmails: 1, _id: 1 },/** A member's Swarms in id order: Swarm lists and Workspace removals. */members: { autonomousEnv: 1, memberIds: 1, _id: 1 },},/** Each part kind's changes since a cursor; machines also by when they were last read. */SwarmHead: { changes: { tabId: 1, changedAt: 1 } },- SwarmMember: { changes: { tabId: 1, changedAt: 1 } },- SwarmAgent: { changes: { tabId: 1, changedAt: 1 } },- SwarmMachine: { changes: { tabId: 1, changedAt: 1 }, read: { tabId: 1, readAt: 1 } },- SwarmStart: { changes: { tabId: 1, changedAt: 1 } },+ /** `purge`: tombstones past their purge time (the hourly sweep). */+ SwarmMember: { changes: { tabId: 1, changedAt: 1 }, purge: { purgeAt: 1 } },+ SwarmAgent: { changes: { tabId: 1, changedAt: 1 }, purge: { purgeAt: 1 } },+ SwarmMachine: { changes: { tabId: 1, changedAt: 1 }, read: { tabId: 1, readAt: 1 }, purge: { purgeAt: 1 } },+ /** `expiry`: live starts by finish time (the hourly sweep). */+ SwarmStart: { changes: { tabId: 1, changedAt: 1 }, expiry: { deleted: 1, finishedAt: 1 } },SwarmProgress: { changes: { tabId: 1, changedAt: 1 } },SuperTabMessage: {/** A conversation's page in (sequence, id) order. */diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex e0491ce28..54f7234de 100644--- a/backend/src/superTabs/store.ts+++ b/backend/src/superTabs/store.ts@@ -12,7 +12,7 @@ import { applyCommand, authorizeCommandAccess, operationSchema, PAIR_CHAIN_LIMITimport { redactCredentials } from './credentials.js'import type { AvatarUpload } from './profile.js'import { reactionCounts, type ReactionTarget } from './reactions.js'-import { agentOpenDeliveries, deliveredCopies, messagesPast, OPEN_DELIVERY, type MessageEdge, pageDeliveries, pageReactions, pageThreads } from './pageReads.js'+import { agentOpenDeliveries, deliveredCopies, messagesById, messagesPast, OPEN_DELIVERY, type MessageEdge, pageDeliveries, pageReactions, pageThreads } from './pageReads.js'import { threadSummaries } from './threads.js'import { attachmentMime, attachmentName, AttachmentTooLarge, AVATAR_PURPOSE, AVATAR_TYPES, checkedType, MAX_ATTACHMENT_BYTES, MAX_AVATAR_BYTES, objectKeyFor, peekType, publicUrl, trimPrefix,type Attachment, type Attachments, type AttachmentStore, type AvatarStore } from './attachments.js'@@ -56,7 +56,8 @@ import { costRows, summarizeCosts } from './costs/read.js'import { recordEvidence } from './evidence/store.js'import { closeAssignment, closeUnassignedStart, readDecision, recentDecisions, recordAttempts, timedDecisionOf, writeRouteEffects } from './routeDecisions.js'import { listMentions, markDone, mentionsWaiting, openTags, readMention, resolveByReply, writeMentions } from './mentions.js'-import { answerable, fullFor, listDecisions, type DecisionList, readAskedDecision, recordAnswer, repeatOf, waitingIn, waitingInProject, writeDecisions } from './decisions.js'+import { answerable, fullFor, listDecisions, type DecisionList, readAskedDecision, recordAnswer, repeatOf, waitingFor, waitingIn, waitingInProject, writeDecisions } from './decisions.js'+import { CATCH_UP_SCAN, catchUpSummary, type CatchUp } from './catchUp.js'import { DEFAULT_ROUTING_POLICY, effectivePolicy, routingPolicySchema, type RoutingPolicy } from './routingPolicy.js'import { invitedSwarms } from './invitedSwarms.js'import { authenticatedEmail, authorizeSwarmJoin, configureSharing, joinSwarmSchema, requireSharingOwner,@@ -360,6 +361,12 @@ export class GrantReads {* as a busy load of a share's own Swarm hides its shares (Lead, review of #1973), rather than failing every share. */const busyListing = (tabId: string) => logger.warn('[super-tab] shares list: a busy Swarm hid the shares it could not answer for', { tabId })+/** Whether `actor` reads a row of a conversation they read: an agent-only notice is listed for its own recipient alone, and a+ * Buddy reads its project's workgroups but never how work is routed: a route row names the machines that could run it and why+ * others could not (security review 2 of #2115). */+const readsRow = (actor: Actor, buddy: boolean) => (m: Pick<SuperTabMessage, 'source' | 'recipientIds'>): boolean =>+ (!agentOnly(m.source, m.recipientIds) || (actor.kind === 'agent' && m.recipientIds.includes(actor.agentId))) && !(buddy && routingRow(m.source))+/** A row as a Buddy reads it, without the machine it names (security reviews of #2115): a lost task's reason, in its text and* its source (liveness.ts loseTask), and a machine leaving the Swarm (machines.ts removalEnded, commands.ts removeMachine). */function withoutMachineNames(m: SuperTabMessage): SuperTabMessage {@@ -1920,10 +1927,8 @@ export class SuperTabStore {const actor = await this.actor(tx, user, state, asAgentId)const group = readConversation(state, actor, conversationId)// A Buddy reads its project's workgroups but never how work is routed: a route row names the machines that could run it- // and why others could not (security review 2 of #2115). Left out like an agent-only notice, so no page is shorter.- const buddy = isBuddyReader(state, actor)- const readable = (m: Pick<SuperTabMessage, 'source' | 'recipientIds'>) => (!agentOnly(m.source, m.recipientIds) || (actor.kind === 'agent' && m.recipientIds.includes(actor.agentId)))- && !(buddy && routingRow(m.source))+ // and why others could not (security review 2 of #2115). Left out like an agent-only notice (readsRow), so no page is shorter.+ const buddy = isBuddyReader(state, actor), readable = readsRow(actor, buddy)// One thread is read only through a root this reader may read. A hidden root (an agent-only note to someone else; for a// Buddy, a route row) reads as one that is not in this conversation, and as an exact message it may not see: an empty// page, never its replies alone (review 2 of #2168). By its id, through the primary key.@@ -1940,7 +1945,7 @@ export class SuperTabStore {const at = { tabId, conversationId, messageId: cursor.messageId, thread: cursor.thread }const start: MessageEdge | undefined = forward ? { sequence: cursor.after!, id: cursor.afterId }: cursor.before !== undefined ? { sequence: cursor.before, id: cursor.beforeId } : undefined- // An agent-only notice is listed for its own recipient alone. Hidden rows never shorten a page: Desktop reads on from the+ // Hidden rows never shorten a page: Desktop reads on from the// last row it shows, so the page reads past them until it has 101 rows this reader may see, or reaches the end.// Each batch reads on from the last row of the one before, never by an offset that walks every row before it again.const rows: SuperTabMessage[] = []@@ -1963,8 +1968,7 @@ export class SuperTabStore {const onPage = new Set(page.map(m => m.id))const pointed = [...new Set(page.flatMap(m => [m.thread, m.replyTo]).filter((id): id is string => !!id && !onPage.has(id)))]// A task chat's copy of a Lead's notice stored before it was marked is read by no one (pageReads.ts deliveredCopies).- const pointedRows = pointed.length ? await tx.superTabMessage.findMany({ where: { tabId, conversationId, id: { in: pointed } },- select: { id: true, source: true, recipientIds: true } }) : []+ const pointedRows = await messagesById(tx, tabId, conversationId, pointed)const pointedCopies = pointedRows.length ? await deliveredCopies(tx, tabId, pointedRows) : new Set<string>()const hidden = new Set(pointedRows.filter(m => !readable(m) || pointedCopies.has(m.id)).map(m => m.id))// The threads the page's rows are in, so a poll that brings only a reply still moves its root's reply line.@@ -1980,6 +1984,27 @@ export class SuperTabStore {reactionSeq: group.reactionSeq ?? 0 }}+ /** What the person missed in one conversation since `after` (catchUp.ts), from the rows past it they may read, as a page+ * shows them: the same read check and row filter as messages(). People only, reading as themselves: agents read every+ * message as it comes. At most CATCH_UP_SCAN rows are read; `more` says there were more. */+ async catchUp(user: AuthUser, tabId: string, conversationId: string, after: number): Promise<CatchUp> {+ this.personOnly(user)+ const { state } = await this.readLoad(user, tabId, { groupIds: [conversationId] })+ const actor = await this.actor(this.db, user, state)+ readConversation(state, actor, conversationId)+ const buddy = isBuddyReader(state, actor)+ const [rows, decisions] = await Promise.all([+ this.db.superTabMessage.findMany({ where: { tabId, conversationId, sequence: { gt: after } }, orderBy: [{ sequence: 'asc' }, { id: 'asc' }],+ take: CATCH_UP_SCAN + 1 }),+ waitingFor(this.db, tabId, conversationId, user.sub),+ ])+ const scanned = rows.slice(0, CATCH_UP_SCAN), reads = readsRow(actor, buddy)+ // A task chat's copy of a Lead's notice stored before it was marked is read by no one, as on the page (pageReads.ts).+ const copies = await deliveredCopies(this.db, tabId, scanned)+ const shown = scanned.filter(m => !copies.has(m.id) && reads(m))+ return catchUpSummary(buddy ? shown.map(withoutMachineNames) : shown, user.sub, { after, more: rows.length > CATCH_UP_SCAN, decisions })+ }+/** The caller's own tags in this Swarm, newest first: still waiting, or answered and marked done. */async mentions(user: AuthUser, tabId: string, state: 'waiting' | 'earlier') {this.personOnly(user)diff --git a/backend/src/superTabs/sweeps.ts b/backend/src/superTabs/sweeps.tsindex 75b2e9dcb..6b2379a1e 100644--- a/backend/src/superTabs/sweeps.ts+++ b/backend/src/superTabs/sweeps.ts@@ -5,6 +5,8 @@ import { DORMANT_AFTER_MS, RETENTION_MS } from './parts/types.js'import { logger } from '../utils/logger.js'import { ensureIndex } from '../lib/db/indexes.js'import { swarmTransaction } from './cache.js'+import { listNamedIndexes, readBy } from './parts/indexed.js'+import { autonomousEnvironments } from '../lib/autonomousEnvironment.js'import { expireEvidence } from './evidence/store.js'/** Parts whose key is never used twice (conversations, starts, projects' progress) lose their tombstone at `purgeAt`.@@ -25,9 +27,21 @@ export async function ensurePartExpiry(db: PrismaClient): Promise<void> {/** A removed person, agent or machine keeps its tombstone after its 7 days, with its data dropped: the version it holds* is where a part added again under that key continues (parts/write.ts). Readers already passed its removal. */async function compactTombstones(db: PrismaClient, now: number): Promise<number> {+ // Plain matches on the purge index (parts/indexed.ts). Through Prisma, `purgeAt: { lt }` was $expr, which no index bounds+ // (a collection scan each hour) and where a null purge time is less than any date: every tombstone compacted before was+ // compacted again, each hour (roadmap Phase 3.6).+ const due = { deleted: true, purgeAt: { $lt: { $date: new Date(now).toISOString() } } }let compacted = 0- for (const model of [db.swarmMember, db.swarmAgent, db.swarmMachine] as unknown as Array<{ updateMany(args: unknown): Promise<{ count: number }> }>) {- compacted += (await model.updateMany({ where: { deleted: true, purgeAt: { lt: new Date(now) } }, data: { data: {}, purgeAt: null } })).count+ for (const collection of ['SwarmMember', 'SwarmAgent', 'SwarmMachine'] as const) {+ for (;;) {+ const ids = (await readBy(db, collection, 'purge', [{ $match: due }, { $limit: BATCH }, { $project: { _id: 1 } }])).map(row => row._id as string)+ if (!ids.length) break+ // The same match again: a tombstone revived since the read is left alone.+ const reply = await db.$runCommandRaw({ update: collection, updates: [{ q: { _id: { $in: ids }, ...due }, u: { $set: { data: {}, purgeAt: null } }, multi: true }] }) as+ unknown as { nModified?: number }+ compacted += Number(reply.nModified ?? 0)+ if (ids.length < BATCH) break+ }}return compacted}@@ -88,23 +102,29 @@ async function sleepQuietGroups(db: PrismaClient, now: number): Promise<number>/** Finished starts are kept 7 days, then removed (spec, Archive); their tombstones go 7 days later (purge index). */async function expireStarts(db: PrismaClient, now: number): Promise<number> {- // A plain match: Prisma sent `finishedAt: { lt }` as $expr, where a null finish time is less than any date, so every start- // still starting was removed too (2026-10-29). Here a start with no finish time never matches.- const rows = await db.swarmStart.aggregateRaw({ pipeline: [+ // A plain match on the expiry index: through Prisma, `finishedAt: { lt }` was $expr, where a null finish time is less than+ // any date, so every start still starting was removed too (#2169). Here a start with no finish time never matches.+ const rows = await readBy(db, 'SwarmStart', 'expiry', [{ $match: { deleted: false, finishedAt: { $lt: { $date: new Date(now - RETENTION_MS).toISOString() } } } }, { $limit: BATCH },- { $project: { tabId: 1, key: 1, version: 1, data: 1 } }] }) as unknown as Array<{ tabId: string; key: string; version: number; data: unknown }>+ { $project: { tabId: 1, key: 1, version: 1, data: 1 } }])let expired = 0for (const row of rows) {- if (await guarded(db, { tabId: row.tabId, op: 'remove', kind: 'start', key: row.key, seen: Number(row.version), data: row.data as AgentStart })) expired+++ if (await guarded(db, { tabId: row.tabId as string, op: 'remove', kind: 'start', key: row.key as string, seen: Number(row.version), data: row.data as unknown as AgentStart })) expired++}return expired}/** Expired invitations leave the head and the index the invited person's list is read from (spec, Archive). */async function expireInvitations(db: PrismaClient, now: number): Promise<number> {- const heads = await db.swarmHead.findMany({ where: { deleted: false } })+ // Only the Swarms with an invitation: their row's invitation index names each invited address (parts/commit.ts), so the+ // invitation index holds exactly them. Every head was read whole each hour before (roadmap Phase 3.6).+ // Each environment named, so the index bounds the addresses within it; an empty list holds no address.+ const invited = await readBy(db, 'SuperTab', 'invited', [{ $match: { autonomousEnv: { $in: [...autonomousEnvironments] }, invitedEmails: { $gte: '' } } },+ { $group: { _id: '$_id' } }])let expired = 0- for (const head of heads) {+ for (const { _id: tabId } of invited) {+ const head = await db.swarmHead.findUnique({ where: { id: `${tabId as string}:head` } })+ if (!head || head.deleted) continueconst data = head.data as unknown as HeadDataconst kept = data.invitations.filter(i => i.expiresAt > now)if (kept.length === data.invitations.length) continue@@ -132,7 +152,9 @@ export async function sweepSwarms(db: PrismaClient, now = Date.now()) {/** Runs the sweeps every hour in the singleton worker. `finishWorkspaceRemovals` finishes Workspace removals whose Swarm removals* did not all run (workspaceStore.ts SwarmWorkspaces.finishRemovals); it needs the store, so the worker passes it in. */export function startSwarmSweeps(db: PrismaClient, everyMs = 3_600_000, finishWorkspaceRemovals?: () => Promise<number>): () => void {- const run = () => void sweepSwarms(db).then(async result => ({ ...result, workspaceRemovalsPending: await finishWorkspaceRemovals?.() }))+ // The worker names indexes as servers do: listed before each pass, so a pass after the schema push names them.+ const run = () => void listNamedIndexes(db).catch(error => logger.warn('[swarm-sweeps] listing indexes failed', { error: error instanceof Error ? error.message : String(error) }))+ .then(() => sweepSwarms(db)).then(async result => ({ ...result, workspaceRemovalsPending: await finishWorkspaceRemovals?.() })).then(result => logger.info('[swarm-sweeps] done', result)).catch(error => logger.warn('[swarm-sweeps] failed', { error: error instanceof Error ? error.message : String(error) }))run()diff --git a/backend/vitest.super-tabs.config.ts b/backend/vitest.super-tabs.config.tsindex 0e697995b..145397460 100644--- a/backend/vitest.super-tabs.config.ts+++ b/backend/vitest.super-tabs.config.ts@@ -6,5 +6,5 @@ export default defineConfig({ test: { include: ['integration/superTabs.test.ts','integration/superTabHotReads.test.ts', 'integration/swarmSweepStarts.test.ts', 'integration/superTabGroupPlans.test.ts', 'integration/superTabInvitationPlans.test.ts', 'integration/superTabCache.test.ts','integration/superTabObserver.test.ts', 'integration/productUsageConflicts.test.ts', 'integration/productUsageReceipts.test.ts', 'integration/schemaRelease.test.ts', 'integration/superTabBuddies.test.ts','integration/superTabBuddyProbes.test.ts', 'integration/superTabCosts.test.ts', 'integration/harnessSharesList.test.ts', 'integration/atlasSnapshot.test.ts', 'integration/queryStats.test.ts',- 'integration/superTabEvidence.test.ts', 'integration/superTabNamedReads.test.ts'], hookTimeout: 120000, testTimeout: 30000, setupFiles: ['integration/cacheOn.test-support.ts'],+ 'integration/superTabEvidence.test.ts', 'integration/superTabNamedReads.test.ts', 'integration/swarmSweepPlans.test.ts', 'integration/workerIndexPlans.test.ts'], hookTimeout: 120000, testTimeout: 30000, setupFiles: ['integration/cacheOn.test-support.ts'],fileParallelism: false, env: { NODE_ENV: 'test', HARNESS_CREDENTIAL_ENCRYPTION_KEY: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' } } })diff --git a/desktop/lib/super_tabs/catch_up.dart b/desktop/lib/super_tabs/catch_up.dartnew file mode 100644index 000000000..93403e134--- /dev/null+++ b/desktop/lib/super_tabs/catch_up.dart@@ -0,0 +1,131 @@+import 'model.dart';++/// One row the catch-up card links to (backend catchUp.ts): who wrote it and+/// what it says, shortened by the server.+class SuperTabCatchUpItem {+ const SuperTabCatchUpItem({+ required this.messageId,+ required this.author,+ required this.text,+ });++ factory SuperTabCatchUpItem.fromJson(Map<String, dynamic> row) =>+ SuperTabCatchUpItem(+ messageId: row['messageId'] as String? ?? '',+ author: row['author'] as String? ?? '',+ text: row['text'] as String? ?? '',+ );++ final String messageId, author, text;+}++/// One list of the card: its newest items, and how many there are in all.+class SuperTabCatchUpList {+ const SuperTabCatchUpList({this.total = 0, this.items = const []});++ /// A list missing from the answer, or a row that is not one, reads as+ /// nothing, never a failed read.+ factory SuperTabCatchUpList.fromJson(Object? value) {+ final row = value is Map ? superTabMap(value) : const <String, dynamic>{};+ final items = [+ for (final item in row['items'] as List? ?? const [])+ if (item is Map) SuperTabCatchUpItem.fromJson(superTabMap(item)),+ ].where((item) => item.messageId.isNotEmpty).toList();+ final total = (row['total'] as num?)?.toInt() ?? items.length;+ return SuperTabCatchUpList(+ total: total < items.length ? items.length : total,+ items: List.unmodifiable(items),+ );+ }++ final int total;+ final List<SuperTabCatchUpItem> items;++ /// The items counted but not shown.+ int get more => total - items.length;+}++/// "While you were away": what the reader missed in one conversation since+/// their read mark, as the backend summarizes it from the rows they may read+/// (catchUp.ts).+class SuperTabCatchUp {+ const SuperTabCatchUp({+ this.more = false,+ this.unread = 0,+ this.decisions = 0,+ this.landed = const SuperTabCatchUpList(),+ this.blocked = const SuperTabCatchUpList(),+ this.needsYou = const SuperTabCatchUpList(),+ });++ factory SuperTabCatchUp.fromJson(Map<String, dynamic> row) => SuperTabCatchUp(+ more: row['more'] == true,+ unread: (row['unread'] as num?)?.toInt() ?? 0,+ decisions: (row['decisions'] as num?)?.toInt() ?? 0,+ landed: SuperTabCatchUpList.fromJson(row['landed']),+ blocked: SuperTabCatchUpList.fromJson(row['blocked']),+ needsYou: SuperTabCatchUpList.fromJson(row['needsYou']),+ );++ /// The span is longer than one summary reads (backend CATCH_UP_SCAN): the+ /// lists and [unread] cover only its first part, and no status is listed.+ final bool more;++ final int unread, decisions;+ final SuperTabCatchUpList landed, blocked, needsYou;++ /// Nothing landed, is blocked or needs the reader: no card, since a count+ /// of new messages alone is what the New messages line already says. A+ /// partial summary always shows, so the reader learns it is partial.+ bool get isEmpty =>+ !more &&+ decisions == 0 &&+ landed.items.isEmpty &&+ blocked.items.isEmpty &&+ needsYou.items.isEmpty;+}++/// Each conversation's catch-up card for this visit: read once, when its New+/// messages line is placed, and gone with the line (Esc, leaving the+/// conversation) or when closed. A read that fails or comes back empty shows+/// no card; the line is unchanged either way.+class SuperTabCatchUps {+ final _shown = <String, SuperTabCatchUp>{};++ /// The read under way or done this visit, by conversation: a reply to an+ /// earlier visit's read is never shown in this one.+ final _asked = <String, Object>{};++ /// [id]'s card, or null.+ SuperTabCatchUp? of(String id) => _shown[id];++ /// Reads [id]'s summary with [read], once a visit; true when a card is now+ /// shown.+ Future<bool> load(String id, Future<SuperTabCatchUp> Function() read) async {+ if (_asked.containsKey(id)) return false;+ final visit = _asked[id] = Object();+ try {+ final summary = await read();+ if (!identical(_asked[id], visit) || summary.isEmpty) return false;+ _shown[id] = summary;+ return true;+ } catch (_) {+ // Offline, or an older backend: the New messages line says enough.+ return false;+ }+ }++ /// Closed by the reader, or read with Esc: not read again this visit.+ void dismiss(String id) => _shown.remove(id);++ /// [id] was left: the next visit reads again.+ void forget(String? id) {+ _asked.remove(id);+ _shown.remove(id);+ }++ void reset() {+ _asked.clear();+ _shown.clear();+ }+}diff --git a/desktop/lib/super_tabs/catch_up_card.dart b/desktop/lib/super_tabs/catch_up_card.dartnew file mode 100644index 000000000..398b11296--- /dev/null+++ b/desktop/lib/super_tabs/catch_up_card.dart@@ -0,0 +1,215 @@+import 'package:flutter/material.dart';++import '../shared/theme/app_icons.dart';+import '../shared/theme/app_theme.dart' as grid;+import '../shared/widgets/app_icon_button.dart';+import '../widgets/desktop_chrome.dart';+import 'catch_up.dart';++/// "While you were away", under the New messages line: what needs the reader,+/// what is blocked and what landed, each item opening its message+/// ([onOpen]), and Close ([onClose]). Each list has its words as well as its+/// mark, so colour is never the only signal.+class SuperTabCatchUpCard extends StatelessWidget {+ const SuperTabCatchUpCard({+ super.key,+ required this.summary,+ required this.onOpen,+ required this.onClose,+ });++ final SuperTabCatchUp summary;+ final ValueChanged<String> onOpen;+ final VoidCallback onClose;++ @override+ Widget build(BuildContext context) {+ grid.AppTheme.watch(context);+ final decisions = summary.decisions;+ return Padding(+ padding: const EdgeInsets.fromLTRB(+ grid.AppDesktop.panelPadding,+ grid.AppDesktop.controlGap,+ grid.AppDesktop.panelPadding,+ grid.AppDesktop.controlGap,+ ),+ child: Semantics(+ container: true,+ label: 'While you were away',+ child: DecoratedBox(+ key: const ValueKey('super-catch-up'),+ decoration: BoxDecoration(+ color: DesktopChrome.surface,+ border: Border.all(color: DesktopChrome.rim),+ borderRadius: BorderRadius.circular(DesktopChrome.rowRadius),+ ),+ child: Padding(+ padding: const EdgeInsets.fromLTRB(+ grid.AppDesktop.groupGap,+ grid.AppDesktop.controlGap,+ grid.AppDesktop.controlGap,+ grid.AppDesktop.groupGap,+ ),+ child: Column(+ crossAxisAlignment: CrossAxisAlignment.start,+ children: [+ _header(),+ _section(+ 'Needs you',+ AppIcons.hand,+ DesktopChrome.accent,+ summary.needsYou,+ ),+ _section(+ 'Blocked',+ AppIcons.triangleAlert,+ grid.AppPalette.warn,+ summary.blocked,+ ),+ _section(+ 'Landed',+ AppIcons.circleCheck,+ grid.AppPalette.online,+ summary.landed,+ ),+ if (decisions > 0)+ _note(+ decisions == 1+ ? '1 decision waits for you'+ : '$decisions decisions wait for you',+ ),+ // Never a partial summary read as the whole absence.+ if (summary.more)+ _note(+ 'Covers only the first part of what you missed. '+ 'Newer messages are below.',+ ),+ ],+ ),+ ),+ ),+ ),+ );+ }++ Widget _note(String text) => Padding(+ padding: const EdgeInsets.only(top: grid.AppDesktop.controlGap),+ child: Text(text, style: DesktopChrome.metadata()),+ );++ Widget _header() => Row(+ children: [+ Icon(+ AppIcons.sparkles,+ size: grid.AppDesktop.iconSize,+ color: DesktopChrome.accent,+ ),+ const SizedBox(width: grid.AppDesktop.controlGap),+ Text('While you were away', style: DesktopChrome.control(medium: true)),+ const SizedBox(width: grid.AppDesktop.controlGap),+ // The count takes the spare width, so Close sits at the card's end.+ Expanded(+ child: Text(+ switch ((summary.unread, summary.more)) {+ (0, _) => '',+ (final count, true) => '$count+ new messages',+ (1, false) => '1 new message',+ (final count, false) => '$count new messages',+ },+ style: DesktopChrome.metadata(),+ overflow: TextOverflow.ellipsis,+ ),+ ),+ AppIconButton(+ key: const ValueKey('super-catch-up-close'),+ tooltip: 'Close',+ icon: AppIcons.close,+ onPressed: onClose,+ ),+ ],+ );++ Widget _section(+ String heading,+ IconData icon,+ Color color,+ SuperTabCatchUpList list,+ ) {+ if (list.items.isEmpty) return const SizedBox.shrink();+ return Padding(+ padding: const EdgeInsets.only(top: grid.AppDesktop.controlGap),+ child: Column(+ crossAxisAlignment: CrossAxisAlignment.start,+ children: [+ Text(+ heading,+ style: DesktopChrome.metadata().copyWith(+ fontWeight: grid.AppFont.semibold,+ ),+ ),+ for (final item in list.items)+ _SuperTabCatchUpRow(+ item: item,+ icon: icon,+ color: color,+ onOpen: () => onOpen(item.messageId),+ ),+ if (list.more > 0)+ Text('${list.more} more', style: DesktopChrome.metadata()),+ ],+ ),+ );+ }+}++/// One item: its mark, who wrote it and what it says; opens its message.+class _SuperTabCatchUpRow extends StatelessWidget {+ const _SuperTabCatchUpRow({+ required this.item,+ required this.icon,+ required this.color,+ required this.onOpen,+ });++ final SuperTabCatchUpItem item;+ final IconData icon;+ final Color color;+ final VoidCallback onOpen;++ @override+ Widget build(BuildContext context) => InkWell(+ key: ValueKey('super-catch-up-${item.messageId}'),+ onTap: onOpen,+ hoverColor: grid.AppSurface.hoverFill,+ borderRadius: BorderRadius.circular(DesktopChrome.controlRadius),+ child: Padding(+ padding: const EdgeInsets.symmetric(vertical: grid.AppDesktop.listRowGap),+ child: Row(+ crossAxisAlignment: CrossAxisAlignment.start,+ children: [+ Padding(+ padding: const EdgeInsets.only(top: grid.AppDesktop.listRowGap),+ child: Icon(icon, size: grid.AppDesktop.iconSize, color: color),+ ),+ const SizedBox(width: grid.AppDesktop.controlGap),+ Expanded(+ child: Text.rich(+ TextSpan(+ children: [+ if (item.author.isNotEmpty)+ TextSpan(+ text: '${item.author} ',+ style: DesktopChrome.control(medium: true),+ ),+ TextSpan(text: item.text, style: DesktopChrome.control()),+ ],+ ),+ maxLines: 2,+ overflow: TextOverflow.ellipsis,+ ),+ ),+ ],+ ),+ ),+ );+}diff --git a/desktop/lib/super_tabs/controller.dart b/desktop/lib/super_tabs/controller.dartindex 694a28fb3..38b455d49 100644--- a/desktop/lib/super_tabs/controller.dart+++ b/desktop/lib/super_tabs/controller.dart@@ -13,6 +13,7 @@ import 'avatar_upload.dart';import 'message_link.dart';import 'model.dart';import 'buddy_chat.dart';+import 'catch_up.dart';import 'project_github.dart';import 'parts.dart';import 'read_marks.dart';@@ -1469,6 +1470,17 @@ class SuperTabController extends ChangeNotifier {int readMark(String id) =>max(_readAt[id] ?? 0, snapshot?.readMarks[id] ?? 0);+ /// What the reader missed in [id] after [after] (backend catchUp.ts).+ Future<SuperTabCatchUp> readCatchUp(String id, int after) async =>+ SuperTabCatchUp.fromJson(+ superTabMap(+ await request(+ 'GET',+ '$_path/conversations/${Uri.encodeComponent(id)}/catch-up?after=$after',+ ),+ ),+ );+late final _serverMarks = SuperTabReadMarkSender((id, sequence) => request('POST',diff --git a/desktop/lib/super_tabs/unread_line.dart b/desktop/lib/super_tabs/unread_line.dartindex bb88e7f33..537334015 100644--- a/desktop/lib/super_tabs/unread_line.dart+++ b/desktop/lib/super_tabs/unread_line.dart@@ -3,6 +3,7 @@ import 'package:flutter/material.dart';import '../shared/theme/app_icons.dart';import '../shared/theme/app_theme.dart' as grid;import '../widgets/desktop_chrome.dart';+import 'catch_up.dart';import 'model.dart';/// The first message of [shown] the reader has not read, for the New messages line: in the main stream (a reply@@ -44,6 +45,9 @@ class SuperTabUnreadLines {final _failed = <String, int>{};static const _tries = 3;+ /// The catch-up card under each line, kept and forgotten with it.+ final catchUps = SuperTabCatchUps();+/// The line on screen, to tell whether it is scrolled out of view.final key = GlobalKey(debugLabel: 'New messages line');@@ -114,12 +118,14 @@ class SuperTabUnreadLines {_loading.remove(id);_loaded.remove(id);_failed.remove(id);+ catchUps.forget(id);away = false;}- /// Read with Esc: no line until the next visit.+ /// Read with Esc: no line or card until the next visit.void clear(String id) {_at[id] = null;+ catchUps.dismiss(id);away = false;}@@ -128,6 +134,7 @@ class SuperTabUnreadLines {_loading.clear();_loaded.clear();_failed.clear();+ catchUps.reset();away = false;}}diff --git a/desktop/lib/super_tabs/view.dart b/desktop/lib/super_tabs/view.dartindex c5009483a..370323e0e 100644--- a/desktop/lib/super_tabs/view.dart+++ b/desktop/lib/super_tabs/view.dart@@ -20,6 +20,7 @@ import '../state/harness_attachments.dart';import '../state/workspace_chrome.dart';import 'chat_scroll.dart';import 'leaderboard/reader.dart';+import 'catch_up_card.dart';import 'jump_to_latest.dart';import 'unread_line.dart';import 'roster.dart';@@ -356,6 +357,7 @@ class _SuperTabViewState extends State<SuperTabView>// The line is placed once the messages reach back to the mark.} else if (_unread.decide(id, shown, mark, own: c.isOwn)) {_revealUnreadLine(id);+ _loadCatchUp(id, mark);} else if (firstView || (grew && atEnd)) {_followEnd(id);} else if (atEnd) {@@ -504,8 +506,14 @@ class _SuperTabViewState extends State<SuperTabView>id,0,arrived: (row) {+ // The line itself, not its row: with the catch-up card under it the+ // row can be taller than the view, and its top would go above it.+ final line = _unread.key.currentContext;unawaited(- Scrollable.ensureVisible(row, alignment: .15).then((_) {+ Scrollable.ensureVisible(+ line != null && line.mounted ? line : row,+ alignment: .15,+ ).then((_) {_checkUnreadLine();}),);@@ -513,6 +521,14 @@ class _SuperTabViewState extends State<SuperTabView>);}+ /// Reads [id]'s catch-up card for the span after [mark], shown under its+ /// line once it arrives.+ void _loadCatchUp(String id, int mark) => unawaited(+ _unread.catchUps.load(id, () => c.readCatchUp(id, mark)).then((shown) {+ if (shown && mounted) setState(() {});+ }),+ );+/// Shows the jump pill while the reader is scrolled away from the line, and/// Jump to latest while the list is away from its newest message.void _checkUnreadLine() {@@ -2701,8 +2717,17 @@ class _SuperTabViewState extends State<SuperTabView>previous?.createdAt?.toLocal(),))_date(time),- if (message.id == _unread.lineAt(c.selectedId))+ if (message.id == _unread.lineAt(c.selectedId)) ...[SuperTabNewMessagesLine(key: _unread.key),+ if (_unread.catchUps.of(c.selectedId) case final summary?)+ SuperTabCatchUpCard(+ summary: summary,+ onOpen: (messageId) =>+ unawaited(_openMessage(c.selectedId, messageId)),+ onClose: () =>+ setState(() => _unread.catchUps.dismiss(c.selectedId)),+ ),+ ],// The message itself is kept in place: its// date moves above earlier ones as they come._BuiltRow(diff --git a/desktop/test/super_tab_catch_up_shots_test.dart b/desktop/test/super_tab_catch_up_shots_test.dartnew file mode 100644index 000000000..2f34cedf3--- /dev/null+++ b/desktop/test/super_tab_catch_up_shots_test.dart@@ -0,0 +1,130 @@+import 'dart:io';+import 'dart:ui' as ui;++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 'box_render_preview_test.dart' show loadPreviewFonts;+import 'support/super_tab_fixture.dart';++/// Set to a folder to write the PR's screenshots there.+final shots = Platform.environment['SUPER_TAB_CATCH_UP_SHOTS'];++const _updates = [+ 'Reading the offline queue before the reconnect.',+ 'The reconnect keeps every queued edit in order.',+ 'Two devices editing at once settle on the newest edit.',+ 'Pushed the branch; the checks are running.',+];++Map<String, dynamic> _item(int sequence, String author, String text) => {+ 'messageId': 'message-$sequence',+ 'sequence': sequence,+ 'author': author,+ 'text': text,+};++/// The chat opened after a while away: the New messages line with the+/// catch-up card under it, at normal and enlarged text.+void main() {+ setUpAll(() async {+ if (shots != null) await loadPreviewFonts();+ });++ for (final (brightness, scale) in [+ (Brightness.light, 1.0),+ (Brightness.dark, 1.0),+ (Brightness.dark, 1.8),+ ]) {+ final name = '${brightness.name}${scale > 1 ? '-large-text' : ''}';+ testWidgets('screenshots for review ($name)', (tester) async {+ final picture = GlobalKey();+ final server = ConversationServer();+ for (var i = 1; i <= 80; i++) {+ server.append('${_updates[i % _updates.length]} ($i)');+ server.messages.last['author'] = {+ 'kind': 'agent',+ 'id': 'lead-agent',+ 'name': 'Lead',+ };+ }+ server.markReadElsewhere('lead', 30);+ server.catchUps['lead'] = {+ 'after': 30,+ 'through': 80,+ 'unread': 50,+ 'more': false,+ 'decisions': 1,+ 'needsYou': {+ 'total': 2,+ 'items': [+ _item(+ 52,+ 'River',+ 'Dee, the reconnect can keep the newest edit or ask the person. Which one should ship first?',+ ),+ _item(61, 'River', 'Dee, can you try the phone build tonight?'),+ ],+ },+ 'blocked': {+ 'total': 1,+ 'items': [+ _item(74, 'Iris', 'Stuck: No iPhone simulator on this Mac.'),+ ],+ },+ 'landed': {+ 'total': 4,+ 'items': [+ _item(44, 'River', 'Offline queue keeps edits in order'),+ _item(58, 'River', 'Done: Merged #2201.'),+ ],+ },+ };+ final c = server.controller();+ addTearDown(c.dispose);+ await c.refresh();+ grid.AppTheme.brightness.value = brightness;+ addTearDown(() => grid.AppTheme.brightness.value = Brightness.light);+ tester.view.physicalSize = const Size(1200, 860);+ tester.view.devicePixelRatio = 1;+ addTearDown(tester.view.reset);+ await tester.pumpWidget(+ MaterialApp(+ theme: grid.buildAppTheme(brightness: brightness),+ builder: (context, child) => MediaQuery(+ data: MediaQuery.of(context)+ .copyWith(textScaler: TextScaler.linear(scale)),+ child: RepaintBoundary(key: picture, child: child),+ ),+ home: Scaffold(+ body: SuperTabView(+ controller: c,+ onInvite: () {},+ onAddAgent: (_) {},+ onOpenTerminal: (_) {},+ machineName: (_) => 'Mac Studio',+ ),+ ),+ ),+ );+ await tester.pumpAndSettle();+ expect(find.byKey(const ValueKey('super-catch-up')), findsOne);+ expect(tester.takeException(), isNull);+ if (shots == null) return;+ await tester.runAsync(() async {+ final boundary =+ picture.currentContext!.findRenderObject()!+ as RenderRepaintBoundary;+ final image = await boundary.toImage(pixelRatio: 1.5);+ final bytes = await image.toByteData(format: ui.ImageByteFormat.png);+ await Directory(shots!).create(recursive: true);+ await File('$shots/catch-up-$name.png')+ .writeAsBytes(bytes!.buffer.asUint8List());+ image.dispose();+ });+ });+ }+}diff --git a/desktop/test/super_tab_catch_up_test.dart b/desktop/test/super_tab_catch_up_test.dartnew file mode 100644index 000000000..6b718698a--- /dev/null+++ b/desktop/test/super_tab_catch_up_test.dart@@ -0,0 +1,296 @@+import 'dart:async';++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/catch_up.dart';+import 'package:harness/super_tabs/controller.dart';+import 'package:harness/super_tabs/message_row.dart';+import 'package:harness/super_tabs/view.dart';++import 'support/super_tab_fixture.dart';++const _card = ValueKey('super-catch-up');+const _close = ValueKey('super-catch-up-close');+const _line = ValueKey('super-new-messages-line');++/// [count] messages in the Lead conversation from the Lead agent.+ConversationServer _server(int count) {+ final server = ConversationServer();+ for (var i = 1; i <= count; i++) {+ server.append('Update $i');+ server.messages.last['author'] = {+ 'kind': 'agent',+ 'id': 'lead-agent',+ 'name': 'Lead',+ };+ }+ return server;+}++Map<String, dynamic> _item(int sequence, String text, {String by = 'River'}) =>+ {+ 'messageId': 'message-$sequence',+ 'sequence': sequence,+ 'author': by,+ 'text': text,+ };++Map<String, dynamic> _list(List<Map<String, dynamic>> items, {int? total}) => {+ 'total': total ?? items.length,+ 'items': items,+};++/// What the backend answers for the Lead conversation read after message 10.+Map<String, dynamic> _summary({+ List<Map<String, dynamic>> landed = const [],+ List<Map<String, dynamic>> blocked = const [],+ List<Map<String, dynamic>> needsYou = const [],+ int needsYouTotal = 0,+ int decisions = 0,+ bool more = false,+}) => {+ 'after': 10,+ 'through': 40,+ 'unread': 30,+ 'more': more,+ 'decisions': decisions,+ 'landed': _list(landed),+ 'blocked': _list(blocked),+ 'needsYou': _list(needsYou, total: needsYouTotal > 0 ? needsYouTotal : null),+};++void main() {+ Future<SuperTabController> show(+ WidgetTester tester,+ ConversationServer server,+ ) async {+ final c = server.controller();+ await c.refresh();+ await tester.pumpWidget(+ MaterialApp(+ theme: grid.buildAppTheme(brightness: Brightness.dark),+ home: Scaffold(+ body: SuperTabView(+ controller: c,+ onInvite: () {},+ onAddAgent: (_) {},+ onOpenTerminal: (_) {},+ machineName: (_) => 'Team Mac',+ ),+ ),+ ),+ );+ await tester.pumpAndSettle();+ addTearDown(c.dispose);+ return c;+ }++ Finder inCard(String text) =>+ find.descendant(of: find.byKey(_card), matching: find.text(text));++ /// An item row, whose words follow its author's name.+ Finder rowSaying(String text) => find.descendant(+ of: find.byKey(_card),+ matching: find.textContaining(text),+ );++ group('SuperTabCatchUp', () {+ test('reads the backend summary, and is empty with nothing listed', () {+ final summary = SuperTabCatchUp.fromJson(+ _summary(+ needsYou: [_item(12, 'Dee, which colour?')],+ needsYouTotal: 7,+ decisions: 2,+ ),+ );+ expect(summary.unread, 30);+ expect(summary.decisions, 2);+ expect(summary.needsYou.total, 7);+ expect(summary.needsYou.items.single.messageId, 'message-12');+ expect(summary.needsYou.items.single.author, 'River');+ expect(summary.needsYou.items.single.text, 'Dee, which colour?');+ expect(summary.isEmpty, isFalse);+ expect(SuperTabCatchUp.fromJson(_summary()).isEmpty, isTrue);+ // Decisions alone are something that needs the reader.+ expect(SuperTabCatchUp.fromJson(_summary(decisions: 1)).isEmpty, isFalse);+ // A span longer than one summary reads is shown even with nothing+ // listed: the reader is told it is partial.+ final partial = SuperTabCatchUp.fromJson(_summary(more: true));+ expect(partial.more, isTrue);+ expect(partial.isEmpty, isFalse);+ // A malformed answer is empty, never a crash.+ expect(SuperTabCatchUp.fromJson(const {}).isEmpty, isTrue);+ });+ });++ for (final late in [false, true]) {+ testWidgets('shows what the reader missed just under the New messages '+ 'line (${late ? 'answered late' : 'answered at once'})', (+ tester,+ ) async {+ // A window and a span as long as a real return's: the card arrives+ // once the view has opened at the line.+ tester.view.physicalSize = const Size(1200, 860);+ tester.view.devicePixelRatio = 1;+ addTearDown(tester.view.reset);+ final server = _server(80)..markReadElsewhere('lead', 30);+ server.catchUps['lead'] = _summary(+ landed: [_item(40, 'Avatars'), _item(44, 'Done: Merged #2201.')],+ blocked: [_item(50, 'Stuck: No simulator on this Mac.', by: 'Iris')],+ needsYou: [_item(45, 'Dee, which colour?')],+ );+ final hold = late ? server.holdCatchUp = Completer<void>() : null;+ await show(tester, server);+ if (hold != null) {+ expect(find.byKey(_card), findsNothing);+ hold.complete();+ await tester.pumpAndSettle();+ }+ expect(server.catchUpReads, [+ '/api/super-tabs/tab/conversations/lead/catch-up?after=30',+ ]);+ expect(find.byKey(_card), findsOneWidget);+ // Whenever it arrives, the line and the card's top are in view: the card+ // makes the line's row taller than the view.+ final list = tester.getRect(+ find.byKey(const PageStorageKey('super-messages-tab-lead')),+ );+ expect(tester.getTopLeft(find.byKey(_line)).dy, greaterThan(list.top));+ expect(+ tester.getTopLeft(inCard('While you were away')).dy,+ lessThan(list.bottom),+ );+ expect(inCard('While you were away'), findsOneWidget);+ expect(inCard('30 new messages'), findsOneWidget);+ for (final heading in ['Needs you', 'Blocked', 'Landed']) {+ expect(inCard(heading), findsOneWidget);+ }+ expect(rowSaying('Dee, which colour?'), findsOneWidget);+ expect(rowSaying('Stuck: No simulator on this Mac.'), findsOneWidget);+ expect(rowSaying('Avatars'), findsOneWidget);+ // Needs you first: what the reader has to act on.+ final top = tester.getTopLeft(inCard('Needs you')).dy;+ expect(top, lessThan(tester.getTopLeft(inCard('Blocked')).dy));+ expect(+ tester.getTopLeft(inCard('Blocked')).dy,+ lessThan(tester.getTopLeft(inCard('Landed')).dy),+ );+ // At the top of the new messages: below the line, above the first unread.+ expect(+ tester.getTopLeft(find.byKey(_card)).dy,+ greaterThan(tester.getTopLeft(find.byKey(_line)).dy),+ );+ expect(+ tester.getTopLeft(find.byKey(_card)).dy,+ lessThan(tester.getTopLeft(find.text('Update 31')).dy),+ );+ });+ }++ testWidgets('an item opens its message, lit', (tester) async {+ final server = _server(40)..markReadElsewhere('lead', 10);+ server.catchUps['lead'] = _summary(needsYou: [_item(38, 'Update 38')]);+ await show(tester, server);+ await tester.tap(find.byKey(const ValueKey('super-catch-up-message-38')));+ await tester.pumpAndSettle();+ final lit = find.byWidgetPredicate(+ (w) => w is SuperTabMessageHighlight && w.on,+ );+ expect(+ find.descendant(of: lit, matching: find.text('Update 38')),+ findsOneWidget,+ );+ });++ testWidgets('says how many more each list has, and the decisions waiting', (+ tester,+ ) async {+ final server = _server(40)..markReadElsewhere('lead', 10);+ server.catchUps['lead'] = _summary(+ needsYou: [_item(25, 'Question 3'), _item(26, 'Question 4')],+ needsYouTotal: 5,+ decisions: 2,+ );+ await show(tester, server);+ expect(inCard('3 more'), findsOneWidget);+ expect(inCard('2 decisions wait for you'), findsOneWidget);+ });++ testWidgets('says when it covers only the first part of a long absence', (+ tester,+ ) async {+ final server = _server(40)..markReadElsewhere('lead', 10);+ server.catchUps['lead'] = _summary(more: true);+ await show(tester, server);+ expect(find.byKey(_card), findsOneWidget);+ // Never a count that reads as complete.+ expect(inCard('30+ new messages'), findsOneWidget);+ expect(inCard('30 new messages'), findsNothing);+ expect(+ inCard(+ 'Covers only the first part of what you missed. '+ 'Newer messages are below.',+ ),+ findsOneWidget,+ );+ });++ testWidgets('Close dismisses it for this visit, without reading again', (+ tester,+ ) async {+ final server = _server(40)..markReadElsewhere('lead', 10);+ server.catchUps['lead'] = _summary(landed: [_item(20, 'Avatars')]);+ final c = await show(tester, server);+ await tester.tap(find.byKey(_close));+ await tester.pumpAndSettle();+ expect(find.byKey(_card), findsNothing);+ // The line stays: only the card was dismissed.+ expect(find.byKey(_line), findsOneWidget);+ server.append('Later');+ await c.refresh();+ await tester.pumpAndSettle();+ expect(find.byKey(_card), findsNothing);+ expect(server.catchUpReads, hasLength(1));+ });++ testWidgets('Esc reads everything, card and line together', (tester) async {+ final server = _server(40)..markReadElsewhere('lead', 10);+ server.catchUps['lead'] = _summary(landed: [_item(20, 'Avatars')]);+ await show(tester, server);+ await tester.tap(find.byType(TextField).last);+ await tester.sendKeyEvent(LogicalKeyboardKey.escape);+ await tester.pumpAndSettle();+ expect(find.byKey(_card), findsNothing);+ expect(find.byKey(_line), findsNothing);+ });++ testWidgets('no card when nothing landed, is blocked or needs the reader', (+ tester,+ ) async {+ final server = _server(40)..markReadElsewhere('lead', 10);+ await show(tester, server);+ expect(server.catchUpReads, hasLength(1));+ expect(find.byKey(_line), findsOneWidget);+ expect(find.byKey(_card), findsNothing);+ });++ testWidgets('nothing unread reads no summary', (tester) async {+ final server = _server(40)..markReadElsewhere('lead', 40);+ await show(tester, server);+ expect(server.catchUpReads, isEmpty);+ expect(find.byKey(_card), findsNothing);+ });++ testWidgets('a failed read leaves the New messages line as it was', (+ tester,+ ) async {+ final server = _server(40)+ ..markReadElsewhere('lead', 10)+ ..failCatchUp = true;+ await show(tester, server);+ expect(find.byKey(_card), findsNothing);+ expect(find.byKey(_line), findsOneWidget);+ });+}diff --git a/desktop/test/support/super_tab_fixture.dart b/desktop/test/support/super_tab_fixture.dartindex c8152e41c..14c261ba9 100644--- a/desktop/test/support/super_tab_fixture.dart+++ b/desktop/test/support/super_tab_fixture.dart@@ -509,6 +509,32 @@ class ConversationServer {/// The read marks this device sent, in order: {conversationId, sequence}.final readMarkPosts = <Map<String, dynamic>>[];+ /// The catch-up summary the backend answers per conversation (catchUp.ts);+ /// one not set answers an empty summary.+ final catchUps = <String, Map<String, dynamic>>{};++ /// Every catch-up read, by path; [failCatchUp] makes them fail as offline.+ final catchUpReads = <String>[];+ bool failCatchUp = false;++ /// While set, catch-up reads wait for it: a summary that arrives late.+ Completer<void>? holdCatchUp;++ Map<String, dynamic> _catchUp(String conversationId, int after) {+ const empty = {'total': 0, 'items': <dynamic>[]};+ return catchUps[conversationId] ??+ {+ 'after': after,+ 'through': after,+ 'unread': 0,+ 'more': false,+ 'decisions': 0,+ 'landed': empty,+ 'blocked': empty,+ 'needsYou': empty,+ };+ }+/// Every read-mark write fails, as offline.bool failReadMarks = false;@@ -1082,6 +1108,15 @@ class ConversationServer {if (holdReads case final hold?) await hold.future;if (failReads) throw StateError('Offline');final uri = Uri.parse(path);+ if (uri.pathSegments.last == 'catch-up') {+ catchUpReads.add(path);+ if (holdCatchUp case final hold?) await hold.future;+ if (failCatchUp) throw StateError('Offline');+ final id = uri.pathSegments[uri.pathSegments.length - 2];+ final after = int.parse(uri.queryParameters['after']!);+ return jsonDecode(jsonEncode(_catchUp(id, after)))+ as Map<String, dynamic>;+ }if (uri.pathSegments.last == 'mentions') {mentionReads++;if (mentionsMissing) {