Skip to content

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

Merge batch 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: FastifyInstance
let clock = NOW
const 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_000
beforeAll(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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.prisma
index 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.ts
index 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?: Su
app.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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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)?.lostTask
if (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.ts
index 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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: string
description: string
diff --git a/backend/src/superTabs/pageReads.ts b/backend/src/superTabs/pageReads.ts
index 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; convers
return [...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.ts
index 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.ts
index 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_LIMIT
import { 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.ts
index 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 = 0
for (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) continue
const data = head.data as unknown as HeadData
const 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.ts
index 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.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
index 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.dart
index 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.dart
index 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.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
index 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) {