The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Swarm state by parts (#1726) and Swarm v1: Chat with PM, lost-work takeover, routing readiness (#1755)
0xken15a4b32c97af1c
diff --git a/backend/build.mjs b/backend/build.mjsindex 1b5acf163..dfe6eaaf6 100644--- a/backend/build.mjs+++ b/backend/build.mjs@@ -7,7 +7,7 @@ function getAllTsFiles(dir, fileList = []) {const filePath = join(dir, file)if (statSync(filePath).isDirectory()) {getAllTsFiles(filePath, fileList)- } else if (file.endsWith('.ts') && !file.endsWith('.test.ts')) {+ } else if (file.endsWith('.ts') && !file.endsWith('.test.ts') && !file.endsWith('.test-support.ts')) {fileList.push(filePath)}}diff --git a/backend/integration/bench/README.md b/backend/integration/bench/README.mdnew file mode 100644index 000000000..c80035328--- /dev/null+++ b/backend/integration/bench/README.md@@ -0,0 +1,103 @@+# Swarm state benchmark (#1726)++A repeatable before and after measure for two goals of+[Swarm state by parts](../../../docs/plans/2026-10-26-swarm-state-parts.md): agents in different work groups never+conflict (goal 1), and a poll costs what changed, not the whole Swarm (goal 3). The baseline on main is+[docs/performance/2026-10-26-swarm-state-baseline.md](../../../docs/performance/2026-10-26-swarm-state-baseline.md).++## Run it++From `backend/`, after `npm ci`:++```bash+npm run bench:swarm-state # the default busy Swarm, about 3 minutes+npm run bench:swarm-state -- --lane cross-group # goal 1: one writer per group, so any conflict is across groups+npm run bench:swarm-state -- --done-share 0 # the hot Swarm: all 200 groups active, the same 20 workers spread over them+```++It starts its own MongoDB replica set on 127.0.0.1 (as `integration/superTabs.test.ts` does), with fixture accounts and+machines, and never reads `DATABASE_URL` or any other database. It writes `<driver>-<time>.json` and `.md` to+`integration/bench/results/` (or `--out DIR`) and prints the markdown.++| Option | Default | Meaning |+|---|---|---|+| `--seed N` | 1726 | Seeds every choice: who posts what, when. Same seed, same plan (the report's plan fingerprint). |+| `--groups N` | 200 | Work groups besides the Leads group. |+| `--done-share X` | 0.9 | Share of groups done before the load; the rest are active. |+| `--workers N` | 20 | Workers, at most one per active group. Each takes active groups in turn and holds the task of its first (an agent holds one active task at a time); its messages go to any of its groups, its status and checks to that first group. |+| `--lane L` | mixed | `mixed`: the busy Swarm below. `cross-group`: one writer per group at a time, for goal 1 (below). |+| `--machines N` | 6 | Contributed machines, each its own person's; machine 0 is the owner's and runs the Lead. |+| `--duration S` | 120 | Load length in seconds. A slow store stretches it by up to a quarter (at least 10 s); work left after that is reported as skipped. |+| `--desktop-readers N` | 3 | Desktop windows of the owner and the first machine owners, polling the Swarm (below). |+| `--host-readers N` | 2 | CLI hosts of the first machines reading their roster (below). |+| `--mix a=w,…` | `message.send=2,work.status=1,work.check=1` | Relative weights of a worker's posts in its own group. |+| `--every k=ms,…` | see `config.ts` | Cadences: `workerPostMs` 4000, `leadSendMs` 5000, `nativeTurnMs` 10000, `observeMs` 15000, `deliveryPassMs` 3000, `desktopPollMs` 3000, `hostTickMs` 1000. |+| `--driver NAME` | parts | Which store's clients to run (below). |++The isolated poll in the report runs right after the load, while every part changed in the last 30 s still comes+again. To see what one up-to-date poll costs the database when the Swarm is idle, and after a single post, run the+diagnostic. It takes the same options:++```bash+NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= \+ DATABASE_URL=mongodb://127.0.0.1:1/bench-never-used npx tsx integration/bench/pollDatabaseBytes.ts+```++The bench's own tests (helpers, plus a short run of the whole scenario), and its typecheck:++```bash+npx vitest run --config integration/bench/vitest.config.ts+npx tsc -p integration/bench/tsconfig.json+```++## What runs++Setup builds the Swarm through real commands: members join, machines are contributed, the Lead and the workers are+added, every group gets a brief and two checks, and each done group runs a whole task (assign, pass both checks, done).+Then, all at once, each on its own seeded timeline:++- each worker posts in its own group: `message.send`, `work.status`, `work.check`, in the mix;+- each worker's terminal records a turn (a prompt and its answer, `native.append`), which also notifies the Lead;+- the Lead sends a worker a message, which waits as a delivery;+- each machine reports (`observeMachine`) every 15 s;+- each machine's host passes over its agents' deliveries every 3 s: lists them, claims and acknowledges each one;+- Desktop readers poll the full state every 3 s and host readers their roster every 1 s.++In the `cross-group` lane each worker's posts and terminal turns run in one sequence, and there are no Lead messages and+no delivery passes, so no two calls ever write one group at once: every conflict between agents is between different+groups. Machine reports stay, every 15 s: after the parts change they write only their machine's part, so they must not+conflict with group writes either. The report's writer kinds table shows which kind of writer met the conflicts.++After the load each reader polls once more, alone, as a client that is already up to date. That poll's response size+and what MongoDB sent the backend for it (`serverStatus` bytes out, minus the status call's own reply) show what a poll+costs the database: today a host roster reply is a few KB, but it loads the whole Swarm document.++## What it reports++Per operation, per kind of writer (worker, terminal, machine, delivery pass, Lead, Desktop and host readers) and per writer: calls, OK, failed transaction attempts (P2034 write conflicts and transient errors the+store retried), calls that needed a retry, `SWARM_BUSY` (a call that ran out of retries), other errors, p50, p95 and+max latency. Per reader: polls, latency, response bytes, and the isolated poll. The state's size (documents and BSON+bytes) after setup and after the load. The run: commit, machine, MongoDB version, seed, plan fingerprint and settings.++Retries are counted without touching the store: `attempts.ts` wraps the database client's `$transaction`, which every+store attempt goes through (spec: "Mongo transactions through Prisma as today"), and ties each failed attempt to the+call that made it.++## The seam for the parts store++The scenario talks to a store only through `SwarmDriver` (`driver.ts`): create a Swarm, run a command (as a person or+as an agent), read back setup facts (`snapshot`), a machine's generation and report, open and record a terminal, list,+claim and acknowledge deliveries, a Desktop reader and a host reader, the state's size, close. Commands keep their+shapes across versions, so they cross the seam as they are.++Two drivers, registered in `DRIVERS` (`bench.ts`); run either with the same seed. Nothing in `plan.ts`, `seed.ts` or+`load.ts` differs between them.++- `legacyDriver.ts` (`--driver legacy`) is main's store through main's routes: every Desktop poll reads the whole+ Swarm, every host tick its roster. On the store by parts those full reads answer 426, so it runs only on main (the+ baseline).+- `drivers/parts.ts` (`--driver parts`, the default here) is the store by parts, read the way the merged clients read+ it: commands and the other writes through the same routes; setup facts from a first load; each Desktop window loads+ once, then reads the changes since its cursor (a `reload` answer is followed by a first load in the same poll); each+ host reads its host form in full at start and at least every minute, and by change in between, naming the etag of+ the rows it holds. The state's size is its live parts.diff --git a/backend/integration/bench/attempts.test.ts b/backend/integration/bench/attempts.test.tsnew file mode 100644index 000000000..ad9f86c38--- /dev/null+++ b/backend/integration/bench/attempts.test.ts@@ -0,0 +1,65 @@+import { describe, expect, it } from 'vitest'+import type { PrismaClient } from '@prisma/client'+import { transaction } from '../../src/superTabs/store.js'+import { AttemptCounter } from './attempts.js'++const conflict = () => Object.assign(new Error('Transaction failed due to a write conflict'), { code: 'P2034' })+const transient = () => new Error('Error code 251 TransientTransactionError: lock wait')++/** A client whose transactions fail with [failures] in turn, then run the body. Stands in for Mongo's conflicts. */+function flaky(failures: Array<() => Error>) {+ let call = 0+ return {+ calls: () => call,+ db: {+ superTab: { label: 'delegate' },+ async $transaction<T>(body: (tx: unknown) => Promise<T>) {+ const failure = failures[call++]+ if (failure) throw failure()+ return body({})+ },+ },+ }+}+const instant = async () => {}++describe('AttemptCounter', () => {+ it('records each retried attempt of the store transaction, by error code, for the call that made it', async () => {+ const counter = new AttemptCounter(), source = flaky([conflict, transient, conflict])+ const db = counter.wrap(source.db)+ const tracked = await counter.track(() => transaction(db as unknown as PrismaClient, async () => 'written', instant))+ expect(tracked).toMatchObject({ value: 'written', failedAttempts: ['P2034', 'TRANSIENT', 'P2034'] })+ expect(source.calls()).toBe(4)+ expect(tracked.ms).toBeGreaterThanOrEqual(0)+ })++ it('records every attempt when the store gives up and says the Swarm is busy', async () => {+ const counter = new AttemptCounter(), db = counter.wrap(flaky(Array(8).fill(conflict)).db)+ const tracked = await counter.track(() => transaction(db as unknown as PrismaClient, async () => 'never', instant))+ expect(tracked.value).toBeUndefined()+ expect((tracked.error as { code?: string }).code).toBe('SWARM_BUSY')+ expect(tracked.failedAttempts).toEqual(Array(8).fill('P2034'))+ })++ it('does not count a refusal from inside the transaction as a conflict', async () => {+ const counter = new AttemptCounter(), db = counter.wrap(flaky([]).db)+ const refusal = Object.assign(new Error('Not yours'), { code: 'FORBIDDEN' })+ const tracked = await counter.track(() => transaction(db as unknown as PrismaClient, async () => { throw refusal }, instant))+ expect(tracked).toMatchObject({ error: refusal, failedAttempts: [] })+ })++ it('keeps concurrent calls apart', async () => {+ const counter = new AttemptCounter(), db = counter.wrap(flaky([conflict]).db)+ const [first, second] = await Promise.all([+ counter.track(() => transaction(db as unknown as PrismaClient, async () => 1, instant)),+ counter.track(async () => { await new Promise(resolve => setTimeout(resolve, 5)); return transaction(db as unknown as PrismaClient, async () => 2, instant) }),+ ])+ expect(first.failedAttempts).toEqual(['P2034'])+ expect(second.failedAttempts).toEqual([])+ })++ it('passes every other client property through', () => {+ const counter = new AttemptCounter(), db = counter.wrap(flaky([]).db)+ expect(db.superTab).toEqual({ label: 'delegate' })+ })+})diff --git a/backend/integration/bench/attempts.ts b/backend/integration/bench/attempts.tsnew file mode 100644index 000000000..8a76c1694--- /dev/null+++ b/backend/integration/bench/attempts.ts@@ -0,0 +1,58 @@+import { AsyncLocalStorage } from 'node:async_hooks'+import { performance } from 'node:perf_hooks'++export interface Tracked<T> {+ value?: T+ error?: unknown+ ms: number+ /** One code per database transaction attempt that failed with a retryable error: P2034, P2002 or TRANSIENT. */+ failedAttempts: string[]+}++type Transactional = { $transaction: (...args: never[]) => Promise<unknown> }++/** The codes the store's retry loop retries (store.ts `retryable`); anything else is the call's own outcome. */+function retryCode(error: unknown): string | null {+ if (!error || typeof error !== 'object') return null+ const code = 'code' in error ? error.code : null+ if (code === 'P2034' || code === 'P2002') return code+ return error instanceof Error && error.message.includes('TransientTransactionError') ? 'TRANSIENT' : null+}++/**+ * Counts write conflicts without touching the store: every store (today's and the parts store, spec "Mongo transactions+ * through Prisma as today") runs each attempt as one `$transaction` call, so a wrapped client sees each failed attempt.+ * AsyncLocalStorage ties each attempt to the scenario call that caused it, while calls run concurrently.+ */+export class AttemptCounter {+ private readonly current = new AsyncLocalStorage<string[]>()++ wrap<D extends Transactional>(db: D): D {+ const failed = (error: unknown) => {+ const code = retryCode(error)+ if (code) this.current.getStore()?.push(code)+ }+ return new Proxy(db, {+ get(target, property) {+ const value = Reflect.get(target, property, target)+ if (property === '$transaction') {+ return async (...args: never[]) => {+ try { return await (value as Transactional['$transaction']).apply(target, args) } catch (error) { failed(error); throw error }+ }+ }+ return typeof value === 'function' ? value.bind(target) : value+ },+ })+ }++ async track<T>(call: () => Promise<T>): Promise<Tracked<T>> {+ const failedAttempts: string[] = []+ const started = performance.now()+ try {+ const value = await this.current.run(failedAttempts, call)+ return { value, ms: performance.now() - started, failedAttempts }+ } catch (error) {+ return { error, ms: performance.now() - started, failedAttempts }+ }+ }+}diff --git a/backend/integration/bench/bench.ts b/backend/integration/bench/bench.tsnew file mode 100644index 000000000..91439cd32--- /dev/null+++ b/backend/integration/bench/bench.ts@@ -0,0 +1,64 @@+import { execFileSync } from 'node:child_process'+import { arch, cpus, platform, release, totalmem } from 'node:os'+import { performance } from 'node:perf_hooks'+import type { PrismaClient } from '@prisma/client'+import type { AuthUser } from '../../src/lib/ssoAuth.js'+import { AttemptCounter } from './attempts.js'+import { activeCount, type BenchConfig } from './config.js'+import type { SwarmDriver } from './driver.js'+import { seedAccounts } from './fixtures.js'+import { legacyDriver } from './legacyDriver.js'+import { partsDriver } from './drivers/parts.js'+import { runLoad } from './load.js'+import { plan, planDigest } from './plan.js'+import { isolatedPolls } from './probe.js'+import type { BenchReport } from './report.js'+import { seedSwarm } from './seed.js'++/** Each store version's clients. The parts store (#1726 groups 2–3) adds its driver here; the scenario stays as it is. */+export const DRIVERS: Record<string, (db: PrismaClient, users: () => readonly AuthUser[]) => Promise<SwarmDriver>> = { legacy: legacyDriver, parts: partsDriver }++function commit(): BenchReport['commit'] {+ try {+ const sha = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim()+ const dirty = execFileSync('git', ['status', '--porcelain', '--', '.'], { encoding: 'utf8' }).trim() !== ''+ return { sha, dirty }+ } catch { return null }+}++async function mongoVersion(db: PrismaClient): Promise<string> {+ return String((await db.$runCommandRaw({ buildInfo: 1 }) as { version?: unknown }).version ?? 'unknown')+}++/** Seeds a Swarm on [db] (a fresh local database), runs the load, and measures. */+export async function runBench(config: BenchConfig, driverName: string, db: PrismaClient): Promise<BenchReport> {+ const make = DRIVERS[driverName] ?? (() => { throw new Error(`Unknown driver ${driverName}; known: ${Object.keys(DRIVERS).join(', ')}`) })()+ const startedAt = new Date().toISOString()+ const counter = new AttemptCounter()+ const people = await seedAccounts(db, config.machines)+ const driver = await make(counter.wrap(db), () => people)+ try {+ const p = plan(config)+ const setupStart = performance.now()+ const { swarm, calls } = await seedSwarm(driver, config, p, people)+ const setupMs = performance.now() - setupStart+ const afterSetup = await driver.stateSize(swarm.tabId)+ const load = await runLoad(driver, counter, config, p, swarm)+ const afterLoad = await driver.stateSize(swarm.tabId)+ const polls = await isolatedPolls(db, load.readers)+ const readerLabels = new Set(load.readers.map(r => r.label))+ return {+ benchmark: 'swarm-state', version: 1, driver: driver.name, startedAt, commit: commit(),+ machine: { platform: platform(), release: release(), arch: arch(), cpu: cpus()[0]?.model ?? 'unknown', cpus: cpus().length,+ memoryGb: Math.round(totalmem() / 2 ** 30), node: process.versions.node, mongo: await mongoVersion(db) },+ config, planDigest: planDigest(p),+ setup: { ms: setupMs, calls, workers: p.workers.length, activeGroups: activeCount(config), doneGroups: p.doneGroups.length },+ load: { plannedMs: config.durationMs, actualMs: load.actualMs, skipped: load.skipped, ops: load.recorder.byOp(), writerKinds: load.recorder.byWriterKind(),+ writers: load.recorder.byWriter().filter(w => !readerLabels.has(w.key)), readers: load.recorder.byWriter().filter(w => readerLabels.has(w.key)) },+ state: { afterSetup, afterLoad },+ isolatedPolls: polls,+ }+ } finally {+ await driver.close()+ }+}diff --git a/backend/integration/bench/config.test.ts b/backend/integration/bench/config.test.tsnew file mode 100644index 000000000..bc39efd44--- /dev/null+++ b/backend/integration/bench/config.test.ts@@ -0,0 +1,37 @@+import { describe, expect, it } from 'vitest'+import { DEFAULT_CONFIG, parseArgs } from './config.js'++describe('parseArgs', () => {+ it('uses the defaults the brief names: 200 groups, 20 active, 6 machines, 3 Desktop and 2 host readers', () => {+ const { config } = parseArgs([])+ expect(config).toEqual(DEFAULT_CONFIG)+ expect(config).toMatchObject({ groups: 200, doneShare: 0.9, workers: 20, lane: 'mixed', machines: 6, desktopReaders: 3, hostReaders: 2 })+ expect(config.every).toMatchObject({ observeMs: 15_000, desktopPollMs: 3_000, hostTickMs: 1_000, deliveryPassMs: 3_000 })+ })++ it('runs the store by parts unless told otherwise: on this branch the old full reads answer 426', () => {+ expect(parseArgs([]).driver).toBe('parts')+ })++ it('reads sizes, seconds, the mix and cadences', () => {+ const { config, out, driver } = parseArgs(['--seed', '9', '--groups', '50', '--done-share', '0', '--workers', '5', '--lane', 'cross-group', '--duration', '30',+ '--mix', 'message.send=1,work.status=0,work.check=3', '--every', 'workerPostMs=500,hostTickMs=2000', '--out', '/tmp/x', '--driver', 'legacy'])+ expect(config).toMatchObject({ seed: 9, groups: 50, doneShare: 0, workers: 5, lane: 'cross-group', durationMs: 30_000,+ mix: { 'message.send': 1, 'work.status': 0, 'work.check': 3 } })+ expect(config.every).toEqual({ ...DEFAULT_CONFIG.every, workerPostMs: 500, hostTickMs: 2000 })+ expect(out).toBe('/tmp/x')+ expect(driver).toBe('legacy')+ })++ it('refuses settings it cannot run', () => {+ expect(() => parseArgs(['--done-share', '1'])).toThrow(/at least one active group/)+ expect(() => parseArgs(['--desktop-readers', '9'])).toThrow(/Readers/)+ expect(() => parseArgs(['--workers', '0'])).toThrow(/worker/)+ expect(() => parseArgs(['--workers', '21'])).toThrow(/worker/)+ expect(() => parseArgs(['--lane', 'diagonal'])).toThrow(/--lane/)+ expect(() => parseArgs(['--mix', 'message.send=0,work.status=0,work.check=0'])).toThrow(/mix/)+ expect(() => parseArgs(['--every', 'nope=1'])).toThrow(/nope/)+ expect(() => parseArgs(['--groups'])).toThrow(/--groups/)+ expect(() => parseArgs(['--colour', 'red'])).toThrow(/--colour/)+ })+})diff --git a/backend/integration/bench/config.ts b/backend/integration/bench/config.tsnew file mode 100644index 000000000..c3ef7b0ad--- /dev/null+++ b/backend/integration/bench/config.ts@@ -0,0 +1,119 @@+export const WORKER_ACTIONS = ['message.send', 'work.status', 'work.check'] as const+export type WorkerAction = typeof WORKER_ACTIONS[number]++/**+ * `mixed` is the busy Swarm: each worker's posts and its terminal run side by side in its group, and the Lead messages it+ * there. `cross-group` keeps one writer per group at a time (a worker's posts and turns run in one sequence; no Lead+ * messages, no delivery passes), so any conflict between agents is between different groups (#1726 goal 1). Machine+ * reports stay: after the parts change they write only their machine's part.+ */+export const LANES = ['mixed', 'cross-group'] as const+export type Lane = typeof LANES[number]++export interface Cadence {+ /** Mean gap between one worker's posts in its own group. */+ workerPostMs: number+ /** Mean gap between the Lead's messages to a worker (each one a delivery). */+ leadSendMs: number+ /** Mean gap between one worker's terminal turns (a prompt and an answer, each recorded). */+ nativeTurnMs: number+ /** Each contributed machine's report (cli/src/superTabs/machines.ts: 15 s). */+ observeMs: number+ /** Each host's pass over its agents' deliveries, claiming and acknowledging what waits. */+ deliveryPassMs: number+ /** Desktop and web poll the full state (Flutter super_tabs: 3 s). */+ desktopPollMs: number+ /** The CLI host's roster tick (cli/src/superTabs/host.ts: 1 s). */+ hostTickMs: number+}++export interface BenchConfig {+ seed: number+ /** Work groups besides the Leads group. */+ groups: number+ /** The share of groups whose work is done before the load starts. Every other group is active, with its own worker. */+ doneShare: number+ /** Workers, each with its own active groups: one when there are as many workers as active groups (the default). */+ workers: number+ lane: Lane+ /** Contributed machines, each owned by its own person; the Swarm owner's is machine 0 and runs the Lead. */+ machines: number+ durationMs: number+ /** Desktop windows of the first people (the owner, then machine owners). */+ desktopReaders: number+ /** CLI hosts of the first machines reading their roster. */+ hostReaders: number+ /** Relative weights of a worker's posts. */+ mix: Record<WorkerAction, number>+ every: Cadence+ /** Text sizes, so the state has the size of a real Swarm (#1726: 1.16 MB with 195 groups). */+ text: { briefChars: number; resultChars: number; messageChars: number }+}++export const DEFAULT_CONFIG: BenchConfig = {+ seed: 1726, groups: 200, doneShare: 0.9, workers: 20, lane: 'mixed', machines: 6, durationMs: 120_000, desktopReaders: 3, hostReaders: 2,+ mix: { 'message.send': 2, 'work.status': 1, 'work.check': 1 },+ every: { workerPostMs: 4_000, leadSendMs: 5_000, nativeTurnMs: 10_000, observeMs: 15_000, deliveryPassMs: 3_000, desktopPollMs: 3_000, hostTickMs: 1_000 },+ text: { briefChars: 3_000, resultChars: 600, messageChars: 300 },+}++export interface Args { config: BenchConfig; out: string | null; driver: string }++const NUMBERS: Record<string, (config: BenchConfig, value: number) => void> = {+ '--seed': (c, v) => { c.seed = v },+ '--groups': (c, v) => { c.groups = v },+ '--done-share': (c, v) => { c.doneShare = v },+ '--workers': (c, v) => { c.workers = v },+ '--machines': (c, v) => { c.machines = v },+ '--duration': (c, v) => { c.durationMs = v * 1000 },+ '--desktop-readers': (c, v) => { c.desktopReaders = v },+ '--host-readers': (c, v) => { c.hostReaders = v },+}++/** `key=number,key=number`, only for keys [known] has. */+function pairs<T extends object>(flag: string, text: string, known: T): Partial<T> {+ const result: Record<string, number> = {}+ for (const pair of text.split(',')) {+ const [key, value] = pair.split('=')+ if (!key || !(key in known) || !Number.isFinite(Number(value))) throw new Error(`${flag}: unknown or invalid "${pair}"`)+ result[key] = Number(value)+ }+ return result as Partial<T>+}++export function parseArgs(argv: readonly string[]): Args {+ const config: BenchConfig = structuredClone(DEFAULT_CONFIG)+ let out: string | null = null, driver = 'parts'+ for (let i = 0; i < argv.length; i += 2) {+ const flag = argv[i]!, value = argv[i + 1]+ if (value === undefined) throw new Error(`${flag} needs a value`)+ if (flag in NUMBERS) {+ if (!Number.isFinite(Number(value))) throw new Error(`${flag} needs a number`)+ NUMBERS[flag]!(config, Number(value))+ } else if (flag === '--mix') config.mix = { ...config.mix, ...pairs(flag, value, config.mix) }+ else if (flag === '--every') config.every = { ...config.every, ...pairs(flag, value, config.every) }+ else if (flag === '--lane') {+ if (!(LANES as readonly string[]).includes(value)) throw new Error(`--lane is one of ${LANES.join(', ')}`)+ config.lane = value as Lane+ } else if (flag === '--out') out = value+ else if (flag === '--driver') driver = value+ else throw new Error(`Unknown option ${flag}`)+ }+ validate(config)+ return { config, out, driver }+}++export function activeCount(config: BenchConfig): number {+ return config.groups - Math.round(config.groups * config.doneShare)+}++function validate(config: BenchConfig): void {+ if (config.doneShare < 0 || config.doneShare > 1 || activeCount(config) < 1) throw new Error('The Swarm needs at least one active group.')+ if (!Number.isInteger(config.workers) || config.workers < 1 || config.workers > activeCount(config)) {+ throw new Error('Each worker needs an active group: between 1 worker and one per active group.')+ }+ if (config.machines < 1 || config.desktopReaders > config.machines || config.hostReaders > config.machines) {+ throw new Error('Readers are the first people and machines: at most one of each kind per machine.')+ }+ if (!WORKER_ACTIONS.some(action => config.mix[action] > 0)) throw new Error('The mix needs at least one action with weight above 0.')+}diff --git a/backend/integration/bench/driver.ts b/backend/integration/bench/driver.tsnew file mode 100644index 000000000..a612f9941--- /dev/null+++ b/backend/integration/bench/driver.ts@@ -0,0 +1,72 @@+import type { AuthUser } from '../../src/lib/ssoAuth.js'+import type { Command } from '../../src/superTabs/commands.js'+import type { MachineObservation } from '../../src/superTabs/machines.js'++/**+ * The seam between the scenario and a store (#1726 group 0).+ *+ * The scenario only says what a client does: run a command, report a machine, record a terminal turn, take a delivery,+ * poll. A driver says how the clients of one store version do it. Today's driver (legacyDriver.ts) uses today's routes;+ * the parts store (groups 2–3) adds its own driver, e.g. readers that poll by cursor, and the scenario stays unchanged.+ * Commands keep their shapes across versions (spec: "Keep the existing behavior of every command"), so they cross the+ * seam as they are.+ */+export interface SwarmDriver {+ readonly name: string+ /** A new Swarm owned by [owner]; returns its id. */+ createSwarm(owner: AuthUser, operationId: string, name: string): Promise<Reply<{ id: string }>>+ /** A command as a person, or as an agent when [asAgentId] is set (the agent's execution host signs in). */+ execute(tabId: string, user: AuthUser, operationId: string, command: Command, asAgentId?: string): Promise<Reply<CommandResult>>+ /** What setup needs to read back: group checks, the Lead, assignments, machine generations, in today's state shape. */+ snapshot(tabId: string, user: AuthUser): Promise<Snapshot>+ /** A machine's contribution generation, as its host reads it before reporting. */+ machineGeneration(tabId: string, host: AuthUser, machineId: string): Promise<string>+ observeMachine(tabId: string, host: AuthUser, machineId: string, observation: MachineObservation): Promise<Reply>+ /** A person opens an agent's terminal in a group; its host then records the turns. */+ openNative(tabId: string, opener: AuthUser, input: { operationId: string; conversationId: string; agentId: string }): Promise<Reply<{ contextId: string }>>+ appendNative(tabId: string, host: AuthUser, contextId: string, event: NativeEvent): Promise<Reply<{ eventId: string }>>+ /** The deliveries waiting for an agent, as its host reads them on each pass. */+ deliveries(tabId: string, host: AuthUser, agentId: string): Promise<Reply<Array<{ id: string }>>>+ delivery(tabId: string, host: AuthUser, agentId: string, deliveryId: string, action: DeliveryAction): Promise<Reply>+ /** A Desktop or web window open on the Swarm, polling every 3 s today. */+ desktopReader(tabId: string, person: AuthUser): Reader+ /** A CLI host's roster read, every 1 s today. */+ hostReader(host: AuthUser, machineId: string): Reader+ /** What the Swarm's state costs to store: the documents that hold it and their total BSON size. */+ stateSize(tabId: string): Promise<{ bytes: number; documents: number }>+ close(): Promise<void>+}++/** A client's view of one call. `code` is the error code (`SWARM_BUSY` and so on), null on success. */+export interface Reply<T = unknown> {+ status: number+ code: string | null+ data: T | null+ /** Response body size in bytes. */+ bytes: number+}++export interface Reader {+ readonly label: string+ /** One poll. A reader keeps whatever it needs between polls (a cursor, a version). */+ poll(): Promise<Reply>+}++export type CommandResult = { revision?: number; result: Record<string, unknown> }++export interface NativeEvent {+ turnId: string+ kind: 'prompt' | 'answer'+ previousEventId: string | null+ text: string+ truncated: boolean+ interrupted: boolean+}++export type DeliveryAction = { type: 'claim'; claimId: string } | { type: 'ack'; claimId: string; receipt: string; uncertain: boolean }++/** The few facts setup reads back, independent of how a store keeps them. */+export interface Snapshot {+ conversations: Array<{ id: string; checks: Array<{ id: string }>; assignment: { id: string; agentId: string; status: string } | null }>+ agents: Array<{ id: string; machineId: string; harnessId: string }>+}diff --git a/backend/integration/bench/drivers/parts.test.ts b/backend/integration/bench/drivers/parts.test.tsnew file mode 100644index 000000000..d004889d7--- /dev/null+++ b/backend/integration/bench/drivers/parts.test.ts@@ -0,0 +1,65 @@+import { afterAll, beforeAll, describe, expect, it } from 'vitest'+import { AttemptCounter } from '../attempts.js'+import { DEFAULT_CONFIG, type BenchConfig } from '../config.js'+import type { SwarmDriver } from '../driver.js'+import { machineId, seedAccounts } from '../fixtures.js'+import { localDatabase, type LocalDatabase } from '../mongo.js'+import { plan } from '../plan.js'+import { seedSwarm, type Swarm } from '../seed.js'+import { partsDriver } from './parts.js'++// A small Swarm built through the parts store's routes, read the way today's clients on the new read API read it.+const config: BenchConfig = { ...DEFAULT_CONFIG, groups: 4, doneShare: 0.5, workers: 2, machines: 2, text: { briefChars: 200, resultChars: 50, messageChars: 40 } }+let database: LocalDatabase, driver: SwarmDriver, swarm: Swarm+let clock = Date.now()++beforeAll(async () => {+ database = await localDatabase()+ const people = await seedAccounts(database.db, config.machines)+ driver = await partsDriver(new AttemptCounter().wrap(database.db), () => people, { now: () => clock })+ swarm = (await seedSwarm(driver, config, plan(config), people)).swarm+})+afterAll(async () => { await driver?.close(); await database?.stop() })++const post = (text: string) => driver.execute(swarm.tabId, swarm.people[0]!, `post-${text.replaceAll(' ', '-')}`,+ { type: 'message.send', conversationId: swarm.workers[0]!.group, text, replyTo: null, recipientIds: [] })++describe('the parts driver', () => {+ it('seeds through the new reads: check ids from the first load, machine generations from the host form', () => {+ for (const w of swarm.workers) expect(w.checkIds).toHaveLength(2)+ expect(swarm.generations).toHaveLength(config.machines)+ for (const generation of swarm.generations) expect(generation).toMatch(/\S/)+ })++ it('has a Desktop window load the Swarm once, then read only what changed since its cursor', async () => {+ const reader = driver.desktopReader(swarm.tabId, swarm.people[0]!)+ const first = await reader.poll() as { data: { format: number; head: unknown }; bytes: number }+ expect(first.data.format).toBe(2)+ expect(first.data.head).toBeTruthy()+ // A change read, not another first load. (Parts changed in the last 30 s come again by design, so right after seeding+ // it is not yet small.)+ const idle = await reader.poll() as { data: { reload: boolean; head?: unknown; cursor: string } }+ expect(idle.data.reload).toBe(false)+ expect(idle.data.cursor).toMatch(/\S/)+ expect((await post('after the first load')).code).toBeNull()+ const changed = await reader.poll() as { data: { groups: Array<{ key: string }> } }+ expect(changed.data.groups.map(g => g.key)).toContain(swarm.workers[0]!.group)+ })++ it('has a host read its form in full once, then by change naming the rows it holds, and in full again after a minute', async () => {+ const host = swarm.people[swarm.workers[0]!.machine]!+ const reader = driver.hostReader(host, machineId(swarm.workers[0]!.machine))+ const first = await reader.poll() as { data: { full: boolean; tabs: Array<{ tabId: string; roster?: unknown[] }> } }+ expect(first.data.full).toBe(true)+ expect(first.data.tabs.find(t => t.tabId === swarm.tabId)?.roster?.length).toBeGreaterThan(0)+ clock += 1_000+ const next = await reader.poll() as { data: { full: boolean; tabs: Array<{ tabId: string; unchanged?: true; roster?: unknown[] }> } }+ expect(next.data.full).toBe(false)+ // Whatever comes back for this Swarm hashes the same as the rows held, so it carries none.+ for (const tab of next.data.tabs) expect(tab.roster, tab.tabId).toBeUndefined()+ clock += 60_000+ const minute = await reader.poll() as { data: { full: boolean; tabs: Array<{ tabId: string; unchanged?: true; roster?: unknown[] }> } }+ expect(minute.data.full).toBe(true)+ expect(minute.data.tabs.find(t => t.tabId === swarm.tabId)).toMatchObject({ unchanged: true })+ })+})diff --git a/backend/integration/bench/drivers/parts.ts b/backend/integration/bench/drivers/parts.tsnew file mode 100644index 000000000..e1e4e798d--- /dev/null+++ b/backend/integration/bench/drivers/parts.ts@@ -0,0 +1,100 @@+import type { PrismaClient } from '@prisma/client'+import type { AuthUser } from '../../../src/lib/ssoAuth.js'+import type { Changes, FirstLoad, HostChanges, HostChangesRequest } from '../../../src/superTabs/read/contract.js'+import type { Reader, Reply, Snapshot, SwarmDriver } from '../driver.js'+import { legacyDriver, storeRoutes } from '../legacyDriver.js'++const base = '/api/super-tabs'+/** The parts' collections (backend/prisma/schema.prisma, Swarm state by parts). */+const PARTS = ['SwarmHead', 'SwarmMember', 'SwarmGroup', 'SwarmAgent', 'SwarmMachine', 'SwarmStart', 'SwarmProgress']+/** A host asks for its whole form at least this often (cli/src/superTabs/hostFeed.ts `HOST_FULL_MS`). */+const HOST_FULL_MS = 60_000++/**+ * The store by parts (#1726 groups 2 and 3), read through the new read API the way the merged clients read it. Commands,+ * machine reports, terminals and deliveries go through the same routes as `legacyDriver`; only the reads differ:+ * - setup facts come from a first load, and a machine's generation from its host form;+ * - a Desktop window loads the Swarm once, then reads the changes since its cursor (desktop/lib/super_tabs controller); a+ * `reload` answer is followed by a first load in the same poll;+ * - a host reads its form (cli/src/superTabs/hostFeed.ts): in full at start and at least every minute, by change in+ * between, naming the etag of the rows it holds so an unchanged Swarm comes back without them;+ * - the state's size is its live parts: every part except tombstones and dormant groups.+ */+export async function partsDriver(db: PrismaClient, users: () => readonly AuthUser[], options: { now?: () => number } = {}): Promise<SwarmDriver> {+ const now = options.now ?? Date.now+ // One app and store behind the writes and the reads, as in one backend process.+ const routes = await storeRoutes(db, users), { call } = routes+ const legacy = await legacyDriver(db, users, routes)+ const firstLoad = (tabId: string, user: AuthUser) => call<FirstLoad>(user, 'GET', `${base}/${tabId}/parts`)+ const hostForm = (host: AuthUser, machineId: string, request: HostChangesRequest) => Object.keys(request.held ?? {}).length+ ? call<HostChanges>(host, 'POST', `${base}/hosts/${machineId}/changes`, request)+ : call<HostChanges>(host, 'GET', `${base}/hosts/${machineId}/changes?${request.full ? 'full=1' : `cursor=${request.cursor}`}`)++ const desktopReader = (tabId: string, person: AuthUser): Reader => {+ let cursor: string | null = null+ const load = async (spent: number): Promise<Reply> => {+ const reply = await firstLoad(tabId, person)+ cursor = reply.data?.cursor ?? null+ return { ...reply, bytes: spent + reply.bytes }+ }+ return { label: `desktop:${person.email}`, async poll() {+ if (cursor === null) return load(0)+ const reply = await call<Changes>(person, 'GET', `${base}/${tabId}/changes?cursor=${cursor}`)+ if (reply.data?.reload) return load(reply.bytes)+ if (reply.data) cursor = reply.data.cursor+ return reply+ } }+ }++ const hostReader = (host: AuthUser, machineId: string): Reader => {+ let cursor: string | null = null, fullAt = -Infinity+ let held: Record<string, string> = {}+ return { label: `host:${machineId}`, async poll() {+ const full = cursor === null || now() - fullAt >= HOST_FULL_MS, startedAt = now()+ const reply = await hostForm(host, machineId, full ? { full: true, held } : { cursor: cursor!, held })+ const answer = reply.data+ if (!answer) return reply+ // As the CLI keeps them: a full answer replaces every Swarm; one it answers unchanged keeps the etag it already had.+ const next: Record<string, string> = answer.full ? {} : { ...held }+ for (const tabId of answer.removedTabIds) delete next[tabId]+ for (const tab of answer.tabs) {+ if (!tab.unchanged || held[tab.tabId]) next[tab.tabId] = tab.etag+ else delete next[tab.tabId]+ }+ held = next+ cursor = answer.cursor+ if (answer.full) fullAt = startedAt+ return reply+ } }+ }++ return {+ ...legacy,+ name: 'parts',+ async snapshot(tabId, user) {+ const reply = await firstLoad(tabId, user)+ if (!reply.data) throw new Error(`First load failed: ${reply.code}`)+ return { conversations: reply.data.groups.map(g => g.data), agents: reply.data.agents.map(a => a.data) } satisfies Snapshot+ },+ async machineGeneration(tabId, host, machineId) {+ const reply = await hostForm(host, machineId, { full: true })+ const tab = reply.data?.tabs.find(t => t.tabId === tabId)+ if (!tab || tab.unchanged || !tab.pool) throw new Error(`No contribution of ${machineId}: ${reply.code}`)+ return tab.pool.machine.generation+ },+ desktopReader,+ hostReader,+ async stateSize(tabId) {+ let bytes = 0, documents = 0+ for (const collection of PARTS) {+ const match = collection === 'SwarmGroup' ? { tabId, deleted: false, dormant: false } : { tabId, deleted: false }+ const result = await db.$runCommandRaw({ aggregate: collection, cursor: {},+ pipeline: [{ $match: match }, { $group: { _id: null, bytes: { $sum: { $bsonSize: '$$ROOT' } }, documents: { $sum: 1 } } }] }) as+ { cursor: { firstBatch: Array<{ bytes: number; documents: number }> } }+ bytes += result.cursor.firstBatch[0]?.bytes ?? 0+ documents += result.cursor.firstBatch[0]?.documents ?? 0+ }+ return { bytes, documents }+ },+ }+}diff --git a/backend/integration/bench/fixtures.ts b/backend/integration/bench/fixtures.tsnew file mode 100644index 000000000..2221b56ea--- /dev/null+++ b/backend/integration/bench/fixtures.ts@@ -0,0 +1,24 @@+import type { PrismaClient } from '@prisma/client'+import type { AuthUser } from '../../src/lib/ssoAuth.js'++/** Person [n]: 0 is the Swarm's owner, n ≥ 1 owns machine n. Ids are Mongo ObjectIds, as the User model needs. */+export function person(n: number): AuthUser {+ return { sub: (0x100000000000000000000001n + BigInt(n)).toString(16).padStart(24, '0'), email: `bench-${n}@example.com`,+ autonomousEnv: 'prod', role: 'user' }+}++export const machineId = (n: number) => `bench-machine-${n}`++/** The accounts and machine rows behind a Swarm: synthetic, local, one person per machine. Not part of any Swarm's state,+ * so every driver shares them. */+export async function seedAccounts(db: PrismaClient, machines: number): Promise<AuthUser[]> {+ const people = Array.from({ length: machines }, (_, n) => person(n))+ for (const user of people) {+ await db.user.create({ data: { id: user.sub, externalId: `bench-${user.sub}`, email: user.email, autonomousEnv: user.autonomousEnv } })+ }+ for (let n = 0; n < machines; n++) {+ await db.machine.create({ data: { machineId: machineId(n), userId: people[n]!.sub, apiKey: 'bench-only', managerId: 'bench',+ autonomousEnv: 'prod', authMode: 'remote', name: `Bench machine ${n}` } })+ }+ return people+}diff --git a/backend/integration/bench/http.ts b/backend/integration/bench/http.tsnew file mode 100644index 000000000..75265803d--- /dev/null+++ b/backend/integration/bench/http.ts@@ -0,0 +1,37 @@+import Fastify, { type FastifyInstance, type FastifyPluginAsync } from 'fastify'+import type { AuthUser } from '../../src/lib/ssoAuth.js'+import { errorHandler } from '../../src/middlewares/errorHandler.js'+import type { Reply } from './driver.js'++/** The bench's accounts sign in with their id as the bearer token, as in integration/superTabs.test.ts: external SSO is+ * replaced, and every permission and transaction behind the routes is real. */+export async function benchApp(users: () => readonly AuthUser[], routes: FastifyPluginAsync): Promise<FastifyInstance> {+ const app = Fastify()+ app.setErrorHandler(errorHandler)+ app.addHook('onRequest', async (request, reply) => {+ const user = users().find(u => `Bearer ${u.sub}` === request.headers.authorization)+ if (!user) return reply.code(401).send({ success: false })+ request.user = user+ })+ await app.register(routes)+ await app.ready()+ return app+}++export type Call = <T>(user: AuthUser, method: 'GET' | 'POST', url: string, body?: unknown) => Promise<Reply<T>>++/** One HTTP call in process, read the way clients read it: `{ success, data }` or `{ success: false, error: { code } }`. */+export function caller(app: FastifyInstance): Call {+ return async <T>(user: AuthUser, method: 'GET' | 'POST', url: string, body?: unknown) => {+ const response = await app.inject({ method, url, headers: { authorization: `Bearer ${user.sub}` },+ ...(body === undefined ? {} : { payload: body as Record<string, unknown> }) })+ const parsed = parse(response.body)+ const ok = response.statusCode < 400 && parsed?.success === true+ return { status: response.statusCode, bytes: response.rawPayload.byteLength,+ code: ok ? null : parsed?.error?.code ?? `HTTP_${response.statusCode}`, data: ok ? (parsed!.data as T) : null }+ }+}++function parse(body: string): { success?: boolean; data?: unknown; error?: { code?: string } } | null {+ try { return JSON.parse(body) } catch { return null }+}diff --git a/backend/integration/bench/legacyDriver.ts b/backend/integration/bench/legacyDriver.tsnew file mode 100644index 000000000..ff293c7f8--- /dev/null+++ b/backend/integration/bench/legacyDriver.ts@@ -0,0 +1,56 @@+import type { PrismaClient } from '@prisma/client'+import type { AuthUser } from '../../src/lib/ssoAuth.js'+import { superTabRoutes } from '../../src/routes/superTabs.js'+import { SuperTabStore } from '../../src/superTabs/store.js'+import type { CommandResult, Reader, Snapshot, SwarmDriver } from './driver.js'+import { benchApp, caller, type Call } from './http.js'++const base = '/api/super-tabs'++/** The Super Tab routes on one store, in process. Drivers that share them share the store and its in-process state. */+export interface StoreRoutes { call: Call; close(): Promise<void> }++export async function storeRoutes(db: PrismaClient, users: () => readonly AuthUser[]): Promise<StoreRoutes> {+ const store = new SuperTabStore(db)+ // No GitHub App: the bench never reaches GitHub.+ const app = await benchApp(users, async scope => superTabRoutes(scope, { store, github: null }))+ return { call: caller(app), close: () => app.close() }+}++/** Today's store: one `SuperTab` document per Swarm, read in full by every poll (store.ts, routes/superTabs.ts). On the+ * store by parts its full reads answer 426, so `partsDriver` keeps only its writes. */+export async function legacyDriver(db: PrismaClient, users: () => readonly AuthUser[], routes?: StoreRoutes): Promise<SwarmDriver> {+ const { call, close } = routes ?? await storeRoutes(db, users)+ const reader = (label: string, user: AuthUser, url: string): Reader => ({ label, poll: () => call(user, 'GET', url) })+ return {+ name: 'legacy',+ close,+ createSwarm: (owner, operationId, name) => call(owner, 'POST', base, { operationId, name }),+ execute: (tabId, user, operationId, command, asAgentId) =>+ call<CommandResult>(user, 'POST', `${base}/${tabId}/commands`, { operationId, command, ...(asAgentId ? { asAgentId } : {}) }),+ async snapshot(tabId, user) {+ const reply = await call<{ state: Snapshot }>(user, 'GET', `${base}/${tabId}`)+ if (!reply.data) throw new Error(`Snapshot failed: ${reply.code}`)+ return reply.data.state+ },+ async machineGeneration(tabId, host, machineId) {+ const reply = await call<Array<{ tabId: string; machine: { generation: string } }>>(host, 'GET', `${base}/hosts/${machineId}/pools`)+ const row = reply.data?.find(r => r.tabId === tabId)+ if (!row) throw new Error(`No contribution of ${machineId}: ${reply.code}`)+ return row.machine.generation+ },+ observeMachine: (tabId, host, machineId, observation) => call(host, 'POST', `${base}/${tabId}/machines/${machineId}`, observation),+ openNative: (tabId, opener, input) => call(opener, 'POST', `${base}/${tabId}/native`, input),+ appendNative: (tabId, host, contextId, event) => call(host, 'POST', `${base}/${tabId}/native/${contextId}`, event),+ deliveries: (tabId, host, agentId) => call(host, 'GET', `${base}/${tabId}/agents/${agentId}/deliveries`),+ delivery: (tabId, host, agentId, deliveryId, action) => call(host, 'POST', `${base}/${tabId}/agents/${agentId}/deliveries/${deliveryId}`, action),+ desktopReader: (tabId, person) => reader(`desktop:${person.email}`, person, `${base}/${tabId}`),+ hostReader: (host, machineId) => reader(`host:${machineId}`, host, `${base}/hosts/${machineId}`),+ async stateSize(tabId) {+ const result = await db.$runCommandRaw({ aggregate: 'SuperTab', cursor: {},+ pipeline: [{ $match: { _id: tabId } }, { $project: { size: { $bsonSize: '$$ROOT' } } }] }) as { cursor: { firstBatch: Array<{ size: number }> } }+ const rows = result.cursor.firstBatch+ return { bytes: rows.reduce((sum, r) => sum + r.size, 0), documents: rows.length }+ },+ }+}diff --git a/backend/integration/bench/load.ts b/backend/integration/bench/load.tsnew file mode 100644index 000000000..d836a15ed--- /dev/null+++ b/backend/integration/bench/load.ts@@ -0,0 +1,131 @@+import { performance } from 'node:perf_hooks'+import { setTimeout as sleep } from 'node:timers/promises'+import type { Command } from '../../src/superTabs/commands.js'+import type { MachineObservation } from '../../src/superTabs/machines.js'+import type { AttemptCounter } from './attempts.js'+import type { BenchConfig } from './config.js'+import type { Reader, Reply, SwarmDriver } from './driver.js'+import { machineId } from './fixtures.js'+import { Recorder } from './metrics.js'+import type { Plan } from './plan.js'+import { random, words } from './random.js'+import type { Swarm, Worker } from './seed.js'++export interface LoadResult {+ recorder: Recorder+ /** Planned calls left undone because the run passed its deadline, by activity. */+ skipped: Record<string, number>+ actualMs: number+ /** The readers, after the load: a probe polls each once more, as a client that is already up to date. */+ readers: Reader[]+}++const pad = (n: number) => String(n).padStart(2, '0')++/** A machine's report in the shape its host sends (cli/src/superTabs/machines.ts), naming the sessions running there. */+function observation(generation: string, runningHarnessIds: string[]): MachineObservation {+ return { generation, quotas: [], tools: {}, runningHarnessIds, stoppedHarnessIds: [],+ resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9, diskTotalBytes: 500e9,+ projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Bench', os: 'macOS', gpuPercent: null } }+}++/** Runs the plan against the driver: every actor on its own timeline, all at once, each call measured. */+export async function runLoad(driver: SwarmDriver, counter: AttemptCounter, config: BenchConfig, p: Plan, swarm: Swarm): Promise<LoadResult> {+ const recorder = new Recorder(), skipped: Record<string, number> = {}+ const { tabId, people, leadId, workers, generations } = swarm, owner = people[0]!+ // A slow store stretches the run instead of dropping work, up to this point; what is left after it is counted as skipped.+ const start = performance.now(), deadline = start + config.durationMs + Math.max(10_000, config.durationMs / 4)+ let operation = 0+ const op = () => `bench-${config.seed}-load-${operation++}`++ async function measure<T>(name: string, writer: string, call: () => Promise<Reply<T>>, read = false): Promise<Reply<T> | null> {+ const tracked = await counter.track(call)+ const reply = tracked.value ?? null+ recorder.add({ op: name, writer, ms: tracked.ms, failedAttempts: tracked.failedAttempts,+ outcome: tracked.error ? 'EXCEPTION' : reply!.code ?? 'ok', ...(read && reply ? { bytes: reply.bytes } : {}) })+ return reply && !reply.code ? reply : null+ }+ async function timeline(activity: string, times: number[], act: (i: number) => Promise<void>) {+ for (let i = 0; i < times.length; i++) {+ if (performance.now() > deadline) { skipped[activity] = (skipped[activity] ?? 0) + times.length - i; return }+ const wait = start + times[i]! - performance.now()+ if (wait > 0) await sleep(wait)+ await act(i)+ }+ }+ const command = (writer: string, user = owner, asAgentId?: string) => (c: Command) =>+ measure(c.type, writer, () => driver.execute(tabId, user, op(), c, asAgentId))++ /** A worker's post in one of its groups (status and checks in the group whose task it holds). */+ function poster(w: Worker, i: number) {+ const rng = random(config.seed, `worker-text-${i}`), post = command(`worker-${pad(i)}`, people[w.machine]!, w.id)+ return async (n: number) => {+ const { op: kind, group: g } = p.workers[i]!.actions[n]!, group = swarm.groups[g]!+ if (kind === 'message.send') await post({ type: kind, conversationId: group, text: words(rng, config.text.messageChars), replyTo: null, recipientIds: [] })+ if (kind === 'work.status') await post({ type: kind, conversationId: group, assignmentId: w.assignmentId, status: 'working', result: words(rng, config.text.resultChars) })+ if (kind === 'work.check') {+ await post({ type: kind, conversationId: group, assignmentId: w.assignmentId, checkId: rng.pick(w.checkIds), passed: rng.next() < 0.5, evidence: words(rng, 200) })+ }+ }+ }+ /** A worker's terminal turn, recorded by its host: the prompt, then its answer. */+ function turner(w: Worker, i: number) {+ const rng = random(config.seed, `worker-turns-${i}`), host = people[w.machine]!+ let previousEventId: string | null = null+ const append = (turnId: string, kind: 'prompt' | 'answer') => measure('native.append', `terminal-${pad(i)}`, () => driver.appendNative(tabId, host, w.contextId,+ { turnId, kind, previousEventId, text: words(rng, config.text.messageChars), truncated: false, interrupted: false }))+ return async (n: number) => {+ const prompt = await append(`turn-${n}`, 'prompt')+ // An answer to an unrecorded prompt is refused by design; the host records a gap instead, which the bench does not model.+ if (!prompt) { skipped['native answers'] = (skipped['native answers'] ?? 0) + 1; return }+ previousEventId = prompt.data!.eventId+ const answer = await append(`turn-${n}`, 'answer')+ if (answer) previousEventId = answer.data!.eventId+ }+ }+ /** Mixed: posts and terminal side by side, as today. Cross-group lane: one sequence, so the worker's groups have one writer. */+ function worker(w: Worker, i: number): Array<Promise<void>> {+ const post = poster(w, i), turn = turner(w, i), { actions, turns } = p.workers[i]!+ if (config.lane === 'mixed') return [timeline('worker posts', actions.map(a => a.at), post), timeline('native turns', turns, turn)]+ const events = [...actions.map((a, n) => ({ at: a.at, run: () => post(n) })), ...turns.map((at, n) => ({ at, run: () => turn(n) }))]+ .sort((a, b) => a.at - b.at)+ return [timeline('worker posts and turns', events.map(e => e.at), n => events[n]!.run())]+ }+ function leadSends() {+ const rng = random(config.seed, 'lead-text'), send = command('lead', owner, leadId)+ return timeline('lead sends', p.lead.map(s => s.at), async n => {+ const { worker: index, group } = p.lead[n]!, target = workers[index]!+ await send({ type: 'message.send', conversationId: swarm.groups[group]!, text: words(rng, config.text.messageChars), replyTo: null, recipientIds: [target.id] })+ })+ }+ const running = (m: number) => [...(m === 0 ? ['bench-lead'] : []), ...workers.filter(w => w.machine === m).map(w => w.harnessId)]+ const agentsOn = (m: number) => [...(m === 0 ? [leadId] : []), ...workers.filter(w => w.machine === m).map(w => w.id)]+ function machineReports(m: number) {+ return timeline('machine reports', p.machines[m]!.observations, async () => {+ await measure('observeMachine', `machine-${m}`, () => driver.observeMachine(tabId, people[m]!, machineId(m), observation(generations[m]!, running(m))))+ })+ }+ function deliveryPasses(m: number) {+ const host = people[m]!, writer = `delivery-${m}`+ return timeline('delivery passes', p.machines[m]!.deliveryPasses, async () => {+ for (const agentId of agentsOn(m)) {+ const waiting = await measure('deliveries.list', writer, () => driver.deliveries(tabId, host, agentId))+ for (const { id } of waiting?.data ?? []) {+ const claimId = `claim-${id}`+ if (!await measure('delivery.claim', writer, () => driver.delivery(tabId, host, agentId, id, { type: 'claim', claimId }))) continue+ await measure('delivery.ack', writer, () => driver.delivery(tabId, host, agentId, id, { type: 'ack', claimId, receipt: `typed-${id}`, uncertain: false }))+ }+ }+ })+ }+ const readers = p.readers.map(r => ({ plan: r, reader: r.kind === 'desktop' ? driver.desktopReader(tabId, people[r.index]!) : driver.hostReader(people[r.index]!, machineId(r.index)) }))+ const polls = readers.map(({ plan: r, reader }) => timeline(`${r.kind} polls`, r.polls, async () => {+ await measure(`read.${r.kind}`, reader.label, () => reader.poll(), true)+ }))++ await Promise.all([+ ...workers.flatMap(worker), leadSends(),+ ...p.machines.flatMap(m => [machineReports(m.index), deliveryPasses(m.index)]), ...polls,+ ])+ return { recorder, skipped, actualMs: performance.now() - start, readers: readers.map(r => r.reader) }+}diff --git a/backend/integration/bench/metrics.test.ts b/backend/integration/bench/metrics.test.tsnew file mode 100644index 000000000..d424b2c09--- /dev/null+++ b/backend/integration/bench/metrics.test.ts@@ -0,0 +1,63 @@+import { describe, expect, it } from 'vitest'+import { percentile, Recorder } from './metrics.js'++describe('percentile', () => {+ it('takes the nearest rank', () => {+ const values = [5, 1, 4, 2, 3, 10, 9, 8, 7, 6]+ expect(percentile(values, 50)).toBe(5)+ expect(percentile(values, 95)).toBe(10)+ expect(percentile(values, 100)).toBe(10)+ expect(percentile([42], 95)).toBe(42)+ })++ it('is null for no values', () => {+ expect(percentile([], 50)).toBeNull()+ })+})++describe('Recorder', () => {+ it('sums count, retries by code, Swarm busy and errors, and latency per operation and per writer', () => {+ const recorder = new Recorder()+ recorder.add({ op: 'message.send', writer: 'agent-01', ms: 10, failedAttempts: [], outcome: 'ok' })+ recorder.add({ op: 'message.send', writer: 'agent-01', ms: 30, failedAttempts: ['P2034', 'P2034'], outcome: 'ok' })+ recorder.add({ op: 'message.send', writer: 'agent-02', ms: 50, failedAttempts: Array(7).fill('P2034'), outcome: 'SWARM_BUSY' })+ recorder.add({ op: 'work.check', writer: 'agent-02', ms: 20, failedAttempts: ['TRANSIENT'], outcome: 'NOT_FOUND' })++ const send = recorder.byOp().find(row => row.key === 'message.send')!+ expect(send).toEqual({ key: 'message.send', count: 3, ok: 2, conflicts: 9, retriedCalls: 2, swarmBusy: 1, errors: {},+ p50Ms: 30, p95Ms: 50, maxMs: 50, bytes: null })+ const check = recorder.byOp().find(row => row.key === 'work.check')!+ expect(check).toMatchObject({ count: 1, ok: 0, conflicts: 1, retriedCalls: 1, swarmBusy: 0, errors: { NOT_FOUND: 1 } })++ const second = recorder.byWriter().find(row => row.key === 'agent-02')!+ expect(second).toMatchObject({ count: 2, ok: 0, conflicts: 8, retriedCalls: 2, swarmBusy: 1, p50Ms: 20, p95Ms: 50 })+ })++ it('reports bytes per call for readers: mean, p50 and p95', () => {+ const recorder = new Recorder()+ for (const bytes of [100, 200, 300, 400]) recorder.add({ op: 'read.full', writer: 'desktop-0', ms: 5, failedAttempts: [], outcome: 'ok', bytes })+ expect(recorder.byOp()[0]!.bytes).toEqual({ mean: 250, p50: 200, p95: 400, total: 1000 })+ })++ it('counts each writer\'s calls per operation', () => {+ const recorder = new Recorder()+ for (const op of ['message.send', 'message.send', 'work.check']) recorder.add({ op, writer: 'lead', ms: 1, failedAttempts: [], outcome: 'ok' })+ expect(recorder.byWriter()[0]!.byOp).toEqual({ 'message.send': 2, 'work.check': 1 })+ })++ it('totals by kind of writer, so a machine conflicting with group writes shows on its own line', () => {+ const recorder = new Recorder()+ recorder.add({ op: 'message.send', writer: 'worker-01', ms: 1, failedAttempts: ['P2034'], outcome: 'ok' })+ recorder.add({ op: 'native.append', writer: 'worker-12', ms: 1, failedAttempts: [], outcome: 'ok' })+ recorder.add({ op: 'observeMachine', writer: 'machine-3', ms: 1, failedAttempts: ['P2034', 'P2034'], outcome: 'ok' })+ recorder.add({ op: 'read.desktop', writer: 'desktop:[email protected]', ms: 1, failedAttempts: [], outcome: 'ok', bytes: 10 })+ expect(recorder.byWriterKind().map(row => [row.key, row.count, row.conflicts])).toEqual([['desktop', 1, 0], ['machine', 1, 2], ['worker', 2, 1]])+ })++ it('keeps operations and writers in name order', () => {+ const recorder = new Recorder()+ for (const op of ['work.status', 'message.send', 'observeMachine']) recorder.add({ op, writer: `w-${op}`, ms: 1, failedAttempts: [], outcome: 'ok' })+ expect(recorder.byOp().map(row => row.key)).toEqual(['message.send', 'observeMachine', 'work.status'])+ expect(recorder.byWriter().map(row => row.key)).toEqual(['w-message.send', 'w-observeMachine', 'w-work.status'])+ })+})diff --git a/backend/integration/bench/metrics.ts b/backend/integration/bench/metrics.tsnew file mode 100644index 000000000..e33f54476--- /dev/null+++ b/backend/integration/bench/metrics.ts@@ -0,0 +1,82 @@+/** One call the scenario made, as the client saw it. */+export interface Sample {+ /** The command type or the non-command path, e.g. `message.send`, `observeMachine`, `read.full`. */+ op: string+ /** Who made it, e.g. `agent-03`, `machine-2`, `desktop-0`. */+ writer: string+ ms: number+ /** The error code of every database transaction attempt that failed and was retried or given up. */+ failedAttempts: string[]+ /** `ok`, or the error code the client got (`SWARM_BUSY` when the store gave up retrying). */+ outcome: string+ /** Response body size, for readers. */+ bytes?: number+}++export interface Row {+ key: string+ count: number+ ok: number+ /** Failed transaction attempts (write conflicts and other retryable errors). */+ conflicts: number+ /** Calls that needed at least one retry. */+ retriedCalls: number+ swarmBusy: number+ /** Other error outcomes, by code. */+ errors: Record<string, number>+ p50Ms: number | null+ p95Ms: number | null+ maxMs: number | null+ bytes: { mean: number; p50: number; p95: number; total: number } | null+}++/** A writer's row, with how many calls of each operation it made. */+export type WriterRow = Row & { byOp: Record<string, number> }++/** Nearest-rank percentile; null when there are no values. */+export function percentile(values: readonly number[], p: number): number | null {+ if (!values.length) return null+ const sorted = [...values].sort((a, b) => a - b)+ return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1))]!+}++function row(key: string, samples: readonly Sample[]): Row {+ const ms = samples.map(s => s.ms)+ const sizes = samples.flatMap(s => s.bytes === undefined ? [] : [s.bytes])+ const errors: Record<string, number> = {}+ for (const s of samples) if (s.outcome !== 'ok' && s.outcome !== 'SWARM_BUSY') errors[s.outcome] = (errors[s.outcome] ?? 0) + 1+ const total = sizes.reduce((sum, n) => sum + n, 0)+ return {+ key, count: samples.length, ok: samples.filter(s => s.outcome === 'ok').length,+ conflicts: samples.reduce((sum, s) => sum + s.failedAttempts.length, 0),+ retriedCalls: samples.filter(s => s.failedAttempts.length > 0).length,+ swarmBusy: samples.filter(s => s.outcome === 'SWARM_BUSY').length, errors,+ p50Ms: percentile(ms, 50), p95Ms: percentile(ms, 95), maxMs: percentile(ms, 100),+ bytes: sizes.length ? { mean: Math.round(total / sizes.length), p50: percentile(sizes, 50)!, p95: percentile(sizes, 95)!, total } : null,+ }+}++function grouped(samples: readonly Sample[], key: (s: Sample) => string): Row[] {+ const groups = new Map<string, Sample[]>()+ for (const s of samples) {+ const list = groups.get(key(s))+ if (list) list.push(s)+ else groups.set(key(s), [s])+ }+ return [...groups.keys()].sort().map(k => row(k, groups.get(k)!))+}++export class Recorder {+ private readonly samples: Sample[] = []+ add(sample: Sample): void { this.samples.push(sample) }+ byOp(): Row[] { return grouped(this.samples, s => s.op) }+ /** By kind of writer: `worker-03` and `worker-11` are both `worker`, `desktop:someone` is `desktop`. */+ byWriterKind(): Row[] { return grouped(this.samples, s => s.writer.split(':')[0]!.replace(/-\d+$/, '')) }+ byWriter(): WriterRow[] {+ return grouped(this.samples, s => s.writer).map(row => {+ const byOp: Record<string, number> = {}+ for (const s of this.samples) if (s.writer === row.key) byOp[s.op] = (byOp[s.op] ?? 0) + 1+ return { ...row, byOp }+ })+ }+}diff --git a/backend/integration/bench/mongo.ts b/backend/integration/bench/mongo.tsnew file mode 100644index 000000000..936636d9f--- /dev/null+++ b/backend/integration/bench/mongo.ts@@ -0,0 +1,29 @@+import { randomUUID } from 'node:crypto'+import { execFile } from 'node:child_process'+import { promisify } from 'node:util'+import { join } from 'node:path'+import { tmpdir } from 'node:os'+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'+import { PrismaClient } from '@prisma/client'++export interface LocalDatabase {+ db: PrismaClient+ /** The MongoDB server version the run measured. */+ version: string+ stop(): Promise<void>+}++/** A fresh loopback replica set with the backend's schema, as integration/superTabs.test.ts makes one. The bench never+ * reads DATABASE_URL or any existing database (spec: "Constraints all groups share", isolation). */+export async function localDatabase(): Promise<LocalDatabase> {+ const version = '7.0.24'+ const replica = await MongoMemoryReplSet.create({ binary: { version, downloadDir: join(tmpdir(), 'harness-super-tab-mongodb-binaries') },+ replSet: { count: 1, ip: '127.0.0.1', storageEngine: 'wiredTiger' } })+ const uri = replica.getUri(`swarm_bench_${randomUUID().replaceAll('-', '_')}`)+ if (!new URL(uri).hostname.startsWith('127.0.0.1')) throw new Error(`Refusing a database that is not on this computer: ${uri}`)+ await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], {+ env: { ...process.env, DATABASE_URL: uri }, timeout: 60000,+ })+ const db = new PrismaClient({ datasources: { db: { url: uri } } })+ return { db, version, async stop() { await db.$disconnect(); await replica.stop() } }+}diff --git a/backend/integration/bench/plan.test.ts b/backend/integration/bench/plan.test.tsnew file mode 100644index 000000000..d5c128cff--- /dev/null+++ b/backend/integration/bench/plan.test.ts@@ -0,0 +1,76 @@+import { describe, expect, it } from 'vitest'+import { DEFAULT_CONFIG, type BenchConfig } from './config.js'+import { plan, planDigest } from './plan.js'++const small: BenchConfig = { ...DEFAULT_CONFIG, groups: 10, doneShare: 0.7, workers: 3, machines: 3, durationMs: 20_000 }++describe('plan', () => {+ it('is the same for the same seed and differs for another', () => {+ expect(plan(small)).toEqual(plan(small))+ expect(plan({ ...small, seed: small.seed + 1 }).workers[0]!.actions).not.toEqual(plan(small).workers[0]!.actions)+ })++ it('fingerprints the plan, so two reports can show they ran the same work', () => {+ expect(planDigest(plan(small))).toMatch(/^[0-9a-f]{64}$/)+ expect(planDigest(plan(small))).toBe(planDigest(plan(small)))+ expect(planDigest(plan({ ...small, seed: 2 }))).not.toBe(planDigest(plan(small)))+ })++ it('gives each worker its own active groups, its task in the first, and shares the done groups among the workers', () => {+ const p = plan(small)+ expect(p.doneGroups).toEqual([0, 1, 2, 3, 4, 5, 6])+ expect(p.workers.map(w => w.groups)).toEqual([[7], [8], [9]])+ expect(p.workers.map(w => w.doneGroups)).toEqual([[0, 3, 6], [1, 4], [2, 5]])+ expect(p.workers.map(w => w.machine)).toEqual([0, 1, 2])+ expect(p.workers.every(w => w.actions.every(a => a.group === w.groups[0]))).toBe(true)+ })++ it('runs a hot Swarm with every group active and the same workers spread over them', () => {+ const p = plan({ ...small, doneShare: 0, durationMs: 120_000 })+ expect(p.doneGroups).toEqual([])+ expect(p.workers.map(w => w.groups)).toEqual([[0, 3, 6, 9], [1, 4, 7], [2, 5, 8]])+ for (const w of p.workers) {+ // An agent holds one active task at a time (AGENT_BUSY): its status and checks stay in its first group.+ expect(w.actions.filter(a => a.op !== 'message.send').every(a => a.group === w.groups[0])).toBe(true)+ expect(w.actions.every(a => w.groups.includes(a.group))).toBe(true)+ expect(new Set(w.actions.filter(a => a.op === 'message.send').map(a => a.group)).size).toBeGreaterThan(1)+ }+ })++ it('keeps each worker\'s schedule when only the share of done groups changes', () => {+ const at = (c: BenchConfig) => plan(c).workers.map(w => w.actions.map(a => `${a.at}:${a.op}`))+ expect(at({ ...small, doneShare: 0 })).toEqual(at(small))+ })++ it('draws worker actions only from the mix, within the run', () => {+ const p = plan({ ...small, mix: { 'message.send': 1, 'work.status': 0, 'work.check': 1 } })+ const ops = new Set(p.workers.flatMap(w => w.actions.map(a => a.op)))+ expect([...ops].sort()).toEqual(['message.send', 'work.check'])+ expect(p.workers.every(w => w.actions.every(a => a.at < small.durationMs) && w.turns.every(t => t < small.durationMs))).toBe(true)+ })++ it('reports every machine every 15 s, and puts readers on the first people and machines', () => {+ const p = plan(small)+ for (const { observations } of p.machines) {+ expect(observations[0]).toBeLessThan(15_000)+ expect(observations.slice(1).map((t, i) => t - observations[i]!)).toEqual(observations.slice(1).map(() => 15_000))+ }+ expect(p.readers.map(r => `${r.kind}:${r.index}`)).toEqual(['desktop:0', 'desktop:1', 'desktop:2', 'host:0', 'host:1'])+ expect(p.readers.find(r => r.kind === 'host')!.polls.slice(0, 3)).toEqual([0, 1000, 2000].map(t => t + p.readers.find(r => r.kind === 'host')!.polls[0]!))+ })++ it('has the Lead send to workers that exist, in one of their groups', () => {+ const p = plan({ ...small, doneShare: 0 })+ expect(p.lead.length).toBeGreaterThan(0)+ expect(p.lead.every(send => p.workers[send.worker]?.groups.includes(send.group))).toBe(true)+ })++ it('leaves out the Lead and the delivery passes in the cross-group lane, and keeps workers, machine reports and readers', () => {+ const mixed = plan(small), lane = plan({ ...small, lane: 'cross-group' })+ expect(lane.lead).toEqual([])+ expect(lane.machines.every(m => !m.deliveryPasses.length)).toBe(true)+ expect(lane.machines.map(m => m.observations)).toEqual(mixed.machines.map(m => m.observations))+ expect(lane.workers).toEqual(mixed.workers)+ expect(lane.readers).toEqual(mixed.readers)+ })+})diff --git a/backend/integration/bench/plan.ts b/backend/integration/bench/plan.tsnew file mode 100644index 000000000..c27483a51--- /dev/null+++ b/backend/integration/bench/plan.ts@@ -0,0 +1,80 @@+import { createHash } from 'node:crypto'+import { activeCount, WORKER_ACTIONS, type BenchConfig, type WorkerAction } from './config.js'+import { random, schedule, type Random } from './random.js'++export interface WorkerPlan {+ index: number+ machine: number+ /** Its active groups. It holds the task of the first; an agent holds one active task at a time (AGENT_BUSY). */+ groups: number[]+ /** The groups it finished during setup. */+ doneGroups: number[]+ /** Status and checks go to its first group; messages to any of its groups. */+ actions: Array<{ at: number; op: WorkerAction; group: number }>+ /** When it takes a terminal turn: a prompt, then its answer. */+ turns: number[]+}++export interface Plan {+ doneGroups: number[]+ workers: WorkerPlan[]+ lead: Array<{ at: number; worker: number; group: number }>+ machines: Array<{ index: number; observations: number[]; deliveryPasses: number[] }>+ readers: Array<{ kind: 'desktop' | 'host'; index: number; polls: number[] }>+}++function weighted(rng: Random, mix: BenchConfig['mix']): WorkerAction {+ const actions = WORKER_ACTIONS.filter(a => mix[a] > 0)+ let roll = rng.next() * actions.reduce((sum, a) => sum + mix[a], 0)+ for (const action of actions) if ((roll -= mix[action]) < 0) return action+ return actions[actions.length - 1]!+}++/** A steady poller or reporter: a seeded first time within one interval, then exactly every interval. */+function steady(rng: Random, everyMs: number, durationMs: number): number[] {+ return schedule(rng, { meanMs: everyMs, durationMs, offsetMs: Math.floor(rng.next() * everyMs), jitter: false })+}++/** Everything the load will do and when, from the seed alone, so two runs do the same work in the same order. */+export function plan(config: BenchConfig): Plan {+ const { seed, durationMs, every } = config+ const done = config.groups - activeCount(config), workerCount = config.workers+ const doneGroups = Array.from({ length: done }, (_, i) => i)+ const activeGroups = Array.from({ length: activeCount(config) }, (_, i) => done + i)+ const workers = Array.from({ length: workerCount }, (_, index): WorkerPlan => {+ // Group choices have their own stream, so a worker's timing and mix stay the same whatever its number of groups.+ const rng = random(seed, `worker-${index}`), where = random(seed, `worker-groups-${index}`)+ const groups = activeGroups.filter((_, i) => i % workerCount === index)+ const actions = schedule(rng, { meanMs: every.workerPostMs, durationMs, offsetMs: Math.floor(rng.next() * every.workerPostMs) })+ .map(at => {+ const op = weighted(rng, config.mix)+ return { at, op, group: op === 'message.send' && groups.length > 1 ? where.pick(groups) : groups[0]! }+ })+ const turns = schedule(rng, { meanMs: every.nativeTurnMs, durationMs, offsetMs: Math.floor(rng.next() * every.nativeTurnMs) })+ return { index, machine: index % config.machines, groups, doneGroups: doneGroups.filter(g => g % workerCount === index), actions, turns }+ })+ const crossGroup = config.lane === 'cross-group'+ const leadRng = random(seed, 'lead'), leadWhere = random(seed, 'lead-groups')+ const lead = crossGroup ? [] : schedule(leadRng, { meanMs: every.leadSendMs, durationMs, offsetMs: Math.floor(leadRng.next() * every.leadSendMs) })+ .map(at => {+ const worker = Math.floor(leadRng.next() * workerCount), groups = workers[worker]!.groups+ return { at, worker, group: groups.length > 1 ? leadWhere.pick(groups) : groups[0]! }+ })+ const machines = Array.from({ length: config.machines }, (_, index) => {+ const rng = random(seed, `machine-${index}`)+ const observations = steady(rng, every.observeMs, durationMs), deliveryPasses = steady(rng, every.deliveryPassMs, durationMs)+ return { index, observations, deliveryPasses: crossGroup ? [] : deliveryPasses }+ })+ const readers = [+ ...Array.from({ length: config.desktopReaders }, (_, index) => ({ kind: 'desktop' as const, index,+ polls: steady(random(seed, `desktop-${index}`), every.desktopPollMs, durationMs) })),+ ...Array.from({ length: config.hostReaders }, (_, index) => ({ kind: 'host' as const, index,+ polls: steady(random(seed, `host-${index}`), every.hostTickMs, durationMs) })),+ ]+ return { doneGroups, workers, lead, machines, readers }+}++/** A fingerprint of the work a plan holds: equal fingerprints in two reports mean both runs were asked to do the same. */+export function planDigest(p: Plan): string {+ return createHash('sha256').update(JSON.stringify(p)).digest('hex')+}diff --git a/backend/integration/bench/pollDatabaseBytes.ts b/backend/integration/bench/pollDatabaseBytes.tsnew file mode 100644index 000000000..bc780e023--- /dev/null+++ b/backend/integration/bench/pollDatabaseBytes.ts@@ -0,0 +1,61 @@+import { setTimeout as sleep } from 'node:timers/promises'+import { AttemptCounter } from './attempts.js'+import { DRIVERS } from './bench.js'+import { parseArgs } from './config.js'+import type { Reader } from './driver.js'+import { machineId, seedAccounts } from './fixtures.js'+import { localDatabase } from './mongo.js'+import { plan } from './plan.js'+import { isolatedPolls } from './probe.js'+import { seedSwarm } from './seed.js'++/** Past the change reads' 30 s overlap (design section 3.3), so the next reads are idle. */+const QUIET_MS = 35_000++/**+ * What one up-to-date poll costs the database, idle and after one post (#1726; docs/performance/2026-10-26-swarm-state-results.md,+ * "What the server reads from MongoDB"). The load benchmark's isolated poll runs right after the load, inside that+ * overlap; this tells idle and active apart. It seeds the benchmark's Swarm on its own loopback replica set, polls once as+ * a Desktop window and as a host, waits with no writes, then polls idle twice and once after a post in a group with the+ * host's agent. Takes the benchmark's options (`--driver`, `--done-share`, `--seed`, …). From `backend/`:+ *+ * NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= \+ * DATABASE_URL=mongodb://127.0.0.1:1/bench-never-used npx tsx integration/bench/pollDatabaseBytes.ts+ */+async function main() {+ const { config, driver: driverName } = parseArgs(process.argv.slice(2))+ const database = await localDatabase()+ try {+ const people = await seedAccounts(database.db, config.machines)+ const driver = await DRIVERS[driverName]!(new AttemptCounter().wrap(database.db), () => people)+ const { swarm } = await seedSwarm(driver, config, plan(config), people)+ // Machine 1's host (machine 0 also runs the Lead), as the results doc measured it.+ const worker = swarm.workers.find(w => w.machine === 1) ?? swarm.workers[0]!+ const desktop = driver.desktopReader(swarm.tabId, people[0]!), hostReader = driver.hostReader(people[worker.machine]!, machineId(worker.machine))+ const poll = async (label: string, reader: Reader) => {+ const [measured] = await isolatedPolls(database.db, [reader])+ process.stdout.write(`${JSON.stringify({ label, ...measured })}\n`)+ }+ await poll('desktop first load', desktop)+ await poll('host form in full', hostReader)+ process.stdout.write(`${JSON.stringify({ state: await driver.stateSize(swarm.tabId) })}\n`)+ await sleep(QUIET_MS)+ await poll('desktop change read (resends what changed in the 30 s before the first load)', desktop)+ await poll('host form', hostReader)+ await poll('desktop change read, idle', desktop)+ await poll('host form, idle', hostReader)+ const { code } = await driver.execute(swarm.tabId, people[0]!, `bench-${config.seed}-probe-post`,+ { type: 'message.send', conversationId: worker.group, text: 'One post.', replyTo: null, recipientIds: [] })+ if (code) throw new Error(`The post failed: ${code}`)+ await poll('desktop change read, after one post', desktop)+ await poll('host form, after one post in a group with its agent', hostReader)+ await driver.close()+ } finally {+ await database.stop()+ }+}++main().catch(error => {+ process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`)+ process.exitCode = 1+})diff --git a/backend/integration/bench/probe.ts b/backend/integration/bench/probe.tsnew file mode 100644index 000000000..bea0d859b--- /dev/null+++ b/backend/integration/bench/probe.ts@@ -0,0 +1,45 @@+import { performance } from 'node:perf_hooks'+import type { PrismaClient } from '@prisma/client'+import type { Reader } from './driver.js'++export interface IsolatedPoll {+ reader: string+ responseBytes: number+ /** What MongoDB sent the backend to answer this one poll, with nothing else running. */+ databaseBytesOut: number+ ms: number+}++/** A raw command's number: plain, or Extended JSON's `$numberLong` / `$numberInt` as Prisma returns some of them. */+function count(value: unknown): number {+ if (typeof value === 'number') return value+ if (value && typeof value === 'object') {+ const wrapped = (value as Record<string, unknown>).$numberLong ?? (value as Record<string, unknown>).$numberInt+ if (wrapped !== undefined) return Number(wrapped)+ }+ throw new Error(`Not a number: ${JSON.stringify(value)}`)+}++async function bytesOut(db: PrismaClient): Promise<number> {+ const status = await db.$runCommandRaw({ serverStatus: 1 }) as { network: { bytesOut: unknown } }+ return count(status.network.bytesOut)+}++/**+ * The cost of one poll alone, after the load: a host's roster reply is small, but today's store loads every Swarm document+ * it names to build it, which only the database's own counter shows. Each reader polls once more, as a client that is+ * already up to date. The status call's own reply is measured and taken off.+ */+export async function isolatedPolls(db: PrismaClient, readers: readonly Reader[]): Promise<IsolatedPoll[]> {+ const before = await bytesOut(db)+ const ownReply = await bytesOut(db) - before+ const polls: IsolatedPoll[] = []+ for (const reader of readers) {+ const start = await bytesOut(db), started = performance.now()+ const reply = await reader.poll()+ const ms = performance.now() - started+ if (reply.code) throw new Error(`Isolated poll of ${reader.label} failed: ${reply.code}`)+ polls.push({ reader: reader.label, responseBytes: reply.bytes, databaseBytesOut: Math.max(0, await bytesOut(db) - start - ownReply), ms })+ }+ return polls+}diff --git a/backend/integration/bench/random.test.ts b/backend/integration/bench/random.test.tsnew file mode 100644index 000000000..90c20f24e--- /dev/null+++ b/backend/integration/bench/random.test.ts@@ -0,0 +1,51 @@+import { describe, expect, it } from 'vitest'+import { random, schedule, words } from './random.js'++describe('seeded random numbers', () => {+ it('repeats the same sequence for the same seed and label', () => {+ const a = random(7, 'agent-1'), b = random(7, 'agent-1')+ const first = Array.from({ length: 5 }, () => a.next())+ expect(Array.from({ length: 5 }, () => b.next())).toEqual(first)+ expect(first.every(n => n >= 0 && n < 1)).toBe(true)+ })++ it('gives another sequence for another label or seed', () => {+ const base = random(7, 'agent-1').next()+ expect(random(7, 'agent-2').next()).not.toBe(base)+ expect(random(8, 'agent-1').next()).not.toBe(base)+ })++ it('picks every item of a list over many draws, and only those', () => {+ const rng = random(1, 'pick'), seen = new Set<string>()+ for (let i = 0; i < 200; i++) seen.add(rng.pick(['a', 'b', 'c']))+ expect([...seen].sort()).toEqual(['a', 'b', 'c'])+ })+})++describe('schedule', () => {+ it('spaces events between half and one and a half times the mean, starting at the offset, inside the duration', () => {+ const times = schedule(random(3, 'machine-0'), { meanMs: 1000, durationMs: 10_000, offsetMs: 250 })+ expect(times[0]).toBe(250)+ expect(times.every(t => t < 10_000)).toBe(true)+ for (let i = 1; i < times.length; i++) {+ const gap = times[i]! - times[i - 1]!+ expect(gap).toBeGreaterThanOrEqual(500)+ expect(gap).toBeLessThanOrEqual(1500)+ }+ // About duration / mean events: 10 s at 1 s apart, give or take the jitter.+ expect(times.length).toBeGreaterThanOrEqual(7)+ expect(times.length).toBeLessThanOrEqual(20)+ })++ it('keeps a fixed interval when asked for no jitter', () => {+ expect(schedule(random(3, 'x'), { meanMs: 15_000, durationMs: 60_000, offsetMs: 0, jitter: false })).toEqual([0, 15_000, 30_000, 45_000])+ })+})++describe('words', () => {+ it('writes text of the asked length from the seed', () => {+ const text = words(random(5, 'brief'), 300)+ expect(text).toHaveLength(300)+ expect(words(random(5, 'brief'), 300)).toBe(text)+ })+})diff --git a/backend/integration/bench/random.ts b/backend/integration/bench/random.tsnew file mode 100644index 000000000..9ef8c7868--- /dev/null+++ b/backend/integration/bench/random.ts@@ -0,0 +1,47 @@+import { createHash } from 'node:crypto'++/** A seeded stream: the same seed and label give the same numbers, so two runs of the benchmark do the same work. */+export interface Random {+ /** In [0, 1). */+ next(): number+ pick<T>(items: readonly T[]): T+}++/** mulberry32, seeded from the run's seed and the actor's label, so each actor's choices do not depend on another's. */+export function random(seed: number, label: string): Random {+ let state = createHash('sha256').update(`${seed}:${label}`).digest().readUInt32LE(0)+ const next = () => {+ state = (state + 0x6d2b79f5) >>> 0+ let t = state+ t = Math.imul(t ^ (t >>> 15), t | 1)+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61)+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296+ }+ return { next, pick: items => items[Math.floor(next() * items.length)]! }+}++export interface ScheduleOptions {+ meanMs: number+ durationMs: number+ /** When the first event happens, so actors with one cadence do not all fire at once. */+ offsetMs: number+ /** Gaps between half and one and a half times the mean (the default), or exactly the mean. */+ jitter?: boolean+}++/** When an actor acts, in ms from the start of the load. Planned up front, so a slow reply never changes the plan. */+export function schedule(rng: Random, { meanMs, durationMs, offsetMs, jitter = true }: ScheduleOptions): number[] {+ const times: number[] = []+ for (let at = offsetMs; at < durationMs; at += jitter ? Math.round(meanMs * (0.5 + rng.next())) : meanMs) times.push(at)+ return times+}++const VOCABULARY = ['build', 'review', 'merge', 'check', 'agent', 'group', 'swarm', 'state', 'part', 'store', 'cursor', 'poll',+ 'machine', 'delivery', 'native', 'turn', 'brief', 'result', 'evidence', 'test', 'branch', 'commit', 'fix', 'plan']++/** Text of exactly [length] characters, so seeded briefs and results give the state a realistic size. */+export function words(rng: Random, length: number): string {+ let text = ''+ while (text.length < length) text += `${rng.pick(VOCABULARY)} `+ return text.slice(0, length)+}diff --git a/backend/integration/bench/report.ts b/backend/integration/bench/report.tsnew file mode 100644index 000000000..a5e4ab782--- /dev/null+++ b/backend/integration/bench/report.ts@@ -0,0 +1,70 @@+import type { BenchConfig } from './config.js'+import type { Row, WriterRow } from './metrics.js'+import type { IsolatedPoll } from './probe.js'++export interface Size { bytes: number; documents: number }++export interface BenchReport {+ benchmark: 'swarm-state'+ version: 1+ driver: string+ startedAt: string+ commit: { sha: string; dirty: boolean } | null+ machine: { platform: string; release: string; arch: string; cpu: string; cpus: number; memoryGb: number; node: string; mongo: string }+ config: BenchConfig+ /** plan.ts planDigest: the same in two reports when both ran the same planned work. */+ planDigest: string+ setup: { ms: number; calls: number; workers: number; activeGroups: number; doneGroups: number }+ load: { plannedMs: number; actualMs: number; skipped: Record<string, number>; ops: Row[]; writerKinds: Row[]; writers: WriterRow[]; readers: Row[] }+ state: { afterSetup: Size; afterLoad: Size }+ isolatedPolls: IsolatedPoll[]+}++const ms = (value: number | null) => value === null ? '–' : value.toFixed(1)+const kb = (bytes: number) => (bytes / 1024).toFixed(1)+const errors = (row: Row) => Object.entries(row.errors).map(([code, n]) => `${code} ${n}`).join(', ') || '0'++function table(header: string[], rows: string[][]): string {+ return [`| ${header.join(' | ')} |`, `|${header.map(() => '---').join('|')}|`, ...rows.map(r => `| ${r.join(' | ')} |`)].join('\n')+}++const CALL_HEADER = ['Calls', 'OK', 'Failed attempts (conflicts)', 'Calls retried', 'SWARM_BUSY', 'Other errors', 'p50 ms', 'p95 ms', 'max ms']+const callCells = (row: Row) => [row.count, row.ok, row.conflicts, row.retriedCalls, row.swarmBusy].map(String)+ .concat([errors(row), ms(row.p50Ms), ms(row.p95Ms), ms(row.maxMs)])++/** The report people read: one table per question the #1726 goals ask. */+export function renderMarkdown(report: BenchReport): string {+ const { config, setup, load, state } = report+ const run = [+ ['Driver', report.driver], ['Commit', report.commit ? `${report.commit.sha}${report.commit.dirty ? ' (uncommitted changes)' : ''}` : 'unknown'],+ ['Started', report.startedAt],+ ['Machine', `${report.machine.cpu}, ${report.machine.cpus} cores, ${report.machine.memoryGb} GB, ${report.machine.platform} ${report.machine.release} ${report.machine.arch}`],+ ['Runtime', `Node ${report.machine.node}, MongoDB ${report.machine.mongo} (local single-node replica set)`],+ ['Lane', config.lane === 'cross-group' ? 'cross-group (one writer per group: no Lead messages, no delivery passes)' : 'mixed'],+ ['Seed', String(config.seed)], ['Plan', `sha256 ${report.planDigest.slice(0, 16)}`],+ ['Swarm', `${config.groups} groups (${setup.doneGroups} done, ${setup.activeGroups} active), ${setup.workers} workers and a Lead, ${config.machines} machines`],+ ['Readers', `${config.desktopReaders} Desktop every ${config.every.desktopPollMs} ms, ${config.hostReaders} hosts every ${config.every.hostTickMs} ms`],+ ['Cadence', Object.entries(config.every).map(([k, v]) => `${k} ${v}`).join(', ')],+ ['Worker mix', Object.entries(config.mix).map(([k, v]) => `${k} ${v}`).join(', ')],+ ['Setup', `${setup.calls} calls in ${(setup.ms / 1000).toFixed(1)} s`],+ ['Load', `planned ${(load.plannedMs / 1000).toFixed(0)} s, ran ${(load.actualMs / 1000).toFixed(1)} s`],+ ['Skipped', Object.entries(load.skipped).map(([k, v]) => `${k} ${v}`).join(', ') || 'none'],+ ]+ return [+ `# Swarm state benchmark (${report.driver})`, '',+ '## Run', '', table(['', ''], run), '',+ '## Operations', '', 'Every call during the load, by operation. A failed attempt is one database transaction the store retried (write conflict P2034, or a transient error); SWARM_BUSY is a call that ran out of retries.', '',+ table(['Operation', ...CALL_HEADER], load.ops.map(row => [row.key, ...callCells(row)])), '',+ '## Writer kinds', '', 'Every call by kind of writer: workers (posts in their groups), terminals (turns recorded in their groups), machines (reports), delivery (each host\'s delivery passes), the Lead, and the Desktop and host readers.', '',+ table(['Kind', ...CALL_HEADER], load.writerKinds.map(row => [row.key, ...callCells(row)])), '',+ '## Writers', '', table(['Writer', ...CALL_HEADER], load.writers.map(row => [row.key, ...callCells(row)])), '',+ '## Readers', '', 'Bytes are response bodies during the load. The isolated poll runs once each after the load, alone, and counts what MongoDB sent the backend for it.', '',+ table(['Reader', 'Polls', 'p50 ms', 'p95 ms', 'Mean KB', 'p95 KB', 'Isolated: response KB', 'Isolated: database KB'], load.readers.map(row => {+ const alone = report.isolatedPolls.find(p => p.reader === row.key)+ return [row.key, String(row.count), ms(row.p50Ms), ms(row.p95Ms), row.bytes ? kb(row.bytes.mean) : '–', row.bytes ? kb(row.bytes.p95) : '–',+ alone ? kb(alone.responseBytes) : '–', alone ? kb(alone.databaseBytesOut) : '–']+ })), '',+ '## State', '', table(['When', 'Documents', 'KB'], [+ ['After setup', String(state.afterSetup.documents), kb(state.afterSetup.bytes)], ['After the load', String(state.afterLoad.documents), kb(state.afterLoad.bytes)]]), '',+ ].join('\n')+}diff --git a/backend/integration/bench/results/.gitignore b/backend/integration/bench/results/.gitignorenew file mode 100644index 000000000..d093b6c63--- /dev/null+++ b/backend/integration/bench/results/.gitignore@@ -0,0 +1,5 @@+# Runs land here. Only the committed baselines (main) and results (the integration branch) are kept in git.+*+!.gitignore+!baseline-*.json+!results-*.jsondiff --git a/backend/integration/bench/results/baseline-main-0d3485bad-cross-group.json b/backend/integration/bench/results/baseline-main-0d3485bad-cross-group.jsonnew file mode 100644index 000000000..062bfb5c0--- /dev/null+++ b/backend/integration/bench/results/baseline-main-0d3485bad-cross-group.json@@ -0,0 +1,1172 @@+{+ "benchmark": "swarm-state",+ "version": 1,+ "driver": "legacy",+ "startedAt": "2026-10-26T11:35:05.409Z",+ "commit": {+ "sha": "b71522ab633a1881e5390f81da9b854e0a1e9778",+ "dirty": false+ },+ "machine": {+ "platform": "darwin",+ "release": "25.6.0",+ "arch": "arm64",+ "cpu": "Apple M1 Max",+ "cpus": 10,+ "memoryGb": 64,+ "node": "24.18.0",+ "mongo": "7.0.24"+ },+ "config": {+ "seed": 1726,+ "groups": 200,+ "doneShare": 0.9,+ "workers": 20,+ "lane": "cross-group",+ "machines": 6,+ "durationMs": 120000,+ "desktopReaders": 3,+ "hostReaders": 2,+ "mix": {+ "message.send": 2,+ "work.status": 1,+ "work.check": 1+ },+ "every": {+ "workerPostMs": 4000,+ "leadSendMs": 5000,+ "nativeTurnMs": 10000,+ "observeMs": 15000,+ "deliveryPassMs": 3000,+ "desktopPollMs": 3000,+ "hostTickMs": 1000+ },+ "text": {+ "briefChars": 3000,+ "resultChars": 600,+ "messageChars": 300+ }+ },+ "planDigest": "575e841eb53ecf495233ccc04f807dcd3f38db7efde2c269a11b21d83f79b1cf",+ "setup": {+ "ms": 59092.144208,+ "calls": 1178,+ "workers": 20,+ "activeGroups": 20,+ "doneGroups": 180+ },+ "load": {+ "plannedMs": 120000,+ "actualMs": 120128.96350000001,+ "skipped": {+ "native answers": 2+ },+ "ops": [+ {+ "key": "message.send",+ "count": 313,+ "ok": 310,+ "conflicts": 361,+ "retriedCalls": 160,+ "swarmBusy": 3,+ "errors": {},+ "p50Ms": 120.81566600000951,+ "p95Ms": 1023.1834169999929,+ "maxMs": 3103.047500000015,+ "bytes": null+ },+ {+ "key": "native.append",+ "count": 470,+ "ok": 465,+ "conflicts": 433,+ "retriedCalls": 168,+ "swarmBusy": 5,+ "errors": {},+ "p50Ms": 76.98391700000502,+ "p95Ms": 1174.347959000006,+ "maxMs": 3755.792459000004,+ "bytes": null+ },+ {+ "key": "observeMachine",+ "count": 48,+ "ok": 48,+ "conflicts": 37,+ "retriedCalls": 20,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 66.31970800002455,+ "p95Ms": 371.2342499999795,+ "maxMs": 958.7901249999995,+ "bytes": null+ },+ {+ "key": "read.desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 26.054332999992766,+ "p95Ms": 39.70120799999859,+ "maxMs": 70.84629199998744,+ "bytes": {+ "mean": 1047734,+ "p50": 1049429,+ "p95": 1052343,+ "total": 125728132+ }+ },+ {+ "key": "read.host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 32.77799999999115,+ "p95Ms": 54.56220800001756,+ "maxMs": 80.97658299998147,+ "bytes": {+ "mean": 4691,+ "p50": 4177,+ "p95": 5205,+ "total": 1125840+ }+ },+ {+ "key": "work.check",+ "count": 128,+ "ok": 128,+ "conflicts": 122,+ "retriedCalls": 58,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 74.20816599999671,+ "p95Ms": 744.6922499999928,+ "maxMs": 1916.6312500000058,+ "bytes": null+ },+ {+ "key": "work.status",+ "count": 155,+ "ok": 153,+ "conflicts": 122,+ "retriedCalls": 67,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 79.15099999999802,+ "p95Ms": 473.0610410000081,+ "maxMs": 3377.003500000006,+ "bytes": null+ }+ ],+ "writerKinds": [+ {+ "key": "desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 26.054332999992766,+ "p95Ms": 39.70120799999859,+ "maxMs": 70.84629199998744,+ "bytes": {+ "mean": 1047734,+ "p50": 1049429,+ "p95": 1052343,+ "total": 125728132+ }+ },+ {+ "key": "host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 32.77799999999115,+ "p95Ms": 54.56220800001756,+ "maxMs": 80.97658299998147,+ "bytes": {+ "mean": 4691,+ "p50": 4177,+ "p95": 5205,+ "total": 1125840+ }+ },+ {+ "key": "machine",+ "count": 48,+ "ok": 48,+ "conflicts": 37,+ "retriedCalls": 20,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 66.31970800002455,+ "p95Ms": 371.2342499999795,+ "maxMs": 958.7901249999995,+ "bytes": null+ },+ {+ "key": "terminal",+ "count": 470,+ "ok": 465,+ "conflicts": 433,+ "retriedCalls": 168,+ "swarmBusy": 5,+ "errors": {},+ "p50Ms": 76.98391700000502,+ "p95Ms": 1174.347959000006,+ "maxMs": 3755.792459000004,+ "bytes": null+ },+ {+ "key": "worker",+ "count": 596,+ "ok": 591,+ "conflicts": 605,+ "retriedCalls": 285,+ "swarmBusy": 5,+ "errors": {},+ "p50Ms": 91.3065409999981,+ "p95Ms": 825.4736249999842,+ "maxMs": 3377.003500000006,+ "bytes": null+ }+ ],+ "writers": [+ {+ "key": "machine-0",+ "count": 8,+ "ok": 8,+ "conflicts": 5,+ "retriedCalls": 3,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 61.44354199999361,+ "p95Ms": 314.75754099999904,+ "maxMs": 314.75754099999904,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-1",+ "count": 8,+ "ok": 8,+ "conflicts": 4,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 59.36545800001477,+ "p95Ms": 958.7901249999995,+ "maxMs": 958.7901249999995,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-2",+ "count": 8,+ "ok": 8,+ "conflicts": 10,+ "retriedCalls": 5,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 156.52687500001048,+ "p95Ms": 388.6226250000036,+ "maxMs": 388.6226250000036,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-3",+ "count": 8,+ "ok": 8,+ "conflicts": 8,+ "retriedCalls": 4,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 65.0358750000014,+ "p95Ms": 371.2342499999795,+ "maxMs": 371.2342499999795,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-4",+ "count": 8,+ "ok": 8,+ "conflicts": 3,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 65.8251670000027,+ "p95Ms": 256.9096669999999,+ "maxMs": 256.9096669999999,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-5",+ "count": 8,+ "ok": 8,+ "conflicts": 7,+ "retriedCalls": 5,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 120.88850000000093,+ "p95Ms": 281.2715829999943,+ "maxMs": 281.2715829999943,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "terminal-00",+ "count": 22,+ "ok": 21,+ "conflicts": 25,+ "retriedCalls": 10,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 96.5470420000056,+ "p95Ms": 610.4179160000058,+ "maxMs": 2849.077541999999,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-01",+ "count": 20,+ "ok": 20,+ "conflicts": 14,+ "retriedCalls": 8,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 76.98391700000502,+ "p95Ms": 363.2027919999964,+ "maxMs": 914.0202920000011,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-02",+ "count": 23,+ "ok": 22,+ "conflicts": 30,+ "retriedCalls": 9,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 78.67341600000509,+ "p95Ms": 1179.3570409999957,+ "maxMs": 3174.8524170000164,+ "bytes": null,+ "byOp": {+ "native.append": 23+ }+ },+ {+ "key": "terminal-03",+ "count": 22,+ "ok": 22,+ "conflicts": 15,+ "retriedCalls": 6,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 71.22433300002012,+ "p95Ms": 617.7004579999921,+ "maxMs": 937.1571249999979,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-04",+ "count": 22,+ "ok": 22,+ "conflicts": 15,+ "retriedCalls": 8,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 71.51087500000722,+ "p95Ms": 338.30137499999546,+ "maxMs": 613.5025840000017,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-05",+ "count": 24,+ "ok": 24,+ "conflicts": 28,+ "retriedCalls": 10,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 80.834291999985,+ "p95Ms": 1224.5661669999972,+ "maxMs": 1565.5097909999895,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-06",+ "count": 25,+ "ok": 24,+ "conflicts": 22,+ "retriedCalls": 7,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 68.56204200000502,+ "p95Ms": 1398.7310409999918,+ "maxMs": 2445.160208999994,+ "bytes": null,+ "byOp": {+ "native.append": 25+ }+ },+ {+ "key": "terminal-07",+ "count": 22,+ "ok": 22,+ "conflicts": 17,+ "retriedCalls": 9,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 78.46470800001407,+ "p95Ms": 509.6628330000094,+ "maxMs": 527.8924589999951,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-08",+ "count": 24,+ "ok": 23,+ "conflicts": 30,+ "retriedCalls": 10,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 82.92379200000141,+ "p95Ms": 2968.23275000001,+ "maxMs": 3755.792459000004,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-09",+ "count": 24,+ "ok": 24,+ "conflicts": 12,+ "retriedCalls": 5,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 70.08624999999302,+ "p95Ms": 721.1360000000132,+ "maxMs": 1305.8627080000006,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-10",+ "count": 28,+ "ok": 28,+ "conflicts": 34,+ "retriedCalls": 11,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 86.63291700000991,+ "p95Ms": 1458.3123750000086,+ "maxMs": 2996.826709000001,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "terminal-11",+ "count": 26,+ "ok": 25,+ "conflicts": 32,+ "retriedCalls": 9,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 78.29816700000083,+ "p95Ms": 2840.1407499999914,+ "maxMs": 3416.5272089999926,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-12",+ "count": 24,+ "ok": 24,+ "conflicts": 14,+ "retriedCalls": 7,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 80.36804200001643,+ "p95Ms": 395.82445899999584,+ "maxMs": 818.822417000003,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-13",+ "count": 22,+ "ok": 22,+ "conflicts": 21,+ "retriedCalls": 8,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 80.88470900000539,+ "p95Ms": 1685.1872920000023,+ "maxMs": 3561.9487079999963,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-14",+ "count": 28,+ "ok": 28,+ "conflicts": 24,+ "retriedCalls": 10,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 72.41358300000138,+ "p95Ms": 899.9398330000113,+ "maxMs": 1200.2474159999983,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "terminal-15",+ "count": 22,+ "ok": 22,+ "conflicts": 8,+ "retriedCalls": 5,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 69.80783299999894,+ "p95Ms": 164.7476659999811,+ "maxMs": 891.3787079999893,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-16",+ "count": 22,+ "ok": 22,+ "conflicts": 15,+ "retriedCalls": 6,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 67.20508299999346,+ "p95Ms": 561.8045830000192,+ "maxMs": 628.5534590000025,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-17",+ "count": 22,+ "ok": 22,+ "conflicts": 18,+ "retriedCalls": 7,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 66.25816599998507,+ "p95Ms": 723.9640829999989,+ "maxMs": 1412.3087080000114,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-18",+ "count": 20,+ "ok": 20,+ "conflicts": 24,+ "retriedCalls": 8,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 70.55074999999488,+ "p95Ms": 1273.5819999999949,+ "maxMs": 1900.8990410000115,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-19",+ "count": 28,+ "ok": 28,+ "conflicts": 35,+ "retriedCalls": 15,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 123.50579200001084,+ "p95Ms": 1912.9238749999931,+ "maxMs": 2014.8057919999992,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "worker-00",+ "count": 29,+ "ok": 29,+ "conflicts": 20,+ "retriedCalls": 12,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 68.40429200000654,+ "p95Ms": 629.6783750000031,+ "maxMs": 682.3922499999899,+ "bytes": null,+ "byOp": {+ "work.status": 10,+ "work.check": 7,+ "message.send": 12+ }+ },+ {+ "key": "worker-01",+ "count": 28,+ "ok": 28,+ "conflicts": 33,+ "retriedCalls": 17,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 135.18337499999325,+ "p95Ms": 1279.9623750000028,+ "maxMs": 2295.914417000022,+ "bytes": null,+ "byOp": {+ "work.status": 5,+ "message.send": 13,+ "work.check": 10+ }+ },+ {+ "key": "worker-02",+ "count": 29,+ "ok": 29,+ "conflicts": 31,+ "retriedCalls": 14,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 78.0087499999936,+ "p95Ms": 911.7958750000107,+ "maxMs": 3235.876375000007,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 10,+ "work.check": 3+ }+ },+ {+ "key": "worker-03",+ "count": 30,+ "ok": 30,+ "conflicts": 40,+ "retriedCalls": 18,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 142.71504199999617,+ "p95Ms": 997.0675420000043,+ "maxMs": 1026.2655419999937,+ "bytes": null,+ "byOp": {+ "message.send": 18,+ "work.check": 9,+ "work.status": 3+ }+ },+ {+ "key": "worker-04",+ "count": 31,+ "ok": 30,+ "conflicts": 34,+ "retriedCalls": 14,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 79.740541999985,+ "p95Ms": 909.7163750000036,+ "maxMs": 3334.3642500000133,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 11,+ "work.check": 5+ }+ },+ {+ "key": "worker-05",+ "count": 32,+ "ok": 32,+ "conflicts": 20,+ "retriedCalls": 13,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 75.20175000000745,+ "p95Ms": 370.43683299999975,+ "maxMs": 402.20158400000946,+ "bytes": null,+ "byOp": {+ "message.send": 14,+ "work.status": 10,+ "work.check": 8+ }+ },+ {+ "key": "worker-06",+ "count": 30,+ "ok": 30,+ "conflicts": 22,+ "retriedCalls": 10,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 71.8770829999994,+ "p95Ms": 550.8658750000031,+ "maxMs": 602.202249999973,+ "bytes": null,+ "byOp": {+ "message.send": 19,+ "work.status": 7,+ "work.check": 4+ }+ },+ {+ "key": "worker-07",+ "count": 29,+ "ok": 28,+ "conflicts": 39,+ "retriedCalls": 17,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 125.62191700001131,+ "p95Ms": 825.4736249999842,+ "maxMs": 3103.047500000015,+ "bytes": null,+ "byOp": {+ "message.send": 11,+ "work.check": 7,+ "work.status": 11+ }+ },+ {+ "key": "worker-08",+ "count": 31,+ "ok": 31,+ "conflicts": 25,+ "retriedCalls": 11,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 72.17695799999638,+ "p95Ms": 585.8123750000086,+ "maxMs": 1440.0054579999996,+ "bytes": null,+ "byOp": {+ "work.status": 7,+ "message.send": 15,+ "work.check": 9+ }+ },+ {+ "key": "worker-09",+ "count": 31,+ "ok": 31,+ "conflicts": 23,+ "retriedCalls": 14,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 78.13658399999258,+ "p95Ms": 444.16762499997276,+ "maxMs": 1122.185083000004,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 11,+ "work.status": 7+ }+ },+ {+ "key": "worker-10",+ "count": 33,+ "ok": 33,+ "conflicts": 29,+ "retriedCalls": 13,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 79.93300000001909,+ "p95Ms": 899.0219170000055,+ "maxMs": 1029.471000000005,+ "bytes": null,+ "byOp": {+ "message.send": 17,+ "work.check": 7,+ "work.status": 9+ }+ },+ {+ "key": "worker-11",+ "count": 29,+ "ok": 29,+ "conflicts": 28,+ "retriedCalls": 19,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 143.44874999998137,+ "p95Ms": 342.16049999999814,+ "maxMs": 1350.7582919999986,+ "bytes": null,+ "byOp": {+ "work.check": 4,+ "work.status": 5,+ "message.send": 20+ }+ },+ {+ "key": "worker-12",+ "count": 31,+ "ok": 31,+ "conflicts": 32,+ "retriedCalls": 13,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 73.73924999998417,+ "p95Ms": 1318.0842499999853,+ "maxMs": 1352.0725000000093,+ "bytes": null,+ "byOp": {+ "work.status": 8,+ "message.send": 15,+ "work.check": 8+ }+ },+ {+ "key": "worker-13",+ "count": 27,+ "ok": 27,+ "conflicts": 30,+ "retriedCalls": 13,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 91.78891600000497,+ "p95Ms": 845.5444999999891,+ "maxMs": 1279.1974999999948,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 8,+ "work.check": 4+ }+ },+ {+ "key": "worker-14",+ "count": 29,+ "ok": 29,+ "conflicts": 24,+ "retriedCalls": 15,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 110.09379199999967,+ "p95Ms": 478.3904579999944,+ "maxMs": 673.6472499999945,+ "bytes": null,+ "byOp": {+ "work.check": 5,+ "message.send": 17,+ "work.status": 7+ }+ },+ {+ "key": "worker-15",+ "count": 30,+ "ok": 29,+ "conflicts": 48,+ "retriedCalls": 14,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 99.95112499999232,+ "p95Ms": 1916.6312500000058,+ "maxMs": 3377.003500000006,+ "bytes": null,+ "byOp": {+ "work.status": 6,+ "message.send": 17,+ "work.check": 7+ }+ },+ {+ "key": "worker-16",+ "count": 30,+ "ok": 29,+ "conflicts": 51,+ "retriedCalls": 16,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 148.82129200000782,+ "p95Ms": 1806.2677079999994,+ "maxMs": 2894.7078330000077,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 8,+ "work.check": 6+ }+ },+ {+ "key": "worker-17",+ "count": 29,+ "ok": 29,+ "conflicts": 25,+ "retriedCalls": 18,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 130.50033299998904,+ "p95Ms": 378.9470830000064,+ "maxMs": 422.24854200001573,+ "bytes": null,+ "byOp": {+ "message.send": 20,+ "work.check": 4,+ "work.status": 5+ }+ },+ {+ "key": "worker-18",+ "count": 31,+ "ok": 30,+ "conflicts": 40,+ "retriedCalls": 16,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 133.6583329999994,+ "p95Ms": 1475.2338330000057,+ "maxMs": 2119.4416250000068,+ "bytes": null,+ "byOp": {+ "work.status": 11,+ "message.send": 17,+ "work.check": 3+ }+ },+ {+ "key": "worker-19",+ "count": 27,+ "ok": 27,+ "conflicts": 11,+ "retriedCalls": 8,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 67.22054099998786,+ "p95Ms": 316.7227910000074,+ "maxMs": 327.7261249999865,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 7,+ "work.status": 7+ }+ }+ ],+ "readers": [+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 25.296915999992052,+ "p95Ms": 39.70120799999859,+ "maxMs": 51.94608299998799,+ "bytes": {+ "mean": 1047717,+ "p50": 1049429,+ "p95": 1052343,+ "total": 41908687+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 26.336458000005223,+ "p95Ms": 33.82612500002142,+ "maxMs": 40.9632910000073,+ "bytes": {+ "mean": 1047622,+ "p50": 1049429,+ "p95": 1052342,+ "total": 41904883+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 27.03979199999594,+ "p95Ms": 41.85879100000602,+ "maxMs": 70.84629199998744,+ "bytes": {+ "mean": 1047864,+ "p50": 1049427,+ "p95": 1052370,+ "total": 41914562+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "host:bench-machine-0",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.08299999999872,+ "p95Ms": 65.35700000000361,+ "maxMs": 80.97658299998147,+ "bytes": {+ "mean": 5205,+ "p50": 5205,+ "p95": 5205,+ "total": 624600+ },+ "byOp": {+ "read.host": 120+ }+ },+ {+ "key": "host:bench-machine-1",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 32.4922910000023,+ "p95Ms": 50.40116599999601,+ "maxMs": 77.38820799998939,+ "bytes": {+ "mean": 4177,+ "p50": 4177,+ "p95": 4177,+ "total": 501240+ },+ "byOp": {+ "read.host": 120+ }+ }+ ]+ },+ "state": {+ "afterSetup": {+ "bytes": 1038794,+ "documents": 1+ },+ "afterLoad": {+ "bytes": 1062261,+ "documents": 1+ }+ },+ "isolatedPolls": [+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 1052372,+ "databaseBytesOut": 1063247,+ "ms": 26.446832999994513+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 1052372,+ "databaseBytesOut": 1063247,+ "ms": 24.90837499999907+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 1052372,+ "databaseBytesOut": 1063247,+ "ms": 24.365125000011176+ },+ {+ "reader": "host:bench-machine-0",+ "responseBytes": 5205,+ "databaseBytesOut": 1066832,+ "ms": 37.86504100001184+ },+ {+ "reader": "host:bench-machine-1",+ "responseBytes": 4177,+ "databaseBytesOut": 1066334,+ "ms": 44.95941699997638+ }+ ]+}diff --git a/backend/integration/bench/results/baseline-main-0d3485bad-hot.json b/backend/integration/bench/results/baseline-main-0d3485bad-hot.jsonnew file mode 100644index 000000000..2f9ca9a33--- /dev/null+++ b/backend/integration/bench/results/baseline-main-0d3485bad-hot.json@@ -0,0 +1,1361 @@+{+ "benchmark": "swarm-state",+ "version": 1,+ "driver": "legacy",+ "startedAt": "2026-10-26T14:14:55.419Z",+ "commit": {+ "sha": "f53d296d860adc11412cd436152de3557a0dc582",+ "dirty": false+ },+ "machine": {+ "platform": "darwin",+ "release": "25.6.0",+ "arch": "arm64",+ "cpu": "Apple M1 Max",+ "cpus": 10,+ "memoryGb": 64,+ "node": "24.18.0",+ "mongo": "7.0.24"+ },+ "config": {+ "seed": 1726,+ "groups": 200,+ "doneShare": 0,+ "workers": 20,+ "lane": "mixed",+ "machines": 6,+ "durationMs": 120000,+ "desktopReaders": 3,+ "hostReaders": 2,+ "mix": {+ "message.send": 2,+ "work.status": 1,+ "work.check": 1+ },+ "every": {+ "workerPostMs": 4000,+ "leadSendMs": 5000,+ "nativeTurnMs": 10000,+ "observeMs": 15000,+ "deliveryPassMs": 3000,+ "desktopPollMs": 3000,+ "hostTickMs": 1000+ },+ "text": {+ "briefChars": 3000,+ "resultChars": 600,+ "messageChars": 300+ }+ },+ "planDigest": "d078610a00b2c6bf2a87229331f63d895d3fce756698240b8624d4b9e2cfcc63",+ "setup": {+ "ms": 14792.972709000001,+ "calls": 458,+ "workers": 20,+ "activeGroups": 200,+ "doneGroups": 0+ },+ "load": {+ "plannedMs": 120000,+ "actualMs": 121139.06654199999,+ "skipped": {+ "native answers": 14+ },+ "ops": [+ {+ "key": "deliveries.list",+ "count": 840,+ "ok": 840,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 16.100875000003725,+ "p95Ms": 35.19445799999812,+ "maxMs": 127.75433300000441,+ "bytes": null+ },+ {+ "key": "delivery.ack",+ "count": 515,+ "ok": 515,+ "conflicts": 32,+ "retriedCalls": 20,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 31.756208999999217,+ "p95Ms": 55.83133299999463,+ "maxMs": 672.3860419999983,+ "bytes": null+ },+ {+ "key": "delivery.claim",+ "count": 515,+ "ok": 515,+ "conflicts": 81,+ "retriedCalls": 47,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 32.68266700000095,+ "p95Ms": 112.18362500000512,+ "maxMs": 1066.4747079999943,+ "bytes": null+ },+ {+ "key": "message.send",+ "count": 339,+ "ok": 320,+ "conflicts": 752,+ "retriedCalls": 216,+ "swarmBusy": 19,+ "errors": {},+ "p50Ms": 133.1646250000049,+ "p95Ms": 2608.0745000000024,+ "maxMs": 4122.023166000006,+ "bytes": null+ },+ {+ "key": "native.append",+ "count": 458,+ "ok": 440,+ "conflicts": 675,+ "retriedCalls": 200,+ "swarmBusy": 18,+ "errors": {},+ "p50Ms": 57.97820800000045,+ "p95Ms": 2130.222333999991,+ "maxMs": 4337.327333000008,+ "bytes": null+ },+ {+ "key": "observeMachine",+ "count": 48,+ "ok": 44,+ "conflicts": 148,+ "retriedCalls": 31,+ "swarmBusy": 4,+ "errors": {},+ "p50Ms": 230.63308300000062,+ "p95Ms": 2698.082583999989,+ "maxMs": 3141.3579159999936,+ "bytes": null+ },+ {+ "key": "read.desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 18.638292000003275,+ "p95Ms": 29.31129100000544,+ "maxMs": 34.64533400000073,+ "bytes": {+ "mean": 788427,+ "p50": 790192,+ "p95": 793207,+ "total": 94611247+ }+ },+ {+ "key": "read.host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 24.149082999996608,+ "p95Ms": 43.586292000007234,+ "maxMs": 85.01333400000294,+ "bytes": {+ "mean": 4690,+ "p50": 4177,+ "p95": 5205,+ "total": 1125552+ }+ },+ {+ "key": "work.check",+ "count": 128,+ "ok": 118,+ "conflicts": 266,+ "retriedCalls": 81,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 120.22487499999988,+ "p95Ms": 2791.144333999997,+ "maxMs": 3785.385459000012,+ "bytes": null+ },+ {+ "key": "work.status",+ "count": 155,+ "ok": 150,+ "conflicts": 354,+ "retriedCalls": 101,+ "swarmBusy": 5,+ "errors": {},+ "p50Ms": 129.56762499999604,+ "p95Ms": 2507.8728330000013,+ "maxMs": 4091.6401659999974,+ "bytes": null+ }+ ],+ "writerKinds": [+ {+ "key": "delivery",+ "count": 1870,+ "ok": 1870,+ "conflicts": 113,+ "retriedCalls": 67,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 25.94999999999709,+ "p95Ms": 59.32970899999782,+ "maxMs": 1066.4747079999943,+ "bytes": null+ },+ {+ "key": "desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 18.638292000003275,+ "p95Ms": 29.31129100000544,+ "maxMs": 34.64533400000073,+ "bytes": {+ "mean": 788427,+ "p50": 790192,+ "p95": 793207,+ "total": 94611247+ }+ },+ {+ "key": "host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 24.149082999996608,+ "p95Ms": 43.586292000007234,+ "maxMs": 85.01333400000294,+ "bytes": {+ "mean": 4690,+ "p50": 4177,+ "p95": 5205,+ "total": 1125552+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 26,+ "conflicts": 57,+ "retriedCalls": 17,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 117.70870899999863,+ "p95Ms": 2617.5132500000036,+ "maxMs": 3744.858124999999,+ "bytes": null+ },+ {+ "key": "machine",+ "count": 48,+ "ok": 44,+ "conflicts": 148,+ "retriedCalls": 31,+ "swarmBusy": 4,+ "errors": {},+ "p50Ms": 230.63308300000062,+ "p95Ms": 2698.082583999989,+ "maxMs": 3141.3579159999936,+ "bytes": null+ },+ {+ "key": "terminal",+ "count": 458,+ "ok": 440,+ "conflicts": 675,+ "retriedCalls": 200,+ "swarmBusy": 18,+ "errors": {},+ "p50Ms": 57.97820800000045,+ "p95Ms": 2130.222333999991,+ "maxMs": 4337.327333000008,+ "bytes": null+ },+ {+ "key": "worker",+ "count": 596,+ "ok": 562,+ "conflicts": 1315,+ "retriedCalls": 381,+ "swarmBusy": 34,+ "errors": {},+ "p50Ms": 130.81195899999875,+ "p95Ms": 2523.502792000003,+ "maxMs": 4122.023166000006,+ "bytes": null+ }+ ],+ "writers": [+ {+ "key": "delivery-0",+ "count": 1162,+ "ok": 1162,+ "conflicts": 94,+ "retriedCalls": 55,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 31.02850000000035,+ "p95Ms": 78.80129200000374,+ "maxMs": 1066.4747079999943,+ "bytes": null,+ "byOp": {+ "deliveries.list": 200,+ "delivery.claim": 481,+ "delivery.ack": 481+ }+ },+ {+ "key": "delivery-1",+ "count": 172,+ "ok": 172,+ "conflicts": 2,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 16.453290999983437,+ "p95Ms": 30.236290999997436,+ "maxMs": 63.12437499999942,+ "bytes": null,+ "byOp": {+ "deliveries.list": 160,+ "delivery.claim": 6,+ "delivery.ack": 6+ }+ },+ {+ "key": "delivery-2",+ "count": 128,+ "ok": 128,+ "conflicts": 5,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 17.43920799999978,+ "p95Ms": 33.817457999997714,+ "maxMs": 839.4384579999969,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 4,+ "delivery.ack": 4+ }+ },+ {+ "key": "delivery-3",+ "count": 136,+ "ok": 136,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 17.904999999998836,+ "p95Ms": 37.904083000001265,+ "maxMs": 86.41874999999709,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 8,+ "delivery.ack": 8+ }+ },+ {+ "key": "delivery-4",+ "count": 144,+ "ok": 144,+ "conflicts": 10,+ "retriedCalls": 7,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 17.237291999990703,+ "p95Ms": 45.43841700000121,+ "maxMs": 185.3169170000001,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 12,+ "delivery.ack": 12+ }+ },+ {+ "key": "delivery-5",+ "count": 128,+ "ok": 128,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 15.158625000010943,+ "p95Ms": 31.072833999998693,+ "maxMs": 95.71724999999788,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 4,+ "delivery.ack": 4+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 26,+ "conflicts": 57,+ "retriedCalls": 17,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 117.70870899999863,+ "p95Ms": 2617.5132500000036,+ "maxMs": 3744.858124999999,+ "bytes": null,+ "byOp": {+ "message.send": 26+ }+ },+ {+ "key": "machine-0",+ "count": 8,+ "ok": 8,+ "conflicts": 24,+ "retriedCalls": 4,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.19595899999695,+ "p95Ms": 2529.475584,+ "maxMs": 2529.475584,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-1",+ "count": 8,+ "ok": 6,+ "conflicts": 46,+ "retriedCalls": 8,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 1675.7479579999927,+ "p95Ms": 3141.3579159999936,+ "maxMs": 3141.3579159999936,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-2",+ "count": 8,+ "ok": 8,+ "conflicts": 34,+ "retriedCalls": 7,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 844.4782500000001,+ "p95Ms": 2385.7434580000045,+ "maxMs": 2385.7434580000045,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-3",+ "count": 8,+ "ok": 7,+ "conflicts": 32,+ "retriedCalls": 8,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 393.9262500000041,+ "p95Ms": 3117.3853339999914,+ "maxMs": 3117.3853339999914,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-4",+ "count": 8,+ "ok": 8,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.45920800000022,+ "p95Ms": 123.07662499998696,+ "maxMs": 123.07662499998696,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-5",+ "count": 8,+ "ok": 7,+ "conflicts": 11,+ "retriedCalls": 3,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 40.88683299999684,+ "p95Ms": 2581.963458000002,+ "maxMs": 2581.963458000002,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "terminal-00",+ "count": 22,+ "ok": 22,+ "conflicts": 22,+ "retriedCalls": 8,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.90387500000361,+ "p95Ms": 985.449958000012,+ "maxMs": 1395.719459,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-01",+ "count": 20,+ "ok": 20,+ "conflicts": 26,+ "retriedCalls": 7,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.46204200000648,+ "p95Ms": 2132.0319999999992,+ "maxMs": 2220.242624999999,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-02",+ "count": 24,+ "ok": 24,+ "conflicts": 27,+ "retriedCalls": 11,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 55.97433300000557,+ "p95Ms": 1262.9003329999978,+ "maxMs": 2774.1752079999933,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-03",+ "count": 20,+ "ok": 18,+ "conflicts": 38,+ "retriedCalls": 9,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 60.32012499999837,+ "p95Ms": 2910.3882080000003,+ "maxMs": 4337.327333000008,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-04",+ "count": 22,+ "ok": 22,+ "conflicts": 20,+ "retriedCalls": 8,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.959124999993946,+ "p95Ms": 715.4802500000005,+ "maxMs": 1440.2097500000018,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-05",+ "count": 24,+ "ok": 23,+ "conflicts": 26,+ "retriedCalls": 12,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 77.07854199999565,+ "p95Ms": 844.9060419999878,+ "maxMs": 1652.1538750000036,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-06",+ "count": 25,+ "ok": 24,+ "conflicts": 22,+ "retriedCalls": 7,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 53.36183300000266,+ "p95Ms": 1161.952084000004,+ "maxMs": 2051.6026249999995,+ "bytes": null,+ "byOp": {+ "native.append": 25+ }+ },+ {+ "key": "terminal-07",+ "count": 21,+ "ok": 19,+ "conflicts": 50,+ "retriedCalls": 13,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 110.62283300000126,+ "p95Ms": 2775.495041000002,+ "maxMs": 2925.6296250000014,+ "bytes": null,+ "byOp": {+ "native.append": 21+ }+ },+ {+ "key": "terminal-08",+ "count": 24,+ "ok": 24,+ "conflicts": 31,+ "retriedCalls": 12,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 61.493500000000495,+ "p95Ms": 1336.5743330000041,+ "maxMs": 1551.0978340000001,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-09",+ "count": 22,+ "ok": 20,+ "conflicts": 57,+ "retriedCalls": 13,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 213.4035000000149,+ "p95Ms": 2899.504208000013,+ "maxMs": 3166.1113750000077,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-10",+ "count": 26,+ "ok": 23,+ "conflicts": 50,+ "retriedCalls": 11,+ "swarmBusy": 3,+ "errors": {},+ "p50Ms": 51.211708000002545,+ "p95Ms": 3070.8578329999873,+ "maxMs": 3187.5140419999952,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-11",+ "count": 26,+ "ok": 26,+ "conflicts": 30,+ "retriedCalls": 9,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.048583000025246,+ "p95Ms": 1172.3605000000025,+ "maxMs": 1373.7869160000118,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-12",+ "count": 24,+ "ok": 24,+ "conflicts": 26,+ "retriedCalls": 11,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 57.97820800000045,+ "p95Ms": 1878.5513749999955,+ "maxMs": 3542.2994999999937,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-13",+ "count": 22,+ "ok": 21,+ "conflicts": 30,+ "retriedCalls": 8,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 48.329291999994894,+ "p95Ms": 1818.742416000001,+ "maxMs": 1824.7536250000048,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-14",+ "count": 27,+ "ok": 26,+ "conflicts": 48,+ "retriedCalls": 12,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 73.39212499998393,+ "p95Ms": 1815.5611669999926,+ "maxMs": 3068.983500000002,+ "bytes": null,+ "byOp": {+ "native.append": 27+ }+ },+ {+ "key": "terminal-15",+ "count": 20,+ "ok": 18,+ "conflicts": 38,+ "retriedCalls": 9,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 51.80629200000112,+ "p95Ms": 2518.0773340000014,+ "maxMs": 3623.1529169999994,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-16",+ "count": 21,+ "ok": 20,+ "conflicts": 33,+ "retriedCalls": 11,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 101.87145900000178,+ "p95Ms": 1077.529416999998,+ "maxMs": 2120.7209169999987,+ "bytes": null,+ "byOp": {+ "native.append": 21+ }+ },+ {+ "key": "terminal-17",+ "count": 20,+ "ok": 18,+ "conflicts": 21,+ "retriedCalls": 5,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 51.27950000000419,+ "p95Ms": 2074.5575409999947,+ "maxMs": 3467.3286660000012,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-18",+ "count": 20,+ "ok": 20,+ "conflicts": 26,+ "retriedCalls": 9,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 61.61758400002145,+ "p95Ms": 1062.031084000002,+ "maxMs": 1264.7511249999952,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-19",+ "count": 28,+ "ok": 28,+ "conflicts": 54,+ "retriedCalls": 15,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 91.77258299999812,+ "p95Ms": 1584.6196249999994,+ "maxMs": 2546.1287079999893,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "worker-00",+ "count": 29,+ "ok": 27,+ "conflicts": 59,+ "retriedCalls": 17,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 110.91829200000211,+ "p95Ms": 2707.363874999999,+ "maxMs": 3346.9899589999986,+ "bytes": null,+ "byOp": {+ "work.status": 10,+ "work.check": 7,+ "message.send": 12+ }+ },+ {+ "key": "worker-01",+ "count": 28,+ "ok": 28,+ "conflicts": 53,+ "retriedCalls": 17,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 110.46137499999895,+ "p95Ms": 1591.5406249999942,+ "maxMs": 2686.2753340000054,+ "bytes": null,+ "byOp": {+ "work.status": 5,+ "message.send": 13,+ "work.check": 10+ }+ },+ {+ "key": "worker-02",+ "count": 29,+ "ok": 28,+ "conflicts": 68,+ "retriedCalls": 20,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 154.33687500000087,+ "p95Ms": 1688.3124169999792,+ "maxMs": 2302.8929999999964,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 10,+ "work.check": 3+ }+ },+ {+ "key": "worker-03",+ "count": 30,+ "ok": 25,+ "conflicts": 91,+ "retriedCalls": 24,+ "swarmBusy": 5,+ "errors": {},+ "p50Ms": 230.47704100000556,+ "p95Ms": 3468.9310840000107,+ "maxMs": 3686.5655000000115,+ "bytes": null,+ "byOp": {+ "message.send": 18,+ "work.check": 9,+ "work.status": 3+ }+ },+ {+ "key": "worker-04",+ "count": 31,+ "ok": 29,+ "conflicts": 58,+ "retriedCalls": 14,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 49.7791670000006,+ "p95Ms": 2238.1924160000053,+ "maxMs": 2488.3463340000017,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 11,+ "work.check": 5+ }+ },+ {+ "key": "worker-05",+ "count": 32,+ "ok": 30,+ "conflicts": 67,+ "retriedCalls": 21,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 119.15991700001177,+ "p95Ms": 2155.442458000005,+ "maxMs": 3673.010666999995,+ "bytes": null,+ "byOp": {+ "message.send": 14,+ "work.status": 10,+ "work.check": 8+ }+ },+ {+ "key": "worker-06",+ "count": 30,+ "ok": 29,+ "conflicts": 69,+ "retriedCalls": 21,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 185.0560420000038,+ "p95Ms": 2608.0745000000024,+ "maxMs": 2929.716999999997,+ "bytes": null,+ "byOp": {+ "message.send": 19,+ "work.status": 7,+ "work.check": 4+ }+ },+ {+ "key": "worker-07",+ "count": 29,+ "ok": 27,+ "conflicts": 53,+ "retriedCalls": 16,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 103.17195800000627,+ "p95Ms": 1133.1201250000013,+ "maxMs": 3156.0604590000003,+ "bytes": null,+ "byOp": {+ "message.send": 11,+ "work.check": 7,+ "work.status": 11+ }+ },+ {+ "key": "worker-08",+ "count": 31,+ "ok": 29,+ "conflicts": 63,+ "retriedCalls": 18,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 101.10366700000304,+ "p95Ms": 2345.8228329999984,+ "maxMs": 3195.7378329999992,+ "bytes": null,+ "byOp": {+ "work.status": 7,+ "message.send": 15,+ "work.check": 9+ }+ },+ {+ "key": "worker-09",+ "count": 31,+ "ok": 28,+ "conflicts": 78,+ "retriedCalls": 18,+ "swarmBusy": 3,+ "errors": {},+ "p50Ms": 131.3617090000189,+ "p95Ms": 2845.762041999995,+ "maxMs": 3155.140625,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 11,+ "work.status": 7+ }+ },+ {+ "key": "worker-10",+ "count": 33,+ "ok": 31,+ "conflicts": 86,+ "retriedCalls": 23,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 183.61350000000675,+ "p95Ms": 2700.033749999988,+ "maxMs": 3314.430165999991,+ "bytes": null,+ "byOp": {+ "message.send": 17,+ "work.check": 7,+ "work.status": 9+ }+ },+ {+ "key": "worker-11",+ "count": 29,+ "ok": 29,+ "conflicts": 58,+ "retriedCalls": 23,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 124.7777919999935,+ "p95Ms": 1633.0097090000054,+ "maxMs": 2316.904666999999,+ "bytes": null,+ "byOp": {+ "work.check": 4,+ "work.status": 5,+ "message.send": 20+ }+ },+ {+ "key": "worker-12",+ "count": 31,+ "ok": 30,+ "conflicts": 55,+ "retriedCalls": 19,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 118.70075000000361,+ "p95Ms": 1920.3758329999982,+ "maxMs": 2984.3881249999977,+ "bytes": null,+ "byOp": {+ "work.status": 8,+ "message.send": 15,+ "work.check": 8+ }+ },+ {+ "key": "worker-13",+ "count": 27,+ "ok": 27,+ "conflicts": 37,+ "retriedCalls": 15,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 100.21125000000029,+ "p95Ms": 959.3403749999998,+ "maxMs": 1422.5223339999939,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 8,+ "work.check": 4+ }+ },+ {+ "key": "worker-14",+ "count": 29,+ "ok": 25,+ "conflicts": 73,+ "retriedCalls": 18,+ "swarmBusy": 4,+ "errors": {},+ "p50Ms": 187.87774999999965,+ "p95Ms": 2957.116915999999,+ "maxMs": 3084.4600409999985,+ "bytes": null,+ "byOp": {+ "work.check": 5,+ "message.send": 17,+ "work.status": 7+ }+ },+ {+ "key": "worker-15",+ "count": 30,+ "ok": 27,+ "conflicts": 105,+ "retriedCalls": 22,+ "swarmBusy": 3,+ "errors": {},+ "p50Ms": 256.89774999999645,+ "p95Ms": 2523.502792000003,+ "maxMs": 3785.385459000012,+ "bytes": null,+ "byOp": {+ "work.status": 6,+ "message.send": 17,+ "work.check": 7+ }+ },+ {+ "key": "worker-16",+ "count": 30,+ "ok": 29,+ "conflicts": 66,+ "retriedCalls": 19,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 124.48729200000525,+ "p95Ms": 2676.7655000000086,+ "maxMs": 3650.2045,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 8,+ "work.check": 6+ }+ },+ {+ "key": "worker-17",+ "count": 29,+ "ok": 28,+ "conflicts": 55,+ "retriedCalls": 19,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 123.17454199999338,+ "p95Ms": 2159.9652080000087,+ "maxMs": 4122.023166000006,+ "bytes": null,+ "byOp": {+ "message.send": 20,+ "work.check": 4,+ "work.status": 5+ }+ },+ {+ "key": "worker-18",+ "count": 31,+ "ok": 30,+ "conflicts": 68,+ "retriedCalls": 21,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 133.5604170000006,+ "p95Ms": 3827.7874999999913,+ "maxMs": 4091.6401659999974,+ "bytes": null,+ "byOp": {+ "work.status": 11,+ "message.send": 17,+ "work.check": 3+ }+ },+ {+ "key": "worker-19",+ "count": 27,+ "ok": 26,+ "conflicts": 53,+ "retriedCalls": 16,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 119.30591699999059,+ "p95Ms": 2791.144333999997,+ "maxMs": 3395.713459000006,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 7,+ "work.status": 7+ }+ }+ ],+ "readers": [+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 18.340457999991486,+ "p95Ms": 28.089749999999185,+ "maxMs": 33.4543330000015,+ "bytes": {+ "mean": 788376,+ "p50": 790192,+ "p95": 793208,+ "total": 31535051+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 17.609249999994063,+ "p95Ms": 25.402625000002445,+ "maxMs": 33.76470800000243,+ "bytes": {+ "mean": 788312,+ "p50": 790192,+ "p95": 793205,+ "total": 31532494+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 19.267124999998487,+ "p95Ms": 30.665791999999783,+ "maxMs": 34.64533400000073,+ "bytes": {+ "mean": 788593,+ "p50": 790165,+ "p95": 793209,+ "total": 31543702+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "host:bench-machine-0",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 23.722083000000566,+ "p95Ms": 43.586292000007234,+ "maxMs": 85.01333400000294,+ "bytes": {+ "mean": 5204,+ "p50": 5205,+ "p95": 5205,+ "total": 624440+ },+ "byOp": {+ "read.host": 120+ }+ },+ {+ "key": "host:bench-machine-1",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 24.20324999999866,+ "p95Ms": 43.020833999995375,+ "maxMs": 60.212083000005805,+ "bytes": {+ "mean": 4176,+ "p50": 4177,+ "p95": 4177,+ "total": 501112+ },+ "byOp": {+ "read.host": 120+ }+ }+ ]+ },+ "state": {+ "afterSetup": {+ "bytes": 772391,+ "documents": 1+ },+ "afterLoad": {+ "bytes": 795688,+ "documents": 1+ }+ },+ "isolatedPolls": [+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 793239,+ "databaseBytesOut": 796674,+ "ms": 16.754417000018293+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 793239,+ "databaseBytesOut": 796674,+ "ms": 16.250792000006186+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 793239,+ "databaseBytesOut": 796674,+ "ms": 16.350500000000466+ },+ {+ "reader": "host:bench-machine-0",+ "responseBytes": 5205,+ "databaseBytesOut": 800259,+ "ms": 22.42895800000406+ },+ {+ "reader": "host:bench-machine-1",+ "responseBytes": 4177,+ "databaseBytesOut": 799761,+ "ms": 18.929083000024548+ }+ ]+}diff --git a/backend/integration/bench/results/baseline-main-0d3485bad-mixed-1.json b/backend/integration/bench/results/baseline-main-0d3485bad-mixed-1.jsonnew file mode 100644index 000000000..f6f6a9550--- /dev/null+++ b/backend/integration/bench/results/baseline-main-0d3485bad-mixed-1.json@@ -0,0 +1,1361 @@+{+ "benchmark": "swarm-state",+ "version": 1,+ "driver": "legacy",+ "startedAt": "2026-10-26T11:28:41.741Z",+ "commit": {+ "sha": "b71522ab633a1881e5390f81da9b854e0a1e9778",+ "dirty": false+ },+ "machine": {+ "platform": "darwin",+ "release": "25.6.0",+ "arch": "arm64",+ "cpu": "Apple M1 Max",+ "cpus": 10,+ "memoryGb": 64,+ "node": "24.18.0",+ "mongo": "7.0.24"+ },+ "config": {+ "seed": 1726,+ "groups": 200,+ "doneShare": 0.9,+ "workers": 20,+ "lane": "mixed",+ "machines": 6,+ "durationMs": 120000,+ "desktopReaders": 3,+ "hostReaders": 2,+ "mix": {+ "message.send": 2,+ "work.status": 1,+ "work.check": 1+ },+ "every": {+ "workerPostMs": 4000,+ "leadSendMs": 5000,+ "nativeTurnMs": 10000,+ "observeMs": 15000,+ "deliveryPassMs": 3000,+ "desktopPollMs": 3000,+ "hostTickMs": 1000+ },+ "text": {+ "briefChars": 3000,+ "resultChars": 600,+ "messageChars": 300+ }+ },+ "planDigest": "8ba3412b11e8239158b685f025f27eb4d02db893abf3a889b67194fc99766a2a",+ "setup": {+ "ms": 59874.019583,+ "calls": 1178,+ "workers": 20,+ "activeGroups": 20,+ "doneGroups": 180+ },+ "load": {+ "plannedMs": 120000,+ "actualMs": 123005.69850000001,+ "skipped": {+ "native answers": 146+ },+ "ops": [+ {+ "key": "deliveries.list",+ "count": 840,+ "ok": 840,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 32.144333000003826,+ "p95Ms": 98.93291600001976,+ "maxMs": 502.50216699999874,+ "bytes": null+ },+ {+ "key": "delivery.ack",+ "count": 540,+ "ok": 539,+ "conflicts": 129,+ "retriedCalls": 55,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 54.61937499998021,+ "p95Ms": 223.08970799998497,+ "maxMs": 3096.9547080000048,+ "bytes": null+ },+ {+ "key": "delivery.claim",+ "count": 543,+ "ok": 540,+ "conflicts": 203,+ "retriedCalls": 80,+ "swarmBusy": 3,+ "errors": {},+ "p50Ms": 57.6301660000172,+ "p95Ms": 399.9926250000135,+ "maxMs": 3512.298207999993,+ "bytes": null+ },+ {+ "key": "message.send",+ "count": 339,+ "ok": 192,+ "conflicts": 1769,+ "retriedCalls": 304,+ "swarmBusy": 147,+ "errors": {},+ "p50Ms": 1900.9105419999978,+ "p95Ms": 4059.2594580000004,+ "maxMs": 5485.685666999998,+ "bytes": null+ },+ {+ "key": "native.append",+ "count": 326,+ "ok": 147,+ "conflicts": 1770,+ "retriedCalls": 268,+ "swarmBusy": 179,+ "errors": {},+ "p50Ms": 2456.9245830000145,+ "p95Ms": 4346.361541999999,+ "maxMs": 5719.260875000007,+ "bytes": null+ },+ {+ "key": "observeMachine",+ "count": 48,+ "ok": 39,+ "conflicts": 163,+ "retriedCalls": 37,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 476.59579200000735,+ "p95Ms": 4274.465874999994,+ "maxMs": 4479.853499999997,+ "bytes": null+ },+ {+ "key": "read.desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.05966699999408,+ "p95Ms": 95.85662500000035,+ "maxMs": 229.1157499999972,+ "bytes": {+ "mean": 1044472,+ "p50": 1046362,+ "p95": 1051467,+ "total": 125336629+ }+ },+ {+ "key": "read.host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 59.520083000010345,+ "p95Ms": 208.34070900001097,+ "maxMs": 477.1201660000079,+ "bytes": {+ "mean": 4691,+ "p50": 4177,+ "p95": 5205,+ "total": 1125840+ }+ },+ {+ "key": "work.check",+ "count": 128,+ "ok": 92,+ "conflicts": 516,+ "retriedCalls": 104,+ "swarmBusy": 36,+ "errors": {},+ "p50Ms": 801.3889579999959,+ "p95Ms": 3778.6127500000002,+ "maxMs": 4302.960208000004,+ "bytes": null+ },+ {+ "key": "work.status",+ "count": 155,+ "ok": 104,+ "conflicts": 659,+ "retriedCalls": 125,+ "swarmBusy": 51,+ "errors": {},+ "p50Ms": 736.6139169999806,+ "p95Ms": 3975.8716669999994,+ "maxMs": 4709.328125,+ "bytes": null+ }+ ],+ "writerKinds": [+ {+ "key": "delivery",+ "count": 1923,+ "ok": 1919,+ "conflicts": 332,+ "retriedCalls": 135,+ "swarmBusy": 4,+ "errors": {},+ "p50Ms": 45.90854199999012,+ "p95Ms": 186.79679199999373,+ "maxMs": 3512.298207999993,+ "bytes": null+ },+ {+ "key": "desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.05966699999408,+ "p95Ms": 95.85662500000035,+ "maxMs": 229.1157499999972,+ "bytes": {+ "mean": 1044472,+ "p50": 1046362,+ "p95": 1051467,+ "total": 125336629+ }+ },+ {+ "key": "host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 59.520083000010345,+ "p95Ms": 208.34070900001097,+ "maxMs": 477.1201660000079,+ "bytes": {+ "mean": 4691,+ "p50": 4177,+ "p95": 5205,+ "total": 1125840+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 14,+ "conflicts": 138,+ "retriedCalls": 22,+ "swarmBusy": 12,+ "errors": {},+ "p50Ms": 2065.8852909999987,+ "p95Ms": 3467.104083000013,+ "maxMs": 3587.8644170000043,+ "bytes": null+ },+ {+ "key": "machine",+ "count": 48,+ "ok": 39,+ "conflicts": 163,+ "retriedCalls": 37,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 476.59579200000735,+ "p95Ms": 4274.465874999994,+ "maxMs": 4479.853499999997,+ "bytes": null+ },+ {+ "key": "terminal",+ "count": 326,+ "ok": 147,+ "conflicts": 1770,+ "retriedCalls": 268,+ "swarmBusy": 179,+ "errors": {},+ "p50Ms": 2456.9245830000145,+ "p95Ms": 4346.361541999999,+ "maxMs": 5719.260875000007,+ "bytes": null+ },+ {+ "key": "worker",+ "count": 596,+ "ok": 374,+ "conflicts": 2806,+ "retriedCalls": 511,+ "swarmBusy": 222,+ "errors": {},+ "p50Ms": 1401.5269590000098,+ "p95Ms": 4031.2419170000067,+ "maxMs": 5485.685666999998,+ "bytes": null+ }+ ],+ "writers": [+ {+ "key": "delivery-0",+ "count": 1227,+ "ok": 1225,+ "conflicts": 264,+ "retriedCalls": 115,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 51.484792000002926,+ "p95Ms": 253.8469589999877,+ "maxMs": 3096.9547080000048,+ "bytes": null,+ "byOp": {+ "deliveries.list": 200,+ "delivery.claim": 514,+ "delivery.ack": 513+ }+ },+ {+ "key": "delivery-1",+ "count": 172,+ "ok": 172,+ "conflicts": 4,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.02804199999082,+ "p95Ms": 96.55170899999212,+ "maxMs": 287.6119159999944,+ "bytes": null,+ "byOp": {+ "deliveries.list": 160,+ "delivery.claim": 6,+ "delivery.ack": 6+ }+ },+ {+ "key": "delivery-2",+ "count": 128,+ "ok": 128,+ "conflicts": 8,+ "retriedCalls": 3,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.48733399999037,+ "p95Ms": 166.50987499998882,+ "maxMs": 596.6721249999973,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 4,+ "delivery.ack": 4+ }+ },+ {+ "key": "delivery-3",+ "count": 130,+ "ok": 130,+ "conflicts": 2,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 35.148082999992766,+ "p95Ms": 131.05837499999325,+ "maxMs": 213.81908299999486,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 5,+ "delivery.ack": 5+ }+ },+ {+ "key": "delivery-4",+ "count": 137,+ "ok": 136,+ "conflicts": 33,+ "retriedCalls": 9,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 35.750583000000915,+ "p95Ms": 186.79679199999373,+ "maxMs": 3512.298207999993,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 9,+ "delivery.ack": 8+ }+ },+ {+ "key": "delivery-5",+ "count": 129,+ "ok": 128,+ "conflicts": 21,+ "retriedCalls": 4,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 34.98708299998543,+ "p95Ms": 100.66662500001257,+ "maxMs": 3152.7777500000084,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 5,+ "delivery.ack": 4+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 14,+ "conflicts": 138,+ "retriedCalls": 22,+ "swarmBusy": 12,+ "errors": {},+ "p50Ms": 2065.8852909999987,+ "p95Ms": 3467.104083000013,+ "maxMs": 3587.8644170000043,+ "bytes": null,+ "byOp": {+ "message.send": 26+ }+ },+ {+ "key": "machine-0",+ "count": 8,+ "ok": 6,+ "conflicts": 36,+ "retriedCalls": 7,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 778.186916000006,+ "p95Ms": 4472.398707999993,+ "maxMs": 4472.398707999993,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-1",+ "count": 8,+ "ok": 8,+ "conflicts": 17,+ "retriedCalls": 5,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 198.21062499999243,+ "p95Ms": 2966.3235409999907,+ "maxMs": 2966.3235409999907,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-2",+ "count": 8,+ "ok": 7,+ "conflicts": 15,+ "retriedCalls": 4,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 142.5431249999965,+ "p95Ms": 3494.491666999995,+ "maxMs": 3494.491666999995,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-3",+ "count": 8,+ "ok": 7,+ "conflicts": 25,+ "retriedCalls": 6,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 503.6803749999963,+ "p95Ms": 2601.405958999996,+ "maxMs": 2601.405958999996,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-4",+ "count": 8,+ "ok": 4,+ "conflicts": 45,+ "retriedCalls": 8,+ "swarmBusy": 4,+ "errors": {},+ "p50Ms": 1125.2124159999948,+ "p95Ms": 4479.853499999997,+ "maxMs": 4479.853499999997,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-5",+ "count": 8,+ "ok": 7,+ "conflicts": 25,+ "retriedCalls": 7,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 371.81849999999395,+ "p95Ms": 2161.812666999991,+ "maxMs": 2161.812666999991,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "terminal-00",+ "count": 12,+ "ok": 1,+ "conflicts": 88,+ "retriedCalls": 11,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 3454.249125000002,+ "p95Ms": 4076.029208000007,+ "maxMs": 4076.029208000007,+ "bytes": null,+ "byOp": {+ "native.append": 12+ }+ },+ {+ "key": "terminal-01",+ "count": 15,+ "ok": 9,+ "conflicts": 74,+ "retriedCalls": 11,+ "swarmBusy": 6,+ "errors": {},+ "p50Ms": 1992.955958000006,+ "p95Ms": 4998.776375000001,+ "maxMs": 4998.776375000001,+ "bytes": null,+ "byOp": {+ "native.append": 15+ }+ },+ {+ "key": "terminal-02",+ "count": 17,+ "ok": 7,+ "conflicts": 97,+ "retriedCalls": 14,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 3066.5562910000153,+ "p95Ms": 4618.858250000005,+ "maxMs": 4618.858250000005,+ "bytes": null,+ "byOp": {+ "native.append": 17+ }+ },+ {+ "key": "terminal-03",+ "count": 17,+ "ok": 8,+ "conflicts": 93,+ "retriedCalls": 15,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 2533.5344590000022,+ "p95Ms": 5551.610792000007,+ "maxMs": 5551.610792000007,+ "bytes": null,+ "byOp": {+ "native.append": 17+ }+ },+ {+ "key": "terminal-04",+ "count": 14,+ "ok": 6,+ "conflicts": 84,+ "retriedCalls": 13,+ "swarmBusy": 8,+ "errors": {},+ "p50Ms": 2256.1366670000134,+ "p95Ms": 4184.124916999979,+ "maxMs": 4184.124916999979,+ "bytes": null,+ "byOp": {+ "native.append": 14+ }+ },+ {+ "key": "terminal-05",+ "count": 18,+ "ok": 11,+ "conflicts": 76,+ "retriedCalls": 13,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 659.4079999999958,+ "p95Ms": 4880.282374999981,+ "maxMs": 4880.282374999981,+ "bytes": null,+ "byOp": {+ "native.append": 18+ }+ },+ {+ "key": "terminal-06",+ "count": 17,+ "ok": 7,+ "conflicts": 97,+ "retriedCalls": 14,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 2788.4877080000006,+ "p95Ms": 4250.602749999991,+ "maxMs": 4250.602749999991,+ "bytes": null,+ "byOp": {+ "native.append": 17+ }+ },+ {+ "key": "terminal-07",+ "count": 13,+ "ok": 4,+ "conflicts": 79,+ "retriedCalls": 11,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 2881.1486250000016,+ "p95Ms": 4674.167207999999,+ "maxMs": 4674.167207999999,+ "bytes": null,+ "byOp": {+ "native.append": 13+ }+ },+ {+ "key": "terminal-08",+ "count": 15,+ "ok": 5,+ "conflicts": 86,+ "retriedCalls": 12,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 2675.9355410000135,+ "p95Ms": 5577.241875000007,+ "maxMs": 5577.241875000007,+ "bytes": null,+ "byOp": {+ "native.append": 15+ }+ },+ {+ "key": "terminal-09",+ "count": 15,+ "ok": 4,+ "conflicts": 101,+ "retriedCalls": 14,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 2603.795000000013,+ "p95Ms": 4619.312791999997,+ "maxMs": 4619.312791999997,+ "bytes": null,+ "byOp": {+ "native.append": 15+ }+ },+ {+ "key": "terminal-10",+ "count": 18,+ "ok": 7,+ "conflicts": 100,+ "retriedCalls": 16,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 2626.147583999991,+ "p95Ms": 4348.822333999997,+ "maxMs": 4348.822333999997,+ "bytes": null,+ "byOp": {+ "native.append": 18+ }+ },+ {+ "key": "terminal-11",+ "count": 19,+ "ok": 10,+ "conflicts": 104,+ "retriedCalls": 16,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 1973.0822089999856,+ "p95Ms": 4538.10437500001,+ "maxMs": 4538.10437500001,+ "bytes": null,+ "byOp": {+ "native.append": 19+ }+ },+ {+ "key": "terminal-12",+ "count": 17,+ "ok": 8,+ "conflicts": 91,+ "retriedCalls": 14,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 1804.7447500000126,+ "p95Ms": 4575.181832999995,+ "maxMs": 4575.181832999995,+ "bytes": null,+ "byOp": {+ "native.append": 17+ }+ },+ {+ "key": "terminal-13",+ "count": 13,+ "ok": 4,+ "conflicts": 74,+ "retriedCalls": 11,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 2845.8350830000127,+ "p95Ms": 4158.896667000008,+ "maxMs": 4158.896667000008,+ "bytes": null,+ "byOp": {+ "native.append": 13+ }+ },+ {+ "key": "terminal-14",+ "count": 22,+ "ok": 13,+ "conflicts": 99,+ "retriedCalls": 16,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 1102.0141669999866,+ "p95Ms": 3794.934707999986,+ "maxMs": 5719.260875000007,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-15",+ "count": 18,+ "ok": 11,+ "conflicts": 79,+ "retriedCalls": 13,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 607.6225829999894,+ "p95Ms": 4855.806415999992,+ "maxMs": 4855.806415999992,+ "bytes": null,+ "byOp": {+ "native.append": 18+ }+ },+ {+ "key": "terminal-16",+ "count": 16,+ "ok": 6,+ "conflicts": 98,+ "retriedCalls": 14,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 2652.4899159999914,+ "p95Ms": 3812.9601669999975,+ "maxMs": 3812.9601669999975,+ "bytes": null,+ "byOp": {+ "native.append": 16+ }+ },+ {+ "key": "terminal-17",+ "count": 13,+ "ok": 3,+ "conflicts": 86,+ "retriedCalls": 12,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 2561.406624999974,+ "p95Ms": 4250.731375000003,+ "maxMs": 4250.731375000003,+ "bytes": null,+ "byOp": {+ "native.append": 13+ }+ },+ {+ "key": "terminal-18",+ "count": 16,+ "ok": 10,+ "conflicts": 71,+ "retriedCalls": 12,+ "swarmBusy": 6,+ "errors": {},+ "p50Ms": 933.3707500000019,+ "p95Ms": 4013.342499999999,+ "maxMs": 4013.342499999999,+ "bytes": null,+ "byOp": {+ "native.append": 16+ }+ },+ {+ "key": "terminal-19",+ "count": 21,+ "ok": 13,+ "conflicts": 93,+ "retriedCalls": 16,+ "swarmBusy": 8,+ "errors": {},+ "p50Ms": 955.0239579999907,+ "p95Ms": 3926.023291999998,+ "maxMs": 5603.4360000000015,+ "bytes": null,+ "byOp": {+ "native.append": 21+ }+ },+ {+ "key": "worker-00",+ "count": 29,+ "ok": 15,+ "conflicts": 163,+ "retriedCalls": 28,+ "swarmBusy": 14,+ "errors": {},+ "p50Ms": 2384.986499999999,+ "p95Ms": 3952.9475000000093,+ "maxMs": 4302.960208000004,+ "bytes": null,+ "byOp": {+ "work.status": 10,+ "work.check": 7,+ "message.send": 12+ }+ },+ {+ "key": "worker-01",+ "count": 28,+ "ok": 17,+ "conflicts": 145,+ "retriedCalls": 25,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 1685.9646249999932,+ "p95Ms": 3589.6807079999853,+ "maxMs": 4115.083165999997,+ "bytes": null,+ "byOp": {+ "work.status": 5,+ "message.send": 13,+ "work.check": 10+ }+ },+ {+ "key": "worker-02",+ "count": 29,+ "ok": 21,+ "conflicts": 132,+ "retriedCalls": 24,+ "swarmBusy": 8,+ "errors": {},+ "p50Ms": 1397.172916999989,+ "p95Ms": 3846.7316250000003,+ "maxMs": 4252.304875000002,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 10,+ "work.check": 3+ }+ },+ {+ "key": "worker-03",+ "count": 30,+ "ok": 17,+ "conflicts": 153,+ "retriedCalls": 26,+ "swarmBusy": 13,+ "errors": {},+ "p50Ms": 1777.848874999996,+ "p95Ms": 4051.6157079999975,+ "maxMs": 4509.867083000005,+ "bytes": null,+ "byOp": {+ "message.send": 18,+ "work.check": 9,+ "work.status": 3+ }+ },+ {+ "key": "worker-04",+ "count": 31,+ "ok": 22,+ "conflicts": 131,+ "retriedCalls": 26,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 732.201166999992,+ "p95Ms": 4339.570582999993,+ "maxMs": 4860.273249999998,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 11,+ "work.check": 5+ }+ },+ {+ "key": "worker-05",+ "count": 32,+ "ok": 18,+ "conflicts": 154,+ "retriedCalls": 28,+ "swarmBusy": 14,+ "errors": {},+ "p50Ms": 1424.836874999979,+ "p95Ms": 4335.046541999996,+ "maxMs": 4426.697207999998,+ "bytes": null,+ "byOp": {+ "message.send": 14,+ "work.status": 10,+ "work.check": 8+ }+ },+ {+ "key": "worker-06",+ "count": 30,+ "ok": 20,+ "conflicts": 122,+ "retriedCalls": 26,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 479.5955829999875,+ "p95Ms": 3960.773958000005,+ "maxMs": 4549.929124999995,+ "bytes": null,+ "byOp": {+ "message.send": 19,+ "work.status": 7,+ "work.check": 4+ }+ },+ {+ "key": "worker-07",+ "count": 29,+ "ok": 20,+ "conflicts": 111,+ "retriedCalls": 23,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 493.9177090000012,+ "p95Ms": 3703.2193750000006,+ "maxMs": 3946.222874999992,+ "bytes": null,+ "byOp": {+ "message.send": 11,+ "work.check": 7,+ "work.status": 11+ }+ },+ {+ "key": "worker-08",+ "count": 31,+ "ok": 19,+ "conflicts": 149,+ "retriedCalls": 27,+ "swarmBusy": 12,+ "errors": {},+ "p50Ms": 1519.3422919999866,+ "p95Ms": 4031.2419170000067,+ "maxMs": 4139.835166999997,+ "bytes": null,+ "byOp": {+ "work.status": 7,+ "message.send": 15,+ "work.check": 9+ }+ },+ {+ "key": "worker-09",+ "count": 31,+ "ok": 21,+ "conflicts": 130,+ "retriedCalls": 23,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 896.8492079999996,+ "p95Ms": 3975.8716669999994,+ "maxMs": 4448.638707999999,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 11,+ "work.status": 7+ }+ },+ {+ "key": "worker-10",+ "count": 33,+ "ok": 21,+ "conflicts": 158,+ "retriedCalls": 28,+ "swarmBusy": 12,+ "errors": {},+ "p50Ms": 1696.5891669999983,+ "p95Ms": 4006.081375000009,+ "maxMs": 4049.0110829999903,+ "bytes": null,+ "byOp": {+ "message.send": 17,+ "work.check": 7,+ "work.status": 9+ }+ },+ {+ "key": "worker-11",+ "count": 29,+ "ok": 19,+ "conflicts": 143,+ "retriedCalls": 24,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 1481.9694580000069,+ "p95Ms": 3497.6175409999996,+ "maxMs": 5485.685666999998,+ "bytes": null,+ "byOp": {+ "work.check": 4,+ "work.status": 5,+ "message.send": 20+ }+ },+ {+ "key": "worker-12",+ "count": 31,+ "ok": 17,+ "conflicts": 171,+ "retriedCalls": 30,+ "swarmBusy": 14,+ "errors": {},+ "p50Ms": 1860.9367499999935,+ "p95Ms": 4230.546999999991,+ "maxMs": 4268.267749999999,+ "bytes": null,+ "byOp": {+ "work.status": 8,+ "message.send": 15,+ "work.check": 8+ }+ },+ {+ "key": "worker-13",+ "count": 27,+ "ok": 18,+ "conflicts": 113,+ "retriedCalls": 23,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 809.9100420000032,+ "p95Ms": 3008.349417000005,+ "maxMs": 3967.051833000005,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 8,+ "work.check": 4+ }+ },+ {+ "key": "worker-14",+ "count": 29,+ "ok": 20,+ "conflicts": 124,+ "retriedCalls": 23,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 1052.0155830000003,+ "p95Ms": 4228.097959000006,+ "maxMs": 4549.236583000005,+ "bytes": null,+ "byOp": {+ "work.check": 5,+ "message.send": 17,+ "work.status": 7+ }+ },+ {+ "key": "worker-15",+ "count": 30,+ "ok": 16,+ "conflicts": 136,+ "retriedCalls": 24,+ "swarmBusy": 14,+ "errors": {},+ "p50Ms": 1054.47775000002,+ "p95Ms": 4557.83045899999,+ "maxMs": 4709.328125,+ "bytes": null,+ "byOp": {+ "work.status": 6,+ "message.send": 17,+ "work.check": 7+ }+ },+ {+ "key": "worker-16",+ "count": 30,+ "ok": 16,+ "conflicts": 154,+ "retriedCalls": 26,+ "swarmBusy": 14,+ "errors": {},+ "p50Ms": 2082.8289589999913,+ "p95Ms": 4290.947,+ "maxMs": 4551.231250000012,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 8,+ "work.check": 6+ }+ },+ {+ "key": "worker-17",+ "count": 29,+ "ok": 18,+ "conflicts": 138,+ "retriedCalls": 24,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 1487.864791,+ "p95Ms": 3516.5904579999915,+ "maxMs": 3842.832917000007,+ "bytes": null,+ "byOp": {+ "message.send": 20,+ "work.check": 4,+ "work.status": 5+ }+ },+ {+ "key": "worker-18",+ "count": 31,+ "ok": 20,+ "conflicts": 154,+ "retriedCalls": 27,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 1556.4408330000006,+ "p95Ms": 4294.452957999994,+ "maxMs": 4484.393000000011,+ "bytes": null,+ "byOp": {+ "work.status": 11,+ "message.send": 17,+ "work.check": 3+ }+ },+ {+ "key": "worker-19",+ "count": 27,+ "ok": 19,+ "conflicts": 125,+ "retriedCalls": 26,+ "swarmBusy": 8,+ "errors": {},+ "p50Ms": 703.265665999992,+ "p95Ms": 3622.4960830000055,+ "maxMs": 4512.975458000001,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 7,+ "work.status": 7+ }+ }+ ],+ "readers": [+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.804833999995026,+ "p95Ms": 69.35004100002698,+ "maxMs": 203.22983300000487,+ "bytes": {+ "mean": 1044451,+ "p50": 1046164,+ "p95": 1051467,+ "total": 41778056+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.99129100001301,+ "p95Ms": 86.92779200000223,+ "maxMs": 229.1157499999972,+ "bytes": {+ "mean": 1044405,+ "p50": 1046164,+ "p95": 1051467,+ "total": 41776180+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.358792000013636,+ "p95Ms": 95.85662500000035,+ "maxMs": 202.40491699999257,+ "bytes": {+ "mean": 1044560,+ "p50": 1046362,+ "p95": 1051467,+ "total": 41782393+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "host:bench-machine-0",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 56.67512500000885,+ "p95Ms": 183.3848330000037,+ "maxMs": 477.1201660000079,+ "bytes": {+ "mean": 5205,+ "p50": 5205,+ "p95": 5205,+ "total": 624600+ },+ "byOp": {+ "read.host": 120+ }+ },+ {+ "key": "host:bench-machine-1",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 61.34341599998879,+ "p95Ms": 208.34070900001097,+ "maxMs": 382.8262909999903,+ "bytes": {+ "mean": 4177,+ "p50": 4177,+ "p95": 4177,+ "total": 501240+ },+ "byOp": {+ "read.host": 120+ }+ }+ ]+ },+ "state": {+ "afterSetup": {+ "bytes": 1038794,+ "documents": 1+ },+ "afterLoad": {+ "bytes": 1061336,+ "documents": 1+ }+ },+ "isolatedPolls": [+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 1051496,+ "databaseBytesOut": 1062322,+ "ms": 25.27733400001307+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 1051496,+ "databaseBytesOut": 1062322,+ "ms": 20.120042000024114+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 1051496,+ "databaseBytesOut": 1062322,+ "ms": 19.638959000003524+ },+ {+ "reader": "host:bench-machine-0",+ "responseBytes": 5205,+ "databaseBytesOut": 1065907,+ "ms": 24.943708000006154+ },+ {+ "reader": "host:bench-machine-1",+ "responseBytes": 4177,+ "databaseBytesOut": 1065409,+ "ms": 25.271416000003228+ }+ ]+}diff --git a/backend/integration/bench/results/baseline-main-0d3485bad-mixed-2.json b/backend/integration/bench/results/baseline-main-0d3485bad-mixed-2.jsonnew file mode 100644index 000000000..d1f3bc780--- /dev/null+++ b/backend/integration/bench/results/baseline-main-0d3485bad-mixed-2.json@@ -0,0 +1,1361 @@+{+ "benchmark": "swarm-state",+ "version": 1,+ "driver": "legacy",+ "startedAt": "2026-10-26T11:31:55.416Z",+ "commit": {+ "sha": "b71522ab633a1881e5390f81da9b854e0a1e9778",+ "dirty": false+ },+ "machine": {+ "platform": "darwin",+ "release": "25.6.0",+ "arch": "arm64",+ "cpu": "Apple M1 Max",+ "cpus": 10,+ "memoryGb": 64,+ "node": "24.18.0",+ "mongo": "7.0.24"+ },+ "config": {+ "seed": 1726,+ "groups": 200,+ "doneShare": 0.9,+ "workers": 20,+ "lane": "mixed",+ "machines": 6,+ "durationMs": 120000,+ "desktopReaders": 3,+ "hostReaders": 2,+ "mix": {+ "message.send": 2,+ "work.status": 1,+ "work.check": 1+ },+ "every": {+ "workerPostMs": 4000,+ "leadSendMs": 5000,+ "nativeTurnMs": 10000,+ "observeMs": 15000,+ "deliveryPassMs": 3000,+ "desktopPollMs": 3000,+ "hostTickMs": 1000+ },+ "text": {+ "briefChars": 3000,+ "resultChars": 600,+ "messageChars": 300+ }+ },+ "planDigest": "8ba3412b11e8239158b685f025f27eb4d02db893abf3a889b67194fc99766a2a",+ "setup": {+ "ms": 59110.810959,+ "calls": 1178,+ "workers": 20,+ "activeGroups": 20,+ "doneGroups": 180+ },+ "load": {+ "plannedMs": 120000,+ "actualMs": 122225.49050000001,+ "skipped": {+ "native answers": 134+ },+ "ops": [+ {+ "key": "deliveries.list",+ "count": 840,+ "ok": 840,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 29.929541999998037,+ "p95Ms": 66.08920799999032,+ "maxMs": 431.28695799999696,+ "bytes": null+ },+ {+ "key": "delivery.ack",+ "count": 580,+ "ok": 579,+ "conflicts": 96,+ "retriedCalls": 45,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 51.57925000000978,+ "p95Ms": 172.51929199999722,+ "maxMs": 2323.6855829999986,+ "bytes": null+ },+ {+ "key": "delivery.claim",+ "count": 582,+ "ok": 580,+ "conflicts": 219,+ "retriedCalls": 87,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 54.59962500000256,+ "p95Ms": 325.91537499999686,+ "maxMs": 3917.455999999991,+ "bytes": null+ },+ {+ "key": "message.send",+ "count": 339,+ "ok": 218,+ "conflicts": 1559,+ "retriedCalls": 292,+ "swarmBusy": 121,+ "errors": {},+ "p50Ms": 991.359415999992,+ "p95Ms": 3797.460167000012,+ "maxMs": 4572.808459000007,+ "bytes": null+ },+ {+ "key": "native.append",+ "count": 338,+ "ok": 169,+ "conflicts": 1737,+ "retriedCalls": 282,+ "swarmBusy": 169,+ "errors": {},+ "p50Ms": 2031.6948750000156,+ "p95Ms": 4014.1297500000073,+ "maxMs": 4627.844125000003,+ "bytes": null+ },+ {+ "key": "observeMachine",+ "count": 48,+ "ok": 33,+ "conflicts": 201,+ "retriedCalls": 39,+ "swarmBusy": 15,+ "errors": {},+ "p50Ms": 586.984375,+ "p95Ms": 3473.784790999998,+ "maxMs": 4749.710999999996,+ "bytes": null+ },+ {+ "key": "read.desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 35.69079199997941,+ "p95Ms": 77.8876670000027,+ "maxMs": 108.6934590000019,+ "bytes": {+ "mean": 1046145,+ "p50": 1047703,+ "p95": 1051918,+ "total": 125537440+ }+ },+ {+ "key": "read.host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 54.16037500000675,+ "p95Ms": 116.18441699999676,+ "maxMs": 203.78804200000013,+ "bytes": {+ "mean": 4691,+ "p50": 4177,+ "p95": 5205,+ "total": 1125840+ }+ },+ {+ "key": "work.check",+ "count": 128,+ "ok": 98,+ "conflicts": 507,+ "retriedCalls": 99,+ "swarmBusy": 30,+ "errors": {},+ "p50Ms": 772.3967090000224,+ "p95Ms": 3720.4720830000006,+ "maxMs": 4038.2212089999957,+ "bytes": null+ },+ {+ "key": "work.status",+ "count": 155,+ "ok": 112,+ "conflicts": 657,+ "retriedCalls": 134,+ "swarmBusy": 43,+ "errors": {},+ "p50Ms": 733.9343329999829,+ "p95Ms": 3542.695792000013,+ "maxMs": 4039.738375000001,+ "bytes": null+ }+ ],+ "writerKinds": [+ {+ "key": "delivery",+ "count": 2002,+ "ok": 1999,+ "conflicts": 315,+ "retriedCalls": 132,+ "swarmBusy": 3,+ "errors": {},+ "p50Ms": 41.96183299999393,+ "p95Ms": 154.64745800000674,+ "maxMs": 3917.455999999991,+ "bytes": null+ },+ {+ "key": "desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 35.69079199997941,+ "p95Ms": 77.8876670000027,+ "maxMs": 108.6934590000019,+ "bytes": {+ "mean": 1046145,+ "p50": 1047703,+ "p95": 1051918,+ "total": 125537440+ }+ },+ {+ "key": "host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 54.16037500000675,+ "p95Ms": 116.18441699999676,+ "maxMs": 203.78804200000013,+ "bytes": {+ "mean": 4691,+ "p50": 4177,+ "p95": 5205,+ "total": 1125840+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 17,+ "conflicts": 122,+ "retriedCalls": 22,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 754.2920000000158,+ "p95Ms": 3859.0559590000194,+ "maxMs": 4025.296457999997,+ "bytes": null+ },+ {+ "key": "machine",+ "count": 48,+ "ok": 33,+ "conflicts": 201,+ "retriedCalls": 39,+ "swarmBusy": 15,+ "errors": {},+ "p50Ms": 586.984375,+ "p95Ms": 3473.784790999998,+ "maxMs": 4749.710999999996,+ "bytes": null+ },+ {+ "key": "terminal",+ "count": 338,+ "ok": 169,+ "conflicts": 1737,+ "retriedCalls": 282,+ "swarmBusy": 169,+ "errors": {},+ "p50Ms": 2031.6948750000156,+ "p95Ms": 4014.1297500000073,+ "maxMs": 4627.844125000003,+ "bytes": null+ },+ {+ "key": "worker",+ "count": 596,+ "ok": 411,+ "conflicts": 2601,+ "retriedCalls": 503,+ "swarmBusy": 185,+ "errors": {},+ "p50Ms": 859.1547910000081,+ "p95Ms": 3666.462541000001,+ "maxMs": 4572.808459000007,+ "bytes": null+ }+ ],+ "writers": [+ {+ "key": "delivery-0",+ "count": 1307,+ "ok": 1305,+ "conflicts": 255,+ "retriedCalls": 111,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 48.495959000021685,+ "p95Ms": 201.9663750000036,+ "maxMs": 3917.455999999991,+ "bytes": null,+ "byOp": {+ "deliveries.list": 200,+ "delivery.claim": 554,+ "delivery.ack": 553+ }+ },+ {+ "key": "delivery-1",+ "count": 170,+ "ok": 170,+ "conflicts": 15,+ "retriedCalls": 4,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 29.887083999987226,+ "p95Ms": 62.68912499997532,+ "maxMs": 2391.6747079999914,+ "bytes": null,+ "byOp": {+ "deliveries.list": 160,+ "delivery.claim": 5,+ "delivery.ack": 5+ }+ },+ {+ "key": "delivery-2",+ "count": 126,+ "ok": 126,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 32.84008300001733,+ "p95Ms": 60.46045800000138,+ "maxMs": 140.09700000000885,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 3,+ "delivery.ack": 3+ }+ },+ {+ "key": "delivery-3",+ "count": 134,+ "ok": 134,+ "conflicts": 16,+ "retriedCalls": 6,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 31.233666999993147,+ "p95Ms": 90.05037499999162,+ "maxMs": 3724.9892500000133,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 7,+ "delivery.ack": 7+ }+ },+ {+ "key": "delivery-4",+ "count": 139,+ "ok": 138,+ "conflicts": 23,+ "retriedCalls": 8,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 31.0944579999923,+ "p95Ms": 145.06050000002142,+ "maxMs": 3240.5427920000075,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 10,+ "delivery.ack": 9+ }+ },+ {+ "key": "delivery-5",+ "count": 126,+ "ok": 126,+ "conflicts": 5,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.4708329999994,+ "p95Ms": 68.20616699999664,+ "maxMs": 300.5302090000041,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 3,+ "delivery.ack": 3+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 17,+ "conflicts": 122,+ "retriedCalls": 22,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 754.2920000000158,+ "p95Ms": 3859.0559590000194,+ "maxMs": 4025.296457999997,+ "bytes": null,+ "byOp": {+ "message.send": 26+ }+ },+ {+ "key": "machine-0",+ "count": 8,+ "ok": 6,+ "conflicts": 30,+ "retriedCalls": 6,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 559.8869580000173,+ "p95Ms": 2664.1543749999983,+ "maxMs": 2664.1543749999983,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-1",+ "count": 8,+ "ok": 8,+ "conflicts": 21,+ "retriedCalls": 5,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 327.09249999999884,+ "p95Ms": 2401.515458000009,+ "maxMs": 2401.515458000009,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-2",+ "count": 8,+ "ok": 2,+ "conflicts": 53,+ "retriedCalls": 8,+ "swarmBusy": 6,+ "errors": {},+ "p50Ms": 2736.4561669999966,+ "p95Ms": 3473.784790999998,+ "maxMs": 3473.784790999998,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-3",+ "count": 8,+ "ok": 7,+ "conflicts": 26,+ "retriedCalls": 7,+ "swarmBusy": 1,+ "errors": {},+ "p50Ms": 236.7528750000056,+ "p95Ms": 2958.321207999994,+ "maxMs": 2958.321207999994,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-4",+ "count": 8,+ "ok": 4,+ "conflicts": 41,+ "retriedCalls": 7,+ "swarmBusy": 4,+ "errors": {},+ "p50Ms": 571.901457999993,+ "p95Ms": 4749.710999999996,+ "maxMs": 4749.710999999996,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-5",+ "count": 8,+ "ok": 6,+ "conflicts": 30,+ "retriedCalls": 6,+ "swarmBusy": 2,+ "errors": {},+ "p50Ms": 272.74862500000745,+ "p95Ms": 3593.989709000016,+ "maxMs": 3593.989709000016,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "terminal-00",+ "count": 16,+ "ok": 9,+ "conflicts": 69,+ "retriedCalls": 12,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 554.8032499999972,+ "p95Ms": 3571.219207999995,+ "maxMs": 3571.219207999995,+ "bytes": null,+ "byOp": {+ "native.append": 16+ }+ },+ {+ "key": "terminal-01",+ "count": 12,+ "ok": 3,+ "conflicts": 76,+ "retriedCalls": 11,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 2021.7418340000004,+ "p95Ms": 3882.5487500000017,+ "maxMs": 3882.5487500000017,+ "bytes": null,+ "byOp": {+ "native.append": 12+ }+ },+ {+ "key": "terminal-02",+ "count": 16,+ "ok": 7,+ "conflicts": 89,+ "retriedCalls": 14,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 2358.0570420000004,+ "p95Ms": 3837.832290999999,+ "maxMs": 3837.832290999999,+ "bytes": null,+ "byOp": {+ "native.append": 16+ }+ },+ {+ "key": "terminal-03",+ "count": 18,+ "ok": 11,+ "conflicts": 78,+ "retriedCalls": 13,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 591.78125,+ "p95Ms": 4263.075582999998,+ "maxMs": 4263.075582999998,+ "bytes": null,+ "byOp": {+ "native.append": 18+ }+ },+ {+ "key": "terminal-04",+ "count": 13,+ "ok": 2,+ "conflicts": 99,+ "retriedCalls": 13,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 2540.842874999973,+ "p95Ms": 3321.4497919999994,+ "maxMs": 3321.4497919999994,+ "bytes": null,+ "byOp": {+ "native.append": 13+ }+ },+ {+ "key": "terminal-05",+ "count": 19,+ "ok": 11,+ "conflicts": 83,+ "retriedCalls": 14,+ "swarmBusy": 8,+ "errors": {},+ "p50Ms": 1538.5490839999984,+ "p95Ms": 4025.092499999999,+ "maxMs": 4025.092499999999,+ "bytes": null,+ "byOp": {+ "native.append": 19+ }+ },+ {+ "key": "terminal-06",+ "count": 19,+ "ok": 9,+ "conflicts": 101,+ "retriedCalls": 17,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 2519.5529589999933,+ "p95Ms": 4014.1297500000073,+ "maxMs": 4014.1297500000073,+ "bytes": null,+ "byOp": {+ "native.append": 19+ }+ },+ {+ "key": "terminal-07",+ "count": 16,+ "ok": 6,+ "conflicts": 96,+ "retriedCalls": 16,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 2362.2848749999976,+ "p95Ms": 4304.918875000003,+ "maxMs": 4304.918875000003,+ "bytes": null,+ "byOp": {+ "native.append": 16+ }+ },+ {+ "key": "terminal-08",+ "count": 18,+ "ok": 11,+ "conflicts": 86,+ "retriedCalls": 15,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 908.8664169999975,+ "p95Ms": 4059.5746669999935,+ "maxMs": 4059.5746669999935,+ "bytes": null,+ "byOp": {+ "native.append": 18+ }+ },+ {+ "key": "terminal-09",+ "count": 21,+ "ok": 14,+ "conflicts": 81,+ "retriedCalls": 15,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 844.2677499999991,+ "p95Ms": 4007.7873750000144,+ "maxMs": 4411.494707999998,+ "bytes": null,+ "byOp": {+ "native.append": 21+ }+ },+ {+ "key": "terminal-10",+ "count": 17,+ "ok": 5,+ "conflicts": 101,+ "retriedCalls": 14,+ "swarmBusy": 12,+ "errors": {},+ "p50Ms": 2208.157124999998,+ "p95Ms": 4201.217082999996,+ "maxMs": 4201.217082999996,+ "bytes": null,+ "byOp": {+ "native.append": 17+ }+ },+ {+ "key": "terminal-11",+ "count": 18,+ "ok": 9,+ "conflicts": 106,+ "retriedCalls": 16,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 2340.242083000019,+ "p95Ms": 4627.844125000003,+ "maxMs": 4627.844125000003,+ "bytes": null,+ "byOp": {+ "native.append": 18+ }+ },+ {+ "key": "terminal-12",+ "count": 15,+ "ok": 6,+ "conflicts": 84,+ "retriedCalls": 12,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 2182.2167499999923,+ "p95Ms": 4455.805207999991,+ "maxMs": 4455.805207999991,+ "bytes": null,+ "byOp": {+ "native.append": 15+ }+ },+ {+ "key": "terminal-13",+ "count": 17,+ "ok": 10,+ "conflicts": 75,+ "retriedCalls": 12,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 1352.0327499999985,+ "p95Ms": 4186.48662500002,+ "maxMs": 4186.48662500002,+ "bytes": null,+ "byOp": {+ "native.append": 17+ }+ },+ {+ "key": "terminal-14",+ "count": 20,+ "ok": 11,+ "conflicts": 93,+ "retriedCalls": 16,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 1149.1426670000073,+ "p95Ms": 4064.1034170000057,+ "maxMs": 4148.698000000004,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-15",+ "count": 18,+ "ok": 13,+ "conflicts": 65,+ "retriedCalls": 14,+ "swarmBusy": 5,+ "errors": {},+ "p50Ms": 328.50279200001387,+ "p95Ms": 3756.6022499999963,+ "maxMs": 3756.6022499999963,+ "bytes": null,+ "byOp": {+ "native.append": 18+ }+ },+ {+ "key": "terminal-16",+ "count": 15,+ "ok": 7,+ "conflicts": 89,+ "retriedCalls": 13,+ "swarmBusy": 8,+ "errors": {},+ "p50Ms": 2416.6996660000004,+ "p95Ms": 3333.9922910000023,+ "maxMs": 3333.9922910000023,+ "bytes": null,+ "byOp": {+ "native.append": 15+ }+ },+ {+ "key": "terminal-17",+ "count": 17,+ "ok": 10,+ "conflicts": 82,+ "retriedCalls": 15,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 1267.9710839999898,+ "p95Ms": 4282.834999999992,+ "maxMs": 4282.834999999992,+ "bytes": null,+ "byOp": {+ "native.append": 17+ }+ },+ {+ "key": "terminal-18",+ "count": 13,+ "ok": 6,+ "conflicts": 70,+ "retriedCalls": 11,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 2465.9057500000054,+ "p95Ms": 4043.005999999994,+ "maxMs": 4043.005999999994,+ "bytes": null,+ "byOp": {+ "native.append": 13+ }+ },+ {+ "key": "terminal-19",+ "count": 20,+ "ok": 9,+ "conflicts": 114,+ "retriedCalls": 19,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 1993.0559169999906,+ "p95Ms": 3451.806540999998,+ "maxMs": 3800.130375000008,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "worker-00",+ "count": 29,+ "ok": 23,+ "conflicts": 120,+ "retriedCalls": 25,+ "swarmBusy": 6,+ "errors": {},+ "p50Ms": 783.9985000000161,+ "p95Ms": 2791.0575839999947,+ "maxMs": 3900.6545830000105,+ "bytes": null,+ "byOp": {+ "work.status": 10,+ "work.check": 7,+ "message.send": 12+ }+ },+ {+ "key": "worker-01",+ "count": 28,+ "ok": 20,+ "conflicts": 110,+ "retriedCalls": 24,+ "swarmBusy": 8,+ "errors": {},+ "p50Ms": 393.49566699998104,+ "p95Ms": 3666.462541000001,+ "maxMs": 3839.490167000011,+ "bytes": null,+ "byOp": {+ "work.status": 5,+ "message.send": 13,+ "work.check": 10+ }+ },+ {+ "key": "worker-02",+ "count": 29,+ "ok": 19,+ "conflicts": 134,+ "retriedCalls": 26,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 1418.6976250000007,+ "p95Ms": 3844.616458000004,+ "maxMs": 4194.588166000001,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 10,+ "work.check": 3+ }+ },+ {+ "key": "worker-03",+ "count": 30,+ "ok": 20,+ "conflicts": 127,+ "retriedCalls": 24,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 634.8042080000014,+ "p95Ms": 3449.058999999994,+ "maxMs": 3599.1717079999944,+ "bytes": null,+ "byOp": {+ "message.send": 18,+ "work.check": 9,+ "work.status": 3+ }+ },+ {+ "key": "worker-04",+ "count": 31,+ "ok": 22,+ "conflicts": 131,+ "retriedCalls": 26,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 995.1517089999979,+ "p95Ms": 3983.5236659999937,+ "maxMs": 4010.416167000003,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 11,+ "work.check": 5+ }+ },+ {+ "key": "worker-05",+ "count": 32,+ "ok": 20,+ "conflicts": 158,+ "retriedCalls": 29,+ "swarmBusy": 12,+ "errors": {},+ "p50Ms": 1415.4045420000039,+ "p95Ms": 3910.617665999991,+ "maxMs": 4089.363333000001,+ "bytes": null,+ "byOp": {+ "message.send": 14,+ "work.status": 10,+ "work.check": 8+ }+ },+ {+ "key": "worker-06",+ "count": 30,+ "ok": 24,+ "conflicts": 108,+ "retriedCalls": 24,+ "swarmBusy": 6,+ "errors": {},+ "p50Ms": 413.51066700000956,+ "p95Ms": 3509.6701659999962,+ "maxMs": 3956.456707999998,+ "bytes": null,+ "byOp": {+ "message.send": 19,+ "work.status": 7,+ "work.check": 4+ }+ },+ {+ "key": "worker-07",+ "count": 29,+ "ok": 22,+ "conflicts": 110,+ "retriedCalls": 24,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 435.76425000000745,+ "p95Ms": 3409.5670830000017,+ "maxMs": 3458.319082999995,+ "bytes": null,+ "byOp": {+ "message.send": 11,+ "work.check": 7,+ "work.status": 11+ }+ },+ {+ "key": "worker-08",+ "count": 31,+ "ok": 22,+ "conflicts": 135,+ "retriedCalls": 28,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 812.5999580000062,+ "p95Ms": 3995.6258329999982,+ "maxMs": 4038.2212089999957,+ "bytes": null,+ "byOp": {+ "work.status": 7,+ "message.send": 15,+ "work.check": 9+ }+ },+ {+ "key": "worker-09",+ "count": 31,+ "ok": 26,+ "conflicts": 118,+ "retriedCalls": 26,+ "swarmBusy": 5,+ "errors": {},+ "p50Ms": 761.4969999999885,+ "p95Ms": 3578.313875000007,+ "maxMs": 3642.8384169999918,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 11,+ "work.status": 7+ }+ },+ {+ "key": "worker-10",+ "count": 33,+ "ok": 26,+ "conflicts": 136,+ "retriedCalls": 27,+ "swarmBusy": 7,+ "errors": {},+ "p50Ms": 822.3235419999983,+ "p95Ms": 3542.695792000013,+ "maxMs": 3551.4192500000063,+ "bytes": null,+ "byOp": {+ "message.send": 17,+ "work.check": 7,+ "work.status": 9+ }+ },+ {+ "key": "worker-11",+ "count": 29,+ "ok": 18,+ "conflicts": 129,+ "retriedCalls": 24,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 772.3967090000224,+ "p95Ms": 3797.460167000012,+ "maxMs": 4039.738375000001,+ "bytes": null,+ "byOp": {+ "work.check": 4,+ "work.status": 5,+ "message.send": 20+ }+ },+ {+ "key": "worker-12",+ "count": 31,+ "ok": 22,+ "conflicts": 143,+ "retriedCalls": 28,+ "swarmBusy": 9,+ "errors": {},+ "p50Ms": 1011.9704170000041,+ "p95Ms": 3809.3565420000086,+ "maxMs": 4570.4903750000085,+ "bytes": null,+ "byOp": {+ "work.status": 8,+ "message.send": 15,+ "work.check": 8+ }+ },+ {+ "key": "worker-13",+ "count": 27,+ "ok": 16,+ "conflicts": 133,+ "retriedCalls": 24,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 1275.0475420000002,+ "p95Ms": 3817.2034580000036,+ "maxMs": 3972.7917080000043,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 8,+ "work.check": 4+ }+ },+ {+ "key": "worker-14",+ "count": 29,+ "ok": 18,+ "conflicts": 132,+ "retriedCalls": 23,+ "swarmBusy": 11,+ "errors": {},+ "p50Ms": 827.8370829999913,+ "p95Ms": 3516.802541000012,+ "maxMs": 4336.8305419999815,+ "bytes": null,+ "byOp": {+ "work.check": 5,+ "message.send": 17,+ "work.status": 7+ }+ },+ {+ "key": "worker-15",+ "count": 30,+ "ok": 22,+ "conflicts": 126,+ "retriedCalls": 22,+ "swarmBusy": 8,+ "errors": {},+ "p50Ms": 917.3925409999792,+ "p95Ms": 3891.4512920000125,+ "maxMs": 4004.6839159999945,+ "bytes": null,+ "byOp": {+ "work.status": 6,+ "message.send": 17,+ "work.check": 7+ }+ },+ {+ "key": "worker-16",+ "count": 30,+ "ok": 14,+ "conflicts": 154,+ "retriedCalls": 25,+ "swarmBusy": 16,+ "errors": {},+ "p50Ms": 2048.2822500000184,+ "p95Ms": 3393.3949580000044,+ "maxMs": 3646.9659159999865,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 8,+ "work.check": 6+ }+ },+ {+ "key": "worker-17",+ "count": 29,+ "ok": 17,+ "conflicts": 151,+ "retriedCalls": 27,+ "swarmBusy": 12,+ "errors": {},+ "p50Ms": 2153.693250000011,+ "p95Ms": 3910.8346670000174,+ "maxMs": 4572.808459000007,+ "bytes": null,+ "byOp": {+ "message.send": 20,+ "work.check": 4,+ "work.status": 5+ }+ },+ {+ "key": "worker-18",+ "count": 31,+ "ok": 21,+ "conflicts": 136,+ "retriedCalls": 26,+ "swarmBusy": 10,+ "errors": {},+ "p50Ms": 1029.708375000002,+ "p95Ms": 3371.993499999997,+ "maxMs": 3949.5331250000017,+ "bytes": null,+ "byOp": {+ "work.status": 11,+ "message.send": 17,+ "work.check": 3+ }+ },+ {+ "key": "worker-19",+ "count": 27,+ "ok": 19,+ "conflicts": 110,+ "retriedCalls": 21,+ "swarmBusy": 8,+ "errors": {},+ "p50Ms": 715.6362920000101,+ "p95Ms": 3343.7470829999947,+ "maxMs": 4476.554207999987,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 7,+ "work.status": 7+ }+ }+ ],+ "readers": [+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 29.445040999999037,+ "p95Ms": 75.23050000000512,+ "maxMs": 100.83287499999278,+ "bytes": {+ "mean": 1046141,+ "p50": 1047703,+ "p95": 1051918,+ "total": 41845656+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.85029200000281,+ "p95Ms": 60.06575000000885,+ "maxMs": 72.14545899999212,+ "bytes": {+ "mean": 1046040,+ "p50": 1047703,+ "p95": 1051918,+ "total": 41841589+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.72529200001736,+ "p95Ms": 88.69462500000373,+ "maxMs": 108.6934590000019,+ "bytes": {+ "mean": 1046255,+ "p50": 1047703,+ "p95": 1051917,+ "total": 41850195+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "host:bench-machine-0",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 54.096082999996725,+ "p95Ms": 121.08166700000584,+ "maxMs": 196.9342910000123,+ "bytes": {+ "mean": 5205,+ "p50": 5205,+ "p95": 5205,+ "total": 624600+ },+ "byOp": {+ "read.host": 120+ }+ },+ {+ "key": "host:bench-machine-1",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 54.16037500000675,+ "p95Ms": 110.45604099999764,+ "maxMs": 203.78804200000013,+ "bytes": {+ "mean": 4177,+ "p50": 4177,+ "p95": 4177,+ "total": 501240+ },+ "byOp": {+ "read.host": 120+ }+ }+ ]+ },+ "state": {+ "afterSetup": {+ "bytes": 1038794,+ "documents": 1+ },+ "afterLoad": {+ "bytes": 1061815,+ "documents": 1+ }+ },+ "isolatedPolls": [+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 1051947,+ "databaseBytesOut": 1062801,+ "ms": 20.12524999998277+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 1051947,+ "databaseBytesOut": 1062801,+ "ms": 19.75633299999754+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 1051947,+ "databaseBytesOut": 1062801,+ "ms": 18.94900000002235+ },+ {+ "reader": "host:bench-machine-0",+ "responseBytes": 5205,+ "databaseBytesOut": 1066386,+ "ms": 21.349541000003228+ },+ {+ "reader": "host:bench-machine-1",+ "responseBytes": 4177,+ "databaseBytesOut": 1065888,+ "ms": 19.198999999993248+ }+ ]+}diff --git a/backend/integration/bench/results/results-44d51aae8-cross-group.json b/backend/integration/bench/results/results-44d51aae8-cross-group.jsonnew file mode 100644index 000000000..ff1b78372--- /dev/null+++ b/backend/integration/bench/results/results-44d51aae8-cross-group.json@@ -0,0 +1,1170 @@+{+ "benchmark": "swarm-state",+ "version": 1,+ "driver": "parts",+ "startedAt": "2026-10-26T16:49:07.363Z",+ "commit": {+ "sha": "4b8b5ea8a14e9019ac7d174986859afc4f23c84d",+ "dirty": false+ },+ "machine": {+ "platform": "darwin",+ "release": "25.6.0",+ "arch": "arm64",+ "cpu": "Apple M1 Max",+ "cpus": 10,+ "memoryGb": 64,+ "node": "24.18.0",+ "mongo": "7.0.24"+ },+ "config": {+ "seed": 1726,+ "groups": 200,+ "doneShare": 0.9,+ "workers": 20,+ "lane": "cross-group",+ "machines": 6,+ "durationMs": 120000,+ "desktopReaders": 3,+ "hostReaders": 2,+ "mix": {+ "message.send": 2,+ "work.status": 1,+ "work.check": 1+ },+ "every": {+ "workerPostMs": 4000,+ "leadSendMs": 5000,+ "nativeTurnMs": 10000,+ "observeMs": 15000,+ "deliveryPassMs": 3000,+ "desktopPollMs": 3000,+ "hostTickMs": 1000+ },+ "text": {+ "briefChars": 3000,+ "resultChars": 600,+ "messageChars": 300+ }+ },+ "planDigest": "575e841eb53ecf495233ccc04f807dcd3f38db7efde2c269a11b21d83f79b1cf",+ "setup": {+ "ms": 37401.364707999994,+ "calls": 1178,+ "workers": 20,+ "activeGroups": 20,+ "doneGroups": 180+ },+ "load": {+ "plannedMs": 120000,+ "actualMs": 119679.175416,+ "skipped": {},+ "ops": [+ {+ "key": "message.send",+ "count": 313,+ "ok": 313,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.72483399999328,+ "p95Ms": 68.3927079999994,+ "maxMs": 120.1217089999991,+ "bytes": null+ },+ {+ "key": "native.append",+ "count": 472,+ "ok": 472,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.09599999999773,+ "p95Ms": 68.32233399999677,+ "maxMs": 88.10066599999845,+ "bytes": null+ },+ {+ "key": "observeMachine",+ "count": 48,+ "ok": 48,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.16979100000026,+ "p95Ms": 48.653707999998005,+ "maxMs": 84.888208999997,+ "bytes": null+ },+ {+ "key": "read.desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 31.46950000000652,+ "p95Ms": 52.76379200001247,+ "maxMs": 109.25679200000013,+ "bytes": {+ "mean": 242960,+ "p50": 112352,+ "p95": 895355,+ "total": 29155195+ }+ },+ {+ "key": "read.host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.26187499999651,+ "p95Ms": 63.78375000000233,+ "maxMs": 112.75845799999661,+ "bytes": {+ "mean": 321,+ "p50": 269,+ "p95": 269,+ "total": 76947+ }+ },+ {+ "key": "work.check",+ "count": 128,+ "ok": 128,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.757500000006985,+ "p95Ms": 57.206749999983,+ "maxMs": 83.78345799999079,+ "bytes": null+ },+ {+ "key": "work.status",+ "count": 155,+ "ok": 155,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.05950000000303,+ "p95Ms": 63.104624999992666,+ "maxMs": 143.61558300000615,+ "bytes": null+ }+ ],+ "writerKinds": [+ {+ "key": "desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 31.46950000000652,+ "p95Ms": 52.76379200001247,+ "maxMs": 109.25679200000013,+ "bytes": {+ "mean": 242960,+ "p50": 112352,+ "p95": 895355,+ "total": 29155195+ }+ },+ {+ "key": "host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.26187499999651,+ "p95Ms": 63.78375000000233,+ "maxMs": 112.75845799999661,+ "bytes": {+ "mean": 321,+ "p50": 269,+ "p95": 269,+ "total": 76947+ }+ },+ {+ "key": "machine",+ "count": 48,+ "ok": 48,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.16979100000026,+ "p95Ms": 48.653707999998005,+ "maxMs": 84.888208999997,+ "bytes": null+ },+ {+ "key": "terminal",+ "count": 472,+ "ok": 472,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.09599999999773,+ "p95Ms": 68.32233399999677,+ "maxMs": 88.10066599999845,+ "bytes": null+ },+ {+ "key": "worker",+ "count": 596,+ "ok": 596,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.172916000010446,+ "p95Ms": 65.367957999988,+ "maxMs": 143.61558300000615,+ "bytes": null+ }+ ],+ "writers": [+ {+ "key": "machine-0",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.23466699998244,+ "p95Ms": 48.653707999998005,+ "maxMs": 48.653707999998005,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-1",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 35.22499999997672,+ "p95Ms": 53.56100000000151,+ "maxMs": 53.56100000000151,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-2",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 35.769040999992285,+ "p95Ms": 41.01829199999338,+ "maxMs": 41.01829199999338,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-3",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.06804199999897,+ "p95Ms": 84.888208999997,+ "maxMs": 84.888208999997,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-4",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 35.40383299998939,+ "p95Ms": 46.1215830000001,+ "maxMs": 46.1215830000001,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-5",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.16979100000026,+ "p95Ms": 42.6427079999994,+ "maxMs": 42.6427079999994,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "terminal-00",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.71066599999904,+ "p95Ms": 55.912665999996534,+ "maxMs": 69.10112500000105,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-01",+ "count": 20,+ "ok": 20,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.53516600000148,+ "p95Ms": 60.31620899999689,+ "maxMs": 82.25074999999924,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-02",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.032500000001164,+ "p95Ms": 63.24487500000396,+ "maxMs": 65.73904099999345,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-03",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.203125,+ "p95Ms": 72.03020800001104,+ "maxMs": 73.22179200000392,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-04",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.94933399999718,+ "p95Ms": 69.43104200001108,+ "maxMs": 82.29241700001876,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-05",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.76425000000745,+ "p95Ms": 56.13329199999862,+ "maxMs": 74.7546250000014,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-06",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.43549999999232,+ "p95Ms": 78.01675000000978,+ "maxMs": 82.31462500001362,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-07",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.15862499999639,+ "p95Ms": 65.33808300000965,+ "maxMs": 68.48054199999024,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-08",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.996458999987226,+ "p95Ms": 78.30041599999822,+ "maxMs": 87.95470899998327,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-09",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.67050000000745,+ "p95Ms": 80.89008300000569,+ "maxMs": 84.39887499999895,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-10",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.96700000000419,+ "p95Ms": 63.45708400000876,+ "maxMs": 63.895417000007,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "terminal-11",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.01941699998861,+ "p95Ms": 66.58170800001244,+ "maxMs": 69.34437500001513,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-12",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.39558299999044,+ "p95Ms": 59.35620900000504,+ "maxMs": 61.4958750000078,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-13",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.31104200000118,+ "p95Ms": 65.7129169999971,+ "maxMs": 79.64862500000163,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-14",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.604584000000614,+ "p95Ms": 61.33062500000233,+ "maxMs": 62.32945799999288,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "terminal-15",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.8442500000092,+ "p95Ms": 62.38312500000029,+ "maxMs": 65.2757910000073,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-16",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.338000000003376,+ "p95Ms": 62.646999999997206,+ "maxMs": 67.04891700000735,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-17",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 51.198457999998936,+ "p95Ms": 81.48579200000677,+ "maxMs": 88.10066599999845,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-18",+ "count": 20,+ "ok": 20,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.698540999990655,+ "p95Ms": 68.87174999999115,+ "maxMs": 81.92020799999591,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-19",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.98916699999245,+ "p95Ms": 69.17108299999381,+ "maxMs": 76.90212499999325,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "worker-00",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.192333000013605,+ "p95Ms": 54.48820799999521,+ "maxMs": 57.155457999993814,+ "bytes": null,+ "byOp": {+ "work.status": 10,+ "work.check": 7,+ "message.send": 12+ }+ },+ {+ "key": "worker-01",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.70524999999907,+ "p95Ms": 57.46516600000905,+ "maxMs": 62.39341700001387,+ "bytes": null,+ "byOp": {+ "work.status": 5,+ "message.send": 13,+ "work.check": 10+ }+ },+ {+ "key": "worker-02",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.773417000003974,+ "p95Ms": 65.26366700000654,+ "maxMs": 78.28020799999649,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 10,+ "work.check": 3+ }+ },+ {+ "key": "worker-03",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.66399999999703,+ "p95Ms": 60.21220799999719,+ "maxMs": 61.18033299999661,+ "bytes": null,+ "byOp": {+ "message.send": 18,+ "work.check": 9,+ "work.status": 3+ }+ },+ {+ "key": "worker-04",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.15495799999917,+ "p95Ms": 68.68866600000183,+ "maxMs": 77.33304199998383,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 11,+ "work.check": 5+ }+ },+ {+ "key": "worker-05",+ "count": 32,+ "ok": 32,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.05950000000303,+ "p95Ms": 63.311541999995825,+ "maxMs": 90.62879099999554,+ "bytes": null,+ "byOp": {+ "message.send": 14,+ "work.status": 10,+ "work.check": 8+ }+ },+ {+ "key": "worker-06",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.95975000000908,+ "p95Ms": 60.479999999995925,+ "maxMs": 69.92191699999967,+ "bytes": null,+ "byOp": {+ "message.send": 19,+ "work.status": 7,+ "work.check": 4+ }+ },+ {+ "key": "worker-07",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.757500000006985,+ "p95Ms": 68.56291700000293,+ "maxMs": 81.98754100000951,+ "bytes": null,+ "byOp": {+ "message.send": 11,+ "work.check": 7,+ "work.status": 11+ }+ },+ {+ "key": "worker-08",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.452332999993814,+ "p95Ms": 60.501250000001164,+ "maxMs": 71.99404200000572,+ "bytes": null,+ "byOp": {+ "work.status": 7,+ "message.send": 15,+ "work.check": 9+ }+ },+ {+ "key": "worker-09",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.039999999979045,+ "p95Ms": 69.02183300000615,+ "maxMs": 82.89808400000038,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 11,+ "work.status": 7+ }+ },+ {+ "key": "worker-10",+ "count": 33,+ "ok": 33,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.15587499999674,+ "p95Ms": 57.61904100001266,+ "maxMs": 59.16716599999927,+ "bytes": null,+ "byOp": {+ "message.send": 17,+ "work.check": 7,+ "work.status": 9+ }+ },+ {+ "key": "worker-11",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.07570799998939,+ "p95Ms": 73.03749999999127,+ "maxMs": 120.1217089999991,+ "bytes": null,+ "byOp": {+ "work.check": 4,+ "work.status": 5,+ "message.send": 20+ }+ },+ {+ "key": "worker-12",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.29024999999092,+ "p95Ms": 73.46400000000722,+ "maxMs": 79.11391700000968,+ "bytes": null,+ "byOp": {+ "work.status": 8,+ "message.send": 15,+ "work.check": 8+ }+ },+ {+ "key": "worker-13",+ "count": 27,+ "ok": 27,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.0054999999993,+ "p95Ms": 83.78345799999079,+ "maxMs": 85.90895799999998,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 8,+ "work.check": 4+ }+ },+ {+ "key": "worker-14",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.394333000003826,+ "p95Ms": 55.32095900000422,+ "maxMs": 55.877707999999984,+ "bytes": null,+ "byOp": {+ "work.check": 5,+ "message.send": 17,+ "work.status": 7+ }+ },+ {+ "key": "worker-15",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.88866699999198,+ "p95Ms": 73.83379199999763,+ "maxMs": 93.11929099999543,+ "bytes": null,+ "byOp": {+ "work.status": 6,+ "message.send": 17,+ "work.check": 7+ }+ },+ {+ "key": "worker-16",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.25920900001074,+ "p95Ms": 66.14274999999907,+ "maxMs": 82.6306670000049,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 8,+ "work.check": 6+ }+ },+ {+ "key": "worker-17",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.078999999997905,+ "p95Ms": 65.36433399999805,+ "maxMs": 70.21437500001048,+ "bytes": null,+ "byOp": {+ "message.send": 20,+ "work.check": 4,+ "work.status": 5+ }+ },+ {+ "key": "worker-18",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.52941699999792,+ "p95Ms": 77.24300000000221,+ "maxMs": 143.61558300000615,+ "bytes": null,+ "byOp": {+ "work.status": 11,+ "message.send": 17,+ "work.check": 3+ }+ },+ {+ "key": "worker-19",+ "count": 27,+ "ok": 27,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.14999999999418,+ "p95Ms": 60.30883300000278,+ "maxMs": 68.3927079999994,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 7,+ "work.status": 7+ }+ }+ ],+ "readers": [+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 31.46950000000652,+ "p95Ms": 45.69262499999604,+ "maxMs": 63.59962500000256,+ "bytes": {+ "mean": 243772,+ "p50": 112324,+ "p95": 879971,+ "total": 9750891+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.46908299998904,+ "p95Ms": 46.536917000004905,+ "maxMs": 58.73920899999939,+ "bytes": {+ "mean": 247427,+ "p50": 112155,+ "p95": 895355,+ "total": 9897082+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 28.611166999995476,+ "p95Ms": 53.013208999997005,+ "maxMs": 109.25679200000013,+ "bytes": {+ "mean": 237681,+ "p50": 112352,+ "p95": 855792,+ "total": 9507222+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "host:bench-machine-0",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.12891700000182,+ "p95Ms": 63.24199999999837,+ "maxMs": 85.74454200000037,+ "bytes": {+ "mean": 325,+ "p50": 269,+ "p95": 269,+ "total": 39059+ },+ "byOp": {+ "read.host": 120+ }+ },+ {+ "key": "host:bench-machine-1",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 35.4460409999956,+ "p95Ms": 65.38908399999491,+ "maxMs": 112.75845799999661,+ "bytes": {+ "mean": 316,+ "p50": 269,+ "p95": 269,+ "total": 37888+ },+ "byOp": {+ "read.host": 120+ }+ }+ ]+ },+ "state": {+ "afterSetup": {+ "bytes": 1174606,+ "documents": 237+ },+ "afterLoad": {+ "bytes": 1198073,+ "documents": 237+ }+ },+ "isolatedPolls": [+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 113508,+ "databaseBytesOut": 185547,+ "ms": 26.80870799999684+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 113508,+ "databaseBytesOut": 185547,+ "ms": 26.580291999998735+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 113508,+ "databaseBytesOut": 185547,+ "ms": 29.41883300000336+ },+ {+ "reader": "host:bench-machine-0",+ "responseBytes": 269,+ "databaseBytesOut": 145570,+ "ms": 41.25325000000885+ },+ {+ "reader": "host:bench-machine-1",+ "responseBytes": 269,+ "databaseBytesOut": 88329,+ "ms": 34.618249999999534+ }+ ]+}diff --git a/backend/integration/bench/results/results-44d51aae8-hot.json b/backend/integration/bench/results/results-44d51aae8-hot.jsonnew file mode 100644index 000000000..d22e2fca2--- /dev/null+++ b/backend/integration/bench/results/results-44d51aae8-hot.json@@ -0,0 +1,1359 @@+{+ "benchmark": "swarm-state",+ "version": 1,+ "driver": "parts",+ "startedAt": "2026-10-26T16:51:52.709Z",+ "commit": {+ "sha": "4b8b5ea8a14e9019ac7d174986859afc4f23c84d",+ "dirty": false+ },+ "machine": {+ "platform": "darwin",+ "release": "25.6.0",+ "arch": "arm64",+ "cpu": "Apple M1 Max",+ "cpus": 10,+ "memoryGb": 64,+ "node": "24.18.0",+ "mongo": "7.0.24"+ },+ "config": {+ "seed": 1726,+ "groups": 200,+ "doneShare": 0,+ "workers": 20,+ "lane": "mixed",+ "machines": 6,+ "durationMs": 120000,+ "desktopReaders": 3,+ "hostReaders": 2,+ "mix": {+ "message.send": 2,+ "work.status": 1,+ "work.check": 1+ },+ "every": {+ "workerPostMs": 4000,+ "leadSendMs": 5000,+ "nativeTurnMs": 10000,+ "observeMs": 15000,+ "deliveryPassMs": 3000,+ "desktopPollMs": 3000,+ "hostTickMs": 1000+ },+ "text": {+ "briefChars": 3000,+ "resultChars": 600,+ "messageChars": 300+ }+ },+ "planDigest": "d078610a00b2c6bf2a87229331f63d895d3fce756698240b8624d4b9e2cfcc63",+ "setup": {+ "ms": 14741.571625,+ "calls": 458,+ "workers": 20,+ "activeGroups": 200,+ "doneGroups": 0+ },+ "load": {+ "plannedMs": 120000,+ "actualMs": 120280.514917,+ "skipped": {},+ "ops": [+ {+ "key": "deliveries.list",+ "count": 840,+ "ok": 840,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 30.417709000001196,+ "p95Ms": 63.00845900000422,+ "maxMs": 342.9375409999993,+ "bytes": null+ },+ {+ "key": "delivery.ack",+ "count": 548,+ "ok": 548,+ "conflicts": 2,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.69554199999766,+ "p95Ms": 48.50870799999393,+ "maxMs": 118.27300000000105,+ "bytes": null+ },+ {+ "key": "delivery.claim",+ "count": 548,+ "ok": 548,+ "conflicts": 12,+ "retriedCalls": 8,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.54670800000167,+ "p95Ms": 51.158290999999736,+ "maxMs": 714.5152500000004,+ "bytes": null+ },+ {+ "key": "message.send",+ "count": 339,+ "ok": 339,+ "conflicts": 3,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.01829100000032,+ "p95Ms": 57.36237500000425,+ "maxMs": 242.80491599999368,+ "bytes": null+ },+ {+ "key": "native.append",+ "count": 472,+ "ok": 472,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.82537500000035,+ "p95Ms": 61.94904200000019,+ "maxMs": 175.89262499999313,+ "bytes": null+ },+ {+ "key": "observeMachine",+ "count": 48,+ "ok": 48,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 30.251499999998487,+ "p95Ms": 40.57512500000303,+ "maxMs": 52.835499999986496,+ "bytes": null+ },+ {+ "key": "read.desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.0463749999908,+ "p95Ms": 55.93329100000847,+ "maxMs": 186.29333400000178,+ "bytes": {+ "mean": 467704,+ "p50": 372346,+ "p95": 807845,+ "total": 56124423+ }+ },+ {+ "key": "read.host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.581458000000566,+ "p95Ms": 72.69570799999929,+ "maxMs": 226.9855000000025,+ "bytes": {+ "mean": 321,+ "p50": 269,+ "p95": 269,+ "total": 76947+ }+ },+ {+ "key": "work.check",+ "count": 128,+ "ok": 128,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 35.42849999999453,+ "p95Ms": 49.0515000000014,+ "maxMs": 82.64904199999728,+ "bytes": null+ },+ {+ "key": "work.status",+ "count": 155,+ "ok": 155,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.361541999998735,+ "p95Ms": 53.0850000000064,+ "maxMs": 162.58133299999463,+ "bytes": null+ }+ ],+ "writerKinds": [+ {+ "key": "delivery",+ "count": 1936,+ "ok": 1936,+ "conflicts": 14,+ "retriedCalls": 10,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 33.31929200000013,+ "p95Ms": 51.59412499998871,+ "maxMs": 714.5152500000004,+ "bytes": null+ },+ {+ "key": "desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.0463749999908,+ "p95Ms": 55.93329100000847,+ "maxMs": 186.29333400000178,+ "bytes": {+ "mean": 467704,+ "p50": 372346,+ "p95": 807845,+ "total": 56124423+ }+ },+ {+ "key": "host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.581458000000566,+ "p95Ms": 72.69570799999929,+ "maxMs": 226.9855000000025,+ "bytes": {+ "mean": 321,+ "p50": 269,+ "p95": 269,+ "total": 76947+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.67362499999581,+ "p95Ms": 50.30745900000329,+ "maxMs": 147.4987919999985,+ "bytes": null+ },+ {+ "key": "machine",+ "count": 48,+ "ok": 48,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 30.251499999998487,+ "p95Ms": 40.57512500000303,+ "maxMs": 52.835499999986496,+ "bytes": null+ },+ {+ "key": "terminal",+ "count": 472,+ "ok": 472,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.82537500000035,+ "p95Ms": 61.94904200000019,+ "maxMs": 175.89262499999313,+ "bytes": null+ },+ {+ "key": "worker",+ "count": 596,+ "ok": 596,+ "conflicts": 5,+ "retriedCalls": 4,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.583041999998386,+ "p95Ms": 55.379791999999725,+ "maxMs": 242.80491599999368,+ "bytes": null+ }+ ],+ "writers": [+ {+ "key": "delivery-0",+ "count": 1228,+ "ok": 1228,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.26295899999968,+ "p95Ms": 53.099042000001646,+ "maxMs": 342.9375409999993,+ "bytes": null,+ "byOp": {+ "deliveries.list": 200,+ "delivery.claim": 514,+ "delivery.ack": 514+ }+ },+ {+ "key": "delivery-1",+ "count": 172,+ "ok": 172,+ "conflicts": 5,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 32.7768329999999,+ "p95Ms": 47.29316600000311,+ "maxMs": 714.5152500000004,+ "bytes": null,+ "byOp": {+ "deliveries.list": 160,+ "delivery.claim": 6,+ "delivery.ack": 6+ }+ },+ {+ "key": "delivery-2",+ "count": 128,+ "ok": 128,+ "conflicts": 5,+ "retriedCalls": 4,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 32.012541999996756,+ "p95Ms": 51.0590830000001,+ "maxMs": 235.57070799999929,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 4,+ "delivery.ack": 4+ }+ },+ {+ "key": "delivery-3",+ "count": 136,+ "ok": 136,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 30.94083399999363,+ "p95Ms": 43.98229199999696,+ "maxMs": 145.92345899999782,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 8,+ "delivery.ack": 8+ }+ },+ {+ "key": "delivery-4",+ "count": 144,+ "ok": 144,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 29.197165999998106,+ "p95Ms": 43.22583300000406,+ "maxMs": 125.11549999999988,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 12,+ "delivery.ack": 12+ }+ },+ {+ "key": "delivery-5",+ "count": 128,+ "ok": 128,+ "conflicts": 3,+ "retriedCalls": 3,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 29.350208000003477,+ "p95Ms": 48.07250000000931,+ "maxMs": 135.01833299999998,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 4,+ "delivery.ack": 4+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.67362499999581,+ "p95Ms": 50.30745900000329,+ "maxMs": 147.4987919999985,+ "bytes": null,+ "byOp": {+ "message.send": 26+ }+ },+ {+ "key": "machine-0",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.80620799999815,+ "p95Ms": 52.835499999986496,+ "maxMs": 52.835499999986496,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-1",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 29.477249999996275,+ "p95Ms": 39.87079100000119,+ "maxMs": 39.87079100000119,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-2",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 29.58466700000281,+ "p95Ms": 35.860292000026675,+ "maxMs": 35.860292000026675,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-3",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 30.425042000002577,+ "p95Ms": 43.12812500000291,+ "maxMs": 43.12812500000291,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-4",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 29.18974999999773,+ "p95Ms": 40.57512500000303,+ "maxMs": 40.57512500000303,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-5",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 29.33770799999911,+ "p95Ms": 33.782416999994894,+ "maxMs": 33.782416999994894,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "terminal-00",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.848958999995375,+ "p95Ms": 48.60124999999971,+ "maxMs": 60.457540999999765,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-01",+ "count": 20,+ "ok": 20,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.77637500000128,+ "p95Ms": 54.56858300000022,+ "maxMs": 56.63879099999758,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-02",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.379666000000725,+ "p95Ms": 58.48279199999524,+ "maxMs": 64.0905000000057,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-03",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.57766599999741,+ "p95Ms": 61.72133399999802,+ "maxMs": 61.77812499999709,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-04",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.078125,+ "p95Ms": 49.53983299999527,+ "maxMs": 49.78112499999406,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-05",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.770833999995375,+ "p95Ms": 57.31587500000023,+ "maxMs": 61.94904200000019,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-06",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.49712499999441,+ "p95Ms": 63.645707999996375,+ "maxMs": 67.86545800000022,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-07",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.631042000008165,+ "p95Ms": 60.70929199999955,+ "maxMs": 68.96212500002002,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-08",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.07887500000652,+ "p95Ms": 59.6182919999992,+ "maxMs": 66.3202089999977,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-09",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.73775000000023,+ "p95Ms": 57.62020800000755,+ "maxMs": 77.68841699999757,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-10",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.720458000010694,+ "p95Ms": 69.34937499999069,+ "maxMs": 74.56949999999779,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "terminal-11",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.13783300000068,+ "p95Ms": 62.548249999999825,+ "maxMs": 69.32733299999381,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-12",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.625874999997905,+ "p95Ms": 56.06812500000524,+ "maxMs": 57.54899999999907,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-13",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.348208000010345,+ "p95Ms": 52.50895799999853,+ "maxMs": 58.71579100000963,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-14",+ "count": 28,+ "ok": 28,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.61883399999715,+ "p95Ms": 64.56375000000116,+ "maxMs": 150.41091600000073,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "terminal-15",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.338374999992084,+ "p95Ms": 55.239832999999635,+ "maxMs": 67.74466699999903,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-16",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.49337499999092,+ "p95Ms": 55.99908300000243,+ "maxMs": 66.90504200000578,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-17",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.582709000009345,+ "p95Ms": 90.55391600000439,+ "maxMs": 101.99425000000338,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-18",+ "count": 20,+ "ok": 20,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.92083400000047,+ "p95Ms": 63.089874999997846,+ "maxMs": 175.89262499999313,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-19",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.72158299999137,+ "p95Ms": 64.43495899999834,+ "maxMs": 74.56262500000594,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "worker-00",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.966458999999304,+ "p95Ms": 47.25416700000642,+ "maxMs": 54.22270900000149,+ "bytes": null,+ "byOp": {+ "work.status": 10,+ "work.check": 7,+ "message.send": 12+ }+ },+ {+ "key": "worker-01",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.452125000003434,+ "p95Ms": 49.0515000000014,+ "maxMs": 140.46800000000803,+ "bytes": null,+ "byOp": {+ "work.status": 5,+ "message.send": 13,+ "work.check": 10+ }+ },+ {+ "key": "worker-02",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.28345799999079,+ "p95Ms": 59.98391700000502,+ "maxMs": 64.19654199999786,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 10,+ "work.check": 3+ }+ },+ {+ "key": "worker-03",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.25658299999486,+ "p95Ms": 51.27183399999922,+ "maxMs": 93.14166700000351,+ "bytes": null,+ "byOp": {+ "message.send": 18,+ "work.check": 9,+ "work.status": 3+ }+ },+ {+ "key": "worker-04",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.08529200000339,+ "p95Ms": 50.60337499999878,+ "maxMs": 54.550791999994544,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 11,+ "work.check": 5+ }+ },+ {+ "key": "worker-05",+ "count": 32,+ "ok": 32,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.85212499999761,+ "p95Ms": 126.74512500000128,+ "maxMs": 162.58133299999463,+ "bytes": null,+ "byOp": {+ "message.send": 14,+ "work.status": 10,+ "work.check": 8+ }+ },+ {+ "key": "worker-06",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.09545799999614,+ "p95Ms": 65.20258399999875,+ "maxMs": 72.99749999999767,+ "bytes": null,+ "byOp": {+ "message.send": 19,+ "work.status": 7,+ "work.check": 4+ }+ },+ {+ "key": "worker-07",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.02879199999734,+ "p95Ms": 43.82454200000211,+ "maxMs": 54.28975000001083,+ "bytes": null,+ "byOp": {+ "message.send": 11,+ "work.check": 7,+ "work.status": 11+ }+ },+ {+ "key": "worker-08",+ "count": 31,+ "ok": 31,+ "conflicts": 2,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.91525000000547,+ "p95Ms": 229.81366700000945,+ "maxMs": 242.80491599999368,+ "bytes": null,+ "byOp": {+ "work.status": 7,+ "message.send": 15,+ "work.check": 9+ }+ },+ {+ "key": "worker-09",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.13499999999476,+ "p95Ms": 53.71774999999616,+ "maxMs": 55.41866700000537,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 11,+ "work.status": 7+ }+ },+ {+ "key": "worker-10",+ "count": 33,+ "ok": 33,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.48179099999834,+ "p95Ms": 53.48345800000243,+ "maxMs": 59.95462499999849,+ "bytes": null,+ "byOp": {+ "message.send": 17,+ "work.check": 7,+ "work.status": 9+ }+ },+ {+ "key": "worker-11",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.67424999999639,+ "p95Ms": 90.85666700000002,+ "maxMs": 215.08970799999952,+ "bytes": null,+ "byOp": {+ "work.check": 4,+ "work.status": 5,+ "message.send": 20+ }+ },+ {+ "key": "worker-12",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.71725000000151,+ "p95Ms": 55.81837499998801,+ "maxMs": 65.56320899999992,+ "bytes": null,+ "byOp": {+ "work.status": 8,+ "message.send": 15,+ "work.check": 8+ }+ },+ {+ "key": "worker-13",+ "count": 27,+ "ok": 27,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.34445800000685,+ "p95Ms": 65.91575000000012,+ "maxMs": 74.09245799999917,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 8,+ "work.check": 4+ }+ },+ {+ "key": "worker-14",+ "count": 29,+ "ok": 29,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.43566700001247,+ "p95Ms": 48.81545799999731,+ "maxMs": 82.64904199999728,+ "bytes": null,+ "byOp": {+ "work.check": 5,+ "message.send": 17,+ "work.status": 7+ }+ },+ {+ "key": "worker-15",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.16800000000512,+ "p95Ms": 50.91954099999566,+ "maxMs": 64.4283749999995,+ "bytes": null,+ "byOp": {+ "work.status": 6,+ "message.send": 17,+ "work.check": 7+ }+ },+ {+ "key": "worker-16",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.219916999994894,+ "p95Ms": 51.529707999987295,+ "maxMs": 55.88716700000077,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 8,+ "work.check": 6+ }+ },+ {+ "key": "worker-17",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.68191699999443,+ "p95Ms": 53.0850000000064,+ "maxMs": 57.36237500000425,+ "bytes": null,+ "byOp": {+ "message.send": 20,+ "work.check": 4,+ "work.status": 5+ }+ },+ {+ "key": "worker-18",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.50495799999044,+ "p95Ms": 50.27495799999451,+ "maxMs": 88.36308299998927,+ "bytes": null,+ "byOp": {+ "work.status": 11,+ "message.send": 17,+ "work.check": 3+ }+ },+ {+ "key": "worker-19",+ "count": 27,+ "ok": 27,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.452332999993814,+ "p95Ms": 77.91629199999443,+ "maxMs": 123.34516699999222,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 7,+ "work.status": 7+ }+ }+ ],+ "readers": [+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.00554199999897,+ "p95Ms": 46.277915999999095,+ "maxMs": 55.21208299999125,+ "bytes": {+ "mean": 467622,+ "p50": 371364,+ "p95": 807272,+ "total": 18704869+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.538082999992184,+ "p95Ms": 65.46808299999975,+ "maxMs": 110.60841600000276,+ "bytes": {+ "mean": 470629,+ "p50": 372390,+ "p95": 807266,+ "total": 18825170+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.256583000009414,+ "p95Ms": 51.98245799999859,+ "maxMs": 186.29333400000178,+ "bytes": {+ "mean": 464860,+ "p50": 372281,+ "p95": 807845,+ "total": 18594384+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "host:bench-machine-0",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.50287500000559,+ "p95Ms": 64.54408300000068,+ "maxMs": 226.9855000000025,+ "bytes": {+ "mean": 325,+ "p50": 269,+ "p95": 269,+ "total": 39059+ },+ "byOp": {+ "read.host": 120+ }+ },+ {+ "key": "host:bench-machine-1",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.800208000000566,+ "p95Ms": 73.48579199999222,+ "maxMs": 120.02120899999863,+ "bytes": {+ "mean": 316,+ "p50": 269,+ "p95": 269,+ "total": 37888+ },+ "byOp": {+ "read.host": 120+ }+ }+ ]+ },+ "state": {+ "afterSetup": {+ "bytes": 901003,+ "documents": 237+ },+ "afterLoad": {+ "bytes": 924470,+ "documents": 237+ }+ },+ "isolatedPolls": [+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 355164,+ "databaseBytesOut": 458049,+ "ms": 29.448457999998936+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 359001,+ "databaseBytesOut": 462357,+ "ms": 23.260708999994677+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 347489,+ "databaseBytesOut": 449386,+ "ms": 22.605875000008382+ },+ {+ "reader": "host:bench-machine-0",+ "responseBytes": 268,+ "databaseBytesOut": 131380,+ "ms": 32.130750000011176+ },+ {+ "reader": "host:bench-machine-1",+ "responseBytes": 268,+ "databaseBytesOut": 83716,+ "ms": 25.54375000001164+ }+ ]+}diff --git a/backend/integration/bench/results/results-44d51aae8-mixed-1.json b/backend/integration/bench/results/results-44d51aae8-mixed-1.jsonnew file mode 100644index 000000000..2386e8e45--- /dev/null+++ b/backend/integration/bench/results/results-44d51aae8-mixed-1.json@@ -0,0 +1,1359 @@+{+ "benchmark": "swarm-state",+ "version": 1,+ "driver": "parts",+ "startedAt": "2026-10-26T16:43:33.539Z",+ "commit": {+ "sha": "4b8b5ea8a14e9019ac7d174986859afc4f23c84d",+ "dirty": false+ },+ "machine": {+ "platform": "darwin",+ "release": "25.6.0",+ "arch": "arm64",+ "cpu": "Apple M1 Max",+ "cpus": 10,+ "memoryGb": 64,+ "node": "24.18.0",+ "mongo": "7.0.24"+ },+ "config": {+ "seed": 1726,+ "groups": 200,+ "doneShare": 0.9,+ "workers": 20,+ "lane": "mixed",+ "machines": 6,+ "durationMs": 120000,+ "desktopReaders": 3,+ "hostReaders": 2,+ "mix": {+ "message.send": 2,+ "work.status": 1,+ "work.check": 1+ },+ "every": {+ "workerPostMs": 4000,+ "leadSendMs": 5000,+ "nativeTurnMs": 10000,+ "observeMs": 15000,+ "deliveryPassMs": 3000,+ "desktopPollMs": 3000,+ "hostTickMs": 1000+ },+ "text": {+ "briefChars": 3000,+ "resultChars": 600,+ "messageChars": 300+ }+ },+ "planDigest": "8ba3412b11e8239158b685f025f27eb4d02db893abf3a889b67194fc99766a2a",+ "setup": {+ "ms": 36810.009042,+ "calls": 1178,+ "workers": 20,+ "activeGroups": 20,+ "doneGroups": 180+ },+ "load": {+ "plannedMs": 120000,+ "actualMs": 121011.06175,+ "skipped": {},+ "ops": [+ {+ "key": "deliveries.list",+ "count": 840,+ "ok": 840,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.56054199999198,+ "p95Ms": 76.45691599999554,+ "maxMs": 261.66737499999726,+ "bytes": null+ },+ {+ "key": "delivery.ack",+ "count": 1006,+ "ok": 1006,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.32933399999456,+ "p95Ms": 70.39704199999687,+ "maxMs": 141.3632079999952,+ "bytes": null+ },+ {+ "key": "delivery.claim",+ "count": 1006,+ "ok": 1006,+ "conflicts": 11,+ "retriedCalls": 5,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.08462499998859,+ "p95Ms": 69.80466700001853,+ "maxMs": 411.421875,+ "bytes": null+ },+ {+ "key": "message.send",+ "count": 339,+ "ok": 339,+ "conflicts": 5,+ "retriedCalls": 4,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.73683300000266,+ "p95Ms": 88.11100000000442,+ "maxMs": 237.50095899999724,+ "bytes": null+ },+ {+ "key": "native.append",+ "count": 472,+ "ok": 472,+ "conflicts": 2,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 57.393167000001995,+ "p95Ms": 91.52908299998671,+ "maxMs": 171.4899999999907,+ "bytes": null+ },+ {+ "key": "observeMachine",+ "count": 48,+ "ok": 48,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.9586249999993,+ "p95Ms": 53.69329199998174,+ "maxMs": 93.97200000000885,+ "bytes": null+ },+ {+ "key": "read.desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.484041000003344,+ "p95Ms": 81.03195800000685,+ "maxMs": 103.6390830000164,+ "bytes": {+ "mean": 239109,+ "p50": 112324,+ "p95": 879373,+ "total": 28693048+ }+ },+ {+ "key": "read.host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.78504200000316,+ "p95Ms": 91.15829200000735,+ "maxMs": 114.25070800000685,+ "bytes": {+ "mean": 321,+ "p50": 269,+ "p95": 269,+ "total": 76947+ }+ },+ {+ "key": "work.check",+ "count": 128,+ "ok": 128,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.499875000008615,+ "p95Ms": 83.13595799999894,+ "maxMs": 118.47000000000116,+ "bytes": null+ },+ {+ "key": "work.status",+ "count": 155,+ "ok": 155,+ "conflicts": 2,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.35775000000285,+ "p95Ms": 81.67874999999185,+ "maxMs": 173.11837499999092,+ "bytes": null+ }+ ],+ "writerKinds": [+ {+ "key": "delivery",+ "count": 2852,+ "ok": 2852,+ "conflicts": 12,+ "retriedCalls": 6,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.31362500000978,+ "p95Ms": 71.01891699999396,+ "maxMs": 411.421875,+ "bytes": null+ },+ {+ "key": "desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.484041000003344,+ "p95Ms": 81.03195800000685,+ "maxMs": 103.6390830000164,+ "bytes": {+ "mean": 239109,+ "p50": 112324,+ "p95": 879373,+ "total": 28693048+ }+ },+ {+ "key": "host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.78504200000316,+ "p95Ms": 91.15829200000735,+ "maxMs": 114.25070800000685,+ "bytes": {+ "mean": 321,+ "p50": 269,+ "p95": 269,+ "total": 76947+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.03399999999965,+ "p95Ms": 80.64295800001128,+ "maxMs": 119.57566699999734,+ "bytes": null+ },+ {+ "key": "machine",+ "count": 48,+ "ok": 48,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.9586249999993,+ "p95Ms": 53.69329199998174,+ "maxMs": 93.97200000000885,+ "bytes": null+ },+ {+ "key": "terminal",+ "count": 472,+ "ok": 472,+ "conflicts": 2,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 57.393167000001995,+ "p95Ms": 91.52908299998671,+ "maxMs": 171.4899999999907,+ "bytes": null+ },+ {+ "key": "worker",+ "count": 596,+ "ok": 596,+ "conflicts": 8,+ "retriedCalls": 6,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.91783299998497,+ "p95Ms": 85.5494580000086,+ "maxMs": 237.50095899999724,+ "bytes": null+ }+ ],+ "writers": [+ {+ "key": "delivery-0",+ "count": 2144,+ "ok": 2144,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.4048749999929,+ "p95Ms": 72.4706249999872,+ "maxMs": 261.66737499999726,+ "bytes": null,+ "byOp": {+ "deliveries.list": 200,+ "delivery.claim": 972,+ "delivery.ack": 972+ }+ },+ {+ "key": "delivery-1",+ "count": 172,+ "ok": 172,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.11979199999769,+ "p95Ms": 69.13949999999022,+ "maxMs": 130.88754099999642,+ "bytes": null,+ "byOp": {+ "deliveries.list": 160,+ "delivery.claim": 6,+ "delivery.ack": 6+ }+ },+ {+ "key": "delivery-2",+ "count": 128,+ "ok": 128,+ "conflicts": 6,+ "retriedCalls": 3,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.51391599999624,+ "p95Ms": 79.10324999998556,+ "maxMs": 411.421875,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 4,+ "delivery.ack": 4+ }+ },+ {+ "key": "delivery-3",+ "count": 136,+ "ok": 136,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.93266700000095,+ "p95Ms": 57.007500000006985,+ "maxMs": 77.17541599998367,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 8,+ "delivery.ack": 8+ }+ },+ {+ "key": "delivery-4",+ "count": 144,+ "ok": 144,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.42545899999095,+ "p95Ms": 57.23779099999956,+ "maxMs": 111.98629100000835,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 12,+ "delivery.ack": 12+ }+ },+ {+ "key": "delivery-5",+ "count": 128,+ "ok": 128,+ "conflicts": 5,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.50512499999604,+ "p95Ms": 55.689291999995476,+ "maxMs": 382.8534579999978,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 4,+ "delivery.ack": 4+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.03399999999965,+ "p95Ms": 80.64295800001128,+ "maxMs": 119.57566699999734,+ "bytes": null,+ "byOp": {+ "message.send": 26+ }+ },+ {+ "key": "machine-0",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.228916000021854,+ "p95Ms": 93.97200000000885,+ "maxMs": 93.97200000000885,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-1",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 40.34799999999814,+ "p95Ms": 47.931666999997105,+ "maxMs": 47.931666999997105,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-2",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.08299999999872,+ "p95Ms": 49.69949999998789,+ "maxMs": 49.69949999998789,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-3",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.53525000001537,+ "p95Ms": 47.17849999999453,+ "maxMs": 47.17849999999453,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-4",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.04991699999664,+ "p95Ms": 46.981667000000016,+ "maxMs": 46.981667000000016,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-5",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.505583000020124,+ "p95Ms": 68.05729199998314,+ "maxMs": 68.05729199998314,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "terminal-00",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 51.97333400000207,+ "p95Ms": 82.49554199999693,+ "maxMs": 102.69599999999627,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-01",+ "count": 20,+ "ok": 20,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 58.62575000000652,+ "p95Ms": 86.60420800000429,+ "maxMs": 99.93349999999919,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-02",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 62.285125000002154,+ "p95Ms": 86.62875000000349,+ "maxMs": 87.94366599999194,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-03",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 64.5254169999971,+ "p95Ms": 102.52587499999936,+ "maxMs": 115.59170799999265,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-04",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 54.81625000000349,+ "p95Ms": 99.94604099998833,+ "maxMs": 116.37887499999488,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-05",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 55.462375000002794,+ "p95Ms": 72.0644159999938,+ "maxMs": 74.70733399999153,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-06",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.71908300000359,+ "p95Ms": 88.49037500002305,+ "maxMs": 107.75724999999511,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-07",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 57.1263750000071,+ "p95Ms": 74.46570800000336,+ "maxMs": 95.50645800000348,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-08",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.839291000011144,+ "p95Ms": 84.56562500000291,+ "maxMs": 85.37387500000477,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-09",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 58.84625000000233,+ "p95Ms": 90.08404100000189,+ "maxMs": 92.04145800000697,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-10",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.15120799999568,+ "p95Ms": 81.43037499999627,+ "maxMs": 102.25241700001061,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "terminal-11",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 60.491582999995444,+ "p95Ms": 101.73645900000702,+ "maxMs": 103.01408399999491,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-12",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 58.140125000005355,+ "p95Ms": 91.52908299998671,+ "maxMs": 115.11912499999744,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-13",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 54.54020899999887,+ "p95Ms": 85.39020799999707,+ "maxMs": 96.47154199999932,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-14",+ "count": 28,+ "ok": 28,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 58.41104199999245,+ "p95Ms": 133.50554099999135,+ "maxMs": 157.50962500000605,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "terminal-15",+ "count": 22,+ "ok": 22,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 58.3681660000002,+ "p95Ms": 128.42829099998926,+ "maxMs": 171.4899999999907,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-16",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 57.781833000000915,+ "p95Ms": 83.8998750000028,+ "maxMs": 91.72704199998407,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-17",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 58.39487499999814,+ "p95Ms": 71.19912499998463,+ "maxMs": 128.4475000000093,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-18",+ "count": 20,+ "ok": 20,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.78666599999997,+ "p95Ms": 70.05845900002168,+ "maxMs": 71.19154200000048,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-19",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 57.33208300000115,+ "p95Ms": 114.62795899997582,+ "maxMs": 128.22283300000709,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "worker-00",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.99154099999578,+ "p95Ms": 77.67145899999741,+ "maxMs": 79.87925000000541,+ "bytes": null,+ "byOp": {+ "work.status": 10,+ "work.check": 7,+ "message.send": 12+ }+ },+ {+ "key": "worker-01",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 51.03804100000707,+ "p95Ms": 79.19187500000407,+ "maxMs": 86.94287500000792,+ "bytes": null,+ "byOp": {+ "work.status": 5,+ "message.send": 13,+ "work.check": 10+ }+ },+ {+ "key": "worker-02",+ "count": 29,+ "ok": 29,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.08079199999338,+ "p95Ms": 88.11100000000442,+ "maxMs": 138.85095799999544,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 10,+ "work.check": 3+ }+ },+ {+ "key": "worker-03",+ "count": 30,+ "ok": 30,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.51091599999927,+ "p95Ms": 76.45845899998676,+ "maxMs": 124.13787500000035,+ "bytes": null,+ "byOp": {+ "message.send": 18,+ "work.check": 9,+ "work.status": 3+ }+ },+ {+ "key": "worker-04",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.911417000002984,+ "p95Ms": 78.38474999999744,+ "maxMs": 93.80333300000348,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 11,+ "work.check": 5+ }+ },+ {+ "key": "worker-05",+ "count": 32,+ "ok": 32,+ "conflicts": 2,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.55874999999651,+ "p95Ms": 106.90262499998789,+ "maxMs": 173.11837499999092,+ "bytes": null,+ "byOp": {+ "message.send": 14,+ "work.status": 10,+ "work.check": 8+ }+ },+ {+ "key": "worker-06",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.68208400000003,+ "p95Ms": 85.61104100002558,+ "maxMs": 109.87504099999933,+ "bytes": null,+ "byOp": {+ "message.send": 19,+ "work.status": 7,+ "work.check": 4+ }+ },+ {+ "key": "worker-07",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.40045799998916,+ "p95Ms": 65.85108299998683,+ "maxMs": 67.80737500000396,+ "bytes": null,+ "byOp": {+ "message.send": 11,+ "work.check": 7,+ "work.status": 11+ }+ },+ {+ "key": "worker-08",+ "count": 31,+ "ok": 31,+ "conflicts": 2,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.499875000008615,+ "p95Ms": 59.01774999999907,+ "maxMs": 237.50095899999724,+ "bytes": null,+ "byOp": {+ "work.status": 7,+ "message.send": 15,+ "work.check": 9+ }+ },+ {+ "key": "worker-09",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.43462499999441,+ "p95Ms": 75.02049999999872,+ "maxMs": 121.98333300001104,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 11,+ "work.status": 7+ }+ },+ {+ "key": "worker-10",+ "count": 33,+ "ok": 33,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.5020829999994,+ "p95Ms": 106.41666700001224,+ "maxMs": 108.95270900000469,+ "bytes": null,+ "byOp": {+ "message.send": 17,+ "work.check": 7,+ "work.status": 9+ }+ },+ {+ "key": "worker-11",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.36233300001186,+ "p95Ms": 87.18374999999651,+ "maxMs": 114.50608400002238,+ "bytes": null,+ "byOp": {+ "work.check": 4,+ "work.status": 5,+ "message.send": 20+ }+ },+ {+ "key": "worker-12",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.018459000013536,+ "p95Ms": 100.37808299998869,+ "maxMs": 109.15545799999381,+ "bytes": null,+ "byOp": {+ "work.status": 8,+ "message.send": 15,+ "work.check": 8+ }+ },+ {+ "key": "worker-13",+ "count": 27,+ "ok": 27,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.25441699998919,+ "p95Ms": 102.2052079999994,+ "maxMs": 105.2455829999817,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 8,+ "work.check": 4+ }+ },+ {+ "key": "worker-14",+ "count": 29,+ "ok": 29,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.931291999993846,+ "p95Ms": 77.18062500000087,+ "maxMs": 118.47000000000116,+ "bytes": null,+ "byOp": {+ "work.check": 5,+ "message.send": 17,+ "work.status": 7+ }+ },+ {+ "key": "worker-15",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.687375000008615,+ "p95Ms": 85.94766599999275,+ "maxMs": 107.99591699999291,+ "bytes": null,+ "byOp": {+ "work.status": 6,+ "message.send": 17,+ "work.check": 7+ }+ },+ {+ "key": "worker-16",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 57.802249999993364,+ "p95Ms": 72.94295899999997,+ "maxMs": 94.01979100001336,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 8,+ "work.check": 6+ }+ },+ {+ "key": "worker-17",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.48433299997123,+ "p95Ms": 81.67874999999185,+ "maxMs": 86.31208299999707,+ "bytes": null,+ "byOp": {+ "message.send": 20,+ "work.check": 4,+ "work.status": 5+ }+ },+ {+ "key": "worker-18",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.156833000000915,+ "p95Ms": 78.64595799997915,+ "maxMs": 108.59608399998979,+ "bytes": null,+ "byOp": {+ "work.status": 11,+ "message.send": 17,+ "work.check": 3+ }+ },+ {+ "key": "worker-19",+ "count": 27,+ "ok": 27,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.30070799999521,+ "p95Ms": 83.13595799999894,+ "maxMs": 89.53433300000324,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 7,+ "work.status": 7+ }+ }+ ],+ "readers": [+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 39.046457999997074,+ "p95Ms": 79.96158299999661,+ "maxMs": 92.24279200000456,+ "bytes": {+ "mean": 240002,+ "p50": 112324,+ "p95": 863993,+ "total": 9600083+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 54.44408299999486,+ "p95Ms": 81.93220899999869,+ "maxMs": 93.247749999995,+ "bytes": {+ "mean": 243283,+ "p50": 112155,+ "p95": 879373,+ "total": 9731303+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.38637500000186,+ "p95Ms": 59.97966699999961,+ "maxMs": 103.6390830000164,+ "bytes": {+ "mean": 234042,+ "p50": 112155,+ "p95": 839812,+ "total": 9361662+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "host:bench-machine-0",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.94170799999847,+ "p95Ms": 82.86929200000304,+ "maxMs": 103.07037499999569,+ "bytes": {+ "mean": 325,+ "p50": 269,+ "p95": 269,+ "total": 39059+ },+ "byOp": {+ "read.host": 120+ }+ },+ {+ "key": "host:bench-machine-1",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.16133400000399,+ "p95Ms": 98.6086670000077,+ "maxMs": 114.25070800000685,+ "bytes": {+ "mean": 316,+ "p50": 269,+ "p95": 269,+ "total": 37888+ },+ "byOp": {+ "read.host": 120+ }+ }+ ]+ },+ "state": {+ "afterSetup": {+ "bytes": 1174606,+ "documents": 237+ },+ "afterLoad": {+ "bytes": 1198073,+ "documents": 237+ }+ },+ "isolatedPolls": [+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 113508,+ "databaseBytesOut": 185547,+ "ms": 23.125291999982437+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 113508,+ "databaseBytesOut": 185547,+ "ms": 24.159874999983003+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 113508,+ "databaseBytesOut": 185547,+ "ms": 23.840374999999767+ },+ {+ "reader": "host:bench-machine-0",+ "responseBytes": 268,+ "databaseBytesOut": 141310,+ "ms": 27.599416999990353+ },+ {+ "reader": "host:bench-machine-1",+ "responseBytes": 268,+ "databaseBytesOut": 85727,+ "ms": 26.558583999983966+ }+ ]+}diff --git a/backend/integration/bench/results/results-44d51aae8-mixed-2.json b/backend/integration/bench/results/results-44d51aae8-mixed-2.jsonnew file mode 100644index 000000000..1ce5d1dc0--- /dev/null+++ b/backend/integration/bench/results/results-44d51aae8-mixed-2.json@@ -0,0 +1,1359 @@+{+ "benchmark": "swarm-state",+ "version": 1,+ "driver": "parts",+ "startedAt": "2026-10-26T16:46:20.024Z",+ "commit": {+ "sha": "4b8b5ea8a14e9019ac7d174986859afc4f23c84d",+ "dirty": false+ },+ "machine": {+ "platform": "darwin",+ "release": "25.6.0",+ "arch": "arm64",+ "cpu": "Apple M1 Max",+ "cpus": 10,+ "memoryGb": 64,+ "node": "24.18.0",+ "mongo": "7.0.24"+ },+ "config": {+ "seed": 1726,+ "groups": 200,+ "doneShare": 0.9,+ "workers": 20,+ "lane": "mixed",+ "machines": 6,+ "durationMs": 120000,+ "desktopReaders": 3,+ "hostReaders": 2,+ "mix": {+ "message.send": 2,+ "work.status": 1,+ "work.check": 1+ },+ "every": {+ "workerPostMs": 4000,+ "leadSendMs": 5000,+ "nativeTurnMs": 10000,+ "observeMs": 15000,+ "deliveryPassMs": 3000,+ "desktopPollMs": 3000,+ "hostTickMs": 1000+ },+ "text": {+ "briefChars": 3000,+ "resultChars": 600,+ "messageChars": 300+ }+ },+ "planDigest": "8ba3412b11e8239158b685f025f27eb4d02db893abf3a889b67194fc99766a2a",+ "setup": {+ "ms": 37375.918458,+ "calls": 1178,+ "workers": 20,+ "activeGroups": 20,+ "doneGroups": 180+ },+ "load": {+ "plannedMs": 120000,+ "actualMs": 120951.074292,+ "skipped": {},+ "ops": [+ {+ "key": "deliveries.list",+ "count": 840,+ "ok": 840,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.75620899999922,+ "p95Ms": 63.23933399999805,+ "maxMs": 288.9312920000011,+ "bytes": null+ },+ {+ "key": "delivery.ack",+ "count": 1006,+ "ok": 1006,+ "conflicts": 2,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.59962499998801,+ "p95Ms": 57.56666700000642,+ "maxMs": 146.37433299999975,+ "bytes": null+ },+ {+ "key": "delivery.claim",+ "count": 1006,+ "ok": 1006,+ "conflicts": 8,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.46395800000755,+ "p95Ms": 58.41074999999546,+ "maxMs": 752.9817079999993,+ "bytes": null+ },+ {+ "key": "message.send",+ "count": 339,+ "ok": 339,+ "conflicts": 3,+ "retriedCalls": 3,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.88345799999661,+ "p95Ms": 82.93820800000685,+ "maxMs": 207.67229100000986,+ "bytes": null+ },+ {+ "key": "native.append",+ "count": 472,+ "ok": 472,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.598540999999386,+ "p95Ms": 83.05200000000332,+ "maxMs": 130.3256670000119,+ "bytes": null+ },+ {+ "key": "observeMachine",+ "count": 48,+ "ok": 48,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.786209000012605,+ "p95Ms": 49.30062500000349,+ "maxMs": 59.41420800000196,+ "bytes": null+ },+ {+ "key": "read.desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.055374999996275,+ "p95Ms": 62.10987500000192,+ "maxMs": 84.97050000000309,+ "bytes": {+ "mean": 242417,+ "p50": 112324,+ "p95": 895355,+ "total": 29090074+ }+ },+ {+ "key": "read.host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.68054200001643,+ "p95Ms": 79.91175000000658,+ "maxMs": 119.58304199999839,+ "bytes": {+ "mean": 321,+ "p50": 269,+ "p95": 269,+ "total": 76947+ }+ },+ {+ "key": "work.check",+ "count": 128,+ "ok": 128,+ "conflicts": 3,+ "retriedCalls": 3,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.76049999999668,+ "p95Ms": 66.53808299999218,+ "maxMs": 131.1140000000014,+ "bytes": null+ },+ {+ "key": "work.status",+ "count": 155,+ "ok": 155,+ "conflicts": 3,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.869542000000365,+ "p95Ms": 74.6397500000021,+ "maxMs": 201.60175000000163,+ "bytes": null+ }+ ],+ "writerKinds": [+ {+ "key": "delivery",+ "count": 2852,+ "ok": 2852,+ "conflicts": 10,+ "retriedCalls": 3,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.163916000004974,+ "p95Ms": 59.942207999993116,+ "maxMs": 752.9817079999993,+ "bytes": null+ },+ {+ "key": "desktop",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.055374999996275,+ "p95Ms": 62.10987500000192,+ "maxMs": 84.97050000000309,+ "bytes": {+ "mean": 242417,+ "p50": 112324,+ "p95": 895355,+ "total": 29090074+ }+ },+ {+ "key": "host",+ "count": 240,+ "ok": 240,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.68054200001643,+ "p95Ms": 79.91175000000658,+ "maxMs": 119.58304199999839,+ "bytes": {+ "mean": 321,+ "p50": 269,+ "p95": 269,+ "total": 76947+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.70433400000911,+ "p95Ms": 80.09741699999722,+ "maxMs": 131.15783300000476,+ "bytes": null+ },+ {+ "key": "machine",+ "count": 48,+ "ok": 48,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.786209000012605,+ "p95Ms": 49.30062500000349,+ "maxMs": 59.41420800000196,+ "bytes": null+ },+ {+ "key": "terminal",+ "count": 472,+ "ok": 472,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.598540999999386,+ "p95Ms": 83.05200000000332,+ "maxMs": 130.3256670000119,+ "bytes": null+ },+ {+ "key": "worker",+ "count": 596,+ "ok": 596,+ "conflicts": 9,+ "retriedCalls": 8,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.77154100000189,+ "p95Ms": 76.19604199999594,+ "maxMs": 207.67229100000986,+ "bytes": null+ }+ ],+ "writers": [+ {+ "key": "delivery-0",+ "count": 2144,+ "ok": 2144,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.433875000002445,+ "p95Ms": 61.05504199999996,+ "maxMs": 288.9312920000011,+ "bytes": null,+ "byOp": {+ "deliveries.list": 200,+ "delivery.claim": 972,+ "delivery.ack": 972+ }+ },+ {+ "key": "delivery-1",+ "count": 172,+ "ok": 172,+ "conflicts": 3,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.9877919999999,+ "p95Ms": 61.1751660000009,+ "maxMs": 464.36270800000057,+ "bytes": null,+ "byOp": {+ "deliveries.list": 160,+ "delivery.claim": 6,+ "delivery.ack": 6+ }+ },+ {+ "key": "delivery-2",+ "count": 128,+ "ok": 128,+ "conflicts": 7,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.95183399999223,+ "p95Ms": 62.80229200000031,+ "maxMs": 752.9817079999993,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 4,+ "delivery.ack": 4+ }+ },+ {+ "key": "delivery-3",+ "count": 136,+ "ok": 136,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.580958999998984,+ "p95Ms": 55.021082999999635,+ "maxMs": 83.67979199999536,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 8,+ "delivery.ack": 8+ }+ },+ {+ "key": "delivery-4",+ "count": 144,+ "ok": 144,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.4333750000078,+ "p95Ms": 50.84224999999424,+ "maxMs": 64.10704200000328,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 12,+ "delivery.ack": 12+ }+ },+ {+ "key": "delivery-5",+ "count": 128,+ "ok": 128,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.422915999995894,+ "p95Ms": 50.56524999999965,+ "maxMs": 69.43312499999593,+ "bytes": null,+ "byOp": {+ "deliveries.list": 120,+ "delivery.claim": 4,+ "delivery.ack": 4+ }+ },+ {+ "key": "lead",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.70433400000911,+ "p95Ms": 80.09741699999722,+ "maxMs": 131.15783300000476,+ "bytes": null,+ "byOp": {+ "message.send": 26+ }+ },+ {+ "key": "machine-0",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.48225000000093,+ "p95Ms": 57.57941700000083,+ "maxMs": 57.57941700000083,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-1",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 38.058416999992914,+ "p95Ms": 46.88262499999837,+ "maxMs": 46.88262499999837,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-2",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 37.786209000012605,+ "p95Ms": 49.30062500000349,+ "maxMs": 49.30062500000349,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-3",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 35.75754099999904,+ "p95Ms": 47.643249999993714,+ "maxMs": 47.643249999993714,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-4",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 35.57662500000151,+ "p95Ms": 44.9312920000084,+ "maxMs": 44.9312920000084,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "machine-5",+ "count": 8,+ "ok": 8,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 34.34987499998533,+ "p95Ms": 59.41420800000196,+ "maxMs": 59.41420800000196,+ "bytes": null,+ "byOp": {+ "observeMachine": 8+ }+ },+ {+ "key": "terminal-00",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 53.650167000014335,+ "p95Ms": 71.45254199999908,+ "maxMs": 80.78370800000266,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-01",+ "count": 20,+ "ok": 20,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 56.51329199998872,+ "p95Ms": 80.89308300000266,+ "maxMs": 119.03112500000861,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-02",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 55.96091599998181,+ "p95Ms": 71.88999999999942,+ "maxMs": 106.94362499999988,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-03",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 60.44662500001141,+ "p95Ms": 86.12154200000077,+ "maxMs": 87.43491600000561,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-04",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.80529099999694,+ "p95Ms": 65.40954200000851,+ "maxMs": 80.02412499999627,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-05",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.775124999985565,+ "p95Ms": 80.9323749999894,+ "maxMs": 108.66462500000489,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-06",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.022208000009414,+ "p95Ms": 72.44062499998836,+ "maxMs": 88.92075000001932,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-07",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.66670800000429,+ "p95Ms": 76.1711670000077,+ "maxMs": 96.39375000000291,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-08",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 51.551582999993116,+ "p95Ms": 81.9230830000015,+ "maxMs": 84.69779099999869,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-09",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 58.812917000002926,+ "p95Ms": 83.05200000000332,+ "maxMs": 107.1892089999892,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-10",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.513999999995576,+ "p95Ms": 77.38262499999837,+ "maxMs": 85.53433300000324,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "terminal-11",+ "count": 26,+ "ok": 26,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.24133299999812,+ "p95Ms": 85.62816699998803,+ "maxMs": 93.56445800000074,+ "bytes": null,+ "byOp": {+ "native.append": 26+ }+ },+ {+ "key": "terminal-12",+ "count": 24,+ "ok": 24,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.85495800001081,+ "p95Ms": 77.12033299999894,+ "maxMs": 88.33587500000431,+ "bytes": null,+ "byOp": {+ "native.append": 24+ }+ },+ {+ "key": "terminal-13",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.14045800000895,+ "p95Ms": 67.94862500000454,+ "maxMs": 83.3028750000085,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-14",+ "count": 28,+ "ok": 28,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.34308400000009,+ "p95Ms": 87.617957999988,+ "maxMs": 130.3256670000119,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "terminal-15",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.22387499999604,+ "p95Ms": 68.38624999999593,+ "maxMs": 70.45395900000585,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-16",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.72554100000707,+ "p95Ms": 70.15774999999849,+ "maxMs": 74.10391700000037,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-17",+ "count": 22,+ "ok": 22,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 54.213209000008646,+ "p95Ms": 89.68362500000512,+ "maxMs": 91.18279099999927,+ "bytes": null,+ "byOp": {+ "native.append": 22+ }+ },+ {+ "key": "terminal-18",+ "count": 20,+ "ok": 20,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.25079100000585,+ "p95Ms": 68.2309580000001,+ "maxMs": 91.4544590000005,+ "bytes": null,+ "byOp": {+ "native.append": 20+ }+ },+ {+ "key": "terminal-19",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.6086670000077,+ "p95Ms": 94.51358400000026,+ "maxMs": 115.74279200000456,+ "bytes": null,+ "byOp": {+ "native.append": 28+ }+ },+ {+ "key": "worker-00",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.52279100001033,+ "p95Ms": 65.15020899999945,+ "maxMs": 75.02558300000237,+ "bytes": null,+ "byOp": {+ "work.status": 10,+ "work.check": 7,+ "message.send": 12+ }+ },+ {+ "key": "worker-01",+ "count": 28,+ "ok": 28,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.67562499998894,+ "p95Ms": 68.78937500000757,+ "maxMs": 79.17929200000071,+ "bytes": null,+ "byOp": {+ "work.status": 5,+ "message.send": 13,+ "work.check": 10+ }+ },+ {+ "key": "worker-02",+ "count": 29,+ "ok": 29,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.22779200000514,+ "p95Ms": 78.15533299999515,+ "maxMs": 123.8763340000005,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 10,+ "work.check": 3+ }+ },+ {+ "key": "worker-03",+ "count": 30,+ "ok": 30,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 44.35599999999977,+ "p95Ms": 82.93820800000685,+ "maxMs": 207.67229100000986,+ "bytes": null,+ "byOp": {+ "message.send": 18,+ "work.check": 9,+ "work.status": 3+ }+ },+ {+ "key": "worker-04",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.6310000000085,+ "p95Ms": 73.47291699999187,+ "maxMs": 110.14120900000125,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 11,+ "work.check": 5+ }+ },+ {+ "key": "worker-05",+ "count": 32,+ "ok": 32,+ "conflicts": 3,+ "retriedCalls": 2,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.97629200000665,+ "p95Ms": 131.1140000000014,+ "maxMs": 201.60175000000163,+ "bytes": null,+ "byOp": {+ "message.send": 14,+ "work.status": 10,+ "work.check": 8+ }+ },+ {+ "key": "worker-06",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.88479099998949,+ "p95Ms": 88.61962500000664,+ "maxMs": 100.38712500000838,+ "bytes": null,+ "byOp": {+ "message.send": 19,+ "work.status": 7,+ "work.check": 4+ }+ },+ {+ "key": "worker-07",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 42.2941249999858,+ "p95Ms": 60.54899999999907,+ "maxMs": 64.22095799999079,+ "bytes": null,+ "byOp": {+ "message.send": 11,+ "work.check": 7,+ "work.status": 11+ }+ },+ {+ "key": "worker-08",+ "count": 31,+ "ok": 31,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 47.159374999995634,+ "p95Ms": 87.64070799999172,+ "maxMs": 166.5745420000021,+ "bytes": null,+ "byOp": {+ "work.status": 7,+ "message.send": 15,+ "work.check": 9+ }+ },+ {+ "key": "worker-09",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.19137499999488,+ "p95Ms": 65.5897920000134,+ "maxMs": 122.10383300000103,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 11,+ "work.status": 7+ }+ },+ {+ "key": "worker-10",+ "count": 33,+ "ok": 33,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 51.253333000000566,+ "p95Ms": 75.94541700000991,+ "maxMs": 95.48820900000283,+ "bytes": null,+ "byOp": {+ "message.send": 17,+ "work.check": 7,+ "work.status": 9+ }+ },+ {+ "key": "worker-11",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 48.61979199999769,+ "p95Ms": 76.60333399999945,+ "maxMs": 90.45374999998603,+ "bytes": null,+ "byOp": {+ "work.check": 4,+ "work.status": 5,+ "message.send": 20+ }+ },+ {+ "key": "worker-12",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.61304199999722,+ "p95Ms": 82.84412500000326,+ "maxMs": 103.38133300002664,+ "bytes": null,+ "byOp": {+ "work.status": 8,+ "message.send": 15,+ "work.check": 8+ }+ },+ {+ "key": "worker-13",+ "count": 27,+ "ok": 27,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 50.961083999995026,+ "p95Ms": 85.03908299999603,+ "maxMs": 109.38100000002305,+ "bytes": null,+ "byOp": {+ "message.send": 15,+ "work.status": 8,+ "work.check": 4+ }+ },+ {+ "key": "worker-14",+ "count": 29,+ "ok": 29,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 49.70491700001003,+ "p95Ms": 65.70645799998601,+ "maxMs": 122.1943750000064,+ "bytes": null,+ "byOp": {+ "work.check": 5,+ "message.send": 17,+ "work.status": 7+ }+ },+ {+ "key": "worker-15",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.70754099999613,+ "p95Ms": 85.428041999985,+ "maxMs": 86.07616599999892,+ "bytes": null,+ "byOp": {+ "work.status": 6,+ "message.send": 17,+ "work.check": 7+ }+ },+ {+ "key": "worker-16",+ "count": 30,+ "ok": 30,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 52.223916000002646,+ "p95Ms": 76.74620799999684,+ "maxMs": 82.78066699999908,+ "bytes": null,+ "byOp": {+ "message.send": 16,+ "work.status": 8,+ "work.check": 6+ }+ },+ {+ "key": "worker-17",+ "count": 29,+ "ok": 29,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 46.981583999993745,+ "p95Ms": 76.19604199999594,+ "maxMs": 76.91166599999997,+ "bytes": null,+ "byOp": {+ "message.send": 20,+ "work.check": 4,+ "work.status": 5+ }+ },+ {+ "key": "worker-18",+ "count": 31,+ "ok": 31,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.638041000005614,+ "p95Ms": 73.91279200000281,+ "maxMs": 75.83512499998324,+ "bytes": null,+ "byOp": {+ "work.status": 11,+ "message.send": 17,+ "work.check": 3+ }+ },+ {+ "key": "worker-19",+ "count": 27,+ "ok": 27,+ "conflicts": 1,+ "retriedCalls": 1,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.70241699999315,+ "p95Ms": 71.22783300000447,+ "maxMs": 112.80595799999719,+ "bytes": null,+ "byOp": {+ "message.send": 13,+ "work.check": 7,+ "work.status": 7+ }+ }+ ],+ "readers": [+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.40287499999977,+ "p95Ms": 49.64199999999255,+ "maxMs": 52.96879199999967,+ "bytes": {+ "mean": 243240,+ "p50": 112324,+ "p95": 879971,+ "total": 9729598+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 45.972540999995545,+ "p95Ms": 66.29674999999406,+ "maxMs": 84.97050000000309,+ "bytes": {+ "mean": 246879,+ "p50": 112155,+ "p95": 895355,+ "total": 9875147+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "desktop:[email protected]",+ "count": 40,+ "ok": 40,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 36.59091699999408,+ "p95Ms": 59.47241699998267,+ "maxMs": 84.4465840000048,+ "bytes": {+ "mean": 237133,+ "p50": 112155,+ "p95": 855792,+ "total": 9485329+ },+ "byOp": {+ "read.desktop": 40+ }+ },+ {+ "key": "host:bench-machine-0",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 43.241208000006736,+ "p95Ms": 72.87387500001932,+ "maxMs": 107.63020800000231,+ "bytes": {+ "mean": 325,+ "p50": 269,+ "p95": 269,+ "total": 39059+ },+ "byOp": {+ "read.host": 120+ }+ },+ {+ "key": "host:bench-machine-1",+ "count": 120,+ "ok": 120,+ "conflicts": 0,+ "retriedCalls": 0,+ "swarmBusy": 0,+ "errors": {},+ "p50Ms": 41.50508300001093,+ "p95Ms": 83.1715419999964,+ "maxMs": 119.58304199999839,+ "bytes": {+ "mean": 316,+ "p50": 269,+ "p95": 269,+ "total": 37888+ },+ "byOp": {+ "read.host": 120+ }+ }+ ]+ },+ "state": {+ "afterSetup": {+ "bytes": 1174606,+ "documents": 237+ },+ "afterLoad": {+ "bytes": 1198073,+ "documents": 237+ }+ },+ "isolatedPolls": [+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 113508,+ "databaseBytesOut": 185547,+ "ms": 21.857041999988724+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 113508,+ "databaseBytesOut": 185547,+ "ms": 22.25+ },+ {+ "reader": "desktop:[email protected]",+ "responseBytes": 113508,+ "databaseBytesOut": 185547,+ "ms": 20.79041699998197+ },+ {+ "reader": "host:bench-machine-0",+ "responseBytes": 268,+ "databaseBytesOut": 141310,+ "ms": 25.22408399998676+ },+ {+ "reader": "host:bench-machine-1",+ "responseBytes": 268,+ "databaseBytesOut": 85727,+ "ms": 22.353957999992417+ }+ ]+}diff --git a/backend/integration/bench/run.ts b/backend/integration/bench/run.tsnew file mode 100644index 000000000..34e696b3f--- /dev/null+++ b/backend/integration/bench/run.ts@@ -0,0 +1,29 @@+import { mkdir, writeFile } from 'node:fs/promises'+import { join } from 'node:path'+import { runBench } from './bench.js'+import { parseArgs } from './config.js'+import { localDatabase } from './mongo.js'+import { renderMarkdown } from './report.js'++/** `npm run bench:swarm-state -- [options]` (README.md). Writes `<driver>-<time>.json` and `.md` to the results folder. */+async function main() {+ const { config, out, driver } = parseArgs(process.argv.slice(2))+ const folder = out ?? join(process.cwd(), 'integration/bench/results')+ const database = await localDatabase()+ try {+ const report = await runBench(config, driver, database.db)+ const name = `${report.driver}-${report.startedAt.replaceAll(':', '-').replace(/\.\d+Z$/, 'Z')}`+ const markdown = renderMarkdown(report)+ await mkdir(folder, { recursive: true })+ await writeFile(join(folder, `${name}.json`), `${JSON.stringify(report, null, 2)}\n`)+ await writeFile(join(folder, `${name}.md`), markdown)+ process.stdout.write(`${markdown}\nWrote ${join(folder, name)}.json and .md\n`)+ } finally {+ await database.stop()+ }+}++main().catch(error => {+ process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`)+ process.exitCode = 1+})diff --git a/backend/integration/bench/scenario.test.ts b/backend/integration/bench/scenario.test.tsnew file mode 100644index 000000000..f7d673d88--- /dev/null+++ b/backend/integration/bench/scenario.test.ts@@ -0,0 +1,113 @@+import { afterAll, beforeAll, describe, expect, it } from 'vitest'+import { AttemptCounter } from './attempts.js'+import { runBench } from './bench.js'+import { DEFAULT_CONFIG, type BenchConfig } from './config.js'+import { person } from './fixtures.js'+import { partsDriver } from './drivers/parts.js'+import { localDatabase, type LocalDatabase } from './mongo.js'+import { plan, planDigest } from './plan.js'+import type { BenchReport } from './report.js'+import { renderMarkdown } from './report.js'++// A short run of the whole scenario through the store by parts and its clients' reads, on its own loopback replica set.+// (Today's full reads answer 426 on this branch: `legacyDriver` runs only on main.)+const config: BenchConfig = { ...DEFAULT_CONFIG, groups: 6, doneShare: 0.5, workers: 3, machines: 2, durationMs: 6_000, desktopReaders: 2, hostReaders: 1,+ every: { workerPostMs: 600, leadSendMs: 800, nativeTurnMs: 1_500, observeMs: 2_000, deliveryPassMs: 700, desktopPollMs: 1_000, hostTickMs: 500 },+ text: { briefChars: 400, resultChars: 100, messageChars: 80 } }+// The cross-group lane on a hot Swarm: every group active, fewer workers than groups.+const lane: BenchConfig = { ...config, doneShare: 0, workers: 2, lane: 'cross-group' }+let database: LocalDatabase, laneDatabase: LocalDatabase+let report: BenchReport, laneReport: BenchReport+const op = (name: string, from = report) => from.load.ops.find(row => row.key === name)++beforeAll(async () => {+ database = await localDatabase()+ report = await runBench(config, 'parts', database.db)+ // Each run seeds its own accounts, so it gets a fresh database.+ laneDatabase = await localDatabase()+ laneReport = await runBench(lane, 'parts', laneDatabase.db)+})+afterAll(async () => { await database?.stop(); await laneDatabase?.stop() })++describe('the Swarm load benchmark on the store by parts', () => {+ it('runs every planned worker post, Lead message, terminal turn, machine report and poll exactly once', () => {+ const p = plan(config)+ const planned = (name: string) => p.workers.flatMap(w => w.actions).filter(a => a.op === name).length+ for (const name of ['work.status', 'work.check']) expect(op(name)?.count, name).toBe(planned(name))+ const workerSends = report.load.writers.filter(w => w.key.startsWith('worker-')).reduce((sum, w) => sum + (w.byOp['message.send'] ?? 0), 0)+ expect(workerSends).toBe(planned('message.send'))+ expect(report.load.writers.find(w => w.key === 'lead')!.byOp['message.send']).toBe(p.lead.length)+ // An answer whose prompt ran out of retries is not sent (load.ts); that is counted, never lost.+ expect(op('native.append')!.count + (report.load.skipped['native answers'] ?? 0)).toBe(2 * p.workers.reduce((sum, w) => sum + w.turns.length, 0))+ expect(op('observeMachine')?.count).toBe(p.machines.reduce((sum, m) => sum + m.observations.length, 0))+ expect(op('read.desktop')?.count).toBe(p.readers.filter(r => r.kind === 'desktop').reduce((sum, r) => sum + r.polls.length, 0))+ expect(op('read.host')?.count).toBe(p.readers.filter(r => r.kind === 'host').reduce((sum, r) => sum + r.polls.length, 0))+ expect(Object.keys(report.load.skipped).filter(k => k !== 'native answers')).toEqual([])+ expect(report.planDigest).toBe(planDigest(p))+ })++ it('gets no error back but a busy Swarm', () => {+ for (const row of report.load.ops) {+ expect(row.errors, row.key).toEqual({})+ expect(row.ok + row.swarmBusy, row.key).toBe(row.count)+ }+ })++ it('claims and acknowledges the deliveries the Lead and the terminals create', () => {+ expect(op('delivery.claim')!.ok).toBeGreaterThan(0)+ expect(op('delivery.ack')!.count).toBe(op('delivery.claim')!.ok)+ expect(op('deliveries.list')!.count).toBeGreaterThan(0)+ })++ it('keeps each kind of writer apart: delivery passes, host roster reads, machines, terminals, workers, the Lead', () => {+ const kinds = Object.fromEntries(report.load.writerKinds.map(k => [k.key, k.count]))+ expect(Object.keys(kinds)).toEqual(['delivery', 'desktop', 'host', 'lead', 'machine', 'terminal', 'worker'])+ expect(kinds.host).toBe(op('read.host')!.count)+ expect(kinds.delivery).toBe(op('deliveries.list')!.count + op('delivery.claim')!.count + op('delivery.ack')!.count)+ })++ it('measures what a poll costs and how big the state is', () => {+ const desktop = op('read.desktop')!.bytes!, host = op('read.host')!.bytes!+ expect(desktop.mean).toBeGreaterThan(host.mean)+ expect(report.state.afterSetup.bytes).toBeGreaterThan(0)+ // The stored parts grow during the load: messages raise their groups' counters, reports their watermarks.+ expect(report.state.afterLoad.bytes).toBeGreaterThan(report.state.afterSetup.bytes)+ expect(report.state.afterLoad.documents).toBeGreaterThan(1)+ expect(report.isolatedPolls.map(p => p.reader).sort()).toEqual(report.load.readers.map(r => r.key).sort())+ for (const poll of report.isolatedPolls) expect(poll.responseBytes).toBeGreaterThan(0)+ })++ it('writes a markdown report with the run, the operations, the writers and the readers', () => {+ const markdown = renderMarkdown(report)+ for (const heading of ['## Run', '## Operations', '## Writer kinds', '## Writers', '## Readers', '## State']) expect(markdown).toContain(heading)+ expect(renderMarkdown(laneReport)).toContain('| Lane | cross-group')+ expect(markdown).toContain('| work.status |')+ })++ it('runs the cross-group lane: workers in all their groups, terminals and machine reports, no Lead and no delivery passes', () => {+ const p = plan(lane)+ expect(p.workers.map(w => w.groups.length)).toEqual([3, 3])+ const planned = (name: string) => p.workers.flatMap(w => w.actions).filter(a => a.op === name).length+ for (const name of ['message.send', 'work.status', 'work.check']) expect(op(name, laneReport)?.count ?? 0, name).toBe(planned(name))+ expect(op('native.append', laneReport)!.count + (laneReport.load.skipped['native answers'] ?? 0)).toBe(2 * p.workers.reduce((sum, w) => sum + w.turns.length, 0))+ expect(op('observeMachine', laneReport)?.count).toBe(p.machines.reduce((sum, m) => sum + m.observations.length, 0))+ for (const name of ['deliveries.list', 'delivery.claim', 'delivery.ack']) expect(op(name, laneReport), name).toBeUndefined()+ expect(laneReport.load.writers.map(w => w.key)).not.toContain('lead')+ for (const row of laneReport.load.ops) expect(row.errors, row.key).toEqual({})+ expect(laneReport.load.writerKinds.map(k => k.key)).toEqual(['desktop', 'host', 'machine', 'terminal', 'worker'])+ })++ it('counts the write conflicts the store retries when commands on one Swarm run at once', async () => {+ const counter = new AttemptCounter(), owner = person(0)+ const driver = await partsDriver(counter.wrap(database.db), () => [owner])+ try {+ const tab = (await driver.createSwarm(owner, 'conflict-check', 'Conflicts')).data!.id+ const sends = await Promise.all(Array.from({ length: 10 }, (_, i) => counter.track(() => driver.execute(tab, owner, `conflict-${i}`,+ { type: 'message.send', conversationId: 'lead', text: `Note ${i}`, replyTo: null, recipientIds: [] }))))+ expect(sends.map(s => s.value?.code ?? 'ok')).toEqual(Array(10).fill('ok'))+ expect(sends.flatMap(s => s.failedAttempts).filter(code => code === 'P2034').length).toBeGreaterThan(0)+ } finally {+ await driver.close()+ }+ })+})diff --git a/backend/integration/bench/seed.ts b/backend/integration/bench/seed.tsnew file mode 100644index 000000000..5c367ed81--- /dev/null+++ b/backend/integration/bench/seed.ts@@ -0,0 +1,131 @@+import type { AuthUser } from '../../src/lib/ssoAuth.js'+import type { Command } from '../../src/superTabs/commands.js'+import type { BenchConfig } from './config.js'+import type { Reply, SwarmDriver } from './driver.js'+import { machineId } from './fixtures.js'+import type { Plan } from './plan.js'+import { random, words, type Random } from './random.js'++export interface Worker {+ id: string+ harnessId: string+ machine: number+ /** The group whose task it holds; its terminal is open there. */+ group: string+ assignmentId: string+ checkIds: string[]+ /** Its terminal, opened by its machine's owner. */+ contextId: string+}++/** The Swarm the load runs on: who is who, and the ids the load's calls need. */+export interface Swarm {+ tabId: string+ people: AuthUser[]+ leadId: string+ /** Every work group's id, by its index in the plan. */+ groups: string[]+ workers: Worker[]+ /** Each machine's contribution generation, which its reports name. */+ generations: string[]+}++export const AGENT_CONFIGURATION = { engine: 'codex', model: 'bench-model', effort: 'high', contextWindow: 200000, engineVersion: 'bench' }++function must<T>(reply: Reply<T>, what: string): T {+ if (reply.code || reply.data === null) throw new Error(`Setup failed at ${what}: ${reply.code} (HTTP ${reply.status})`)+ return reply.data+}++/** Setup's calls: each must succeed, and each is counted. */+class Setup {+ calls = 0+ private operation = 0+ tabId = ''+ constructor(readonly driver: SwarmDriver, readonly config: BenchConfig, readonly people: AuthUser[]) {}+ get owner() { return this.people[0]! }+ op() { return `bench-${this.config.seed}-setup-${this.operation++}` }+ async check<T>(what: string, call: Promise<Reply<T>>): Promise<T> {+ this.calls+++ return must(await call, what)+ }+ async run(user: AuthUser, command: Command, asAgentId?: string) {+ return (await this.check(command.type, this.driver.execute(this.tabId, user, this.op(), command, asAgentId))).result+ }+}++/** Members join and contribute their machines; the owner's machine 0 runs the Lead. */+async function seedMembers(s: Setup): Promise<string> {+ for (const member of s.people.slice(1)) {+ const invitation = await s.run(s.owner, { type: 'invite.create', email: member.email, role: 'collaborator', conversationId: 'lead' })+ await s.run(member, { type: 'invite.accept', inviteId: String(invitation.inviteId) })+ }+ for (let n = 0; n < s.config.machines; n++) {+ await s.run(s.people[n]!, { type: 'machine.contribute', machineId: machineId(n), name: `Bench machine ${n}`, cwd: '/bench/repo',+ engines: ['codex'], maxAgents: 16 })+ }+ return String((await s.run(s.owner, { type: 'agent.add', conversationId: 'lead', machineId: machineId(0), harnessId: 'bench-lead',+ name: 'Lead', configuration: AGENT_CONFIGURATION, lead: true })).agentId)+}++/** Every group with a brief and two checks; returns their ids in plan order. */+async function seedGroups(s: Setup, rng: Random): Promise<string[]> {+ const groups: string[] = []+ for (let g = 0; g < s.config.groups; g++) {+ groups.push(String((await s.run(s.owner, { type: 'conversation.create', title: `Bench group ${g}`, brief: words(rng, s.config.text.briefChars),+ checks: [0, 1].map(() => ({ description: words(rng, 120), independent: false })) })).conversationId))+ }+ return groups+}++/** Each worker added by its machine's owner into its first active group, then joined to its other active groups. */+async function seedWorkers(s: Setup, p: Plan, groups: string[]): Promise<Array<{ id: string; harnessId: string }>> {+ const agents: Array<{ id: string; harnessId: string }> = []+ for (const w of p.workers) {+ const harnessId = `bench-worker-${w.index}`+ const id = String((await s.run(s.people[w.machine]!, { type: 'agent.add', conversationId: groups[w.groups[0]!]!,+ machineId: machineId(w.machine), harnessId, name: `Engineer ${w.index}`, configuration: AGENT_CONFIGURATION, lead: false })).agentId)+ for (const g of w.groups.slice(1)) await s.run(s.owner, { type: 'conversation.agent', conversationId: groups[g]!, agentId: id, present: true, lead: false })+ agents.push({ harnessId, id })+ }+ return agents+}++/** A done group's whole task: its worker joins, is assigned, passes both checks and reports done. */+async function finishGroup(s: Setup, rng: Random, group: string, agentId: string, host: AuthUser, checkIds: string[]) {+ await s.run(s.owner, { type: 'conversation.agent', conversationId: group, agentId, present: true, lead: false })+ const assignmentId = String((await s.run(s.owner, { type: 'work.assign', conversationId: group, agentId })).assignmentId)+ for (const checkId of checkIds) {+ await s.run(host, { type: 'work.check', conversationId: group, assignmentId, checkId, passed: true, evidence: words(rng, 200) }, agentId)+ }+ await s.run(host, { type: 'work.status', conversationId: group, assignmentId, status: 'done', result: words(rng, s.config.text.resultChars) }, agentId)+}++/**+ * Builds the Swarm through the driver's real commands, one after another, as people and agents would: members join,+ * machines are contributed, the Lead and the workers are added, every group gets a brief and checks, the done groups run+ * a whole task, and each worker is given its active group's task with its terminal open. Returns how many calls it made.+ */+export async function seedSwarm(driver: SwarmDriver, config: BenchConfig, p: Plan, people: AuthUser[]): Promise<{ swarm: Swarm; calls: number }> {+ const s = new Setup(driver, config, people), rng = random(config.seed, 'setup')+ s.tabId = (await s.check('create', driver.createSwarm(s.owner, s.op(), 'Bench Swarm'))).id+ const leadId = await seedMembers(s)+ const groups = await seedGroups(s, rng)+ const agents = await seedWorkers(s, p, groups)+ // Check ids are fixed when a group is created; one read gives them all.+ const snapshot = await driver.snapshot(s.tabId, s.owner)+ const checksOf = (group: string) => snapshot.conversations.find(c => c.id === group)!.checks.map(c => c.id)+ for (const w of p.workers) {+ for (const g of w.doneGroups) await finishGroup(s, rng, groups[g]!, agents[w.index]!.id, people[w.machine]!, checksOf(groups[g]!))+ }+ const workers: Worker[] = []+ for (const w of p.workers) {+ const group = groups[w.groups[0]!]!, agent = agents[w.index]!, host = people[w.machine]!+ const assignmentId = String((await s.run(s.owner, { type: 'work.assign', conversationId: group, agentId: agent.id })).assignmentId)+ const { contextId } = await s.check('native.open', driver.openNative(s.tabId, host, { operationId: s.op(), conversationId: group, agentId: agent.id }))+ workers.push({ ...agent, machine: w.machine, group, assignmentId, checkIds: checksOf(group), contextId })+ }+ const generations: string[] = []+ for (let n = 0; n < config.machines; n++) generations.push(await driver.machineGeneration(s.tabId, people[n]!, machineId(n)))+ return { swarm: { tabId: s.tabId, people, leadId, groups, workers, generations }, calls: s.calls }+}diff --git a/backend/integration/bench/tsconfig.json b/backend/integration/bench/tsconfig.jsonnew file mode 100644index 000000000..349d59e15--- /dev/null+++ b/backend/integration/bench/tsconfig.json@@ -0,0 +1,5 @@+{+ "extends": "../../tsconfig.json",+ "compilerOptions": { "noEmit": true, "rootDir": "../..", "incremental": false },+ "include": ["./**/*.ts", "../../src/**/*"]+}diff --git a/backend/integration/bench/vitest.config.ts b/backend/integration/bench/vitest.config.tsnew file mode 100644index 000000000..dd0f53a93--- /dev/null+++ b/backend/integration/bench/vitest.config.ts@@ -0,0 +1,5 @@+import { defineConfig } from 'vitest/config'++// The benchmark's own tests: its helpers, and one short run of the whole scenario on a local replica set.+export default defineConfig({ test: { include: ['integration/bench/**/*.test.ts'], hookTimeout: 120000, testTimeout: 180000,+ fileParallelism: false, env: { NODE_ENV: 'test', HARNESS_CREDENTIAL_ENCRYPTION_KEY: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' } } })diff --git a/backend/integration/hostRows.test-support.ts b/backend/integration/hostRows.test-support.tsnew file mode 100644index 000000000..beedb6da5--- /dev/null+++ b/backend/integration/hostRows.test-support.ts@@ -0,0 +1,24 @@+/**+ * Test support: the host form's rows (read/host.ts) in the shapes of the store's old host reads, which it replaced+ * (`hostTabs`, `hostPools`, `hostAssignments`). Suites written against those call these instead and keep their assertions.+ */+import type { AuthUser } from '../src/lib/ssoAuth.js'+import type { SuperTabStore } from '../src/superTabs/store.js'+import { HostReads } from '../src/superTabs/read/host.js'+import type { HostTabRows } from '../src/superTabs/read/contract.js'++type Options = { teamAccountsIdle?: boolean; githubApp?: boolean }++/** A full host read, holding no etags, so every Swarm comes back with its rows. */+async function hostRead(store: SuperTabStore, user: AuthUser, machineId: string, options: Options = {}): Promise<HostTabRows[]> {+ return (await new HostReads(store, options).changes(user, machineId, { full: true })).tabs as HostTabRows[]+}+/** What `store.hostTabs` listed: every Swarm's roster rows, in order. */+export const rosterRows = async (store: SuperTabStore, user: AuthUser, machineId: string, options?: Options) =>+ (await hostRead(store, user, machineId, options)).flatMap(tab => tab.roster)+/** What `store.hostPools` listed: the pool of every Swarm where this machine is the caller's contribution. */+export const poolRows = async (store: SuperTabStore, user: AuthUser, machineId: string, options?: Options) =>+ (await hostRead(store, user, machineId, options)).flatMap(tab => tab.pool ? [tab.pool] : [])+/** What `store.hostAssignments` listed: the active assignments this machine runs for the caller. */+export const assignmentRows = async (store: SuperTabStore, user: AuthUser, machineId: string, options?: Options) =>+ (await hostRead(store, user, machineId, options)).flatMap(tab => tab.assignments)diff --git a/backend/integration/interleave.test-support.ts b/backend/integration/interleave.test-support.tsnew file mode 100644index 000000000..88fed8d16--- /dev/null+++ b/backend/integration/interleave.test-support.ts@@ -0,0 +1,26 @@+/** Test support: a database whose transactions let another writer in at a chosen point, to make races repeatable. */+import type { PrismaClient } from '@prisma/client'++const WRITES = new Set(['create', 'createMany', 'update', 'updateMany', 'upsert', 'delete', 'deleteMany'])++/** `db`, but each transaction attempt runs `interleave` (another writer committing, or a barrier) once, before its first+ * write of any kind: after everything it read, before anything it wrote. */+export function beforeFirstWrite(db: PrismaClient, interleave: () => Promise<void>): PrismaClient {+ const wrap = (tx: PrismaClient) => {+ let waited: Promise<void> | null = null+ return new Proxy(tx, { get(target, key, receiver) {+ const model = Reflect.get(target, key, receiver)+ if (!model || typeof model !== 'object') return model+ return new Proxy(model, { get(delegate, method, delegateReceiver) {+ const original = Reflect.get(delegate, method, delegateReceiver)+ if (typeof method !== 'string' || !WRITES.has(method) || typeof original !== 'function') return original+ return async (...args: unknown[]) => { await (waited ??= interleave()); return original.apply(delegate, args) }+ } })+ } })+ }+ return new Proxy(db, { get(target, key, receiver) {+ if (key !== '$transaction') return Reflect.get(target, key, receiver)+ return (body: (tx: PrismaClient) => Promise<unknown>, options: unknown) =>+ (target.$transaction as (b: unknown, o: unknown) => Promise<unknown>)((tx: PrismaClient) => body(wrap(tx)), options)+ } })+}diff --git a/backend/integration/superTabGithub.test.ts b/backend/integration/superTabGithub.test.tsindex c78659374..6e24e2275 100644--- a/backend/integration/superTabGithub.test.ts+++ b/backend/integration/superTabGithub.test.ts@@ -14,6 +14,7 @@ import { errorHandler } from '../src/middlewares/errorHandler.js'import type { Command } from '../src/superTabs/commands.js'import { GitHubTokens, MemoryTokenCache } from '../src/github/tokens.js'import { fakeApp, fakeGitHub, throwawayKey } from '../src/github/fakeGitHub.js'+import { poolRows } from './hostRows.test-support.js'// The Harness GitHub App's token endpoint on the real control API: a fresh loopback MongoDB and a fake GitHub. This suite// never reads DATABASE_URL, an existing database or github.com.@@ -104,7 +105,7 @@ describe('the GitHub token endpoint', () => {// The same task gets the same token back.expect((await ask(env, tab, worker)).json().data.token).toBe('ghs_fixture_1')// The tab tells a Lead's start that this server has the app.- const read = await env.app.inject({ method: 'GET', url: `/api/super-tabs/${tab}`, headers: { authorization: `Bearer ${owner.sub}` } })+ const read = await env.app.inject({ method: 'GET', url: `/api/super-tabs/${tab}/parts`, headers: { authorization: `Bearer ${owner.sub}` } })expect(read.json().data.githubApp).toBe(true)})@@ -172,12 +173,18 @@ describe('the GitHub token endpoint', () => {const response = await ask(env, tab, worker)expect(response.statusCode).toBe(503)expect(response.json().error.code).toBe('GITHUB_APP_NOT_CONFIGURED')- const read = await env.app.inject({ method: 'GET', url: `/api/super-tabs/${tab}`, headers: { authorization: `Bearer ${owner.sub}` } })+ const read = await env.app.inject({ method: 'GET', url: `/api/super-tabs/${tab}/parts`, headers: { authorization: `Bearer ${owner.sub}` } })expect(read.json().data).not.toHaveProperty('githubApp')})})describe('a queued start\'s preparation token', () => {+ /** The host's pool rows, now each Swarm's `pool` in the host form (design 4.10), in the shape the old pools route answered. */+ const hostPools = async (env: Env) => {+ const response = await env.app.inject({ method: 'GET', url: '/api/super-tabs/hosts/gh-pool/changes?full=1', headers: { authorization: `Bearer ${host.sub}` } })+ const rows = (response.json().data.tabs as Array<{ pool: unknown }>).flatMap(tab => tab.pool ? [tab.pool] : [])+ return { json: () => ({ data: rows }) }+ }const observed = { resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9, diskTotalBytes: 500e9,projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture CPU', os: 'macOS', gpuPercent: null }, quotas: [], tools: { git: true },runningHarnessIds: [], stoppedHarnessIds: [] }@@ -191,7 +198,7 @@ describe('a queued start\'s preparation token', () => {await env.run(tab, { type: 'invite.accept', inviteId: invitation.result.inviteId as string } as Command, contributor)}await env.run(tab, { type: 'machine.contribute', machineId, name: 'Pool', cwd: '/swarm-root', scope: 'swarm', engines: ['codex'], maxAgents: 2 } as Command, contributor)- const pool = (await env.store.hostPools(contributor, machineId)).find(p => p.tabId === tab)!+ const pool = (await poolRows(env.store, contributor, machineId)).find(p => p.tabId === tab)!if (contributor === owner) await env.store.observeMachine(contributor, tab, machineId, { generation: pool.machine.generation, ...observed })else {// Another person's project runs only on a Team machine (#1694): this one is used only for agents (`harness team on`).@@ -211,7 +218,7 @@ describe('a queued start\'s preparation token', () => {it('gives the host of another person\'s start a token that only reads the project\'s repository, and says whom the work is for', async () => {const env = await fresh()const { tab, startId } = await queued(env)- const pools = await env.app.inject({ method: 'GET', url: '/api/super-tabs/hosts/gh-pool/pools', headers: { authorization: `Bearer ${host.sub}` } })+ const pools = await hostPools(env)expect(pools.json().data.find((row: { tabId: string }) => row.tabId === tab)).toMatchObject({ githubApp: true })const response = await prepare(env, tab, startId)expect(response.statusCode, response.body).toBe(200)@@ -253,7 +260,7 @@ describe('a queued start\'s preparation token', () => {const response = await prepare(env, tab, startId)expect(response.statusCode).toBe(503)expect(response.json().error.code).toBe('GITHUB_APP_NOT_CONFIGURED')- const pools = await env.app.inject({ method: 'GET', url: '/api/super-tabs/hosts/gh-pool/pools', headers: { authorization: `Bearer ${host.sub}` } })+ const pools = await hostPools(env)expect(pools.json().data.find((row: { tabId: string }) => row.tabId === tab)).not.toHaveProperty('githubApp')})})diff --git a/backend/integration/superTabLiveness.test.ts b/backend/integration/superTabLiveness.test.tsnew file mode 100644index 000000000..ee142998b--- /dev/null+++ b/backend/integration/superTabLiveness.test.ts@@ -0,0 +1,302 @@+import { randomUUID } from 'node:crypto'+import { execFile } from 'node:child_process'+import { promisify } from 'node:util'+import { join } from 'node:path'+import { tmpdir } from 'node:os'+import { afterAll, beforeAll, describe, expect, it } from 'vitest'+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'+import { PrismaClient } from '@prisma/client'+import type { AuthUser } from '../src/lib/ssoAuth.js'+import { SuperTabStore } from '../src/superTabs/store.js'+import type { Command } from '../src/superTabs/commands.js'+import type { MachineObservation } from '../src/superTabs/machines.js'+import * as parts from '../src/superTabs/parts/index.js'+import { poolRows } from './hostRows.test-support.js'+import { beforeFirstWrite } from './interleave.test-support.js'+import { SwarmReads } from '../src/superTabs/read/service.js'++// Work never sits with a dead owner: an active assignment whose agent died, stalled or hit a limit becomes lost within+// minutes, its old agent is fenced off, and the Lead is woken to hand it on. A fresh loopback replica set, created here.+let replica: MongoMemoryReplSet+let db: PrismaClient+const owner: AuthUser = { sub: '200000000000000000000001', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }+const host: AuthUser = { sub: '200000000000000000000003', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }+const config = { engine: 'codex', model: 'fixture-model', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }+const MINUTE = 60_000++beforeAll(async () => {+ replica = await MongoMemoryReplSet.create({ binary: { version: '7.0.24', downloadDir: join(tmpdir(), 'harness-super-tab-mongodb-binaries') },+ replSet: { count: 1, ip: '127.0.0.1', storageEngine: 'wiredTiger' } })+ const uri = replica.getUri(`swarm_liveness_test_${randomUUID().replaceAll('-', '_')}`)+ await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], {+ env: { ...process.env, DATABASE_URL: uri }, timeout: 60000,+ })+ db = new PrismaClient({ datasources: { db: { url: uri } } })+ for (const user of [owner, host]) await db.user.create({ data: { id: user.sub, externalId: `fixture-${user.sub}`, email: user.email, autonomousEnv: user.autonomousEnv } })+ for (const machineId of ['lead-host', 'test-host']) {+ await db.machine.create({ data: { machineId, userId: host.sub, apiKey: `fixture-${machineId}`, managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })+ await db.machineShare.create({ data: { machineId, ownerId: host.sub, autonomousEnv: 'prod', emails: [owner.email] } })+ }+})+afterAll(async () => {+ await db?.$disconnect()+ await replica?.stop()+})++/** A Swarm whose Lead runs on one of host's machines and whose worker runs on another, assigned "Ship the parser". */+async function swarm({ legacy = false } = {}) {+ let now = 10_000_000+ const timed = new SuperTabStore(db, () => now)+ const tab = (await timed.create(owner, randomUUID(), 'Liveness', legacy ? undefined : 'public')).id+ if (legacy) await dropProjects(tab)+ const execute = (command: Command, user = owner, asAgentId?: string) => timed.execute(user, tab, { operationId: randomUUID(), command }, asAgentId)+ const invitation = await execute({ type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })+ await execute({ type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)+ for (const [machineId, name] of [['lead-host', 'Lead Mac'], ['test-host', 'Worker Mac']]) {+ await execute({ type: 'machine.contribute', machineId: machineId!, name: name!, cwd: '/repo', engines: ['codex'], maxAgents: 4 }, host)+ }+ const generations = new Map<string, string>()+ for (const machineId of ['lead-host', 'test-host']) generations.set(machineId, (await poolRows(timed, host, machineId)).find(p => p.tabId === tab)!.machine.generation)+ const harness = { lead: randomUUID(), worker: randomUUID(), other: randomUUID() }+ const add = async (conversationId: string, machineId: string, harnessId: string, name: string, lead = false) => String((await execute({ type: 'agent.add',+ conversationId, machineId, harnessId, name, configuration: config, lead })).result.agentId)+ const lead = await add('lead', 'lead-host', harness.lead, 'Lead', true)+ const group = String((await execute({ type: 'conversation.create', title: 'Ship the parser', brief: 'Implement it',+ checks: [{ description: 'Verified', independent: false }] })).result.conversationId)+ const worker = await add(group, 'test-host', harness.worker, 'Worker')+ const assignmentId = String((await execute({ type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId)+ const observe = (machineId: string, running: string[], extra: Partial<MachineObservation> = {}) => timed.observeMachine(host, tab, machineId, {+ generation: generations.get(machineId)!, resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9,+ diskTotalBytes: 500e9, projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture', os: 'macOS', gpuPercent: null },+ quotas: [], tools: {}, runningHarnessIds: running, stoppedHarnessIds: [], ...extra })+ /** Both machines report: the Lead's alive, the worker's listing its session with its screen last changed at `progressAt`+ * (none: an older host that sends no progress). */+ const beat = async (progressAt?: number) => {+ await observe('lead-host', [harness.lead])+ await observe('test-host', [harness.worker], progressAt === undefined ? {} : { harnessProgress: { [harness.worker]: progressAt } })+ }+ /** The member name people and the Lead read for an agent. */+ const name = async (agentId: string) => (await timed.read(owner, tab)).state.agents.find(a => a.id === agentId)!.displayName+ const assignment = async () => (await timed.read(owner, tab)).state.conversations.find(c => c.id === group)!.assignment!+ /** What the Lead's host receives now (this poll is also the Lead's wake-up path), with each row's text. */+ const leadInbox = async () => {+ const rows = await timed.deliveries(host, tab, lead)+ const messages = await db.superTabMessage.findMany({ where: { id: { in: rows.map(r => r.messageId) } } })+ return rows.map(r => messages.find(m => m.id === r.messageId)!)+ }+ const lostRows = async () => (await db.superTabMessage.findMany({ where: { tabId: tab }, orderBy: { sequence: 'asc' } }))+ .filter(m => (m.source as { kind?: string } | null)?.kind === 'work-lost')+ return { timed, tab, execute, lead, group, worker, assignmentId, harness, observe, beat, name, assignment, leadInbox, lostRows, add,+ clock: { get now() { return now }, set now(value: number) { now = value } } }+}++/** A Swarm created before projects existed. */+async function dropProjects(tab: string) {+ await db.$transaction(async tx => {+ const current = await parts.loadAll(tx, tab)+ const state = parts.reassemble(current)+ delete state.projects+ const version = Math.max(current.head.version, ...[...current.members, ...current.agents, ...current.groups, ...current.machines,+ ...current.starts, ...current.progress].map(p => p.version)) + 1+ for (const model of [tx.swarmHead, tx.swarmMember, tx.swarmAgent, tx.swarmGroup, tx.swarmMachine, tx.swarmStart, tx.swarmProgress] as unknown as+ Array<{ deleteMany(args: unknown): Promise<unknown> }>) await model.deleteMany({ where: { tabId: tab } })+ await parts.insertParts(tx, { ...parts.split(state, { tabId: tab, version, now: Date.now(), visibilityEpoch: current.visibilityEpoch }),+ sequenceBase: current.sequenceBase })+ })+}++describe('work that loses its owner', () => {+ // Final review, Important 3: routing keeps a lost task's worker out after the task is cancelled, from the mark on the agent.+ it('marks its worker in the same write that loses it, and the mark outlives a cancel in first loads and change reads', async () => {+ const f = await swarm()+ const reads = new SwarmReads(f.timed, { now: () => f.clock.now })+ await f.beat(f.clock.now)+ const { cursor } = await reads.firstLoad(owner, f.tab)+ f.clock.now += 2 * MINUTE + 5_000+ await f.observe('lead-host', [f.harness.lead])+ const lostAt = f.clock.now+ expect((await f.assignment()).status).toBe('lost')+ const [agentRow, groupRow] = [await db.swarmAgent.findFirst({ where: { tabId: f.tab, key: f.worker } }), await db.swarmGroup.findFirst({ where: { tabId: f.tab, key: f.group } })]+ // One commit stamps every part it writes alike: the worker's part was written with the lost task's.+ expect(agentRow!.changedAt.getTime()).toBe(groupRow!.changedAt.getTime())+ expect((agentRow!.data as { lostTask?: unknown }).lostTask).toBeDefined()+ f.clock.now += MINUTE+ await f.execute({ type: 'work.cancel', conversationId: f.group, assignmentId: f.assignmentId, reason: 'Not needed' })+ const mark = { conversationId: f.group, assignmentId: f.assignmentId, reason: 'its machine Worker Mac has been offline for 2 minutes', at: lostAt }+ const changed = await reads.changes(owner, f.tab, cursor)+ expect(changed.reload).toBe(false)+ expect('agents' in changed && changed.agents.find(a => a.key === f.worker)).toMatchObject({ data: { lostTask: mark } })+ expect((await reads.firstLoad(owner, f.tab)).agents.find(a => a.key === f.worker)!.data.lostTask).toEqual(mark)+ })++ it('is lost when its machine has been offline for 2 minutes, found by another machine\'s report', async () => {+ const f = await swarm()+ await f.beat(f.clock.now)+ const silent = f.clock.now+ // Only the Lead's machine keeps reporting. The time checks run on its reports, at most every 30 seconds.+ f.clock.now = silent + 90_000+ await f.observe('lead-host', [f.harness.lead])+ expect((await f.assignment()).status).toBe('working')+ f.clock.now = silent + 2 * MINUTE + 5_000+ await f.observe('lead-host', [f.harness.lead])+ expect(await f.assignment()).toMatchObject({ status: 'lost', lost: { reason: 'its machine Worker Mac has been offline for 2 minutes' } })+ })++ it('is not lost when a fresh report from its machine commits between the time checks\' read and their write', async () => {+ const f = await swarm()+ await f.beat(f.clock.now)+ f.clock.now += 2 * MINUTE + 5_000+ // The Lead's poll reads the worker's machine as silent; just before it writes the loss, that machine reports.+ let raced = false+ const racing = new SuperTabStore(beforeFirstWrite(db, async () => {+ if (raced) return+ raced = true+ await f.observe('test-host', [f.harness.worker], { harnessProgress: { [f.harness.worker]: f.clock.now } })+ }), () => f.clock.now)+ await racing.deliveries(host, f.tab, f.lead)+ expect(raced).toBe(true)+ expect((await f.assignment()).status).toBe('working')+ expect(await f.lostRows()).toEqual([])+ })++ it('is lost at once when the host reports its session stopped, and the Lead is woken with who, why and the last result', async () => {+ const f = await swarm()+ await f.beat(f.clock.now)+ await f.execute({ type: 'work.status', conversationId: f.group, assignmentId: f.assignmentId, status: 'working',+ result: 'Parser half done, pushed to https://github.com/example/project/pull/7' }, host, f.worker)+ f.clock.now += 3 * MINUTE+ await f.observe('test-host', [], { stoppedHarnessIds: [f.harness.worker] })+ expect(await f.assignment()).toMatchObject({ status: 'lost', lost: { reason: 'its session on Worker Mac stopped' } })+ const wake = (await f.leadInbox()).find(m => (m.source as { kind?: string }).kind === 'work-lost')!+ expect(wake.conversationId).toBe(f.group)+ expect(wake.text).toBe(`${await f.name(f.worker)} lost its task`+' "Ship the parser": its session on Worker Mac stopped. Last progress 3 minutes ago. '+ + 'Last result: Parser half done, pushed to https://github.com/example/project/pull/7. Assign it to another agent now, or cancel it.')+ })++ it('is lost at once when its agent hits a usage limit', async () => {+ const f = await swarm()+ await f.execute({ type: 'agent.alert', agentId: f.worker, alert: 'limit', active: true, resetAt: new Date(f.clock.now + 30 * MINUTE).toISOString() }, host, f.worker)+ expect(await f.assignment()).toMatchObject({ status: 'lost', lost: { reason: `it hit a usage limit until ${new Date(f.clock.now + 30 * MINUTE).toISOString().slice(11, 16)} UTC` } })+ expect((await f.leadInbox()).some(m => (m.source as { kind?: string }).kind === 'work-lost')).toBe(true)+ })++ it('is lost when its lease runs out with no progress, though its machine keeps reporting', async () => {+ const f = await swarm()+ const assigned = f.clock.now+ // The session is listed as running, but its screen has not changed for over half an hour.+ for (let minute = 1; minute <= 4; minute++) {+ f.clock.now = assigned + minute * MINUTE+ await f.beat(assigned - 31 * MINUTE)+ }+ f.clock.now = assigned + 5 * MINUTE+ await f.beat(assigned - 31 * MINUTE)+ expect(await f.lostRows()).toEqual([])+ await f.leadInbox()+ expect((await f.assignment()).status).toBe('working')+ f.clock.now = assigned + 5 * MINUTE + 1+ await f.leadInbox()+ expect(await f.assignment()).toMatchObject({ status: 'lost', lost: { reason: 'no progress for 5 minutes' } })+ })++ it('gives a session still running but quiet (a long silent test run) 30 minutes from its last progress', async () => {+ const f = await swarm()+ const progress = f.clock.now+ for (let minute = 1; minute <= 30; minute++) {+ f.clock.now = progress + minute * MINUTE+ await f.beat(progress)+ await f.leadInbox()+ }+ expect((await f.assignment()).status).toBe('working')+ f.clock.now = progress + 30 * MINUTE + 1+ await f.beat(progress)+ expect(await f.assignment()).toMatchObject({ status: 'lost', lost: { reason: 'no progress for 30 minutes' } })+ })++ it('keeps its lease while the host reports progress, an older host reports it running, or the agent reports', async () => {+ const f = await swarm()+ for (let minute = 1; minute <= 12; minute++) {+ f.clock.now += MINUTE+ // Minutes 1-4: screen changes; 5-8: an older host that sends no progress; 9-12: only the agent's own status.+ if (minute <= 4) await f.beat(f.clock.now - 10_000)+ else if (minute <= 8) await f.beat()+ else {+ await f.execute({ type: 'work.status', conversationId: f.group, assignmentId: f.assignmentId, status: 'working', result: `Minute ${minute}` }, host, f.worker)+ await f.observe('lead-host', [f.harness.lead])+ await f.observe('test-host', [f.harness.worker], { harnessProgress: {} })+ }+ await f.leadInbox()+ expect((await f.assignment()).status).toBe('working')+ }+ expect((await f.assignment()).leaseUntil).toBe(f.clock.now + 5 * MINUTE)+ })++ it('fences the old agent once lost: its status, checks and done are refused and it is told its task moved', async () => {+ const f = await swarm()+ const check = (await f.timed.read(owner, f.tab)).state.conversations.find(c => c.id === f.group)!.checks[0]!.id+ await f.observe('test-host', [], { stoppedHarnessIds: [f.harness.worker] })+ for (const command of [+ { type: 'work.status', conversationId: f.group, assignmentId: f.assignmentId, status: 'working', result: null },+ { type: 'work.status', conversationId: f.group, assignmentId: f.assignmentId, status: 'done', result: 'Shipped' },+ { type: 'work.check', conversationId: f.group, assignmentId: f.assignmentId, checkId: check, passed: true, evidence: 'Ran it' },+ ] as Command[]) await expect(f.execute(command, host, f.worker)).rejects.toMatchObject({ code: 'ASSIGNMENT_LOST' })+ const told = await f.timed.deliveries(host, f.tab, f.worker)+ const notice = (await db.superTabMessage.findMany({ where: { id: { in: told.map(d => d.messageId) } } }))+ .find(m => (m.source as { kind?: string }).kind === 'work-lost')!+ expect(notice.text).toBe('Your task "Ship the parser" moved: its session on Worker Mac stopped. Stop working on it; your status and results for it are no longer accepted.')+ })++ it('lets the Lead assign the lost work to another agent, and keeps the old one fenced', async () => {+ const f = await swarm()+ await f.observe('test-host', [], { stoppedHarnessIds: [f.harness.worker] })+ const other = await f.add(f.group, 'test-host', f.harness.other, 'Other')+ const next = String((await f.execute({ type: 'work.assign', conversationId: f.group, agentId: other })).result.assignmentId)+ expect(await f.assignment()).toMatchObject({ id: next, agentId: other, status: 'working' })+ await expect(f.execute({ type: 'work.status', conversationId: f.group, assignmentId: f.assignmentId, status: 'working', result: null }, host, f.worker))+ .rejects.toMatchObject({ code: 'ASSIGNMENT_LOST' })+ await f.execute({ type: 'work.status', conversationId: f.group, assignmentId: next, status: 'working', result: 'Taking over' }, host, other)+ })++ it('lets the Lead cancel lost work', async () => {+ const f = await swarm()+ await f.observe('test-host', [], { stoppedHarnessIds: [f.harness.worker] })+ expect((await f.assignment()).status).toBe('lost')+ await f.execute({ type: 'work.cancel', conversationId: f.group, assignmentId: f.assignmentId, reason: 'Not needed any more' }, host, f.lead)+ expect((await f.assignment()).status).toBe('cancelled')+ })++ it('wakes the Lead of an older Swarm without stored projects, once', async () => {+ const f = await swarm({ legacy: true })+ expect((await f.timed.read(owner, f.tab)).state.projects).toBeUndefined()+ await f.observe('test-host', [], { stoppedHarnessIds: [f.harness.worker] })+ await f.observe('test-host', [], { stoppedHarnessIds: [f.harness.worker] })+ expect(await f.lostRows()).toHaveLength(2)+ expect((await f.leadInbox()).filter(m => (m.source as { kind?: string }).kind === 'work-lost')).toHaveLength(1)+ })+})++describe('a start that never runs', () => {+ it('fails 3 minutes after dispatch, naming its machine, and tells the Lead in its group', async () => {+ const f = await swarm()+ await f.beat(f.clock.now)+ const decision = { assessment: { difficulty: 'low', risk: 'low', why: 'Small task.' },+ candidates: [{ id: 'c0', kind: 'new', machineId: 'test-host', engine: 'codex', model: 'fixture-model', effort: 'high',+ quality: 2, cost: 2, title: 'New agent', label: 'New agent' }],+ excluded: [], floor: 1, notes: false, pick: 'c0', via: 'only', p: null, belowFloor: false, why: 'Only candidate.' }+ const routeDecisionId = String((await f.execute({ type: 'route.record', conversationId: 'lead', decision } as Command, host, f.lead)).result.routeDecisionId)+ const request = { conversationId: 'lead', machineId: 'test-host', engine: 'codex', model: 'fixture-model', effort: 'high', name: 'Builder',+ cwd: '/repo', worktree: false, requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }+ const startId = String((await f.execute({ type: 'agent.start', request, routeDecisionId } as Command, host, f.lead)).result.startId)+ // The start's own machine dispatches and confirms it.+ const onMachine = (command: Command) => f.timed.execute(host, f.tab, { operationId: randomUUID(), command }, undefined, 'test-host')+ await onMachine({ type: 'agent.startDispatch', startId })+ const dispatched = f.clock.now+ f.clock.now = dispatched + 3 * MINUTE+ await f.leadInbox()+ expect((await f.timed.read(owner, f.tab)).state.starts!.find(s => s.id === startId)!.error).toBeNull()+ f.clock.now = dispatched + 3 * MINUTE + 1+ const told = (await f.leadInbox()).find(m => (m.source as { kind?: string }).kind === 'start-timeout')!+ expect(told).toMatchObject({ conversationId: 'lead', text: 'Could not start Builder: Worker Mac did not start it within 3 minutes.' })+ await expect(onMachine({ type: 'agent.started', startId, harnessId: randomUUID(), configuration: config }))+ .rejects.toMatchObject({ code: 'START_FAILED' })+ })+})diff --git a/backend/integration/superTabMigration.test.ts b/backend/integration/superTabMigration.test.tsnew file mode 100644index 000000000..0c61616e7--- /dev/null+++ b/backend/integration/superTabMigration.test.ts@@ -0,0 +1,294 @@+import { randomUUID } from 'node:crypto'+import { execFile } from 'node:child_process'+import { promisify } from 'node:util'+import { join } from 'node:path'+import { tmpdir } from 'node:os'+import { afterAll, beforeAll, describe, expect, it } from 'vitest'+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'+import { PrismaClient } from '@prisma/client'+import * as parts from '../src/superTabs/parts/index.js'+import { migrateSwarm } from '../src/superTabs/migration/migrate.js'+import { rollbackFromParts, rollbackLegacy } from '../src/superTabs/migration/rollback.js'+import { migrateAll } from '../src/superTabs/migration/job.js'+import { guardedWrite } from '../src/superTabs/parts/write.js'+import { normalize } from '../src/superTabs/migration/normalize.js'+import { stateDifference } from '../src/superTabs/migration/verify.js'+import { visibleState, type Author, type SuperTabState } from '../src/superTabs/model.js'+import { setLegacyProgress, writeLegacySwarm, type LegacyMessage } from '../scripts/swarm-parts/legacy.js'+import { NOW, richSwarm } from '../src/superTabs/read/fixture.test-support.js'++// A fresh loopback replica set, created here. This suite never reads DATABASE_URL or an existing database.+let replica: MongoMemoryReplSet+let db: PrismaClient+const R = 500+const DAY = 86_400_000+const PR = 'https://github.com/autonomous-ai/openharness/pull/1726'++beforeAll(async () => {+ replica = await MongoMemoryReplSet.create({ binary: { version: '7.0.24', downloadDir: join(tmpdir(), 'harness-super-tab-mongodb-binaries') },+ replSet: { count: 1, ip: '127.0.0.1', storageEngine: 'wiredTiger' } })+ const uri = replica.getUri(`swarm_migration_test_${randomUUID().replaceAll('-', '_')}`)+ await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], {+ env: { ...process.env, DATABASE_URL: uri }, timeout: 60000,+ })+ db = new PrismaClient({ datasources: { db: { url: uri } } })+})+afterAll(async () => {+ await db?.$disconnect()+ await replica?.stop()+})++/** A legacy Swarm at revision R: a finished group quiet for two days, a link only its history holds, some messages. */+async function legacySwarm(edit: (state: SuperTabState, s: ReturnType<typeof richSwarm>) => void = () => {}) {+ const s = richSwarm()+ const tabId = `tab-${randomUUID()}`+ const state = structuredClone(s.state)+ state.id = tabId+ const web = state.conversations.find(c => c.id === s.web)!+ web.assignment = { ...web.assignment!, status: 'done' }+ delete web.pullRequestUrls+ web.lastMessageSequence = 30+ state.conversations.find(c => c.id === 'lead')!.lastMessageSequence = 40+ edit(state, s)+ const author: Author = { kind: 'person', id: 'owner', name: '[email protected]', membershipGeneration: 'tab' }+ const message = (conversationId: string, sequence: number, text: string, at: number): LegacyMessage =>+ ({ id: `${tabId}-${sequence}`, conversationId, sequence, text, author, createdAt: new Date(at) })+ const messages = [message(s.web, 10, 'Starting', NOW - 3 * DAY), message(s.web, 30, `Opened ${PR}`, NOW - 2 * DAY),+ message('lead', 40, 'Thanks', NOW - 1_000)]+ await writeLegacySwarm(db, { state, revision: R, messages })+ return { s, tabId, state, messages }+}+const partCount = (tabId: string) => db.swarmHead.count({ where: { tabId } })++describe('migrating one Swarm to parts (design 6.1.2)', () => {+ it('splits a legacy Swarm into parts that reassemble into its state, fences the row and keeps the old state', async () => {+ const { s, tabId, state } = await legacySwarm()+ const report = await migrateSwarm(db, tabId, { now: () => NOW })+ expect(report).toMatchObject({ tabId, ok: true, groups: state.conversations.length, dormant: 1, messages: 3 })++ const row = (await db.superTab.findUnique({ where: { id: tabId } }))!+ expect(row).toMatchObject({ format: 2, revision: R + 1, state: { version: 2 }, migratedAt: new Date(NOW) })+ expect(row.legacyState).toEqual(JSON.parse(JSON.stringify(state)))++ const stored = await db.$transaction(tx => parts.loadAll(tx, tabId))+ expect(stored).toMatchObject({ sequenceBase: R, visibilityEpoch: 1 })+ const web = stored.groups.find(g => g.key === s.web)!+ expect(web).toMatchObject({ version: R, dormant: true, data: { messageSeq: R, pullRequestUrls: [PR], lastActivityAt: new Date(NOW - 2 * DAY).toISOString() } })+ const expected = normalize({ ...state, conversations: state.conversations.map(c => ({ ...c, pullRequestUrls: c.pullRequestUrls ?? (c.id === s.web ? [PR] : []) })) },+ { now: NOW, lastActivity: new Map([[s.web, NOW - 2 * DAY], ['lead', NOW - 1_000]]) })+ expect(stateDifference(parts.toLegacyState(expected), parts.toLegacyState(parts.reassemble(stored)))).toBeNull()+ expect(await db.superTabMessage.findMany({ where: { tabId }, orderBy: { sequence: 'asc' }, select: { sequence: true } }))+ .toEqual([{ sequence: 10 }, { sequence: 30 }, { sequence: 40 }])+ })++ it('keeps a finished, quiet group awake while its reports are unread, and still verifies', async () => {+ // The web group finished two days ago; its last report (30) is past what the Lead summarized (20).+ const { s, tabId } = await legacySwarm(state => {+ setLegacyProgress(state.projects![0]!, { dirtyRevision: 30, summarizedRevision: 20, since: 1, requestedRevision: 20 })+ })+ expect(await migrateSwarm(db, tabId, { now: () => NOW })).toMatchObject({ ok: true, dormant: 0 })+ const web = (await db.$transaction(tx => parts.loadAll(tx, tabId))).groups.find(g => g.key === s.web)!+ expect(web.dormant).toBeUndefined()+ expect(web.data).toMatchObject({ reportSeq: 30 })+ })++ it('stores the host-fields digest of every conversation it creates (host form version check)', async () => {+ const { tabId, state } = await legacySwarm()+ await migrateSwarm(db, tabId, { now: () => NOW })+ const rows = await db.swarmGroup.findMany({ where: { tabId }, select: { key: true, hostDigest: true } })+ expect(rows).toHaveLength(state.conversations.length)+ expect(rows.filter(r => !r.hostDigest)).toEqual([])+ })++ it('skips a Swarm that is already in parts, changing nothing', async () => {+ const { tabId } = await legacySwarm()+ await migrateSwarm(db, tabId, { now: () => NOW })+ const before = await db.superTab.findUnique({ where: { id: tabId } })+ expect(await migrateSwarm(db, tabId, { now: () => NOW + 1 })).toMatchObject({ tabId, ok: true, skipped: true })+ expect(await db.superTab.findUnique({ where: { id: tabId } })).toEqual(before)+ })++ it('writes nothing and names the first difference when the parts would not reassemble into the old state', async () => {+ // Report progress past every group's last message cannot be told apart from the groups; the Swarm stays as it was.+ const { tabId } = await legacySwarm(state => {+ setLegacyProgress(state.projects![0]!, { dirtyRevision: 45, summarizedRevision: 0, since: 1, requestedRevision: 0 })+ })+ const report = await migrateSwarm(db, tabId, { now: () => NOW })+ expect(report).toMatchObject({ tabId, ok: false })+ expect(report.error).toContain('projects[0].progress.dirtyRevision: 45 ≠ 30')+ expect(await db.superTab.findUnique({ where: { id: tabId } })).toMatchObject({ format: 1, revision: R, legacyState: null })+ expect(await partCount(tabId)).toBe(0)+ })++ it('refuses to migrate a Swarm with a message whose conversation it does not have', async () => {+ const { tabId } = await legacySwarm()+ await db.superTabMessage.create({ data: { id: `${tabId}-orphan`, tabId, conversationId: 'gone', sequence: 7, author: {}, text: 'lost',+ recipientIds: [], mentions: [] } })+ const report = await migrateSwarm(db, tabId, { now: () => NOW })+ expect(report).toMatchObject({ ok: false })+ expect(report.error).toContain('1 message in a conversation it does not have: gone')+ expect(await partCount(tabId)).toBe(0)+ })+})++describe('link lists rebuilt from history (moved from the store, design R8)', () => {+ const link = (n: number) => `https://github.com/autonomous-ai/openharness/pull/${n}`+ const links = async (tabId: string, group: string) => (await db.$transaction(tx => parts.loadAll(tx, tabId))).groups.find(g => g.key === group)!.data!.pullRequestUrls++ /** The done group from before link lists. */+ const legacyDone = (state: SuperTabState, s: ReturnType<typeof richSwarm>) => { delete state.conversations.find(c => c.id === s.done)!.pullRequestUrls }++ it('finds a link in a message older than the latest page of 100', async () => {+ const { s, tabId } = await legacySwarm(legacyDone)+ const author: Author = { kind: 'person', id: 'owner', name: '[email protected]', membershipGeneration: 'tab' }+ await db.superTabMessage.createMany({ data: Array.from({ length: 150 }, (_, i) => ({ id: `${tabId}-page-${i}`, tabId, conversationId: s.done,+ sequence: 100 + i, author: author as never, text: i === 0 ? `First PR ${link(11)}` : `Update ${i}`, recipientIds: [], mentions: [] })) })+ await migrateSwarm(db, tabId, { now: () => NOW })+ expect(await links(tabId, s.done)).toEqual([link(11)])+ })++ it('finds links in check evidence and in a work result', async () => {+ const { s, tabId } = await legacySwarm((state, s) => {+ legacyDone(state, s)+ const done = state.conversations.find(c => c.id === s.done)!+ done.checks = [{ id: 'c1', description: 'Works', independent: false, evidence: `Ran it in ${link(21)}`, passedBy: 'agent' }]+ done.assignment = { ...state.conversations.find(c => c.id === s.web)!.assignment!, id: 'w2', status: 'done', result: `Merged ${link(22)}` }+ })+ await migrateSwarm(db, tabId, { now: () => NOW })+ expect(await links(tabId, s.done)).toEqual([link(21), link(22)])+ })++ it('finds links in earlier attempts of the group', async () => {+ const { s, tabId } = await legacySwarm(legacyDone)+ await db.superTabAttempt.create({ data: { id: `${tabId}-attempt`, tabId, conversationId: s.done,+ snapshot: { checks: [{ evidence: `Tried ${link(31)}` }], assignment: { result: `Abandoned ${link(32)}` } } } })+ await migrateSwarm(db, tabId, { now: () => NOW })+ expect(await links(tabId, s.done)).toEqual([link(31), link(32)])+ })+})++describe('rolling back (design 6.4)', () => {+ it('before any new write, puts the old state back unchanged and drops the Swarm\'s parts', async () => {+ const { tabId, state } = await legacySwarm()+ await migrateSwarm(db, tabId, { now: () => NOW })+ expect(await rollbackLegacy(db, tabId)).toMatchObject({ tabId, ok: true })+ expect(await db.superTab.findUnique({ where: { id: tabId } })).toMatchObject({ format: 1, revision: R + 1, migratedAt: null, legacyState: null,+ state: JSON.parse(JSON.stringify(state)) })+ expect(await partCount(tabId)).toBe(0)+ // And it migrates again from there.+ expect(await migrateSwarm(db, tabId, { now: () => NOW })).toMatchObject({ ok: true })+ })++ it('refuses the plain rollback once parts were written after the migration, since it would lose them', async () => {+ const { s, tabId } = await legacySwarm()+ await migrateSwarm(db, tabId, { now: () => NOW })+ await db.$transaction(async tx => {+ const lead = (await parts.loadActive(tx, tabId)).groups.find(g => g.key === 'lead')!+ await guardedWrite(tx, tabId, { op: 'update', kind: 'group', key: 'lead', seen: lead.version, data: { ...lead.data!, title: 'Changed' } }, NOW + 1)+ })+ void s+ expect(await rollbackLegacy(db, tabId)).toMatchObject({ ok: false, error: expect.stringContaining('written since') })+ expect(await db.superTab.findUnique({ where: { id: tabId } })).toMatchObject({ format: 2 })+ })++ it('after new writes, rebuilds the old state from the parts, numbering past every sequence and number used since', async () => {+ const { s, tabId } = await legacySwarm()+ await migrateSwarm(db, tabId, { now: () => NOW })+ await db.$transaction(async tx => {+ const loaded = await parts.loadActive(tx, tabId)+ const lead = loaded.groups.find(g => g.key === 'lead')!+ await guardedWrite(tx, tabId, { op: 'update', kind: 'group', key: 'lead', seen: lead.version,+ data: { ...lead.data!, title: 'Changed', messageSeq: R + 3, lastMessageSequence: R + 3 } }, NOW + 1)+ await guardedWrite(tx, tabId, { op: 'update', kind: 'head', key: 'head', seen: loaded.head.version, data: loaded.head.data,+ head: { groupCounter: 9, visibilityEpoch: 1, sequenceBase: R } }, NOW + 1)+ })+ await db.superTabMessage.create({ data: { id: `${tabId}-new`, tabId, conversationId: 'lead', sequence: R + 3, author: {}, text: 'New', recipientIds: [], mentions: [] } })+ expect(await rollbackFromParts(db, tabId)).toMatchObject({ tabId, ok: true })+ const row = (await db.superTab.findUnique({ where: { id: tabId } }))!+ expect(row).toMatchObject({ format: 1, revision: R + 4, migratedAt: null })+ const state = row.state as unknown as SuperTabState+ expect(state.version).toBe(1)+ expect(state.conversations.find(c => c.id === 'lead')).toMatchObject({ title: 'Changed', lastMessageSequence: R + 3 })+ expect(state.conversations.find(c => c.id === 'lead')).not.toHaveProperty('messageSeq')+ expect(state).not.toHaveProperty('groupCounter')+ expect(state.retiredConversationNumber).toBe(9)+ expect(state.conversations.find(c => c.id === s.web)!.pullRequestUrls).toEqual([PR])+ // The previous release reads it as it read any Swarm.+ expect(() => visibleState(state, { kind: 'person', userId: state.ownerId, email: '[email protected]' }, NOW)).not.toThrow()+ })++ // Final review, Critical 2: the previous release checks no audience (private conversations become readable by every+ // project reader) and reads lost work as active. A rollback that would hand it either is refused before any row changes.+ /** A write in parts after the migration, as the new release makes it: one group changed, or a new one. */+ async function writeGroup(tabId: string, key: string, change: (group: parts.SwarmParts['groups'][number]['data']) => object) {+ await db.$transaction(async tx => {+ const groups = (await parts.loadAll(tx, tabId)).groups+ const group = groups.find(g => g.key === key)+ if (group) return void await guardedWrite(tx, tabId, { op: 'update', kind: 'group', key, seen: group.version, data: change(group.data) }, NOW + 1)+ const lead = groups.find(g => g.key === 'lead')!+ await guardedWrite(tx, tabId, { op: 'insert', kind: 'group', key, ordinal: Math.max(...groups.map(g => g.ordinal)) + 1,+ data: change({ ...lead.data!, id: key, number: 90, assignment: null, lastMessageSequence: 0 }) }, NOW + 1)+ })+ }+ /** Every row a rollback could change: the Swarm's row and its parts. */+ const rows = async (tabId: string) => ({ tab: await db.superTab.findUnique({ where: { id: tabId } }),+ parts: await db.$transaction(tx => parts.loadAll(tx, tabId)) })++ it('refuses to roll back from the parts while a conversation is private, changing no row, and says how to recover', async () => {+ const { tabId } = await legacySwarm()+ await migrateSwarm(db, tabId, { now: () => NOW })+ await writeGroup(tabId, 'chat-with-pm', group => ({ ...group, title: 'Chat with PM', audience: { people: [{ id: 'owner', generation: 'tab' }] } }))+ const before = await rows(tabId)+ const report = await rollbackFromParts(db, tabId)+ expect(report).toMatchObject({ tabId, ok: false })+ expect(report.error).toContain(tabId)+ expect(report.error).toContain('private conversation')+ expect(report.error).toMatch(/roll forward with a fix/i)+ expect(await rows(tabId)).toEqual(before)+ })++ it('refuses while a task is lost, or was lost and then cancelled, changing no row', async () => {+ for (const status of ['lost', 'cancelled'] as const) {+ const { s, tabId } = await legacySwarm()+ await migrateSwarm(db, tabId, { now: () => NOW })+ await writeGroup(tabId, s.web, group => ({ ...group, assignment: { ...group!.assignment!, status, lost: { reason: 'no progress seen', at: NOW } },+ lostAttempt: { id: group!.assignment!.id, agentId: group!.assignment!.agentId } }))+ const before = await rows(tabId)+ const report = await rollbackFromParts(db, tabId)+ expect([status, report]).toMatchObject([status, { tabId, ok: false, error: expect.stringContaining('lost') }])+ // A cancelled task is finished on the previous backend too; what it loses is the lost marker (final review, Minor).+ expect(report.error).toContain(status === 'lost' ? 'would read as active work' : 'lost and then cancelled would lose the lost marker')+ expect(report.error).toMatch(/roll forward with a fix/i)+ expect(await rows(tabId)).toEqual(before)+ }+ })++ it('still rolls back from the parts a Swarm with new writes but no private conversation and no lost work', async () => {+ const { tabId } = await legacySwarm()+ await migrateSwarm(db, tabId, { now: () => NOW })+ await writeGroup(tabId, 'lead', group => ({ ...group, title: 'Changed after the migration' }))+ expect(await rollbackFromParts(db, tabId)).toMatchObject({ tabId, ok: true })+ expect(await db.superTab.findUnique({ where: { id: tabId } })).toMatchObject({ format: 1 })+ })+})++describe('the migration job (design 6.1.1)', () => {+ const instant = async () => {}++ it('refuses to start while a writer is still running', async () => {+ const { tabId } = await legacySwarm()+ const sleep = async () => { await db.superTabMessage.create({ data: { id: `${tabId}-late`, tabId, conversationId: 'lead', sequence: R, author: {},+ text: 'Still here', recipientIds: [], mentions: [] } }) }+ await expect(migrateAll(db, { now: () => NOW, sleep })).rejects.toThrow('a writer is still running')+ expect(await db.superTab.findUnique({ where: { id: tabId } })).toMatchObject({ format: 1 })+ })++ it('migrates every Swarm still in one row once writers are quiet, and reports each one', async () => {+ const [a, b] = [await legacySwarm(), await legacySwarm()]+ const run = await migrateAll(db, { now: () => NOW, sleep: instant })+ expect(run.reports.map(r => r.tabId)).toEqual(expect.arrayContaining([a.tabId, b.tabId]))+ expect(run.reports.find(r => r.tabId === a.tabId)).toMatchObject({ ok: true, groups: a.state.conversations.length })+ expect(run.totals).toMatchObject({ swarms: run.reports.length, failed: run.reports.filter(r => !r.ok).length })+ expect(await db.superTab.count({ where: { id: { in: [a.tabId, b.tabId] }, format: 2 } })).toBe(2)+ })+})diff --git a/backend/integration/superTabRead.test.ts b/backend/integration/superTabRead.test.tsnew file mode 100644index 000000000..453446bdc--- /dev/null+++ b/backend/integration/superTabRead.test.ts@@ -0,0 +1,659 @@+import { randomUUID } from 'node:crypto'+import { execFile } from 'node:child_process'+import { promisify } from 'node:util'+import { join } from 'node:path'+import { tmpdir } from 'node:os'+import { afterAll, beforeAll, describe, expect, it } from 'vitest'+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'+import { PrismaClient } from '@prisma/client'+import Fastify, { type FastifyInstance } from 'fastify'+import type { AuthUser } from '../src/lib/ssoAuth.js'+import { SuperTabStore } from '../src/superTabs/store.js'+import { superTabRoutes } from '../src/routes/superTabs.js'+import { errorHandler } from '../src/middlewares/errorHandler.js'+import * as parts from '../src/superTabs/parts/index.js'+import { guardedWrite } from '../src/superTabs/parts/write.js'+import { migrateSwarm } from '../src/superTabs/migration/migrate.js'+import { SwarmReads } from '../src/superTabs/read/service.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'+import { NOW, outsider as outsiderActor, owner as ownerActor, peer as peerActor, swarm } from '../src/superTabs/read/fixture.test-support.js'++// A fresh loopback replica set, created here. This suite never reads DATABASE_URL or an existing database.+let replica: MongoMemoryReplSet+let db: PrismaClient+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 R = 700+const MIGRATED = NOW - 60_000+const DAY = 86_400_000++beforeAll(async () => {+ replica = await MongoMemoryReplSet.create({ binary: { version: '7.0.24', downloadDir: join(tmpdir(), 'harness-super-tab-mongodb-binaries') },+ replSet: { count: 1, ip: '127.0.0.1', storageEngine: 'wiredTiger' } })+ const uri = replica.getUri(`swarm_read_test_${randomUUID().replaceAll('-', '_')}`)+ await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], {+ env: { ...process.env, DATABASE_URL: uri }, timeout: 60000,+ })+ db = new PrismaClient({ datasources: { db: { url: uri } } })+ for (const each of [owner, peer, outsider]) await db.user.create({ data: { id: each.sub, externalId: `fixture-${each.sub}`, email: each.email, autonomousEnv: 'prod' } })+ // The owner's own machine runs the Swarm's agents, so reading as one of them needs no machine share.+ await db.machine.create({ data: { machineId: 'host', userId: owner.sub, apiKey: 'fixture-only', managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })+ const store = new SuperTabStore(db)+ app = Fastify()+ app.setErrorHandler(errorHandler)+ // External SSO is replaced with fixture accounts; every permission and transaction below is real.+ app.addHook('onRequest', async (request, reply) => {+ const found = [owner, peer, outsider].find(u => `Bearer ${u.sub}` === request.headers.authorization)+ if (!found) return reply.code(401).send({ success: false })+ request.user = found+ })+ await app.register(superTabRoutes, { store, github: null, reads: new SwarmReads(store, { now: () => clock }),+ hosts: new HostReads(store, { now: () => clock }) })+ await app.ready()+})+afterAll(async () => {+ await app?.close()+ await db?.$disconnect()+ await replica?.stop()+})++/** A Swarm in parts: two projects (one private to its owner), a Lead and a worker on the owner's machine, finished work+ * quiet for two days (dormant), and a private conversation for `peer`. */+async function scene<T = void>(extra: (s: ReturnType<typeof swarm>, ids: { web: string; done: string; lead: string; secret: string }) => T = () => undefined as T, machineId = 'host') {+ const s = swarm(MIGRATED)+ s.join(peerActor)+ s.join(outsiderActor)+ const lead = s.add('lead-harness', 'lead', true, ownerActor, machineId, owner.sub)+ const secret = s.run({ type: 'project.create', name: 'Secret', visibility: 'private', brief: '' }).projectId as string+ const web = s.group('Web')+ const worker = s.add('worker-harness', web, false, ownerActor, machineId, owner.sub)+ s.run({ type: 'work.assign', conversationId: web, agentId: worker })+ const done = s.group('Done work')+ const secretGroup = s.group('Secret work', secret)+ const privateId = s.group('Peer and PM')+ s.edit(state => {+ const generation = state.people.find(p => p.id === peer.sub)!.generation+ state.conversations.find(c => c.id === privateId)!.audience = { people: [{ id: peer.sub, generation }] }+ const finished = state.conversations.find(c => c.id === done)!+ finished.assignment = { ...state.conversations.find(c => c.id === web)!.assignment!, id: 'old-work', status: 'done' }+ })+ const more = extra(s, { web, done, lead, secret })+ const tabId = `tab-${randomUUID()}`+ const state = { ...structuredClone(s.state), id: tabId } as SuperTabState+ await writeLegacySwarm(db, { state, revision: R, messages: [{ id: `${tabId}-m1`, conversationId: done, sequence: 5, text: 'Done',+ author: { kind: 'person', id: owner.sub, name: owner.email, membershipGeneration: tabId }, createdAt: new Date(MIGRATED - 2 * DAY) }] })+ const report = await migrateSwarm(db, tabId, { now: () => MIGRATED })+ if (!report.ok) throw new Error(report.error)+ return { tabId, lead, worker, web, done, secretGroup, privateId, secret, leads: state.leadsConversationId!, more }+}+const get = async (url: string, as: AuthUser = owner) => {+ const response = await app.inject({ method: 'GET', url, headers: { authorization: `Bearer ${as.sub}` } })+ return { status: response.statusCode, body: response.json() as { data: any; error?: { code: string; message: string } } }+}+const keys = (list: Array<{ key: string }>) => list.map(p => p.key)+/** A later write of one group by a command, as group 2's store does it, stamped `at`. */+async function writeGroup(tabId: string, key: string, at: number, change: (group: Conversation) => void, op: 'update' | 'remove' = 'update') {+ await db.$transaction(async tx => {+ const current = (await parts.loadActive(tx, tabId, { groupIds: [key] })).groups.find(g => g.key === key)!+ const data = structuredClone(current.data!) as Conversation+ change(data)+ await guardedWrite(tx, tabId, { op, kind: 'group', key, seen: current.version, data }, at)+ })+}++describe('first load (design 4.3)', () => {+ it('answers the design\'s shape: cursor 30 s before the read, epoch, newest change, the reader\'s parts and derived values', async () => {+ const s = await scene()+ clock = NOW+ const { status, body } = await get(`/api/super-tabs/${s.tabId}/parts`, peer)+ expect(status).toBe(200)+ expect(Object.keys(body.data).sort()).toEqual(['agents', 'cursor', 'derived', 'epoch', 'format', 'groups', 'head', 'lastChangedAt',+ 'machines', 'members', 'progress', 'serverTime', 'starts', 'tabId'].sort())+ expect(body.data).toMatchObject({ format: 2, tabId: s.tabId, serverTime: NOW, epoch: 1, lastChangedAt: MIGRATED,+ head: { key: 'head', version: R, changedAt: MIGRATED, data: { id: s.tabId, name: 'Pilot' } } })+ expect(JSON.parse(Buffer.from(body.data.cursor, 'base64url').toString())).toEqual({ v: 2, t: NOW - 30_000, e: 1 })+ expect(keys(body.data.members)).toEqual([owner.sub, peer.sub, outsider.sub])+ expect(keys(body.data.groups)).toEqual(['lead', s.web, s.privateId, s.leads])+ expect(body.data.derived).toMatchObject({ agents: { [s.lead]: { downSince: null }, [s.worker]: { workDecision: null } }, mentionsWaiting: 0 })+ })++ it('keeps the private conversation and the private project from every reader outside them', async () => {+ const s = await scene()+ const groups = async (as: AuthUser, agent?: string) =>+ keys((await get(`/api/super-tabs/${s.tabId}/parts${agent ? `?asAgentId=${agent}` : ''}`, as)).body.data.groups)+ expect(await groups(outsider)).not.toContain(s.privateId)+ expect(await groups(outsider)).not.toContain(s.secretGroup)+ expect(await groups(owner)).not.toContain(s.privateId)+ expect(await groups(owner)).toContain(s.secretGroup)+ expect(await groups(owner, s.lead)).toContain(s.privateId)+ expect(await groups(owner, s.worker)).not.toContain(s.privateId)+ })++ it('migrates a Swarm still in one row on first access', async () => {+ const s = swarm(MIGRATED)+ const tabId = `tab-${randomUUID()}`+ await writeLegacySwarm(db, { state: { ...structuredClone(s.state), id: tabId }, revision: 3 })+ const { status, body } = await get(`/api/super-tabs/${tabId}/parts`)+ expect(status).toBe(200)+ expect(body.data.head.version).toBe(3)+ expect(await db.superTab.findUnique({ where: { id: tabId } })).toMatchObject({ format: 2 })+ })++ it('answers "being upgraded" when a Swarm cannot be migrated yet, and every client retries that', async () => {+ const s = swarm(MIGRATED)+ const tabId = `tab-${randomUUID()}`+ await writeLegacySwarm(db, { state: { ...structuredClone(s.state), id: tabId }, revision: 3 })+ await db.superTabMessage.create({ data: { id: `${tabId}-orphan`, tabId, conversationId: 'gone', sequence: 1, author: {}, text: 'x', recipientIds: [], mentions: [] } })+ const { status, body } = await get(`/api/super-tabs/${tabId}/parts`)+ expect(status).toBe(503)+ expect(body.error!.code).toBe('SWARM_MIGRATING')+ })+})++describe('changes since a cursor (design 4.2, 4.4)', () => {+ async function firstLoad(tabId: string, as: AuthUser, at: number) {+ clock = at+ return (await get(`/api/super-tabs/${tabId}/parts`, as)).body.data.cursor as string+ }+ const changes = async (tabId: string, cursor: string, as: AuthUser, at: number) => {+ clock = at+ return get(`/api/super-tabs/${tabId}/changes?cursor=${cursor}`, as)+ }++ it('sends only what changed, whole, to the readers who may see it', async () => {+ const s = await scene()+ const [peerCursor, outsiderCursor] = [await firstLoad(s.tabId, peer, NOW), await firstLoad(s.tabId, outsider, NOW)]+ expect((await changes(s.tabId, peerCursor, peer, NOW + 1_000)).body.data).toMatchObject({ reload: false, head: null, groups: [], agents: [] })+ await writeGroup(s.tabId, s.web, NOW + 2_000, g => { g.title = 'Web 2' })+ await writeGroup(s.tabId, s.privateId, NOW + 2_000, g => { g.title = 'Private 2' })+ const seen = (await changes(s.tabId, peerCursor, peer, NOW + 3_000)).body.data+ expect(seen).toMatchObject({ format: 2, reload: false, serverTime: NOW + 3_000, epoch: 1, lastChangedAt: NOW + 2_000 })+ expect(seen.groups.map((g: { key: string; version: number; data: { title: string } }) => [g.key, g.version, g.data.title]))+ .toEqual([[s.web, R + 1, 'Web 2'], [s.privateId, R + 1, 'Private 2']])+ expect(keys((await changes(s.tabId, outsiderCursor, outsider, NOW + 3_000)).body.data.groups)).toEqual([s.web])+ })++ it('leaves out a conversation of a kind this release does not know, in changes as in a first load (rolling deploys)', async () => {+ const s = await scene()+ clock = Date.now()+ const cursor = (await get(`/api/super-tabs/${s.tabId}/parts`, owner)).body.data.cursor+ // A newer release wrote a conversation of a kind this one parks (model.ts parkLaterConversations).+ await db.$transaction(tx => guardedWrite(tx, s.tabId, { op: 'insert', kind: 'group', key: 'later-kind', ordinal: Date.now(), first: R + 1,+ data: { id: 'later-kind', kind: 'board', title: 'Board', leadId: null, agentIds: [], archived: false, brief: 'Not for this release', checks: [],+ assignment: null, lastMessageSequence: 0 } }, Date.now()))+ clock = Date.now()+ expect(keys((await get(`/api/super-tabs/${s.tabId}/parts`, owner)).body.data.groups)).not.toContain('later-kind')+ expect(keys((await get(`/api/super-tabs/${s.tabId}/changes?cursor=${cursor}`, owner)).body.data.groups)).not.toContain('later-kind')+ })++ /** Derived values from a whole first load and from a change read in the same moment must agree (parts/light.ts). */+ async function derivedBoth(tabId: string, as: AuthUser) {+ clock = Date.now()+ const first = (await get(`/api/super-tabs/${tabId}/parts`, as)).body.data+ const changed = (await get(`/api/super-tabs/${tabId}/changes?cursor=${first.cursor}`, as)).body.data+ return { full: first.derived, light: changed.derived }+ }+ /** The web group's task was lost, then cancelled: its worker keeps no decision (liveness.ts, commands.ts work.cancel). */+ const lostThenCancelled = (state: SuperTabState, web: string, worker: string) => {+ const group = state.conversations.find(c => c.id === web)!+ group.assignment = { ...group.assignment!, status: 'cancelled', result: 'Gone quiet', lost: { reason: 'no progress seen', at: MIGRATED } }+ group.lostAttempt = { id: group.assignment.id, agentId: worker }+ delete state.agents.find(a => a.id === worker)!.workDecision+ }+ /** After the migration (which stores derived decisions), the worker has none: as a loss after it leaves it. */+ async function noDecision(tabId: string, agentId: string) {+ await db.$transaction(async tx => {+ const agent = (await parts.loadActive(tx, tabId)).agents.find(a => a.key === agentId)!+ const { workDecision: _gone, ...data } = agent.data!+ await guardedWrite(tx, tabId, { op: 'update', kind: 'agent', key: agentId, seen: agent.version, data }, MIGRATED + 1)+ })+ }+ const mention = (tabId: string, conversationId: string, personId: string) => db.superTabMention.create({ data: { id: `${tabId}-${conversationId}-m`,+ tabId, conversationId, messageId: `${tabId}-msg`, personId, projectId: 'lead', authorAgentId: 'lead-agent', createdAt: new Date() } })++ it('derives the same decisions from a change read as from a first load after a task was lost, then cancelled', async () => {+ const s = await scene((f, ids) => f.edit(state => lostThenCancelled(state, ids.web, state.agents.find(a => a.name === 'worker-harness')!.id)))+ await noDecision(s.tabId, s.worker)+ await mention(s.tabId, s.web, peer.sub)+ const { full, light } = await derivedBoth(s.tabId, peer)+ expect(full.agents[s.worker].workDecision).toBeNull()+ expect(light).toEqual(full)+ })++ it('and when that worker also has an earlier ordinary finished task, which the first load does count', async () => {+ const s = await scene((f, ids) => {+ const earlier = f.group('Earlier work')+ f.edit(state => {+ const worker = state.agents.find(a => a.name === 'worker-harness')!.id+ lostThenCancelled(state, ids.web, worker)+ const group = state.conversations.find(c => c.id === earlier)!+ group.agentIds.push(worker)+ group.assignment = { ...state.conversations.find(c => c.id === ids.web)!.assignment!, id: 'earlier-work', status: 'done', result: 'Shipped' }+ delete group.assignment.lost+ })+ })+ await noDecision(s.tabId, s.worker)+ const { full, light } = await derivedBoth(s.tabId, peer)+ expect(full.agents[s.worker].workDecision).toBe('awaiting')+ expect(light).toEqual(full)+ })++ it('never sends a private conversation\'s removal to a reader outside it', async () => {+ const s = await scene()+ const [peerCursor, outsiderCursor] = [await firstLoad(s.tabId, peer, NOW), await firstLoad(s.tabId, outsider, NOW)]+ await writeGroup(s.tabId, s.privateId, NOW + 2_000, () => {}, 'remove')+ expect((await changes(s.tabId, peerCursor, peer, NOW + 3_000)).body.data.groups).toEqual([{ key: s.privateId, version: R + 1, changedAt: NOW + 2_000, deleted: true }])+ expect((await changes(s.tabId, outsiderCursor, outsider, NOW + 3_000)).body.data.groups).toEqual([])+ })++ it('still delivers a write that committed after the read but was stamped inside the 30 s overlap', async () => {+ const s = await scene()+ const cursor = await firstLoad(s.tabId, peer, NOW)+ // A command that started before the read and committed after it, 10 s later than its stamp.+ await writeGroup(s.tabId, s.web, NOW - 10_000, g => { g.title = 'Late' })+ // One stamped before the overlap would be missed; transactions are cut at 15 s, so that never commits.+ await writeGroup(s.tabId, s.done, NOW - 30_001, g => { g.title = 'Too late' })+ expect(keys((await changes(s.tabId, cursor, peer, NOW + 3_000)).body.data.groups)).toEqual([s.web])+ })++ it('asks for a full reload when the cursor is older than tombstones are kept, or from another epoch', async () => {+ const s = await scene()+ const cursor = await firstLoad(s.tabId, peer, NOW)+ expect((await changes(s.tabId, cursor, peer, NOW - 30_000 + 7 * DAY)).body.data).toEqual({ reload: true })+ await db.swarmHead.updateMany({ where: { tabId: s.tabId }, data: { visibilityEpoch: 2 } })+ expect((await changes(s.tabId, cursor, peer, NOW + 1_000)).body.data).toEqual({ reload: true })+ expect((await changes(s.tabId, 'not-a-cursor', peer, NOW + 1_000)).body.data).toEqual({ reload: true })+ })+})++describe('dormant groups on demand (design 4.5)', () => {+ it('pages dormant groups newest first, 50 at a time, without the ones the reader may not see', async () => {+ const s = await scene(f => {+ for (let i = 0; i < 52; i++) f.run({ type: 'conversation.archive', conversationId: f.group(`Old ${i}`), archived: true })+ })+ await writeGroup(s.tabId, s.privateId, NOW, g => { g.dormant = true; g.lastActivityAt = new Date(NOW).toISOString() })+ const first = (await get(`/api/super-tabs/${s.tabId}/groups?dormant=1`, outsider)).body.data+ expect(first.groups).toHaveLength(49)+ expect(first.groups.every((g: { data: { dormant: boolean } }) => g.data.dormant)).toBe(true)+ expect(keys(first.groups)).not.toContain(s.privateId)+ const second = (await get(`/api/super-tabs/${s.tabId}/groups?dormant=1&before=${first.next}`, outsider)).body.data+ expect(second).toMatchObject({ next: null })+ expect(new Set([...keys(first.groups), ...keys(second.groups)]).size).toBe(53)+ expect(keys((await get(`/api/super-tabs/${s.tabId}/groups?dormant=1`, peer)).body.data.groups)[0]).toBe(s.privateId)+ })++ it('reads one group by id, dormant or not, and 404s one the reader may not see', async () => {+ const s = await scene()+ expect((await get(`/api/super-tabs/${s.tabId}/groups/${s.done}`, outsider)).body.data.group)+ .toMatchObject({ key: s.done, version: R, data: { id: s.done, dormant: true, messageSeq: R } })+ expect((await get(`/api/super-tabs/${s.tabId}/groups/${s.privateId}`, peer)).status).toBe(200)+ for (const [id, as] of [[s.privateId, outsider], [s.privateId, owner], [s.secretGroup, outsider], ['missing', owner]] as const) {+ const { status, body } = await get(`/api/super-tabs/${s.tabId}/groups/${id}`, as)+ expect([status, body.error!.code]).toEqual([404, 'NOT_FOUND'])+ }+ })+})++describe('Swarm list and old routes (design 4.9, 4.11)', () => {+ it('lists the caller\'s Swarms with their newest change', async () => {+ const s = await scene()+ const { body } = await get('/api/super-tabs/list', outsider)+ expect(body.data.tabs).toContainEqual({ id: s.tabId, name: 'Pilot', ownerId: owner.sub, paused: false, lastChangedAt: MIGRATED })+ })++ it.each(['/api/super-tabs', '/api/super-tabs/TAB', '/api/super-tabs/hosts/host', '/api/super-tabs/hosts/host/pools', '/api/super-tabs/hosts/host/assignments'])(+ 'answers %s with 426 Update required', async url => {+ const s = await scene()+ const { status, body } = await get(url.replace('TAB', s.tabId))+ expect(status).toBe(426)+ expect(body.error).toEqual({ code: 'UPDATE_REQUIRED', message: 'Update Harness to keep using this Swarm.' })+ })+})++describe('host form (design 4.10)', () => {+ /** The owner's machine `host` contributed to the Swarm, a third agent whose only group is dormant, a queued start. */+ let machine = 'host'+ /** Each test has its own machine, so other tests' Swarms never show up in its host reads. */+ const hostScene = async () => {+ machine = `m-${randomUUID().slice(0, 8)}`+ await db.machine.create({ data: { machineId: machine, userId: owner.sub, apiKey: 'fixture-only', managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })+ return scene((s, ids) => {+ s.contribute(machine, 'swarm')+ const idle = s.add('idle-harness', ids.done, false, ownerActor, machine, owner.sub)+ // An agent whose only group has nothing else of this machine in it (no Lead, no running work here).+ const lonerGroup = s.group('Loner home', ids.secret)+ const loner = s.add('loner-harness', lonerGroup, false, ownerActor, machine, owner.sub)+ // In the project without a Lead, so no agent of this machine is in it.+ const archived = s.group('Archived, no agent here', ids.secret)+ s.run({ type: 'conversation.archive', conversationId: archived, archived: true })+ s.edit(state => {+ const pool = state.machines!.find(m => m.machineId === machine)!+ // One in a running group, one in a dormant group none of its agents is in: the host still has to settle it.+ state.starts = [[ids.web, 'queued'], [archived, 'queued-in-dormant']].map(([conversationId, id]) => ({ id: id!, creationId: 'c',+ actorKey: `person:${owner.sub}`, contributorId: owner.sub, membershipGeneration: pool.membershipGeneration,+ machineOwnerId: owner.sub, hostGrant: null, harnessId: null, dispatched: false, error: null, poolGeneration: pool.generation,+ request: { conversationId: conversationId!, machineId: machine, engine: 'codex', name: 'Builder', cwd: '/repo', worktree: false,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } } }))+ })+ return { idle, loner, lonerGroup }+ }, machine)+ }+ const host = async (cursor?: string, full = false, as: AuthUser = owner) =>+ get(`/api/super-tabs/hosts/${machine}/changes?${[cursor && `cursor=${cursor}`, full && 'full=1'].filter(Boolean).join('&')}`, as)+ type Row = { agent?: { id: string }; lead?: boolean; active?: boolean; leadsConversationId?: string; observers?: Array<{ userId: string }>; lastChangedAt?: number }++ it('gives a full read of the machine\'s Swarm: today\'s roster, pool and assignment rows, from the parts', async () => {+ const s = await hostScene()+ clock = NOW+ const { status, body } = await host(undefined, true)+ expect(status).toBe(200)+ expect(body.data).toMatchObject({ format: 2, full: true, removedTabIds: [] })+ const tab = body.data.tabs.find((t: { tabId: string }) => t.tabId === s.tabId)+ expect(tab.lastChangedAt).toBe(MIGRATED)+ const rows = new Map<string, Row>(tab.roster.filter((r: Row) => r.agent).map((r: Row) => [r.agent!.id, r]))+ expect([...rows.keys()].sort()).toEqual([s.lead, s.worker, s.more.idle, s.more.loner].sort())+ // Nobody but its machine's owner watches a Lead (final review, Critical 1); a Builder's readers still do.+ expect(rows.get(s.lead)).toMatchObject({ lead: true, active: true, leadsConversationId: s.leads, lastChangedAt: MIGRATED, observers: [] })+ expect(rows.get(s.worker)).toMatchObject({ observers: [{ email: peer.email, userId: peer.sub }, { email: outsider.email, userId: outsider.sub }] })+ // Its only group is finished and dormant, yet not archived: the host must not hand it to automatic cleanup.+ expect(rows.get(s.more.idle)).toMatchObject({ lead: false, active: true })+ expect(tab.pool).toMatchObject({ tabId: s.tabId, machine: { machineId: machine }, starts: [{ id: 'queued' }, { id: 'queued-in-dormant' }] })+ expect(tab.pool.projects[0].conversationIds).toContain(s.web)+ expect(tab.pool.projects[0].conversationIds).not.toContain(s.privateId)+ expect(tab.assignments).toEqual([{ tabId: s.tabId, assignmentId: expect.any(String), harnessId: 'worker-harness' }])+ })++ it('wakes the host only for changes that concern its machine', async () => {+ const s = await hostScene()+ const { cursor } = await fullRead(s.tabId)+ clock = Date.now()+ expect((await host(cursor)).body.data).toMatchObject({ full: false, tabs: [], removedTabIds: [] })+ await command(s.tabId, { type: 'conversation.rename', conversationId: s.secretGroup, title: 'Not this machine' })+ clock = Date.now()+ expect((await host(cursor)).body.data.tabs).toEqual([])+ await command(s.tabId, { type: 'conversation.rename', conversationId: s.web, title: 'Its worker\'s group' })+ clock = Date.now()+ expect((await host(cursor)).body.data.tabs.map((t: { tabId: string }) => t.tabId)).toEqual([s.tabId])+ })++ /** The machine's reading, through the store as its host sends it every 15 s. */+ async function reading(tabId: string, generation: string) {+ await new SuperTabStore(db).observeMachine(owner, tabId, machine, { generation, resources: { cpuPercent: 5, memoryTotalBytes: null,+ memoryUsedBytes: null, diskFreeBytes: null, diskTotalBytes: null, projectDiskFreeBytes: null, deviceType: null, chip: null, os: null,+ gpuPercent: null }, tools: {}, quotas: [], runningHarnessIds: ['lead-harness', 'worker-harness', 'idle-harness', 'loner-harness'],+ stoppedHarnessIds: [] })+ }+ const command = (tabId: string, body: Record<string, unknown>) => new SuperTabStore(db).execute(owner, tabId, { operationId: randomUUID(), command: body as never })+ /** A full read on the real clock (the store stamps with it): its cursor and the machine's contribution generation. */+ async function fullRead(tabId: string) {+ clock = Date.now()+ const data = (await host(undefined, true)).body.data+ return { cursor: data.cursor as string, generation: data.tabs.find((t: { tabId: string }) => t.tabId === tabId).pool.machine.generation as string }+ }+ const poolOf = async (tabId: string, cursor: string) => {+ clock = Date.now()+ return (await host(cursor)).body.data.tabs.find((t: { tabId: string }) => t.tabId === tabId)?.pool as { machine: { paused: boolean } } | undefined+ }++ it('wakes the host for a pause even when a reading lands after it, before the host polls', async () => {+ const s = await hostScene()+ const { cursor, generation } = await fullRead(s.tabId)+ await command(s.tabId, { type: 'machine.pause', machineId: machine, paused: true })+ await reading(s.tabId, generation)+ expect((await poolOf(s.tabId, cursor))?.machine.paused).toBe(true)+ })++ it('wakes the host for a pause made right after a reading', async () => {+ const s = await hostScene()+ const { cursor, generation } = await fullRead(s.tabId)+ await reading(s.tabId, generation)+ await command(s.tabId, { type: 'machine.pause', machineId: machine, paused: true })+ expect((await poolOf(s.tabId, cursor))?.machine.paused).toBe(true)+ })++ it('wakes an agent\'s host when the agent leaves its last group, so the host sees it inactive', async () => {+ const s = await hostScene()+ const { cursor } = await fullRead(s.tabId)+ await command(s.tabId, { type: 'conversation.agent', conversationId: s.more.lonerGroup, agentId: s.more.loner, present: false, lead: false })+ clock = Date.now()+ const tab = (await host(cursor)).body.data.tabs.find((t: { tabId: string }) => t.tabId === s.tabId)+ expect(tab?.roster.find((r: { agent?: { id: string } }) => r.agent?.id === s.more.loner)).toMatchObject({ active: false })+ })++ it('still wakes the departed agent\'s host when the group is renamed after the removal, before the host polls', async () => {+ const s = await hostScene()+ const { cursor } = await fullRead(s.tabId)+ await command(s.tabId, { type: 'conversation.agent', conversationId: s.more.lonerGroup, agentId: s.more.loner, present: false, lead: false })+ await command(s.tabId, { type: 'conversation.rename', conversationId: s.more.lonerGroup, title: 'Renamed after the removal' })+ clock = Date.now()+ const tab = (await host(cursor)).body.data.tabs.find((t: { tabId: string }) => t.tabId === s.tabId)+ expect(tab?.roster.find((r: { agent?: { id: string } }) => r.agent?.id === s.more.loner)).toMatchObject({ active: false })+ })++ it('still wakes it after two more writes to the group', async () => {+ const s = await hostScene()+ const { cursor } = await fullRead(s.tabId)+ await command(s.tabId, { type: 'conversation.agent', conversationId: s.more.lonerGroup, agentId: s.more.loner, present: false, lead: false })+ await command(s.tabId, { type: 'conversation.rename', conversationId: s.more.lonerGroup, title: 'Once' })+ await command(s.tabId, { type: 'message.send', conversationId: s.more.lonerGroup, text: 'Twice', replyTo: null, recipientIds: [] })+ clock = Date.now()+ const tab = (await host(cursor)).body.data.tabs.find((t: { tabId: string }) => t.tabId === s.tabId)+ expect(tab?.roster.find((r: { agent?: { id: string } }) => r.agent?.id === s.more.loner)).toMatchObject({ active: false })+ })++ /** The host form by POST, with the hashes the host holds for each Swarm's rows. */+ const hostPost = async (body: { cursor?: string; full?: boolean; held?: Record<string, string> }) => {+ clock = Date.now()+ const response = await app.inject({ method: 'POST', url: `/api/super-tabs/hosts/${machine}/changes`, headers: { authorization: `Bearer ${owner.sub}` }, payload: body })+ return { status: response.statusCode, bytes: response.body.length, data: response.json().data as { cursor: string; tabs: Array<Record<string, unknown>> } }+ }+ const entry = (data: { tabs: Array<Record<string, unknown>> }, tabId: string) => data.tabs.find(t => t.tabId === tabId)!++ it('answers "unchanged" for an active Swarm whose rows the host already holds, and sends the rows once one changes', async () => {+ const s = await hostScene()+ const first = await hostPost({ full: true })+ const etag = entry(first.data, s.tabId).etag as string+ expect(etag).toMatch(/^[A-Za-z0-9_-]{16,64}$/)+ // Active: a change that concerns this host (its worker's group), but leaves its rows as they were.+ await command(s.tabId, { type: 'conversation.rename', conversationId: s.web, title: 'Same rows' })+ const same = await hostPost({ cursor: first.data.cursor, held: { [s.tabId]: etag } })+ expect(entry(same.data, s.tabId)).toEqual({ tabId: s.tabId, etag, unchanged: true, lastChangedAt: expect.any(Number) })+ expect(same.bytes).toBeLessThan(first.bytes / 4)+ // One row changes: the machine is paused, so its pool row does.+ await command(s.tabId, { type: 'machine.pause', machineId: machine, paused: true })+ const changed = entry((await hostPost({ cursor: first.data.cursor, held: { [s.tabId]: etag } })).data, s.tabId)+ expect(changed.unchanged).toBeUndefined()+ expect(changed.etag).not.toBe(etag)+ expect(changed).toMatchObject({ pool: { machine: { paused: true } }, roster: expect.any(Array), assignments: expect.any(Array) })+ })++ it('keeps the same hash through the host\'s own reading, and honours held hashes on the full read too', async () => {+ const s = await hostScene()+ const first = await hostPost({ full: true })+ const { etag, pool } = entry(first.data, s.tabId) as { etag: string; pool: { machine: { generation: string } } }+ await reading(s.tabId, pool.machine.generation)+ expect(entry((await hostPost({ full: true, held: { [s.tabId]: etag } })).data, s.tabId)).toMatchObject({ unchanged: true, etag })+ })++ it('rebuilds the rows on a full read even when every version still matches: emails and grants live outside the parts', async () => {+ const s = await hostScene()+ const first = await hostPost({ full: true })+ const etag = entry(first.data, s.tabId).etag as string+ await db.user.update({ where: { id: peer.sub }, data: { email: '[email protected]' } })+ try {+ const full = entry((await hostPost({ full: true, held: { [s.tabId]: etag } })).data, s.tabId) as { unchanged?: true; roster: Array<{ observers?: Array<{ email: string }> }> }+ expect(full.unchanged).toBeUndefined()+ expect(full.roster.flatMap(r => r.observers ?? []).map(o => o.email)).toContain('[email protected]')+ } finally { await db.user.update({ where: { id: peer.sub }, data: { email: peer.email } }) }+ })++ it('refuses a malformed held map', async () => {+ await hostScene()+ clock = Date.now()+ const response = await app.inject({ method: 'POST', url: `/api/super-tabs/hosts/${machine}/changes`, headers: { authorization: `Bearer ${owner.sub}` },+ payload: { held: { 'not a tab id!': 'x' } } })+ expect(response.statusCode).toBe(400)+ })++ it('sleeps through a real reading sent through the store', async () => {+ const s = await hostScene()+ const { cursor, generation } = await fullRead(s.tabId)+ await reading(s.tabId, generation)+ clock = Date.now()+ expect((await host(cursor)).body.data).toMatchObject({ tabs: [], removedTabIds: [] })+ })++ it('names a Swarm that no longer lists the machine', async () => {+ const s = await hostScene()+ clock = NOW+ const cursor = (await host(undefined, true)).body.data.cursor+ await db.superTab.update({ where: { id: s.tabId }, data: { machineIds: [], cleanupMachineIds: [] } })+ await db.$transaction(async tx => {+ const stored = (await parts.loadActive(tx, s.tabId)).machines.find(m => m.key === machine)!+ // As the commit writes it: the contribution ended, so the settings marker moves (parts/commit.ts).+ await guardedWrite(tx, s.tabId, { op: 'update', kind: 'machine', key: machine, seen: stored.version, data: { ...stored.data!, contribution: null },+ host: { hostChangedAt: new Date(NOW + 1_000) } }, NOW + 1_000)+ })+ clock = NOW + 2_000+ expect((await host(cursor)).body.data).toMatchObject({ tabs: [], removedTabIds: [s.tabId] })+ })++ it('refuses a machine the caller does not own', async () => {+ await hostScene()+ const { status, body } = await host(undefined, true, peer)+ expect([status, body.error!.code]).toEqual([403, 'HOST_UNAVAILABLE'])+ })+})++describe('a real command through the store by parts (design 4.7)', () => {+ it('replies with the parts it wrote, and the next poll sends exactly those versions', async () => {+ const s = await scene()+ // The store stamps with the real clock; readers here keep to it too.+ clock = Date.now()+ const cursor = (await get(`/api/super-tabs/${s.tabId}/parts`, peer)).body.data.cursor+ const response = await app.inject({ method: 'POST', url: `/api/super-tabs/${s.tabId}/commands`, headers: { authorization: `Bearer ${owner.sub}` },+ payload: { operationId: randomUUID(), command: { type: 'conversation.rename', conversationId: s.web, title: 'Renamed for real' } } })+ expect(response.statusCode, response.body).toBe(200)+ const reply = response.json().data as { result: unknown; parts: Array<{ kind: string; key: string; version: number }>; lastChangedAt: number }+ expect(Object.keys(reply).sort()).toEqual(['lastChangedAt', 'parts', 'result'])+ const written = reply.parts.find(p => p.kind === 'group' && p.key === s.web)!+ expect(written.version).toBeGreaterThan(R)+ clock = Date.now()+ const seen = (await get(`/api/super-tabs/${s.tabId}/changes?cursor=${cursor}`, peer)).body.data+ expect(seen.groups.map((g: { key: string; version: number; data: { title: string } }) => [g.key, g.version, g.data.title]))+ .toEqual([[s.web, written.version, 'Renamed for real']])+ expect(seen.lastChangedAt).toBe(reply.lastChangedAt)+ })+})++describe('routes given only a store', () => {+ it('read from that store\'s database, not the app-wide client', async () => {+ const s = await scene()+ const plain = Fastify()+ plain.setErrorHandler(errorHandler)+ plain.addHook('onRequest', async request => { request.user = owner })+ await plain.register(superTabRoutes, { store: new SuperTabStore(db), github: null })+ await plain.ready()+ try {+ expect((await plain.inject({ method: 'GET', url: `/api/super-tabs/${s.tabId}/parts` })).statusCode).toBe(200)+ expect((await plain.inject({ method: 'GET', url: '/api/super-tabs/hosts/host/changes?full=1' })).statusCode).toBe(200)+ } finally { await plain.close() }+ }, 10_000)+})++describe('what a read costs the database (group 3b)', () => {+ /** What MongoDB sent this process, as the benchmark's isolated poll measures it (integration/bench/probe.ts). */+ const sent = async () => {+ const out = ((await db.$runCommandRaw({ serverStatus: 1 })) as { network: { bytesOut: unknown } }).network.bytesOut+ return typeof out === 'number' ? out : Number((out as { $numberLong?: string; $numberInt?: string }).$numberLong ?? (out as { $numberInt?: string }).$numberInt)+ }+ async function databaseBytes(call: () => Promise<unknown>): Promise<number> {+ const before = await sent(), own = await sent() - before+ const start = await sent()+ await call()+ return Math.max(0, await sent() - start - own)+ }+ /** The whole Swarm as stored: what a read that reassembles it loads. */+ const swarmBytes = async (tabId: string) => {+ const all = await db.$transaction(tx => parts.loadAll(tx, tabId))+ return [all.head, ...all.members, ...all.agents, ...all.groups, ...all.machines, ...all.starts, ...all.progress].reduce((n, p) => n + JSON.stringify(p.data).length, 0)+ }+ /** Sixty more conversations with long briefs, as a busy Swarm's history makes them (about half a megabyte). */+ const bulky = (s: ReturnType<typeof swarm>) => {+ for (let i = 0; i < 60; i++) s.run({ type: 'conversation.create', title: `Old work ${i}`, brief: `${'Long brief text. '.repeat(470)}${i}`, checks: [] })+ }++ it('a Desktop change read with nothing changed loads a few tens of KB, not the Swarm', async () => {+ const s = await scene(f => bulky(f))+ const whole = await swarmBytes(s.tabId)+ expect(whole).toBeGreaterThan(400_000)+ clock = Date.now()+ const cursor = (await get(`/api/super-tabs/${s.tabId}/parts`, peer)).body.data.cursor+ clock = Date.now()+ const bytes = await databaseBytes(() => get(`/api/super-tabs/${s.tabId}/changes?cursor=${cursor}`, peer))+ expect(bytes).toBeLessThan(25_000)+ })++ it('still sends a new start in a conversation with no work yet', async () => {+ const s = await scene(f => ({ idle: f.group('Not started yet') }))+ clock = Date.now()+ const cursor = (await get(`/api/super-tabs/${s.tabId}/parts`, owner)).body.data.cursor+ const generation = (await db.swarmMember.findFirst({ where: { tabId: s.tabId, key: owner.sub } }))!.data as { generation: string }+ await db.$transaction(tx => guardedWrite(tx, s.tabId, { op: 'insert', kind: 'start', key: 'queued-start', ordinal: Date.now(), first: R + 1, data: {+ id: 'queued-start', creationId: 'c', actorKey: `person:${owner.sub}`, contributorId: owner.sub, membershipGeneration: generation.generation,+ machineOwnerId: owner.sub, hostGrant: null, harnessId: null, dispatched: false, error: null,+ request: { conversationId: s.more.idle, machineId: 'host', engine: 'codex', name: 'Builder', cwd: '/repo', worktree: false,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } } } }, Date.now()))+ clock = Date.now()+ expect(keys((await get(`/api/super-tabs/${s.tabId}/changes?cursor=${cursor}`, owner)).body.data.starts)).toEqual(['queued-start'])+ })++ it('still shows the owner an invitation that lands in a conversation with no work', async () => {+ const s = await scene(f => ({ idle: f.group('Landing') }))+ clock = Date.now()+ const cursor = (await get(`/api/super-tabs/${s.tabId}/parts`, owner)).body.data.cursor+ await new SuperTabStore(db).execute(owner, s.tabId, { operationId: randomUUID(),+ command: { type: 'invite.create', email: '[email protected]', role: 'viewer', conversationId: s.more.idle } })+ clock = Date.now()+ const head = (await get(`/api/super-tabs/${s.tabId}/changes?cursor=${cursor}`, owner)).body.data.head+ expect(head.data.invitations.map((i: { email: string }) => i.email)).toEqual(['[email protected]'])+ })++ it('after one post it loads about what changed', async () => {+ const s = await scene(f => bulky(f))+ clock = Date.now()+ const cursor = (await get(`/api/super-tabs/${s.tabId}/parts`, peer)).body.data.cursor+ await new SuperTabStore(db).execute(owner, s.tabId, { operationId: randomUUID(),+ command: { type: 'message.send', conversationId: s.web, text: 'One post', replyTo: null, recipientIds: [] } })+ clock = Date.now()+ let groups = 0+ const bytes = await databaseBytes(async () => { groups = (await get(`/api/super-tabs/${s.tabId}/changes?cursor=${cursor}`, peer)).body.data.groups.length })+ expect(groups).toBe(1)+ expect(bytes).toBeLessThan(30_000)+ })++ it('the host form answers "unchanged" after a post in its agent\'s group without loading conversation bodies', async () => {+ const machineId = `m-${randomUUID().slice(0, 8)}`+ await db.machine.create({ data: { machineId, userId: owner.sub, apiKey: 'fixture-only', managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })+ const s = await scene(f => { f.contribute(machineId, 'swarm'); bulky(f) }, machineId)+ const post = (body: Record<string, unknown>) => app.inject({ method: 'POST', url: `/api/super-tabs/hosts/${machineId}/changes`,+ headers: { authorization: `Bearer ${owner.sub}` }, payload: body })+ clock = Date.now()+ const first = (await post({ full: true })).json().data as { cursor: string; tabs: Array<{ tabId: string; etag: string }> }+ const etag = first.tabs.find(t => t.tabId === s.tabId)!.etag+ await new SuperTabStore(db).execute(owner, s.tabId, { operationId: randomUUID(),+ command: { type: 'message.send', conversationId: s.web, text: 'Busy', replyTo: null, recipientIds: [] } })+ clock = Date.now()+ let answer: Record<string, unknown> | undefined+ const bytes = await databaseBytes(async () => {+ answer = ((await post({ cursor: first.cursor, held: { [s.tabId]: etag } })).json().data.tabs as Array<Record<string, unknown>>).find(t => t.tabId === s.tabId)+ })+ expect(answer).toMatchObject({ unchanged: true, etag: expect.stringMatching(/^[A-Za-z0-9_-]{44}$/) })+ // From version columns alone: building the rows from light conversations costs about 39 KB here, this about 10 KB.+ expect(bytes).toBeLessThan(20_000)+ })+})diff --git a/backend/integration/superTabSharing.test.ts b/backend/integration/superTabSharing.test.tsindex 2859921b8..2b5b71516 100644--- a/backend/integration/superTabSharing.test.ts+++ b/backend/integration/superTabSharing.test.ts@@ -12,8 +12,27 @@ import { errorHandler } from '../src/middlewares/errorHandler.js'import { SuperTabStore } from '../src/superTabs/store.js'import type { AuthUser } from '../src/lib/ssoAuth.js'import type { GeneralAccess } from '../src/superTabs/sharing.js'+import * as parts from '../src/superTabs/parts/index.js'+import type { SuperTabState } from '../src/superTabs/model.js'let replica: MongoMemoryReplSet, db: PrismaClient, store: SuperTabStore, app: FastifyInstance++/** A Swarm's whole state as its parts hold it (test helper: the store keeps no single document). */+async function storedState(tab: string): Promise<SuperTabState> {+ return parts.reassemble(await db.$transaction(tx => parts.loadAll(tx, tab)))+}+/** Replaces a Swarm's parts with `state`, as an older release would have left them. Versions keep rising. */+async function saveState(tab: string, state: SuperTabState) {+ await db.$transaction(async tx => {+ const current = await parts.loadAll(tx, tab)+ const version = Math.max(current.head.version, ...[...current.members, ...current.agents, ...current.groups, ...current.machines,+ ...current.starts, ...current.progress].map(p => p.version)) + 1+ for (const model of [tx.swarmHead, tx.swarmMember, tx.swarmAgent, tx.swarmGroup, tx.swarmMachine, tx.swarmStart, tx.swarmProgress] as unknown as+ Array<{ deleteMany(args: unknown): Promise<unknown> }>) await model.deleteMany({ where: { tabId: tab } })+ await parts.insertParts(tx, { ...parts.split(state, { tabId: tab, version, now: Date.now(), visibilityEpoch: current.visibilityEpoch }),+ sequenceBase: current.sequenceBase })+ })+}const owner: AuthUser = { sub: '200000000000000000000001', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }const peer: AuthUser = { sub: '200000000000000000000002', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }const outsider: AuthUser = { sub: '200000000000000000000003', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }@@ -116,7 +135,7 @@ describe('Swarm sharing on the authenticated control API', () => {expect((await request(tab, 'join', { operationId: randomUUID(), token }, peer)).json().data).toMatchObject({ role: 'viewer', alreadyMember: true })const join = { operationId: randomUUID(), token }expect((await request(tab, 'join', join, outsider)).json().data.role).toBe('collaborator')- const stored = await db.superTab.findUniqueOrThrow({ where: { id: tab } })+ const stored = [await db.superTab.findUniqueOrThrow({ where: { id: tab } }), await storedState(tab)]expect(JSON.stringify(stored)).not.toContain(token)expect(JSON.stringify(await db.superTabOperation.findMany({ where: { tabId: tab } }))).not.toContain(token)expect((await store.read(owner, tab)).state.sharing).toBeUndefined()@@ -155,10 +174,10 @@ describe('Swarm sharing on the authenticated control API', () => {it('keeps legacy members without a generation stable without restoring them after removal', async () => {const tab = await create()await save(tab, { mode: 'domain', domain: 'example.com', role: 'collaborator' })- const row = await db.superTab.findUniqueOrThrow({ where: { id: tab } })- const state = JSON.parse(JSON.stringify(row.state))- state.people.push({ id: peer.sub, email: peer.email, role: 'viewer' })- await db.superTab.update({ where: { id: tab }, data: { state, memberIds: [owner.sub, peer.sub] } })+ const state = await storedState(tab)+ state.people.push({ id: peer.sub, email: peer.email, role: 'viewer' } as SuperTabState['people'][number])+ await saveState(tab, state)+ await db.superTab.update({ where: { id: tab }, data: { memberIds: [owner.sub, peer.sub] } })const join = { operationId: randomUUID() }const result = await store.join(peer, tab, join)expect(result).toMatchObject({ role: 'viewer', alreadyMember: true })diff --git a/backend/integration/superTabTeam.test.ts b/backend/integration/superTabTeam.test.tsindex 35e06fc1d..19b57c953 100644--- a/backend/integration/superTabTeam.test.ts+++ b/backend/integration/superTabTeam.test.ts@@ -10,12 +10,32 @@ import type { AuthUser } from '../src/lib/ssoAuth.js'import { SuperTabStore } from '../src/superTabs/store.js'import type { Command } from '../src/superTabs/commands.js'import type { ContributedMachine } from '../src/superTabs/machines.js'+import * as parts from '../src/superTabs/parts/index.js'+import type { SuperTabState } from '../src/superTabs/model.js'+import { assignmentRows, poolRows, rosterRows } from './hostRows.test-support.js'// A team session (docs/plans/2026-10-24-swarm-team-account.md, Task 1) is the owner's account signed in on a second// macOS user of the owner's Mac. In a Swarm it may host its own machine and speak as the agents running there, and// nothing else: never as the person, never for the person's other machines. A fresh loopback replica set, created here.let replica: MongoMemoryReplSetlet db: PrismaClient++/** A Swarm's whole state as its parts hold it (test helper: the store keeps no single document). */+async function storedState(tab: string): Promise<SuperTabState> {+ return parts.reassemble(await db.$transaction(tx => parts.loadAll(tx, tab)))+}+/** Replaces a Swarm's parts with `state`, as an older release would have left them. Versions keep rising. */+async function saveState(tab: string, state: SuperTabState) {+ await db.$transaction(async tx => {+ const current = await parts.loadAll(tx, tab)+ const version = Math.max(current.head.version, ...[...current.members, ...current.agents, ...current.groups, ...current.machines,+ ...current.starts, ...current.progress].map(p => p.version)) + 1+ for (const model of [tx.swarmHead, tx.swarmMember, tx.swarmAgent, tx.swarmGroup, tx.swarmMachine, tx.swarmStart, tx.swarmProgress] as unknown as+ Array<{ deleteMany(args: unknown): Promise<unknown> }>) await model.deleteMany({ where: { tabId: tab } })+ await parts.insertParts(tx, { ...parts.split(state, { tabId: tab, version, now: Date.now(), visibilityEpoch: current.visibilityEpoch }),+ sequenceBase: current.sequenceBase })+ })+}let store: SuperTabStoreconst TEAM_COMPUTER = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'const owner: AuthUser = { sub: '200000000000000000000001', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }@@ -52,7 +72,7 @@ async function fixture() {const personal = String((await run(tab, { type: 'agent.add', conversationId: personalGroup, machineId: 'personal-mac',harnessId: randomUUID(), name: 'Personal', configuration: config, lead: false }, person)).result.agentId)await run(tab, { type: 'machine.contribute', machineId: 'team-mac', name: 'MacBook Pro · Team', cwd: '/team', engines: ['codex'], maxAgents: 4 }, person)- const generation = (await store.hostPools(team, 'team-mac')).find(p => p.tabId === tab)!.machine.generation+ const generation = (await poolRows(store, team, 'team-mac')).find(p => p.tabId === tab)!.machine.generationawait store.observeMachine(team, tab, 'team-mac', reading(generation))const startId = String((await run(tab, { type: 'agent.start', request: { conversationId: teamGroup, machineId: 'team-mac', engine: 'codex',name: 'Builder', cwd: '/team', worktree: false, requirements } })).result.startId)@@ -89,11 +109,11 @@ afterAll(async () => {describe('a team session hosting its own machine', () => {it('reads its pools, its agents\' rows, terminal requests and assignments, and reports its machine', async () => {const f = await fixture()- expect((await store.hostPools(team, 'team-mac')).map(p => p.tabId)).toContain(f.tab)- expect((await store.hostTabs(team, 'team-mac')).filter(r => r.tabId === f.tab).map(r => r.agent.id)).toEqual([f.builder])+ expect((await poolRows(store, team, 'team-mac')).map(p => p.tabId)).toContain(f.tab)+ expect((await rosterRows(store, team, 'team-mac')).filter(r => r.tabId === f.tab).map(r => r.agent.id)).toEqual([f.builder])expect(await store.hostTerminal(team, 'team-mac')).toEqual([])const assignmentId = String((await run(f.tab, { type: 'work.assign', conversationId: f.teamGroup, agentId: f.builder })).result.assignmentId)- expect(await store.hostAssignments(team, 'team-mac')).toContainEqual(expect.objectContaining({ tabId: f.tab, assignmentId }))+ expect(await assignmentRows(store, team, 'team-mac')).toContainEqual(expect.objectContaining({ tabId: f.tab, assignmentId }))await store.observeMachine(team, f.tab, 'team-mac', reading(f.generation))// The reading is stamped with how the machine is signed in, from the session and never from the request.const pool = () => store.read(owner, f.tab).then(r => r.state.machines!.find(m => m.machineId === 'team-mac')!)@@ -110,14 +130,14 @@ describe('a team session hosting its own machine', () => {it('never hosts the person\'s other machines', async () => {const f = await fixture()await run(f.tab, { type: 'machine.contribute', machineId: 'personal-mac', name: 'MacBook Pro', cwd: '/work', scope: 'swarm', engines: ['codex'], maxAgents: 2 }, person)- const generation = (await store.hostPools(person, 'personal-mac')).find(p => p.tabId === f.tab)!.machine.generation+ const generation = (await poolRows(store, person, 'personal-mac')).find(p => p.tabId === f.tab)!.machine.generationawait store.observeMachine(person, f.tab, 'personal-mac', reading(generation))const queued = String((await run(f.tab, { type: 'agent.start', request: { conversationId: f.personalGroup, machineId: 'personal-mac', engine: 'codex',name: 'Another', cwd: `/work/${f.own}`, worktree: false, requirements } }, person)).result.startId)- await expect(store.hostPools(team, 'personal-mac')).rejects.toMatchObject(LIMITED)- await expect(store.hostTabs(team, 'personal-mac')).rejects.toMatchObject(LIMITED)+ await expect(poolRows(store, team, 'personal-mac')).rejects.toMatchObject(LIMITED)+ await expect(rosterRows(store, team, 'personal-mac')).rejects.toMatchObject(LIMITED)await expect(store.hostTerminal(team, 'personal-mac')).rejects.toMatchObject(LIMITED)- await expect(store.hostAssignments(team, 'personal-mac')).rejects.toMatchObject(LIMITED)+ await expect(assignmentRows(store, team, 'personal-mac')).rejects.toMatchObject(LIMITED)await expect(store.observeMachine(team, f.tab, 'personal-mac', reading(generation))).rejects.toMatchObject(LIMITED)await expect(store.start(team, f.tab, queued, undefined, 'personal-mac')).rejects.toMatchObject(LIMITED)await expect(hostRun(f.tab, { type: 'agent.startDispatch', startId: queued }, 'personal-mac')).rejects.toMatchObject(LIMITED)@@ -129,7 +149,7 @@ describe('a team session hosting its own machine', () => {const f = await fixture()await db.machine.update({ where: { machineId: 'team-mac' }, data: { deletedAt: new Date() } })try {- await expect(store.hostTabs(team, 'team-mac')).rejects.toMatchObject(LIMITED)+ await expect(rosterRows(store, team, 'team-mac')).rejects.toMatchObject(LIMITED)await expect(store.read(team, f.tab, f.builder)).rejects.toMatchObject(LIMITED)} finally { await db.machine.update({ where: { machineId: 'team-mac' }, data: { deletedAt: null } }) }})@@ -140,7 +160,7 @@ describe('a team session speaking in a Swarm', () => {const f = await fixture()expect((await store.read(team, f.tab, f.builder)).state.agents.map(a => a.id)).toContain(f.builder)const sent = await run(f.tab, { type: 'message.send', conversationId: f.teamGroup, text: 'Started.', replyTo: null, recipientIds: [] }, team, f.builder)- expect(sent.revision).toBeGreaterThan(0)+ expect(sent.parts.length).toBeGreaterThan(0)expect((await store.messages(team, f.tab, f.teamGroup, {}, f.builder)).messages.at(-1)).toMatchObject({ text: 'Started.',author: expect.objectContaining({ kind: 'agent', id: f.builder }) })expect(await store.deliveries(team, f.tab, f.builder)).toEqual([])@@ -280,7 +300,7 @@ describe('a teammate\'s work and the machines that take it', () => {/** The person's personal MacBook, contributed for every project, reporting from the person's own sign-in. */async function personalMac(f: Awaited<ReturnType<typeof fixture>>) {await run(f.tab, { type: 'machine.contribute', machineId: 'personal-mac', name: 'MacBook Pro', cwd: '/work', scope: 'swarm', engines: ['codex'], maxAgents: 2 }, person)- const generation = (await store.hostPools(person, 'personal-mac')).find(p => p.tabId === f.tab)!.machine.generation+ const generation = (await poolRows(store, person, 'personal-mac')).find(p => p.tabId === f.tab)!.machine.generationawait store.observeMachine(person, f.tab, 'personal-mac', reading(generation))return generation}@@ -385,7 +405,7 @@ describe('a teammate\'s work and the machines that take it', () => {const failed = (await store.read(owner, f.tab)).state.starts!.find(s => s.id === queued)!expect(failed).toMatchObject({ dispatched: false, error: expect.stringContaining('is not private (gitconfig') })expect((await store.messages(owner, f.tab, f.teamGroup, {})).messages.at(-1)!.text).toMatch(/^Could not start Builder: The Harness Team account on MacBook Pro · Team is not private/)- expect((await store.hostPools(team, 'team-mac')).find(p => p.tabId === f.tab)!.starts.map(s => s.id)).not.toContain(queued)+ expect((await poolRows(store, team, 'team-mac')).find(p => p.tabId === f.tab)!.starts.map(s => s.id)).not.toContain(queued)// A stale check may pass again by itself: that start keeps waiting for it.const passedAgain = { ...PASSED, checkedAt: Date.now() + 1 }await store.observeMachine(team, f.tab, 'team-mac', reading(f.generation, passedAgain))@@ -414,17 +434,16 @@ describe('a teammate\'s work and the machines that take it', () => {const old = String((await run(f.tab, { type: 'agent.add', conversationId: f.teamGroup, machineId: 'personal-mac', harnessId: 'before-release',name: 'Old', configuration: config, lead: false }, person)).result.agentId)// Its task was assigned by a release from before the rule: written into the stored Swarm as that release left it.- const row = await db.superTab.findUniqueOrThrow({ where: { id: f.tab } })- const state = structuredClone(row.state) as unknown as { conversations: Array<{ id: string; agentIds: string[]; assignment: unknown }> }+ const state = await storedState(f.tab)const work = state.conversations.find(c => c.id === f.teamGroup)!work.assignment = { id: 'assigned-before', agentId: old, status: 'working', configuration: config, result: null,execution: { machineId: 'personal-mac', harnessId: 'before-release', machineOwnerId: person.sub } }- await db.superTab.update({ where: { id: f.tab }, data: { state: state as never, revision: row.revision + 1 } })+ await saveState(f.tab, state)await db.superTabRun.create({ data: { id: old, tabId: f.tab, assignmentId: 'assigned-before', machineId: 'personal-mac', harnessId: 'before-release' } })await store.observeMachine(person, f.tab, 'personal-mac', reading(generation))- expect((await store.hostTabs(person, 'personal-mac')).find(r => r.tabId === f.tab && r.agent.id === old)).toMatchObject({ stopRequested: false })- expect(await store.hostAssignments(person, 'personal-mac')).toContainEqual({ tabId: f.tab, assignmentId: 'assigned-before', harnessId: 'before-release' })+ expect((await rosterRows(store, person, 'personal-mac')).find(r => r.tabId === f.tab && r.agent.id === old)).toMatchObject({ stopRequested: false })+ expect(await assignmentRows(store, person, 'personal-mac')).toContainEqual({ tabId: f.tab, assignmentId: 'assigned-before', harnessId: 'before-release' })await run(f.tab, { type: 'work.status', conversationId: f.teamGroup, assignmentId: 'assigned-before', status: 'blocked', result: 'Needs a token.' }, person, old)await run(f.tab, { type: 'message.send', conversationId: f.teamGroup, text: 'Here it is.', replyTo: null, recipientIds: [old] })expect(await db.superTabDelivery.count({ where: { tabId: f.tab, agentId: old } })).toBeGreaterThan(0)@@ -446,9 +465,9 @@ describe('one machine: a Mac and its Harness Team account', () => {await idle.execute(person, tab, { operationId: randomUUID(), command: { type: 'invite.accept', inviteId: invitation.result.inviteId as string } })await idle.execute(person, tab, { operationId: randomUUID(), command: { type: 'machine.contribute', machineId: 'personal-mac', name: 'MacBook Pro', cwd: '/work',scope: 'swarm', engines: ['codex'], maxAgents: 3 } })- expect((await idle.hostTabs(person, 'personal-mac')).some(r => r.tabId === tab && 'joinTeam' in r)).toBe(false)+ expect((await rosterRows(idle, person, 'personal-mac', { teamAccountsIdle: true })).some(r => r.tabId === tab && 'joinTeam' in r)).toBe(false)// The same Swarm on a server with the app asks the Mac's host to add it.- expect((await store.hostTabs(person, 'personal-mac')).some(r => r.tabId === tab && 'joinTeam' in r)).toBe(true)+ expect((await rosterRows(store, person, 'personal-mac')).some(r => r.tabId === tab && 'joinTeam' in r)).toBe(true)} finally {await db.machine.update({ where: { machineId: 'team-mac' }, data: { hostMachineId: null } })}@@ -461,10 +480,10 @@ describe('one machine: a Mac and its Harness Team account', () => {const invitation = await run(tab, { type: 'invite.create', email: person.email, role: 'collaborator', conversationId: 'lead' })await run(tab, { type: 'invite.accept', inviteId: invitation.result.inviteId as string }, person)await run(tab, { type: 'machine.contribute', machineId: 'personal-mac', name: 'MacBook Pro', cwd: '/work', scope: 'swarm', engines: ['codex'], maxAgents: 3 }, person)- const joins = async () => (await store.hostTabs(person, 'personal-mac')).filter(r => r.tabId === tab && 'joinTeam' in r)+ const joins = async () => (await rosterRows(store, person, 'personal-mac')).filter(r => r.tabId === tab && 'joinTeam' in r)expect(await joins()).toEqual([{ tabId: tab, joinTeam: { machineId: 'team-mac', name: 'MacBook Pro', maxAgents: 3 } }])// The team account's own daemon is never asked, and cannot add itself.- expect((await store.hostTabs(team, 'team-mac')).some(r => 'joinTeam' in r)).toBe(false)+ expect((await rosterRows(store, team, 'team-mac')).some(r => 'joinTeam' in r)).toBe(false)await expect(store.execute(team, tab, { operationId: randomUUID(), command: { type: 'machine.contribute', machineId: 'team-mac', name: 'x', cwd: '/team',scope: 'swarm', engines: ['codex'], maxAgents: 1, ifMissing: true } })).rejects.toMatchObject(LIMITED)// The Mac's host adds it, as the person: the backend gives it the Mac's name and slots, and the Mac it lives on.@@ -473,15 +492,15 @@ describe('one machine: a Mac and its Harness Team account', () => {expect(await joins()).toEqual([])const listed = (await store.read(owner, tab)).state.machines!.find(m => m.machineId === 'team-mac')!expect(listed).toMatchObject({ hostMachineId: 'personal-mac', name: 'MacBook Pro', maxAgents: 3, cwd: '/team' })- const generation = (await store.hostPools(team, 'team-mac')).find(p => p.tabId === tab)!.machine.generation+ const generation = (await poolRows(store, team, 'team-mac')).find(p => p.tabId === tab)!.machine.generationawait store.observeMachine(team, tab, 'team-mac', reading(generation))const group = String((await run(tab, { type: 'conversation.create', projectId: 'lead', title: 'Work', brief: 'Do it',checks: [{ description: 'Verified', independent: false }] })).result.conversationId)const started = await run(tab, { type: 'agent.start', request: { conversationId: group, machineId: 'personal-mac', engine: 'codex', name: 'Builder',cwd: '/work/lead', worktree: false, requirements } })- const queued = (await store.hostPools(team, 'team-mac')).find(p => p.tabId === tab)!.starts+ const queued = (await poolRows(store, team, 'team-mac')).find(p => p.tabId === tab)!.startsexpect(queued).toEqual([expect.objectContaining({ id: started.result.startId, request: expect.objectContaining({ machineId: 'team-mac', cwd: '/team/lead' }) })])- expect((await store.hostPools(person, 'personal-mac')).find(p => p.tabId === tab)!.starts).toEqual([])+ expect((await poolRows(store, person, 'personal-mac')).find(p => p.tabId === tab)!.starts).toEqual([])} finally {await db.machine.update({ where: { machineId: 'team-mac' }, data: { hostMachineId: null } })}diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.tsindex 3f5649212..11c655eaa 100644--- a/backend/integration/superTabs.test.ts+++ b/backend/integration/superTabs.test.ts@@ -18,6 +18,12 @@ import { DEFAULT_ROUTING_POLICY } from '../src/superTabs/routingPolicy.js'import { stableId, type SuperTabState } from '../src/superTabs/model.js'import { ensureTerminalExpiry, TERMINAL_EXPIRY_MS } from '../src/superTabs/terminal.js'import { ensureMentionExpiry, MENTION_EXPIRY_MS } from '../src/superTabs/mentions.js'+import * as parts from '../src/superTabs/parts/index.js'+import { guardedWrite, PartConflict } from '../src/superTabs/parts/write.js'+import { ensurePartExpiry, sweepSwarms } from '../src/superTabs/sweeps.js'+import { assignmentRows, poolRows, rosterRows } from './hostRows.test-support.js'+import { recipientShare } from '../src/routes/harnessShares.js'+import { beforeFirstWrite } from './interleave.test-support.js'// A fresh loopback replica set, created here. This suite never reads DATABASE_URL or an existing database.let replica: MongoMemoryReplSet@@ -59,6 +65,22 @@ async function teamMachine(machineId: string) {const session: AuthUser = { ...host, harnessSessionId: `team-${machineId}`, harnessSessionKind: 'team', harnessComputerId: computerId }return { session, privacy: { mode: 'dedicated' as const } }}+/** A Swarm's whole state as its parts hold it, dormant groups included (test helper: the store keeps no single document). */+async function storedState(tab: string): Promise<SuperTabState> {+ return parts.reassemble(await db.$transaction(tx => parts.loadAll(tx, tab)))+}+/** Replaces a Swarm's parts with `state`, as an older release or the migration would have left them. Versions keep rising. */+async function saveState(tab: string, state: SuperTabState) {+ await db.$transaction(async tx => {+ const current = await parts.loadAll(tx, tab)+ const version = Math.max(current.head.version, ...[...current.members, ...current.agents, ...current.groups, ...current.machines,+ ...current.starts, ...current.progress].map(p => p.version)) + 1+ for (const model of [tx.swarmHead, tx.swarmMember, tx.swarmAgent, tx.swarmGroup, tx.swarmMachine, tx.swarmStart, tx.swarmProgress] as unknown as+ Array<{ deleteMany(args: unknown): Promise<unknown> }>) await model.deleteMany({ where: { tabId: tab } })+ await parts.insertParts(tx, { ...parts.split(state, { tabId: tab, version, now: Date.now(), visibilityEpoch: current.visibilityEpoch }),+ sequenceBase: current.sequenceBase })+ })+}async function invite(tab: string, role: 'collaborator' | 'viewer' = 'collaborator') {const invitation = await run(tab, { type: 'invite.create', email: peer.email, role, conversationId: 'lead' })await run(tab, { type: 'invite.accept', inviteId: invitation.result.inviteId as string }, peer)@@ -102,7 +124,7 @@ describe('durable group pull request links', () => {return (group as unknown as { pullRequestUrls?: string[] }).pullRequestUrls}- it('keeps one link beyond the latest 100 messages and reconstructs an older group on read', async () => {+ it('keeps one link beyond the latest 100 messages', async () => {const { tab } = await fixture()await run(tab, message(`Review ${pr(41)}`))await run(tab, message(`Same PR again: ${pr(41)}`))@@ -115,26 +137,6 @@ describe('durable group pull request links', () => {expect((await store.messages(owner, tab, 'lead', {})).messages).toHaveLength(100)expect((await store.messages(owner, tab, 'lead', {})).messages.some(row => row.text.includes(pr(41)))).toBe(false)expect(await links(tab)).toEqual([pr(41)])-- const stored = await db.superTab.findUniqueOrThrow({ where: { id: tab } })- const state = stored.state as { conversations: Array<{ id: string; pullRequestUrls?: string[] }> }- delete state.conversations.find(group => group.id === 'lead')!.pullRequestUrls- await db.superTab.update({ where: { id: tab }, data: { state } })- let historyScans = 0- const observed = db.$extends({ query: { superTabMessage: { async findMany({ args, query }) {- historyScans++- return query(args)- } } } })- const observedStore = new SuperTabStore(observed as unknown as PrismaClient)- expect((await observedStore.read(owner, tab)).state.conversations[0]!.pullRequestUrls).toEqual([pr(41)])- expect(historyScans).toBe(1)- const backfilled = (await db.superTab.findUniqueOrThrow({ where: { id: tab } })).state as typeof state- expect(backfilled.conversations.find(group => group.id === 'lead')!.pullRequestUrls).toEqual([pr(41)])- expect((await observedStore.read(owner, tab)).state.conversations[0]!.pullRequestUrls).toEqual([pr(41)])- expect(historyScans).toBe(1)- await run(tab, message('One more note after the older link was found.'))- const saved = (await db.superTab.findUniqueOrThrow({ where: { id: tab } })).state as typeof state- expect(saved.conversations.find(group => group.id === 'lead')!.pullRequestUrls).toEqual([pr(41)])})it('lists links from check evidence and a work result even when no message has those links', async () => {@@ -148,24 +150,6 @@ describe('durable group pull request links', () => {expect((await store.messages(owner, tab, 'lead', {})).messages.some(row => row.text.includes(pr(42)))).toBe(false)await run(tab, { type: 'work.status', conversationId: 'lead', assignmentId, status: 'working', result: `Built ${pr(43)}` }, host, lead)expect(await links(tab)).toEqual([pr(42), pr(43)])-- await db.superTabMessage.deleteMany({ where: { tabId: tab, conversationId: 'lead', text: { contains: pr(43) } } })- const stored = await db.superTab.findUniqueOrThrow({ where: { id: tab } })- const state = stored.state as { conversations: Array<{ id: string; pullRequestUrls?: string[] }> }- delete state.conversations.find(group => group.id === 'lead')!.pullRequestUrls- await db.superTab.update({ where: { id: tab }, data: { state } })- expect((await store.messages(owner, tab, 'lead', {})).messages.some(row => /github\.com/.test(row.text))).toBe(false)- expect(await links(tab)).toEqual([pr(42), pr(43)])-- await run(tab, { type: 'work.status', conversationId: 'lead', assignmentId, status: 'done', result: `Built ${pr(43)}` }, host, lead)- await run(tab, { type: 'work.define', conversationId: 'lead', brief: 'Next work',- checks: [{ description: 'Next check', independent: false }] })- await db.superTabMessage.deleteMany({ where: { tabId: tab, conversationId: 'lead', text: { contains: pr(43) } } })- const old = await db.superTab.findUniqueOrThrow({ where: { id: tab } })- const oldState = old.state as typeof state- delete oldState.conversations.find(group => group.id === 'lead')!.pullRequestUrls- await db.superTab.update({ where: { id: tab }, data: { state: oldState } })- expect(await links(tab)).toEqual([pr(42), pr(43)])})})@@ -219,21 +203,6 @@ describe('native recording restart recovery', () => {expect((await group()).pullRequestUrls).toEqual([url])})- it('keeps older links when a native message arrives before a legacy group is backfilled', async () => {- const f = await recoveryFixture()- const oldUrl = 'https://github.com/example/project/pull/45'- const newUrl = 'https://github.com/example/project/pull/46'- await run(f.tab, { type: 'message.send', conversationId: f.group, text: oldUrl, replyTo: null, recipientIds: [] })- const stored = await db.superTab.findUniqueOrThrow({ where: { id: f.tab } })- const state = stored.state as { conversations: Array<{ id: string; pullRequestUrls?: string[] }> }- delete state.conversations.find(group => group.id === f.group)!.pullRequestUrls- await db.superTab.update({ where: { id: f.tab }, data: { state } })- await f.append({ turnId: 'saved_turn', kind: 'answer', previousEventId: f.checkpoint.eventId,- text: newUrl, truncated: false, interrupted: false })- const group = (await store.read(owner, f.tab)).state.conversations.find(c => c.id === f.group)!- expect(group.pullRequestUrls).toEqual([oldUrl, newUrl])- })-it.each(['recording_restarted', 'history_lost', 'agent_stopped'] as const)('wakes only the Lead and blocks working work for %s with a checkpoint time and no visible ids', async reason => {const f = await recoveryFixture(), event = f.interruption(reason)const result = await store.native.append(host, f.tab, f.contextId, event) as { eventId: string }@@ -421,6 +390,23 @@ describe('Change agent on a Swarm member', () => {const resent = (await store.deliveries(host, tab, lead)).find(d => d.id !== uncertain.id && !receiptIds.includes(d.id) && d.status === 'queued')!expect(resent).toMatchObject({ agentId: lead, status: 'queued' })})+ it('revokes the replaced terminal\'s recording contexts and the turns of it still waiting for the Lead', async () => {+ const { tab, lead } = await fixture()+ const group = String((await run(tab, { type: 'conversation.create', title: 'Rebound', brief: 'Work', checks: [{ description: 'Done', independent: false }] })).result.conversationId)+ const harnessId = randomUUID()+ const worker = String((await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId, name: 'Worker',+ configuration: config, lead: false })).result.agentId)+ const { contextId } = await store.native.open(owner, tab, { operationId: randomUUID(), conversationId: group, agentId: worker })+ await store.native.append(host, tab, contextId, { turnId: 'old_turn', kind: 'prompt', previousEventId: null, text: 'Typed before the switch',+ truncated: false, interrupted: false })+ const turn = (await store.deliveries(host, tab, lead)).find(d => d.nativeContextId === contextId)!+ await run(tab, { type: 'agent.rebind', agentId: worker, machineId: 'test-host', projectId: 'lead', previousHarnessId: harnessId,+ harnessId: randomUUID(), configuration: config }, host, worker)+ expect((await db.superTabNativeContext.findUniqueOrThrow({ where: { id: contextId } })).revoked).toBe(true)+ expect((await db.superTabDelivery.findUniqueOrThrow({ where: { id: turn.id } })).status).toBe('cancelled')+ await expect(store.delivery(host, tab, lead, turn.id, { type: 'claim', claimId: randomUUID() })).rejects.toMatchObject({ code: 'DELIVERY_REVOKED' })+ })+it('refuses a replacement already contributed in another tab', async () => {const first = await fixture(), second = await fixture()const previous = (await store.read(owner, first.tab)).state.agents[0]!@@ -487,7 +473,7 @@ describe('agent member identities', () => {expect(agent.displayName).toBeTruthy()expect(agent.displayName).not.toBe('Lead')expect(await run(tab, command, owner, undefined, operationId)).toEqual(added)- expect((await store.read(owner, tab)).revision).toBe(first.revision)+ expect((await store.read(owner, tab)).lastChangedAt).toBe(first.lastChangedAt)await run(tab, message('The plan is ready.'), host, agentId)await run(tab, { type: 'agent.remove', agentId })const rows = (await store.messages(owner, tab, 'lead', {})).messages@@ -628,7 +614,7 @@ describe('private swarm projects on the real control API', () => {await expect(run(tab, { type: 'agent.start', request })).rejects.toMatchObject({ code: 'PROJECT_CONTRIBUTION' })await run(tab, { type: 'machine.contribute', machineId, name: 'Shared capacity', cwd: '/swarm-root',scope: 'swarm', engines: ['codex'], maxAgents: 2 }, host)- const pool = (await store.hostPools(host, machineId))[0]!+ const pool = (await poolRows(store, host, machineId))[0]!await store.observeMachine(team.session, tab, machineId, { generation: pool.machine.generation,resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, projectDiskFreeBytes: 100e9,diskFreeBytes: 100e9, diskTotalBytes: 500e9, deviceType: 'Laptop', chip: 'Fixture CPU', os: 'macOS', gpuPercent: null },@@ -638,7 +624,7 @@ describe('private swarm projects on the real control API', () => {.rejects.toMatchObject({ code: 'OUTSIDE_CONTRIBUTION' })const secondStart = (await run(tab, { type: 'agent.start', request })).result.startId as stringawait run(tab, { type: 'agent.start', request: { ...request, conversationId: 'lead', cwd: '/swarm-root/lead' } })- const queued = (await store.hostPools(host, machineId))[0]!+ const queued = (await poolRows(store, host, machineId))[0]!expect(queued.starts).toHaveLength(2)expect(queued.projects!.find(p => p.id === projectId)).toMatchObject({repository: { machineId: 'test-host', cwd: '/lead/second', repositoryUrl: 'https://github.com/example/second' },@@ -663,17 +649,21 @@ describe('private swarm projects on the real control API', () => {const harnessId = randomUUID()const agentId = String((await run(tab, { type: 'agent.add', conversationId, machineId: 'test-host', harnessId,name: 'Private lead', configuration: config, lead: true })).result.agentId)+ // Its terminal observers are checked on a Builder's terminal: nobody but its machine's owner watches a Lead (Critical 1).+ const workerHarness = randomUUID()+ const workerId = String((await run(tab, { type: 'agent.add', conversationId, machineId: 'test-host', harnessId: workerHarness,+ name: 'Private builder', configuration: config, lead: false })).result.agentId)await run(tab, { ...message('Private result'), conversationId } as Command)expect((await store.read(peer, tab)).state.projects!.map(p => p.id)).not.toContain(projectId)await expect(store.messages(peer, tab, conversationId, {})).rejects.toMatchObject({ code: 'NOT_FOUND' })await expect(store.native.open(peer, tab, { operationId: randomUUID(), conversationId, agentId })).rejects.toMatchObject({ code: 'NOT_FOUND' })- expect(await store.mayObserve(peer, tab, 'test-host', harnessId, host.sub)).toBe(false)- expect((await store.hostTabs(host, 'test-host')).find(t => t.agent?.id === agentId)!.observers.map(p => p.userId)).not.toContain(peer.sub)+ expect(await store.mayObserve(peer, tab, 'test-host', workerHarness, host.sub)).toBe(false)+ expect((await rosterRows(store, host, 'test-host')).find(t => t.agent?.id === workerId)!.observers.map(p => p.userId)).not.toContain(peer.sub)await expect(store.messages(host, tab, 'lead', {}, agentId)).rejects.toMatchObject({ code: 'NOT_FOUND' })await run(tab, { type: 'project.sharing', projectId, visibility: 'private', memberIds: [peer.sub] })expect((await store.messages(peer, tab, conversationId, {})).messages.map(m => m.text)).toContain('Private result')- expect(await store.mayObserve(peer, tab, 'test-host', harnessId, host.sub)).toBe(true)+ expect(await store.mayObserve(peer, tab, 'test-host', workerHarness, host.sub)).toBe(true)const context = await store.native.open(peer, tab, { operationId: randomUUID(), conversationId, agentId })const command = { ...message('Shared review'), conversationId } as Commandconst operationId = randomUUID()@@ -681,7 +671,7 @@ describe('private swarm projects on the real control API', () => {await run(tab, { type: 'project.sharing', projectId, visibility: 'private', memberIds: [] })await expect(run(tab, command, peer, undefined, operationId)).rejects.toMatchObject({ code: 'NOT_FOUND' })await expect(store.native.read(host, tab, context.contextId)).rejects.toMatchObject({ code: 'NATIVE_CONTEXT_REVOKED' })- expect(await store.mayObserve(peer, tab, 'test-host', harnessId, host.sub)).toBe(false)+ expect(await store.mayObserve(peer, tab, 'test-host', workerHarness, host.sub)).toBe(false)// Removing a roster row, here with its project, cannot erase the terminal's private history.await run(tab, { type: 'project.delete', projectId })@@ -714,8 +704,9 @@ describe('private swarm projects on the real control API', () => {await execute({ ...message('New evidence'), conversationId: group } as Command)now += 300_000expect((await updates()).map(d => d.id)).toEqual([...ids])- const revision = (await timed.read(owner, tab)).revision- await execute({ type: 'project.report', projectId: 'lead', throughRevision: revision,+ // The Lead reports through what it read of each workgroup: here the new evidence, the group's latest message.+ const read = (await timed.read(owner, tab)).state.conversations.find(c => c.id === group)!+ await execute({ type: 'project.report', projectId: 'lead', through: { [group]: read.lastMessageSequence },text: 'The implementation is ready. Verification is next.' }, lead)expect(await updates()).toEqual([])now += 3_600_000@@ -732,17 +723,10 @@ describe('private swarm projects on the real control API', () => {})describe('since when a worker is down', () => {- async function downFixture({ legacy = false } = {}) {+ async function downFixture() {let now = 1_000_000const timed = new SuperTabStore(db, () => now)- const tab = (await timed.create(owner, randomUUID(), 'Down since', legacy ? undefined : 'public')).id- if (legacy) {- // New Swarms always store a project; emulate one created before projects existed.- const stored = await db.superTab.findUniqueOrThrow({ where: { id: tab } })- const state = stored.state as { projects?: unknown }- delete state.projects- await db.superTab.update({ where: { id: tab }, data: { state } })- }+ const tab = (await timed.create(owner, randomUUID(), 'Down since', 'public')).idconst execute = (command: Command, user = owner, asAgentId?: string) =>timed.execute(user, tab, { operationId: randomUUID(), command }, asAgentId)const invitation = await execute({ type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })@@ -756,7 +740,7 @@ describe('since when a worker is down', () => {const worker = String((await execute({ type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: workerHarness,name: 'Worker', configuration: config, lead: false })).result.agentId)const assignmentId = String((await execute({ type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId)- const generation = (await timed.hostPools(host, 'test-host')).find(p => p.tabId === tab)!.machine.generation+ const generation = (await poolRows(timed, host, 'test-host')).find(p => p.tabId === tab)!.machine.generationconst observe = (running: string[], stopped: string[] = []) => timed.observeMachine(host, tab, 'test-host', { generation,resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9, diskTotalBytes: 500e9,projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture', os: 'macOS', gpuPercent: null },@@ -809,70 +793,6 @@ describe('since when a worker is down', () => {expect(await f.downSince(f.worker)).toBe(iso(lastReading))expect(await f.downSince(f.lead)).toBeUndefined()})-- it('names a worker down two hours or more in the Lead\'s scheduled wake-up, once per time it went down', async () => {- const f = await downFixture()- const wakeUps = async () => (await db.superTabMessage.findMany({ where: { tabId: f.tab, conversationId: 'lead' }, orderBy: { sequence: 'asc' } }))- .filter(m => (m.source as Record<string, unknown>)?.kind === 'update-request')- const poll = async () => (await f.timed.deliveries(host, f.tab, f.lead)).filter(d => d.conversationId === 'lead')- // The Lead acknowledges through the revision its wake-up names.- const acknowledge = async () => f.execute({ type: 'project.report', projectId: 'lead',- throughRevision: ((await wakeUps()).at(-1)!.source as { throughRevision: number }).throughRevision, text: null }, host, f.lead)- await f.observe([f.leadHarness, f.workerHarness])- f.clock.now += 300_000- expect(await poll()).toHaveLength(1)- await acknowledge()- expect(await poll()).toEqual([])-- const down = f.clock.now- await f.observe([f.leadHarness, f.workerHarness])- await f.observe([f.leadHarness])- f.clock.now = down + 2 * 3_600_000 - 60_000- await f.execute({ ...message('A new report'), conversationId: f.group } as Command)- f.clock.now += 59_999- expect(await poll()).toEqual([])- f.clock.now++- expect(await poll()).toHaveLength(1)- const named = (await wakeUps()).at(-1)!- expect(named.text).toContain(`Worker (down since ${iso(down)}; task "Ship the parser")`)- expect(named.text).not.toContain('Lead (down')- expect(named.text).not.toContain('Consolidate')- expect(await poll()).toHaveLength(1)- await acknowledge()- // The report that was not yet due still gets its own request.- f.clock.now += 240_000- expect(await poll()).toHaveLength(1)- expect((await wakeUps()).at(-1)!.text).toContain('Consolidate new reports')- await acknowledge()- f.clock.now += 3 * 3_600_000- expect(await poll()).toEqual([])-- await f.observe([f.leadHarness, f.workerHarness])- const again = f.clock.now- await f.observe([f.leadHarness])- f.clock.now += 2 * 3_600_000- expect(await poll()).toHaveLength(1)- expect((await wakeUps()).at(-1)!.text).toContain(`Worker (down since ${iso(again)}`)- expect(await wakeUps()).toHaveLength(4)- })-- it('wakes the Lead of an older Swarm without stored projects', async () => {- const f = await downFixture({ legacy: true })- expect((await f.timed.read(owner, f.tab)).state.projects).toBeUndefined()- const poll = async () => (await f.timed.deliveries(host, f.tab, f.lead)).filter(d => d.conversationId === 'lead')- const down = f.clock.now- await f.observe([f.leadHarness, f.workerHarness])- await f.observe([f.leadHarness])- f.clock.now = down + 2 * 3_600_000 - 1- expect(await poll()).toEqual([])- f.clock.now++- const polls = [...await poll(), ...await poll()]- expect(new Set(polls.map(d => d.id)).size).toBe(1)- const wakeUps = (await db.superTabMessage.findMany({ where: { tabId: f.tab, conversationId: 'lead' } }))- .filter(m => (m.source as Record<string, unknown>)?.kind === 'update-request')- expect(wakeUps).toHaveLength(1)- expect(wakeUps[0]!.text).toContain(`Worker (down since ${iso(down)}; task "Ship the parser")`)- })})describe('Super Tabs on a real Mongo replica set', () => {@@ -886,7 +806,7 @@ describe('Super Tabs on a real Mongo replica set', () => {await expect(run(tab, contribute)).rejects.toMatchObject({ code: 'HOST_REQUIRED' })await run(tab, contribute, host)expect(await db.machineShare.findUnique({ where: { machineId: 'pool-host' } })).toBeNull()- const pools = await store.hostPools(host, 'pool-host')+ const pools = await poolRows(store, host, 'pool-host')expect(pools).toHaveLength(1)const generation = pools[0]!.machine.generationconst observation = { generation, resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9, diskTotalBytes: 500e9,@@ -922,7 +842,7 @@ describe('Super Tabs on a real Mongo replica set', () => {expect((await store.start(owner, tab, startId)).poolSettled).toBe(true)expect((await store.read(owner, tab)).state.agents[0]).toMatchObject({ contributorId: host.sub, machineOwnerId: host.sub, harnessId: 'pool-builder' })await run(tab, { type: 'member.remove', userId: host.sub })- expect(await store.hostPools(host, 'pool-host')).toEqual([])+ expect(await poolRows(store, host, 'pool-host')).toEqual([])// The machine stays listed while its host cleans up, but its owner left: a reading is refused as theirs no longer.await expect(store.observeMachine(host, tab, 'pool-host', observation)).rejects.toMatchObject({ code: 'FORBIDDEN' })await expect(store.start(host, tab, startId, undefined, 'pool-host')).rejects.toMatchObject({ code: 'FORBIDDEN' })@@ -1187,11 +1107,25 @@ describe('Super Tabs on a real Mongo replica set', () => {// The Lead pages through all of its own notices, a full page then the rest.const page = await store.messages(host, tab, 'lead', {}, lead)expect(page.messages).toHaveLength(100)- const rest = await store.messages(host, tab, 'lead', { before: page.next! }, lead)+ const rest = await store.messages(host, tab, 'lead', { before: page.next!.sequence, beforeId: page.next!.id }, lead)expect([...rest.messages, ...page.messages].map(m => m.text)).toEqual(['Before the notices.', ...Array.from({ length: 120 }, (_, i) => `Notice ${i}.`), 'After the notices.'])expect(rest.next).toBeNull()})+ it('pages through older rows that share one sequence without skipping any at a page edge', async () => {+ const { tab } = await fixture()+ // Before the store by parts, every row one command wrote shared that command's tab revision.+ const ids = Array.from({ length: 150 }, (_, i) => `shared-${String(i).padStart(3, '0')}`)+ await db.superTabMessage.createMany({ data: ids.map(id => ({ id, tabId: tab, conversationId: 'lead', sequence: 0,+ author: { kind: 'person', id: owner.sub, name: owner.email }, text: id, replyTo: null, recipientIds: [] })) })+ const page = await store.messages(owner, tab, 'lead', { before: 1 })+ expect(page.messages).toHaveLength(100)+ expect(page.next).toEqual({ sequence: 0, id: page.messages[0]!.id })+ const rest = await store.messages(owner, tab, 'lead', { before: page.next!.sequence, beforeId: page.next!.id })+ expect([...rest.messages, ...page.messages].map(m => m.id)).toEqual(ids)+ expect(rest.next).toBeNull()+ })+it('accepts an agent-only notice only from an agent to itself alone', async () => {const { tab, lead } = await fixture()const worker = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: randomUUID(), name: 'Worker', configuration: config, lead: false })).result.agentId as string@@ -1411,7 +1345,7 @@ describe('Super Tabs on a real Mongo replica set', () => {const invitation = await run(tab, { type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })await run(tab, { type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)await run(tab, { type: 'machine.contribute', machineId: 'test-host', name: 'Host', cwd: '/swarm-root', scope: 'swarm', engines: ['codex'], maxAgents: 2 }, host)- const pool = (await store.hostPools(host, 'test-host')).find(p => p.tabId === tab)!+ const pool = (await poolRows(store, host, 'test-host')).find(p => p.tabId === tab)!const team = await teamMachine('test-host')await store.observeMachine(team.session, tab, 'test-host', { generation: pool.machine.generation,resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, projectDiskFreeBytes: 100e9,@@ -1420,7 +1354,7 @@ describe('Super Tabs on a real Mongo replica set', () => {const request = { conversationId: 'lead', machineId: 'test-host', engine: 'codex', name: 'Builder', cwd: '/work/app', worktree: true,requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }await run(tab, { type: 'agent.start', request })- expect((await store.hostPools(host, 'test-host')).find(p => p.tabId === tab)!.projects).toEqual([expect.objectContaining({ id: 'lead', repository })])+ expect((await poolRows(store, host, 'test-host')).find(p => p.tabId === tab)!.projects).toEqual([expect.objectContaining({ id: 'lead', repository })])})it('lets a project\'s Lead change its skills only by quoting a message the project owner wrote there, and tells the host', async () => {const tab = (await store.create(owner, randomUUID(), 'Skills')).id@@ -1430,7 +1364,7 @@ describe('Super Tabs on a real Mongo replica set', () => {name: 'Lead', configuration: config, lead: true }, peer)).result.agentId as stringconst legacyLead = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: randomUUID(),name: 'Old', configuration: config, lead: true })).result.agentId as string- const modes = async () => Object.fromEntries((await store.hostTabs(host, 'test-host')).filter(r => r.tabId === tab).map(r => [r.agent?.id, r.skillMode]))+ const modes = async () => Object.fromEntries((await rosterRows(store, host, 'test-host')).filter(r => r.tabId === tab).map(r => [r.agent?.id, r.skillMode]))expect(await modes()).toEqual({ [lead]: 'default', [legacyLead]: 'default' })const say = async (text: string, user = peer) => (await run(tab, { ...message(text), conversationId: chat } as Command, user)).result.messageId as stringconst skills = (messageId: string): Command => ({ type: 'project.skills', projectId, mode: 'orchestration', askedIn: { conversationId: chat, messageId } })@@ -1444,10 +1378,9 @@ describe('Super Tabs on a real Mongo replica set', () => {await run(tab, { type: 'project.skills', projectId, mode: 'default' }, peer)expect(await modes()).toEqual({ [lead]: 'default', [legacyLead]: 'default' })// A project stored before skill modes keeps Harness orchestration.- const stored = await db.superTab.findUniqueOrThrow({ where: { id: tab } })- const state = stored.state as { projects: Array<{ id: string; skillMode?: string }> }- delete state.projects.find(p => p.id === 'lead')!.skillMode- await db.superTab.update({ where: { id: tab }, data: { state } })+ const state = await storedState(tab)+ delete state.projects!.find(p => p.id === 'lead')!.skillMode+ await saveState(tab, state)expect(await modes()).toEqual({ [lead]: 'default', [legacyLead]: 'orchestration' })})it('keeps custom role texts out of the tab and the host rows, and serves a text only to the project owner, its Lead and its agents\' hosts', async () => {@@ -1459,13 +1392,13 @@ describe('Super Tabs on a real Mongo replica set', () => {const roles = [{ id: 'lead', name: 'Product Manager', kind: 'lead' as const, text: 'LEAD-TEXT' },{ id: 'dev', name: 'Engineer', kind: 'builder' as const, text: 'DEV-TEXT' }, { id: 'review', name: 'Reviewer', kind: 'reviewer' as const, text: 'REVIEW-TEXT' }]await run(tab, { type: 'project.roles.create', projectId: 'lead', roles })- const rows = async () => (await store.hostTabs(host, 'test-host')).filter(r => r.tabId === tab)+ const rows = async () => (await rosterRows(store, host, 'test-host')).filter(r => r.tabId === tab)const rowOf = async (id: string) => (await rows()).find(r => r.agent.id === id)!expect(await rowOf(worker)).not.toHaveProperty('role')await run(tab, { type: 'project.skills', projectId: 'lead', mode: 'custom' })expect(await rowOf(lead)).toMatchObject({ skillMode: 'default', role: { id: 'lead', name: 'Product Manager', kind: 'lead', version: version('LEAD-TEXT'), projectId: 'lead' } })expect(await rowOf(worker)).toMatchObject({ skillMode: 'default', role: { id: 'dev', name: 'Engineer', kind: 'builder', version: version('DEV-TEXT'), projectId: 'lead' } })- const stored = JSON.stringify((await db.superTab.findUniqueOrThrow({ where: { id: tab } })).state)+ const stored = JSON.stringify(await storedState(tab))for (const text of [JSON.stringify(await rows()), stored, JSON.stringify((await store.read(owner, tab)).state)]) expect(text).not.toMatch(/LEAD-TEXT|DEV-TEXT/)const text = (user: AuthUser, roleId: string, asAgentId?: string) => app.inject({ method: 'GET',@@ -1593,13 +1526,13 @@ describe('Super Tabs on a real Mongo replica set', () => {const assignmentId = (await run(one.tab, { type: 'work.assign', conversationId: 'lead', agentId: worker })).result.assignmentId as stringawait expect(run(two.tab, { type: 'work.assign', conversationId: 'lead', agentId: worker })).rejects.toMatchObject({ code: 'AGENT_BUSY' })await run(one.tab, { type: 'agent.remove', agentId: worker })- expect(await store.hostAssignments(host, 'test-host')).toContainEqual({ tabId: one.tab, assignmentId, harnessId: session })- await expect(store.hostAssignments(owner, 'test-host')).rejects.toMatchObject({ code: 'HOST_UNAVAILABLE' })+ expect(await assignmentRows(store, host, 'test-host')).toContainEqual({ tabId: one.tab, assignmentId, harnessId: session })+ await expect(assignmentRows(store, owner, 'test-host')).rejects.toMatchObject({ code: 'HOST_UNAVAILABLE' })await expect(store.stopped(owner, one.tab, assignmentId, 'forged')).rejects.toMatchObject({ code: 'FORBIDDEN' })await store.stopped(host, one.tab, assignmentId, 'native-stop-receipt')expect((await store.read(owner, one.tab)).state.conversations[0]!.assignment?.status).toBe('stopped')await store.stopped(host, one.tab, assignmentId, 'native-stop-receipt')- expect(await store.hostAssignments(host, 'test-host')).not.toContainEqual({ tabId: one.tab, assignmentId, harnessId: session })+ expect(await assignmentRows(store, host, 'test-host')).not.toContainEqual({ tabId: one.tab, assignmentId, harnessId: session })expect(await db.superTabDelivery.count({ where: { tabId: one.tab, assignmentId, status: 'queued' } })).toBe(0)await run(two.tab, { type: 'work.assign', conversationId: 'lead', agentId: worker })await run(one.tab, define)@@ -1674,9 +1607,9 @@ describe('Super Tabs on a real Mongo replica set', () => {it('rejects unshared hosts and spoofed agent identities through the HTTP API', async () => {const { tab, lead } = await fixture()const headers = { authorization: `Bearer ${owner.sub}` }- expect((await app.inject({ url: `/api/super-tabs/${tab}` })).statusCode).toBe(401)- expect((await app.inject({ url: `/api/super-tabs/${tab}`, headers })).statusCode).toBe(200)- expect((await app.inject({ url: `/api/super-tabs/${tab}?asAgentId=${lead}`, headers })).statusCode).toBe(403)+ expect((await app.inject({ url: `/api/super-tabs/${tab}/parts` })).statusCode).toBe(401)+ expect((await app.inject({ url: `/api/super-tabs/${tab}/parts`, headers })).statusCode).toBe(200)+ expect((await app.inject({ url: `/api/super-tabs/${tab}/parts?asAgentId=${lead}`, headers })).statusCode).toBe(403)const malformed = await app.inject({ method: 'POST', url: `/api/super-tabs/${tab}/commands`, headers,payload: { operationId: randomUUID(), command: { ...message('No spoofing.'), contributorId: owner.sub } } })expect(malformed.statusCode).toBe(400)@@ -1735,18 +1668,19 @@ describe('Super Tabs on a real Mongo replica set', () => {})it('derives session-only observer access from accepted membership and removes it with that membership', async () => {- const { tab, lead } = await fixture()- const state = (await store.read(owner, tab)).state- const native = state.agents.find(a => a.id === lead)!.harnessId+ const { tab } = await fixture()+ // A Builder's terminal: nobody but its machine's owner watches a Lead (Critical 1).+ const native = randomUUID()+ await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: native, name: 'Builder', configuration: config, lead: false })expect(await store.mayObserve(peer, tab, 'test-host', native, host.sub)).toBe(false)await invite(tab, 'viewer')expect(await store.mayObserve(peer, tab, 'test-host', native, host.sub)).toBe(true)expect(await store.mayObserve(peer, tab, 'test-host', 'another-session', host.sub)).toBe(false)- const grants = (await store.hostTabs(host, 'test-host')).find(t => t.tabId === tab)+ const grants = (await rosterRows(store, host, 'test-host')).find(t => t.tabId === tab && t.agent?.harnessId === native)expect(grants?.observers).toContainEqual({ email: peer.email, userId: peer.sub })await run(tab, { type: 'member.remove', userId: peer.sub })expect(await store.mayObserve(peer, tab, 'test-host', native, host.sub)).toBe(false)- expect((await store.hostTabs(host, 'test-host')).find(t => t.tabId === tab)?.observers).not.toContainEqual({ email: peer.email, userId: peer.sub })+ expect((await rosterRows(store, host, 'test-host')).find(t => t.tabId === tab && t.agent?.harnessId === native)?.observers).not.toContainEqual({ email: peer.email, userId: peer.sub })})it('tells the execution host which of its agents need a decision or are stuck', async () => {@@ -1755,7 +1689,7 @@ describe('Super Tabs on a real Mongo replica set', () => {const worker = (await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: randomUUID(),name: 'Builder', configuration: config, lead: false })).result.agentId as stringconst assignmentId = (await run(tab, { type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId as string- const row = async () => (await store.hostTabs(host, 'test-host')).find(t => t.tabId === tab && t.agent.id === worker)!+ const row = async () => (await rosterRows(store, host, 'test-host')).find(t => t.tabId === tab && t.agent.id === worker)!expect(await row()).toMatchObject({ tabName: 'Pilot', attention: null })await run(tab, { type: 'work.status', conversationId: group, assignmentId, status: 'blocked', result: 'No access to staging.' } as Command, host, worker)expect((await row()).attention).toEqual({ assignmentId, status: 'blocked', result: 'No access to staging.' })@@ -1770,7 +1704,7 @@ describe('Super Tabs on a real Mongo replica set', () => {const group = (await run(tab, { type: 'conversation.create', title: 'Done work', brief: '', checks: [] })).result.conversationId as stringconst worker = (await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: randomUUID(),name: 'Builder', configuration: config, lead: false })).result.agentId as string- const active = async () => Object.fromEntries((await store.hostTabs(host, 'test-host'))+ const active = async () => Object.fromEntries((await rosterRows(store, host, 'test-host')).filter(t => t.tabId === tab).map(t => [t.agent.id, t.active]))expect(await active()).toEqual({ [lead]: true, [worker]: true })await run(tab, { type: 'conversation.archive', conversationId: group, archived: true })@@ -1933,7 +1867,7 @@ describe('Super Tabs on a real Mongo replica set', () => {const invitation = await run(tab, { type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })await run(tab, { type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)await run(tab, { type: 'machine.contribute', machineId: 'test-host', name: 'Host', cwd: '/fixture/repo', engines: ['codex'], maxAgents: 4 }, host)- const machine = (await store.hostPools(host, 'test-host')).find(pool => pool.tabId === tab)!.machine+ const machine = (await poolRows(store, host, 'test-host')).find(pool => pool.tabId === tab)!.machineconst team = await teamMachine('test-host')await store.observeMachine(team.session, tab, 'test-host', { generation: machine.generation,resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9, diskTotalBytes: 500e9,@@ -2182,7 +2116,7 @@ it('releases a finished worker through its execution host, cancels deliveries anconst group = (await run(tab, { type: 'conversation.create', title: 'Task', brief: 'Deliver it', checks: [{ description: 'Verified', independent: false }] })).result.conversationId as stringconst native = randomUUID()const worker = (await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: native, name: 'Worker', configuration: config, lead: false })).result.agentId as string- const pool = (await store.hostPools(host, 'test-host')).find(p => p.tabId === tab)!.machine+ const pool = (await poolRows(store, host, 'test-host')).find(p => p.tabId === tab)!.machineconst oldObservation = { generation: pool.generation,resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9, diskTotalBytes: 500e9, projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture', os: 'macOS', gpuPercent: null },quotas: [], tools: {}, runningHarnessIds: [native], stoppedHarnessIds: [] }@@ -2195,7 +2129,7 @@ it('releases a finished worker through its execution host, cancels deliveries anconst { machineSlots } = await import('../src/superTabs/machines.js')expect(machineSlots(before, before.machines![0]!)).toBe(2)await run(tab, { type: 'agent.release', agentId: worker, decision: 'stop' }, host, lead)- expect((await store.hostTabs(host, 'test-host')).find(r => r.agent?.id === worker)).toMatchObject({ stopRequested: true })+ expect((await rosterRows(store, host, 'test-host')).find(r => r.agent?.id === worker)).toMatchObject({ stopRequested: true })await expect(run(tab, { type: 'agent.remove', agentId: worker }, owner, worker)).rejects.toMatchObject({ code: 'FORBIDDEN' })const operation = randomUUID()const releaseId = (await store.read(owner, tab)).state.agents.find(a => a.id === worker)!.releaseId!@@ -2210,11 +2144,11 @@ it('releases a finished worker through its execution host, cancels deliveries anconst delayed = (await store.read(owner, tab)).stateexpect(delayed.machines![0]!.availableSlots).toBe(3)expect(await db.superTabDelivery.count({ where: { tabId: tab, agentId: worker, status: { in: ['queued', 'claimed', 'uncertain'] } } })).toBe(0)- expect((await store.hostTabs(host, 'test-host')).some(r => r.agent?.id === worker)).toBe(false)+ expect((await rosterRows(store, host, 'test-host')).some(r => r.agent?.id === worker)).toBe(false)// Re-contribution reserves a new runtime; ordinary removal must not reuse its old stop proof.await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: native, name: 'Renewed worker', configuration: config, lead: false })await run(tab, { type: 'agent.remove', agentId: worker })- const hostPool = (await store.hostPools(host, 'test-host')).find(p => p.tabId === tab)!+ const hostPool = (await poolRows(store, host, 'test-host')).find(p => p.tabId === tab)!expect(hostPool.harnessIds).toContain(native)const reservation = hostPool.reservations.find(r => r.harnessId === native)!await store.observeMachine(host, tab, 'test-host', { ...oldObservation, runningHarnessIds: [], stoppedHarnessIds: [native],@@ -2273,14 +2207,14 @@ it('lets a person force-withdraw a stuck stop, clears its fence and retires theawait run(tab, { type: 'project.delete', projectId: 'lead' })})-it('refuses to stop a finished worker that is the Lead of another Swarm', async () => {- // The other Swarm has no Lead yet: the shared session becomes its first.+it('refuses to stop a finished worker that also works in another Swarm', async () => {+ // A session registered in two Swarms can no longer be a Lead in either (final review, Critical 1), so it works there as a Builder.const first = await fixture(), second = { tab: (await store.create(owner, randomUUID(), 'Other')).id }, native = randomUUID()const group = (await run(first.tab, { type: 'conversation.create', title: 'Finished worker', brief: 'Work', checks: [{ description: 'Done', independent: false }] })).result.conversationId as stringconst worker = (await run(first.tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: native, name: 'Worker', configuration: config, lead: false })).result.agentId as stringconst assignmentId = (await run(first.tab, { type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId as stringawait store.stopped(host, first.tab, assignmentId, 'completed')- await run(second.tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: native, name: 'Other Lead', configuration: config, lead: true })+ await run(second.tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: native, name: 'Other Builder', configuration: config, lead: false })await expect(run(first.tab, { type: 'agent.release', agentId: worker, decision: 'stop' }, host, first.lead)).rejects.toMatchObject({ code: 'SESSION_SHARED' })expect((await store.read(owner, first.tab)).state.agents.find(a => a.id === worker)!.workDecision).toBe('awaiting')})@@ -2327,7 +2261,7 @@ describe('the owner\'s Lead machine joins its Swarm', () => {await db.machine.create({ data: { machineId, userId: owner.sub, apiKey: `fixture-${machineId}`, managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })const tab = (await store.create(owner, randomUUID(), 'Own machine')).idconst lead = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId, harnessId: randomUUID(), name: 'Lead', configuration: config, lead: true })).result.agentId as string- expect((await store.hostTabs(owner, machineId)).map(r => r.joinSwarm)).toEqual([true])+ expect((await rosterRows(store, owner, machineId)).map(r => r.joinSwarm)).toEqual([true])const request = { conversationId: 'lead', machineId, engine: 'codex', name: 'Builder', cwd: '/repo', worktree: true,requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }const start = async () => (await run(tab, { type: 'agent.start', request })).result.startId as string@@ -2354,7 +2288,7 @@ describe('the owner\'s Lead machine joins its Swarm', () => {owner, lead)).rejects.toMatchObject({ code: 'OWNER_MESSAGE_REQUIRED' })const added = joined.machines!.find(m => m.machineId === machineId)!expect(added).toMatchObject({ contributorId: owner.sub, maxAgents: 3, scope: 'swarm', cwd: '/swarm' })- expect((await store.hostTabs(owner, machineId)).map(r => r.joinSwarm)).toEqual([false, false])+ expect((await rosterRows(store, owner, machineId)).map(r => r.joinSwarm)).toEqual([false, false])await run(tab, { ...join, maxAgents: 8, cwd: '/elsewhere' })expect((await store.read(owner, tab)).state.machines!.find(m => m.machineId === machineId)).toEqual(added)})@@ -2363,7 +2297,7 @@ describe('the owner\'s Lead machine joins its Swarm', () => {const { tab } = await fixture()const invitation = await run(tab, { type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })await run(tab, { type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)- expect((await store.hostTabs(host, 'test-host')).filter(r => r.tabId === tab).map(r => r.joinSwarm)).toEqual([false])+ expect((await rosterRows(store, host, 'test-host')).filter(r => r.tabId === tab).map(r => r.joinSwarm)).toEqual([false])const join = { type: 'machine.contribute' as const, machineId: 'test-host', name: 'Host', cwd: '/swarm', scope: 'swarm' as const, engines: ['codex'], maxAgents: 2, ifMissing: true as const }await expect(run(tab, join)).rejects.toMatchObject({ code: 'OWNER_REQUIRED' })await expect(run(tab, join, host)).rejects.toMatchObject({ code: 'OWNER_REQUIRED' })@@ -2377,7 +2311,7 @@ describe('the owner\'s Lead machine joins its Swarm', () => {const tab = (await store.create(owner, randomUUID(), 'Shared Lead')).idawait invite(tab)await run(tab, { type: 'agent.add', conversationId: 'lead', machineId, harnessId: randomUUID(), name: 'Peer Lead', configuration: config, lead: true }, peer)- expect((await store.hostTabs(owner, machineId)).map(r => [r.agent.contributorId, r.joinSwarm])).toEqual([[peer.sub, false]])+ expect((await rosterRows(store, owner, machineId)).map(r => [r.agent.contributorId, r.joinSwarm])).toEqual([[peer.sub, false]])})})@@ -2387,7 +2321,7 @@ describe('Lead safety on the host roster', () => {const harness = randomUUID()const worker = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: harness, name: 'Worker',configuration: config, lead: false })).result.agentId as string- const rows = async () => (await store.hostTabs(host, 'test-host')).filter(r => r.tabId === tab)+ const rows = async () => (await rosterRows(store, host, 'test-host')).filter(r => r.tabId === tab)expect((await rows()).map(r => [r.agent.id, r.lead])).toEqual([[lead, true], [worker, false]])await expect(run(tab, { type: 'agent.remove', agentId: lead })).rejects.toMatchObject({ code: 'LEAD_PROTECTED',message: expect.stringContaining('is the Product Manager of project Pilot. Delete the project first.') })@@ -2401,10 +2335,10 @@ describe('Lead safety on the host roster', () => {expect((await store.read(owner, tab)).state).not.toHaveProperty('closingSessions')// Neither the Swarm owner nor an outsider can confirm it, and a refusal writes nothing; the machine's owner can,// though it is not in the Swarm.- const revision = (await store.read(owner, tab)).revision+ const revision = (await store.read(owner, tab)).lastChangedAtawait expect(confirm(worker, harness, owner)).rejects.toMatchObject({ code: 'NOT_FOUND' })await expect(confirm(worker, harness, peer)).rejects.toMatchObject({ code: 'NOT_FOUND' })- expect((await store.read(owner, tab)).revision).toBe(revision)+ expect((await store.read(owner, tab)).lastChangedAt).toBe(revision)const receipt = await confirm(worker, harness)expect(await confirm(worker, harness)).toEqual(receipt)await expect(run(tab, { type: 'agent.sessionClosed', agentId: worker, harnessId: harness }, host)).rejects.toMatchObject({ code: 'NOT_FOUND' })@@ -2479,10 +2413,9 @@ describe('the Lead reads and types in an agent terminal', () => {// Neither demotion has a command (the Lead guard keeps a project's Lead), so the state is edited the way a future one would.async function edit(tab: string, change: (state: SuperTabState) => void) {- const row = (await db.superTab.findUnique({ where: { id: tab } }))!- const state = structuredClone(row.state) as unknown as SuperTabState+ const state = await storedState(tab)change(state)- await db.superTab.update({ where: { id: tab }, data: { state: state as never, revision: row.revision + 1 } })+ await saveState(tab, state)}async function answered(tab: string, worker: string, requester: AuthUser = host, asAgentId?: string) {const requestId = (await run(tab, { type: 'agent.screen', agentId: worker }, requester, asAgentId)).result.requestId as string@@ -2534,12 +2467,11 @@ describe('Leads conversation', () => {it('appears in an old Swarm, lets people and Leads post, and delivers only to the other Leads', async () => {const { tab, lead } = await fixture()// A Swarm stored before the Leads conversation existed.- const row = await db.superTab.findUniqueOrThrow({ where: { id: tab } })- const stored = row.state as unknown as { leadsConversationId?: string; conversations: Array<{ kind?: string }> }+ const stored = await storedState(tab)const leads = stored.leadsConversationId!delete stored.leadsConversationIdstored.conversations = stored.conversations.filter(c => c.kind !== 'leads')- await db.superTab.update({ where: { id: tab }, data: { state: stored as never } })+ await saveState(tab, stored)// Clients find it without a project: by the tab's id for it and its kind.const read = (await store.read(owner, tab)).stateexpect(read.leadsConversationId).toBe(leads)@@ -2600,20 +2532,20 @@ describe('a Swarm written by a later release', () => {await run(tab, { type: 'project.create', name: 'Pilot', visibility: 'public', brief: '' })await run(tab, { type: 'project.delete', projectId: 'lead' })type Stored = Record<string, unknown> & { conversations: Array<Record<string, unknown>>; parkedConversations?: Array<Record<string, unknown>> }- const stored = (await db.superTab.findUniqueOrThrow({ where: { id: tab } })).state as unknown as Stored+ const stored = await storedState(tab) as unknown as Storedconst later = { id: 'later', kind: 'later-kind', title: 'From a later release', leadId: null, agentIds: [], archived: false, brief: '',checks: [], assignment: null, lastMessageSequence: 0, laterField: { nested: [1] } }const chat = stored.conversations.find(c => c.kind !== 'leads')!stored.laterField = { kept: true }chat.laterField = 'kept'stored.conversations.push(later)- await db.superTab.update({ where: { id: tab }, data: { state: stored as never } })+ await saveState(tab, stored as unknown as SuperTabState)expect((await store.read(owner, tab)).state.conversations.map(c => c.id)).toEqual([chat.id, stored.leadsConversationId])await run(tab, { type: 'message.send', conversationId: chat.id as string, text: 'Still writable', replyTo: null, recipientIds: [] })expect((await store.messages(owner, tab, chat.id as string, {})).messages.map(m => m.text)).toEqual(['Still writable'])await expect(store.messages(owner, tab, 'later', {})).rejects.toMatchObject({ code: 'NOT_FOUND' })- const written = (await db.superTab.findUniqueOrThrow({ where: { id: tab } })).state as unknown as Stored+ const written = await storedState(tab) as unknown as Storedexpect(written.laterField).toEqual({ kept: true })expect(written.conversations.find(c => c.id === chat.id)!.laterField).toBe('kept')// A later release, which knows the kind, puts it back from here.@@ -2622,10 +2554,11 @@ describe('a Swarm written by a later release', () => {it('never gives a new conversation the number of a conversation it set aside', async () => {const tab = (await store.create(owner, randomUUID(), 'Rollout numbers')).id- const stored = (await db.superTab.findUniqueOrThrow({ where: { id: tab } })).state as unknown as { conversations: Array<Record<string, unknown>> }- stored.conversations.push({ id: 'later', kind: 'later-kind', number: 7, title: 'From a later release', leadId: null, agentIds: [],+ const stored = await storedState(tab)+ stored.conversations.push({ id: 'later', kind: 'later-kind' as never, number: 7, title: 'From a later release', leadId: null, agentIds: [],archived: false, brief: '', checks: [], assignment: null, lastMessageSequence: 0 })- await db.superTab.update({ where: { id: tab }, data: { state: stored as never } })+ delete stored.groupCounter+ await saveState(tab, stored)const created = String((await run(tab, { type: 'conversation.create', title: 'New work', brief: '', checks: [] })).result.conversationId)expect((await store.read(owner, tab)).state.conversations.find(c => c.id === created)!.number).toBe(8)})@@ -2639,14 +2572,14 @@ describe('machine removal', () => {await run(tab, { type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)await run(tab, { type: 'machine.contribute', machineId: 'test-host', name: 'Host', cwd: '/fixture/repo', engines: ['codex'], maxAgents: 4 }, host)// Its host is here and reporting, so removing it waits for that host to acknowledge.- const machine = (await store.hostPools(host, 'test-host')).find(pool => pool.tabId === tab)!.machine+ const machine = (await poolRows(store, host, 'test-host')).find(pool => pool.tabId === tab)!.machineawait store.observeMachine(host, tab, 'test-host', { generation: machine.generation,resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9, diskTotalBytes: 500e9,projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture', os: 'macOS', gpuPercent: null },quotas: [], tools: {}, runningHarnessIds: [], stoppedHarnessIds: [] })return tab}- const cleanups = async (tab: string, from = store) => (await from.hostTabs(host, 'test-host')).filter(r => r.tabId === tab && 'cleanup' in r)+ const cleanups = async (tab: string, from = store) => (await rosterRows(from, host, 'test-host')).filter(r => r.tabId === tab && 'cleanup' in r)const cleaned = (tab: string, removalId: string) => app.inject({ method: 'POST', url: `/api/super-tabs/${tab}/commands`, headers: { authorization: `Bearer ${host.sub}` },payload: { operationId: randomUUID(), command: { type: 'machine.cleaned', machineId: 'test-host', removalId } } })@@ -2664,8 +2597,8 @@ describe('machine removal', () => {const removalId = (await run(tab, { type: 'machine.remove', machineId: 'test-host' }, host)).result.removalId as stringexpect((await store.read(owner, tab)).state.machines!.map(m => [m.removal?.state, m.paused])).toEqual([['cleaning', true]])expect(await cleanups(tab)).toEqual([{ tabId: tab, cleanup: { machineId: 'test-host', removalId } }])- expect((await store.hostTabs(host, 'test-host')).filter(r => r.tabId === tab && r.agent?.id === worker && 'closeSession' in r)).toHaveLength(1)- expect((await store.hostTabs(owner, 'test-host').catch(() => []))).toEqual([])+ expect((await rosterRows(store, host, 'test-host')).filter(r => r.tabId === tab && r.agent?.id === worker && 'closeSession' in r)).toHaveLength(1)+ expect((await rosterRows(store, owner, 'test-host').catch(() => []))).toEqual([])// The machine owner's host acknowledges even after leaving the Swarm.await run(tab, { type: 'member.remove', userId: host.sub }, host)expect((await cleaned(tab, 'not-this-one')).statusCode).toBe(404)@@ -2677,11 +2610,11 @@ describe('machine removal', () => {it('drops a machine that went silent while cleaning, and a reconnecting host gets that cleanup once before its ack', async () => {const tab = await contributed()- const generation = (await store.hostPools(host, 'test-host')).find(pool => pool.tabId === tab)!.machine.generation+ const generation = (await poolRows(store, host, 'test-host')).find(pool => pool.tabId === tab)!.machine.generationconst removalId = (await run(tab, { type: 'machine.remove', machineId: 'test-host' }, host)).result.removalId as string// Its host goes silent for longer than three beats: a read leaves the machine out, but its stored removal is still there.const later = new SuperTabStore(db, () => Date.now() + 60_000)- const stored = async () => (await db.superTab.findUniqueOrThrow({ where: { id: tab } })).state as unknown as SuperTabState+ const stored = () => storedState(tab)expect((await later.read(owner, tab)).state.machines).toEqual([])expect((await stored()).machines!.map(m => m.removal?.id)).toEqual([removalId])// It reconnects and reports before acknowledging: that reading must not bring the machine back as cleaning.@@ -2721,7 +2654,7 @@ describe('machine removal', () => {await run(tab, { type: 'member.remove', userId: host.sub }, host)const [row] = await cleanups(tab)expect(row).toEqual({ tabId: tab, cleanup: { machineId: 'test-host', removalId: expect.any(String) } })- expect((await store.hostTabs(host, 'test-host')).filter(r => r.tabId === tab && r.agent?.id === worker && 'closeSession' in r)).toHaveLength(1)+ expect((await rosterRows(store, host, 'test-host')).filter(r => r.tabId === tab && r.agent?.id === worker && 'closeSession' in r)).toHaveLength(1)expect((await store.read(owner, tab)).state.machines!.map(m => m.removal?.state)).toEqual(['cleaning'])expect((await cleaned(tab, (row as { cleanup: { removalId: string } }).cleanup.removalId)).statusCode).toBe(200)expect(await cleanups(tab)).toEqual([])@@ -2734,12 +2667,12 @@ describe('machine removal', () => {const later = new SuperTabStore(db, () => Date.now() + day)expect((await later.read(owner, tab)).state.machines).toEqual([])await later.execute(owner, tab, { operationId: randomUUID(), command: { type: 'tab.rename', name: 'A day later' } })- const stored = (await db.superTab.findUniqueOrThrow({ where: { id: tab } })).state as unknown as SuperTabState- expect([stored.machines, stored.machineCleanups]).toEqual([[], [{ machineId: 'test-host', removalId, machineOwnerId: host.sub }]])+ const stored = await storedState(tab)+ expect([stored.machines ?? [], stored.machineCleanups]).toEqual([[], [{ machineId: 'test-host', removalId, machineOwnerId: host.sub }]])expect(await cleanups(tab, later)).toEqual([{ tabId: tab, cleanup: { machineId: 'test-host', removalId } }])await later.execute(host, tab, { operationId: randomUUID(), command: { type: 'machine.cleaned', machineId: 'test-host', removalId } })expect(await cleanups(tab, later)).toEqual([])- expect(((await db.superTab.findUniqueOrThrow({ where: { id: tab } })).state as unknown as SuperTabState).machineCleanups).toBeUndefined()+ expect((await storedState(tab)).machineCleanups).toBeUndefined()})})@@ -2830,7 +2763,7 @@ describe('Lead mentions', () => {it('keeps the stored tab and older messages as the previous backend reads and writes them', async () => {const { tab, group } = await tagged()- const stored = (await db.superTab.findUniqueOrThrow({ where: { id: tab } })).state+ const stored = await storedState(tab)expect(JSON.stringify(stored)).not.toMatch(/mention/i)// A message the previous backend wrote has no mentions field; its next post omits mentions too.await db.$runCommandRaw({ insert: 'SuperTabMessage', documents: [{ _id: 'old-backend-row', tabId: tab, conversationId: group, sequence: 1,@@ -2853,7 +2786,7 @@ describe('credentials in Swarm chat', () => {const notice = 'Removed 2 credentials (JWT, GitHub token) before saving. Revoke or rotate them.'/** Everything stored for the tab, besides a terminal request (whose host must type exactly what was sent). */const stored = async (tab: string) => JSON.stringify(await Promise.all([- db.superTab.findMany({ where: { id: tab } }), db.superTabMessage.findMany({ where: { tabId: tab } }),+ db.superTab.findMany({ where: { id: tab } }), storedState(tab), db.superTabMessage.findMany({ where: { tabId: tab } }),db.superTabOperation.findMany({ where: { tabId: tab } }), db.superTabDelivery.findMany({ where: { tabId: tab } }),db.superTabAttempt.findMany({ where: { tabId: tab } }), db.superTabRouteDecision.findMany({ where: { tabId: tab } }),]))@@ -2925,3 +2858,635 @@ describe('credentials in Swarm chat', () => {}})})++describe('Swarm parts storage', () => {+ /** A Swarm born in parts at version 1, with one dormant group and one finished start. */+ async function stored() {+ const tabId = `parts-${randomUUID()}`+ const state = (await import('../src/superTabs/model.js')).createSuperTab(tabId, 'Parts', { id: owner.sub, email: owner.email }, 'prod')+ state.conversations.push({ id: 'quiet', projectId: 'lead', number: 1, title: 'Quiet', leadId: null, agentIds: ['a1'], archived: false,+ brief: '', checks: [], assignment: null, lastMessageSequence: 0, dormant: true })+ state.agents.push({ id: 'a1', machineId: 'm1', harnessId: 'h1', machineOwnerId: host.sub, contributorId: owner.sub, membershipGeneration: tabId,+ name: 'A', configuration: config })+ const request = { conversationId: 'lead', machineId: 'm1', engine: 'codex', name: 'B', cwd: '/w', worktree: false,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }+ const start = { creationId: 'c', actorKey: 'person:x', contributorId: owner.sub, membershipGeneration: tabId, machineOwnerId: host.sub,+ hostGrant: null, request, dispatched: true, error: null }+ state.starts = [{ ...start, id: 'running', harnessId: null }, { ...start, id: 'done', harnessId: 'h1' }]+ await db.$transaction(tx => parts.insertParts(tx, parts.split(state, { tabId, version: 1, now: Date.now() - 60_000 })))+ return tabId+ }++ it('writes a part only at the version it was read; a writer that read an older version conflicts and retries', async () => {+ const tabId = await stored()+ const head = (await db.$transaction(tx => parts.loadActive(tx, tabId))).head+ await db.$transaction(tx => guardedWrite(tx, tabId, { op: 'update', kind: 'head', key: 'head', seen: head.version,+ data: { ...head.data!, name: 'Renamed' } }, Date.now()))+ const stale = db.$transaction(tx => guardedWrite(tx, tabId, { op: 'update', kind: 'head', key: 'head', seen: head.version,+ data: { ...head.data!, name: 'Lost' } }, Date.now()))+ await expect(stale).rejects.toBeInstanceOf(PartConflict)+ await expect(stale).rejects.toMatchObject({ code: 'P2034' })+ const after = (await db.$transaction(tx => parts.loadActive(tx, tabId))).head+ expect(after).toMatchObject({ version: head.version + 1, data: { name: 'Renamed' } })+ })++ it('moves the version on a touch but leaves the data and the change time', async () => {+ const tabId = await stored()+ const before = (await db.$transaction(tx => parts.loadActive(tx, tabId))).agents[0]!+ await db.$transaction(tx => guardedWrite(tx, tabId, { op: 'touch', kind: 'agent', key: 'a1', seen: before.version }, Date.now()))+ const after = (await db.$transaction(tx => parts.loadActive(tx, tabId))).agents[0]!+ expect(after).toEqual({ ...before, version: before.version + 1 })+ })++ it('keeps a removed part as a tombstone with its last data, and a part added again continues from its version', async () => {+ const tabId = await stored()+ const agent = (await db.$transaction(tx => parts.loadActive(tx, tabId))).agents[0]!+ await db.$transaction(tx => guardedWrite(tx, tabId, { op: 'remove', kind: 'agent', key: 'a1', seen: agent.version, data: agent.data! }, Date.now()))+ expect((await db.$transaction(tx => parts.loadActive(tx, tabId))).agents).toEqual([])+ const since = new Date(Date.now() - 1_000)+ const changed = (await db.$transaction(tx => parts.loadChanged(tx, [tabId], since))).get(tabId)!+ expect(changed.find(p => p.kind === 'agent')).toMatchObject({ key: 'a1', deleted: true, data: { name: 'A' } })+ await db.$transaction(tx => guardedWrite(tx, tabId, { op: 'insert', kind: 'agent', key: 'a1', data: { ...agent.data!, name: 'Again' }, ordinal: 5 }, Date.now()))+ expect((await db.$transaction(tx => parts.loadActive(tx, tabId))).agents[0]).toMatchObject({ version: agent.version + 2, data: { name: 'Again' } })+ })++ it('loads dormant groups and finished starts only when a command names them', async () => {+ const tabId = await stored()+ const active = await db.$transaction(tx => parts.loadActive(tx, tabId))+ expect(active.groups.map(p => p.key)).not.toContain('quiet')+ expect(active.starts.map(p => p.key)).toEqual(['running'])+ const named = await db.$transaction(tx => parts.loadActive(tx, tabId, { groupIds: ['quiet'], startIds: ['done'] }))+ expect(named.groups.find(p => p.key === 'quiet')).toMatchObject({ dormant: true })+ expect(named.starts.map(p => p.key).sort()).toEqual(['done', 'running'])+ const firstLoad = await db.$transaction(tx => parts.loadActive(tx, tabId, { includeRecentStarts: true }))+ expect(firstLoad.starts.map(p => p.key).sort()).toEqual(['done', 'running'])+ expect((await db.$transaction(tx => parts.loadActive(tx, tabId, { agentIds: ['a1'] }))).groups.map(p => p.key)).toContain('quiet')+ expect((await db.$transaction(tx => parts.loadDormant(tx, tabId, {}))).map(p => p.key)).toEqual(['quiet'])+ expect((await db.$transaction(tx => parts.loadAll(tx, tabId))).groups.map(p => p.key)).toContain('quiet')+ })++ it('refuses to write a part over 4 MiB and writes nothing of that command', async () => {+ const tabId = await stored()+ const row = await db.superTab.findFirstOrThrow({ where: { id: tabId } }).catch(() => null)+ const loaded = await db.$transaction(tx => parts.loadActive(tx, tabId))+ const state = parts.reassemble(loaded)+ const next = structuredClone(state)+ next.name = 'Renamed'+ next.conversations.find(c => c.id === 'lead')!.brief = 'x'.repeat(4 * 1024 * 1024 + 1)+ const { commitParts } = await import('../src/superTabs/parts/commit.js')+ await expect(db.$transaction(tx => commitParts(tx, { parts: loaded, state, row: row ?? { id: tabId, revision: 0 } }, next, { stamp: Date.now() })))+ .rejects.toMatchObject({ code: 'PART_TOO_LARGE', status: 413 })+ expect((await db.$transaction(tx => parts.loadActive(tx, tabId))).head.data!.name).toBe('Parts')+ })++ it('names the newest data change of each Swarm', async () => {+ const tabId = await stored()+ const before = (await db.$transaction(tx => parts.lastChangedAt(tx, [tabId]))).get(tabId)!+ const head = (await db.$transaction(tx => parts.loadActive(tx, tabId))).head+ const stamp = Date.now()+ await db.$transaction(tx => guardedWrite(tx, tabId, { op: 'update', kind: 'head', key: 'head', seen: head.version, data: head.data! }, stamp))+ expect((await db.$transaction(tx => parts.lastChangedAt(tx, [tabId]))).get(tabId)).toBe(stamp)+ expect(stamp).toBeGreaterThan(before)+ })+})++describe('private conversations through the store', () => {+ it('keeps one out of everyone else\'s reads, messages and mentions, and changing who is in it reloads readers and drops their deliveries', async () => {+ const { tab, lead } = await fixture()+ await invite(tab)+ const group = String((await run(tab, { type: 'conversation.create', title: 'Peer and PM', brief: '', checks: [], audience: { personIds: [peer.sub] } }, peer))+ .result.conversationId)+ const sent = await run(tab, { type: 'message.send', conversationId: group, text: 'Only for the PM.', replyTo: null, recipientIds: [] }, peer)+ const ids = async (user: AuthUser, asAgentId?: string) => (await store.read(user, tab, asAgentId)).state.conversations.map(c => c.id)+ expect(await ids(peer)).toContain(group)+ expect(await ids(host, lead)).toContain(group)+ expect(await ids(owner)).not.toContain(group)+ await expect(store.messages(owner, tab, group, {})).rejects.toMatchObject({ code: 'NOT_FOUND' })+ await expect(run(tab, { type: 'message.send', conversationId: group, text: 'Hi', replyTo: null, recipientIds: [], mentions: [owner.sub] }, host, lead))+ .rejects.toMatchObject({ code: 'INVALID_MENTION' })+ expect((await store.deliveries(host, tab, lead)).map(d => d.messageId)).toContain(sent.result.messageId)++ const epoch = async () => (await db.$transaction(tx => parts.loadAll(tx, tab))).visibilityEpoch+ const before = await epoch()+ await run(tab, { type: 'conversation.audience', conversationId: group, personIds: [] }, host, lead)+ expect(await epoch()).toBe(before + 1)+ expect(await ids(peer)).not.toContain(group)+ expect((await store.deliveries(host, tab, lead)).map(d => d.messageId)).not.toContain(sent.result.messageId)+ expect((await db.superTabDelivery.findFirstOrThrow({ where: { tabId: tab, messageId: sent.result.messageId as string } })).status).toBe('cancelled')+ })+})++describe('the PM\'s terminal after a private chat (final review, Critical 1)', () => {+ const bob: AuthUser = { sub: '100000000000000000000004', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }+ /** Someone the machine's owner shared the PM's terminal with the ordinary way, outside any Swarm. */+ const carol: AuthUser = { sub: '100000000000000000000005', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }+ /** Alice (peer) and Bob read a public project whose machine neither owns; Alice has a private chat with its PM, and Bob held+ * a share of the PM's terminal from before that chat. */+ async function privateChat() {+ const { tab, lead } = await fixture()+ await invite(tab)+ // The PM runs on host's machine; host is a member too, so the one person who may still watch it.+ const asHost = await run(tab, { type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })+ await run(tab, { type: 'invite.accept', inviteId: asHost.result.inviteId as string }, host)+ if (!await db.user.findUnique({ where: { id: bob.sub } })) {+ await db.user.create({ data: { id: bob.sub, externalId: `fixture-${bob.sub}`, email: bob.email, autonomousEnv: bob.autonomousEnv } })+ }+ const invitation = await run(tab, { type: 'invite.create', email: bob.email, role: 'collaborator', conversationId: 'lead' })+ await run(tab, { type: 'invite.accept', inviteId: invitation.result.inviteId as string }, bob)+ const harnessId = (await store.read(owner, tab)).state.agents.find(a => a.id === lead)!.harnessId+ // Shares of the PM's session from before the chat: Bob's, which this Swarm made, and Carol's, made outside any Swarm.+ const share = (superTabId: string | null, recipient: AuthUser, agentId = harnessId) => db.harnessShare.create({ data: { id: randomUUID(), superTabId,+ ownerId: host.sub, machineId: 'test-host', agentId, recipientEmail: recipient.email, autonomousEnv: 'prod', name: 'Lead', ownerPublicKey: 'fixture-key',+ expiresAt: new Date(Date.now() + 86_400_000), revokedAt: null } }).then(row => row.id)+ const swarmShare = await share(tab, bob), ordinaryShare = await share(null, carol)+ const chat = String((await run(tab, { type: 'conversation.create', title: 'Chat with PM', brief: '', checks: [], audience: { personIds: [peer.sub] } }, peer))+ .result.conversationId)+ const secret = await run(tab, { type: 'message.send', conversationId: chat, text: 'Only for the PM: the launch slips a week.', replyTo: null, recipientIds: [] }, peer)+ // The PM's host types it into the PM's terminal and confirms it.+ const delivery = (await store.deliveries(host, tab, lead)).find(d => d.messageId === secret.result.messageId)!+ const claimId = randomUUID()+ await store.delivery(host, tab, lead, delivery.id, { type: 'claim', claimId })+ await store.delivery(host, tab, lead, delivery.id, { type: 'ack', claimId, receipt: 'Typed into the PM terminal', uncertain: false })+ expect((await db.superTabDelivery.findUniqueOrThrow({ where: { id: delivery.id } })).status).toBe('delivered')+ return { tab, lead, harnessId, swarmShare, ordinaryShare, share }+ }+ const observers = async (agentId: string) => (await rosterRows(store, host, 'test-host')).find(t => t.agent?.id === agentId)!.observers.map(p => p.userId)++ it('lets nobody but its machine\'s owner watch it: not a reader outside the chat, not the Swarm owner, not with an earlier share', async () => {+ const { tab, lead, harnessId } = await privateChat()+ expect(await observers(lead)).toEqual([])+ for (const user of [bob, owner, peer]) expect(await store.mayObserve(user, tab, 'test-host', harnessId, host.sub)).toBe(false)+ // A Builder's terminal stays watchable by the project's readers.+ const workerHarness = randomUUID()+ const worker = String((await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: workerHarness,+ name: 'Worker', configuration: config, lead: false })).result.agentId)+ expect(await observers(worker)).toEqual(expect.arrayContaining([bob.sub, owner.sub, peer.sub]))+ expect(await store.mayObserve(bob, tab, 'test-host', workerHarness, host.sub)).toBe(true)+ })++ /** Swarm B, where Bob reads a public project. */+ async function otherSwarm() {+ const other = (await store.create(owner, randomUUID(), 'Other Swarm', 'public')).id+ const invitation = await run(other, { type: 'invite.create', email: bob.email, role: 'collaborator', conversationId: 'lead' })+ await run(other, { type: 'invite.accept', inviteId: invitation.result.inviteId as string }, bob)+ return other+ }++ it('lets a confidential session be registered in one Swarm only, and no session in two become confidential', async () => {+ const { harnessId } = await privateChat()+ const other = await otherSwarm()+ const add = (tab: string, harness: string, lead: boolean) => run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: harness,+ name: lead ? 'Lead' : 'Builder', configuration: config, lead })+ await expect(add(other, harnessId, false)).rejects.toMatchObject({ code: 'SESSION_CONFIDENTIAL' })+ // A session in two Swarms already cannot become a Lead in either.+ const shared = randomUUID()+ const first = (await store.create(owner, randomUUID(), 'No Lead yet', 'public')).id+ const sharedId = String((await add(first, shared, false)).result.agentId)+ await add(other, shared, false)+ await expect(run(first, { type: 'conversation.agent', conversationId: 'lead', agentId: sharedId, present: true, lead: true }))+ .rejects.toMatchObject({ code: 'SESSION_CONFIDENTIAL' })+ })++ /** A gate a transaction waits at once, before its first write: `reached` says it read everything, `open` lets it write. */+ function gate() {+ let reach!: () => void, open!: () => void, first = true+ const reached = new Promise<void>(resolve => { reach = resolve }), opened = new Promise<void>(resolve => { open = resolve })+ // Only its first attempt waits; a retry after the conflict reads again and goes straight on.+ const at = async () => { if (!first) return; first = false; reach(); await opened }+ return { at, reached, open }+ }++ it.each(['promotion', 'registration'] as const)('lets only one of a concurrent promotion to Lead in one Swarm and a registration in another win: %s first', async winner => {+ const shared = randomUUID()+ const first = (await fixture()).tab, other = await otherSwarm()+ const project = (await run(first, { type: 'project.create', name: 'Promotes', visibility: 'public', brief: '' })).result as { projectId: string; conversationId: string }+ const sharedId = String((await run(first, { type: 'agent.add', conversationId: project.conversationId, machineId: 'test-host', harnessId: shared,+ name: 'Shared', configuration: config, lead: false })).result.agentId)+ // Both transactions read before either writes; then the winner commits, and only then may the other write.+ const promotionGate = gate(), registrationGate = gate()+ const promotion = new SuperTabStore(beforeFirstWrite(db, promotionGate.at)).execute(owner, first, { operationId: randomUUID(),+ command: { type: 'conversation.agent', conversationId: project.conversationId, agentId: sharedId, present: true, lead: true } })+ const registration = new SuperTabStore(beforeFirstWrite(db, registrationGate.at)).execute(owner, other, { operationId: randomUUID(),+ command: { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: shared, name: 'Shared', configuration: config, lead: false } })+ await Promise.all([promotionGate.reached, registrationGate.reached])+ const [won, lost] = winner === 'promotion' ? [promotion, registration] : [registration, promotion]+ const [wonGate, lostGate] = winner === 'promotion' ? [promotionGate, registrationGate] : [registrationGate, promotionGate]+ wonGate.open()+ await won+ lostGate.open()+ await expect(lost).rejects.toMatchObject({ code: 'SESSION_CONFIDENTIAL' })+ const registered = async (tab: string) => db.swarmAgent.count({ where: { key: sharedId, deleted: false, tabId: tab } })+ if (winner === 'promotion') {+ expect(await registered(other)).toBe(0)+ expect((await storedState(first)).agents.find(a => a.id === sharedId)!.confidential).toBe(true)+ } else {+ expect(await registered(other)).toBe(1)+ expect((await storedState(first)).agents.find(a => a.id === sharedId)!.confidential).toBeUndefined()+ }+ // Swarm A lets the session go with its project (a Lead is protected from plain removal): no Swarm then holds a confidential+ // session unmarked, because it never had a second registration.+ await run(first, { type: 'project.delete', projectId: project.projectId })+ expect(await registered(first)).toBe(0)+ const left = await db.swarmAgent.findMany({ where: { key: sharedId, deleted: false } })+ expect(left.every(row => winner === 'registration' && !(row.data as { confidential?: boolean }).confidential)).toBe(true)+ expect(left).toHaveLength(winner === 'promotion' ? 0 : 1)+ })++ it('keeps a session registered in two Swarms before the rule closed everywhere: to the other Swarm\'s Lead, its readers and earlier shares', async () => {+ const { tab, lead, harnessId, swarmShare, ordinaryShare, share } = await privateChat()+ const other = await otherSwarm()+ const otherLead = String((await run(other, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: randomUUID(),+ name: 'Other Lead', configuration: config, lead: true })).result.agentId)+ // The PM's session as a Builder in Swarm B, written the way a duplicate from before the rule is stored.+ const pm = (await storedState(tab)).agents.find(a => a.id === lead)!+ const b = await storedState(other)+ const { confidential: _mark, ...unmarked } = pm+ b.agents.push({ ...unmarked, projectId: b.projects![0]!.id, name: 'Builder elsewhere',+ membershipGeneration: b.people.find(p => p.id === pm.contributorId)!.generation })+ b.conversations.find(c => c.id === 'lead')!.agentIds.push(lead)+ await saveState(other, b)+ const row = (await rosterRows(store, host, 'test-host')).find(t => t.tabId === other && t.agent?.id === lead)!+ expect(row).toMatchObject({ observers: [], confidential: true })+ expect(await store.mayObserve(bob, other, 'test-host', harnessId, host.sub)).toBe(false)+ await expect(run(other, { type: 'agent.screen', agentId: lead }, bob)).rejects.toMatchObject({ code: 'TERMINAL_PRIVATE' })+ // Swarm B's Lead cannot read or type into its Builder alias of Swarm A's PM.+ await expect(run(other, { type: 'agent.screen', agentId: lead }, host, otherLead)).rejects.toMatchObject({ code: 'TERMINAL_PRIVATE' })+ await expect(run(other, { type: 'agent.input', agentId: lead, keys: ['Enter'] }, host, otherLead)).rejects.toMatchObject({ code: 'TERMINAL_PRIVATE' })+ // Shares made before the chat, opened as the observer relay opens them.+ expect(await recipientShare(swarmShare, bob, db)).toBeNull()+ expect(await recipientShare(ordinaryShare, carol, db)).toBeNull()+ await db.harnessShare.update({ where: { id: swarmShare }, data: { superTabId: other } })+ expect(await recipientShare(swarmShare, bob, db)).toBeNull()+ // A Builder's session shared the ordinary way still opens.+ const builderHarness = randomUUID()+ await run(other, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: builderHarness, name: 'Plain builder', configuration: config, lead: false })+ expect(await recipientShare(await share(null, carol, builderHarness), carol, db)).not.toBeNull()+ })++ it('lets nobody but its machine\'s owner read or type in it through the terminal requests', async () => {+ const { tab, lead } = await privateChat()+ for (const user of [bob, owner]) {+ await expect(run(tab, { type: 'agent.screen', agentId: lead, scrollback: 200 }, user)).rejects.toMatchObject({ code: 'TERMINAL_PRIVATE' })+ await expect(run(tab, { type: 'agent.input', agentId: lead, text: 'history' }, user)).rejects.toMatchObject({ code: 'TERMINAL_PRIVATE' })+ }+ expect((await run(tab, { type: 'agent.screen', agentId: lead }, host)).result.requestId).toBeTruthy()+ })+})++describe('Swarm sweeps', () => {+ const day = 86_400_000+ async function finishedGroup(tab: string, lead: string) {+ const group = String((await run(tab, { type: 'conversation.create', title: 'Done work', brief: 'Do it',+ checks: [{ description: 'Done', independent: false }] })).result.conversationId)+ const worker = String((await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: randomUUID(),+ name: 'Worker', configuration: config, lead: false })).result.agentId)+ const assignmentId = String((await run(tab, { type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId)+ const checkId = (await store.read(owner, tab)).state.conversations.find(c => c.id === group)!.checks[0]!.id+ await run(tab, { type: 'work.check', conversationId: group, assignmentId, checkId, passed: true, evidence: 'Shown' }, host, lead)+ await run(tab, { type: 'work.status', conversationId: group, assignmentId, status: 'done', result: 'Shipped' }, host, worker)+ return group+ }++ /** The project's Lead reports through everything its workgroup said so far. */+ async function acknowledge(tab: string, lead: string, group: string) {+ const read = (await store.read(owner, tab)).state.conversations.find(c => c.id === group)!+ await run(tab, { type: 'project.report', projectId: 'lead', through: { [group]: read.lastMessageSequence }, text: null }, host, lead)+ }++ it('puts a conversation archived by hand to sleep once its reports are acknowledged, and ordinary loads stop reading it', async () => {+ const { tab, lead } = await fixture()+ const group = await finishedGroup(tab, lead)+ await run(tab, { type: 'conversation.archive', conversationId: group, archived: true })+ const loaded = async () => (await db.$transaction(tx => parts.loadActive(tx, tab))).groups.map(p => p.key)+ expect(await loaded()).toContain(group)+ await acknowledge(tab, lead, group)+ await sweepSwarms(db)+ expect(await loaded()).not.toContain(group)+ expect((await db.$transaction(tx => parts.loadDormant(tx, tab, {}))).map(p => p.key)).toEqual([group])+ // Reopened, it is active again.+ await run(tab, { type: 'conversation.archive', conversationId: group, archived: false })+ expect(await loaded()).toContain(group)+ })++ it('puts a conversation with finished work to sleep after a quiet day, and a new message wakes it', async () => {+ const { tab, lead } = await fixture()+ const group = await finishedGroup(tab, lead)+ const listed = async () => (await store.read(owner, tab)).state.conversations.map(c => c.id)+ await sweepSwarms(db, Date.now() + day - 60_000)+ expect(await listed()).toContain(group)+ // Its reports are not acknowledged yet: it stays awake, where the Lead's report check sees it.+ await sweepSwarms(db, Date.now() + day + 60_000)+ expect(await listed()).toContain(group)+ await acknowledge(tab, lead, group)+ await sweepSwarms(db, Date.now() + day + 60_000)+ expect(await listed()).not.toContain(group)+ // The Lead conversation stays awake whatever its age.+ expect(await listed()).toContain('lead')+ expect((await db.$transaction(tx => parts.loadDormant(tx, tab, {}))).map(p => p.key)).toEqual([group])+ expect((await store.messages(owner, tab, group, {})).messages.at(-1)!.text).toMatch(/^Done/)+ await run(tab, { type: 'message.send', conversationId: group, text: 'One more thing.', replyTo: null, recipientIds: [] })+ expect(await listed()).toContain(group)+ expect(await db.$transaction(tx => parts.loadDormant(tx, tab, {}))).toEqual([])+ })++ it('reaches a finished group behind more than a batch of quiet groups that cannot sleep', async () => {+ const { tab, lead } = await fixture()+ const group = await finishedGroup(tab, lead)+ // 520 groups the sweep must pass over: quiet for days, older than the finished group, but their work is not finished.+ const old = new Date(Date.now() - 10 * day)+ await db.swarmGroup.createMany({ data: Array.from({ length: 520 }, (_, i) => {+ // Keys that sort before any generated id, so they come first in the store's natural order as well as by age.+ const key = `-idle-${String(i).padStart(3, '0')}`+ return { id: `${tab}:${key}`, tabId: tab, key, version: 1, changedAt: old, deleted: false, ordinal: 1000 + i, projectId: 'lead', kind: null,+ archived: false, dormant: false, agentIds: [], executionMachineId: null, messageSeq: 0, reportSeq: 0, lastActivityAt: old,+ data: { id: key, projectId: 'lead', title: key, leadId: null, agentIds: [], archived: false, brief: '', checks: [], assignment: null, lastMessageSequence: 0 } }+ }) })+ await acknowledge(tab, lead, group)+ await sweepSwarms(db, Date.now() + day + 60_000)+ expect((await db.$transaction(tx => parts.loadDormant(tx, tab, {}))).map(p => p.key)).toContain(group)+ })++ it('revokes a terminal in a dormant conversation when its opener loses the project, and restoring access does not revive it', async () => {+ const { tab } = await fixture()+ await invite(tab)+ const projectId = String((await run(tab, { type: 'project.create', name: 'Secret', visibility: 'private', brief: '' })).result.projectId)+ await run(tab, { type: 'project.sharing', projectId, visibility: 'private', memberIds: [peer.sub] })+ const leadChat = (await store.read(owner, tab)).state.projects!.find(p => p.id === projectId)!.leadConversationId+ const projectLead = String((await run(tab, { type: 'agent.add', conversationId: leadChat, machineId: 'test-host', harnessId: randomUUID(),+ name: 'Secret Lead', configuration: config, lead: true })).result.agentId)+ const group = String((await run(tab, { type: 'conversation.create', projectId, title: 'Quiet', brief: 'Old work',+ checks: [{ description: 'Done', independent: false }] })).result.conversationId)+ const worker = String((await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: randomUUID(),+ name: 'Secret Worker', configuration: config, lead: false })).result.agentId)+ const { contextId } = await store.native.open(peer, tab, { operationId: randomUUID(), conversationId: group, agentId: worker })+ const turn = await store.native.append(host, tab, contextId, { turnId: 'kept', kind: 'prompt', previousEventId: null, text: 'Typed by the peer',+ truncated: false, interrupted: false }) as { eventId: string }+ const waiting = await db.superTabDelivery.findFirstOrThrow({ where: { tabId: tab, messageId: turn.eventId, agentId: projectLead } })+ // Its work finished, its reports acknowledged, a quiet day later it sleeps: no ordinary load reads it any more. Not+ // archived: archiving revokes its terminals by itself.+ const assignmentId = String((await run(tab, { type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId)+ const checkId = (await storedState(tab)).conversations.find(c => c.id === group)!.checks[0]!.id+ await run(tab, { type: 'work.check', conversationId: group, assignmentId, checkId, passed: true, evidence: 'Shown' })+ await run(tab, { type: 'work.status', conversationId: group, assignmentId, status: 'done', result: 'Shipped' }, host, worker)+ const read = (await storedState(tab)).conversations.find(c => c.id === group)!+ await run(tab, { type: 'project.report', projectId, through: { [group]: read.lastMessageSequence }, text: null }, host, projectLead)+ await sweepSwarms(db, Date.now() + day + 60_000)+ expect((await db.$transaction(tx => parts.loadDormant(tx, tab, {}))).map(p => p.key)).toContain(group)+ expect((await db.superTabNativeContext.findUniqueOrThrow({ where: { id: contextId } })).revoked).toBe(false)++ await run(tab, { type: 'project.sharing', projectId, visibility: 'private', memberIds: [] })+ expect((await db.superTabNativeContext.findUniqueOrThrow({ where: { id: contextId } })).revoked).toBe(true)+ expect((await db.superTabDelivery.findUniqueOrThrow({ where: { id: waiting.id } })).status).toBe('cancelled')+ await run(tab, { type: 'project.sharing', projectId, visibility: 'private', memberIds: [peer.sub] })+ await expect(store.native.append(host, tab, contextId, { turnId: 'late', kind: 'prompt', previousEventId: turn.eventId, text: 'After removal',+ truncated: false, interrupted: false })).rejects.toMatchObject({ code: 'NATIVE_CONTEXT_REVOKED' })+ })++ it('revokes a terminal in a dormant legacy conversation of the default project, stored with no project, when its opener loses the project', async () => {+ const { tab, lead } = await fixture()+ await invite(tab)+ await run(tab, { type: 'project.sharing', projectId: 'lead', visibility: 'private', memberIds: [peer.sub] })+ const group = String((await run(tab, { type: 'conversation.create', title: 'Legacy quiet', brief: 'Old work',+ checks: [{ description: 'Done', independent: false }] })).result.conversationId)+ const worker = String((await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: randomUUID(),+ name: 'Legacy Worker', configuration: config, lead: false })).result.agentId)+ const { contextId } = await store.native.open(peer, tab, { operationId: randomUUID(), conversationId: group, agentId: worker })+ const turn = await store.native.append(host, tab, contextId, { turnId: 'kept', kind: 'prompt', previousEventId: null, text: 'Typed by the peer',+ truncated: false, interrupted: false }) as { eventId: string }+ const waiting = await db.superTabDelivery.findFirstOrThrow({ where: { tabId: tab, messageId: turn.eventId, agentId: lead } })+ const assignmentId = String((await run(tab, { type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId)+ const checkId = (await storedState(tab)).conversations.find(c => c.id === group)!.checks[0]!.id+ await run(tab, { type: 'work.check', conversationId: group, assignmentId, checkId, passed: true, evidence: 'Shown' })+ await run(tab, { type: 'work.status', conversationId: group, assignmentId, status: 'done', result: 'Shipped' }, host, worker)+ await acknowledge(tab, lead, group)+ await sweepSwarms(db, Date.now() + day + 60_000)+ // Stored as a Swarm from before projects left it: no project on the group, which then belongs to the default one.+ const row = await db.swarmGroup.findFirstOrThrow({ where: { tabId: tab, key: group } })+ const { projectId: _projectId, ...legacy } = row.data as Record<string, unknown>+ await db.swarmGroup.update({ where: { id: row.id }, data: { projectId: null, data: legacy as never } })+ expect((await db.$transaction(tx => parts.loadDormant(tx, tab, {}))).map(p => p.key)).toContain(group)+ expect((await db.superTabNativeContext.findUniqueOrThrow({ where: { id: contextId } })).revoked).toBe(false)++ await run(tab, { type: 'project.sharing', projectId: 'lead', visibility: 'private', memberIds: [] })+ expect((await db.superTabNativeContext.findUniqueOrThrow({ where: { id: contextId } })).revoked).toBe(true)+ expect((await db.superTabDelivery.findUniqueOrThrow({ where: { id: waiting.id } })).status).toBe('cancelled')+ await run(tab, { type: 'project.sharing', projectId: 'lead', visibility: 'private', memberIds: [peer.sub] })+ await expect(store.native.append(host, tab, contextId, { turnId: 'late', kind: 'prompt', previousEventId: turn.eventId, text: 'After removal',+ truncated: false, interrupted: false })).rejects.toMatchObject({ code: 'NATIVE_CONTEXT_REVOKED' })+ })++ it('never lets a person, agent or machine come back at a lower version, even long after it was removed', async () => {+ const { tab } = await fixture()+ const harnessId = randomUUID()+ const add = async () => String((await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId, name: 'Returning',+ configuration: config, lead: false })).result.agentId)+ const agentId = await add()+ for (const effort of ['low', 'medium']) {+ const previous = (await storedState(tab)).agents.find(a => a.id === agentId)!.configurationVersion ?? null+ await run(tab, { type: 'agent.configuration', previousVersion: previous, configuration: { ...config, effort } }, host, agentId)+ }+ const before = await db.swarmAgent.findFirstOrThrow({ where: { tabId: tab, key: agentId } })+ await run(tab, { type: 'agent.remove', agentId })+ // Past the tombstone's 7 days: its record stays, compacted, and holds the version; nothing purges it.+ await sweepSwarms(db, Date.now() + 8 * day)+ const kept = await db.swarmAgent.findFirstOrThrow({ where: { tabId: tab, key: agentId } })+ expect(kept.deleted).toBe(true)+ expect(kept.data).toEqual({})+ expect(kept.version).toBeGreaterThan(before.version)+ await ensurePartExpiry(db)+ for (const collection of ['SwarmMember', 'SwarmAgent', 'SwarmMachine']) {+ const indexes = await db.$runCommandRaw({ listIndexes: collection }) as { cursor: { firstBatch: Array<{ expireAfterSeconds?: number }> } }+ expect(indexes.cursor.firstBatch.filter(i => i.expireAfterSeconds !== undefined), collection).toEqual([])+ }+ await add()+ const back = await db.swarmAgent.findFirstOrThrow({ where: { tabId: tab, key: agentId } })+ expect(back.deleted).toBe(false)+ expect(back.version).toBeGreaterThan(kept.version)+ const history = await db.superTabConfiguration.findMany({ where: { tabId: tab, agentId }, orderBy: { revision: 'asc' } })+ expect(history.at(-1)!.configuration).toMatchObject({ effort: 'high' })+ })++ it('drops finished starts and expired invitations after their time, and creates the purge index', async () => {+ const { tab, lead } = await fixture()+ const { startId } = await routedStart(tab, lead)+ await store.execute(host, tab, { operationId: randomUUID(), command: { type: 'agent.startFailed', startId, error: 'No room.' } }, lead)+ await run(tab, { type: 'invite.create', email: '[email protected]', role: 'viewer', conversationId: 'lead' })+ await sweepSwarms(db, Date.now() + 6 * day)+ expect((await db.$transaction(tx => parts.loadAll(tx, tab))).starts.find(p => p.key === startId)?.deleted).toBeUndefined()+ await sweepSwarms(db, Date.now() + 8 * day)+ expect((await db.$transaction(tx => parts.loadAll(tx, tab))).starts.find(p => p.key === startId)?.deleted).toBe(true)+ expect((await store.read(owner, tab)).state.invitations).toEqual([])+ expect((await db.superTab.findUniqueOrThrow({ where: { id: tab } })).invitedEmails).not.toContain('[email protected]')+ await ensurePartExpiry(db)+ const indexes = await db.$runCommandRaw({ listIndexes: 'SwarmGroup' }) as { cursor: { firstBatch: Array<{ key: object; expireAfterSeconds?: number }> } }+ expect(indexes.cursor.firstBatch).toContainEqual(expect.objectContaining({ key: { purgeAt: 1 }, expireAfterSeconds: 0 }))+ })+})++describe('Swarm parts under concurrent writes', () => {+ /** A store whose transactions are counted: one per attempt, so every retry after a conflict shows. */+ function counted() {+ let attempts = 0+ const proxy = new Proxy(db, { get(target, key, receiver) {+ if (key === '$transaction') return (...args: Parameters<PrismaClient['$transaction']>) => { attempts++; return (target.$transaction as (...a: unknown[]) => unknown)(...args) }+ return Reflect.get(target, key, receiver)+ } })+ return { store: new SuperTabStore(proxy as PrismaClient), get attempts() { return attempts } }+ }+ /** A group with its own assigned worker, so the worker's posts reach the Lead. */+ async function workGroup(tab: string, title: string) {+ const group = String((await run(tab, { type: 'conversation.create', title, brief: 'Build it', checks: [{ description: 'Built', independent: false }] })).result.conversationId)+ const worker = String((await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: randomUUID(),+ name: title, configuration: config, lead: false })).result.agentId)+ await run(tab, { type: 'work.assign', conversationId: group, agentId: worker })+ return { group, worker }+ }++ it('lets agents post in different groups at the same time without a single conflict', async () => {+ const { tab } = await fixture()+ const groups = await Promise.all(['Parser', 'Renderer', 'Exporter', 'Importer'].map(title => workGroup(tab, title)))+ // The project is dirty already, as it is in a busy Swarm: posts do not write its progress again.+ for (const { group, worker } of groups) await run(tab, { type: 'message.send', conversationId: group, text: 'Started.', replyTo: null, recipientIds: [] }, host, worker)+ const c = counted()+ // Each worker posts in turn in its own group, all workers at once: any conflict is between different groups.+ await Promise.all(groups.map(async ({ group, worker }) => {+ for (let i = 0; i < 5; i++) await c.store.execute(host, tab, { operationId: randomUUID(),+ command: { type: 'message.send', conversationId: group, text: `Progress ${i}`, replyTo: null, recipientIds: [] } }, worker)+ }))+ expect(c.attempts).toBe(groups.length * 5)+ for (const { group } of groups) {+ const sequences = (await store.messages(owner, tab, group, {})).messages.map(m => m.sequence)+ expect(new Set(sequences).size).toBe(sequences.length)+ expect(sequences).toEqual([...sequences].sort((a, b) => a - b))+ }+ })++ it('records terminal turns in different groups at the same time without a single conflict, even when one person opened them all', async () => {+ const { tab } = await fixture()+ const groups = await Promise.all(['Alpha', 'Beta', 'Gamma'].map(title => workGroup(tab, title)))+ const contexts = []+ for (const { group, worker } of groups) contexts.push((await store.native.open(owner, tab, { operationId: randomUUID(), conversationId: group, agentId: worker })).contextId)+ // The project is dirty already: a turn writes only its own group.+ for (const contextId of contexts) await store.native.append(host, tab, contextId, { turnId: 'warm', kind: 'prompt', previousEventId: null, text: 'Warm up', truncated: false, interrupted: false })+ const c = counted()+ await Promise.all(contexts.map(async contextId => {+ let previous = (await db.superTabNativeContext.findUniqueOrThrow({ where: { id: contextId } })).lastEventId+ for (let i = 0; i < 4; i++) {+ const recorded = await c.store.native.append(host, tab, contextId, { turnId: `turn_${i}`, kind: 'prompt', previousEventId: previous,+ text: `Prompt ${i}`, truncated: false, interrupted: false }) as { eventId: string }+ previous = recorded.eventId+ }+ }))+ expect(c.attempts).toBe(contexts.length * 4)+ })++ it('lets a Lead\'s host claim its deliveries while the Lead posts, without a conflict between them', async () => {+ const { tab, lead } = await fixture()+ const groups = await Promise.all(['North', 'South', 'East'].map(title => workGroup(tab, title)))+ for (const { group, worker } of groups) {+ for (let i = 0; i < 2; i++) await run(tab, { type: 'message.send', conversationId: group, text: `Report ${i}`, replyTo: null, recipientIds: [] }, host, worker)+ }+ const waiting = await store.deliveries(host, tab, lead)+ expect(waiting.length).toBeGreaterThanOrEqual(6)+ const c = counted()+ await Promise.all([+ ...waiting.map(d => c.store.delivery(host, tab, lead, d.id, { type: 'claim', claimId: randomUUID() })),+ c.store.execute(host, tab, { operationId: randomUUID(), command: { type: 'message.send', conversationId: 'lead', text: 'Planning.', replyTo: null, recipientIds: [] } }, lead),+ ])+ expect(c.attempts).toBe(waiting.length + 1)+ })++ it('gives a machine\'s last slot to exactly one of two concurrent starts', async () => {+ const tab = (await store.create(owner, randomUUID(), 'Slots')).id+ await run(tab, { type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })+ .then(r => run(tab, { type: 'invite.accept', inviteId: r.result.inviteId as string }, host))+ await run(tab, { type: 'machine.contribute', machineId: 'test-host', name: 'Host', cwd: '/fixture/repo', engines: ['codex'], maxAgents: 1 }, host)+ const generation = (await poolRows(store, host, 'test-host')).find(p => p.tabId === tab)!.machine.generation+ await store.observeMachine(host, tab, 'test-host', { generation, resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9,+ diskFreeBytes: 120e9, diskTotalBytes: 500e9, projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture', os: 'macOS', gpuPercent: null },+ quotas: [], tools: {}, runningHarnessIds: [], stoppedHarnessIds: [] })+ const request = (name: string) => ({ conversationId: 'lead', machineId: 'test-host', engine: 'codex', name, cwd: '/fixture/repo', worktree: false,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } })+ const results = await Promise.allSettled([run(tab, { type: 'agent.start', request: request('One') }, host),+ run(tab, { type: 'agent.start', request: request('Two') }, host)])+ expect(results.filter(r => r.status === 'fulfilled')).toHaveLength(1)+ expect(results.find(r => r.status === 'rejected')).toMatchObject({ reason: { code: 'MACHINE_FULL' } })+ })++ it('never keeps a message from a person removed while it was being sent', async () => {+ const { tab, lead } = await fixture()+ await invite(tab)+ const results = await Promise.allSettled([run(tab, message('Sent while leaving.'), peer), run(tab, { type: 'member.remove', userId: peer.sub })])+ expect(results[1]!.status).toBe('fulfilled')+ // Sent first, its delivery was revoked with the membership; sent second, it was refused. Either way nothing waits.+ expect(await store.deliveries(host, tab, lead)).toEqual([])+ const authored = await db.superTabDelivery.findMany({ where: { tabId: tab, authorId: peer.sub } })+ expect(authored.every(d => d.status === 'cancelled')).toBe(true)+ })++ it('serializes a claim against revoking an agent sender', async () => {+ const { tab, lead } = await fixture()+ const { group, worker } = await workGroup(tab, 'Revoked')+ await run(tab, { type: 'message.send', conversationId: group, text: 'Report for the Lead.', replyTo: null, recipientIds: [] }, host, worker)+ const delivery = (await store.deliveries(host, tab, lead)).find(d => d.authorId === worker)!+ await run(tab, { type: 'work.cancel', conversationId: group, assignmentId: (await store.read(owner, tab)).state.conversations.find(c => c.id === group)!.assignment!.id,+ reason: 'Withdrawing the worker' })+ const results = await Promise.allSettled([+ store.delivery(host, tab, lead, delivery.id, { type: 'claim', claimId: randomUUID() }),+ run(tab, { type: 'agent.remove', agentId: worker }),+ ])+ expect(results[1]!.status).toBe('fulfilled')+ expect((await db.superTabDelivery.findUniqueOrThrow({ where: { id: delivery.id } })).status).toBe('cancelled')+ expect((await store.deliveries(host, tab, lead)).map(d => d.id)).not.toContain(delivery.id)+ })++ it('serializes a claim against removing its receiving agent', async () => {+ const { tab, lead } = await fixture()+ const { group, worker } = await workGroup(tab, 'Receiver')+ await run(tab, { type: 'work.cancel', conversationId: group, assignmentId: (await store.read(owner, tab)).state.conversations.find(c => c.id === group)!.assignment!.id,+ reason: 'Withdrawing the worker' })+ await run(tab, { type: 'message.send', conversationId: group, text: 'For the worker.', replyTo: null, recipientIds: [worker] }, host, lead)+ const delivery = (await store.deliveries(host, tab, worker))[0]!+ const results = await Promise.allSettled([+ store.delivery(host, tab, worker, delivery.id, { type: 'claim', claimId: randomUUID() }),+ run(tab, { type: 'agent.remove', agentId: worker }),+ ])+ expect(results[1]!.status).toBe('fulfilled')+ expect((await db.superTabDelivery.findUniqueOrThrow({ where: { id: delivery.id } })).status).toBe('cancelled')+ })++ it('writes the waiting delivery rows of a conversation archived or left by their receiver, so a claim in flight conflicts', async () => {+ const { tab, lead } = await fixture()+ const { group, worker } = await workGroup(tab, 'Rows')+ const assignmentId = (await store.read(owner, tab)).state.conversations.find(c => c.id === group)!.assignment!.id+ await run(tab, { type: 'work.cancel', conversationId: group, assignmentId, reason: 'Done here' })+ const waiting = await run(tab, { type: 'message.send', conversationId: group, text: 'Still waiting.', replyTo: null, recipientIds: [worker] }, host, lead)+ const row = async () => db.superTabDelivery.findFirstOrThrow({ where: { tabId: tab, agentId: worker, messageId: waiting.result.messageId as string } })+ const before = await row()+ await new Promise(resolve => setTimeout(resolve, 5))+ await run(tab, { type: 'conversation.agent', conversationId: group, agentId: worker, present: false, lead: false })+ const left = await row()+ expect(left.updatedAt.getTime()).toBeGreaterThan(before.updatedAt.getTime())+ expect(left.status).toBe(before.status)+ await new Promise(resolve => setTimeout(resolve, 5))+ await run(tab, { type: 'conversation.archive', conversationId: group, archived: true })+ const archived = await row()+ expect(archived.updatedAt.getTime()).toBeGreaterThan(left.updatedAt.getTime())+ // Archiving keeps them for when the conversation reopens, as before.+ expect(archived.status).toBe(before.status)+ })++ it('assigns the routed agent through its finished start, without an override reason', async () => {+ const { tab, lead } = await fixture()+ const { routeDecisionId, startId } = await routedStart(tab, lead)+ await store.execute(host, tab, { operationId: randomUUID(), command: { type: 'agent.startDispatch', startId } }, lead)+ const agentId = String((await store.execute(host, tab, { operationId: randomUUID(), command: { type: 'agent.started', startId,+ harnessId: randomUUID(), configuration: config } }, lead)).result.agentId)+ // Started and not pooled: the start is finished and out of every command's active state.+ expect((await db.swarmStart.findFirstOrThrow({ where: { tabId: tab, key: startId } })).finishedAt).not.toBeNull()+ await run(tab, { type: 'work.define', conversationId: 'lead', brief: 'Routed work', checks: [{ description: 'Done', independent: false }] }, host, lead)+ const assigned = await run(tab, { type: 'work.assign', conversationId: 'lead', agentId, routeDecisionId }, host, lead)+ expect(assigned.result.assignmentId).toBeTruthy()+ expect((await store.routeDecision(owner, tab, routeDecisionId)).final).toMatchObject({ kind: 'new', startId })+ })+})diff --git a/backend/package.json b/backend/package.jsonindex 59353f2e0..5f110ee8c 100644--- a/backend/package.json+++ b/backend/package.json@@ -23,6 +23,7 @@"test": "NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= vitest run","test:watch": "vitest","test:super-tabs": "vitest run --config vitest.super-tabs.config.ts",+ "bench:swarm-state": "NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= DATABASE_URL=mongodb://127.0.0.1:1/bench-never-used tsx integration/bench/run.ts","test:agent-messages": "NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= vitest run src/lib/agentMessageShares.test.ts src/routes/agentMessages.test.ts src/lib/agentMessagesWs.test.ts --coverage --coverage.include=src/lib/agentMessageShares.ts --coverage.include=src/routes/agentMessages.ts --coverage.include=src/lib/agentMessagesWs.ts --coverage.thresholds.lines=100 --coverage.thresholds.statements=100 --coverage.thresholds.functions=100 --coverage.thresholds.branches=100","test:sharing": "NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= vitest run src/routes/harnessShares.test.ts src/routes/harnessLinks.test.ts src/lib/observerWs.test.ts --coverage --coverage.include=src/routes/harnessShares.ts --coverage.include=src/routes/harnessLinks.ts --coverage.include=src/lib/observerWs.ts --coverage.thresholds.lines=100 --coverage.thresholds.statements=100 --coverage.thresholds.branches=100 --coverage.thresholds.functions=100","postinstall": "prisma generate"diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prismaindex 13f8fd317..ae8bcc454 100644--- a/backend/prisma/schema.prisma+++ b/backend/prisma/schema.prisma@@ -1004,6 +1004,11 @@ model SuperTab {cleanupMachineIds String[] @default([])revision Int @default(0)state Json+ /// 1: the whole Swarm in `state`. 2: split into the Swarm* part collections (docs/design/2026-10-26-swarm-state-parts.md);+ /// `state` is then `{ version: 2 }`, which every older backend refuses before writing, and the old state is kept in `legacyState`.+ format Int @default(1)+ migratedAt DateTime?+ legacyState Json?createdAt DateTime @default(now())updatedAt DateTime @updatedAt@@ -1024,6 +1029,9 @@ model SuperTabSessionScope {closeLeaseGeneration String?/// Serializes contribution changes with stop intent across public Swarms.stopReleaseId String?+ /// Set when the session first became confidential (a Lead or in a private conversation): the write a concurrent+ /// registration in another Swarm conflicts with, so a confidential session keeps one registration (final review C1).+ confidential Boolean?id String @id @map("_id")scopeIds String[]privateScope String?@@ -1047,7 +1055,8 @@ model SuperTabMessage {mentions String[]createdAt DateTime @default(now())- @@index([tabId, conversationId, sequence])+ /// Pages read by (sequence, id): older rows of one command share a sequence.+ @@index([tabId, conversationId, sequence, id])}/// A Lead's tag of a person, waiting until they reply in that conversation or mark it done (superTabs/mentions.ts).@@ -1092,6 +1101,8 @@ model SuperTabOperation {requestHash Stringrevision Intresult Json+ /// The parts a command wrote, with their versions, returned again on a replay. Absent on receipts from before parts.+ parts Json?createdAt DateTime @default(now())@@index([tabId])@@ -1261,6 +1272,168 @@ model SuperTabTerminalRequest {@@index([tabId, createdAt])}+// Swarm state by parts (docs/design/2026-10-26-swarm-state-parts.md). Each part is one record of a Swarm, written only+// by the commands that change it. `version` moves on every write and every guarded touch and never resets; `changedAt`+// moves only when `data` changes, and is what readers ask for changes by. A removed part stays as a tombstone+// (`deleted`) until `purgeAt`, so readers learn it is gone. `data` keeps the record's shape from `SuperTab.state`.++/// The Swarm's scalars and settings: projects (without progress), rules, invitations, sharing, routing, Local models.+model SwarmHead {+ id String @id @map("_id")+ tabId String+ key String+ version Int+ changedAt DateTime+ deleted Boolean @default(false)+ purgeAt DateTime?+ ordinal Float+ data Json+ /// Workgroup numbers are never given twice, whatever was deleted or went dormant.+ groupCounter Int @default(0)+ /// Moves when who may see what changes; a reader with an older epoch loads in full.+ visibilityEpoch Int @default(1)+ /// The tab revision when it was split into parts (0 for a Swarm born in parts). Every later message sequence is above it.+ sequenceBase Int @default(0)++ @@unique([tabId, key])+ @@index([tabId, changedAt])+}++/// One person in the Swarm. Every command of theirs touches it, so removing them and their in-flight action cannot both win.+model SwarmMember {+ id String @id @map("_id")+ tabId String+ key String+ version Int+ changedAt DateTime+ deleted Boolean @default(false)+ purgeAt DateTime?+ ordinal Float+ data Json++ @@unique([tabId, key])+ @@index([tabId, changedAt])+}++/// One conversation: its work, checks, assignment, members and message counter.+model SwarmGroup {+ id String @id @map("_id")+ tabId String+ key String+ version Int+ changedAt DateTime+ deleted Boolean @default(false)+ purgeAt DateTime?+ ordinal Float+ data Json+ projectId String?+ kind String?+ archived Boolean @default(false)+ /// Out of first loads and changes: work done or cancelled and quiet for a day, or archived by hand. A message wakes it.+ dormant Boolean @default(false)+ agentIds String[]+ /// The machine running its active assignment, for the host's change read.+ executionMachineId String?+ messageSeq Int @default(0)+ reportSeq Int @default(0)+ lastActivityAt DateTime+ /// The machines whose hosts this group's last write concerned: its agents' and its work's, before and after (host reads).+ hostMachineIds String[] @default([])+ /// A short hash of the fields host rows read (read/hostRows.ts); a post leaves it. Missing on a part written before it.+ hostDigest String?++ @@unique([tabId, key])+ @@index([tabId, changedAt])+ @@index([tabId, dormant, changedAt])+ @@index([tabId, agentIds])+ @@index([tabId, projectId, dormant, lastActivityAt])+ @@index([tabId, projectId, dormant, reportSeq])+ @@index([dormant, lastActivityAt])+ @@index([executionMachineId])+}++model SwarmAgent {+ id String @id @map("_id")+ tabId String+ key String+ version Int+ changedAt DateTime+ deleted Boolean @default(false)+ purgeAt DateTime?+ ordinal Float+ data Json+ machineId String+ machineOwnerId String+ contributorId String++ @@unique([tabId, key])+ @@index([tabId, changedAt])+ @@index([machineId, deleted])+ @@index([tabId, contributorId])+}++/// One machine the Swarm references, contributed or not: its contribution and observation, and its slot ledger.+model SwarmMachine {+ id String @id @map("_id")+ tabId String+ key String+ version Int+ changedAt DateTime+ deleted Boolean @default(false)+ purgeAt DateTime?+ ordinal Float+ data Json+ machineId String+ contributed Boolean @default(false)+ cleanupOwnerIds String[]+ /// The last change to its settings or ledger, never its own reading (host reads wake on this, not on changedAt).+ hostChangedAt DateTime?++ @@unique([tabId, key])+ @@index([tabId, changedAt])+ @@index([machineId, deleted])+}++model SwarmStart {+ id String @id @map("_id")+ tabId String+ key String+ version Int+ changedAt DateTime+ deleted Boolean @default(false)+ purgeAt DateTime?+ ordinal Float+ data Json+ machineId String+ conversationId String+ /// The agent it started, once it has a harness: an agent's own removal and a routed assignment find it by this.+ agentId String?+ /// Failed, or started and settled: out of command state, still loadable by key or agent until it expires 7 days later.+ finishedAt DateTime?++ @@unique([tabId, key])+ @@index([tabId, changedAt])+ @@index([tabId, finishedAt])+ @@index([machineId, finishedAt])+ @@index([tabId, agentId])+}++/// One project's report watermark, and the fence a Lead's worker decisions serialize on.+model SwarmProgress {+ id String @id @map("_id")+ tabId String+ key String+ version Int+ changedAt DateTime+ deleted Boolean @default(false)+ purgeAt DateTime?+ ordinal Float+ data Json++ @@unique([tabId, key])+ @@index([tabId, changedAt])+}+model ExperimentalSettings {id String @id @map("_id") @db.ObjectIduserId Stringdiff --git a/backend/scripts/swarm-parts/dry-run.ts b/backend/scripts/swarm-parts/dry-run.tsnew file mode 100644index 000000000..4151f5287--- /dev/null+++ b/backend/scripts/swarm-parts/dry-run.ts@@ -0,0 +1,150 @@+/**+ * The migration's local dry run (docs/design/2026-10-26-swarm-state-parts.md 6.5): synthetic production-shaped Swarms on+ * a loopback replica set this script starts itself (never DATABASE_URL or a remote host), each step timed:+ * seed → migrate → verify (migrate again: nothing to do) → read by parts → commands through the store → roll back → old read.+ * Also bytes per poll, before (old full-state reads) and after (first load, changes, host form).+ * After the migration, one Swarm gets a private conversation and another a lost task; rolling those back is refused, since+ * the previous release would make the conversation public and read the task as active (final review, Critical 2).+ * The old-read step reads each rolled-back state with this branch's visibleState: it checks the state's shape, not the+ * previous release's binary or its access checks.+ *+ * NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=<test key, as the suites use> node --import tsx scripts/swarm-parts/dry-run.ts [--out artifacts]+ */+import { execFile } from 'node:child_process'+import { randomUUID } from 'node:crypto'+import { mkdirSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import { promisify } from 'node:util'+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'+import { PrismaClient } from '@prisma/client'+import type { AuthUser } from '../../src/lib/ssoAuth.js'+import type { Command } from '../../src/superTabs/commands.js'+import { SuperTabStore } from '../../src/superTabs/store.js'+import { visibleState, type SuperTabState } from '../../src/superTabs/model.js'+import { migrateAll } from '../../src/superTabs/migration/job.js'+import { rollbackFromParts, rollbackLegacy } from '../../src/superTabs/migration/rollback.js'+import * as parts from '../../src/superTabs/parts/index.js'+import { guardedWrite } from '../../src/superTabs/parts/write.js'+import { stateDifference } from '../../src/superTabs/migration/verify.js'+import { SwarmReads } from '../../src/superTabs/read/service.js'+import { HostReads } from '../../src/superTabs/read/host.js'+import { writeLegacySwarm } from './legacy.js'+import { buildSwarm, PRODUCTION_SHAPED } from './shape.js'++const out = process.argv.includes('--out') ? process.argv[process.argv.indexOf('--out') + 1]! : 'artifacts'+const bytes = (value: unknown) => Buffer.byteLength(JSON.stringify(value))+const timings: Record<string, number> = {}+async function step<T>(name: string, body: () => Promise<T>): Promise<T> {+ const started = performance.now()+ const result = await body()+ timings[name] = Math.round(performance.now() - started)+ console.log(`${name}: ${timings[name]} ms`)+ return result+}++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('swarm_parts_dry_run')+const db = new PrismaClient({ datasources: { db: { url: uri } } })+try {+ await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], { env: { ...process.env, DATABASE_URL: uri }, timeout: 120_000 })+ const now = Date.now()+ const seeded = PRODUCTION_SHAPED.map((spec, index) => ({ spec, index, ...buildSwarm(spec, index, now) }))+ await step('1 seed', async () => {+ for (const s of seeded) {+ await writeLegacySwarm(db, s)+ if (s.attempts.length) await db.superTabAttempt.createMany({ data: s.attempts.map(a => ({ ...a, tabId: s.state.id, snapshot: a.snapshot as never })) })+ await db.user.createMany({ data: s.state.people.map(p => ({ id: p.id, externalId: `dry-run-${p.id}`, email: p.email, autonomousEnv: 'prod' })) })+ await db.machine.createMany({ data: s.state.machines!.map(m => ({ machineId: m.machineId, userId: s.state.ownerId, apiKey: 'dry-run', managerId: 'dry-run', autonomousEnv: 'prod', authMode: 'remote' })) })+ }+ })+ // Dated two minutes back, so readers on the real clock (as the store stamps commands) poll past the 30 s overlap.+ const migration = await step('2 migrate', () => migrateAll(db, { waitMs: 2_000, now: () => Date.now() - 120_000 }))+ const again = await step('3 verify: migrate again', () => migrateAll(db, { waitMs: 0 }))++ const store = new SuperTabStore(db)+ const reads = new SwarmReads(store), hosts = new HostReads(store)+ const owner = (s: typeof seeded[number]): AuthUser => ({ sub: s.state.ownerId, email: s.state.people[0]!.email, autonomousEnv: 'prod', role: 'user' })+ const polls = await step('4 read by parts', async () => Promise.all(seeded.map(async s => {+ const first = await reads.firstLoad(owner(s), s.state.id)+ const machineId = s.state.machines![0]!.machineId+ const hostFull = await hosts.changes(owner(s), machineId, { full: true })+ return { s, first, machineId, hostFull }+ })).then(loads => Promise.all(loads.map(async ({ s, first, machineId, hostFull }) => {+ const idle = await reads.changes(owner(s), s.state.id, first.cursor)+ const hostIdle = await hosts.changes(owner(s), machineId, { cursor: hostFull.cursor })+ return { name: s.spec.name, cursor: first.cursor, machineId,+ // Today's Desktop poll: GET /:tabId, the reader's whole visible state, every 3 s.+ oldDesktopPoll: bytes({ revision: s.revision, state: visibleState(s.state, { kind: 'person', userId: s.state.ownerId, email: s.state.people[0]!.email }, now) }),+ firstLoad: bytes(first), idleChanges: bytes(idle), hostFull: bytes(hostFull), hostIdle: bytes(hostIdle) }+ }))))+ const [big, medium] = [seeded[0]!, seeded[1]!]+ const written = await step('5 commands through the store by parts, then poll', async () => {+ const poll = polls[0]!+ const working = big.state.conversations.find(c => c.assignment?.status === 'working')!+ const runsIt = working.assignment!.execution.machineId+ const [hostCursor, runnerCursor] = [(await hosts.changes(owner(big), poll.machineId, { full: true })).cursor,+ (await hosts.changes(owner(big), runsIt, { full: true })).cursor]+ const results = []+ for (const s of [big, medium]) {+ const group = s.state.conversations.find(c => c.assignment?.status === 'working')!+ const run = (command: Command) => store.execute(owner(s), s.state.id, { operationId: randomUUID(), command })+ results.push(await run({ type: 'conversation.rename', conversationId: group.id, title: `${group.title} (renamed)` }),+ await run({ type: 'message.send', conversationId: group.id, text: 'Posted after the migration.', replyTo: null, recipientIds: [] }))+ }+ const changes = await reads.changes(owner(big), big.state.id, poll.cursor)+ // A host none of whose agents is in the group sleeps through it; the one running its work wakes for that Swarm alone.+ const [host, runner] = [await hosts.changes(owner(big), poll.machineId, { cursor: hostCursor }), await hosts.changes(owner(big), runsIt, { cursor: runnerCursor })]+ return { commands: results.length, partsWritten: results.map(r => r.parts.length), changesAfterTwoCommands: bytes(changes),+ groupsSent: 'groups' in changes ? changes.groups.length : null, otherHost: { bytes: bytes(host), tabs: host.tabs.length },+ runningHost: { bytes: bytes(runner), tabs: runner.tabs.map(t => t.tabId === big.state.id ? 'big' : t.tabId) } }+ })+ // What only the new release writes, after the migration: a private chat, and a task its worker lost.+ const [hidden, lost] = [seeded[2]!, seeded.slice(3).find(s => s.state.conversations.some(c => c.assignment))!]+ const unsafe = await step('5b a private chat and a lost task, written after the migration', async () => {+ const chat = await store.execute(owner(hidden), hidden.state.id, { operationId: randomUUID(),+ command: { type: 'conversation.create', title: 'Chat with PM', brief: 'Private.', checks: [], audience: { personIds: [hidden.state.ownerId] } } })+ const task = lost.state.conversations.find(c => c.assignment)!+ await db.$transaction(async tx => {+ const group = (await parts.loadAll(tx, lost.state.id)).groups.find(g => g.key === task.id)!+ const assignment = group.data!.assignment!+ await guardedWrite(tx, lost.state.id, { op: 'update', kind: 'group', key: task.id, seen: group.version,+ data: { ...group.data!, assignment: { ...assignment, status: 'lost', lost: { reason: 'no progress seen', at: Date.now() } },+ lostAttempt: { id: assignment.id, agentId: assignment.agentId } } }, Date.now())+ })+ return { privateChat: { swarm: hidden.spec.name, parts: chat.parts.length }, lostTask: { swarm: lost.spec.name, conversation: task.id } }+ })+ const before = async (s: typeof seeded[number]) => (await db.superTab.findUnique({ where: { id: s.state.id }, select: { format: true, revision: true } }))!+ const unsafeRows = { hidden: await before(hidden), lost: await before(lost) }+ // Written in parts since the migration: rebuilt from the parts, or refused when the previous release would misread them.+ // The others go back to their old state unchanged.+ const rollbacks = await step('6 roll back', async () => [await rollbackFromParts(db, big.state.id), await rollbackFromParts(db, medium.state.id),+ await rollbackFromParts(db, hidden.state.id), await rollbackFromParts(db, lost.state.id),+ ...await Promise.all(seeded.slice(2).filter(s => s !== hidden && s !== lost).map(s => rollbackLegacy(db, s.state.id)))])+ const refused = await Promise.all([hidden, lost].map(async (s, i) => ({ name: s.spec.name, refused: !rollbacks[2 + i]!.ok, error: rollbacks[2 + i]!.error,+ rowUnchanged: JSON.stringify(await before(s)) === JSON.stringify(i ? unsafeRows.lost : unsafeRows.hidden) })))+ // This branch's visibleState over each rolled-back state: its shape still reads. Not the previous release's binary.+ const oldReads = await step('7 old-shape read of every rolled-back Swarm (this branch\'s visibleState, not the previous binary)', async () => Promise.all(seeded.filter(s => s !== hidden && s !== lost).map(async s => {+ const row = (await db.superTab.findUnique({ where: { id: s.state.id } }))!+ const state = row.state as unknown as SuperTabState+ visibleState(state, { kind: 'person', userId: state.ownerId, email: s.state.people[0]!.email }, now)+ const newest = (await db.superTabMessage.findFirst({ where: { tabId: s.state.id }, orderBy: { sequence: 'desc' }, select: { sequence: true } }))?.sequence ?? 0+ return { name: s.spec.name, format: row.format, version: state.version, revisionAboveEverySequence: row.revision > newest,+ unchanged: s === big || s === medium ? null : stateDifference(s.state, state) === null }+ })))++ const report = { at: new Date(now).toISOString(), timings, migration: migration.reports.map(r => ({ ...r, name: seeded.find(s => s.state.id === r.tabId)?.spec.name })),+ totals: migration.totals, again: again.totals, polls: polls.map(({ cursor: _c, machineId: _m, ...p }) => p), written, unsafe, rollbacks, refused,+ oldReads, oldReadsChecked: 'the rolled-back state\'s shape, with this branch\'s visibleState; not the previous release\'s binary or its access checks' }+ mkdirSync(out, { recursive: true })+ const file = join(out, `swarm-parts-migration-${report.at.slice(0, 10)}.json`)+ writeFileSync(file, JSON.stringify(report, null, 2))+ console.log(JSON.stringify({ totals: report.totals, again: report.again, timings, polls: report.polls.slice(0, 2), written, unsafe,+ rolledBack: rollbacks.filter((_, i) => i !== 2 && i !== 3).every(r => r.ok), refused,+ oldShapeReads: oldReads.every(r => r.format === 1 && r.version === 1 && r.revisionAboveEverySequence && r.unchanged !== false) }, null, 2))+ console.log(`report: ${file}`)+} finally {+ await db.$disconnect()+ await replica.stop()+}diff --git a/backend/scripts/swarm-parts/legacy.ts b/backend/scripts/swarm-parts/legacy.tsnew file mode 100644index 000000000..96db270ae--- /dev/null+++ b/backend/scripts/swarm-parts/legacy.ts@@ -0,0 +1,46 @@+/**+ * Writes a Swarm the way the store before parts did: one `SuperTab` row (format 1) holding the whole state at a+ * revision, and its messages numbered by the tab revision that carried them. For the migration's tests and dry run only.+ */+import type { Prisma, PrismaClient } from '@prisma/client'+import { activeWork, type Author, type SuperTabState } from '../../src/superTabs/model.js'++export interface LegacyMessage {+ id: string+ conversationId: string+ sequence: number+ text: string+ author: Author+ recipientIds?: string[]+ source?: Record<string, unknown>+ createdAt: Date+}++const json = (value: unknown) => JSON.parse(JSON.stringify(value)) as Prisma.InputJsonValue++/** Report progress as rows from before parts keep it, in tab revisions (parts keep a watermark per group instead). */+export interface LegacyProgress { dirtyRevision: number; summarizedRevision: number; since: number; requestedRevision: number; requestedAt?: number; requestMessageId?: string }+export function setLegacyProgress(project: NonNullable<SuperTabState['projects']>[number], progress: LegacyProgress): void {+ (project as { progress?: unknown }).progress = progress+}++/** The row's lookup lists as the old store kept them (store.ts indexes). */+export function legacyIndexes(state: SuperTabState) {+ return {+ memberIds: state.people.map(p => p.id), invitedEmails: state.invitations.map(i => i.email),+ machineIds: [...new Set([...state.agents.map(a => a.machineId), ...(state.machines ?? []).map(m => m.machineId),+ ...state.conversations.filter(activeWork).map(c => c.assignment!.execution.machineId), ...(state.closingSessions ?? []).map(c => c.machineId),+ ...(state.machineCleanups ?? []).map(c => c.machineId)])],+ cleanupMachineIds: [...(state.machines ?? []).filter(m => m.removal).map(m => m.machineId), ...(state.machineCleanups ?? []).map(c => c.machineId)],+ }+}++export async function writeLegacySwarm(db: PrismaClient, input: { state: SuperTabState; revision: number; autonomousEnv?: string; messages?: LegacyMessage[] }) {+ const { state, revision, autonomousEnv = 'prod', messages = [] } = input+ await db.superTab.create({ data: { id: state.id, ownerId: state.ownerId, autonomousEnv, revision, state: json(state), ...legacyIndexes(state) } })+ for (let i = 0; i < messages.length; i += 5_000) {+ await db.superTabMessage.createMany({ data: messages.slice(i, i + 5_000).map(m => ({ id: m.id, tabId: state.id, conversationId: m.conversationId,+ sequence: m.sequence, author: json(m.author), text: m.text, replyTo: null, recipientIds: m.recipientIds ?? [], mentions: [],+ ...(m.source ? { source: json(m.source) } : {}), createdAt: m.createdAt })) })+ }+}diff --git a/backend/scripts/swarm-parts/shape.ts b/backend/scripts/swarm-parts/shape.tsnew file mode 100644index 000000000..a6b769181--- /dev/null+++ b/backend/scripts/swarm-parts/shape.ts@@ -0,0 +1,150 @@+/**+ * Synthetic Swarms shaped like production (spec, PM ruling on the dry run): built through real commands, then the fields+ * only the store writes (assignments' ends, ledgers, observations, progress), and history numbered by tab revision as the+ * old store numbered it. Deterministic for a seed. Sizes from the issue: 1.16 MB with 195 groups, 422 KB with 50.+ */+import { applyCommand, type Command, type CommandContext } from '../../src/superTabs/commands.js'+import { createSuperTab, type Actor, type AgentConfiguration, type Assignment, type Author, type SuperTabState } from '../../src/superTabs/model.js'+import { setLegacyProgress, type LegacyMessage } from './legacy.js'++export interface SwarmSpec { name: string; groups: number; agents: number; machines: number; projects: number; messages: number; targetBytes?: number; withoutProjects?: true }+export const PRODUCTION_SHAPED: SwarmSpec[] = [+ { name: 'big', groups: 195, agents: 20, machines: 6, projects: 3, messages: 40_000, targetBytes: 1_160_000 },+ { name: 'medium', groups: 50, agents: 8, machines: 3, projects: 2, messages: 8_000, targetBytes: 422_000 },+ ...Array.from({ length: 10 }, (_, i): SwarmSpec => ({ name: `small-${i}`, groups: 5 + (i % 5), agents: 2, machines: 1, projects: 1, messages: 50 + 25 * i })),+ { name: 'legacy-without-projects', groups: 7, agents: 2, machines: 1, projects: 1, messages: 120, withoutProjects: true },+]+export interface SeededSwarm { state: SuperTabState; revision: number; messages: LegacyMessage[]; attempts: Array<{ id: string; conversationId: string; snapshot: unknown }> }++const DAY = 86_400_000+const config: AgentConfiguration = { engine: 'claude', model: 'opus', effort: 'high', contextWindow: null, engineVersion: null }+/** mulberry32: a small seeded generator, so a dry run can be repeated exactly. */+function random(seed: number) {+ return () => { seed = (seed + 0x6D2B79F5) | 0; let t = Math.imul(seed ^ (seed >>> 15), 1 | seed); t ^= t + Math.imul(t ^ (t >>> 7), 61 | t); return ((t ^ (t >>> 14)) >>> 0) / 4_294_967_296 }+}+const words = 'the agent ran the suite against the local stack and recorded each check with its output before handing the work back'.split(' ')+const prose = (rng: () => number, length: number) => { let text = ''; while (text.length < length) text += `${words[Math.floor(rng() * words.length)]} `; return text.trim() }+const pr = (n: number) => `https://github.com/autonomous-ai/openharness/pull/${n}`+export const personId = (swarm: number, n: number) => (swarm * 16 + n + 1).toString(16).padStart(24, '0')++export function buildSwarm(spec: SwarmSpec, index: number, now: number): SeededSwarm {+ const rng = random(index + 1)+ const tabId = `seed${index.toString(16).padStart(20, '0')}`+ const people = Array.from({ length: 5 }, (_, n) => ({ kind: 'person' as const, userId: personId(index, n), email: `person${n}@swarm${index}.example` }))+ const owner = people[0]!+ let state = createSuperTab(tabId, spec.name, { id: owner.userId, email: owner.email }, 'prod')+ let op = 0+ const run = (command: Command, actor: Actor = owner, context: Partial<CommandContext> = {}) => {+ const effects = applyCommand(state, actor, command, { now: now - 60 * DAY, operationId: `seed-${++op}`, ...context })+ state = effects.state+ return effects.result+ }+ const own = { contribution: { machineOwnerId: owner.userId, contributorId: owner.userId } }+ for (const person of people.slice(1)) run({ type: 'invite.accept', inviteId: run({ type: 'invite.create', email: person.email, role: 'collaborator', conversationId: 'lead' }).inviteId as string }, person)+ for (let p = 1; p < spec.projects; p++) run({ type: 'project.create', name: `Project ${p}`, visibility: p === 1 ? 'public' : 'private', brief: '' })+ const projects = state.projects!.map(p => p.id)+ const machines = Array.from({ length: spec.machines }, (_, m) => `machine-${index}-${m}`)+ for (const machineId of machines) run({ type: 'machine.contribute', machineId, name: machineId, cwd: '/work', scope: 'swarm', engines: ['claude', 'codex'], maxAgents: 4 }, owner, own)+ const leads = state.projects!.map((p, i) => run({ type: 'agent.add', conversationId: p.leadConversationId, machineId: machines[i % machines.length]!,+ harnessId: `lead-${index}-${i}`, name: `Lead ${i}`, configuration: config, lead: true }, owner, own).agentId as string)+ // `groups` counts every conversation, as the issue's sizes do: the work groups, each project's Lead conversation, the Leads one.+ const groups = Array.from({ length: spec.groups - spec.projects - 1 }, (_, g) => run({ type: 'conversation.create', projectId: projects[g % projects.length]!, title: `Task ${g}: ${prose(rng, 30)}`,+ task: { goal: prose(rng, 300), changes: prose(rng, 500), constraints: prose(rng, 400), owns: [`backend/src/area${g}`, `cli/src/area${g}`] },+ checks: Array.from({ length: 1 + Math.floor(rng() * 3) }, () => ({ description: prose(rng, 80), independent: rng() < 0.3 })) }).conversationId as string)+ const workers = Array.from({ length: Math.max(1, spec.agents - leads.length) }, (_, w) => run({ type: 'agent.add', conversationId: groups[w % groups.length]!,+ machineId: machines[w % machines.length]!, harnessId: `worker-${index}-${w}`, name: `Builder ${w}`, configuration: config, lead: false }, owner, own).agentId as string)+ const finishedBefore = new Map<string, number>()+ edit(state, rng, groups, workers, finishedBefore, now)+ const { messages, revision } = history(state, rng, tabId, finishedBefore, spec.messages, now, owner)+ ledger(state, rng, machines, workers, groups, now)+ if (spec.targetBytes) pad(state, spec.targetBytes, rng)+ if (spec.withoutProjects) { delete state.projects; for (const a of state.agents) delete a.projectId; for (const c of state.conversations) delete c.projectId }+ const attempts = groups.filter((_, g) => g % 10 === 3).map(conversationId => ({ id: `${tabId}-attempt-${conversationId}`, conversationId,+ snapshot: { checks: [{ evidence: `Tried in ${pr(9000 + Math.floor(rng() * 999))}` }], assignment: { agentId: workers[0], status: 'stopped', result: prose(rng, 200) } } }))+ return { state, revision, messages, attempts }+}++/** Every kind of finished, running and stuck work, as the store leaves it. */+function edit(state: SuperTabState, rng: () => number, groups: string[], workers: string[], finishedBefore: Map<string, number>, now: number) {+ const free = [...workers]+ for (const id of groups) {+ const group = state.conversations.find(c => c.id === id)!+ const roll = rng()+ // A worker runs one assignment at a time; finished work may name any of them.+ const running = roll < 0.15 && free.length > 0+ const workerId = running ? free.shift()! : workers[Math.floor(rng() * workers.length)]!+ const worker = state.agents.find(a => a.id === workerId)!+ const status: Assignment['status'] | null = running ? (roll < 0.03 ? 'needs_human' : roll < 0.05 ? 'reconciling' : 'working')+ : roll < 0.65 ? 'done' : roll < 0.75 ? 'cancelled' : roll < 0.8 ? 'stopped' : null+ if (!status) continue+ if (!group.agentIds.includes(worker.id)) group.agentIds.push(worker.id)+ group.assignment = { id: `work-${id}`, agentId: worker.id, status, configuration: config,+ execution: { machineId: worker.machineId, harnessId: worker.harnessId, machineOwnerId: worker.machineOwnerId },+ result: status === 'done' ? `Done. ${rng() < 0.5 ? pr(1000 + Math.floor(rng() * 999)) : ''} ${prose(rng, 300)}` : status === 'working' ? null : prose(rng, 120) }+ if (status === 'done') for (const check of group.checks) { check.evidence = prose(rng, 250); check.passedBy = worker.id }+ if (['done', 'cancelled', 'stopped'].includes(status)) {+ finishedBefore.set(id, now - (1 + Math.floor(rng() * 40)) * DAY)+ if (rng() < 0.15) group.archived = true+ }+ }+}++/** Messages numbered by the tab revision of the command that carried them (ties when one command wrote several). */+function history(state: SuperTabState, rng: () => number, tabId: string, finishedBefore: Map<string, number>, count: number, now: number, owner: { userId: string; email: string }) {+ const author: Author = { kind: 'person', id: owner.userId, name: owner.email, membershipGeneration: tabId }+ const groups = state.conversations+ const drafts = Array.from({ length: count }, (_, n) => {+ const group = groups[Math.floor(rng() * groups.length)]!+ const end = finishedBefore.get(group.id) ?? now - 3_600_000+ return { group, at: end - Math.floor(rng() * 20 * DAY), n }+ }).sort((a, b) => a.at - b.at)+ let sequence = 1_000+ const messages = drafts.map(({ group, at, n }) => {+ if (rng() > 0.1) sequence += 1 + Math.floor(rng() * 3)+ group.lastMessageSequence = sequence+ return { id: `${tabId}-m${n}`, conversationId: group.id, sequence, author, createdAt: new Date(at),+ text: rng() < 0.03 ? `Opened ${pr(2000 + n % 999)}` : prose(rng, 40 + Math.floor(rng() * 500)) }+ })+ return { messages, revision: sequence + 7 }+}++/** What only the store writes: starts in every state, slot ledgers, observations, rules, invitations, report progress. */+function ledger(state: SuperTabState, rng: () => number, machines: string[], workers: string[], groups: string[], now: number) {+ const pool = state.machines![0]!+ const request = (conversationId: string) => ({ conversationId, machineId: pool.machineId, engine: 'claude', name: 'Builder', cwd: '/work', worktree: true,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 85, tools: ['git'], devices: [], quotaRequired: false } })+ const owner = state.ownerId+ state.starts = [[null, false, null, false], [null, true, null, false], ['started-h', true, null, true], [null, false, 'Machine offline.', false], ['pooled-h', true, null, false]]+ .map(([harnessId, dispatched, error, settled], s) => ({ id: `start-${s}`, creationId: `creation-${s}`, actorKey: `person:${owner}`, contributorId: owner,+ membershipGeneration: state.people[0]!.generation, machineOwnerId: owner, hostGrant: null, harnessId: harnessId as string | null, dispatched: dispatched as boolean,+ error: error as string | null, poolGeneration: pool.generation, poolSettled: settled as boolean, request: request(groups[s % groups.length]!) }))+ for (const machine of state.machines!) machine.observation = { generation: machine.generation, receivedAt: now - Math.floor(rng() * 20_000), sessionKind: 'computer',+ resources: { cpuPercent: 12, memoryTotalBytes: 34_359_738_368, memoryUsedBytes: 17_179_869_184, diskFreeBytes: 10 ** 11, diskTotalBytes: 10 ** 12,+ projectDiskFreeBytes: 10 ** 11, deviceType: 'laptop', chip: 'Apple M2', os: 'macOS 15', gpuPercent: null }, tools: { git: true },+ quotas: [], runningHarnessIds: state.agents.filter(a => a.machineId === machine.machineId).map(a => a.harnessId), stoppedHarnessIds: [] }+ state.harnessReservations = workers.slice(0, 4).map(id => { const a = state.agents.find(x => x.id === id)!; return { machineId: a.machineId, harnessId: a.harnessId, generation: 'g1', renewed: false } })+ state.releasedHarnesses = Array.from({ length: 30 }, (_, r) => ({ machineId: machines[r % machines.length]!, harnessId: `released-${r}` }))+ state.closingSessions = [{ agentId: 'removed-agent', machineId: machines[0]!, harnessId: 'closing-h', machineOwnerId: owner }]+ state.machineCleanups = [{ machineId: 'removed-machine', removalId: 'removal-1', machineOwnerId: owner }]+ state.overlapAlerts = groups.length > 3 ? [`${groups[0]}:${groups[1]}`] : []+ state.rules = (state.projects ?? []).map((p, r) => ({ id: `rule-${r}`, projectId: p.id, rule: { kind: 'preferEngine' as const, taskKind: 'ui', engine: 'codex' as const },+ text: 'Codex for UI work.', askedBy: owner, askedIn: null, addedBy: owner, createdAt: new Date(now - 30 * DAY).toISOString() }))+ state.invitations.push({ id: 'pending-invite', email: '[email protected]', role: 'viewer', conversationId: 'lead', expiresAt: now + 7 * DAY })+ for (const project of state.projects ?? []) {+ const reports = state.conversations.filter(c => (c.projectId ?? 'lead') === project.id && c.id !== project.leadConversationId && !c.kind).map(c => c.lastMessageSequence)+ const dirty = Math.max(0, ...reports)+ if (dirty) setLegacyProgress(project, { dirtyRevision: dirty, summarizedRevision: Math.max(0, dirty - 40), since: now - DAY, requestedRevision: Math.max(0, dirty - 20), requestedAt: now - 3_600_000 })+ }+ // One group from before link lists, and one of a kind a later release added.+ delete state.conversations.find(c => c.id === groups[groups.length - 1])!.pullRequestUrls+ state.parkedConversations = [{ id: 'later-kind', kind: 'board' as never, title: 'Board', leadId: null, agentIds: [], archived: false, brief: '', checks: [], assignment: null, lastMessageSequence: 0 }]+}++/** Longer results and evidence until the state reaches the production size this spec copies. */+function pad(state: SuperTabState, targetBytes: number, rng: () => number) {+ const finished = state.conversations.filter(c => c.assignment?.result)+ const deficit = targetBytes - Buffer.byteLength(JSON.stringify(state))+ if (deficit <= 0 || !finished.length) return+ const each = Math.ceil(deficit / finished.length)+ for (const group of finished) group.assignment!.result += ` ${prose(rng, each)}`+}diff --git a/backend/src/lib/teamSession.test.ts b/backend/src/lib/teamSession.test.tsindex 6aedcb36d..6c99b00ad 100644--- a/backend/src/lib/teamSession.test.ts+++ b/backend/src/lib/teamSession.test.ts@@ -83,8 +83,7 @@ function recorder() {requester: { name: 'Owner', email: '[email protected]' }, agentName: 'Builder', machineName: 'MacBook Pro · Team' }: name === 'githubStart'? { tabId: 'tab-1', startId: 'start-1', repositoryUrl: 'https://github.com/example/project', own: true, requester: { name: 'Owner', email: '[email protected]' } }- // The pools route marks each row with the app (routes/superTabs.ts), so its store answers rows.- : name === 'hostPools' ? [] : { ok: true }+ : { ok: true }} })return { store: methods() as unknown as SuperTabStore, calls }}@@ -108,7 +107,8 @@ beforeEach(async () => {// A GitHub App that hands out a fixed token: the route's own checks are the store's (githubAssignment).const github = { issue: vi.fn(async () => ({ token: 'fixture-token', expiresAt: new Date(0).toISOString() })), release: vi.fn(async () => {}),prepare: vi.fn(async () => ({ token: 'fixture-read-token', expiresAt: new Date(0).toISOString(), repository: 'example/project' })) }- await app.register(superTabRoutes, { store: store.store, github: github as never })+ // The read API by parts is recorded the same way: its classes reach the store only through it.+ await app.register(superTabRoutes, { store: store.store, reads: store.store as never, hosts: store.store as never, github: github as never })await app.register(harnessShareRoutes)await app.register(deviceKeyRoutes)await app.register(machineRoutes)@@ -135,14 +135,16 @@ const share = () => ({ superTabId: 'a'.repeat(24), machineId: 'team-mac', agentIdescribe('a team session on its own machine', () => {// Every route the allowlist names, as a team daemon calls it, and the store method each one reaches.const own: Array<[string, string, unknown, string]> = [- ['GET', '/api/super-tabs/hosts/team-mac', undefined, 'hostTabs'],- ['GET', '/api/super-tabs/hosts/team-mac/pools', undefined, 'hostPools'],- ['GET', '/api/super-tabs/hosts/team-mac/assignments', undefined, 'hostAssignments'],+ ['GET', '/api/super-tabs/hosts/team-mac/changes?full=1', undefined, 'changes'],+ ['POST', '/api/super-tabs/hosts/team-mac/changes', { full: true, held: { 'tab-1': 'etag-1' } }, 'changes'],['POST', '/api/super-tabs/hosts/team-mac/terminal', undefined, 'hostTerminal'],['GET', '/api/super-tabs/hosts/team-mac/starts/tab-1/start-1', undefined, 'start'],['POST', '/api/super-tabs/hosts/team-mac/starts/tab-1/start-1', startOp, 'execute'],['POST', '/api/super-tabs/tab-1/machines/team-mac', observation, 'observeMachine'],- ['GET', '/api/super-tabs/tab-1?asAgentId=agent-1', undefined, 'read'],+ ['GET', '/api/super-tabs/tab-1/parts?asAgentId=agent-1', undefined, 'firstLoad'],+ ['GET', '/api/super-tabs/tab-1/changes?cursor=eyJ2IjoyfQ&asAgentId=agent-1', undefined, 'changes'],+ ['GET', '/api/super-tabs/tab-1/groups?dormant=1&asAgentId=agent-1', undefined, 'dormant'],+ ['GET', '/api/super-tabs/tab-1/groups/group-1?asAgentId=agent-1', undefined, 'group'],['GET', '/api/super-tabs/tab-1/starts/start-1?asAgentId=agent-1', undefined, 'start'],['GET', '/api/super-tabs/tab-1/routing-policy?asAgentId=agent-1', undefined, 'tabPolicy'],['GET', '/api/super-tabs/tab-1/route-decisions?asAgentId=agent-1', undefined, 'routeDecisions'],@@ -168,6 +170,17 @@ describe('a team session on its own machine', () => {})}+ // Kept on the team session's list, so an old team daemon learns to update rather than being refused.+ for (const url of ['/api/super-tabs/hosts/team-mac', '/api/super-tabs/hosts/team-mac/pools', '/api/super-tabs/hosts/team-mac/assignments',+ '/api/super-tabs/tab-1?asAgentId=agent-1']) {+ it(`GET ${url.split('?')[0]} tells an old team daemon to update Harness`, async () => {+ const res = await call('GET', url)+ expect(res.statusCode, res.body).toBe(426)+ expect(res.json().error?.code).toBe('UPDATE_REQUIRED')+ expect(store.calls).toEqual([])+ })+ }+it('asks for its own agent\'s GitHub token, naming its own machine', async () => {const res = await call('POST', '/api/super-tabs/tab-1/github-token?asAgentId=agent-1', { machineId: 'team-mac' })expect(res.statusCode, res.body).toBe(200)@@ -213,6 +226,8 @@ describe('a team session reaching past its own machine', () => {['GET', '/api/super-tabs/hosts/owner-mac', undefined],['GET', '/api/super-tabs/hosts/owner-mac/pools', undefined],['GET', '/api/super-tabs/hosts/owner-mac/assignments', undefined],+ ['GET', '/api/super-tabs/hosts/owner-mac/changes?full=1', undefined],+ ['POST', '/api/super-tabs/hosts/owner-mac/changes', { full: true }],['POST', '/api/super-tabs/hosts/owner-mac/terminal', undefined],['GET', '/api/super-tabs/hosts/owner-mac/starts/tab-1/start-1', undefined],['POST', '/api/super-tabs/hosts/owner-mac/starts/tab-1/start-1', startOp],@@ -226,7 +241,8 @@ describe('a team session reaching past its own machine', () => {for (const url of ['/api/super-tabs/tab-1', '/api/super-tabs/tab-1/starts/start-1', '/api/super-tabs/tab-1/routing-policy','/api/super-tabs/tab-1/route-decisions', '/api/super-tabs/tab-1/route-decisions/decision-1','/api/super-tabs/tab-1/conversations/lead/messages', '/api/super-tabs/tab-1/conversations/lead/attempts',- '/api/super-tabs/tab-1/terminal/request-1', '/api/super-tabs/tab-1?asAgentId=']) limited(await call('GET', url))+ '/api/super-tabs/tab-1/terminal/request-1', '/api/super-tabs/tab-1?asAgentId=', '/api/super-tabs/tab-1/parts',+ '/api/super-tabs/tab-1/changes?cursor=eyJ2IjoyfQ', '/api/super-tabs/tab-1/groups?dormant=1', '/api/super-tabs/tab-1/groups/group-1']) limited(await call('GET', url))limited(await call('POST', '/api/super-tabs/tab-1/attachments'))expect(store.calls).toEqual([])})@@ -277,6 +293,7 @@ describe('a team session reaching past its own machine', () => {it('cannot use the person\'s Swarm routes: list, create, invite, join, sharing, rules, terminals or machine removal', async () => {for (const [method, url, payload] of [['GET', '/api/super-tabs', undefined],+ ['GET', '/api/super-tabs/list', undefined],['POST', '/api/super-tabs', { operationId: 'op', name: 'Mine' }],['GET', '/api/super-tabs/invitations', undefined],['GET', '/api/super-tabs/tab-1/sharing', undefined],@@ -299,7 +316,9 @@ describe('a team session reaching past its own machine', () => {it('without its machine registered yet, it can reach no host or agent route', async () => {m.machines.splice(m.machines.findIndex(row => row.machineId === 'team-mac'), 1)limited(await call('GET', '/api/super-tabs/hosts/team-mac'))+ limited(await call('GET', '/api/super-tabs/hosts/team-mac/changes'))limited(await call('GET', '/api/super-tabs/tab-1?asAgentId=agent-1'))+ limited(await call('GET', '/api/super-tabs/tab-1/parts?asAgentId=agent-1'))limited(await call('POST', '/api/super-tabs/tab-1/commands', { ...command, asAgentId: 'agent-1' }))expect(store.calls).toEqual([])})@@ -322,9 +341,9 @@ describe('behind the gate, each surface refuses on its own too', () => {describe('the owner, unchanged', () => {it('reaches the same routes, as the person', async () => {- expect((await call('GET', '/api/super-tabs/tab-1', undefined, 'owner-token')).statusCode).toBe(200)- expect((await call('GET', '/api/super-tabs/hosts/owner-mac', undefined, 'owner-token')).statusCode).toBe(200)- expect((await call('GET', '/api/super-tabs/hosts/team-mac', undefined, 'owner-token')).statusCode).toBe(200)+ expect((await call('GET', '/api/super-tabs/tab-1/parts', undefined, 'owner-token')).statusCode).toBe(200)+ expect((await call('GET', '/api/super-tabs/hosts/owner-mac/changes', undefined, 'owner-token')).statusCode).toBe(200)+ expect((await call('GET', '/api/super-tabs/hosts/team-mac/changes', undefined, 'owner-token')).statusCode).toBe(200)// A computer's GitHub token request is the store's to judge, whatever machine its body names.expect((await call('POST', '/api/super-tabs/tab-1/github-token?asAgentId=agent-1', { machineId: 'owner-mac' }, 'owner-token')).statusCode).toBe(200)expect(store.calls.map(c => c.args[0])).toEqual([owner, owner, owner, owner])diff --git a/backend/src/lib/teamSession.ts b/backend/src/lib/teamSession.tsindex a89b6f1d1..65f253382 100644--- a/backend/src/lib/teamSession.ts+++ b/backend/src/lib/teamSession.ts@@ -107,6 +107,11 @@ export const TEAM_ROUTES: readonly TeamRoute[] = [{ method: 'GET', url: '/api/super-tabs/hosts/:machineId', scope: 'machine' },{ method: 'GET', url: '/api/super-tabs/hosts/:machineId/pools', scope: 'machine' },{ method: 'GET', url: '/api/super-tabs/hosts/:machineId/assignments', scope: 'machine' },+ // The host loop by parts (docs/design/2026-10-26-swarm-state-parts.md 4.10). The three reads above answer 426 now; they+ // stay listed so an old team daemon is told to update rather than refused.+ { method: 'GET', url: '/api/super-tabs/hosts/:machineId/changes', scope: 'machine' },+ // The same read with the etags the host holds, in a body (too many for a URL).+ { method: 'POST', url: '/api/super-tabs/hosts/:machineId/changes', scope: 'machine' },{ method: 'POST', url: '/api/super-tabs/hosts/:machineId/terminal', scope: 'machine' },{ method: 'GET', url: '/api/super-tabs/hosts/:machineId/starts/:tabId/:startId', scope: 'machine' },{ method: 'POST', url: '/api/super-tabs/hosts/:machineId/starts/:tabId/:startId', scope: 'machine' },@@ -116,6 +121,10 @@ export const TEAM_ROUTES: readonly TeamRoute[] = [{ method: 'POST', url: '/api/super-tabs/:tabId/machines/:machineId', scope: 'machine' },// Reads as one of its agents.{ method: 'GET', url: '/api/super-tabs/:tabId', scope: 'agent' },+ { method: 'GET', url: '/api/super-tabs/:tabId/parts', scope: 'agent' },+ { method: 'GET', url: '/api/super-tabs/:tabId/changes', scope: 'agent' },+ { method: 'GET', url: '/api/super-tabs/:tabId/groups', scope: 'agent' },+ { method: 'GET', url: '/api/super-tabs/:tabId/groups/:conversationId', scope: 'agent' },{ method: 'GET', url: '/api/super-tabs/:tabId/starts/:startId', scope: 'agent' },{ method: 'GET', url: '/api/super-tabs/:tabId/routing-policy', scope: 'agent' },{ method: 'GET', url: '/api/super-tabs/:tabId/route-decisions', scope: 'agent' },diff --git a/backend/src/migrate.ts b/backend/src/migrate.tsnew file mode 100644index 000000000..3f0b5f29c--- /dev/null+++ b/backend/src/migrate.ts@@ -0,0 +1,20 @@+/**+ * The one-off job that moves every Swarm to parts (docs/design/2026-10-26-swarm-state-parts.md, section 6.1):+ * `node dist/migrate.js`, run with no old backend process left. Exits 1 when any Swarm failed (it is left as it was),+ * 2 when a writer is still running.+ */+import { prisma } from './lib/prisma.js'+import { logger } from './utils/logger.js'+import { migrateAll } from './superTabs/migration/job.js'++try {+ const { totals } = await migrateAll(prisma, { log: report => report.ok ? logger.info('[swarm-parts] migrated', { ...report })+ : logger.error('[swarm-parts] not migrated', undefined, { ...report }) })+ logger.info('[swarm-parts] migration finished', totals)+ process.exitCode = totals.failed ? 1 : 0+} catch (error) {+ logger.error('[swarm-parts] migration did not start', error)+ process.exitCode = 2+} finally {+ await prisma.$disconnect()+}diff --git a/backend/src/routes/harnessShares.test.ts b/backend/src/routes/harnessShares.test.tsindex e9c017104..46f979903 100644--- a/backend/src/routes/harnessShares.test.ts+++ b/backend/src/routes/harnessShares.test.ts@@ -4,9 +4,9 @@ import { randomUUID } from 'node:crypto'const mocks = vi.hoisted(() => ({prisma: { harnessShare: { findFirst: vi.fn(), findMany: vi.fn(), findUnique: vi.fn(), upsert: vi.fn(), updateMany: vi.fn() },machine: { findFirst: vi.fn(), findMany: vi.fn() }, user: { findMany: vi.fn(), findUnique: vi.fn() } },- mayObserve: vi.fn(), presence: vi.fn(), changed: vi.fn(), listChanged: vi.fn(), auth: vi.fn(),+ mayOpenShare: vi.fn(), presence: vi.fn(), changed: vi.fn(), listChanged: vi.fn(), auth: vi.fn(),}))-vi.mock('../superTabs/store.js', () => ({ SuperTabStore: class { mayObserve = mocks.mayObserve } }))+vi.mock('../superTabs/store.js', () => ({ SuperTabStore: class { mayOpenShare = mocks.mayOpenShare } }))vi.mock('../lib/prisma.js', () => ({ prisma: mocks.prisma, machineAlive: { OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }] } }))vi.mock('../lib/bus.js', () => ({ getAgentPresenceMany: mocks.presence, publishShareChanged: mocks.changed,publishDeviceMachineListChanged: mocks.listChanged }))@@ -25,6 +25,7 @@ describe('account-bound harness invitations', () => {let app: FastifyInstancebeforeEach(async () => {vi.resetAllMocks()+ mocks.mayOpenShare.mockResolvedValue(true)mocks.auth.mockResolvedValue(owner)mocks.prisma.machine.findFirst.mockResolvedValue(machine)mocks.prisma.machine.findMany.mockResolvedValue([machine])@@ -209,12 +210,22 @@ describe('account-bound harness invitations', () => {const share = { id: 'share', ...input(), superTabId: 'a'.repeat(24), ownerId: owner.sub, expiresAt: new Date(input().expiresAt) }mocks.prisma.harnessShare.findFirst.mockResolvedValue(share)mocks.prisma.harnessShare.findMany.mockResolvedValue([share])- mocks.mayObserve.mockResolvedValue(true)expect(await recipientShare('share', ken)).toEqual(share)- expect(mocks.mayObserve).toHaveBeenCalledWith(ken, share.superTabId, 'm1', 'agent-1', owner.sub)- mocks.mayObserve.mockResolvedValue(false)+ expect(mocks.mayOpenShare).toHaveBeenCalledWith(ken, share)+ mocks.mayOpenShare.mockResolvedValue(false)expect(await recipientShare('share', ken)).toBeNull()expect((await app.inject({ method: 'GET', url: '/api/harness-shares', headers: auth })).json().data.machines).toEqual([])})+ it('asks the Swarms about an ordinary share too: a confidential session refuses it (final review, Critical 1)', async () => {+ mocks.auth.mockResolvedValue(ken)+ const share = { id: 'share', ...input(), superTabId: null, ownerId: owner.sub, expiresAt: new Date(input().expiresAt) }+ mocks.prisma.harnessShare.findFirst.mockResolvedValue(share)+ mocks.prisma.harnessShare.findMany.mockResolvedValue([share])+ mocks.mayOpenShare.mockResolvedValue(false)+ expect(await recipientShare('share', ken)).toBeNull()+ expect(mocks.mayOpenShare).toHaveBeenCalledWith(ken, share)+ expect((await app.inject({ method: 'GET', url: '/api/harness-shares', headers: auth })).json().data.machines).toEqual([])+ })+})diff --git a/backend/src/routes/harnessShares.ts b/backend/src/routes/harnessShares.tsindex 083c795d6..125c69f0f 100644--- a/backend/src/routes/harnessShares.ts+++ b/backend/src/routes/harnessShares.ts@@ -1,4 +1,5 @@import type { FastifyInstance } from 'fastify'+import type { PrismaClient } from '@prisma/client'import { z } from 'zod'import { SuperTabStore } from '../superTabs/store.js'import { prisma, machineAlive } from '../lib/prisma.js'@@ -40,17 +41,17 @@ async function tellRecipient(shareId: string): Promise<void> {} catch { /* best effort */ }}-export async function recipientShare(id: string, user: AuthUser) {- const share = await prisma.harnessShare.findFirst({ where: {+export async function recipientShare(id: string, user: AuthUser, db: PrismaClient = prisma) {+ const share = await db.harnessShare.findFirst({ where: {id, recipientEmail: user.email.trim().toLowerCase(), autonomousEnv: user.autonomousEnv,revokedAt: null, expiresAt: { gt: new Date() },} })if (!share) return null- const machine = await prisma.machine.findFirst({ where: {+ const machine = await db.machine.findFirst({ where: {machineId: share.machineId, userId: share.ownerId, autonomousEnv: user.autonomousEnv, ...machineAlive,} })if (!machine || !machineBillingAllowsDataPlane(machine)) return null- if (share.superTabId && !await new SuperTabStore(prisma).mayObserve(user, share.superTabId, share.machineId, share.agentId, share.ownerId)) return null+ if (!await new SuperTabStore(db).mayOpenShare(user, share)) return nullreturn share}@@ -62,7 +63,7 @@ export async function harnessShareRoutes(app: FastifyInstance): Promise<void> {}, orderBy: { createdAt: 'asc' }, take: 1000 })const visible: typeof shares = []for (const share of shares) {- if (!share.superTabId || await new SuperTabStore(prisma).mayObserve(req.user!, share.superTabId, share.machineId, share.agentId, share.ownerId)) visible.push(share)+ if (await new SuperTabStore(prisma).mayOpenShare(req.user!, share)) visible.push(share)}const machines = await prisma.machine.findMany({ where: {machineId: { in: [...new Set(visible.map(s => s.machineId))] },diff --git a/backend/src/routes/superTabs.ts b/backend/src/routes/superTabs.tsindex aa88c505b..52dbd1b16 100644--- a/backend/src/routes/superTabs.ts+++ b/backend/src/routes/superTabs.ts@@ -19,6 +19,9 @@ import { githubRepository } from '../github/repository.js'import { attribution } from '../github/attribution.js'import { githubTokensFromEnv, type GitHubTokens } from '../github/tokens.js'import { logger } from '../utils/logger.js'+import { SwarmReads } from '../superTabs/read/service.js'+import { HostReads } from '../superTabs/read/host.js'+import { UPDATE_REQUIRED } from '../superTabs/read/contract.js'const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)const tabParams = z.object({ tabId: id })@@ -26,12 +29,22 @@ const agentQuery = z.object({ asAgentId: id.optional() }).strict()const create = z.object({ operationId: id, name: z.string().trim().min(1).max(160), projectVisibility: z.enum(['public', 'private']).optional() }).strict()const operation = operationSchema.extend({ asAgentId: id.optional() })const listQuery = z.object({ after: id.optional() }).strict()+const cursor = z.string().min(1).max(512).regex(/^[A-Za-z0-9_-]+$/)+const changesQuery = agentQuery.extend({ cursor })+const dormantQuery = agentQuery.extend({ dormant: z.literal('1'), projectId: id.optional(), before: cursor.optional() })+const groupParams = tabParams.extend({ conversationId: id })+const hostChangesQuery = z.object({ cursor: cursor.optional(), full: z.literal('1').optional() }).strict()+const etag = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/)+const hostChangesBody = z.object({ cursor: cursor.optional(), full: z.boolean().optional(),+ held: z.record(id, etag).refine(held => Object.keys(held).length <= 500, 'At most 500 Swarms.').optional() }).strict()const startParams = tabParams.extend({ startId: id })const nativeParams = tabParams.extend({ contextId: id })const messageParams = tabParams.extend({ conversationId: id })+// 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() })+ before: z.coerce.number().int().nonnegative().safe().optional(), messageId: id.optional(), afterId: id.optional(), beforeId: id.optional() }).refine(q => [q.after, q.before, q.messageId].filter(value => value !== undefined).length <= 1, 'Choose one message cursor or exact message.')+ .refine(q => (q.afterId === undefined || q.after !== undefined) && (q.beforeId === undefined || q.before !== undefined), 'Send afterId with after, beforeId with before.')const decisionParams = tabParams.extend({ decisionId: id })const roleParams = tabParams.extend({ projectId: id, roleId: id })const terminalParams = tabParams.extend({ requestId: id })@@ -62,17 +75,31 @@ async function respond(reply: FastifyReply, action: () => Promise<unknown>) {/** Uses the normal authenticated control API. It never accepts caller-provided host/contributor identities.* `github` is the Harness GitHub App (github/tokens.ts): read from the environment unless given, null when off. */-export async function superTabRoutes(app: FastifyInstance, options: { store?: SuperTabStore; github?: GitHubTokens | null } = {}) {+/** Full-state reads of clients from before Swarms were stored by parts (design 4.11): every old client reads one of them+ * before or right after any action, so it meets this at once. */+const updateRequired = (_req: unknown, reply: FastifyReply) => sendError(reply, UPDATE_REQUIRED.message, UPDATE_REQUIRED.code, UPDATE_REQUIRED.status)++export async function superTabRoutes(app: FastifyInstance, options: { store?: SuperTabStore; github?: GitHubTokens | null; reads?: SwarmReads; hosts?: HostReads } = {}) {const github = options.github !== undefined ? options.github : await githubTokensFromEnv(env)// A task that ends revokes the token it was given; a revoke that fails is logged inside and never blocks the write.const store = options.store ?? new SuperTabStore(prisma, Date.now, attachmentsFromEnv(env),{ workEnded: (tabId, ended) => { void github?.release(tabId, ended).catch(error => logger.warn('[github] release failed', { tabId, error: String(error) })) },// A team account has no git login of its own: without the app it takes no teammates' work.teamAccountsIdle: !github })+ const reads = options.reads ?? new SwarmReads(store, { githubApp: !!github })+ const hosts = options.hosts ?? new HostReads(store, { githubApp: !!github, teamAccountsIdle: !github })app.get('/api/super-tabs/grids', (req, reply) => respond(reply, () => store.hostGrids(req.user!)))// Each row says whether this server has the Harness GitHub App, so the host knows to ask for a start's token below.- app.get<{ Params: z.infer<typeof hostParams> }>('/api/super-tabs/hosts/:machineId/pools', { preHandler: validateParams(hostParams) },- (req, reply) => respond(reply, async () => (await store.hostPools(req.user!, req.params.machineId)).map(row => github ? { ...row, githubApp: true } : row)))+ app.get('/api/super-tabs/hosts/:machineId/pools', updateRequired)+ // Replaces the three host reads above and below: every Swarm of the machine with `full=1` (at start and at least every+ // 60 s), else only those with a change that concerns it since the cursor (design 4.10).+ app.get<{ Params: z.infer<typeof hostParams>; Querystring: z.infer<typeof hostChangesQuery> }>('/api/super-tabs/hosts/:machineId/changes',+ { preHandler: [validateParams(hostParams), validateQuery(hostChangesQuery)] },+ (req, reply) => respond(reply, () => hosts.changes(req.user!, req.params.machineId, { cursor: req.query.cursor, full: req.query.full === '1' })))+ // The same read for a host that holds etags (`held`, design 4.10): too many for a URL, so in a body.+ app.post<{ Params: z.infer<typeof hostParams>; Body: z.infer<typeof hostChangesBody> }>('/api/super-tabs/hosts/:machineId/changes',+ { preHandler: [validateParams(hostParams), validateBody(hostChangesBody)] },+ (req, reply) => respond(reply, () => hosts.changes(req.user!, req.params.machineId, req.body)))// A read-only token for a queued start's project repository, for its host to clone and fetch the folder before the agent// exists, so that the machine owner's own git login is never used for another person's project (docs/swarm-github-app.md).// The machine owner's own project answers `github: false` and the host uses its own login, unless it asks `always` (a@@ -117,8 +144,9 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Suapp.get<{ Params: z.infer<typeof tabParams>; Querystring: z.infer<typeof agentQuery> }>('/api/super-tabs/:tabId/routing-policy',{ preHandler: [validateParams(tabParams), validateQuery(agentQuery)] },(req, reply) => respond(reply, () => store.tabPolicy(req.user!, req.params.tabId, req.query.asAgentId)))- app.get<{ Querystring: z.infer<typeof listQuery> }>('/api/super-tabs', { preHandler: validateQuery(listQuery) },- (req, reply) => respond(reply, () => store.list(req.user!, req.query.after)))+ app.get('/api/super-tabs', updateRequired)+ app.get<{ Querystring: z.infer<typeof listQuery> }>('/api/super-tabs/list', { preHandler: validateQuery(listQuery) },+ (req, reply) => respond(reply, () => reads.list(req.user!, req.query.after)))app.post<{ Body: z.infer<typeof create> }>('/api/super-tabs', { preHandler: validateBody(create) },(req, reply) => respond(reply, () => store.create(req.user!, req.body.operationId, req.body.name, req.body.projectVisibility)))app.get('/api/super-tabs/invitations', (req, reply) => respond(reply, () => store.invitations(req.user!)))@@ -135,20 +163,29 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Suapp.post<{ Params: z.infer<typeof tabParams>; Body: z.infer<typeof joinSwarmSchema> }>('/api/super-tabs/:tabId/join',{ preHandler: [validateParams(tabParams), validateBody(joinSwarmSchema)] },(req, reply) => respond(reply, () => store.join(req.user!, req.params.tabId, req.body)))- app.get<{ Params: z.infer<typeof hostParams> }>('/api/super-tabs/hosts/:machineId', { preHandler: validateParams(hostParams) },- (req, reply) => respond(reply, () => store.hostTabs(req.user!, req.params.machineId)))+ app.get('/api/super-tabs/hosts/:machineId', updateRequired)app.post<{ Params: z.infer<typeof hostParams> }>('/api/super-tabs/hosts/:machineId/terminal', { preHandler: validateParams(hostParams) },(req, reply) => respond(reply, () => store.hostTerminal(req.user!, req.params.machineId)))// Long-polls about 20 seconds; a request still waiting then answers `pending` and is read again.app.get<{ Params: z.infer<typeof terminalParams>; Querystring: z.infer<typeof agentQuery> }>('/api/super-tabs/:tabId/terminal/:requestId',{ preHandler: [validateParams(terminalParams), validateQuery(agentQuery)] },(req, reply) => respond(reply, () => store.terminalResult(req.user!, req.params.tabId, req.params.requestId, req.query.asAgentId, 20_000)))- app.get<{ Params: z.infer<typeof hostParams> }>('/api/super-tabs/hosts/:machineId/assignments', { preHandler: validateParams(hostParams) },- (req, reply) => respond(reply, () => store.hostAssignments(req.user!, req.params.machineId)))- // `githubApp` (only when the server has the app) lets a Lead's start wire its token into another person's work (cli/src/superTabs/start.ts).- app.get<{ Params: z.infer<typeof tabParams>; Querystring: z.infer<typeof agentQuery> }>('/api/super-tabs/:tabId',+ app.get('/api/super-tabs/hosts/:machineId/assignments', updateRequired)+ app.get('/api/super-tabs/:tabId', updateRequired)+ // The read API by parts (design section 4, superTabs/read/contract.ts). `githubApp` on a first load (only when the server+ // has the app) lets a Lead's start wire its token into another person's work (cli/src/superTabs/start.ts).+ app.get<{ Params: z.infer<typeof tabParams>; Querystring: z.infer<typeof agentQuery> }>('/api/super-tabs/:tabId/parts',{ preHandler: [validateParams(tabParams), validateQuery(agentQuery)] },- (req, reply) => respond(reply, async () => ({ ...await store.read(req.user!, req.params.tabId, req.query.asAgentId), ...(github ? { githubApp: true } : {}) })))+ (req, reply) => respond(reply, () => reads.firstLoad(req.user!, req.params.tabId, req.query.asAgentId)))+ app.get<{ Params: z.infer<typeof tabParams>; Querystring: z.infer<typeof changesQuery> }>('/api/super-tabs/:tabId/changes',+ { preHandler: [validateParams(tabParams), validateQuery(changesQuery)] },+ (req, reply) => respond(reply, () => reads.changes(req.user!, req.params.tabId, req.query.cursor, req.query.asAgentId)))+ app.get<{ Params: z.infer<typeof tabParams>; Querystring: z.infer<typeof dormantQuery> }>('/api/super-tabs/:tabId/groups',+ { preHandler: [validateParams(tabParams), validateQuery(dormantQuery)] },+ (req, reply) => respond(reply, () => reads.dormant(req.user!, req.params.tabId, { projectId: req.query.projectId, before: req.query.before }, req.query.asAgentId)))+ app.get<{ Params: z.infer<typeof groupParams>; Querystring: z.infer<typeof agentQuery> }>('/api/super-tabs/:tabId/groups/:conversationId',+ { preHandler: [validateParams(groupParams), validateQuery(agentQuery)] },+ (req, reply) => respond(reply, () => reads.group(req.user!, req.params.tabId, req.params.conversationId, req.query.asAgentId)))// A one-hour installation token for the repository of the calling agent's task, for git and gh on its machine// (docs/swarm-github-app.md). Only that agent's host, on the machine running it, while the task is in its hands.app.post<{ Params: z.infer<typeof tabParams>; Querystring: z.infer<typeof agentQuery>; Body: z.infer<typeof githubToken> }>('/api/super-tabs/:tabId/github-token',diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.tsindex 5e223a75a..c1bc96f9f 100644--- a/backend/src/superTabs/commands.test.ts+++ b/backend/src/superTabs/commands.test.ts@@ -817,8 +817,10 @@ it('assigns stable workgroup numbers through old snapshots, rename, archive andconst f = fixture(), first = f.group(), second = f.group()// The Lead and Leads conversations have no number.expect(f.state.conversations.map(c => c.number)).toEqual([undefined, 1, 2, undefined])+ // An old snapshot has neither the numbers nor the counter the store by parts keeps.delete f.state.conversations[1]!.numberdelete f.state.conversations[2]!.number+ delete f.state.groupCounterexpect(visibleState(f.state, owner).conversations.map(c => c.number)).toEqual([undefined, 1, 2, undefined])expect(f.state.conversations[1]!.number).toBeUndefined()f.run({ type: 'conversation.rename', conversationId: first, title: 'Renamed' })@@ -2283,3 +2285,165 @@ describe('credentials in Swarm chat', () => {expect(withoutCredentials(pause, removed)).toBe(pause)})})++describe('private conversations (an explicit audience)', () => {+ /** A Swarm with a Lead, a worker, and the peer as a collaborator; the peer opens a private conversation with the Lead. */+ function privateFixture() {+ const f = fixture()+ f.invite()+ const lead = f.add('lead-harness', 'owner', 'lead', true)+ const worker = f.add('worker-harness')+ const group = f.run({ type: 'conversation.create', title: 'Peer and PM', brief: '', checks: [], audience: { personIds: ['peer'] } }, peer)+ .result.conversationId as string+ const agentActor = (agentId: string): Actor => ({ kind: 'agent', agentId, machineOwnerId: 'host-owner' })+ // Object.assign keeps the fixture's live `state` getter; a spread would copy today's state.+ return Object.assign(f, { lead, worker, group, agentActor })+ }+ const sees = (state: Parameters<typeof visibleState>[0], actor: Actor, group: string) => visibleState(state, actor).conversations.some(c => c.id === group)++ it('shows it to the people listed and the project Lead only, not to the owners or other agents', () => {+ const f = privateFixture()+ expect(f.state.conversations.find(c => c.id === f.group)).toMatchObject({ audience: { people: [{ id: 'peer', generation: expect.any(String) }] },+ agentIds: [f.lead], leadId: f.lead })+ expect(sees(f.state, peer, f.group)).toBe(true)+ expect(sees(f.state, f.agentActor(f.lead), f.group)).toBe(true)+ expect(sees(f.state, owner, f.group)).toBe(false)+ expect(sees(f.state, f.agentActor(f.worker), f.group)).toBe(false)+ expect(() => f.run({ type: 'message.send', conversationId: f.group, text: 'Hello', replyTo: null, recipientIds: [] })).toThrow('unavailable')+ expect(f.run({ type: 'message.send', conversationId: f.group, text: 'Hello', replyTo: null, recipientIds: [] }, peer).messages[0]!.recipients).toEqual([f.lead])+ })++ it('lets a person open one only with themselves in it, and a Lead with any project reader', () => {+ const f = privateFixture()+ expect(() => f.run({ type: 'conversation.create', title: 'Not mine', brief: '', checks: [], audience: { personIds: ['owner'] } }, peer))+ .toThrow('yourself')+ const opened = f.run({ type: 'conversation.create', title: 'Owner and PM', brief: '', checks: [], audience: { personIds: ['owner'] } }, f.agentActor(f.lead))+ expect(sees(f.state, owner, opened.result.conversationId as string)).toBe(true)+ expect(() => f.run({ type: 'conversation.create', title: 'Stranger', brief: '', checks: [], audience: { personIds: ['nobody'] } }, f.agentActor(f.lead)))+ .toThrow()+ })++ it('lets only the Lead or a listed person change who is in it, and never makes it public', () => {+ const f = privateFixture()+ expect(() => f.run({ type: 'conversation.audience', conversationId: f.group, personIds: ['peer', 'owner'] })).toThrow('unavailable')+ f.run({ type: 'conversation.audience', conversationId: f.group, personIds: ['peer', 'owner'] }, peer)+ expect(sees(f.state, owner, f.group)).toBe(true)+ f.run({ type: 'conversation.audience', conversationId: f.group, personIds: [] }, f.agentActor(f.lead))+ expect(sees(f.state, peer, f.group)).toBe(false)+ expect(sees(f.state, f.agentActor(f.lead), f.group)).toBe(true)+ const shared = f.group === 'lead' ? '' : f.run({ type: 'conversation.create', title: 'Shared', brief: '', checks: [] }).result.conversationId as string+ expect(() => f.run({ type: 'conversation.audience', conversationId: shared, personIds: ['owner'] })).toThrow('stays')+ })++ it('holds only messages and the project Lead', () => {+ const f = privateFixture()+ expect(() => f.run({ type: 'conversation.agent', conversationId: f.group, agentId: f.worker, present: true, lead: false }, peer)).toThrow()+ expect(() => f.run({ type: 'conversation.agent', conversationId: f.group, agentId: f.worker, present: true, lead: false }, f.agentActor(f.lead)))+ .toThrow('only the Lead')+ expect(() => f.run({ type: 'work.define', conversationId: f.group, brief: 'Work', checks: [{ description: 'Done', independent: false }] }, f.agentActor(f.lead)))+ .toThrow('chat')+ })++ it('never puts its work or titles in front of other projects\' Leads', () => {+ const f = privateFixture()+ expect(visibleState(f.state, f.agentActor(f.lead)).otherProjectsWork ?? []).toEqual([])+ })+})++describe('lost work (liveness.ts)', () => {+ /** A Lead, and a group with two workers, the first assigned; the clock is at 1000 in every command. */+ const lostFixture = () => {+ const f = fixture()+ const lead = f.add('lead', 'owner', 'lead', true)+ const group = f.group(), worker = f.add('worker', 'owner', group), other = f.add('other', 'owner', group)+ const as = (agentId: string): Actor => ({ kind: 'agent', agentId, machineOwnerId: 'host-owner' })+ f.run({ type: 'work.assign', conversationId: group, agentId: worker })+ const task = () => f.state.conversations.find(c => c.id === group)!+ const limit = () => f.run({ type: 'agent.alert', agentId: worker, alert: 'limit', active: true, resetAt: new Date(3_600_000).toISOString() }, as(worker))+ return { f, lead, group, worker, other, as, task, limit }+ }++ it('lets the Lead hand lost work to another agent without first deciding about the lost one', () => {+ const { f, lead, group, other, as, task, limit } = lostFixture()+ limit()+ expect(task().assignment!.status).toBe('lost')+ f.run({ type: 'work.assign', conversationId: group, agentId: other, ...via }, as(lead), decisionIn(group))+ expect(task().assignment).toMatchObject({ agentId: other, status: 'working', leaseUntil: 1000 + 5 * 60_000 })+ })++ it('leaves the lost agent undecided when the Lead cancels lost work, without telling it twice or blocking the next assignment', () => {+ const { f, lead, group, worker, other, as, task, limit } = lostFixture()+ limit()+ const cancelled = f.run({ type: 'work.cancel', conversationId: group, assignmentId: task().assignment!.id, reason: 'Not needed' }, as(lead))+ expect(task().assignment!.status).toBe('cancelled')+ expect(cancelled.messages[0]!.recipients).toEqual([])+ expect(f.state.agents.find(a => a.id === worker)!.workDecision).toBeUndefined()+ // The Lead's next assignment in the project goes to a healthy worker without deciding about the dead one first.+ const next = f.group()+ f.run({ type: 'work.assign', conversationId: next, agentId: other, ...via }, as(lead), decisionIn(next))+ expect(f.state.conversations.find(c => c.id === next)!.assignment).toMatchObject({ agentId: other, status: 'working' })+ })++ it('renews the lease on the worker\'s own post in its task\'s group, not on anyone else\'s', () => {+ const { f, lead, group, worker, as, task } = lostFixture()+ task().assignment!.leaseUntil = 0+ f.run({ type: 'message.send', conversationId: group, text: 'Halfway.', replyTo: null, recipientIds: [] }, as(lead))+ expect(task().assignment!.leaseUntil).toBe(0)+ f.run({ type: 'message.send', conversationId: group, text: 'Halfway.', replyTo: null, recipientIds: [] }, as(worker))+ expect(task().assignment).toMatchObject({ leaseUntil: 1000 + 5 * 60_000, progressAt: 1000 })+ })++ it('keeps the lost worker marked when the Lead cancels its task or hands it to another agent (final review, Important 3)', () => {+ const marked = { conversationId: expect.any(String), assignmentId: expect.any(String), reason: expect.stringContaining('usage limit'), at: 1000 }+ for (const close of ['cancel', 'reassign'] as const) {+ const { f, lead, group, worker, other, as, task, limit } = lostFixture()+ limit()+ const lostId = task().assignment!.id+ expect(f.state.agents.find(a => a.id === worker)!.lostTask).toEqual({ ...marked, conversationId: group, assignmentId: lostId })+ if (close === 'cancel') f.run({ type: 'work.cancel', conversationId: group, assignmentId: lostId, reason: 'Not needed' }, as(lead))+ else f.run({ type: 'work.assign', conversationId: group, agentId: other, ...via }, as(lead), decisionIn(group))+ expect(f.state.agents.find(a => a.id === worker)!.lostTask).toEqual({ ...marked, conversationId: group, assignmentId: lostId })+ }+ })++ it('clears the mark once the worker finishes a new task, but not when the Lead merely assigns it one', () => {+ const { f, lead, group, worker, as, task, limit } = lostFixture()+ limit()+ f.run({ type: 'work.cancel', conversationId: group, assignmentId: task().assignment!.id, reason: 'Not needed' }, as(lead))+ const next = f.group()+ const assignmentId = f.run({ type: 'work.assign', conversationId: next, agentId: worker, ...via }, as(lead), decisionIn(next)).result.assignmentId as string+ expect(f.state.agents.find(a => a.id === worker)!.lostTask).toBeDefined()+ f.run({ type: 'work.status', conversationId: next, assignmentId, status: 'review', result: 'Ready' }, as(worker))+ expect(f.state.agents.find(a => a.id === worker)!.lostTask).toBeDefined()+ const checkId = f.state.conversations.find(c => c.id === next)!.checks[0]!.id+ f.run({ type: 'work.check', conversationId: next, assignmentId, checkId, passed: true, evidence: 'Verified' })+ f.run({ type: 'work.status', conversationId: next, assignmentId, status: 'done', result: 'Delivered' }, as(worker))+ expect(f.state.agents.find(a => a.id === worker)!.lostTask).toBeUndefined()+ })++ it('clears the mark when a person assigns the worker by hand', () => {+ const { f, lead, group, worker, as, task, limit } = lostFixture()+ limit()+ f.run({ type: 'work.cancel', conversationId: group, assignmentId: task().assignment!.id, reason: 'Not needed' }, as(lead))+ const next = f.group()+ f.run({ type: 'work.assign', conversationId: next, agentId: worker })+ expect(f.state.agents.find(a => a.id === worker)!.lostTask).toBeUndefined()+ })++ it('clears the mark when the worker\'s terminal is replaced (Change agent)', () => {+ const { f, group, worker, as, limit } = lostFixture()+ limit()+ f.run({ type: 'agent.rebind', agentId: worker, machineId: 'host', projectId: 'lead', previousHarnessId: 'worker', harnessId: 'worker-2', configuration: config }, as(worker))+ expect(f.state.agents.find(a => a.id === worker)).toMatchObject({ harnessId: 'worker-2' })+ expect(f.state.agents.find(a => a.id === worker)!.lostTask).toBeUndefined()+ expect(f.state.conversations.find(c => c.id === group)!.lostAttempt).toMatchObject({ agentId: worker })+ })++ it('does not lose work a Lead holds: Leads are not covered here', () => {+ const { f, lead, as } = lostFixture()+ const own = f.group()+ f.run({ type: 'work.assign', conversationId: own, agentId: lead })+ f.run({ type: 'agent.alert', agentId: lead, alert: 'limit', active: true }, as(lead))+ expect(f.state.conversations.find(c => c.id === own)!.assignment!.status).toBe('working')+ })+})diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex e56b6ab1e..9fc274e86 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -12,8 +12,10 @@ import { agentTarget, askedInSchema, broken, MAX_RULES, RULE_MESSAGE_MS, ruleSchimport { MAX_ATTACHMENTS, type Attachment } from './attachments.js'import { checkMentions, MAX_MENTIONS, type MentionTarget } from './mentions.js'import { TERMINAL_KEYS, terminalAlert, terminalRequest, terminalResult, type TerminalRequest } from './terminal.js'+import { loseTasks, renewLease, renewOwnTask } from './liveness.js'import { credentialResult, redactCredentials, type CredentialKind } from './credentials.js'-import { agentKind, agentProjectId, agentSetRole, deleteProject, groupProject, inviteLanding, ledProject, manageProject, MAX_ROLES, mutableProjects, placeRules, projectMembers, projectOf, projectRules, projectsOf, readAgent, readConversation, readProject, roleVersion, sameProject, sharedWithLeads, SKILL_SET_NAMES, skillSetOf, type ProjectRole, type RoleKind, type SwarmProject } from './projects.js'+import { dirtyGroups, reportGroups, summarize } from './projectUpdates.js'+import { agentKind, agentProjectId, audienceOf, agentSetRole, deleteProject, markConfidential, requireSingleRegistration, groupProject, inviteLanding, ledProject, manageProject, MAX_ROLES, mutableProjects, placeRules, projectMembers, projectOf, projectRules, projectsOf, readAgent, readConversation, readProject, roleVersion, sameProject, sharedWithLeads, SKILL_SET_NAMES, skillSetOf, type ProjectRole, type RoleKind, type SwarmProject } from './projects.js'const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)const title = z.string().trim().min(1).max(160)@@ -79,18 +81,25 @@ export const commandSchema = z.discriminatedUnion('type', [z.object({ type: z.literal('project.delete'), projectId: id }).strict(),z.object({ type: z.literal('project.sharing'), projectId: id, visibility: z.enum(['public', 'private']), memberIds: z.array(id).max(200) }).strict(),z.object({ type: z.literal('project.cadence'), projectId: id, minutes: z.union([z.literal(1), z.literal(5), z.literal(15), z.literal(30)]) }).strict(),- z.object({ type: z.literal('project.report'), projectId: id, throughRevision: z.number().int().nonnegative().safe(), text: text.nullable() }).strict(),+ // `through`: each conversation's sequence the Lead read, as its wake-up names them. `throughRevision` is the tab revision a+ // wake-up from before the store by parts named; it is accepted only up to that split (projectUpdates.ts).+ z.object({ type: z.literal('project.report'), projectId: id, through: z.record(id, z.number().int().nonnegative().safe()).optional(),+ throughRevision: z.number().int().nonnegative().safe().optional(), text: text.nullable() }).strict()+ .refine(c => (c.through === undefined) !== (c.throughRevision === undefined), 'Acknowledge with through, the map your wake-up names.'),z.object({ type: z.literal('project.repository'), projectId: id, repositoryUrl }).strict(),z.object({ type: z.literal('project.skills'), projectId: id, mode: z.enum(['default', 'orchestration', 'custom']), askedIn: askedInSchema.optional() }).strict(),z.object({ type: z.literal('project.roles.create'), projectId: id, roles: roleSet }).strict(),z.object({ type: z.literal('project.role.set'), projectId: id, role }).strict(),z.object({ type: z.literal('project.role.remove'), projectId: id, roleId }).strict(),z.object({ type: z.literal('project.roles.reset'), projectId: id, roles: roleSet }).strict(),- z.object({ type: z.literal('conversation.create'), projectId: id.optional(), title, brief: z.string().trim().max(8000).optional(), task: task.optional(), reviewOf: id.optional(), checks: z.array(check).max(40) }).strict()+ // `audience`: a private conversation that only these people and the project's Lead read (projects.ts canReadGroup).+ z.object({ type: z.literal('conversation.create'), projectId: id.optional(), title, brief: z.string().trim().max(8000).optional(), task: task.optional(), reviewOf: id.optional(), checks: z.array(check).max(40),+ audience: z.object({ personIds: z.array(id).max(200) }).strict().optional() }).strict().refine(c => c.task !== undefined || c.brief !== undefined, 'Provide a task or brief.').refine(c => !c.task || renderWorkTask(c.task).length <= 8000, 'Keep the rendered task within 8,000 characters.'),z.object({ type: z.literal('conversation.rename'), conversationId: id, title }).strict(),z.object({ type: z.literal('conversation.archive'), conversationId: id, archived: z.boolean() }).strict(),+ z.object({ type: z.literal('conversation.audience'), conversationId: id, personIds: z.array(id).max(200) }).strict(),z.object({ type: z.literal('agent.add'), conversationId: id, machineId: id, harnessId: id, name: title, configuration, lead: z.boolean(), project: project.optional(), roleId: roleId.optional(), initialMessage: text.optional() }).strict(),z.object({ type: z.literal('agent.start'), request: startRequestSchema, routeDecisionId: id.optional(), overrideReason: reason.optional() }).strict(),z.object({ type: z.literal('agent.startDispatch'), startId: id }).strict(),@@ -193,6 +202,10 @@ export function withoutCredentials(command: Command, removed: CredentialKind[]):export interface CommandContext {operationId: stringnow: number+ /** For a terminal request: its agent's session is confidential in some Swarm, read by the store (confidential.ts). */+ confidentialSession?: boolean+ /** For a command that registers a session or can make one confidential: the other Swarms' registrations (confidential.ts). */+ registrations?: import('./projects.js').OtherRegistrations/** Read from host ownership/access records by the store, never copied from the request. */contribution?: { machineOwnerId: string; contributorId: string; hostGrant?: string | null/** A Harness Team account's machine: the Mac it lives on, from its account row (machines.ts ContributedMachine). */@@ -448,6 +461,10 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaresult.messageId = operationId}/** An agent starts or assigns only what the route chose; a person may still do either by hand. */+ /** A private conversation is chat only (design section 4.8). */+ const chatOnly = (conversationId: string) => {+ if (state.conversations.find(c => c.id === conversationId)?.audience) fail('AUDIENCE_CHAT_ONLY', 'A private conversation is chat only.', 400)+ }const routed = (routeDecisionId?: string) => {if (actor.kind === 'agent' && !routeDecisionId) fail('ROUTE_REQUIRED', 'Route this task first, then start or assign the pick with its routeDecisionId.', 400)}@@ -619,6 +636,13 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma}}+ /** After its task was lost, its old agent's status and checks for that attempt are refused, even once it is reassigned. */+ const fenceLost = (group: Conversation, assignmentId: string) => {+ if (actor.kind === 'agent' && group.lostAttempt?.id === assignmentId && group.lostAttempt.agentId === actor.agentId) {+ fail('ASSIGNMENT_LOST', 'This task was lost and moved on, so your status and results for it are no longer accepted. Stop working on it.')+ }+ }+/** Changing or clearing the Lead of a project's Lead conversation would let it be stopped next. */const keepLead = (group: Conversation, next: string | null) => {if (group.leadId && group.leadId !== next && group.id === groupProject(state, group).leadConversationId) protectLead(state, group.leadId)@@ -627,7 +651,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaswitch (command.type) {case 'agent.screen':case 'agent.input': {- const { effect, message, removed: typed } = terminalRequest(state, actor, sender, operationId, context.now, command)+ const { effect, message, removed: typed } = terminalRequest(state, actor, sender, operationId, context.now, command, context.confidentialSession)effects.terminal = effectresult.requestId = operationIdif (message) effects.messages.push(message)@@ -640,14 +664,17 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commabreakcase 'agent.alert': {effects.messages.push(...terminalAlert(state, actor, sender, operationId, context.now, command))+ if (command.alert === 'limit' && command.active) effects.messages.push(...loseTasks(state, context.now, worker => worker.id === command.agentId))break}case 'project.report': {const project = readProject(state, actor, command.projectId)const group = conversation(state, project.leadConversationId)if (actor.kind !== 'agent' || group.leadId !== actor.agentId) fail('LEAD_REQUIRED', 'The project lead writes its progress updates.', 403)- if (project.progress) project.progress.summarizedRevision = Math.max(project.progress.summarizedRevision,- Math.min(command.throughRevision, project.progress.dirtyRevision))+ if (command.throughRevision !== undefined && command.throughRevision > (state.sequenceBase ?? 0)) {+ fail('THROUGH_REQUIRED', 'Acknowledge with through, the map of workgroups your latest wake-up names.', 400)+ }+ summarize(state, project, command.through ?? Object.fromEntries(reportGroups(state, project).map(g => [g.id, command.throughRevision!])))if (command.text) message(group.id, command.text, [], null, { kind: 'project-report' })break}@@ -920,11 +947,18 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma(actor.kind === 'agent' ? agentProjectId(state, agent(state, actor.agentId)) : 'lead'))controls(state, actor, project.leadConversationId)if (state.paused) fail('PAUSED', 'New work is paused in this Super Tab.')- if (actor.kind === 'agent' && (!brief || !command.checks.length)) {+ if (command.audience) {+ // A private conversation is chat only: no task, checks or review, so private work never reaches other Leads.+ if (command.task || command.checks.length || command.reviewOf) fail('AUDIENCE_CHAT_ONLY', 'A private conversation is chat only.', 400)+ if (actor.kind === 'person' && !command.audience.personIds.includes(actor.userId)) {+ fail('AUDIENCE_SELF', 'Open a private conversation with yourself in it.', 403)+ }+ } else if (actor.kind === 'agent' && (!brief || !command.checks.length)) {fail('BRIEF_REQUIRED', 'Delegated work needs a brief and acceptance checks.', 400)}const leadId = conversation(state, project.leadConversationId).leadIdif (command.reviewOf) {+ chatOnly(command.reviewOf)const reviewed = open(state, command.reviewOf)if (reviewed.id === project.leadConversationId || reviewed.reviewOf || groupProject(state, reviewed).id !== project.id) {fail('REVIEW_TARGET', 'A review group reviews one build group of the same project.', 400)@@ -932,9 +966,11 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: CommarequireCustomRole(project, 'reviewer')}const number = nextConversationNumber(state)+ state.groupCounter = numberstate.conversations.push({ id: operationId, ...(state.projects ? { projectId: project.id } : {}),number, title: command.title, leadId, agentIds: leadId ? [leadId] : [],archived: false, brief, ...(command.task ? { task: command.task } : {}), ...(command.reviewOf ? { reviewOf: command.reviewOf } : {}),+ ...(command.audience ? { audience: audienceOf(state, project, command.audience.personIds) } : {}),assignment: null, lastMessageSequence: 0,checks: command.checks.map((c, i) => ({ ...c, id: stableId(operationId, String(i)), evidence: null, passedBy: null })),})@@ -947,12 +983,23 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commacontrols(state, actor, command.conversationId)open(state, command.conversationId).title = command.titlebreak+ case 'conversation.audience': {+ // Who may read it already passed (readConversation): only its listed people and the project's Lead get here.+ const group = open(state, command.conversationId)+ if (!group.audience) fail('AUDIENCE_FIXED', 'A shared conversation stays shared. Open a private conversation instead.', 400)+ group.audience = audienceOf(state, groupProject(state, group), command.personIds)+ break+ }case 'conversation.archive': {controls(state, actor, command.conversationId)const group = conversation(state, command.conversationId)if (group.id === groupProject(state, group).leadConversationId) fail('LEAD_CONVERSATION', 'The Lead conversation stays available.')if (command.archived && activeWork(group)) fail('WORK_ACTIVE', 'Resolve the active assignment before archiving this conversation.')group.archived = command.archived+ // Archived by hand, it leaves the active set until it is reopened (spec, Archive), once its reports are acknowledged:+ // until then the sweep leaves it in the active set, where the report check sees it (design section 3.6).+ if (command.archived && !dirtyGroups(state, groupProject(state, group)).includes(group)) group.dormant = true+ else delete group.dormantbreak}case 'agent.add': {@@ -1012,6 +1059,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commabreak}case 'agent.start': {+ chatOnly(command.request.conversationId)controls(state, actor, command.request.conversationId)routed(command.routeDecisionId)requireWorkerDecisions(state, actor, open(state, command.request.conversationId))@@ -1084,6 +1132,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: CommaadmitMachineStart(state, start.request, context.now, start, context.teamMachines)if (start.dispatched || start.error || start.harnessId) fail('START_CLAIMED', 'This native start was already requested. Read its creation status; do not start another.')start.dispatched = true+ start.dispatchedAt = context.nowbreak}if (command.type === 'agent.startSettled') {@@ -1151,6 +1200,8 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma}target.harnessId = command.harnessIdtarget.replacement = { previousHarnessId: command.previousHarnessId, harnessId: command.harnessId }+ // A new terminal is not the session that lost its task.+ delete target.lostTasktarget.configuration = command.configurationtarget.configurationVersion = operationIdif (command.startedSession) target.startedSession = command.startedSession@@ -1248,6 +1299,9 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commagroup.agentIds = group.agentIds.filter(id => id !== command.agentId)if (group.leadId === command.agentId) group.leadId = null} else {+ if (group.audience && ledProject(state, member.id)?.id !== groupProject(state, group).id) {+ fail('AUDIENCE_LEAD_ONLY', 'A private conversation holds only the Lead among agents.', 403)+ }// A Reviewer added to a group is handed its review, as an assignment hands a Builder its task.if (reviewer) requireTeamWork(state, member.machineId, member.contributorId, groupProject(state, group), context.now, context.teamMachines)ruled(agentTarget(state, member), group.id, `${who} added ${member.name}`)@@ -1329,6 +1383,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma}// The transcript still accepts a human message while the lead is unavailable. The UI can say why no delivery was created.message(group.id, command.text, recipients, command.replyTo, command.agentOnly ? AGENT_ONLY : undefined, attachments, mentions)+ if (actor.kind === 'agent') renewOwnTask(group, actor.agentId, context.now)break}case 'delivery.resolve': {@@ -1351,6 +1406,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commabreak}case 'route.record': {+ chatOnly(command.conversationId)controls(state, actor, command.conversationId)// A teammate's work runs only on Team machines: candidates elsewhere leave the decision for its exclusions, with// why, so the Lead and people see it. A pick there is refused; a current CLI already leaves those machines out.@@ -1418,12 +1474,13 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commabreak}case 'work.define': {+ chatOnly(command.conversationId)controls(state, actor, command.conversationId)const group = open(state, command.conversationId)if (activeWork(group)) fail('WORK_ACTIVE', 'Finish or stop the current assignment before changing its acceptance checks.')if (group.assignment) {const worker = state.agents.find(a => a.id === group.assignment!.agentId)- if (worker && !worker.workDecision) finishWorker(state, worker.id)+ if (worker && !worker.workDecision && group.assignment.status !== 'lost') finishWorker(state, worker.id)}rememberAttempt(group)group.assignment = null@@ -1435,6 +1492,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commabreak}case 'work.assign': {+ chatOnly(command.conversationId)const target = agent(state, command.agentId)if (state.starts?.some(s => s.poolGeneration && !s.poolSettled && s.request.machineId === target.machineId && s.harnessId === target.harnessId)) {fail('START_PENDING', 'Wait for the host to finish this agent’s launch and model selection.')@@ -1458,6 +1516,8 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaif (state.conversations.some(c => activeWork(c) && c.assignment?.agentId === worker.id)) fail('AGENT_BUSY', 'This agent already owns an active assignment.')delete worker.workDecisiondelete worker.releaseId+ // A person's own pick takes a worker that lost its task back into routing (model.ts lostTask); a Lead's does not.+ if (actor.kind === 'person') delete worker.lostTaskfor (const reviewer of state.agents) {if (agentRole(reviewer) === 'reviewer' && group.agentIds.includes(reviewer.id) && reviewer.workDecision !== 'stop') delete reviewer.workDecision}@@ -1465,6 +1525,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: CommarememberAttempt(group)group.assignment = { id: operationId, agentId: worker.id, status: 'working', configuration: structuredClone(worker.configuration),execution: { machineId: worker.machineId, harnessId: worker.harnessId, machineOwnerId: worker.machineOwnerId }, result: null }+ renewLease(group.assignment, context.now)group.checks.forEach(c => { c.evidence = null; c.passedBy = null })result.assignmentId = operationIdlet routeNote: { decisionId: string; text: string } | null = null, personChose = false@@ -1488,6 +1549,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commacase 'work.status': {const group = open(state, command.conversationId)const assignment = group.assignment+ fenceLost(group, command.assignmentId)if (!assignment || assignment.id !== command.assignmentId) fail('STALE_ASSIGNMENT', 'This is no longer the active assignment.')if (!activeWork(group)) fail('ATTEMPT_CLOSED', 'Assign a new attempt to continue this work.')if (actor.kind === 'agent' && actor.agentId !== assignment.agentId && actor.agentId !== group.leadId) fail('FORBIDDEN', 'Only the assigned agent or coordinating lead can update this work.', 403)@@ -1500,6 +1562,8 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaassignment.status = command.statusassignment.result = command.resultif (['done', 'stopped'].includes(command.status)) finishWorker(state, assignment.agentId, group)+ // Finished work shows the worker recovered from a task it lost before.+ if (command.status === 'done') delete state.agents.find(a => a.id === assignment.agentId)?.lostTaskif (changed) {const label = { working: 'Working', needs_human: 'Needs a human', blocked: 'Stuck', review: 'Ready for review', done: 'Done', stopped: 'Stopped' }[command.status]const lead = group.leadId@@ -1511,6 +1575,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma(actor.kind !== 'agent' || id !== actor.agentId) && state.agents.some(a => a.id === id && agentRole(a) === 'reviewer' && a.workDecision !== 'stop'))message(group.id, `${label}${command.result ? `\n\n${command.result}` : ''}`, [...(tellLead ? [lead] : []), ...reviewers], null, SYSTEM_ROW)}+ if (actor.kind === 'agent') renewOwnTask(group, actor.agentId, context.now)break}case 'work.cancel': {@@ -1524,18 +1589,21 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma}// A retry after the cancel keeps the first reason and tells the worker once.if (assignment.status === 'cancelled') break- if (!activeWork(group)) fail('ATTEMPT_CLOSED', 'This attempt has already ended.')+ const lost = assignment.status === 'lost'+ if (!activeWork(group) && !lost) fail('ATTEMPT_CLOSED', 'This attempt has already ended.')// A removed worker (reconciling) can never confirm a stop, so this is the only way to close its task; nobody is left to tell.- const gone = assignment.status === 'reconciling'+ // A lost task's agent was told already that its task moved, and does not wait for a decision.+ const gone = assignment.status === 'reconciling' || lostassignment.status = 'cancelled'assignment.result = command.reason- finishWorker(state, assignment.agentId, group)+ if (!lost) finishWorker(state, assignment.agentId, group)message(group.id, `${isLead ? 'The Lead' : 'The tab owner'} cancelled this task: ${command.reason.replace(/[.\s]+$/, '')}.${gone ? '' : ' Stop working on it.'}`,gone ? [] : [assignment.agentId], null, SYSTEM_ROW)break}case 'work.check': {const group = open(state, command.conversationId)+ fenceLost(group, command.assignmentId)if (!group.assignment || group.assignment.id !== command.assignmentId) fail('STALE_ASSIGNMENT', 'This is no longer the active assignment.')if (!activeWork(group)) fail('ATTEMPT_CLOSED', 'Assign a new attempt before changing its acceptance evidence.')if (group.assignment.status === 'reconciling') fail('RECONCILING', 'Reconcile the previous assignment before continuing.')@@ -1544,6 +1612,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaif (check.independent && actor.kind === 'agent' && actor.agentId === group.assignment.agentId) fail('INDEPENDENT_REVIEW', 'Another agent or a person must perform this check.')check.evidence = command.evidencecheck.passedBy = command.passed ? actorKey(actor) : null+ if (actor.kind === 'agent') renewOwnTask(group, actor.agentId, context.now)break}}@@ -1556,9 +1625,10 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Commaif (!acknowledged && !state.agents.some(a => a.id === target.id)) fail('STOP_REQUESTED', 'Wait for the execution host to finish stopping its workers before withdrawing them.')}syncLeads(state)- // MongoDB limits a document to 16 MiB. Leave room for indexes and metadata, and refuse before losing state.+ if (context.registrations) requireSingleRegistration(original, state, context.registrations)+ markConfidential(state)assignAgentDisplayNames(state.agents)- if (Buffer.byteLength(JSON.stringify(state)) > 8 * 1024 * 1024) fail('TAB_TOO_LARGE', 'This Super Tab has reached its metadata limit.', 413)+ // The size limit is per stored part now (parts/commit.ts PART_LIMIT_BYTES); a Swarm as a whole has none.// Every row this command writes, whatever its words came from: an older message resent, a rule written before this check.for (const draft of effects.messages) {const clean = redactCredentials(draft.text)diff --git a/backend/src/superTabs/confidential.ts b/backend/src/superTabs/confidential.tsnew file mode 100644index 000000000..4700d545d--- /dev/null+++ b/backend/src/superTabs/confidential.ts@@ -0,0 +1,61 @@+import type { Prisma } from '@prisma/client'+import type { Agent, SuperTabState } from './model.js'+import { loadActive, reassemble } from './parts/index.js'+import { confidentialSession, sessionKey, type OtherRegistrations } from './projects.js'+import { bindSession, sessionRecordId } from './sessionScope.js'++type Transaction = Prisma.TransactionClient++/**+ * The native sessions (an agent id is one machine's harness, the same in every Swarm) among `agentIds` that are confidential+ * in any Swarm (Lead ruling, final review Critical 1): marked once a Lead or a private conversation's member (projects.ts+ * markConfidential), or, in a part written before that mark, a Lead or private member now. A confidential session is+ * watched by nobody but its machine's person, whichever Swarm or share asks.+ */+export async function confidentialSessions(tx: Transaction, agentIds: string[]): Promise<Set<string>> {+ const found = new Set<string>()+ if (!agentIds.length) return found+ const rows = await tx.swarmAgent.findMany({ where: { key: { in: [...new Set(agentIds)] }, deleted: false }, select: { tabId: true, key: true, data: true } })+ const unmarked = new Map<string, string[]>()+ for (const row of rows) {+ if ((row.data as unknown as Agent).confidential) found.add(row.key)+ else unmarked.set(row.tabId, [...unmarked.get(row.tabId) ?? [], row.key])+ }+ for (const [tabId, keys] of unmarked) {+ const pending = keys.filter(key => !found.has(key))+ if (!pending.length) continue+ const state = reassemble(await loadActive(tx, tabId, { agentIds: pending }))+ for (const target of state.agents) if (pending.includes(target.id) && confidentialSession(state, target)) found.add(target.id)+ }+ return found+}++/** The other Swarms' registrations a command that registers a session or makes one confidential is checked against+ * (projects.ts requireSingleRegistration): every session of these machines registered elsewhere, and which of `check`+ * are confidential there (marked, or a Lead or private member now in a part written before the mark). */+export async function otherRegistrations(tx: Transaction, state: SuperTabState, check: Array<{ machineId: string; harnessId: string }>): Promise<OtherRegistrations> {+ const machineIds = [...new Set([...state.agents.map(a => a.machineId), ...check.map(c => c.machineId)])]+ const rows = await tx.swarmAgent.findMany({ where: { machineId: { in: machineIds }, deleted: false, tabId: { not: state.id } }, select: { tabId: true, key: true, data: true } })+ const registered = new Set<string>(), confidential = new Set<string>(), wanted = new Set(check.map(c => sessionKey(c.machineId, c.harnessId)))+ const unmarked = new Map<string, Agent[]>()+ for (const row of rows) {+ const target = row.data as unknown as Agent, key = sessionKey(target.machineId, target.harnessId)+ registered.add(key)+ if (!wanted.has(key)) continue+ if (target.confidential) confidential.add(key)+ else unmarked.set(row.tabId, [...unmarked.get(row.tabId) ?? [], target])+ }+ for (const [tabId, targets] of unmarked) {+ const there = reassemble(await loadActive(tx, tabId, { agentIds: targets.map(t => t.id) }))+ for (const target of there.agents) if (targets.some(t => t.id === target.id) && confidentialSession(there, target)) confidential.add(sessionKey(target.machineId, target.harnessId))+ }+ return { registered, confidential }+}++/** Records on the native session's shared record (the one each registration writes) that it became confidential. A+ * registration of the same session committing in another Swarm meanwhile then conflicts with this write, so one of the+ * two retries and is refused (projects.ts requireSingleRegistration). */+export async function recordConfidential(tx: Transaction, state: SuperTabState, target: Agent, now: number): Promise<void> {+ await bindSession(tx, state, target, now)+ await tx.superTabSessionScope.update({ where: { id: sessionRecordId(state, target) }, data: { confidential: true } })+}diff --git a/backend/src/superTabs/liveness.test.ts b/backend/src/superTabs/liveness.test.tsnew file mode 100644index 000000000..84c950231--- /dev/null+++ b/backend/src/superTabs/liveness.test.ts@@ -0,0 +1,57 @@+import { describe, expect, it } from 'vitest'+import type { Assignment, SuperTabState } from './model.js'+import { LEASE_MS, QUIET_RUNNING_MS, sweepLiveness } from './liveness.js'+import { split } from './parts/index.js'++const MINUTE = 60_000+const assignment = (patch: Partial<Assignment> = {}): Assignment => ({ id: 'a1', agentId: 'w', status: 'working', result: null,+ configuration: { engine: 'codex', model: null, effort: null, contextWindow: null, engineVersion: null },+ execution: { machineId: 'm', harnessId: 'h', machineOwnerId: 'o' }, ...patch })+/** A worker on machine `m` with session `h` holding `task`; the machine's last report, when given, listed it running. */+const swarm = (task: Assignment, report?: { receivedAt: number; harnessProgress?: Record<string, number> }, lastActivityAt?: number) => ({ id: 't',+ agents: [{ id: 'w', machineId: 'm', harnessId: 'h', machineOwnerId: 'o', contributorId: 'p', membershipGeneration: 'g', name: 'Worker', configuration: task.configuration }],+ people: [{ id: 'p', email: '[email protected]', role: 'owner', generation: 'g' }],+ machines: report ? [{ machineId: 'm', name: 'Mac', observation: { runningHarnessIds: ['h'], stoppedHarnessIds: [], ...report } }] : [],+ conversations: [{ id: 'lead', title: 'Lead', leadId: null, agentIds: [], archived: false, brief: '', checks: [], assignment: null, lastMessageSequence: 0 }, { id: 'g1', title: 'Task', leadId: null, agentIds: ['w'], archived: false, brief: 'Do it', checks: [], assignment: task, lastMessageSequence: 0,+ ...(lastActivityAt === undefined ? {} : { lastActivityAt: new Date(lastActivityAt).toISOString() }) }],+} as unknown as SuperTabState)+const status = (state: SuperTabState, now: number) => (sweepLiveness(state, now), state.conversations[1]!.assignment!)++describe('the lease on a worker\'s task', () => {+ it('runs 30 minutes from the last progress a report showed for a running session, and is never written by the report', () => {+ const progress = 1_000_000, received = progress + 30 * MINUTE+ const lastRenewal = progress + QUIET_RUNNING_MS - LEASE_MS+ // Its own lease ran out long ago; the reports keep it until 5 minutes after the last one that still had fresh progress.+ const kept = swarm(assignment({ leaseUntil: 1 }), { receivedAt: lastRenewal + LEASE_MS, harnessProgress: { h: progress } })+ expect(status(kept, lastRenewal + LEASE_MS)).toMatchObject({ status: 'working', leaseUntil: 1 })+ const lost = swarm(assignment({ leaseUntil: 1 }), { receivedAt: lastRenewal + LEASE_MS + 1, harnessProgress: { h: progress } })+ expect(status(lost, lastRenewal + LEASE_MS + 1)).toMatchObject({ status: 'lost', lost: { reason: 'no progress for 30 minutes' } })+ // A report that has no progress for the session renews nothing.+ expect(status(swarm(assignment({ leaseUntil: 1 }), { receivedAt: received, harnessProgress: {} }), received).status).toBe('lost')+ })++ it('is renewed by a report listing the session running when the host sends no progress at all (an older host)', () => {+ expect(status(swarm(assignment({ leaseUntil: 1 }), { receivedAt: 50 * MINUTE }), 50 * MINUTE).status).toBe('working')+ })++ it('runs an assignment from before leases from its group\'s last message, without writing it', () => {+ const task = assignment()+ expect(status(swarm(task, undefined, 7000), 7000 + LEASE_MS)).toMatchObject({ status: 'working' })+ expect(task.leaseUntil).toBeUndefined()+ expect(status(swarm(task, undefined, 7000), 7000 + LEASE_MS + 1)).toMatchObject({ status: 'lost', lost: { reason: 'no progress seen' } })+ })+})++describe('a worker whose task is lost', () => {+ it('is marked lost in the same write that loses its task, so routing keeps it out after a cancel or reassignment', () => {+ const state = swarm(assignment({ leaseUntil: 1 })), now = 1 + LEASE_MS + 1+ const parts = () => split(structuredClone(state), { tabId: 't', version: 1, now: 0 })+ const before = parts()+ sweepLiveness(state, now)+ const after = parts()+ expect(after.agents[0]!.data).toMatchObject({ lostTask: { conversationId: 'g1', assignmentId: 'a1', reason: 'no progress seen', at: now } })+ // commitParts writes every part whose data changed, all in one transaction: the worker's with the task's.+ expect(after.agents[0]!.data).not.toEqual(before.agents[0]!.data)+ expect(after.groups.find(g => g.key === 'g1')!.data).not.toEqual(before.groups.find(g => g.key === 'g1')!.data)+ })+})diff --git a/backend/src/superTabs/liveness.ts b/backend/src/superTabs/liveness.tsnew file mode 100644index 000000000..e13194f62--- /dev/null+++ b/backend/src/superTabs/liveness.ts@@ -0,0 +1,163 @@+import { activeWork, stableId, type Agent, type Assignment, type Author, type Conversation, type MessageDraft,+ type SuperTabState } from './model.js'+import { agentDisplayName } from './agentNames.js'+import { leadOf, toLead } from './terminal.js'++// Work never sits with a dead owner (design: "A Swarm that never stops", 2026-10-26). A worker's active assignment is held+// by a lease that its progress renews. A dead, stalled or limited worker loses it within minutes: the assignment becomes+// lost, its agent is fenced off, and the Lead is woken to hand it on. Leads are not covered here.+//+// The agent's own status, checks and posts renew the lease stored on the assignment. Its machine's reports renew it too,+// but are read from the report its machine part keeps (written on every report anyway), never written into the group: a+// group written once a minute per task would wake every reader of the Swarm.++/** How long an assignment stays its agent's without progress. */+export const LEASE_MS = 5 * 60_000+/** A session its machine still lists as running may go this long without a screen or transcript change before its task is+ * lost: a long command that prints nothing (a test suite) is still work (Product Manager, 2026-10-26). Hard failures —+ * offline, stopped, a usage limit — stay immediate. */+export const QUIET_RUNNING_MS = 30 * 60_000+/** A report renews the lease while the session's last progress is this recent, so its lease ends QUIET_RUNNING_MS after it. */+const PROGRESS_FRESH_MS = QUIET_RUNNING_MS - LEASE_MS+/** A machine silent this long has lost its work. */+const OFFLINE_LOST_MS = 2 * 60_000+/** A dispatched start not running this long after has failed. */+const START_RUN_MS = 3 * 60_000+/** Any machine's report runs the time checks for its Swarm at most this often. */+export const SWEEP_EVERY_MS = 30_000++const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`+const machineName = (state: SuperTabState, machineId: string) => state.machines?.find(m => m.machineId === machineId)?.name ?? 'its machine'+/** A sweep runs inside a machine's report and the Lead's poll, so it never fails on an agent whose membership changed:+ * it writes as that agent without checking it, and a delivery to an agent no longer shared is not created. */+const writtenBy = (state: SuperTabState, writer: Agent): Author => ({ kind: 'agent', id: writer.id, name: writer.name,+ displayName: agentDisplayName(state.agents, writer.id), membershipGeneration: writer.membershipGeneration })+const reachable = (state: SuperTabState, row: MessageDraft): MessageDraft => ({ ...row, recipients: row.recipients.filter(id => {+ const target = state.agents.find(a => a.id === id)+ return !!target && state.people.find(p => p.id === target.contributorId)?.generation === target.membershipGeneration+}) })++/** The agent's own progress (an assignment, a status, a check, a post) renews the lease stored on its assignment. */+export function renewLease(assignment: Assignment, now: number): void {+ assignment.leaseUntil = now + LEASE_MS+ assignment.progressAt = now+}++/** The active assignments held by workers, not by a Lead, and not already being reconciled after their agent left. */+function workerTasks(state: SuperTabState): Array<{ group: Conversation; assignment: Assignment; worker: Agent }> {+ return state.conversations.filter(activeWork).flatMap(group => {+ const assignment = group.assignment!+ const worker = state.agents.find(a => a.id === assignment.agentId)+ if (!worker || assignment.status === 'reconciling' || state.conversations.some(c => c.leadId === worker.id)) return []+ return [{ group, assignment, worker }]+ })+}++/** The worker's own status, check or message in its task's group renews its lease. */+export function renewOwnTask(group: Conversation, agentId: string, now: number): void {+ if (activeWork(group) && group.assignment!.agentId === agentId) renewLease(group.assignment!, now)+}++/** The last time its machine's reports renewed a worker's lease: a report listing it running with recent progress renews at+ * that report, so a lease from the last report with progress P runs from P + PROGRESS_FRESH_MS at the latest.+ * A host that sends no progress at all (before harnessProgress) renews by running alone; one that stopped listing the+ * session renewed last when it went down. Undefined when no report ever showed it. */+function reportRenewedAt(state: SuperTabState, worker: Agent): number | undefined {+ const report = state.machines?.find(m => m.machineId === worker.machineId)?.observation+ if (!report) return undefined+ if (!report.runningHarnessIds.includes(worker.harnessId)) return worker.downSince ? Date.parse(worker.downSince) : undefined+ if (!report.harnessProgress) return report.receivedAt+ const progress = report.harnessProgress[worker.harnessId]+ return progress === undefined ? undefined : Math.min(report.receivedAt, progress + PROGRESS_FRESH_MS)+}++/** When a worker's lease ends: from its own last status, check or post (for an assignment from before leases, its group's+ * last message), or from its machine's reports, whichever is later. Undefined when nothing ever renewed it. */+function leaseEnd(group: Conversation, assignment: Assignment, renewed: number | undefined): number | undefined {+ const own = assignment.leaseUntil ?? (group.lastActivityAt ? Date.parse(group.lastActivityAt) + LEASE_MS : undefined)+ const reported = renewed === undefined ? undefined : renewed + LEASE_MS+ return own === undefined ? reported : reported === undefined ? own : Math.max(own, reported)+}++/** The worker's last progress any renewal saw: its own report, or a screen change its machine reported. */+function lastProgress(state: SuperTabState, worker: Agent, assignment: Assignment): number | undefined {+ const report = state.machines?.find(m => m.machineId === worker.machineId)?.observation+ const reported = report?.harnessProgress?.[worker.harnessId]+ const seen = [assignment.progressAt, reported === undefined ? undefined : Math.min(reported, report!.receivedAt)].filter((t): t is number => t !== undefined)+ return seen.length ? Math.max(...seen) : undefined+}++/** Why a worker has lost its task now, or null while it still holds it. Only a machine that has reported can be offline. */+function lostReason(state: SuperTabState, group: Conversation, worker: Agent, assignment: Assignment, now: number): string | null {+ const pool = state.machines?.find(m => m.machineId === worker.machineId)+ if (pool?.observation?.stoppedHarnessIds.includes(worker.harnessId)) return `its session on ${pool.name} stopped`+ if (pool?.observation && now - pool.observation.receivedAt > OFFLINE_LOST_MS) return `its machine ${pool.name} has been offline for 2 minutes`+ if (worker.alerting?.includes('limit') && worker.limitedUntil && Date.parse(worker.limitedUntil) > now) {+ return `it hit a usage limit until ${worker.limitedUntil.slice(11, 16)} UTC`+ }+ const end = leaseEnd(group, assignment, reportRenewedAt(state, worker))+ if (end !== undefined && now > end) {+ const progress = lastProgress(state, worker, assignment)+ return progress === undefined ? 'no progress seen' : `no progress for ${plural(Math.floor((now - progress) / 60_000), 'minute')}`+ }+ return null+}++/** Marks a worker's task lost and fences its agent. The Lead hears who, why, how long since progress and the last result;+ * the old agent hears that its task moved. Rows are written as the Lead, or as the worker when the project has none. */+function loseTask(state: SuperTabState, group: Conversation, worker: Agent, reason: string, now: number): MessageDraft[] {+ const assignment = group.assignment!+ assignment.status = 'lost'+ assignment.lost = { reason, at: now }+ group.lostAttempt = { id: assignment.id, agentId: worker.id }+ worker.lostTask = { conversationId: group.id, assignmentId: assignment.id, reason, at: now }+ const sender = writtenBy(state, leadOf(state, worker) ?? worker)+ const progress = lastProgress(state, worker, assignment)+ const since = progress === undefined ? 'unknown' : `${plural(Math.max(0, Math.floor((now - progress) / 60_000)), 'minute')} ago`+ const result = assignment.result?.replace(/[.\s]+$/, '')+ const pr = group.pullRequestUrls?.at(-1)+ const source = { kind: 'work-lost', agentId: worker.id, assignmentId: assignment.id, reason }+ const wake = `${worker.displayName ?? worker.name} lost its task "${group.title}": ${reason}. Last progress ${since}. `+ + `Last result: ${result || 'none'}.${pr && !result?.includes(pr) ? ` Pull request: ${pr}.` : ''} Assign it to another agent now, or cancel it.`+ return [...toLead(state, worker, { id: stableId('work-lost', assignment.id), conversationId: group.id, author: sender, replyTo: null, recipients: [], text: wake, source }),+ { id: stableId('work-lost', assignment.id, 'agent'), conversationId: group.id, author: sender, replyTo: null, recipients: [worker.id], source,+ text: `Your task "${group.title}" moved: ${reason}. Stop working on it; your status and results for it are no longer accepted.` }]+ .map(row => reachable(state, row))+}++/** Loses at once the tasks of the workers `which` picks that have a reason now: an agent that just reported a usage limit,+ * the agents of a machine that just reported. */+export function loseTasks(state: SuperTabState, now: number, which: (worker: Agent) => boolean = () => true): MessageDraft[] {+ return workerTasks(state).filter(t => which(t.worker)).flatMap(({ group, assignment, worker }) => {+ const reason = lostReason(state, group, worker, assignment, now)+ return reason ? loseTask(state, group, worker, reason, now) : []+ })+}++/** The machine parts a loss was judged from (offline, stopped, its reports' renewals). The write that records the loss+ * touches them, so a fresh report committed since the read makes it retry on current data instead of fencing a live worker. */+export function judgedMachines(state: SuperTabState, rows: MessageDraft[]): Array<{ kind: 'machine'; key: string }> {+ const lost = new Set(rows.flatMap(r => r.source?.kind === 'work-lost' ? [r.source.agentId as string] : []))+ const machines = new Set(state.agents.filter(a => lost.has(a.id)).map(a => a.machineId))+ return [...machines].filter(id => state.machines?.some(m => m.machineId === id)).map(key => ({ kind: 'machine' as const, key }))+}++/** The time checks, run on the Lead's poll and on any machine's report: every worker task with a reason is lost, and+ * every start dispatched over 3 minutes ago that is not running fails. */+export function sweepLiveness(state: SuperTabState, now: number): MessageDraft[] {+ return [...loseTasks(state, now), ...failStalledStarts(state, now)]+}++function failStalledStarts(state: SuperTabState, now: number): MessageDraft[] {+ return (state.starts ?? []).flatMap(start => {+ if (!start.dispatched || start.harnessId || start.error || start.dispatchedAt === undefined || now - start.dispatchedAt <= START_RUN_MS) return []+ start.error = `${machineName(state, start.request.machineId)} did not start it within 3 minutes`+ // Never a lookup that throws: these checks run inside every machine's report.+ const group = state.conversations.find(c => c.id === start.request.conversationId)+ const lead = group?.leadId ? state.agents.find(a => a.id === group.leadId) : undefined+ if (!group || !lead) return []+ return [reachable(state, { id: stableId('start-timeout', start.id), conversationId: group.id, replyTo: null,+ recipients: group.agentIds.includes(lead.id) ? [lead.id] : [], author: writtenBy(state, lead),+ text: `Could not start ${start.request.name}: ${start.error}.`, source: { kind: 'start-timeout', startId: start.id } })]+ })+}diff --git a/backend/src/superTabs/machines.test.ts b/backend/src/superTabs/machines.test.tsindex f128699e0..648ba91dc 100644--- a/backend/src/superTabs/machines.test.ts+++ b/backend/src/superTabs/machines.test.ts@@ -37,6 +37,19 @@ it('accepts the served models Builders are not offered, with why', () => {expect(machineObservationSchema.safeParse({ ...sent, refusedModels: Array(17).fill(refused) }).success).toBe(false)})+it('accepts what a machine is ready for, and a reading from before it', () => {+ const { receivedAt: _receivedAt, ...sent } = observation+ const readiness = { engines: [{ engine: 'claude', installed: true, signedIn: false }, { engine: 'codex', installed: null, signedIn: null }],+ checkouts: [{ folder: 'p1', repository: 'github.com/acme/app', git: true, push: false }, { folder: 'p2', repository: null, git: false, push: null }] }+ expect(machineObservationSchema.safeParse(sent).success).toBe(true)+ expect(machineObservationSchema.safeParse({ ...sent, readiness }).success).toBe(true)+ expect(machineObservationSchema.safeParse({ ...sent, readiness: {} }).success).toBe(true)+ expect(machineObservationSchema.safeParse({ ...sent, readiness: { ...readiness, extra: 1 } }).success).toBe(false)+ expect(machineObservationSchema.safeParse({ ...sent, readiness: { checkouts: [{ ...readiness.checkouts[0], folder: '../p1' }] } }).success).toBe(false)+ expect(machineObservationSchema.safeParse({ ...sent, readiness: { checkouts: Array(65).fill(readiness.checkouts[0]) } }).success).toBe(false)+ expect(machineObservationSchema.safeParse({ ...sent, readiness: { engines: [{ engine: 'claude', installed: 'yes', signedIn: null }] } }).success).toBe(false)+})+function setup(machine: Partial<ContributedMachine> = {}) {const state: SuperTabState = createSuperTab('tab', 'Team', { id: 'owner', email: '[email protected]' }, 'test')state.machines = [{ machineId: 'host', name: 'Studio Mac', contributorId: 'owner', membershipGeneration: 'tab', generation: 'g1',diff --git a/backend/src/superTabs/machines.ts b/backend/src/superTabs/machines.tsindex 7f3baf598..25434a2a9 100644--- a/backend/src/superTabs/machines.ts+++ b/backend/src/superTabs/machines.ts@@ -69,12 +69,24 @@ export const machinePrivacySchema = z.union([export type MachinePrivacy = z.infer<typeof machinePrivacySchema>/** As a pool keeps it: `seenAt` is when this server first received that check's result, on the server's clock. */export type StoredPrivacy = MachinePrivacy & { seenAt: number }+/** What the machine is ready for (cli/src/superTabs/machines.ts readiness), for the route to leave out one that cannot do+ * the work: per engine whether it is installed and signed in, and per folder in its Swarm workspace (one per project)+ * the repository it checks out (an address without credentials), whether it is a git checkout, and whether this+ * machine's own login can push to it. Absent from hosts before it; null and absent entries are unknown. */+const readiness = z.object({+ engines: z.array(z.object({ engine: z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/), installed: z.boolean().nullable(), signedIn: z.boolean().nullable() }).strict()).max(8).optional(),+ checkouts: z.array(z.object({ folder: z.string().min(1).max(160).regex(/^[^/\\]+$/).refine(f => f !== '.' && f !== '..'),+ repository: z.string().max(300).nullable(), git: z.boolean(), push: z.boolean().nullable() }).strict()).max(64).optional(),+}).strict()export const machineObservationSchema = z.object({ generation: z.string().max(160), resources: resource,tools: z.record(z.string().max(80), z.boolean()).refine(v => Object.keys(v).length <= 20),toolProbeErrors: z.record(z.string().max(80), z.string().max(200)).refine(v => Object.keys(v).length <= 20).optional(),quotas: z.array(quota).max(32), runningHarnessIds: z.array(z.string().max(160)).max(1000),stoppedHarnessIds: z.array(z.string().max(160)).max(1000),stoppedReservations: z.array(z.object({ harnessId: z.string().min(1).max(160), generation: z.string().min(1).max(160) }).strict()).max(1000).optional(),+ /** When each running agent's screen or transcript last changed (epoch ms); its lease renews on recent progress+ * (liveness.ts). Absent from hosts before it, whose agents renew by running alone. */+ harnessProgress: z.record(z.string().max(160), z.number().int().nonnegative()).refine(v => Object.keys(v).length <= 1000).optional(),/** The Local models add-on (docs/plans/2026-10-23-swarm-local-models.md); absent from hosts before it. On the Swarm's* grid: what this machine serves there (`local` an engine of its own, `api` a saved API it shares), usable by agents on* any machine. On any other grid: a model its owner may use there (`shared`, shared with them), usable only by agents@@ -91,6 +103,7 @@ export const machineObservationSchema = z.object({ generation: z.string().max(16/** A Harness Team daemon's privacy check; absent from the owner's own daemon and from hosts before it. The store keeps* it only when a team session reported it (observedPrivacy). */privacy: machinePrivacySchema.optional(),+ readiness: readiness.optional(),}).strict()export type MachineObservation = z.infer<typeof machineObservationSchema>diff --git a/backend/src/superTabs/mentions.ts b/backend/src/superTabs/mentions.tsindex 8b2f02224..536e35234 100644--- a/backend/src/superTabs/mentions.ts+++ b/backend/src/superTabs/mentions.ts@@ -3,7 +3,7 @@* reads and writes a tab that has them. Called inside SuperTabStore's transactions. */import type { Prisma, PrismaClient } from '@prisma/client'import { fail, isLeads, person, stableId, type Actor, type Conversation, type MessageDraft, type SuperTabState } from './model.js'-import { canReadProject, groupProject, ledProject, projectOf } from './projects.js'+import { canReadGroup, groupProject, ledProject, projectOf } from './projects.js'type Tx = Prisma.TransactionClientexport const MAX_MENTIONS = 5@@ -29,7 +29,7 @@ export function checkMentions(state: SuperTabState, actor: Actor, group: Conversif (isLeads(group) || groupProject(state, group).id !== led.id) fail('MENTION_FORBIDDEN', 'A Lead can tag people only in its own project’s conversations.', 403)for (const id of ids) {const member = state.people.find(p => p.id === id) ?? fail('INVALID_MENTION', 'Tag a person in this Swarm.', 400)- if (!canReadProject(state, { kind: 'person', userId: member.id, email: member.email }, led)) {+ if (!canReadGroup(state, { kind: 'person', userId: member.id, email: member.email }, group)) {fail('INVALID_MENTION', `${member.email} cannot read this conversation.`, 400)}}@@ -68,7 +68,7 @@ async function readable(tx: Tx, tabId: string, state: SuperTabState, actor: Extr...(open ? waiting : { resolvedAt: { not: null } }) }, orderBy: { createdAt: 'desc' }, take: 500 })return rows.filter(row => {const group = state.conversations.find(c => c.id === row.conversationId)- return !!group && !isLeads(group) && canReadProject(state, actor, projectOf(state, group.projectId ?? 'lead'))+ return !!group && !isLeads(group) && canReadGroup(state, actor, group)})}diff --git a/backend/src/superTabs/migration/fingerprint.ts b/backend/src/superTabs/migration/fingerprint.tsnew file mode 100644index 000000000..b808e8283--- /dev/null+++ b/backend/src/superTabs/migration/fingerprint.ts@@ -0,0 +1,37 @@+import { createHash } from 'node:crypto'+import type { Prisma } from '@prisma/client'++/** What the migration must leave untouched (design 6.3): the ordered message list and the other rows of the Swarm. */+export interface Fingerprint {+ messages: number+ /** sha256 of the ordered (conversationId, sequence, id) list. */+ order: string+ conversationIds: Set<string>+ rows: { deliveries: number; routeDecisions: number; attempts: number; operations: number }+}++export async function fingerprint(tx: Prisma.TransactionClient, tabId: string): Promise<Fingerprint> {+ const where = { tabId }+ const [messages, deliveries, routeDecisions, attempts, operations] = await Promise.all([+ tx.superTabMessage.findMany({ where, select: { conversationId: true, sequence: true, id: true },+ orderBy: [{ conversationId: 'asc' }, { sequence: 'asc' }, { id: 'asc' }] }),+ tx.superTabDelivery.count({ where }), tx.superTabRouteDecision.count({ where }), tx.superTabAttempt.count({ where }), tx.superTabOperation.count({ where }),+ ])+ const order = createHash('sha256')+ for (const m of messages) order.update(`${m.conversationId}\t${m.sequence}\t${m.id}\n`)+ return { messages: messages.length, order: order.digest('hex'), conversationIds: new Set(messages.map(m => m.conversationId)),+ rows: { deliveries, routeDecisions, attempts, operations } }+}++/** Where a fingerprint taken after the migration differs from the one before it, or null. */+export function fingerprintDifference(before: Fingerprint, after: Fingerprint): string | null {+ if (before.messages !== after.messages || before.order !== after.order) return `messages changed: ${before.messages} before, ${after.messages} after`+ const changed = (Object.keys(before.rows) as Array<keyof Fingerprint['rows']>).filter(key => before.rows[key] !== after.rows[key])+ return changed.length ? `rows changed: ${changed.map(key => `${key} ${before.rows[key]} → ${after.rows[key]}`).join(', ')}` : null+}++/** The newest message of each conversation: when its group was last active. */+export async function lastActivity(tx: Prisma.TransactionClient, tabId: string): Promise<Map<string, number>> {+ const rows = await tx.superTabMessage.groupBy({ by: ['conversationId'], where: { tabId }, _max: { createdAt: true } })+ return new Map(rows.flatMap(row => row._max.createdAt ? [[row.conversationId, row._max.createdAt.getTime()] as const] : []))+}diff --git a/backend/src/superTabs/migration/job.ts b/backend/src/superTabs/migration/job.tsnew file mode 100644index 000000000..9e6e0b889--- /dev/null+++ b/backend/src/superTabs/migration/job.ts@@ -0,0 +1,47 @@+/**+ * The migration job (design 6.1.1, step 3 and 4): it starts only when no old writer is left, then migrates every Swarm+ * still in one row, one transaction each, and reports each one. A Swarm that fails is left as it was.+ */+import type { PrismaClient } from '@prisma/client'+import { migrateSwarm, type MigrationReport } from './migrate.js'++export const QUIET_WAIT_MS = 60_000+export interface JobOptions {+ now?: () => number+ /** How long the newest writes must stay unchanged. Hosts observe every 5–15 s and claim deliveries every second. */+ waitMs?: number+ sleep?: (ms: number) => Promise<void>+ log?: (report: MigrationReport) => void+}+export interface JobResult { reports: MigrationReport[]; totals: { swarms: number; ok: number; failed: number; skipped: number; ms: number } }++/** The newest write of each kind old writers make, with the row counts, so an insert dated in the past shows too. */+async function writeMarks(db: PrismaClient): Promise<string> {+ const [tab, message, delivery, messages, deliveries] = await Promise.all([+ db.superTab.findFirst({ orderBy: { updatedAt: 'desc' }, select: { updatedAt: true } }),+ db.superTabMessage.findFirst({ orderBy: { createdAt: 'desc' }, select: { createdAt: true } }),+ db.superTabDelivery.findFirst({ orderBy: { updatedAt: 'desc' }, select: { updatedAt: true } }),+ db.superTabMessage.count(), db.superTabDelivery.count(),+ ])+ return JSON.stringify([tab?.updatedAt, message?.createdAt, delivery?.updatedAt, messages, deliveries])+}++export async function writersQuiet(db: PrismaClient, waitMs = QUIET_WAIT_MS, sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms))): Promise<boolean> {+ const before = await writeMarks(db)+ await sleep(waitMs)+ return before === await writeMarks(db)+}++export async function migrateAll(db: PrismaClient, { now = Date.now, waitMs, sleep, log = () => {} }: JobOptions = {}): Promise<JobResult> {+ const started = Date.now()+ if (!await writersQuiet(db, waitMs, sleep)) throw new Error('Stopped: a writer is still running. Stop every old backend process, then run this again.')+ const ids = (await db.superTab.findMany({ where: { format: 1 }, orderBy: { id: 'asc' }, select: { id: true } })).map(r => r.id)+ const reports: MigrationReport[] = []+ for (const id of ids) {+ const report = await migrateSwarm(db, id, { now })+ log(report)+ reports.push(report)+ }+ return { reports, totals: { swarms: reports.length, ok: reports.filter(r => r.ok && !r.skipped).length, failed: reports.filter(r => !r.ok).length,+ skipped: reports.filter(r => r.skipped).length, ms: Date.now() - started } }+}diff --git a/backend/src/superTabs/migration/links.ts b/backend/src/superTabs/migration/links.tsnew file mode 100644index 000000000..8b6260a2e--- /dev/null+++ b/backend/src/superTabs/migration/links.ts@@ -0,0 +1,25 @@+import type { Prisma } from '@prisma/client'+import { appendPullRequestUrls, type SuperTabState } from '../model.js'++/** Groups from before link lists have none. The migration rebuilds theirs once from complete stored history (moved from+ * store.ts, where every read did it: reads never write once Swarms are in parts, design R8). */+export async function restorePullRequestUrls(tx: Prisma.TransactionClient, tabId: string, state: SuperTabState): Promise<void> {+ const missing = state.conversations.filter(group => group.pullRequestUrls === undefined)+ if (!missing.length) return+ const conversationIds = missing.map(group => group.id)+ const [messages, attempts] = await Promise.all([+ tx.superTabMessage.findMany({ where: { tabId, conversationId: { in: conversationIds }, text: { contains: 'https://github.com/' } },+ select: { conversationId: true, text: true }, orderBy: { sequence: 'asc' } }),+ tx.superTabAttempt.findMany({ where: { tabId, conversationId: { in: conversationIds } },+ select: { conversationId: true, snapshot: true }, orderBy: { createdAt: 'asc' } }),+ ])+ for (const group of missing) {+ const prior = attempts.filter(attempt => attempt.conversationId === group.id)+ .map(attempt => attempt.snapshot as unknown as { checks?: Array<{ evidence?: string | null }>; assignment?: { result?: string | null } })+ appendPullRequestUrls(group, [+ ...messages.filter(message => message.conversationId === group.id).map(message => message.text),+ ...prior.flatMap(attempt => [...(attempt.checks ?? []).map(check => check.evidence), attempt.assignment?.result]),+ ...group.checks.map(check => check.evidence), group.assignment?.result,+ ])+ }+}diff --git a/backend/src/superTabs/migration/migrate.ts b/backend/src/superTabs/migration/migrate.tsnew file mode 100644index 000000000..a516703eb--- /dev/null+++ b/backend/src/superTabs/migration/migrate.ts@@ -0,0 +1,70 @@+/**+ * Moves one Swarm from its single row to parts (design 6.1.2), in one transaction: normalize, split, insert, read the+ * parts back and verify them against the state, check messages and other rows are untouched, then fence the row. Any+ * difference aborts the transaction, so a Swarm is either fully in parts or left exactly as it was.+ */+import type { Prisma, PrismaClient } from '@prisma/client'+import type { SuperTabState } from '../model.js'+import * as parts from '../parts/index.js'+import { fingerprint, fingerprintDifference, lastActivity } from './fingerprint.js'+import { restorePullRequestUrls } from './links.js'+import { normalize } from './normalize.js'+import { stateDifference } from './verify.js'++export interface MigrationReport {+ tabId: string+ ok: boolean+ skipped?: true+ error?: string+ /** Size of the old state. */+ bytes: number+ groups: number+ dormant: number+ parts: number+ messages: number+ ms: number+}++/** Only this job: a 1.16 MB Swarm reads, splits and verifies well past the commands' 15 s. */+const MIGRATION_TRANSACTION = { maxWait: 5_000, timeout: 60_000 }+/** The old state that every older backend refuses before it writes (store.ts stateOf), so a survivor of the gate cannot. */+export const FENCED_STATE = { version: 2 }++class MigrationFailed extends Error {}+const fail = (message: string): never => { throw new MigrationFailed(message) }++export async function migrateSwarm(db: PrismaClient, tabId: string, { now = Date.now }: { now?: () => number } = {}): Promise<MigrationReport> {+ const started = Date.now()+ const empty = { tabId, bytes: 0, groups: 0, dormant: 0, parts: 0, messages: 0 }+ try {+ return await db.$transaction(tx => migrateIn(tx, tabId, now(), started), MIGRATION_TRANSACTION)+ } catch (error) {+ return { ...empty, ok: false, error: error instanceof Error ? error.message : String(error), ms: Date.now() - started }+ }+}++async function migrateIn(tx: Prisma.TransactionClient, tabId: string, at: number, started: number): Promise<MigrationReport> {+ const row = await tx.superTab.findUnique({ where: { id: tabId } }) ?? fail(`Swarm ${tabId} does not exist`)+ if (row.format === 2) return { tabId, ok: true, skipped: true, bytes: 0, groups: 0, dormant: 0, parts: 0, messages: 0, ms: Date.now() - started }+ const original = row.state as unknown as SuperTabState+ if (original.version !== 1) fail(`its state has version ${String(original.version)}, not 1`)+ const before = await fingerprint(tx, tabId)+ const activity = await lastActivity(tx, tabId)+ const state = normalize(original, { now: at, lastActivity: activity })+ await restorePullRequestUrls(tx, tabId, state)+ await parts.insertParts(tx, parts.split(state, { tabId, version: row.revision, now: at, lastActivity: activity }))+ const stored = await parts.loadAll(tx, tabId)+ const differs = stateDifference(parts.toLegacyState(state), parts.toLegacyState(parts.reassemble(stored)))+ if (differs) fail(`its parts would not reassemble into its state: ${differs}`)+ const groups = new Set(stored.groups.map(g => g.key))+ const orphaned = [...before.conversationIds].filter(id => !groups.has(id))+ if (orphaned.length) fail(`${orphaned.length} message${orphaned.length === 1 ? '' : 's'} in a conversation it does not have: ${orphaned.join(', ')}`)+ const touched = fingerprintDifference(before, await fingerprint(tx, tabId))+ if (touched) fail(touched)+ const fenced = await tx.superTab.updateMany({ where: { id: tabId, revision: row.revision, format: 1 },+ data: { format: 2, revision: row.revision + 1, migratedAt: new Date(at), legacyState: row.state as Prisma.InputJsonValue, state: FENCED_STATE } })+ if (!fenced.count) fail('it changed while it was being migrated')+ return { tabId, ok: true, bytes: Buffer.byteLength(JSON.stringify(original)), groups: stored.groups.length,+ dormant: stored.groups.filter(g => g.dormant).length, messages: before.messages, ms: Date.now() - started,+ parts: 1 + stored.members.length + stored.agents.length + stored.groups.length + stored.machines.length + stored.starts.length + stored.progress.length }+}diff --git a/backend/src/superTabs/migration/normalize.test.ts b/backend/src/superTabs/migration/normalize.test.tsnew file mode 100644index 000000000..9d6be73bd--- /dev/null+++ b/backend/src/superTabs/migration/normalize.test.ts@@ -0,0 +1,99 @@+import { describe, expect, it } from 'vitest'+import { normalize } from './normalize.js'+import { NOW, richSwarm } from '../read/fixture.test-support.js'+import type { Conversation, SuperTabState } from '../model.js'++const DAY = 86_400_000+const group = (state: SuperTabState, id: string) => state.conversations.find(c => c.id === id)!+const finish = (c: Conversation, status: 'done' | 'cancelled' | 'stopped') => { c.assignment = { ...c.assignment!, status } }++describe('migration normalize (design 6.1.2 step 2)', () => {+ it('persists what reads derive today: display names, numbers, rule projects, agent projects', () => {+ const s = richSwarm()+ const legacy = structuredClone(s.state)+ delete legacy.agents[1]!.displayName+ delete legacy.agents[1]!.projectId+ delete group(legacy, s.done).number+ legacy.retiredConversationNumber = 10+ legacy.rules = [{ id: 'r', rule: { kind: 'preferEngine', taskKind: 'ui', engine: 'codex' }, text: 'Codex for UI.', askedBy: 'someone', askedIn: null } as never]+ const state = normalize(legacy, { now: NOW, lastActivity: new Map() })+ expect(state.agents[1]!.displayName).toBe(s.state.agents[1]!.displayName)+ expect(state.agents[1]!.projectId).toBe('lead')+ expect(group(state, s.done).number).toBe(11)+ expect(state.rules![0]!.projectId).toBe('lead')+ })++ it('leaves an agent without a project alone in a Swarm from before projects', () => {+ const legacy = structuredClone(richSwarm().state)+ delete legacy.projects+ delete legacy.agents[1]!.projectId+ expect(normalize(legacy, { now: NOW, lastActivity: new Map() }).agents[1]).not.toHaveProperty('projectId')+ })++ it('persists the awaiting decision of a worker whose work ended before decisions were stored', () => {+ const s = richSwarm()+ const legacy = structuredClone(s.state)+ finish(group(legacy, s.web), 'done')+ delete legacy.agents.find(a => a.id === s.worker)!.workDecision+ expect(normalize(legacy, { now: NOW, lastActivity: new Map() }).agents.find(a => a.id === s.worker)!.workDecision).toBe('awaiting')+ })++ it('makes archived groups and finished groups quiet for a day dormant, never a Lead conversation or running work', () => {+ const s = richSwarm()+ const legacy = structuredClone(s.state)+ finish(group(legacy, s.web), 'done')+ group(legacy, s.done).archived = true+ const quiet = NOW - DAY - 1+ const activity = new Map([[s.web, quiet], ['lead', quiet], [s.secretGroup, quiet]])+ const state = normalize(legacy, { now: NOW, lastActivity: activity })+ expect(state.conversations.filter(c => c.dormant).map(c => c.id).sort()).toEqual([s.web, s.done].sort())++ const recent = normalize(legacy, { now: NOW, lastActivity: new Map([[s.web, NOW - DAY + 1]]) })+ expect(group(recent, s.web).dormant).toBeUndefined()+ const stopped = structuredClone(legacy)+ finish(group(stopped, s.web), 'stopped')+ expect(group(normalize(stopped, { now: NOW, lastActivity: activity }), s.web).dormant).toBeUndefined()+ })++ it('keeps a finished or archived group awake while its Lead has not read its reports, as the store\'s sweep does', () => {+ const s = richSwarm()+ const legacy = structuredClone(s.state)+ finish(group(legacy, s.web), 'done')+ group(legacy, s.web).lastMessageSequence = 30+ group(legacy, s.done).archived = true+ group(legacy, s.done).lastMessageSequence = 25+ const quiet = new Map([[s.web, NOW - DAY - 1]])+ // Reports up to 30 written, the Lead summarized up to 20: the web group's last report (30) is unread, the archived one's (25) too.+ ;(legacy.projects![0] as { progress?: unknown }).progress = { dirtyRevision: 30, summarizedRevision: 20, since: 1, requestedRevision: 20 }+ expect(normalize(legacy, { now: NOW, lastActivity: quiet }).conversations.filter(c => c.dormant).map(c => c.id)).toEqual([])+ // Once summarized up to 30, both have nothing left to report and sleep.+ ;(legacy.projects![0] as { progress?: unknown }).progress = { dirtyRevision: 30, summarizedRevision: 30, since: 1, requestedRevision: 30 }+ expect(normalize(legacy, { now: NOW, lastActivity: quiet }).conversations.filter(c => c.dormant).map(c => c.id).sort()).toEqual([s.web, s.done].sort())+ })++ it('lets a private conversation sleep whatever its project owes, since it never feeds reports', () => {+ const s = richSwarm()+ const legacy = structuredClone(s.state)+ group(legacy, s.done).archived = true+ group(legacy, s.done).lastMessageSequence = 25+ group(legacy, s.done).audience = { people: [] }+ ;(legacy.projects![0] as { progress?: unknown }).progress = { dirtyRevision: 30, summarizedRevision: 20, since: 1, requestedRevision: 20 }+ expect(group(normalize(legacy, { now: NOW, lastActivity: new Map() }), s.done).dormant).toBe(true)+ })++ it('parks conversations of an unknown kind and keeps the Leads conversation in step, as reading the row does', () => {+ const legacy = structuredClone(richSwarm().state)+ legacy.conversations.push({ id: 'later', kind: 'future' as never, title: 'Later', leadId: null, agentIds: [], archived: false, brief: '', checks: [], assignment: null, lastMessageSequence: 0 })+ legacy.conversations = legacy.conversations.filter(c => c.kind !== 'leads')+ const state = normalize(legacy, { now: NOW, lastActivity: new Map() })+ expect(state.parkedConversations!.map(c => c.id)).toEqual(['later'])+ expect(state.conversations.at(-1)!.kind).toBe('leads')+ })++ it('does not change its input', () => {+ const legacy = structuredClone(richSwarm().state)+ const copy = structuredClone(legacy)+ normalize(legacy, { now: NOW, lastActivity: new Map() })+ expect(legacy).toEqual(copy)+ })+})diff --git a/backend/src/superTabs/migration/normalize.ts b/backend/src/superTabs/migration/normalize.tsnew file mode 100644index 000000000..8aaf44720--- /dev/null+++ b/backend/src/superTabs/migration/normalize.ts@@ -0,0 +1,43 @@+/**+ * The state a Swarm is split from (design 6.1.2 step 2): what the next read or command of the old store would have+ * applied, persisted, so behavior after the migration is identical. Link lists are restored from history beforehand+ * (store.ts restorePullRequestUrls); removals that expire and the released-harness cap are left to the first write.+ */+import { activeWork, awaitingWorkers, isLeads, numberConversations, parkLaterConversations, syncLeads, type Conversation, type SuperTabState } from '../model.js'+import { assignAgentDisplayNames } from '../agentNames.js'+import { agentProjectId, placeRules, projectsOf } from '../projects.js'+import { DORMANT_AFTER_MS, type ProgressData } from '../parts/index.js'++/** Report progress as a row from before parts keeps it, in tab revisions. */+interface LegacyProgress { dirtyRevision: number; summarizedRevision: number }++/** Whether the group's last report is past what its Lead summarized: such a group stays awake until it is read, as the+ * store's sweep keeps it (sweeps.ts, group 2's review round 1). A private conversation never feeds reports. */+function owesReports(state: SuperTabState, group: Conversation): boolean {+ if (group.audience) return false+ const progress = state.projects?.find(p => p.id === (group.projectId ?? 'lead'))?.progress as LegacyProgress | ProgressData | undefined+ if (!progress) return false+ // The split gives a group of a project with old progress the report sequence min(last message, dirty revision).+ if ('dirtyRevision' in progress) return Math.min(group.lastMessageSequence, progress.dirtyRevision) > progress.summarizedRevision+ return (group.reportSeq ?? 0) > (progress.summarized[group.id] ?? progress.summarizedFloor)+}++export function normalize(original: SuperTabState, { now, lastActivity }: { now: number; lastActivity: ReadonlyMap<string, number> }): SuperTabState {+ const state = structuredClone(original)+ parkLaterConversations(state)+ syncLeads(state)+ numberConversations(state)+ placeRules(state)+ assignAgentDisplayNames(state.agents)+ if (state.projects) for (const agent of state.agents) agent.projectId ??= agentProjectId(state, agent)+ for (const project of projectsOf(state)) for (const worker of awaitingWorkers(state, project.id)) worker.workDecision = 'awaiting'+ const leadGroups = new Set(projectsOf(state).map(p => p.leadConversationId))+ for (const group of state.conversations) {+ const finished = !!group.assignment && !activeWork(group) && group.assignment.status !== 'stopped'+ // A group with no message counts as active now; the archive sweep takes it a day later if it stays quiet.+ const quiet = now - (lastActivity.get(group.id) ?? now) > DORMANT_AFTER_MS+ if (isLeads(group) || leadGroups.has(group.id) || owesReports(state, group)) continue+ if (group.archived || (finished && quiet)) group.dormant = true+ }+ return state+}diff --git a/backend/src/superTabs/migration/rollback.ts b/backend/src/superTabs/migration/rollback.tsnew file mode 100644index 000000000..f4314c682--- /dev/null+++ b/backend/src/superTabs/migration/rollback.ts@@ -0,0 +1,89 @@+/**+ * Rollback to the previous release (design 6.4), behind the same gate as the migration. Before any write in parts, the+ * old state goes back unchanged. After writes, the state is rebuilt from the parts, numbered past everything used since,+ * and the parts are kept until the owner says they can go. A Swarm the previous release would misread is never rolled+ * back: it checks no audience and knows no lost work (final review, Critical 2).+ */+import type { Prisma, PrismaClient } from '@prisma/client'+import { nextConversationNumber, type Conversation, type SuperTabState } from '../model.js'+import * as parts from '../parts/index.js'++export interface RollbackReport { tabId: string; ok: boolean; error?: string }++const ROLLBACK_TRANSACTION = { maxWait: 5_000, timeout: 60_000 }+const PART_MODELS = ['swarmHead', 'swarmMember', 'swarmAgent', 'swarmGroup', 'swarmMachine', 'swarmStart', 'swarmProgress'] as const+class RollbackFailed extends Error {}+const fail = (message: string): never => { throw new RollbackFailed(message) }++async function run(db: PrismaClient, tabId: string, body: (tx: Prisma.TransactionClient) => Promise<void>): Promise<RollbackReport> {+ try {+ await db.$transaction(body, ROLLBACK_TRANSACTION)+ return { tabId, ok: true }+ } catch (error) {+ return { tabId, ok: false, error: error instanceof Error ? error.message : String(error) }+ }+}++async function migratedRow(tx: Prisma.TransactionClient, tabId: string) {+ const row = await tx.superTab.findUnique({ where: { id: tabId } }) ?? fail(`Swarm ${tabId} does not exist`)+ if (row.format !== 2) fail('it is not in parts')+ return row+}+const newestVersion = (stored: parts.SwarmParts) =>+ Math.max(...[stored.head, ...stored.members, ...stored.agents, ...stored.groups, ...stored.machines, ...stored.starts, ...stored.progress].map(p => p.version))+const newestSequence = async (tx: Prisma.TransactionClient, tabId: string) =>+ (await tx.superTabMessage.findFirst({ where: { tabId }, orderBy: { sequence: 'desc' }, select: { sequence: true } }))?.sequence ?? 0++const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`++/**+ * What the previous release would misread in a state rebuilt from the parts. It filters conversations by project alone,+ * so a private one becomes readable by every project reader. It ends work only on done, stopped or cancelled, so a task+ * whose status is lost reads as active. A lost task cancelled later is finished there, but it knows no lost marker: the+ * fenced worker reads as an ordinary finished one awaiting a decision (model.ts awaitingWorkers). Null when there is neither.+ */+function downgradeHazard(state: SuperTabState): string | null {+ const groups: Conversation[] = [...state.conversations, ...state.parkedConversations ?? []]+ const hidden = groups.filter(g => g.audience).length+ const lost = groups.filter(g => g.assignment?.status === 'lost').length+ const marked = groups.filter(g => g.assignment?.lost && g.assignment.status !== 'lost').length+ const hazards = [...hidden ? [`its ${plural(hidden, 'private conversation')} would become readable by every project reader`] : [],+ ...lost ? [`its ${plural(lost, 'lost task')} would read as active work`] : [],+ ...marked ? [`its ${plural(marked, 'task')} lost and then cancelled would lose the lost marker, so each fenced worker would read as an ordinary finished one awaiting a decision`] : []]+ return hazards.length ? `the previous release would misread it: ${hazards.join(', and ')}` : null+}++/** Before any write in parts: the old state back as it was, the parts dropped. Refused once anything was written since. */+export function rollbackLegacy(db: PrismaClient, tabId: string): Promise<RollbackReport> {+ return run(db, tabId, async tx => {+ const row = await migratedRow(tx, tabId)+ if (!row.legacyState) fail('it has no old state kept')+ const stored = await parts.loadAll(tx, tabId)+ if (newestVersion(stored) > stored.sequenceBase || await newestSequence(tx, tabId) > stored.sequenceBase) {+ fail('parts were written since the migration; roll back from the parts instead')+ }+ const restored = await tx.superTab.updateMany({ where: { id: tabId, format: 2, revision: row.revision },+ data: { state: row.legacyState as Prisma.InputJsonValue, format: 1, migratedAt: null, legacyState: null } })+ if (!restored.count) fail('it changed during the rollback')+ for (const model of PART_MODELS) await (tx[model] as unknown as { deleteMany(args: unknown): Promise<unknown> }).deleteMany({ where: { tabId } })+ })+}++/** After writes in parts: the old state rebuilt from them. The old store numbers every new message from the tab revision+ * and every new group past the highest number, so both start past anything used in parts. */+export function rollbackFromParts(db: PrismaClient, tabId: string): Promise<RollbackReport> {+ return run(db, tabId, async tx => {+ const row = await migratedRow(tx, tabId)+ const stored = await parts.loadAll(tx, tabId)+ const state = parts.toLegacyState(parts.reassemble(stored))+ if (state.version !== 1) fail(`its rebuilt state has version ${String(state.version)}, not 1`)+ const hazard = downgradeHazard(state)+ if (hazard) fail(`Swarm ${tabId} was not rolled back, and nothing was changed: ${hazard}. Roll forward with a fix instead; `+ + 'the parts stay authoritative, so nothing is lost or made public.')+ if (stored.groupCounter > nextConversationNumber(state) - 1) state.retiredConversationNumber = stored.groupCounter+ const revision = Math.max(row.revision, newestVersion(stored), await newestSequence(tx, tabId)) + 1+ const restored = await tx.superTab.updateMany({ where: { id: tabId, format: 2, revision: row.revision },+ data: { state: JSON.parse(JSON.stringify(state)) as Prisma.InputJsonValue, revision, format: 1, migratedAt: null } })+ if (!restored.count) fail('it changed during the rollback')+ })+}diff --git a/backend/src/superTabs/migration/verify.test.ts b/backend/src/superTabs/migration/verify.test.tsnew file mode 100644index 000000000..4fe8a412e--- /dev/null+++ b/backend/src/superTabs/migration/verify.test.ts@@ -0,0 +1,58 @@+import { describe, expect, it } from 'vitest'+import { stateDifference } from './verify.js'+import { richSwarm } from '../read/fixture.test-support.js'+import type { SuperTabState } from '../model.js'++const base = (): SuperTabState => {+ const state = structuredClone(richSwarm().state)+ state.harnessReservations = [{ machineId: 'a', harnessId: '1', generation: 'g', renewed: false }, { machineId: 'b', harnessId: '2', generation: 'g', renewed: true }]+ state.releasedHarnesses = [{ machineId: 'a', harnessId: 'x' }, { machineId: 'b', harnessId: 'y' }]+ state.overlapAlerts = ['p:q', 'a:b']+ return state+}++describe('state verification (design 6.3)', () => {+ it('finds no difference between equal states', () => {+ expect(stateDifference(base(), base())).toBeNull()+ })++ it('ignores the order of the ledger arrays and overlap alerts, which carry none', () => {+ const other = base()+ other.harnessReservations!.reverse()+ other.releasedHarnesses!.reverse()+ other.overlapAlerts!.reverse()+ expect(stateDifference(base(), other)).toBeNull()+ })++ it('keeps the order of every other array', () => {+ const other = base()+ other.conversations.reverse()+ expect(stateDifference(base(), other)).toMatch(/^conversations\[0\]/)+ })++ it('treats an absent optional list and an empty one as the same', () => {+ const one = base(), other = base()+ one.starts = []+ one.machineCleanups = []+ delete other.starts+ expect(stateDifference(one, other)).toBeNull()+ })++ it('treats a key holding undefined as absent, as stored JSON does', () => {+ const other = base()+ other.agents[0]!.downSince = undefined+ expect(stateDifference(base(), other)).toBeNull()+ })++ it('names the first differing path', () => {+ const other = base()+ other.conversations[2]!.title = 'Changed'+ expect(stateDifference(base(), other)).toBe('conversations[2].title: "Web" ≠ "Changed"')+ const extra = base()+ ;(extra.agents[1] as unknown as Record<string, unknown>).surprise = 1+ expect(stateDifference(base(), extra)).toBe('agents[1].surprise: (absent) ≠ 1')+ const shorter = base()+ shorter.people.pop()+ expect(stateDifference(base(), shorter)).toMatch(/^people: 3 items ≠ 2 items/)+ })+})diff --git a/backend/src/superTabs/migration/verify.ts b/backend/src/superTabs/migration/verify.tsnew file mode 100644index 000000000..d84ed0436--- /dev/null+++ b/backend/src/superTabs/migration/verify.ts@@ -0,0 +1,43 @@+/** Verification of one Swarm's migration (design 6.3): the parts read back reassemble into the state they came from. */+import type { SuperTabState } from '../model.js'++/** Lists the parts store keeps only when they have entries: absent and empty are the same list. */+const OPTIONAL_LISTS = ['starts', 'machines', 'harnessReservations', 'releasedHarnesses', 'closingSessions', 'machineCleanups',+ 'parkedConversations', 'overlapAlerts'] as const+/** Lists whose order carries no meaning; machine parts regroup them by machine. */+const UNORDERED = ['harnessReservations', 'releasedHarnesses', 'closingSessions', 'machineCleanups', 'overlapAlerts'] as const++/** The state as stored JSON sees it (no undefined), unordered lists sorted, empty optional lists removed. */+function canonical(state: SuperTabState): Record<string, unknown> {+ const plain = JSON.parse(JSON.stringify(state)) as Record<string, unknown[] | undefined>+ for (const key of UNORDERED) plain[key]?.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)))+ for (const key of OPTIONAL_LISTS) if (Array.isArray(plain[key]) && !plain[key]!.length) delete plain[key]+ return plain+}++const shown = (value: unknown) => value === undefined ? '(absent)' : JSON.stringify(value)+const isObject = (value: unknown): value is Record<string, unknown> => !!value && typeof value === 'object' && !Array.isArray(value)++function difference(expected: unknown, actual: unknown, path: string): string | null {+ if (Array.isArray(expected) && Array.isArray(actual)) {+ if (expected.length !== actual.length) return `${path}: ${expected.length} items ≠ ${actual.length} items`+ for (let i = 0; i < expected.length; i++) {+ const found = difference(expected[i], actual[i], `${path}[${i}]`)+ if (found) return found+ }+ return null+ }+ if (isObject(expected) && isObject(actual)) {+ for (const key of [...new Set([...Object.keys(expected), ...Object.keys(actual)])].sort()) {+ const found = difference(expected[key], actual[key], path ? `${path}.${key}` : key)+ if (found) return found+ }+ return null+ }+ return Object.is(expected, actual) ? null : `${path}: ${shown(expected)} ≠ ${shown(actual)}`+}++/** The first path where two states differ, field by field, or null when they are the same. */+export function stateDifference(expected: SuperTabState, actual: SuperTabState): string | null {+ return difference(canonical(expected), canonical(actual), '')+}diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.tsindex 1dda84825..3b73428d6 100644--- a/backend/src/superTabs/model.ts+++ b/backend/src/superTabs/model.ts@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto'import type { RouteDecisionEffect } from './routeRecord.js'import { agentDisplayName, assignAgentDisplayNames } from './agentNames.js'import { downSince, expireRemovals } from './machines.js'-import { agentProjectId, agentSetRole, canReadAgent, canReadProject, groupProject, ledProject, placeRules, projectsOf, sharedWithLeads, skillSetOf, type ProjectVisibility, type SwarmProject } from './projects.js'+import { agentProjectId, agentSetRole, canReadAgent, canReadGroup, canReadProject, groupProject, ledProject, placeRules, projectsOf, sharedWithLeads, skillSetOf, type ProjectVisibility, type SwarmProject } from './projects.js'export type Role = 'owner' | 'collaborator' | 'viewer'export interface Person { id: string; email: string; role: Role; generation: string }@@ -41,12 +41,18 @@ export interface Agent {replacement?: { previousHarnessId: string; harnessId: string }/** When a reading first showed its session gone or its host confirmed a stop; cleared when it is back (machines.ts). */downSince?: string- /** The down time already named in the Lead's scheduled wake-up (projectUpdates.ts), so each time down is named once. */+ /** Written by the two-hour down wake-up that lost work replaced (liveness.ts); older states may still carry it, never shown. */downNamed?: string+ /** Its last task was lost (liveness.ts): routing leaves it out, even once that task is cancelled or reassigned, until it+ * finishes a new task, a person assigns it work by hand, or its terminal is replaced (commands.ts). */+ lostTask?: { conversationId: string; assignmentId: string; reason: string; at: number }/** A usage limit seen on its terminal; routing skips the agent until then. Shown as null once passed (terminal.ts). */limitedUntil?: string | null/** Terminal alert episodes in progress, so each one posts a single row (terminal.ts). */alerting?: Array<'prompt' | 'limit' | 'model'>+ /** Set once its session is a Lead or in a private conversation, and kept until the session leaves: nobody but its+ * machine's person watches it (projects.ts canWatchAgent). */+ confidential?: true}export type AgentRole = 'builder' | 'reviewer'export const agentRole = (agent: Pick<Agent, 'role'>): AgentRole => agent.role ?? 'builder'@@ -82,11 +88,14 @@ export interface AgentStart {request: AgentStartRequestharnessId: string | nulldispatched: boolean+ /** When its host was asked to launch it; a start not running 3 minutes later fails (liveness.ts). */+ dispatchedAt?: numbererror: string | null}/** `needs_human`: the agent needs a person's decision (its result is the question). `blocked`: it cannot go on (its result- * says why). Both stay active work; the machine running the agent alerts its Harness Pro (cli/src/superTabs/attention.ts). */-export type WorkStatus = 'planned' | 'working' | 'needs_human' | 'blocked' | 'review' | 'done' | 'stopped' | 'cancelled' | 'reconciling'+ * 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'export interface Check {id: stringdescription: string@@ -103,6 +112,12 @@ export interface Assignment {result: string | null/** Explicit progress fences delayed recording gaps; absent on older backends. */recordingProgress?: { at: number; revision: number }+ /** Its agent owns it until then; progress renews it (liveness.ts). Absent on assignments from before leases. */+ leaseUntil?: number+ /** Its agent's last progress the lease saw, for the Lead's wake-up when it is lost. */+ progressAt?: number+ /** Why and when it was lost (status `lost`). */+ lost?: { reason: string; at: number }}export interface WorkTask {goal: string@@ -135,6 +150,18 @@ export interface Conversation {lastMessageSequence: number/** Linked GitHub pull requests, including links older than the latest message page. Absent in older snapshots. */pullRequestUrls?: string[]+ /** The last sequence given to a message here. Each conversation numbers its own messages (store by parts). */+ messageSeq?: number+ /** The sequence of its last message that counts toward its project's reports (projectUpdates.ts). */+ reportSeq?: number+ /** Out of first loads and changes: work done or cancelled and quiet for a day, or archived by hand. A message wakes it. */+ dormant?: boolean+ /** When its last message was written (ISO). */+ lastActivityAt?: string+ /** A private conversation: only these people and the project's Lead read it (projects.ts canReadGroup). */+ audience?: import('./parts/types.js').Audience+ /** The last attempt here that was lost: its agent's status and checks for it are refused, even after reassignment. */+ lostAttempt?: { id: string; agentId: string }}export function appendPullRequestUrls(group: Conversation, texts: Iterable<string | null | undefined>): void {@@ -196,6 +223,10 @@ export interface SuperTabState {/** The Local models add-on (docs/plans/2026-10-23-swarm-local-models.md): off until the owner turns it on, and only* then does anything call grid. The grid is kept when it is turned off, so turning it on again is instant. */localModels?: SwarmLocalModels+ /** The highest workgroup number ever given (store by parts); numbers are never given twice. */+ groupCounter?: number+ /** The tab revision when this Swarm was split into parts; every later message sequence is above it. */+ sequenceBase?: number}export interface SwarmLocalModels {/** The Swarm's own grid, minted on first turn-on and never renamed. */@@ -255,14 +286,16 @@ export function fail(code: string, message: string, status = 409): never { throwexport const stableId = (...parts: string[]): string => createHash('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 24)export const actorKey = (actor: Actor): string => actor.kind === 'person' ? `person:${actor.userId}` : `agent:${actor.agentId}`export const activeWork = (group: Conversation): boolean => !!group.assignment &&- !['done', 'stopped', 'cancelled'].includes(group.assignment.status)+ !['done', 'stopped', 'cancelled', 'lost'].includes(group.assignment.status)/** Old states derive pending decisions from their closed assignments; new states persist them on the worker. */export function awaitingWorkers(state: SuperTabState, projectId: string): Agent[] {return state.agents.filter(a => {if (state.conversations.some(c => c.leadId === a.id) || state.conversations.some(c => activeWork(c) && c.assignment?.agentId === a.id)|| reviewing(state, a.id)) return false- const groups = state.conversations.filter(c => c.assignment?.agentId === a.id)+ // A lost task's agent is not waiting for a decision, even once the task is cancelled: it may be gone, and it must not+ // hold up the next assignment.+ const groups = state.conversations.filter(c => c.assignment?.agentId === a.id && !c.assignment.lost)return (a.projectId ?? groups.map(c => groupProject(state, c).id)[0] ?? 'lead') === projectId &&(a.workDecision === 'awaiting' || (!a.workDecision && groups.some(c => !activeWork(c))))})@@ -317,10 +350,11 @@ export function parkLaterConversations(state: SuperTabState): void {}/** Work a Lead of another project should know about: assigned and moving, not finished, stuck or archived. */-export const crossProjectActive = (group: Conversation): boolean => !group.archived && !isLeads(group)+export const crossProjectActive = (group: Conversation): boolean => !group.archived && !isLeads(group) && !group.audience&& ['working', 'review', 'needs_human'].includes(group.assignment?.status ?? '')-function otherProjectsWork(state: SuperTabState, own: SwarmProject): OtherProjectWork[] {+/** The active work of the other projects a project's Lead may know about (shared with the read API, design 7.2). */+export function otherProjectsWork(state: SuperTabState, own: SwarmProject): OtherProjectWork[] {return state.conversations.filter(crossProjectActive).flatMap(group => {const project = groupProject(state, group), assignment = group.assignment!if (project.id === own.id || !sharedWithLeads(project)) return []@@ -347,11 +381,14 @@ export function numberConversations(state: SuperTabState): void {let next = nextConversationNumber(state)const leads = new Set(projectsOf(state).map(p => p.leadConversationId))for (const group of state.conversations) {- if (!leads.has(group.id) && !isLeads(group) && group.number == null) group.number = next+++ if (!leads.has(group.id) && !isLeads(group) && group.number == null) state.groupCounter = group.number = next++}}+/** The store by parts keeps the highest number ever given (`groupCounter`): a dormant group is not loaded, and its+ * number must not be given again. */export function nextConversationNumber(state: SuperTabState): number {- return Math.max(state.retiredConversationNumber ?? 0, 0, ...[...state.conversations, ...state.parkedConversations ?? []].map(c => c.number ?? 0)) + 1+ return Math.max(state.groupCounter ?? 0, state.retiredConversationNumber ?? 0, 0,+ ...[...state.conversations, ...state.parkedConversations ?? []].map(c => c.number ?? 0)) + 1}export function author(state: SuperTabState, actor: Actor, write = false): Author {if (actor.kind === 'person') {@@ -392,6 +429,8 @@ export function createSuperTab(id: string, name: string, owner: { id: string; emexport function visibleState(state: SuperTabState, actor: Actor, now = Date.now()): SuperTabState {author(state, actor)const visible = structuredClone(state)+ // A dormant conversation is read on demand, never in a whole-Swarm read (spec, Archive); a command may still load one.+ visible.conversations = visible.conversations.filter(c => !c.dormant)syncLeads(visible)// People and Leads read the Leads conversation; it is not there for any other agent.if (actor.kind === 'agent' && !ledProject(visible, actor.agentId)) {@@ -411,7 +450,7 @@ export function visibleState(state: SuperTabState, actor: Actor, now = Date.now(delete visible.harnessReservationsdelete visible.releasedHarnessesdelete visible.overlapAlerts- // Only that machine's host roster lists them (store.ts hostTabs); a removed private agent's session is not every member's.+ // Only that machine's host roster lists them (read/hostRows.ts); a removed private agent's session is not every member's.delete visible.closingSessions// A failing privacy check's detail is its contributor's: an error from the check can name paths on their Mac. Everyone// else reads which item failed (machines.ts teamWorkRefusal).@@ -420,16 +459,18 @@ export function visibleState(state: SuperTabState, actor: Actor, now = Date.now(if (privacy && 'detail' in privacy && !(actor.kind === 'person' && actor.userId === pool.contributorId)) delete (privacy as { detail?: string }).detail}expireRemovals(visible, now)- // A read never hands out the cleanup records it just applied (store.ts hostTabs delivers them to the machine's host).+ // A read never hands out the cleanup records it just applied (read/hostRows.ts delivers them to the machine's host).delete visible.machineCleanupsdelete visible.parkedConversationsnumberConversations(visible)delete visible.retiredConversationNumber+ delete visible.groupCounter+ delete visible.sequenceBaseplaceRules(visible)if (visible.rules) visible.rules = visible.rules.filter(r => projectsOf(state).some(p => p.id === r.projectId && canReadProject(state, actor, p)))if (visible.projects) {visible.projects = visible.projects.filter(p => canReadProject(state, actor, p))- visible.conversations = visible.conversations.filter(c => isLeads(c) || canReadProject(state, actor, groupProject(state, c)))+ visible.conversations = visible.conversations.filter(c => isLeads(c) || canReadGroup(state, actor, c))visible.agents = visible.agents.filter(a => canReadAgent(state, actor, a))for (const group of visible.conversations.filter(isLeads)) group.agentIds = group.agentIds.filter(id => visible.agents.some(a => a.id === id))visible.starts = visible.starts?.filter(s => visible.conversations.some(c => c.id === s.request.conversationId))@@ -442,6 +483,7 @@ export function visibleState(state: SuperTabState, actor: Actor, now = Date.now(if (!pool.observation) continuepool.observation.runningHarnessIds = pool.observation.runningHarnessIds.filter(id => harnesses.has(id))pool.observation.stoppedHarnessIds = pool.observation.stoppedHarnessIds.filter(id => harnesses.has(id))+ if (pool.observation.harnessProgress) pool.observation.harnessProgress = Object.fromEntries(Object.entries(pool.observation.harnessProgress).filter(([id]) => harnesses.has(id)))if (pool.observation.stoppedReservations) pool.observation.stoppedReservations = pool.observation.stoppedReservations.filter(r => harnesses.has(r.harnessId))}visible.invitations = visible.invitations.filter(i => visible.conversations.some(c => c.id === i.conversationId))diff --git a/backend/src/superTabs/native.ts b/backend/src/superTabs/native.tsindex 9488419b0..16a21dabb 100644--- a/backend/src/superTabs/native.ts+++ b/backend/src/superTabs/native.ts@@ -1,12 +1,13 @@import { createHash } from 'node:crypto'-import type { Prisma, SuperTab, SuperTabNativeContext } from '@prisma/client'+import type { Prisma, SuperTabNativeContext } from '@prisma/client'import { z } from 'zod'import type { AuthUser } from '../lib/ssoAuth.js'import { isTeamSession, TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE } from '../lib/teamSession.js'import { activeWork, agent, appendPullRequestUrls, author, conversation, fail, isLeads, stableId, SuperTabError,type Actor, type Agent, type Author, type Conversation, type SuperTabState } from './model.js'-import { canReadProject, groupProject, readConversation } from './projects.js'+import { canReadGroup, groupProject, readConversation } from './projects.js'import { noteProjectReports } from './projectUpdates.js'+import { numberMessages, type Touch } from './parts/commit.js'import { redactCredentials } from './credentials.js'const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)@@ -24,9 +25,14 @@ interface Binding {tabId: string; conversationId: string; agentId: string; harnessId: string; machineId: string; machineOwnerId: stringoperator: Author; contributorId: string; contributionGeneration: string; contributionGrant: string | null; inputGrant: string | null}+interface Loaded { state: SuperTabState }interface Deps {transaction<T>(body: (tx: Transaction) => Promise<T>): Promise<T>- row(tx: Transaction, user: AuthUser, tabId: string): Promise<{ row: SuperTab; state: SuperTabState }>+ /** The Swarm loaded from its parts, with these groups even when dormant. */+ load(tx: Transaction, user: AuthUser, tabId: string, groupIds: string[]): Promise<Loaded>+ /** Writes what changed from the loaded state, touching the parts the write relied on (store.ts save). */+ save(tx: Transaction, loaded: Loaded, next: SuperTabState, stamp: number, touches: Touch[]): Promise<unknown>+ stamp(): numberagentGrant(tx: Transaction, state: SuperTabState, target: Agent): Promise<void>contribution(tx: Transaction, state: SuperTabState, actor: Actor, command: { machineId: string }): Promise<Grant>/** The one machine a team session (lib/teamSession.ts) hosts for; null for any other sign-in. */@@ -82,7 +88,7 @@ export class SuperTabNativeStore {if (isTeamSession(user)) fail(TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE, 403)const request = openNativeSchema.parse(input)return this.deps.transaction(async tx => {- const { state } = await this.deps.row(tx, user, tabId)+ const { state } = await this.deps.load(tx, user, tabId, [request.conversationId])const operator = author(state, { kind: 'person', userId: user.sub, email: user.email }, true)const target = agent(state, request.agentId)const group = readConversation(state, { kind: 'person', userId: user.sub, email: user.email }, request.conversationId)@@ -108,16 +114,16 @@ export class SuperTabNativeStore {}private async hosted(tx: Transaction, user: AuthUser, tabId: string, contextId: string) {- const { row, state } = await this.deps.row(tx, user, tabId)const record = await tx.superTabNativeContext.findFirst({ where: { id: contextId, tabId } })?? fail('NOT_FOUND', 'This terminal context is unavailable.', 404)+ const loaded = await this.deps.load(tx, user, tabId, [record.conversationId]), state = loaded.stateconst binding = record.binding as unknown as Bindingif (binding.machineOwnerId !== user.sub) fail('FORBIDDEN', 'Only the execution host can record this terminal.', 403)// A team session records only the terminals of its own machine's agents.const team = await this.deps.teamHost(tx, user)if (team !== null && binding.machineId !== team) fail(TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE, 403)const verified = await this.validate(tx, state, record)- return { ...verified, row, state, record, team: team !== null }+ return { ...verified, loaded, record, team: team !== null }}async read(user: AuthUser, tabId: string, contextId: string) {@@ -137,7 +143,7 @@ export class SuperTabNativeStore {}private async recovery(tx: Transaction, tabId: string, group: Conversation, target: Agent, record: SuperTabNativeContext,- event: NativeEvent, eventId: string, revision: number): Promise<{ source: Recovery; text: string } | null> {+ event: NativeEvent, eventId: string): Promise<{ source: Recovery; text: string } | null> {const assignment = group.assignment// A recording gap can also mean ordinary human typing or an expired view.// Older recorders do not distinguish those, so only known interruptions wake the Lead.@@ -172,14 +178,16 @@ export class SuperTabNativeStore {+ `${next} Do not replay earlier input or commands; they may already have taken effect.`if (required && assignment.status === 'working') { assignment.status = 'blocked'; assignment.result = text }if (!prior) await tx.superTabOperation.create({ data: { id: receiptId, tabId, actorKey: `agent:${target.id}`,- requestHash: digest([assignment.id, incidentId]), revision, result: json({ eventId, recovery }) } })+ requestHash: digest([assignment.id, incidentId]), revision: 0, result: json({ eventId, recovery }) } })return { source: recovery, text }}async append(user: AuthUser, tabId: string, contextId: string, input: NativeEvent) {const event = nativeEventSchema.parse(input)return this.deps.transaction(async tx => {- const { row, state, record, binding, target, group, team } = await this.hosted(tx, user, tabId, contextId)+ const { loaded, record, binding, team } = await this.hosted(tx, user, tabId, contextId)+ const state = structuredClone(loaded.state)+ const target = agent(state, record.agentId), group = conversation(state, record.conversationId)const eventId = stableId('native-event', contextId, event.turnId, event.kind), requestHash = digest(event)const prior = await tx.superTabOperation.findUnique({ where: { id: eventId } })if (prior) {@@ -191,9 +199,7 @@ export class SuperTabNativeStore {if (event.kind === 'answer' && !await tx.superTabOperation.findUnique({ where: { id: promptId } })) {fail('NATIVE_PROMPT_MISSING', 'The terminal prompt was not recorded. Record the observation gap first.')}- const revision = row.revision + 1- const recovery = await this.recovery(tx, tabId, group, target, record, event, eventId, revision)- group.lastMessageSequence = revision+ const recovery = await this.recovery(tx, tabId, group, target, record, event, eventId)const observedBy = author(state, { kind: 'agent', agentId: target.id, machineOwnerId: user.sub }, true)// What a person typed in the terminal, or the agent answered, is recorded without any credential in it.const text = recovery?.source.required ? recovery.text : event.kind === 'gap'@@ -203,7 +209,14 @@ export class SuperTabNativeStore {// Inform the coordinating lead without replaying this input into the agent// that already received it. Its resulting programmatic turn is not native input.const recipients = (event.kind !== 'gap' || recovery?.source.required) && group.leadId && group.leadId !== target.id ? [group.leadId] : []- await tx.superTabMessage.create({ data: { id: eventId, tabId, conversationId: group.id, sequence: revision,+ const draft = { id: eventId, conversationId: group.id, author: observedBy, text, replyTo: null, recipients }+ const now = Date.now(), sequences = numberMessages(state, [draft], now), sequence = sequences.get(eventId)!+ noteProjectReports(state, [draft], sequences, now)+ // The turn touches its agent (spec ruling 2). The person who opened the terminal is guarded by this context's row,+ // which the turn writes: removing that person, or taking away their access, revokes the context (rule b,+ // revokeNativeContexts). Touching the person instead would make one person's terminals in different groups conflict.+ await this.deps.save(tx, loaded, state, this.deps.stamp(), [{ kind: 'agent', key: target.id }])+ await tx.superTabMessage.create({ data: { id: eventId, tabId, conversationId: group.id, sequence,author: json(observedBy), source: json({ kind: 'native', phase: event.kind, turnId: event.turnId,operator: binding.operator, truncated: event.truncated, interrupted: event.interrupted, ...(recovery ? { recovery: recovery.source } : {}) }),text, replyTo: event.kind === 'answer' ? promptId : null, recipientIds: recipients } })@@ -219,12 +232,9 @@ export class SuperTabNativeStore {? { authorKind: 'agent', authorId: target.id, authorGeneration: target.membershipGeneration }: { authorKind: 'person', authorId: binding.operator.id, authorGeneration: binding.operator.membershipGeneration }) } })}- noteProjectReports(state, [{ id: eventId, conversationId: group.id, author: observedBy, text,- replyTo: null, recipients }], revision, Date.now())- await tx.superTab.update({ where: { id: tabId, revision: row.revision }, data: { revision, state: json(state) } })await tx.superTabNativeContext.update({ where: { id: contextId }, data: { lastEventId: eventId } })- const result = { eventId, revision }- await tx.superTabOperation.create({ data: { id: eventId, tabId, actorKey: `agent:${target.id}`, requestHash, revision, result } })+ const result = { eventId, sequence }+ await tx.superTabOperation.create({ data: { id: eventId, tabId, actorKey: `agent:${target.id}`, requestHash, revision: 0, result } })return result})}@@ -237,14 +247,19 @@ export async function revokeNativeContexts(tx: Transaction, before: SuperTabStatconst current = after.people.find(p => p.id === member.id)if (!current || current.generation !== member.generation || current.role === 'viewer') conditions.push({ userId: member.id })}- for (const target of before.agents) if (!after.agents.some(a => a.id === target.id)) conditions.push({ agentId: target.id })+ // A removed agent's contexts, and those of an agent given a replacement terminal: they name the old terminal, and its+ // waiting turns are cancelled with them, so a claim racing the change conflicts on their rows (rule b).+ for (const target of before.agents) {+ const current = after.agents.find(a => a.id === target.id)+ if (!current || current.harnessId !== target.harnessId) conditions.push({ agentId: target.id })+ }for (const group of before.conversations) {const current = after.conversations.find(c => c.id === group.id)if (!current || current.archived) conditions.push({ conversationId: group.id })// No terminal opens in the Leads conversation (open), so it holds no context to revoke.else if (!isLeads(current)) {for (const member of after.people) {- if (!canReadProject(after, { kind: 'person', userId: member.id, email: member.email }, groupProject(after, current))) {+ if (!canReadGroup(after, { kind: 'person', userId: member.id, email: member.email }, current)) {conditions.push({ conversationId: group.id, userId: member.id })}}diff --git a/backend/src/superTabs/parts/clock.test.ts b/backend/src/superTabs/parts/clock.test.tsnew file mode 100644index 000000000..77f1a50ec--- /dev/null+++ b/backend/src/superTabs/parts/clock.test.ts@@ -0,0 +1,16 @@+import { describe, expect, it } from 'vitest'+import { createClock } from './clock.js'++describe('part write clock', () => {+ it('never stamps the same or an earlier time twice, even when the wall clock stands still or goes back', () => {+ const wall = [1000, 1000, 999, 1000]+ const clock = createClock(() => wall.shift()!)+ expect([clock.next(), clock.next(), clock.next(), clock.next()]).toEqual([1000, 1001, 1002, 1003])+ })++ it('follows the wall clock once it is ahead again', () => {+ const wall = [1000, 1000, 5000]+ const clock = createClock(() => wall.shift()!)+ expect([clock.next(), clock.next(), clock.next()]).toEqual([1000, 1001, 5000])+ })+})diff --git a/backend/src/superTabs/parts/clock.ts b/backend/src/superTabs/parts/clock.tsnew file mode 100644index 000000000..3fcd1d49c--- /dev/null+++ b/backend/src/superTabs/parts/clock.ts@@ -0,0 +1,8 @@+/** Stamps `changedAt` on part writes: this process's wall clock, made strictly increasing (design section 3.3). Readers+ * ask for changes after their cursor minus an overlap that covers drift between processes and the longest transaction. */+export function createClock(now: () => number = Date.now) {+ let last = 0+ return { next(): number { last = Math.max(now(), last + 1); return last } }+}++export const clock = createClock()diff --git a/backend/src/superTabs/parts/commit.test.ts b/backend/src/superTabs/parts/commit.test.tsnew file mode 100644index 000000000..fcef77806--- /dev/null+++ b/backend/src/superTabs/parts/commit.test.ts@@ -0,0 +1,79 @@+import { describe, expect, it } from 'vitest'+import { createSuperTab } from '../model.js'+import { capReleased, departedAgents, hostMarker, visibilityChanged } from './commit.js'++describe('writing a Swarm\'s parts', () => {+ it('keeps the newest 200 released harnesses of each machine and drops the oldest', () => {+ const state = createSuperTab('tab', 'Pilot', { id: 'owner', email: '[email protected]' }, 'prod')+ state.releasedHarnesses = [...Array.from({ length: 205 }, (_, i) => ({ machineId: 'busy', harnessId: `h${i}` })), { machineId: 'quiet', harnessId: 'only' }]+ capReleased(state)+ const busy = state.releasedHarnesses.filter(r => r.machineId === 'busy').map(r => r.harnessId)+ expect(busy).toHaveLength(200)+ expect(busy[0]).toBe('h5')+ expect(busy.at(-1)).toBe('h204')+ expect(state.releasedHarnesses.filter(r => r.machineId === 'quiet')).toEqual([{ machineId: 'quiet', harnessId: 'only' }])+ })++ it('moves the visibility epoch when who sees what changes, and not for an ordinary write', () => {+ const before = createSuperTab('tab', 'Pilot', { id: 'owner', email: '[email protected]' }, 'prod')+ const renamed = structuredClone(before)+ renamed.name = 'Renamed'+ expect(visibilityChanged(before, renamed)).toBe(false)+ const privateProject = structuredClone(before)+ privateProject.projects![0]!.visibility = 'private'+ expect(visibilityChanged(before, privateProject)).toBe(true)+ const withAudience = structuredClone(before)+ withAudience.conversations.push({ id: 'c', projectId: 'lead', title: 'C', leadId: null, agentIds: [], archived: false, brief: '', checks: [],+ assignment: null, lastMessageSequence: 0, audience: { people: [{ id: 'owner', generation: 'tab' }] } })+ const narrowed = structuredClone(withAudience)+ narrowed.conversations.at(-1)!.audience = { people: [] }+ expect(visibilityChanged(withAudience, narrowed)).toBe(true)+ })+})++describe('what a write tells host reads (review round 1)', () => {+ const pool = { machineId: 'mac', name: 'Mac', contributorId: 'owner', membershipGeneration: 'tab', generation: 'g1', cwd: '/repo', engines: ['codex'],+ maxAgents: 2, paused: false }+ const machine = (change: Record<string, unknown> = {}, observation?: Record<string, unknown>) => ({ machineId: 'mac', reservations: [], released: [],+ closingSessions: [], cleanups: [], ...change, contribution: { ...pool, ...(observation ? { observation } : {}) } })+ const reading = (receivedAt: number) => ({ generation: 'g1', receivedAt, resources: {}, tools: {}, quotas: [], runningHarnessIds: [], stoppedHarnessIds: [] })+ const none = new Map<string, string>()++ it('leaves the settings marker alone when only the machine\'s reading changed', () => {+ expect(hostMarker('machine', machine({}, reading(1)), machine({}, reading(2)), none, 9)).toEqual({})+ expect(hostMarker('machine', machine(), machine({}, reading(2)), none, 9)).toEqual({})+ })++ it('moves it for a change to the machine\'s settings or ledger, and when the part is added or removed', () => {+ const at = { host: { hostChangedAt: new Date(9) } }+ const paused = machine({}, reading(2))+ paused.contribution.paused = true+ expect(hostMarker('machine', machine({}, reading(1)), paused, none, 9)).toEqual(at)+ expect(hostMarker('machine', machine(), machine({ reservations: [{ harnessId: 'h', generation: 'g', renewed: false }] }), none, 9)).toEqual(at)+ expect(hostMarker('machine', undefined, machine(), none, 9)).toEqual(at)+ expect(hostMarker('machine', machine(), undefined, none, 9)).toEqual(at)+ })++ it('names the machines of a group\'s agents and work before and after its write, the agent that left included', () => {+ const group = (agentIds: string[], executionMachineId?: string) => ({ id: 'g', title: 'G', leadId: null, agentIds, archived: false, brief: '', checks: [],+ lastMessageSequence: 0, assignment: executionMachineId ? { id: 'w', agentId: 'a', status: 'done', configuration: {}, result: null,+ execution: { machineId: executionMachineId, harnessId: 'h', machineOwnerId: 'o' } } : null })+ const machineOf = new Map([['leaving', 'm1'], ['staying', 'm2']])+ expect(hostMarker('group', group(['leaving', 'staying'], 'm3'), group(['staying']), machineOf, 9)).toEqual({ host: { hostMachineIds: ['m1', 'm2', 'm3'] } })+ expect(hostMarker('agent', {}, {}, machineOf, 9)).toEqual({})+ })+})++describe('agents a group write lets go (review round 2)', () => {+ const group = (agentIds: string[], worker?: string) => ({ id: 'g', title: 'G', leadId: null, agentIds, archived: false, brief: '', checks: [],+ lastMessageSequence: 0, assignment: worker ? { id: 'w', agentId: worker, status: 'working', configuration: {}, result: null,+ execution: { machineId: 'm', harnessId: 'h', machineOwnerId: 'o' } } : null })++ it('names the agents that left the group or its work, and nobody for a write that keeps everyone', () => {+ expect(departedAgents(group(['lead', 'loner']), group(['lead']))).toEqual(['loner'])+ expect(departedAgents(group(['lead'], 'worker'), group(['lead']))).toEqual(['worker'])+ expect(departedAgents(group(['lead', 'worker'], 'worker'), group(['lead', 'worker']))).toEqual([])+ expect(departedAgents(group(['lead']), group(['lead', 'new']))).toEqual([])+ expect(departedAgents(undefined, group(['lead']))).toEqual([])+ })+})diff --git a/backend/src/superTabs/parts/commit.ts b/backend/src/superTabs/parts/commit.tsnew file mode 100644index 000000000..43f549624--- /dev/null+++ b/backend/src/superTabs/parts/commit.ts@@ -0,0 +1,192 @@+import type { Prisma } from '@prisma/client'+import { agentOnly, conversation, fail, isLeads, type MessageDraft, type SuperTabState } from '../model.js'+import { split } from './shape.js'+import { guardedWrite, PartConflict, type HeadColumns, type HostColumns, type PartWrite } from './write.js'+import type { GroupData, MachineData, Part, PartKind, SwarmParts } from './types.js'+import { RELEASED_CAP } from './types.js'++type Transaction = Prisma.TransactionClient++/** A part a command relies on without changing it: touched so a concurrent change to it conflicts (design section 1). */+export interface Touch { kind: PartKind; key: string }+/** A part a command wrote, at its new version: the command reply (design section 4.7). */+export interface Written { kind: PartKind; key: string; version: number }++/** MongoDB limits a document to 16 MiB. A part leaves room for its columns and indexes (design section 1.4). */+export const PART_LIMIT_BYTES = 4 * 1024 * 1024++const LISTS = { member: 'members', agent: 'agents', group: 'groups', machine: 'machines', start: 'starts', progress: 'progress' } as const+type ListKind = keyof typeof LISTS++/** JSON with sorted keys, so two equal records compare equal whatever order a command built them in. */+function canonical(value: unknown): string {+ return JSON.stringify(value, (_key, item: unknown) => item && typeof item === 'object' && !Array.isArray(item)+ ? Object.fromEntries(Object.entries(item as Record<string, unknown>).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : item)+}++/**+ * Who sees what changed (design section 4.2): a project's visibility or members, a person removed or rejoined, the set of+ * Leads (the Leads conversation's members), a conversation's audience, or a project removed. Readers reload in full.+ */+export function visibilityChanged(before: SuperTabState, after: SuperTabState): boolean {+ const projects = (state: SuperTabState) => canonical((state.projects ?? []).map(p => [p.id, p.visibility, p.members]))+ const people = (state: SuperTabState) => canonical(state.people.map(p => [p.id, p.generation, p.role]))+ const leads = (state: SuperTabState) => canonical(state.conversations.filter(isLeads).map(c => c.agentIds))+ const audiences = (state: SuperTabState) => new Map(state.conversations.map(c => [c.id, canonical(c.audience ?? null)]))+ if (projects(before) !== projects(after) || people(before) !== people(after) || leads(before) !== leads(after)) return true+ const was = audiences(before)+ return [...audiences(after)].some(([id, audience]) => was.has(id) && was.get(id) !== audience)+}++/** The Swarm's index row (SuperTab): what hosts, invitations and member lists are looked up by (design section 2.3). */+export function indexesOf(state: SuperTabState) {+ return {+ memberIds: state.people.map(p => p.id), invitedEmails: state.invitations.map(i => i.email),+ machineIds: [...new Set([...state.agents.map(a => a.machineId), ...(state.machines ?? []).map(m => m.machineId),+ ...(state.closingSessions ?? []).map(c => c.machineId), ...(state.machineCleanups ?? []).map(c => c.machineId)])],+ cleanupMachineIds: [...new Set([...(state.machines ?? []).flatMap(m => m.removal ? [m.machineId] : []),+ ...(state.machineCleanups ?? []).map(c => c.machineId)])],+ }+}++/**+ * Numbers each message in its conversation (design section 1.1 D4): the conversation's counter moves by one per message, in+ * draft order. A shown message is the conversation's latest and wakes a dormant one; an agent-only notice is numbered but+ * shown to nobody. Returns each message's sequence.+ */+export function numberMessages(state: SuperTabState, messages: MessageDraft[], now: number): Map<string, number> {+ const sequences = new Map<string, number>()+ for (const message of messages) {+ const group = conversation(state, message.conversationId)+ const sequence = (group.messageSeq ?? state.sequenceBase ?? 0) + 1+ group.messageSeq = sequence+ sequences.set(message.id, sequence)+ if (agentOnly(message.source)) continue+ group.lastMessageSequence = sequence+ group.lastActivityAt = new Date(now).toISOString()+ delete group.dormant+ }+ return sequences+}++/** Keeps the newest RELEASED_CAP released harnesses of each machine (spec, Archive). */+export function capReleased(state: SuperTabState): void {+ const released = state.releasedHarnesses+ if (!released) return+ const count = new Map<string, number>()+ for (const entry of released) count.set(entry.machineId, (count.get(entry.machineId) ?? 0) + 1)+ if ([...count.values()].every(n => n <= RELEASED_CAP)) return+ const seen = new Map<string, number>()+ state.releasedHarnesses = released.filter(entry => {+ const index = (seen.get(entry.machineId) ?? 0) + 1+ seen.set(entry.machineId, index)+ return index > count.get(entry.machineId)! - RELEASED_CAP+ })+}++/**+ * Writes what a command changed (design section 3.1): each part whose data differs from what was loaded, each new part,+ * a tombstone for each removed one, a guarded touch for each part in `touches` it did not write, the head when its+ * counters or the visibility epoch move, and the index row when a person, invitation or machine reference was added or+ * removed. Every write is guarded by the version it was read at.+ */+/** A machine part without its machine's own reading: what that machine's host needs to hear about. */+const withoutReading = (data: unknown) => {+ const machine = data as MachineData | undefined+ return machine && { ...machine, contribution: machine.contribution && { ...machine.contribution, observation: undefined } }+}++/**+ * What a part write tells host reads (read/host.ts, review round 1), from the part's data before and after (undefined for+ * an insert or a removal): a machine's settings or ledger changed, not only its own reading; and which machines' hosts a+ * group's write concerned, by its agents and its work before and after, so an agent leaving its last group wakes its host.+ */+export function hostMarker(kind: PartKind, before: unknown, after: unknown, machineOf: ReadonlyMap<string, string>, stamp: number): { host?: HostColumns } {+ if (kind === 'machine') return canonical(withoutReading(before)) === canonical(withoutReading(after)) ? {} : { host: { hostChangedAt: new Date(stamp) } }+ if (kind !== 'group') return {}+ const machines = ([before, after] as Array<GroupData | undefined>).flatMap(g => g+ ? [...g.agentIds.flatMap(id => machineOf.get(id) ?? []), ...(g.assignment ? [g.assignment.execution.machineId] : [])] : [])+ return { host: { hostMachineIds: [...new Set(machines)] } }+}++/** The agents a group's write let go: in its members or its work before, in neither after. Each is written again, data+ * unchanged, so its host hears of it whatever later writes to the group leave in that group's marker (review round 2). */+export function departedAgents(before: unknown, after: unknown): string[] {+ const of = (group: GroupData | undefined) => new Set(group ? [...group.agentIds, ...(group.assignment ? [group.assignment.agentId] : [])] : [])+ const kept = of(after as GroupData | undefined)+ return [...of(before as GroupData | undefined)].filter(id => !kept.has(id))+}++export async function commitParts(tx: Transaction, loaded: { parts: SwarmParts; state: SuperTabState; row: { id: string; revision: number } },+ next: SuperTabState, opts: { stamp: number; touches?: Touch[] }): Promise<{ written: Written[]; versions: Map<string, number> }> {+ const { parts } = loaded, { stamp } = opts+ capReleased(next)+ const after = split(next, { tabId: parts.tabId, version: 0, now: stamp, messageBase: parts.sequenceBase })+ const writes: PartWrite[] = []+ const first = parts.sequenceBase + 1+ // An agent removed by this write is still in the loaded state, so its machine is known for the host marker.+ const machineOf = new Map([...loaded.state.agents, ...next.agents].map(a => [a.id, a.machineId]))+ const host = (kind: PartKind, before: unknown, after: unknown) => hostMarker(kind, before, after, machineOf, stamp)+ let referencesChanged = false+ for (const kind of Object.keys(LISTS) as ListKind[]) {+ const before = new Map(parts[LISTS[kind]].filter(p => !p.deleted).map(p => [p.key, p as Part]))+ const now = new Map((after[LISTS[kind]] as Part[]).map(p => [p.key, p]))+ let added = 0+ for (const [key, part] of now) {+ const prior = before.get(key)+ if (!prior) {+ writes.push({ op: 'insert', kind, key, data: part.data, ordinal: stamp + added++ / 1000, first, ...host(kind, undefined, part.data) })+ if (kind !== 'group' && kind !== 'start' && kind !== 'progress') referencesChanged = true+ } else if (canonical(prior.data) !== canonical(part.data)) {+ writes.push({ op: 'update', kind, key, seen: prior.version, data: part.data, ...host(kind, prior.data, part.data) })+ }+ }+ for (const [key, prior] of before) {+ if (now.has(key)) continue+ writes.push({ op: 'remove', kind, key, seen: prior.version, data: prior.data, ...host(kind, prior.data, undefined) })+ if (kind !== 'group' && kind !== 'start' && kind !== 'progress') referencesChanged = true+ }+ }+ const agentsWritten = new Set(writes.filter(w => w.kind === 'agent').map(w => w.key))+ for (const write of writes.filter((w): w is Extract<PartWrite, { op: 'update' }> => w.kind === 'group' && w.op === 'update')) {+ for (const id of departedAgents(parts.groups.find(g => g.key === write.key)!.data, write.data)) {+ const agent = parts.agents.find(a => a.key === id && !a.deleted), data = after.agents.find(a => a.key === id)?.data+ if (!agent || !data || agentsWritten.has(id)) continue+ agentsWritten.add(id)+ writes.push({ op: 'update', kind: 'agent', key: id, seen: agent.version, data })+ }+ }+ const epoch = parts.visibilityEpoch + (visibilityChanged(loaded.state, next) ? 1 : 0)+ const head: HeadColumns = { groupCounter: Math.max(parts.groupCounter, next.groupCounter ?? 0), visibilityEpoch: epoch, sequenceBase: parts.sequenceBase }+ if (canonical(parts.head.data) !== canonical(after.head.data) || head.groupCounter !== parts.groupCounter || epoch !== parts.visibilityEpoch) {+ writes.push({ op: 'update', kind: 'head', key: 'head', seen: parts.head.version, data: after.head.data, head })+ }+ if (canonical(indexesOf(loaded.state)) !== canonical(indexesOf(next))) referencesChanged = true+ for (const write of writes) {+ if ('data' in write && Buffer.byteLength(JSON.stringify(write.data)) > PART_LIMIT_BYTES) {+ fail('PART_TOO_LARGE', 'This Swarm record has reached its size limit.', 413)+ }+ }+ const versions = new Map<string, number>()+ const written: Written[] = []+ for (const write of writes) {+ const version = await guardedWrite(tx, parts.tabId, write, stamp)+ versions.set(`${write.kind}:${write.key}`, version)+ written.push({ kind: write.kind, key: write.key, version })+ }+ const all = [parts.head as Part, ...parts.members, ...parts.agents, ...parts.groups, ...parts.machines, ...parts.starts, ...parts.progress]+ for (const touch of opts.touches ?? []) {+ const key = `${touch.kind}:${touch.key}`+ if (versions.has(key)) continue+ const part = all.find(p => p.kind === touch.kind && p.key === touch.key && !p.deleted)+ if (!part) continue+ versions.set(key, await guardedWrite(tx, parts.tabId, { op: 'touch', kind: touch.kind, key: touch.key, seen: part.version }, stamp))+ }+ if (referencesChanged) {+ // Always written when a reference is added or removed, so two such commands conflict instead of one losing an id.+ const updated = await tx.superTab.updateMany({ where: { id: loaded.row.id, revision: loaded.row.revision },+ data: { revision: loaded.row.revision + 1, ...indexesOf(next) } })+ if (!updated.count) throw new PartConflict('head', 'index')+ }+ return { written, versions }+}diff --git a/backend/src/superTabs/parts/index.ts b/backend/src/superTabs/parts/index.tsnew file mode 100644index 000000000..dd2c031a5--- /dev/null+++ b/backend/src/superTabs/parts/index.ts@@ -0,0 +1,12 @@+/**+ * Swarm state by parts (docs/design/2026-10-26-swarm-state-parts.md, section 7.2): the interface the store, the read API+ * and the migration share.+ */++export * from './types.js'+export { clock, createClock } from './clock.js'+export { knownKind, reassemble, split, toLegacyState } from './shape.js'++export { insertParts, lastChangedAt, loadActive, loadAll, loadChanged, loadDormant } from './load.js'+export { loadLight } from './light.js'+export { guardedWrite, PartConflict, type PartWrite } from './write.js'diff --git a/backend/src/superTabs/parts/light.test.ts b/backend/src/superTabs/parts/light.test.tsnew file mode 100644index 000000000..5f84bc67f--- /dev/null+++ b/backend/src/superTabs/parts/light.test.ts@@ -0,0 +1,34 @@+import { describe, expect, it } from 'vitest'+import { activeWork, type Assignment, type Conversation, type WorkStatus } from '../model.js'+import { FINISHED, GROUP_FIELDS } from './light.js'++/** Every field a conversation and its assignment can carry: adding one to model.ts fails this file's typecheck until it is+ * here, and the test below until light.ts either projects it or names it as unread by reads (review of #1745). */+const assignment: Required<Assignment> = {+ id: 'w', agentId: 'a', status: 'working', configuration: { engine: 'codex', model: null, effort: null, contextWindow: null, engineVersion: null },+ execution: { machineId: 'm', harnessId: 'h', machineOwnerId: 'o' }, result: null, recordingProgress: { at: 1, revision: 1 }, leaseUntil: 1, progressAt: 1,+ lost: { reason: 'r', at: 1 },+}+const conversation: Required<Conversation> = {+ id: 'g', kind: 'leads', projectId: 'p', number: 1, title: 't', leadId: null, agentIds: [], archived: false, brief: '',+ task: { goal: '', changes: '', constraints: '', owns: [] }, reviewOf: 'r', checks: [], assignment, lastMessageSequence: 0, pullRequestUrls: [],+ messageSeq: 0, reportSeq: 0, dormant: false, lastActivityAt: '', audience: { people: [] }, lostAttempt: { id: 'w', agentId: 'a' },+}++describe('the light conversation projection (parts/light.ts)', () => {+ it('projects or deliberately leaves out every field a conversation and its assignment carry', () => {+ const fields = [...Object.keys(conversation).filter(k => k !== 'assignment'), ...Object.keys(assignment).map(k => `assignment.${k}`)]+ const projected: string[] = [...GROUP_FIELDS.always, ...GROUP_FIELDS.whenRunning]+ const named = [...projected, ...GROUP_FIELDS.unread].map(f => f === 'task.owns' ? 'task' : f)+ expect(fields.filter(f => !named.includes(f))).toEqual([])+ expect(GROUP_FIELDS.unread.filter(f => projected.includes(f))).toEqual([])+ })++ it('reads work as finished exactly where model.ts does, for every status', () => {+ const statuses: Record<WorkStatus, true> = { planned: true, working: true, needs_human: true, blocked: true, review: true, done: true,+ stopped: true, cancelled: true, reconciling: true, lost: true }+ for (const status of Object.keys(statuses) as WorkStatus[]) {+ expect([status, !FINISHED.includes(status)]).toEqual([status, activeWork({ ...conversation, assignment: { ...assignment, status } })])+ }+ })+})diff --git a/backend/src/superTabs/parts/light.ts b/backend/src/superTabs/parts/light.tsnew file mode 100644index 000000000..d742786d1--- /dev/null+++ b/backend/src/superTabs/parts/light.ts@@ -0,0 +1,104 @@+/**+ * Read-only loading for the read API (group 3b). The parts a change read or a host form needs, selected as `loadActive`+ * selects them, but conversations with only the fields those reads use: never a brief, a task (beyond its owned paths),+ * checks, or a finished work's result. Group 6's benchmark (b4b28aec8): an idle Desktop change read sent 2.8 KB and loaded+ * 1.17 MB, a whole reassembled Swarm, every 3 s per window. What these loads return is for reading checks, derived values+ * and host rows; it is never sent to a client as a conversation.+ */+import type { Prisma } from '@prisma/client'+import { activeWork, type Agent, type AgentStart } from '../model.js'+import type { GroupData, HeadData, Part, PartKind, SwarmParts } from './types.js'+import { delegate, partId, type PartRow } from './write.js'++type Transaction = Prisma.TransactionClient++/** Statuses of finished work, as model.ts activeWork reads them (light.test.ts holds every status to it). */+export const FINISHED: readonly string[] = ['done', 'stopped', 'cancelled', 'lost']+const running = { $and: [{ $ne: [{ $type: '$data.assignment.status' }, 'missing'] }, { $not: [{ $in: ['$data.assignment.status', FINISHED] }] }] }+/**+ * Which conversation fields a light load keeps. `always`: who reads it and who is in it, and how its work ended (a lost+ * task's worker awaits no decision, model.ts awaitingWorkers). `whenRunning`: what other projects' work and host rows read of+ * running work. `unread`: what visibility checks, derived values and host rows never read. light.test.ts fails when+ * model.ts gains a field this does not place.+ */+export const GROUP_FIELDS = {+ always: ['id', 'kind', 'projectId', 'leadId', 'agentIds', 'archived', 'audience', 'dormant', 'assignment.agentId', 'assignment.status', 'assignment.lost'],+ whenRunning: ['title', 'task.owns', 'assignment.id', 'assignment.execution', 'assignment.result'],+ unread: ['number', 'brief', 'reviewOf', 'checks', 'lastMessageSequence', 'pullRequestUrls', 'messageSeq', 'reportSeq', 'lastActivityAt', 'lostAttempt',+ 'assignment.configuration', 'assignment.recordingProgress', 'assignment.leaseUntil', 'assignment.progressAt'],+} as const+const LIGHT_GROUP = {+ _id: 0, key: 1, version: 1, changedAt: 1, ordinal: 1, dormant: 1,+ ...Object.fromEntries(GROUP_FIELDS.always.map(field => [`data.${field}`, 1])),+ ...Object.fromEntries(GROUP_FIELDS.whenRunning.map(field => [`data.${field}`, { $cond: [running, `$data.${field}`, '$$REMOVE'] }])),+}++/** A date as `aggregateRaw` returns it: Extended JSON. */+function ms(value: unknown): number {+ const date = (value as { $date?: unknown } | null)?.$date ?? value+ if (typeof date === 'string') return Date.parse(date)+ if (typeof date === 'number') return date+ return Number((date as { $numberLong?: string }).$numberLong)+}++function lightGroup(row: Record<string, unknown>): Part<GroupData> {+ const raw = (row.data ?? {}) as Partial<GroupData> & { task?: { owns?: string[] } }+ // A conversation with no work has nothing to project there; never read it as having work.+ // Finished work comes without its id, machine or result: placeholders keep the shape, and nothing reads them.+ const work = raw.assignment?.status ? raw.assignment as Partial<NonNullable<GroupData['assignment']>> : null+ const assignment = work && { id: '', execution: { machineId: '', harnessId: '', machineOwnerId: '' }, result: null, ...work }+ const data = { title: '', ...raw, brief: '', checks: [], assignment,+ ...(raw.task?.owns ? { task: { goal: '', changes: '', constraints: '', owns: raw.task.owns } } : {}) } as GroupData+ return { kind: 'group', key: row.key as string, version: row.version as number, changedAt: ms(row.changedAt), ordinal: row.ordinal as number, data,+ ...(row.dormant ? { dormant: true as const } : {}) }+}++/**+ * A worker with no stored decision and no running work is judged from its finished conversations (model.ts+ * awaitingWorkers): a lost task leaves none stored (liveness.ts). The 'working' selection then also needs every active+ * conversation such a worker is in, works in or leads, as a whole first load sees them (review of #1745).+ */+async function undecidedWork(agents: Part<Agent>[], groups: Part<GroupData>[], lightGroups: (match: Record<string, unknown>) => Promise<Part<GroupData>[]>) {+ const busy = new Set(groups.flatMap(g => [...g.data!.leadId ? [g.data!.leadId] : [], ...activeWork(g.data!) ? [g.data!.assignment!.agentId, ...g.data!.agentIds] : []]))+ const undecided = agents.filter(a => !a.data!.workDecision && !busy.has(a.key)).map(a => a.key)+ if (!undecided.length) return []+ return lightGroups({ dormant: false, key: { $nin: groups.map(g => g.key) },+ $or: [{ 'data.assignment.agentId': { $in: undecided } }, { 'data.leadId': { $in: undecided } }, { agentIds: { $in: undecided } }] })+}++const toPart = <T>(kind: PartKind, row: PartRow): Part<T> => ({ kind, key: row.key, version: row.version, changedAt: row.changedAt.getTime(),+ ordinal: row.ordinal, data: row.data as T })++/**+ * The live parts of one Swarm with conversations light. Conversations: every active one (`groups: 'active'`, as+ * `loadActive`), or only the Lead conversations and those with running work (`'working'`: what visibility and derived+ * values read once every finished worker's decision is stored); plus those named by id and those the named agents are in,+ * dormant ones too, and the active ones of the named projects. Starts: unfinished, or every live start with `includeRecentStarts`.+ */+export async function loadLight(tx: Transaction, tabId: string,+ opts: { groupIds?: string[]; agentIds?: string[]; projectIds?: string[]; includeRecentStarts?: boolean; groups?: 'active' | 'working' } = {}): Promise<SwarmParts> {+ const head = await tx.swarmHead.findUnique({ where: { id: partId(tabId, 'head') } })+ if (!head) throw Object.assign(new Error(`Swarm ${tabId} has no parts`), { code: 'PARTS_MISSING' })+ const live = { tabId, deleted: false }+ const starts = (await delegate(tx, 'start').findMany({ where: opts.includeRecentStarts ? live : { ...live, finishedAt: null } })).map(row => toPart<AgentStart>('start', row))+ const { projects, leadsConversationId, invitations } = head.data as unknown as HeadData+ // Besides the Lead conversations and running work, the conversations a start or an invitation names: a reader sees+ // those only alongside their conversation (model.ts visibleState).+ const working = [...projects ? projects.map(p => p.leadConversationId) : ['lead'], leadsConversationId ?? '',+ ...starts.map(s => s.data!.request.conversationId), ...invitations.map(i => i.conversationId)]+ const which = opts.groups === 'working' ? [{ key: { $in: working } }, { executionMachineId: { $ne: null } }] : [{ dormant: false }]+ const named = [...which, ...opts.groupIds?.length ? [{ key: { $in: opts.groupIds } }] : [], ...opts.agentIds?.length ? [{ agentIds: { $in: opts.agentIds } }] : [],+ ...opts.projectIds?.length ? [{ projectId: { $in: opts.projectIds }, dormant: false }] : [],+ // The Swarm's first project also holds conversations stored with no project (model.ts groupProject).+ ...opts.projectIds?.includes('lead') ? [{ projectId: null, dormant: false }] : []]+ const lightGroups = async (match: Record<string, unknown>) => (await tx.swarmGroup.aggregateRaw({ pipeline: [{ $match: { tabId, deleted: false, ...match } },+ { $project: LIGHT_GROUP }] }) as unknown as Array<Record<string, unknown>>).map(lightGroup)+ const [members, agents, machines, progress, groups] = await Promise.all([+ ...(['member', 'agent', 'machine'] as const).map(kind => delegate(tx, kind).findMany({ where: live }).then(rows => rows.map(row => toPart(kind, row)))),+ delegate(tx, 'progress').findMany({ where: live }).then(rows => rows.map(row => toPart('progress', row))),+ lightGroups({ $or: named }),+ ])+ if (opts.groups === 'working') groups.push(...await undecidedWork(agents as Part<unknown>[] as Part<Agent>[], groups as Part<GroupData>[], lightGroups))+ return { tabId, head: toPart<HeadData>('head', head as unknown as PartRow), members, agents, groups, machines, starts, progress,+ sequenceBase: head.sequenceBase, visibilityEpoch: head.visibilityEpoch, groupCounter: head.groupCounter } as SwarmParts+}diff --git a/backend/src/superTabs/parts/load.ts b/backend/src/superTabs/parts/load.tsnew file mode 100644index 000000000..846a73a25--- /dev/null+++ b/backend/src/superTabs/parts/load.ts@@ -0,0 +1,97 @@+import type { Prisma } from '@prisma/client'+import { delegate, extracted, partId, type PartRow } from './write.js'+import type { GroupData, HeadData, Part, PartKind, SwarmParts } from './types.js'+import { PART_KINDS } from './types.js'++type Transaction = Prisma.TransactionClient+type Where = Record<string, unknown>++const toPart = <T>(kind: PartKind, row: PartRow): Part<T> => ({ kind, key: row.key, version: row.version, changedAt: row.changedAt.getTime(),+ ordinal: row.ordinal, data: row.data as T, ...(row.deleted ? { deleted: true as const } : {}), ...(row.dormant ? { dormant: true as const } : {}) })++async function assemble(tx: Transaction, tabId: string, where: Record<Exclude<PartKind, 'head'>, Where>): Promise<SwarmParts> {+ const head = await tx.swarmHead.findUnique({ where: { id: partId(tabId, 'head') } })+ if (!head) throw Object.assign(new Error(`Swarm ${tabId} has no parts`), { code: 'PARTS_MISSING' })+ const [members, agents, groups, machines, starts, progress] = await Promise.all((['member', 'agent', 'group', 'machine', 'start', 'progress'] as const)+ .map(kind => delegate(tx, kind).findMany({ where: { tabId, ...where[kind] } }).then(rows => rows.map(row => toPart(kind, row)))))+ return { tabId, head: toPart<HeadData>('head', head as unknown as PartRow), members, agents, groups, machines, starts, progress,+ sequenceBase: head.sequenceBase, visibilityEpoch: head.visibilityEpoch, groupCounter: head.groupCounter } as SwarmParts+}++/**+ * The parts a command or read works on (design section 3.1): every live part except dormant groups and finished starts,+ * plus the groups named by id, the groups the named agents are in and the named projects' groups (dormant ones too),+ * and the finished starts named by id or by the agent they started.+ */+export function loadActive(tx: Transaction, tabId: string,+ opts: { groupIds?: string[]; agentIds?: string[]; projectIds?: string[]; startIds?: string[]; startAgentIds?: string[]+ /** Also the finished starts not yet expired (finished within 7 days), as a first load shows them (design section 4.3). */+ includeRecentStarts?: boolean+ /** Every live group, dormant ones too: for the rare reads that list across all of them (mentions, route decisions). */+ allGroups?: boolean } = {}): Promise<SwarmParts> {+ const live = { deleted: false }+ const or = (always: Where, ...named: Array<Where | false>) => ({ ...live, OR: [always, ...named.filter((w): w is Where => !!w)] })+ return assemble(tx, tabId, {+ member: live, agent: live, machine: live, progress: live,+ group: opts.allGroups ? live : or({ dormant: false }, !!opts.groupIds?.length && { key: { in: opts.groupIds } },+ !!opts.agentIds?.length && { agentIds: { hasSome: opts.agentIds } }, !!opts.projectIds?.length && { projectId: { in: opts.projectIds } },+ // A group stored with no project belongs to the default one (projects.ts groupProject), as in a Swarm from before projects.+ !!opts.projectIds?.includes('lead') && { projectId: null }, !!opts.projectIds?.includes('lead') && { projectId: { isSet: false } }),+ start: opts.includeRecentStarts ? live : or({ finishedAt: null }, !!opts.startIds?.length && { key: { in: opts.startIds } },+ !!opts.startAgentIds?.length && { agentId: { in: opts.startAgentIds } }),+ })+}++/** Every part of one Swarm, tombstones included with their last data (migration verification and rollback). */+export function loadAll(tx: Transaction, tabId: string): Promise<SwarmParts> {+ return assemble(tx, tabId, { member: {}, agent: {}, group: {}, machine: {}, start: {}, progress: {} })+}++/** Inserts a Swarm's parts as they are (the migration, a new Swarm). An existing part fails with P2002. */+export async function insertParts(tx: Transaction, parts: SwarmParts): Promise<void> {+ const { tabId } = parts+ const rows = (kind: PartKind, list: Part[]) => list.map(part => ({ id: partId(tabId, part.key), tabId, key: part.key, version: part.version,+ changedAt: new Date(part.changedAt), deleted: !!part.deleted, ordinal: part.ordinal, data: part.data as Prisma.InputJsonValue,+ ...extracted(kind, part.data, part.changedAt),+ ...(kind === 'head' ? { groupCounter: parts.groupCounter, visibilityEpoch: parts.visibilityEpoch, sequenceBase: parts.sequenceBase } : {}) }))+ for (const [kind, list] of [['head', [parts.head]], ['member', parts.members], ['agent', parts.agents], ['group', parts.groups],+ ['machine', parts.machines], ['start', parts.starts], ['progress', parts.progress]] as Array<[PartKind, Part[]]>) {+ if (list.length) await delegate(tx, kind).createMany({ data: rows(kind, list) })+ }+}++/** Parts of these Swarms whose data changed after `since`, by tab, each kind in turn. Tombstones and dormant groups come+ * with their last data and `deleted`/`dormant` set, so the reader can check who may see them before sending anything. */+export async function loadChanged(tx: Transaction, tabIds: string[], since: Date, kinds: readonly PartKind[] = PART_KINDS): Promise<Map<string, Part[]>> {+ const changed = new Map<string, Part[]>(tabIds.map(id => [id, []]))+ if (!tabIds.length) return changed+ for (const kind of kinds) {+ for (const row of await delegate(tx, kind).findMany({ where: { tabId: { in: tabIds }, changedAt: { gt: since } } })) {+ changed.get(row.tabId)!.push(toPart(kind, row))+ }+ }+ return changed+}++/** Dormant groups the caller pages through, newest activity first, 50 at a time. */+export async function loadDormant(tx: Transaction, tabId: string,+ page: { projectId?: string; before?: { lastActivityAt: number; key: string } }): Promise<Part<GroupData>[]> {+ const before = page.before && { OR: [{ lastActivityAt: { lt: new Date(page.before.lastActivityAt) } },+ { lastActivityAt: new Date(page.before.lastActivityAt), key: { lt: page.before.key } }] }+ const rows = await tx.swarmGroup.findMany({ where: { tabId, deleted: false, dormant: true, ...(page.projectId ? { projectId: page.projectId } : {}),+ ...before }, orderBy: [{ lastActivityAt: 'desc' }, { key: 'desc' }], take: 50 })+ return rows.map(row => toPart<GroupData>('group', row as unknown as PartRow))+}++/** The newest data change of each Swarm, over all its parts (design section 3.7). A touch does not count. */+export async function lastChangedAt(tx: Transaction, tabIds: string[]): Promise<Map<string, number>> {+ const newest = new Map<string, number>()+ if (!tabIds.length) return newest+ for (const kind of PART_KINDS) {+ for (const row of await delegate(tx, kind).groupBy({ by: ['tabId'], where: { tabId: { in: tabIds } }, _max: { changedAt: true } })) {+ const at = row._max.changedAt?.getTime() ?? 0+ if (at > (newest.get(row.tabId) ?? 0)) newest.set(row.tabId, at)+ }+ }+ return newest+}diff --git a/backend/src/superTabs/parts/shape.test.ts b/backend/src/superTabs/parts/shape.test.tsnew file mode 100644index 000000000..7a4531a74--- /dev/null+++ b/backend/src/superTabs/parts/shape.test.ts@@ -0,0 +1,112 @@+import { describe, expect, it } from 'vitest'+import type { SuperTabState } from '../model.js'+import { reassemble, split, toLegacyState } from './shape.js'++const configuration = { engine: 'codex', model: null, effort: null, contextWindow: null, engineVersion: null }+const agent = (id: string, machineId: string, projectId = 'p1') => ({ id, projectId, machineId, harnessId: `h-${id}`, machineOwnerId: 'u1',+ contributorId: 'u1', membershipGeneration: 'g1', name: id, displayName: id.toUpperCase(), configuration })+const group = (id: string, extra: Record<string, unknown> = {}) => ({ id, projectId: 'p1', title: id, leadId: 'a1', agentIds: ['a1'],+ archived: false, brief: '', checks: [], assignment: null, lastMessageSequence: 0, pullRequestUrls: [], ...extra })++/** A Swarm as `SuperTab.state` holds it before parts, with a record of every kind. */+function legacy(): SuperTabState {+ return {+ version: 1, id: 'tab1', name: 'Pilot', ownerId: 'u1', environment: 'prod', paused: false,+ leadsConversationId: 'leads', overlapAlerts: ['g2:g3'], retiredConversationNumber: 7,+ projects: [{ id: 'p1', name: 'One', ownerId: 'u1', leadConversationId: 'lead1', visibility: 'public', members: [], updateMinutes: 5,+ progress: { dirtyRevision: 95, summarizedRevision: 90, requestedRevision: 80, since: 111, requestedAt: 222, requestMessageId: 'm1' } }],+ people: [{ id: 'u1', email: '[email protected]', role: 'owner', generation: 'g1' }, { id: 'u2', email: '[email protected]', role: 'viewer', generation: 'g2' }],+ agents: [agent('a1', 'mac'), agent('a2', 'other')],+ conversations: [+ group('lead1', { lastMessageSequence: 40 }),+ group('g2', { number: 3, lastMessageSequence: 100 }),+ group('g3', { number: 5, lastMessageSequence: 92 }),+ { id: 'leads', kind: 'leads', title: 'Leads', leadId: null, agentIds: ['a1'], archived: false, brief: '', checks: [], assignment: null, lastMessageSequence: 0 },+ ],+ parkedConversations: [{ ...group('later'), kind: 'later' as never }],+ invitations: [{ id: 'i1', email: '[email protected]', role: 'viewer', conversationId: 'lead1', expiresAt: 999 }],+ starts: [{ id: 's1', creationId: 'super-s1', actorKey: 'agent:a1', contributorId: 'u1', membershipGeneration: 'g1', machineOwnerId: 'u1',+ hostGrant: null, harnessId: null, dispatched: false, error: null,+ request: { conversationId: 'g2', machineId: 'mac', engine: 'codex', name: 'B', cwd: '/w', worktree: false,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } } }],+ machines: [{ machineId: 'mac', name: 'Mac', contributorId: 'u1', membershipGeneration: 'g1', generation: 'op1', cwd: '/w', engines: ['codex'], maxAgents: 2, paused: false }],+ harnessReservations: [{ machineId: 'mac', harnessId: 'h-a1', generation: 'op2', renewed: false }, { machineId: 'other', harnessId: 'h-a2', generation: 'op3', renewed: true }],+ releasedHarnesses: [{ machineId: 'other', harnessId: 'old' }],+ closingSessions: [{ agentId: 'gone', machineId: 'third', harnessId: 'h-gone', machineOwnerId: 'u1' }],+ machineCleanups: [{ machineId: 'removed', removalId: 'r1', machineOwnerId: 'u1' }],+ } as unknown as SuperTabState+}++describe('splitting a Swarm into parts', () => {+ it('gives every person, agent, conversation, start and project its own part, and keeps every id', () => {+ const parts = split(legacy(), { tabId: 'tab1', version: 500, now: 1000 })+ expect(parts.members.map(p => p.key)).toEqual(['u1', 'u2'])+ expect(parts.agents.map(p => p.key)).toEqual(['a1', 'a2'])+ expect(parts.groups.map(p => p.key)).toEqual(['lead1', 'g2', 'g3', 'leads', 'later'])+ expect(parts.starts.map(p => p.key)).toEqual(['s1'])+ expect(parts.progress.map(p => p.key)).toEqual(['p1'])+ expect([parts.head, ...parts.members, ...parts.groups].every(p => p.version === 500 && p.changedAt === 1000)).toBe(true)+ })++ it('keeps a slot ledger for every machine the Swarm references, contributed or not', () => {+ const machines = split(legacy(), { tabId: 'tab1', version: 500, now: 1000 }).machines+ expect(machines.map(p => p.key)).toEqual(['mac', 'other', 'third', 'removed'])+ expect(machines.map(p => p.data!.contribution?.name ?? null)).toEqual(['Mac', null, null, null])+ expect(machines[1]!.data).toEqual({ machineId: 'other', contribution: null,+ reservations: [{ harnessId: 'h-a2', generation: 'op3', renewed: true }], released: ['old'], closingSessions: [], cleanups: [] })+ expect(machines[2]!.data!.closingSessions).toEqual([{ agentId: 'gone', harnessId: 'h-gone', machineOwnerId: 'u1' }])+ expect(machines[3]!.data!.cleanups).toEqual([{ removalId: 'r1', machineOwnerId: 'u1' }])+ })++ it('keeps the progress out of the head and turns it into a watermark: every group carries its report sequence', () => {+ const parts = split(legacy(), { tabId: 'tab1', version: 500, now: 1000 })+ expect((parts.head.data!.projects![0] as Record<string, unknown>).progress).toBeUndefined()+ expect(parts.progress[0]!.data).toEqual({ since: 111, summarizedFloor: 90, summarized: {}, requestedFloor: 80, requested: {},+ requestedAt: 222, requestMessageId: 'm1' })+ // A report counts up to the project's dirty revision; a later notice in the group is not a report.+ expect(Object.fromEntries(parts.groups.map(p => [p.key, p.data!.reportSeq]))).toEqual({ lead1: 0, g2: 95, g3: 92, leads: 0, later: undefined })+ })++ it('numbers its messages and workgroups after everything before the split', () => {+ const parts = split(legacy(), { tabId: 'tab1', version: 500, now: 1000 })+ expect(parts.groups.filter(p => p.key !== 'later').every(p => p.data!.messageSeq === 500)).toBe(true)+ // A conversation of a kind a later release added is kept exactly as that release wrote it.+ expect(parts.groups.find(p => p.key === 'later')!.data).toEqual(legacy().parkedConversations![0])+ expect(parts.sequenceBase).toBe(500)+ expect(parts.groupCounter).toBe(7)+ })+})++describe('reassembling a Swarm from its parts', () => {+ it('gives back the state it was split from, field by field, in the stored shape', () => {+ expect(toLegacyState(reassemble(split(legacy(), { tabId: 'tab1', version: 500, now: 1000 })))).toEqual(legacy())+ })++ it('keeps the part-only fields commands use', () => {+ const state = reassemble(split(legacy(), { tabId: 'tab1', version: 500, now: 1000 }))+ expect(state.conversations.find(c => c.id === 'g2')).toMatchObject({ messageSeq: 500, reportSeq: 95 })+ expect(state.groupCounter).toBe(7)+ expect(state.sequenceBase).toBe(500)+ expect(state.projects![0]!.progress).toMatchObject({ summarizedFloor: 90, summarized: {} })+ })++ it('leaves out removed parts', () => {+ const parts = split(legacy(), { tabId: 'tab1', version: 500, now: 1000 })+ parts.agents[1] = { ...parts.agents[1]!, deleted: true }+ parts.groups[2] = { ...parts.groups[2]!, deleted: true }+ const state = reassemble(parts)+ expect(state.agents.map(a => a.id)).toEqual(['a1'])+ expect(state.conversations.map(c => c.id)).not.toContain('g3')+ })++ it('reports a project dirty again after a rollback when a group posted past what was summarized', () => {+ const parts = split(legacy(), { tabId: 'tab1', version: 500, now: 1000 })+ const state = reassemble(parts)+ const g3 = state.conversations.find(c => c.id === 'g3')!+ g3.reportSeq = 503+ const progress = state.projects![0]!.progress as unknown as { summarized: Record<string, number> }+ progress.summarized = { g2: 501 }+ expect(toLegacyState(state).projects![0]!.progress).toEqual({ dirtyRevision: 503, summarizedRevision: 90, requestedRevision: 80,+ since: 111, requestedAt: 222, requestMessageId: 'm1' })+ })+})diff --git a/backend/src/superTabs/parts/shape.ts b/backend/src/superTabs/parts/shape.tsnew file mode 100644index 000000000..a226121bd--- /dev/null+++ b/backend/src/superTabs/parts/shape.ts@@ -0,0 +1,157 @@+import type { AgentStart, Conversation, SuperTabState } from '../model.js'+import { isLeads, nextConversationNumber } from '../model.js'+import type { ContributedMachine, MachineCleanup } from '../machines.js'+import type { SwarmProject } from '../projects.js'+import type { HeadData, MachineData, Part, PartKind, ProgressData, SwarmParts } from './types.js'++/** The legacy report progress (`SuperTab.state`), in tab revisions. */+interface LegacyProgress { dirtyRevision: number; summarizedRevision: number; requestedRevision: number; since: number; requestedAt?: number; requestMessageId?: string }++/** Conversation kinds this release knows; a part of another kind is kept aside unchanged (model.ts parkLaterConversations). */+export const knownKind = (group: Conversation) => group.kind == null || group.kind === 'leads'+const PART_ONLY_GROUP_FIELDS = ['messageSeq', 'reportSeq', 'dormant', 'lastActivityAt'] as const+/** Optional lists of `SuperTab.state` an empty one of which differs from an absent one (`[]` after the last machine left). */+const LISTS = ['parkedConversations', 'starts', 'machines', 'harnessReservations', 'releasedHarnesses', 'closingSessions', 'machineCleanups'] as const+const STATE_ONLY = ['people', 'agents', 'conversations', 'parkedConversations', 'starts', 'machines', 'harnessReservations',+ 'releasedHarnesses', 'closingSessions', 'machineCleanups', 'otherProjectsWork', 'groupCounter', 'sequenceBase'] as const++const isLegacyProgress = (progress: unknown): progress is LegacyProgress =>+ !!progress && typeof progress === 'object' && 'dirtyRevision' in progress++/** The project groups whose posts count toward its reports: not its Lead conversation, not the Leads conversation. */+const reportGroups = (conversations: Conversation[], project: Pick<SwarmProject, 'id' | 'leadConversationId'>) =>+ conversations.filter(c => !isLeads(c) && (c.projectId ?? 'lead') === project.id && c.id !== project.leadConversationId)++function part<T>(kind: PartKind, key: string, data: T, ordinal: number, version: number, now: number): Part<T> {+ return { kind, key, version, changedAt: now, ordinal, data }+}++function machineParts(state: SuperTabState): Map<string, MachineData> {+ const machines = new Map<string, MachineData>()+ const of = (machineId: string) => {+ let entry = machines.get(machineId)+ if (!entry) machines.set(machineId, entry = { machineId, contribution: null, reservations: [], released: [], closingSessions: [], cleanups: [] })+ return entry+ }+ for (const pool of state.machines ?? []) of(pool.machineId).contribution = pool+ for (const { machineId, harnessId, generation, renewed } of state.harnessReservations ?? []) of(machineId).reservations.push({ harnessId, generation, renewed })+ for (const { machineId, harnessId } of state.releasedHarnesses ?? []) of(machineId).released.push(harnessId)+ for (const { machineId, agentId, harnessId, machineOwnerId } of state.closingSessions ?? []) of(machineId).closingSessions.push({ agentId, harnessId, machineOwnerId })+ for (const { machineId, removalId, machineOwnerId } of state.machineCleanups ?? []) of(machineId).cleanups.push({ removalId, machineOwnerId })+ return machines+}++/**+ * One Swarm's state as parts, every part at `version` and `changedAt = now`. Accepts the legacy shape too (the+ * migration): legacy report progress becomes a watermark, and each group's report sequence is its last message capped+ * at the project's dirty revision, since a later notice in it was not a report (design section 6.1).+ */+export function split(state: SuperTabState, opts: { tabId: string; version: number; now: number; visibilityEpoch?: number;+ lastActivity?: ReadonlyMap<string, number>; messageBase?: number }): SwarmParts {+ const { version, now } = opts+ const head = Object.fromEntries(Object.entries(state).filter(([key]) => !(STATE_ONLY as readonly string[]).includes(key))) as HeadData+ if (state.projects) head.projects = state.projects.map(({ progress: _progress, ...project }) => project)+ const present = LISTS.filter(list => state[list] !== undefined)+ if (present.length) head.presentLists = present+ const dirty = new Map<string, number>()+ for (const project of state.projects ?? []) {+ if (!isLegacyProgress(project.progress)) continue+ for (const group of reportGroups(state.conversations, project)) dirty.set(group.id, Math.min(group.lastMessageSequence, project.progress.dirtyRevision))+ }+ // A conversation of a kind this release does not know is kept exactly as a later release wrote it.+ const groups = [...state.conversations, ...state.parkedConversations ?? []].map((group, i) => part('group', group.id, !knownKind(group) ? group : {+ ...group, messageSeq: group.messageSeq ?? opts.messageBase ?? version, reportSeq: group.reportSeq ?? dirty.get(group.id) ?? 0,+ lastActivityAt: group.lastActivityAt ?? new Date(opts.lastActivity?.get(group.id) ?? now).toISOString(),+ }, i, version, now))+ for (const entry of groups) if (entry.data?.dormant) entry.dormant = true+ const progress = (state.projects ?? []).flatMap((project, i) => {+ const stored = project.progress as LegacyProgress | ProgressData | undefined+ if (!stored) return []+ const data: ProgressData = isLegacyProgress(stored)+ ? { since: stored.since, summarizedFloor: stored.summarizedRevision, summarized: {}, requestedFloor: stored.requestedRevision, requested: {},+ ...(stored.requestedAt !== undefined ? { requestedAt: stored.requestedAt } : {}),+ ...(stored.requestMessageId !== undefined ? { requestMessageId: stored.requestMessageId } : {}) }+ : stored+ return [part('progress', project.id, data, i, version, now)]+ })+ return {+ tabId: opts.tabId,+ head: part('head', 'head', head, 0, version, now),+ members: state.people.map((person, i) => part('member', person.id, person, i, version, now)),+ agents: state.agents.map((agent, i) => part('agent', agent.id, agent, i, version, now)),+ groups,+ machines: [...machineParts(state).values()].map((machine, i) => part('machine', machine.machineId, machine, i, version, now)),+ starts: (state.starts ?? []).map((start, i) => part('start', start.id, start, i, version, now)),+ progress,+ sequenceBase: state.sequenceBase ?? version,+ visibilityEpoch: opts.visibilityEpoch ?? 1,+ groupCounter: state.groupCounter ?? nextConversationNumber(state) - 1,+ }+}++const live = <T>(parts: Part<T>[]): T[] => parts.filter(p => !p.deleted && p.data).sort((a, b) => a.ordinal - b.ordinal).map(p => p.data!)++/** The state commands run on: `SuperTab.state`'s shape, each list in part order, with the part-only group fields kept. */+export function reassemble(parts: SwarmParts): SuperTabState {+ const groups = live(parts.groups)+ const machines = live(parts.machines)+ const progress = new Map(parts.progress.filter(p => !p.deleted && p.data).map(p => [p.key, p.data!]))+ const flat = <T>(each: (machine: MachineData) => T[]) => machines.flatMap(each)+ const state: SuperTabState = {+ ...structuredClone(parts.head.data!),+ ...(parts.head.data!.projects ? { projects: parts.head.data!.projects.map(project => ({ ...structuredClone(project),+ ...(progress.has(project.id) ? { progress: structuredClone(progress.get(project.id)!) as unknown as SwarmProject['progress'] } : {}) })) } : {}),+ people: structuredClone(live(parts.members)),+ agents: structuredClone(live(parts.agents)),+ conversations: structuredClone(groups.filter(knownKind)),+ groupCounter: parts.groupCounter,+ sequenceBase: parts.sequenceBase,+ }+ const present = new Set<string>(parts.head.data!.presentLists ?? [])+ delete (state as { presentLists?: unknown }).presentLists+ const parked = groups.filter(group => !knownKind(group))+ const starts: AgentStart[] = live(parts.starts)+ const contributed: ContributedMachine[] = machines.flatMap(m => m.contribution ? [m.contribution] : [])+ const reservations = flat(m => m.reservations.map(r => ({ machineId: m.machineId, ...r })))+ const released = flat(m => m.released.map(harnessId => ({ machineId: m.machineId, harnessId })))+ const closing = flat(m => m.closingSessions.map(c => ({ agentId: c.agentId, machineId: m.machineId, harnessId: c.harnessId, machineOwnerId: c.machineOwnerId })))+ const cleanups: MachineCleanup[] = flat(m => m.cleanups.map(c => ({ machineId: m.machineId, removalId: c.removalId, machineOwnerId: c.machineOwnerId })))+ const list = <K extends typeof LISTS[number]>(key: K, items: NonNullable<SuperTabState[K]>) => {+ if (items.length || present.has(key)) state[key] = structuredClone(items)+ }+ list('parkedConversations', parked)+ list('starts', starts)+ list('machines', contributed)+ list('harnessReservations', reservations)+ list('releasedHarnesses', released)+ list('closingSessions', closing)+ list('machineCleanups', cleanups)+ return state+}++/**+ * The state in `SuperTab.state`'s shape (verification and rollback, design section 6.2): part-only group fields removed,+ * and each project's report watermark turned back into revisions. A project with a group past what was summarized or+ * requested keeps the floor, so the next report request still asks for it.+ */+export function toLegacyState(state: SuperTabState): SuperTabState {+ const legacy = structuredClone(state)+ delete legacy.groupCounter+ delete legacy.sequenceBase+ const strip = (group: Conversation) => { for (const field of PART_ONLY_GROUP_FIELDS) delete group[field] }+ for (const project of legacy.projects ?? []) {+ const stored = project.progress as unknown as ProgressData | undefined+ if (!stored || isLegacyProgress(stored)) continue+ const groups = reportGroups(state.conversations, project)+ const dirtyRevision = Math.max(0, ...groups.map(g => g.reportSeq ?? 0))+ const through = (marks: Record<string, number>, floor: number) => !Object.keys(marks).length ? floor+ : groups.every(g => (g.reportSeq ?? 0) <= (marks[g.id] ?? floor)) ? Math.max(floor, dirtyRevision) : floor+ project.progress = { dirtyRevision, summarizedRevision: through(stored.summarized, stored.summarizedFloor),+ requestedRevision: through(stored.requested, stored.requestedFloor), since: stored.since,+ ...(stored.requestedAt !== undefined ? { requestedAt: stored.requestedAt } : {}),+ ...(stored.requestMessageId !== undefined ? { requestMessageId: stored.requestMessageId } : {}) } as unknown as SwarmProject['progress']+ }+ legacy.conversations.forEach(strip)+ legacy.parkedConversations?.forEach(strip)+ return legacy+}diff --git a/backend/src/superTabs/parts/touches.test.ts b/backend/src/superTabs/parts/touches.test.tsnew file mode 100644index 000000000..c5d7841de--- /dev/null+++ b/backend/src/superTabs/parts/touches.test.ts@@ -0,0 +1,68 @@+import { describe, expect, it } from 'vitest'+import { applyCommand, type Command, type CommandContext } from '../commands.js'+import { createSuperTab, type Actor } from '../model.js'+import { touchesFor } from './touches.js'++const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }+const config = { engine: 'codex', model: 'm', effort: 'high', contextWindow: null, engineVersion: null }++/** A Swarm with a Lead and two workers, each with its own assigned group. */+function swarm() {+ let state = createSuperTab('tab', 'Pilot', { id: 'owner', email: owner.email }, 'prod')+ let n = 0+ const run = (command: Command, actor: Actor = owner, context: Partial<CommandContext> = {}) => {+ const before = state+ const effects = applyCommand(state, actor, command, { now: 1000, operationId: `op-${++n}`, ...context })+ state = effects.state+ return { effects, before, touches: touchesFor(command, actor, before, effects, context) }+ }+ const contribution = { contribution: { machineOwnerId: 'host-owner', contributorId: 'owner' } }+ const add = (harnessId: string, conversationId: string, lead = false) => run({ type: 'agent.add', conversationId, machineId: 'host', harnessId,+ name: harnessId, configuration: config, lead }, owner, contribution).effects.result.agentId as string+ const lead = add('lead', 'lead', true)+ const group = (title: string) => {+ const id = run({ type: 'conversation.create', title, brief: 'Do it', checks: [{ description: 'Done', independent: false }] }).effects.result.conversationId as string+ const worker = add(`${title}-worker`, id)+ const assignmentId = run({ type: 'work.assign', conversationId: id, agentId: worker }).effects.result.assignmentId as string+ return { id, worker, assignmentId }+ }+ const agentActor = (agentId: string): Actor => ({ kind: 'agent', agentId, machineOwnerId: 'host-owner' })+ return { run, lead, group, agentActor, get state() { return state } }+}+const has = (touches: Array<{ kind: string; key: string }>, kind: string, key: string) => touches.some(t => t.kind === kind && t.key === key)++describe('the parts a command touches (design section 1.2, column T)', () => {+ it('touches the actor\'s own part on every command', () => {+ const f = swarm(), a = f.group('A')+ expect(has(f.run({ type: 'message.send', conversationId: a.id, text: 'Hi', replyTo: null, recipientIds: [] }).touches, 'member', 'owner')).toBe(true)+ expect(has(f.run({ type: 'message.send', conversationId: a.id, text: 'Hi', replyTo: null, recipientIds: [] }, f.agentActor(a.worker)).touches, 'agent', a.worker)).toBe(true)+ })++ it('leaves a post\'s recipients alone, so workers posting to their Lead in different groups never meet on the Lead', () => {+ const f = swarm(), a = f.group('A')+ const { effects, touches } = f.run({ type: 'message.send', conversationId: a.id, text: 'Report', replyTo: null, recipientIds: [] }, f.agentActor(a.worker))+ expect(effects.messages[0]!.recipients).toEqual([f.lead])+ expect(has(touches, 'agent', f.lead)).toBe(false)+ })++ it('makes finishing work and the Lead\'s next start or assignment meet on the project\'s progress part', () => {+ const f = swarm(), a = f.group('A')+ f.run({ type: 'work.check', conversationId: a.id, assignmentId: a.assignmentId, checkId: f.state.conversations.find(c => c.id === a.id)!.checks[0]!.id,+ passed: true, evidence: 'Shown' }, f.agentActor(f.lead))+ const done = f.run({ type: 'work.status', conversationId: a.id, assignmentId: a.assignmentId, status: 'done', result: 'Shipped' }, f.agentActor(a.worker))+ expect(has(done.touches, 'progress', 'lead')).toBe(true)+ const cancelled = f.group('B')+ expect(has(f.run({ type: 'work.cancel', conversationId: cancelled.id, assignmentId: cancelled.assignmentId, reason: 'Not needed' }).touches, 'progress', 'lead')).toBe(true)+ const next = f.run({ type: 'conversation.create', title: 'C', brief: 'More', checks: [{ description: 'Done', independent: false }] }).effects.result.conversationId as string+ expect(has(f.run({ type: 'work.assign', conversationId: next, agentId: a.worker }).touches, 'progress', 'lead')).toBe(true)+ })++ it('makes two starts on one machine meet on its slot ledger and on the head', () => {+ const f = swarm()+ const request = { conversationId: 'lead', machineId: 'host', engine: 'codex', name: 'New', cwd: '/w', worktree: false,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }+ const { touches } = f.run({ type: 'agent.start', request }, owner, { contribution: { machineOwnerId: 'host-owner', contributorId: 'owner' } })+ expect(has(touches, 'machine', 'host')).toBe(true)+ expect(has(touches, 'head', 'head')).toBe(true)+ })+})diff --git a/backend/src/superTabs/parts/touches.ts b/backend/src/superTabs/parts/touches.tsnew file mode 100644index 000000000..f2cbe926d--- /dev/null+++ b/backend/src/superTabs/parts/touches.ts@@ -0,0 +1,162 @@+import type { Command, CommandContext } from '../commands.js'+import type { Actor, CommandEffects, SuperTabState } from '../model.js'+import { agentRole } from '../model.js'+import type { ContributedMachine } from '../machines.js'+import { agentProjectId, canReadProject, groupProject, projectsOf } from '../projects.js'+import type { Touch } from './commit.js'++/**+ * The parts a command relies on without writing them (design section 1.2, column T). A part the command also writes is+ * skipped when committing, so listing it here is harmless. Each touch is a guarded version bump: a concurrent command that+ * changes that part makes one of the two retry against the other's result.+ */+export function touchesFor(command: Command, actor: Actor, before: SuperTabState, effects: Pick<CommandEffects, 'state' | 'messages'>,+ context: Pick<CommandContext, 'delivery' | 'routeDecision'> = {}): Touch[] {+ const touches: Touch[] = []+ const group = (key: string | undefined) => { if (key) touches.push({ kind: 'group', key }) }+ const agent = (key: string | undefined) => { if (key && before.agents.some(a => a.id === key)) touches.push({ kind: 'agent', key }) }+ const member = (key: string | undefined) => { if (key && before.people.some(p => p.id === key)) touches.push({ kind: 'member', key }) }+ const head = () => touches.push({ kind: 'head', key: 'head' })+ const progress = (projectId: string | undefined) => { if (projectId && before.projects) touches.push({ kind: 'progress', key: projectId }) }+ const machine = (key: string) => touches.push({ kind: 'machine', key })+ const projectOfGroup = (id: string) => { const g = before.conversations.find(c => c.id === id); return g && !g.kind ? groupProject(before, g) : undefined }+ const leadGroupOf = (projectId: string | undefined) => projectsOf(before).find(p => p.id === projectId)?.leadConversationId+ /** The Lead check (`controls`, `mayDrive`, `ruleChange`) reads its project's Lead conversation (design D2). */+ const leadCheck = (projectId: string | undefined) => { if (actor.kind === 'agent') group(leadGroupOf(projectId)) }+ const agentProject = (id: string) => { const a = before.agents.find(x => x.id === id); return a && agentProjectId(before, a) }+ /** Every slot `machineSlots` counts for a start on this machine: the Mac and its team account share them (machines.ts). */+ const slots = (machineId: string) => {+ const pool = before.machines?.find(m => m.machineId === machineId)+ const mac: ContributedMachine | undefined = pool?.hostMachineId ? before.machines?.find(m => m.machineId === pool.hostMachineId) : pool+ for (const id of new Set([machineId, mac?.machineId, ...(before.machines ?? []).filter(m => mac && m.hostMachineId === mac.machineId).map(m => m.machineId)])) {+ if (id) machine(id)+ }+ }++ // D1: the actor's own part (spec ruling 2).+ if (actor.kind === 'person') member(actor.userId)+ else agent(actor.agentId)+ // D2: the group a command names, which it reads even when it does not write it.+ if ('conversationId' in command && command.type !== 'invite.create') group(command.conversationId)+ // D3: the agent a command names. Not a message's recipients: every recipient is in the conversation the message writes,+ // and removing an agent writes every conversation it is in (rule b), so the conversation guards it. Touching them would+ // make every worker's post touch its Lead, and posts in different groups would conflict again (spec goal 1).+ if ('agentId' in command) agent(command.agentId)+ // D9: a custom role choice reads the role sets on the head.+ if ('roleId' in command && command.roleId) head()+ if (command.type === 'agent.start' && command.request.roleId) head()++ switch (command.type) {+ case 'tab.rename': case 'tab.project': case 'tab.pause':+ if (actor.kind === 'agent') group('lead')+ break+ case 'machine.contribute':+ if (!before.machines?.some(m => m.machineId === command.machineId)) head()+ break+ case 'project.report': case 'project.repository': case 'project.skills':+ leadCheck(command.projectId)+ break+ case 'project.sharing':+ // Rule (b): everyone who loses the project sees the change through their own part (design section 1.2).+ for (const person of before.people) {+ const project = projectsOf(before).find(p => p.id === command.projectId)+ const after = projectsOf(effects.state).find(p => p.id === command.projectId)+ const reader = { kind: 'person' as const, userId: person.id, email: person.email }+ if (project && canReadProject(before, reader, project) && !(after && canReadProject(effects.state, reader, after))) member(person.id)+ }+ break+ case 'conversation.create': {+ const projectId = command.projectId ?? (actor.kind === 'agent' ? agentProject(actor.agentId) : 'lead')+ group(leadGroupOf(projectId))+ group(command.reviewOf)+ break+ }+ case 'agent.add': {+ head()+ const target = effects.state.agents.find(a => a.machineId === command.machineId && a.harnessId === command.harnessId)+ member(target?.contributorId)+ break+ }+ case 'agent.start':+ head()+ group(command.request.conversationId)+ slots(command.request.machineId)+ member(effects.state.starts?.find(s => !before.starts?.some(b => b.id === s.id))?.contributorId)+ progress(projectOfGroup(command.request.conversationId)?.id)+ break+ case 'agent.startDispatch': case 'agent.started': {+ const start = before.starts?.find(s => s.id === command.startId)+ if (!start) break+ group(start.request.conversationId)+ member(start.contributorId)+ if (command.type === 'agent.startDispatch') { slots(start.request.machineId); head(); progress(projectOfGroup(start.request.conversationId)?.id) }+ else head()+ break+ }+ case 'agent.release':+ leadCheck(agentProject(command.agentId))+ break+ case 'agent.rebind':+ machine(command.machineId)+ break+ case 'conversation.agent':+ head()+ break+ case 'delivery.resolve':+ if (context.delivery) {+ agent(context.delivery.agentId)+ group(context.delivery.conversationId)+ }+ break+ case 'work.assign': {+ head()+ progress(projectOfGroup(command.conversationId)?.id)+ const target = before.agents.find(a => a.id === command.agentId)+ const reviewers = before.conversations.find(c => c.id === command.conversationId)?.agentIds+ .filter(id => before.agents.some(a => a.id === id && agentRole(a) === 'reviewer')) ?? []+ for (const id of reviewers) agent(id)+ const unsettled = before.starts?.find(s => s.poolGeneration && !s.poolSettled && target && s.request.machineId === target.machineId && s.harnessId === target.harnessId)+ if (unsettled) touches.push({ kind: 'start', key: unsettled.id })+ break+ }+ case 'work.cancel':+ leadCheck(projectOfGroup(command.conversationId)?.id)+ progress(projectOfGroup(command.conversationId)?.id)+ break+ case 'work.status':+ // Finished work puts its worker's decision before the Lead (finishWorker): the Lead's next start, assignment or+ // route touches the same part, so it cannot pass over that decision on a stale read (design ruling R5).+ if (command.status === 'done' || command.status === 'stopped') progress(projectOfGroup(command.conversationId)?.id)+ break+ case 'work.define':+ if (before.conversations.find(c => c.id === command.conversationId)?.assignment) progress(projectOfGroup(command.conversationId)?.id)+ break+ case 'route.record': {+ head()+ progress(projectOfGroup(command.conversationId)?.id)+ const pick = command.decision.candidates.find(c => c.id === command.decision.pick)+ if (pick?.kind === 'member') agent(pick.agentId)+ break+ }+ case 'route.override': {+ const chosen = context.routeDecision?.record.candidates.find(c => c.id === command.candidateId)+ if (chosen?.kind === 'member') agent(chosen.agentId)+ group(context.routeDecision?.conversationId)+ break+ }+ case 'route.modelResult':+ group(context.routeDecision?.conversationId)+ break+ case 'conversation.audience': {+ // Rule (b): everyone the change removes sees it through their own part (design section 1.2).+ const kept = new Set(effects.state.conversations.find(c => c.id === command.conversationId)?.audience?.people.map(p => p.id))+ for (const person of before.conversations.find(c => c.id === command.conversationId)?.audience?.people ?? []) if (!kept.has(person.id)) member(person.id)+ group(leadGroupOf(projectOfGroup(command.conversationId)?.id))+ break+ }+ case 'agent.screen': case 'agent.input':+ leadCheck(agentProject(command.agentId))+ break+ }+ return touches+}diff --git a/backend/src/superTabs/parts/types.ts b/backend/src/superTabs/parts/types.tsnew file mode 100644index 000000000..417e3af8b--- /dev/null+++ b/backend/src/superTabs/parts/types.ts@@ -0,0 +1,82 @@+import type { Agent, AgentStart, Conversation, Person, SuperTabState } from '../model.js'+import type { ContributedMachine } from '../machines.js'+import type { SwarmProject } from '../projects.js'++/** The part collections a Swarm is stored in (docs/design/2026-10-26-swarm-state-parts.md, section 2). */+export type PartKind = 'head' | 'member' | 'agent' | 'group' | 'machine' | 'start' | 'progress'+export const PART_KINDS: readonly PartKind[] = ['head', 'member', 'agent', 'group', 'machine', 'start', 'progress']++/** One stored part. `data` is null only on a tombstone read without its last data. */+export interface Part<T = unknown> {+ kind: PartKind+ key: string+ /** Moves on every write and every guarded touch; never resets. */+ version: number+ /** Epoch ms of the last data change (or tombstone). A touch leaves it. */+ changedAt: number+ deleted?: true+ dormant?: true+ ordinal: number+ data: T | null+}++/** A project as the head keeps it: its report progress lives in its own part. */+export type HeadProject = Omit<SwarmProject, 'progress'>++/** The head: everything in `SuperTabState` that is not one of the other parts. */+export type HeadData = Omit<SuperTabState, 'people' | 'agents' | 'conversations' | 'parkedConversations' | 'starts' | 'machines'+ | 'harnessReservations' | 'releasedHarnesses' | 'closingSessions' | 'machineCleanups' | 'otherProjectsWork' | 'projects'+ | 'groupCounter' | 'sequenceBase'> & { projects?: HeadProject[]+ /** Which optional lists the state had, so an empty one comes back as `[]` and an absent one stays absent. */+ presentLists?: string[] }++/** A conversation with the fields only the part store keeps (section 2.2). */+export type GroupData = Conversation++/** Who may read a private conversation besides the project's Lead (section 4.8). */+export interface Audience { people: Array<{ id: string; generation: string }> }++/** One machine the Swarm references: its contribution (with observation), and its slot ledger. */+export interface MachineData {+ machineId: string+ contribution: ContributedMachine | null+ reservations: Array<{ harnessId: string; generation: string; renewed: boolean }>+ /** Harnesses a host proved stopped, oldest first, at most RELEASED_CAP. */+ released: string[]+ closingSessions: Array<{ agentId: string; harnessId: string; machineOwnerId: string }>+ cleanups: Array<{ removalId: string; machineOwnerId: string }>+}++/** One project's report watermark (section 3.6). Group sequences are per group; floors carry pre-split tab revisions. */+export interface ProgressData {+ /** When the project last went from clean to dirty. */+ since: number+ summarizedFloor: number+ summarized: Record<string, number>+ requestedFloor: number+ requested: Record<string, number>+ requestedAt?: number+ requestMessageId?: string+}++export interface SwarmParts {+ tabId: string+ head: Part<HeadData>+ members: Part<Person>[]+ agents: Part<Agent>[]+ groups: Part<GroupData>[]+ machines: Part<MachineData>[]+ starts: Part<AgentStart>[]+ progress: Part<ProgressData>[]+ /** The tab revision when the Swarm was split (0 for a Swarm born in parts). */+ sequenceBase: number+ visibilityEpoch: number+ groupCounter: number+}++/** Released harnesses kept per machine (spec, Archive). */+export const RELEASED_CAP = 200+/** Tombstones and finished starts are kept this long (spec rulings 5 and 6). */+export const RETENTION_MS = 7 * 86_400_000+/** A group with finished work and no message for this long leaves the active set (spec, Archive). */+export const DORMANT_AFTER_MS = 86_400_000diff --git a/backend/src/superTabs/parts/write.test.ts b/backend/src/superTabs/parts/write.test.tsnew file mode 100644index 000000000..4e98ee9fd--- /dev/null+++ b/backend/src/superTabs/parts/write.test.ts@@ -0,0 +1,28 @@+import { describe, expect, it } from 'vitest'+import { extracted } from './write.js'+import type { GroupData } from './types.js'++describe('the host-fields digest a conversation write stores (group 3b)', () => {+ const group = (change: Partial<GroupData> = {}): GroupData => ({ id: 'g', projectId: 'p', title: 'Work', leadId: 'lead', agentIds: ['lead', 'worker'],+ archived: false, brief: 'Do it', checks: [], lastMessageSequence: 10, messageSeq: 10, reportSeq: 10, lastActivityAt: '2026-10-26T10:00:00.000Z',+ assignment: { id: 'w', agentId: 'worker', status: 'working', configuration: { engine: 'codex', model: null, effort: null, contextWindow: null, engineVersion: null },+ execution: { machineId: 'm', harnessId: 'h', machineOwnerId: 'o' }, result: null }, ...change })+ const digest = (data: GroupData) => extracted('group', data, 1).hostDigest++ it('stays the same for a post, a rename or a new brief, which no host row shows', () => {+ const before = digest(group())+ expect(before).toMatch(/^[A-Za-z0-9_-]{16,}$/)+ expect(digest(group({ lastMessageSequence: 11, messageSeq: 11, reportSeq: 11, lastActivityAt: '2026-10-26T11:00:00.000Z', pullRequestUrls: ['x'] }))).toBe(before)+ expect(digest(group({ title: 'Renamed', brief: 'Something else', checks: [{ id: 'c', description: 'd', independent: false, evidence: 'e', passedBy: null }] }))).toBe(before)+ })++ it('changes with what host rows read, and differs between conversations: its id, members, the Lead, archiving, the project, privacy, and the work', () => {+ const before = digest(group())+ const work = group().assignment!+ for (const change of [{ id: 'another' }, { agentIds: ['lead'] }, { leadId: null }, { archived: true }, { projectId: 'q' }, { audience: { people: [] } },+ { assignment: { ...work, status: 'needs_human' as const } }, { assignment: { ...work, agentId: 'other' } }, { assignment: { ...work, result: 'Blocked on a key' } },+ { assignment: { ...work, execution: { ...work.execution, machineId: 'n' } } }, { assignment: null }]) {+ expect(digest(group(change))).not.toBe(before)+ }+ })+})diff --git a/backend/src/superTabs/parts/write.ts b/backend/src/superTabs/parts/write.tsnew file mode 100644index 000000000..9af04604a--- /dev/null+++ b/backend/src/superTabs/parts/write.ts@@ -0,0 +1,127 @@+import { createHash } from 'node:crypto'+import type { Prisma } from '@prisma/client'+import { activeWork, stableId, type AgentStart, type Agent } from '../model.js'+import type { GroupData, MachineData, PartKind } from './types.js'+import { RETENTION_MS } from './types.js'++type Transaction = Prisma.TransactionClient+const json = (value: unknown): Prisma.InputJsonValue => JSON.parse(JSON.stringify(value)) as Prisma.InputJsonValue++/** A part changed after it was read. Code P2034 so the transaction retries it like a Mongo write conflict (store.ts). */+export class PartConflict extends Error {+ readonly code = 'P2034'+ constructor(readonly kind: PartKind, readonly key: string) {+ super(`The ${kind} part ${key} changed after it was read.`)+ this.name = 'PartConflict'+ }+}++/** The head's own columns: they are not in its data. */+export interface HeadColumns { groupCounter: number; visibilityEpoch: number; sequenceBase: number }++export type PartWrite =+ /** `first`: a new key's version, the Swarm's sequence base + 1 (design section 2.1). */+ | { op: 'insert'; kind: PartKind; key: string; data: unknown; ordinal: number; first?: number; head?: HeadColumns; host?: HostColumns }+ | { op: 'update'; kind: PartKind; key: string; seen: number; data: unknown; head?: HeadColumns; host?: HostColumns }+ | { op: 'remove'; kind: PartKind; key: string; seen: number; data: unknown; host?: HostColumns }+ | { op: 'touch'; kind: PartKind; key: string; seen: number }++/** What a write tells host reads (read/host.ts), set by the commit that knows the part's data before and after. */+export interface HostColumns { hostChangedAt?: Date; hostMachineIds?: string[] }++/** The part model behind each kind. They share their columns (schema.prisma, Swarm state by parts). */+export function delegate(tx: Transaction, kind: PartKind) {+ const models = { head: tx.swarmHead, member: tx.swarmMember, agent: tx.swarmAgent, group: tx.swarmGroup,+ machine: tx.swarmMachine, start: tx.swarmStart, progress: tx.swarmProgress }+ return models[kind] as unknown as {+ findUnique(args: { where: { id: string } }): Promise<{ version: number; deleted: boolean } | null>+ findMany(args: unknown): Promise<PartRow[]>+ create(args: { data: Record<string, unknown> }): Promise<unknown>+ createMany(args: { data: Record<string, unknown>[] }): Promise<unknown>+ updateMany(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<{ count: number }>+ groupBy(args: unknown): Promise<Array<{ tabId: string; _max: { changedAt: Date | null } }>>+ }+}+export interface PartRow { id: string; tabId: string; key: string; version: number; changedAt: Date; deleted: boolean; ordinal: number; data: unknown+ dormant?: boolean; groupCounter?: number; visibilityEpoch?: number; sequenceBase?: number }++export const partId = (tabId: string, key: string) => `${tabId}:${key}`++/** A start leaves command state once it failed, or started and (when pooled) settled. */+export const startFinished = (start: AgentStart) => !!start.error || (!!start.harnessId && (!start.poolGeneration || !!start.poolSettled))++/** What host rows read of a conversation (read/hostRows.ts), with its id, as a short hash: a post, a rename or a new brief+ * leaves it, so the host form can answer 'unchanged' from this column alone (group 3b). */+function hostDigest(group: GroupData): string {+ const work = group.assignment+ return createHash('sha256').update(JSON.stringify([group.id, group.kind ?? null, group.projectId ?? null, group.archived, group.agentIds, group.leadId ?? null,+ !!group.audience, work ? [work.id, work.agentId, work.status, work.execution, work.result?.slice(0, 500) ?? null] : null])).digest('base64url').slice(0, 22)+}++/** The columns each kind keeps out of its data for queries (schema.prisma). */+export function extracted(kind: PartKind, data: unknown, stamp: number): Record<string, unknown> {+ switch (kind) {+ case 'group': {+ const group = data as GroupData+ return { projectId: group.projectId ?? null, kind: group.kind ?? null, archived: group.archived, dormant: !!group.dormant,+ agentIds: group.agentIds, executionMachineId: activeWork(group) ? group.assignment!.execution.machineId : null,+ messageSeq: group.messageSeq ?? 0, reportSeq: group.reportSeq ?? 0,+ lastActivityAt: group.lastActivityAt ? new Date(group.lastActivityAt) : new Date(stamp), hostDigest: hostDigest(group) }+ }+ case 'agent': {+ const agent = data as Agent+ return { machineId: agent.machineId, machineOwnerId: agent.machineOwnerId, contributorId: agent.contributorId }+ }+ case 'machine': {+ const machine = data as MachineData+ return { machineId: machine.machineId, contributed: !!machine.contribution, cleanupOwnerIds: machine.cleanups.map(c => c.machineOwnerId) }+ }+ case 'start': {+ const start = data as AgentStart+ return { machineId: start.request.machineId, conversationId: start.request.conversationId,+ agentId: start.harnessId ? stableId(start.request.machineId, start.harnessId) : null,+ finishedAt: startFinished(start) ? new Date(stamp) : null }+ }+ default: return {}+ }+}++/** The finished time a start keeps once set: a later write of a finished start does not push its expiry back. */+async function keepFinishedAt(tx: Transaction, id: string, fields: Record<string, unknown>) {+ if (!fields.finishedAt) return fields+ const row = await tx.swarmStart.findUnique({ where: { id }, select: { finishedAt: true } })+ return row?.finishedAt ? { ...fields, finishedAt: row.finishedAt } : fields+}++/**+ * Writes one part inside the command's transaction, guarded by the version it was read at (design section 3.2). The+ * guard checks the committed version at write time, so it holds whatever the transaction's read concern: a part another+ * transaction changed since the read throws PartConflict, and the transaction runs again on the new state.+ */+export async function guardedWrite(tx: Transaction, tabId: string, write: PartWrite, stamp: number): Promise<number> {+ const model = delegate(tx, write.kind), id = partId(tabId, write.key)+ if (write.op === 'insert') {+ let fields = { ...extracted(write.kind, write.data, stamp), ...write.head, ...write.host }+ // A part added again under the same key continues from its tombstone's version (spec ruling 6).+ const prior = await model.findUnique({ where: { id } })+ if (prior && !prior.deleted) throw new PartConflict(write.kind, write.key)+ if (prior) {+ if (write.kind === 'start') fields = await keepFinishedAt(tx, id, fields)+ const updated = await model.updateMany({ where: { id, version: prior.version, deleted: true }, data: { version: prior.version + 1,+ changedAt: new Date(stamp), deleted: false, purgeAt: null, data: json(write.data), ...fields } })+ if (!updated.count) throw new PartConflict(write.kind, write.key)+ return prior.version + 1+ }+ const version = write.first ?? 1+ await model.create({ data: { id, tabId, key: write.key, version, changedAt: new Date(stamp), deleted: false, ordinal: write.ordinal,+ data: json(write.data), ...fields } })+ return version+ }+ const data = write.op === 'touch' ? {}+ : write.op === 'remove' ? { changedAt: new Date(stamp), deleted: true, purgeAt: new Date(stamp + RETENTION_MS), data: json(write.data), ...write.host }+ : { changedAt: new Date(stamp), data: json(write.data), ...(write.kind === 'start'+ ? await keepFinishedAt(tx, id, extracted(write.kind, write.data, stamp)) : extracted(write.kind, write.data, stamp)), ...write.head, ...write.host }+ const updated = await model.updateMany({ where: { id, version: write.seen, deleted: false }, data: { version: write.seen + 1, ...data } })+ if (!updated.count) throw new PartConflict(write.kind, write.key)+ return write.seen + 1+}diff --git a/backend/src/superTabs/projectUpdates.ts b/backend/src/superTabs/projectUpdates.tsindex e68c0c741..0f9e3e735 100644--- a/backend/src/superTabs/projectUpdates.ts+++ b/backend/src/superTabs/projectUpdates.ts@@ -1,66 +1,85 @@-import { activeWork, author, conversation, isLeads, stableId, type Agent, type MessageDraft, type SuperTabState } from './model.js'-import { downSince } from './machines.js'-import { agentProjectId, groupProject, projectOf } from './projects.js'+import { author, conversation, isLeads, stableId, type Agent, type Conversation, type MessageDraft, type SuperTabState } from './model.js'+import { agentProjectId, groupProject, projectOf, type SwarmProject } from './projects.js'+import type { ProgressData } from './parts/types.js'-/** Workgroup reports mark a project dirty. No per-message model or timer is- * needed; the existing execution host's delivery poll requests consolidation. */-export function noteProjectReports(state: SuperTabState, messages: MessageDraft[], revision: number, now: number) {+/** A project with no report progress yet starts clean at the start of every conversation's numbering. */+const freshProgress = (now: number): ProgressData => ({ since: now, summarizedFloor: 0, summarized: {}, requestedFloor: 0, requested: {} })++/** The conversations whose posts count toward a project's reports: not its Lead conversation, not the Leads+ * conversation, not a private conversation (its posts never reach the Lead's summary to everyone). */+export function reportGroups(state: SuperTabState, project: SwarmProject): Conversation[] {+ return state.conversations.filter(c => !isLeads(c) && !c.audience && c.id !== project.leadConversationId && groupProject(state, c).id === project.id)+}++/** A conversation is dirty while its last report is past what its Lead summarized (design section 3.6). */+export function dirtyGroups(state: SuperTabState, project: SwarmProject): Conversation[] {+ const progress = project.progress+ if (!progress) return []+ return reportGroups(state, project).filter(g => (g.reportSeq ?? 0) > (progress.summarized[g.id] ?? progress.summarizedFloor))+}++/** Workgroup reports mark their conversation, and the project's progress changes only when the project goes from clean to+ * dirty, so posts in different conversations of one project never write the same part (spec ruling 1). */+export function noteProjectReports(state: SuperTabState, messages: MessageDraft[], sequences: ReadonlyMap<string, number>, now: number) {if (!state.projects) returnfor (const message of messages) {const group = conversation(state, message.conversationId)- if (isLeads(group)) continue+ if (isLeads(group) || group.audience) continueconst project = groupProject(state, group)if (group.id === project.leadConversationId) continue- project.progress ??= { dirtyRevision: revision, summarizedRevision: 0, requestedRevision: 0, since: now }- if (project.progress.dirtyRevision <= project.progress.summarizedRevision) project.progress.since = now- project.progress.dirtyRevision = revision+ const clean = !project.progress || !dirtyGroups(state, project).length+ project.progress ??= freshProgress(now)+ group.reportSeq = sequences.get(message.id) ?? group.messageSeq ?? 0+ if (clean) project.progress.since = now}}-/** The Lead reassigns a Builder or Reviewer that has been down this long (the owner's rule, 2026-10-23). */-export const DOWN_REASSIGN_MS = 2 * 60 * 60_000--/** Builders and Reviewers of the project down for two hours, each named once per time it went down. A worker that is- * already stopping was decided on. */-function downWorkers(state: SuperTabState, projectId: string, now: number) {- return state.agents.flatMap(a => {- const since = downSince(state, a, now)- if (!since || a.downNamed === since || now - Date.parse(since) < DOWN_REASSIGN_MS || a.workDecision === 'stop' ||- agentProjectId(state, a) !== projectId || state.conversations.some(c => c.leadId === a.id)) return []- const task = state.conversations.find(c => activeWork(c) && c.assignment!.agentId === a.id)- return [{ agentId: a.id, since, text: `${a.displayName ?? a.name} (down since ${since}${task ? `; task ${JSON.stringify(task.title)}` : ''})` }]- })-}+/** What each dirty conversation's report reaches, by conversation: what a wake-up asks the Lead to acknowledge. */+const throughOf = (groups: Conversation[]) => Object.fromEntries(groups.map(g => [g.id, g.reportSeq ?? 0]).sort(([a], [b]) => a! < b! ? -1 : 1))export function projectUpdateRequest(state: SuperTabState, target: Agent, now: number): MessageDraft | null {// An older Swarm without stored projects is one synthesized project. It keeps no report progress (noteProjectReports),- // so its Lead is woken only for down workers.+ // so its Lead is woken only for lost work (liveness.ts), which replaced the wake-up for workers down two hours.if (state.paused) return nullconst project = projectOf(state, agentProjectId(state, target))const group = conversation(state, project.leadConversationId), progress = project.progressif (group.leadId !== target.id || group.archived) return null- const reports = !!progress && progress.dirtyRevision > progress.summarizedRevision &&- progress.dirtyRevision > progress.requestedRevision &&+ const dirty = dirtyGroups(state, project)+ const reports = !!progress && dirty.some(g => (g.reportSeq ?? 0) > (progress.requested[g.id] ?? progress.requestedFloor)) &&now >= Math.max(progress.requestedAt ?? 0, progress.since) + project.updateMinutes * 60_000- const down = downWorkers(state, project.id, now)- if (!reports && !down.length) return null- // A wake-up only for down workers is acknowledged through what was already summarized, so reports that are not yet due- // keep their own request.- const through = (reports ? progress!.dirtyRevision : progress?.summarizedRevision) ?? 0- const id = stableId('project-update', state.id, project.id, String(through), ...down.map(d => `${d.agentId}@${d.since}`))- const text = (reports ? `Consolidate new reports for project ${JSON.stringify(project.name)}. ` +- `Read this project's workgroups with lastMessageSequence after ${progress!.summarizedRevision}; inspect their new messages and current work. ` +- 'At your next natural checkpoint, tell the people what changed, what is blocked, and what comes next. Include useful workgroup references and result links. ' : '') +- (down.length ? `Down for 2 hours or more in project ${JSON.stringify(project.name)}: ${down.map(d => d.text).join(', ')}. ` +- 'Their machine is offline or their session ended or stopped. Decide whether to reassign their work to another agent. ' : '') ++ if (!reports) return null+ const through = throughOf(dirty)+ const id = stableId('project-update', state.id, project.id, JSON.stringify(through))+ const after = (g: Conversation) => `${g.number !== undefined ? `#${g.number}` : JSON.stringify(g.title)} after ${progress!.summarized[g.id] ?? progress!.summarizedFloor}`+ const text = `Consolidate new reports for project ${JSON.stringify(project.name)}. ` ++ `Read the new messages of these workgroups: ${dirty.map(after).join(', ')}; inspect their current work. ` ++ 'At your next natural checkpoint, tell the people what changed, what is blocked, and what comes next. Include useful workgroup references and result links. ' +'Do not copy the terminal log or repeat unchanged status. This is a scheduled request, not a new task. ' +`Use harness super-tab --tab ${state.id} command UNIQUE_OPERATION_ID ` +- `JSON with {"type":"project.report","projectId":"${project.id}","throughRevision":${through},"text":"your update"}. ` ++ `JSON with {"type":"project.report","projectId":"${project.id}","through":${JSON.stringify(through)},"text":"your update"}. ` +'Use text:null to acknowledge if nothing merits an update. Reuse the same operation ID after a lost reply. ' +'Keep reporting human questions, serious blockers, and completion immediately; do not wait for this cadence.'return { id, conversationId: group.id,author: author(state, { kind: 'agent', agentId: target.id, machineOwnerId: target.machineOwnerId }),text, replyTo: null, recipients: [target.id],- source: { kind: 'update-request', projectId: project.id, throughRevision: through,- ...(down.length ? { down: down.map(({ agentId, since }) => ({ agentId, since })) } : {}) } }+ source: { kind: 'update-request', projectId: project.id, through } }+}++/** A Lead's report: each conversation it names is summarized through what it read, never past its last report. A legacy+ * scalar from a wake-up written before the split covers every conversation up to that tab revision. */+export function summarize(state: SuperTabState, project: SwarmProject, through: Record<string, number>): void {+ const progress = project.progress+ if (!progress) return+ for (const group of reportGroups(state, project)) {+ if (!(group.id in through)) continue+ progress.summarized[group.id] = Math.max(progress.summarized[group.id] ?? progress.summarizedFloor, Math.min(through[group.id]!, group.reportSeq ?? 0))+ }+}++/** Whether a report answers the latest wake-up: with it, everything a wake-up asked for is summarized. A wake-up from+ * before the store by parts asked through a tab revision, which only a legacy scalar can reach. */+export function answersRequest(progress: ProgressData, legacy: number | undefined): boolean {+ // Nothing asked since the split: a pre-split wake-up's tab revision is reached only by a legacy scalar; a map answers any other.+ if (!Object.keys(progress.requested).length) return legacy === undefined || legacy >= progress.requestedFloor+ return Object.entries(progress.requested).every(([id, seq]) => (progress.summarized[id] ?? progress.summarizedFloor) >= seq)}diff --git a/backend/src/superTabs/projects.test.ts b/backend/src/superTabs/projects.test.tsindex d16b7ed58..c141790d6 100644--- a/backend/src/superTabs/projects.test.ts+++ b/backend/src/superTabs/projects.test.ts@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto'import { describe, expect, it } from 'vitest'import { applyCommand, commandSchema, type Command, type CommandContext } from './commands.js'import { createSuperTab, visibleState, type Actor, type MessageDraft } from './model.js'-import { canReadAgent, projectOf, projectsOf, readConversation, skillModeOf, skillSetOf } from './projects.js'+import { canReadAgent, canWatchAgent, markConfidential, projectOf, projectsOf, readConversation, skillModeOf, skillSetOf } from './projects.js'const owner: Actor = { kind: 'person', userId: 'owner', email: '[email protected]' }const peer: Actor = { kind: 'person', userId: 'peer', email: '[email protected]' }@@ -515,3 +515,36 @@ describe('custom role sets', () => {expect(visible.projects!.find(x => x.id === 'lead')!.skillSet).toBe('default')})})++describe('who may watch an agent\'s terminal (final review, Critical 1)', () => {+ it('keeps a session in a private chat to its machine\'s owner even when it is no longer the Lead, and leaves other agents to every reader', () => {+ const f = setup()+ const host: Actor = { kind: 'person', userId: 'host', email: '[email protected]' }+ f.state.people.push({ id: 'host', email: '[email protected]', role: 'collaborator', generation: 'first' })+ const builder = f.add('lead', 'builder', false), former = f.add('lead', 'former', false)+ const target = (id: string) => f.state.agents.find(a => a.id === id)!+ // A private chat that still lists an earlier Lead's session: its screen holds that chat.+ f.state.conversations.push({ id: 'chat', title: 'Chat with PM', leadId: null, agentIds: [former], archived: false, brief: '', checks: [],+ assignment: null, lastMessageSequence: 0, audience: { people: [{ id: 'peer', generation: 'first' }] } })+ for (const reader of [owner, peer]) {+ expect(canWatchAgent(f.state, reader, target(former))).toBe(false)+ expect(canWatchAgent(f.state, reader, target(builder))).toBe(true)+ }+ expect(canWatchAgent(f.state, host, target(former))).toBe(true)+ })++ it('keeps a session confidential once marked, after its private membership ends, until it leaves', () => {+ const f = setup()+ const former = f.add('lead', 'former', false)+ f.state.conversations.push({ id: 'chat', title: 'Chat with PM', leadId: null, agentIds: [former], archived: false, brief: '', checks: [],+ assignment: null, lastMessageSequence: 0, audience: { people: [{ id: 'peer', generation: 'first' }] } })+ markConfidential(f.state)+ f.state.conversations = f.state.conversations.filter(c => c.id !== 'chat')+ expect(canWatchAgent(f.state, peer, f.state.agents.find(a => a.id === former)!)).toBe(false)+ // Every command marks: a Lead stored before the mark is marked by the next one.+ const lead = f.add('lead', 'pm', true)+ delete f.state.agents.find(a => a.id === lead)!.confidential+ f.run({ type: 'conversation.create', title: 'Next', brief: '', checks: [] })+ expect(f.state.agents.find(a => a.id === lead)!.confidential).toBe(true)+ })+})diff --git a/backend/src/superTabs/projects.ts b/backend/src/superTabs/projects.tsindex 662c982f8..241581fc0 100644--- a/backend/src/superTabs/projects.ts+++ b/backend/src/superTabs/projects.ts@@ -23,14 +23,8 @@ export interface SwarmProject {visibility: ProjectVisibilitymembers: Array<{ id: string; generation: string }>updateMinutes: 1 | 5 | 15 | 30- progress?: {- dirtyRevision: number- summarizedRevision: number- since: number- requestedRevision: number- requestedAt?: number- requestMessageId?: string- }+ /** Report watermark per conversation (projectUpdates.ts); kept in its own part (store by parts). */+ progress?: import('./parts/types.js').ProgressDatarepository?: { machineId: string; cwd: string; repositoryUrl: string | null }/** Absent on projects from before skill modes, which keep the texts their agents already run. */skillMode?: SkillMode@@ -112,13 +106,92 @@ export function readConversation(state: SuperTabState, actor: Actor, conversatioreturn group}readProject(state, actor, groupProject(state, group).id)+ if (!canReadGroup(state, actor, group)) fail('NOT_FOUND', 'This conversation is unavailable.', 404)return group}+/** Whether a project's owner and the Swarm's owner also read its private conversations. The owner decided they do not+ * (2026-10-26); this is the one place that decides it (design section 4.8). */+export const PRIVATE_VISIBLE_TO_OWNERS = false++/** Who reads a conversation: the Leads conversation's people and Leads; a project conversation's readers; and a private+ * conversation's listed people (at the generation they were listed with) and the project's Lead, nobody else. */+export function canReadGroup(state: SuperTabState, actor: Actor, group: Conversation): boolean {+ if (isLeads(group)) return actor.kind === 'person' ? state.people.some(p => p.id === actor.userId) : !!ledProject(state, actor.agentId)+ const project = groupProject(state, group)+ if (!canReadProject(state, actor, project)) return false+ if (!group.audience) return true+ if (actor.kind === 'agent') return ledProject(state, actor.agentId)?.id === project.id+ const member = state.people.find(p => p.id === actor.userId)+ return !!member && (group.audience.people.some(p => p.id === member.id && p.generation === member.generation)+ || (PRIVATE_VISIBLE_TO_OWNERS && (member.id === project.ownerId || member.id === state.ownerId)))+}++/** A private conversation's audience: each person a member who reads its project, captured at their generation. */+export function audienceOf(state: SuperTabState, project: SwarmProject, personIds: string[]): NonNullable<Conversation['audience']> {+ return { people: [...new Set(personIds)].map(id => {+ const member = state.people.find(p => p.id === id) ?? fail('INVALID_AUDIENCE', 'List people in this Swarm.', 400)+ if (!canReadProject(state, { kind: 'person', userId: member.id, email: member.email }, project)) {+ fail('INVALID_AUDIENCE', `${member.email} cannot read this project.`, 400)+ }+ return { id: member.id, generation: member.generation }+ }) }+}+export function canReadAgent(state: SuperTabState, actor: Actor, target: Agent): boolean {return canReadProject(state, actor, projectOf(state, agentProjectId(state, target)))}+/** A session that reads people's private messages: its project's Lead (the Product Manager each person chats with privately),+ * or any agent in a private conversation, so a replaced Lead's earlier screen stays closed too. */+export const confidentialSession = (state: SuperTabState, target: Agent): boolean =>+ !!ledProject(state, target.id) || privateMember(state, target.id)+const privateMember = (state: SuperTabState, agentId: string) => state.conversations.some(c => !!c.audience && c.agentIds.includes(agentId))++/** Whether an agent's session is confidential: marked, or a Lead or private member now, here or (`elsewhere`) in another Swarm. */+export const isConfidential = (state: SuperTabState, target: Agent, elsewhere = false): boolean =>+ !!target.confidential || elsewhere || confidentialSession(state, target)++/** A native session's identity across Swarms: its machine and harness. */+export const sessionKey = (machineId: string, harnessId: string) => `${machineId}\n${harnessId}`+/** The other Swarms' registrations a command is checked against (confidential.ts otherRegistrations), by sessionKey. */+export interface OtherRegistrations { registered: Set<string>; confidential: Set<string> }++/** A confidential session is registered in one Swarm only (Lead ruling, final review Critical 1), so its mark lives exactly as+ * long as that registration: a command may not register again (add, start, rebind) a session confidential elsewhere, nor make+ * a session registered elsewhere a Lead or a private conversation's member. Registrations from before the rule stay. */+export function requireSingleRegistration(before: SuperTabState, after: SuperTabState, elsewhere: OtherRegistrations): void {+ const prior = new Map(before.agents.map(a => [a.id, a]))+ for (const target of after.agents) {+ const was = prior.get(target.id), key = sessionKey(target.machineId, target.harnessId)+ if ((!was || was.harnessId !== target.harnessId) && elsewhere.confidential.has(key)) {+ fail('SESSION_CONFIDENTIAL', 'This terminal reads private chats in another Swarm. Start a new agent here.')+ }+ const lead = !!ledProject(after, target.id) && !(was && ledProject(before, target.id))+ const member = privateMember(after, target.id) && !(was && privateMember(before, target.id))+ if ((lead || member) && elsewhere.registered.has(key)) {+ fail('SESSION_CONFIDENTIAL', 'This terminal also works in another Swarm, so it cannot lead or read private chats. Start a new agent for this.')+ }+ }+}++/** A session becomes confidential the moment it is a Lead or in a private conversation, and stays so until it leaves the+ * Swarm (its session closes), even once that membership ends (Lead ruling, final review Critical 1). */+export function markConfidential(state: SuperTabState): void {+ for (const target of state.agents) if (!target.confidential && confidentialSession(state, target)) target.confidential = true+}++/** Who may watch an agent's terminal: observe it, hold a share of it, read or type in it. A confidential session's screen and+ * scrollback hold people's private chats, so only the person whose machine runs it may, owners included. `elsewhere`: the+ * same session is confidential in another Swarm (confidential.ts). Any other agent: every reader of its project, as before. */+export function canWatchAgent(state: SuperTabState, actor: Actor, target: Agent, elsewhere = false): boolean {+ return canReadAgent(state, actor, target) && (!isConfidential(state, target, elsewhere) || ownSession(actor, target))+}++/** The only actors a confidential session admits: the person whose machine runs it, or the session itself. */+export const ownSession = (actor: Actor, target: Agent): boolean =>+ actor.kind === 'person' ? actor.userId === target.machineOwnerId : actor.agentId === target.id+export function readAgent(state: SuperTabState, actor: Actor, agentId: string): Agent {const target = agent(state, agentId)if (!canReadAgent(state, actor, target)) fail('AGENT_UNAVAILABLE', 'This agent is unavailable.', 404)diff --git a/backend/src/superTabs/read/changes.test.ts b/backend/src/superTabs/read/changes.test.tsnew file mode 100644index 000000000..d07e06c79--- /dev/null+++ b/backend/src/superTabs/read/changes.test.ts@@ -0,0 +1,118 @@+import { describe, expect, it } from 'vitest'+import * as store from '../parts/index.js'+import type { Part, SwarmParts } from '../parts/index.js'+import { readerView } from './views.js'+import { changesFor } from './changes.js'+import { NOW, outsider, owner, peer, richSwarm } from './fixture.test-support.js'+import type { Actor } from '../model.js'++const R = 9_000+const LATER = NOW + 5_000+const agentActor = (agentId: string): Actor => ({ kind: 'agent', agentId, machineOwnerId: `${owner.userId}-machine` })++function scene() {+ const s = richSwarm()+ s.contribute('mac', 'swarm')+ const privateId = s.group('Peer and PM')+ s.edit(state => {+ const generation = state.people.find(p => p.id === peer.userId)!.generation+ state.conversations.find(c => c.id === privateId)!.audience = { people: [{ id: peer.userId, generation }] }+ })+ return { s, privateId, parts: store.split(s.state, { tabId: 'tab', version: R, now: NOW }) }+}+type Kind = 'members' | 'agents' | 'groups' | 'machines' | 'starts' | 'progress'+/** A later write of one part: its version moves and `change` applies to the stored part (data, tombstone or dormant flag). */+function write(parts: SwarmParts, kind: Kind, key: string, change: (part: Part) => void): Part {+ const part = (parts[kind] as Part[]).find(p => p.key === key)!+ part.version += 1+ part.changedAt = LATER+ change(part)+ return part+}+/** What the reader receives: its view of the active (live) parts, then the changed parts run through its read check. */+function receive(parts: SwarmParts, changed: Part[], actor: Actor) {+ const active = { ...parts, ...Object.fromEntries((['members', 'agents', 'groups', 'machines', 'starts', 'progress'] as Kind[])+ .map(kind => [kind, (parts[kind] as Part[]).filter(p => !p.deleted && !p.dormant)])) } as SwarmParts+ return changesFor(readerView(active, actor, LATER, { teamMachines: [] }), changed, actor)+}+const keys = (list: Array<{ key: string }>) => list.map(p => p.key)++describe('changes since a cursor (design 4.4)', () => {+ it('sends nothing but derived when nothing changed, and the head only when it changed', () => {+ const { parts } = scene()+ expect(receive(parts, [], peer)).toMatchObject({ head: null, members: [], agents: [], groups: [], machines: [], starts: [], progress: [] })+ const head = { ...parts.head, version: R + 1, changedAt: LATER }+ parts.head = head+ expect(receive(parts, [head], peer).head).toMatchObject({ key: 'head', version: R + 1 })+ })++ it('sends a changed group whole to its readers and nothing to anyone else', () => {+ const { s, parts } = scene()+ const changed = [write(parts, 'groups', s.web, p => { (p.data as { title: string }).title = 'Web 2' }),+ write(parts, 'groups', s.secretGroup, p => { (p.data as { title: string }).title = 'Secret 2' })]+ const peerGroups = receive(parts, changed, peer).groups+ expect(peerGroups).toEqual([expect.objectContaining({ key: s.web, version: R + 1, data: expect.objectContaining({ title: 'Web 2', messageSeq: R }) })])+ expect(keys(receive(parts, changed, owner).groups)).toEqual([s.web, s.secretGroup])+ })++ it('sends a private conversation\'s change, removal and dormant stub only to its audience and the Lead', () => {+ const { s, parts, privateId } = scene()+ for (const change of [(p: Part) => { (p.data as { title: string }).title = 'x' }, (p: Part) => { p.deleted = true }, (p: Part) => { p.dormant = true }]) {+ const { parts: fresh } = scene()+ const changed = [write(fresh, 'groups', privateId, change)]+ expect(keys(receive(fresh, changed, peer).groups)).toEqual([privateId])+ expect(keys(receive(fresh, changed, agentActor(s.lead)).groups)).toEqual([privateId])+ expect(receive(fresh, changed, owner).groups).toEqual([])+ expect(receive(fresh, changed, agentActor(s.worker)).groups).toEqual([])+ }+ void parts+ })++ it('sends a removed or dormant group as a one-line stub, never its last data', () => {+ const { s, parts } = scene()+ const changed = [write(parts, 'groups', s.done, p => { p.deleted = true }), write(parts, 'groups', s.web, p => { p.dormant = true })]+ expect(receive(parts, changed, peer).groups).toEqual([+ { key: s.done, version: R + 1, changedAt: LATER, deleted: true },+ { key: s.web, version: R + 1, changedAt: LATER, dormant: true }])+ })++ it('sends an agent\'s removal only to readers of its project, and a member\'s removal to everyone', () => {+ const { s, parts } = scene()+ const secretAgent = s.add('secret-harness', s.secretGroup)+ const fresh = store.split(s.state, { tabId: 'tab', version: R, now: NOW })+ const changed = [write(fresh, 'agents', secretAgent, p => { p.deleted = true }), write(fresh, 'agents', s.worker, p => { p.deleted = true }),+ write(fresh, 'members', outsider.userId, p => { p.deleted = true })]+ expect(receive(fresh, changed, peer)).toMatchObject({ agents: [{ key: s.worker, deleted: true }], members: [{ key: outsider.userId, deleted: true }] })+ expect(keys(receive(fresh, changed, owner).agents)).toEqual([secretAgent, s.worker])+ void parts+ })++ it('sends a machine whose contribution ended as a removal', () => {+ const { parts } = scene()+ const changed = [write(parts, 'machines', 'mac', p => { (p.data as { contribution: unknown }).contribution = null })]+ expect(receive(parts, changed, peer).machines).toEqual([{ key: 'mac', version: R + 1, changedAt: LATER, deleted: true }])+ })++ it('sends a start\'s removal only to readers of its group', () => {+ const { s } = scene()+ s.edit(state => {+ state.starts = [s.web, s.secretGroup].map(conversationId => ({ id: `start-${conversationId}`, creationId: 'c', actorKey: 'person:owner',+ contributorId: owner.userId, membershipGeneration: 'tab', machineOwnerId: owner.userId, hostGrant: null, harnessId: null, dispatched: false, error: null,+ request: { conversationId, machineId: 'mac', engine: 'codex', name: 'Builder', cwd: '/repo', worktree: false,+ requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } } }))+ })+ const fresh = store.split(s.state, { tabId: 'tab', version: R, now: NOW })+ const changed = [write(fresh, 'starts', `start-${s.web}`, p => { p.deleted = true }), write(fresh, 'starts', `start-${s.secretGroup}`, p => { p.deleted = true })]+ expect(keys(receive(fresh, changed, peer).starts)).toEqual([`start-${s.web}`])+ expect(keys(receive(fresh, changed, owner).starts)).toEqual([`start-${s.web}`, `start-${s.secretGroup}`])+ })++ it('sends changed project progress only to readers of the project', () => {+ const { s } = scene()+ s.edit(state => { for (const p of state.projects!) p.progress = { since: 1, summarizedFloor: 0, summarized: {}, requestedFloor: 0, requested: {} } })+ const fresh = store.split(s.state, { tabId: 'tab', version: R, now: NOW })+ const changed = [write(fresh, 'progress', 'lead', () => {}), write(fresh, 'progress', s.secret, () => {})]+ expect(receive(fresh, changed, peer).progress).toEqual([{ key: 'lead', version: R + 1, changedAt: LATER,+ data: { since: 1, summarizedFloor: 0, summarized: {}, requestedFloor: 0, requested: {}, requestedAt: null } }])+ })+})diff --git a/backend/src/superTabs/read/changes.ts b/backend/src/superTabs/read/changes.tsnew file mode 100644index 000000000..8101a8283--- /dev/null+++ b/backend/src/superTabs/read/changes.ts@@ -0,0 +1,71 @@+/**+ * Which changed parts one reader receives (design 4.4). A live part goes as the reader sees it now; a removal or a+ * dormant group goes as a one-line stub, and only to a reader who could read the part's last data. Where that check+ * cannot be made (its project is gone), the change also moved the visibility epoch and every reader reloads.+ */+import type { Actor, Agent, AgentStart, Conversation } from '../model.js'+import { canReadAgent, canReadGroup } from '../projects.js'+import { knownKind, type MachineData, type Part } from '../parts/index.js'+import type { ChangesDelta, DormantStub, Tombstone } from './contract.js'+import { envelope, progressView, visibleGroupView, type ReaderView } from './views.js'++export type PartChanges = Pick<ChangesDelta, 'head' | 'members' | 'agents' | 'groups' | 'machines' | 'starts' | 'progress'>++const stub = (part: Part): Tombstone => ({ key: part.key, version: part.version, changedAt: part.changedAt, deleted: true })+const dormantStub = (part: Part): DormantStub => ({ key: part.key, version: part.version, changedAt: part.changedAt, dormant: true })+/** A read check that names a project which no longer exists answers no. */+const safely = (check: () => boolean): boolean => { try { return check() } catch { return false } }++export function changesFor(view: ReaderView, changed: Part[], actor: Actor): PartChanges {+ const { state, parts: seen } = view+ const live = <T>(list: Array<{ key: string } & T>, key: string) => list.find(p => p.key === key)+ const groupReadable = (group: Conversation) => safely(() => canReadGroup(state, actor, group))+ const groupOf = (id: string) => state.conversations.find(c => c.id === id)+ ?? changed.find(p => p.kind === 'group' && p.key === id)?.data as Conversation | undefined+ const visibleAgents = new Set(seen.agents.map(a => a.key))+ const out: PartChanges = { head: null, members: [], agents: [], groups: [], machines: [], starts: [], progress: [] }+ for (const part of changed) {+ switch (part.kind) {+ case 'head': out.head = seen.head; break+ case 'member': {+ const member = live(seen.members, part.key)+ if (part.deleted) out.members.push(stub(part))+ else if (member) out.members.push(member)+ break+ }+ case 'agent': {+ const agent = live(seen.agents, part.key)+ if (part.deleted) { if (safely(() => canReadAgent(state, actor, part.data as Agent))) out.agents.push(stub(part)) }+ else if (agent) out.agents.push(agent)+ break+ }+ case 'group': {+ // A conversation of a kind this release does not know is parked by reassembly, so a first load leaves it out: so+ // do changes, removals and dormant stubs, or an older reader meets it during a rolling deploy (review of #1745).+ if (part.data && !knownKind(part.data as Conversation)) break+ if (part.deleted || part.dormant) { if (groupReadable(part.data as Conversation)) out.groups.push(part.deleted ? stub(part) : dormantStub(part)) }+ // Sent from the changed part itself: the reader's view may hold only a conversation's light fields (parts/light.ts).+ else if (groupReadable(part.data as Conversation)) out.groups.push(envelope(part, visibleGroupView(part.data as Conversation, visibleAgents)))+ break+ }+ case 'machine': {+ const machine = live(seen.machines, part.key)+ if (machine && !part.deleted) out.machines.push(machine)+ // Machine ids are no secret among members, unlike conversations: a contribution that ended reads as a removal.+ else if (part.deleted || !(part.data as MachineData | null)?.contribution) out.machines.push(stub(part))+ break+ }+ case 'start': {+ const start = live(seen.starts, part.key), group = groupOf((part.data as AgentStart).request.conversationId)+ if (part.deleted) { if (group && groupReadable(group)) out.starts.push(stub(part)) }+ else if (start) out.starts.push(start)+ break+ }+ case 'progress': {+ if (!part.deleted && seen.head.data.projects?.some(p => p.id === part.key)) out.progress.push(envelope(part, progressView(part.data as never)))+ break+ }+ }+ }+ return out+}diff --git a/backend/src/superTabs/read/contract.ts b/backend/src/superTabs/read/contract.tsnew file mode 100644index 000000000..0523fff98--- /dev/null+++ b/backend/src/superTabs/read/contract.ts@@ -0,0 +1,213 @@+/**+ * The Swarm read API by parts (docs/design/2026-10-26-swarm-state-parts.md, section 4): the single source of truth for the+ * response shapes. Desktop/web (`desktop/lib/super_tabs`) and the CLI (`cli/src/superTabs`) mirror these by hand; announce+ * any change to the Lead before it merges.+ *+ * Every payload below is the `data` of the usual `{ success, data }` envelope. Times are epoch milliseconds; part `data`+ * keeps today's ISO strings where today's record has them.+ */+import type { Agent, AgentStart, Conversation, Person, SuperTabState, WorkStatus } from '../model.js'+import type { ContributedMachine } from '../machines.js'++export const READ_FORMAT = 2+export type PartKind = 'head' | 'member' | 'agent' | 'group' | 'machine' | 'start' | 'progress'++/** A live part: the reader's view of one stored record. */+export interface LivePart<T> { key: string; version: number; changedAt: number; data: T }+/** A removed part. It never carries data; a reader receives it only if it could read the part's last data. */+export interface Tombstone { key: string; version: number; changedAt: number; deleted: true }+/** A group that left the active set (archived, or finished and idle 24 h). Fetch it whole with `groups/:id`. */+export interface DormantStub { key: string; version: number; changedAt: number; dormant: true }+export type PartChange<T> = LivePart<T> | Tombstone+export type GroupChange = LivePart<GroupView> | Tombstone | DormantStub++/** The head as a reader sees it: no sharing, overlap alerts, retired number or parked groups; projects, rules and+ * invitations filtered (invitations only for the Swarm owner). */+export type HeadView = Pick<SuperTabState, 'version' | 'id' | 'name' | 'project' | 'projects' | 'leadsConversationId' | 'ownerId'+ | 'environment' | 'routingPolicy' | 'rules' | 'paused' | 'invitations' | 'localModels'>+export type MemberView = Person+/** The stored agent. Time-based and cross-part values (`downSince`, `limitedUntil`, an awaiting decision, the custom+ * role) come only in `derived.agents`, so an agent never changes without a new version. */+export type AgentView = Omit<Agent, 'downNamed' | 'downSince' | 'limitedUntil' | 'roleId'>+/** A private conversation's audience: the people it is shared with. The project's Lead always reads it too. */+export interface Audience { people: Array<{ id: string; generation: string }> }+/** A conversation with its own message counter (`lastMessageSequence` and message sequences compare within one group).+ * `dormant` is set only on a dormant group fetched on demand; `audience` only on a private conversation. */+export type GroupView = Omit<Conversation, 'messageSeq' | 'reportSeq' | 'dormant' | 'lastActivityAt' | 'audience'>+ & { messageSeq: number; dormant?: true; audience?: Audience }+/** A contribution as `state.machines[]` has it, privacy detail only for its contributor, harness ids cut to what the+ * reader can see. Machines without a contribution are never sent. */+export type MachineView = ContributedMachine+export type StartView = AgentStart+export interface ProgressView {+ since: number+ summarizedFloor: number+ summarized: Record<string, number>+ requestedFloor: number+ requested: Record<string, number>+ requestedAt: number | null+ requestMessageId?: string+}++/** Values that change without a part changing (time, or several parts). Recomputed in full on every response;+ * clients overlay it on the parts. */+export interface Derived {+ /** Every agent the reader can see. `workDecision` is null when the stored value stands; `roleId` null outside Custom. */+ agents: Record<string, { downSince: string | null; limitedUntil: string | null; workDecision: 'awaiting' | null; roleId: string | null }>+ /** Every contributed machine the reader can see. */+ machines: Record<string, { availableSlots: number; teamWork: { allowed: true } | { allowed: false; reason: string; [key: string]: unknown } }>+ /** A Lead agent only. */+ otherProjectsWork?: OtherProjectWorkView[]+ /** A person only. */+ mentionsWaiting?: number+}+export interface OtherProjectWorkView {+ conversationId: string; projectName: string; title: string; owns: string[]; status: WorkStatus; agentName: string; pr: string | null+}++interface ReadMeta {+ format: typeof READ_FORMAT+ /** Opaque: unpadded base64url. Send it back unchanged to `changes`. */+ cursor: string+ serverTime: number+ /** The newest data change of any part of this Swarm (touches do not count); null for a Swarm with no parts yet. */+ lastChangedAt: number | null+ /** The visibility epoch; a change makes `changes` answer `reload`. */+ epoch: number+}++/** GET /api/super-tabs/:tabId/parts[?asAgentId=] */+export interface FirstLoad extends ReadMeta {+ tabId: string+ githubApp?: true+ head: LivePart<HeadView>+ members: LivePart<MemberView>[]+ agents: LivePart<AgentView>[]+ /** The reader's visible active groups, in creation order. */+ groups: LivePart<GroupView>[]+ machines: LivePart<MachineView>[]+ starts: LivePart<StartView>[]+ progress: LivePart<ProgressView>[]+ derived: Derived+}++/** GET /api/super-tabs/:tabId/changes?cursor=[&asAgentId=] */+export type Changes = ChangesReload | ChangesDelta+/** Drop the store and do a first load: bad or old cursor, another epoch, or older than tombstones are kept. */+export interface ChangesReload { reload: true }+export interface ChangesDelta extends ReadMeta {+ reload: false+ head: LivePart<HeadView> | null+ members: PartChange<MemberView>[]+ agents: PartChange<AgentView>[]+ groups: GroupChange[]+ machines: PartChange<MachineView>[]+ starts: PartChange<StartView>[]+ progress: PartChange<ProgressView>[]+ derived: Derived+}++/** GET /api/super-tabs/:tabId/groups?dormant=1[&projectId=][&before=][&asAgentId=]: newest activity first, 50 a page. */+export interface DormantGroups { groups: LivePart<GroupView>[]; next: string | null }+/** GET /api/super-tabs/:tabId/groups/:conversationId[?asAgentId=]: active or dormant; 404 when unreadable. */+export interface OneGroup { group: LivePart<GroupView> }++/** POST /api/super-tabs/:tabId/commands: the parts the command wrote (never the ones it only touched). */+export interface CommandReply {+ result: Record<string, unknown>+ parts: Array<{ kind: PartKind; key: string; version: number }>+ lastChangedAt: number | null+ /** Only on a replayed receipt from before the migration. */+ legacyRevision?: number+}++/** GET /api/super-tabs/list[?after=] */+export interface SwarmList {+ tabs: Array<{ id: string; name: string; ownerId: string; paused: boolean; lastChangedAt: number | null }>+ next: string | null+}++/** GET /api/super-tabs/:tabId/conversations/:conversationId/messages[?after=&afterId= | ?before=&beforeId= | ?messageId=]+ * (design 4.6). Rows are ordered by (sequence, id); `revision` is gone. With no cursor the page is the newest 100, and+ * `next` names its oldest row: send it back as `before`/`beforeId` for the page before. Forward pages (`after`) name their+ * newest row the same way. `next` is null at the end. `after` alone (no `afterId`) means strictly after that sequence,+ * which is all a poll for new messages needs. */+export interface MessagePageCursor { sequence: number; id: string }+export interface MessagePage<M = Record<string, unknown>> { messages: M[]; next: MessagePageCursor | null }++/** GET /api/super-tabs/hosts/:machineId/changes?cursor=[&full=1], or POST to the same path with this body when the host+ * holds etags (up to 500 Swarms do not fit in a URL). Ask `full` at start and at least every 60 s. */+export interface HostChangesRequest {+ cursor?: string+ full?: boolean+ /** Swarm id → the `etag` of the rows the host holds for it. A Swarm whose rows still hash the same comes back unchanged. */+ held?: Record<string, string>+}+export interface HostChanges {+ format: typeof READ_FORMAT+ full: boolean+ cursor: string+ /** Swarms with a host-relevant change (all of the machine's Swarms when `full`): replace each one's rows, or keep the+ * rows held for an `unchanged` one. */+ tabs: HostTab[]+ /** Incremental only: Swarms that no longer list this machine. Empty when `full`. */+ removedTabIds: string[]+}+export type HostTab = HostTabRows | HostTabUnchanged+/** The rows still hash to the `etag` the host sent in `held`: keep them (only `lastChangedAt` may have moved). */+export interface HostTabUnchanged { tabId: string; lastChangedAt: number | null; etag: string; unchanged: true }+export interface HostTabRows {+ tabId: string+ lastChangedAt: number | null+ /** Opaque: send it back in `held`. It changes whenever `roster`, `pool` or `assignments` do (not for the host's own+ * machine reading or the rows' change times), and may change when they do not. */+ etag: string+ unchanged?: never+ /** Today's `GET /hosts/:m` rows for this Swarm, `revision` replaced by `lastChangedAt`. */+ roster: HostRosterRow[]+ /** Today's `GET /hosts/:m/pools` row for this Swarm, or null when this machine is not contributed there by the caller. */+ pool: HostPool | null+ /** Today's `GET /hosts/:m/assignments` rows for this Swarm. */+ assignments: Array<{ tabId: string; assignmentId: string; harnessId: string }>+}+export type HostRosterRow =+ | HostAgentRow+ | { tabId: string; agent: { id: string; harnessId: string; machineId: string }; closeSession: true; active: false }+ | { tabId: string; cleanup: { machineId: string; removalId: string } }+ | { tabId: string; joinTeam: { machineId: string; name: string; maxAgents: number } }+export interface HostAgentRow {+ tabId: string+ tabName: string+ lastChangedAt: number | null+ paused: boolean+ active: boolean+ attention: { assignmentId: string; status: WorkStatus; result: string | null } | null+ agent: Agent+ joinSwarm: boolean+ skillMode: 'default' | 'orchestration'+ role?: { id: string; name: string; kind: string; version: string; projectId: string } | null+ lead: boolean+ /** New: lets the host decide what it may read without a full Swarm read. */+ leadsConversationId: string | null+ stopRequested: boolean+ observers: Array<{ email: string; userId: string }>+ /** Its session is confidential in some Swarm: the host refuses every share of it, ordinary ones too (Critical 1). */+ confidential: boolean+}+export interface HostPool {+ tabId: string+ paused: boolean+ machine: ContributedMachine+ starts: AgentStart[]+ projects?: Array<{ id: string; leadConversationId: string; repository?: unknown; conversationIds: string[] }>+ localGrid?: string+ reservations: Array<{ harnessId: string; generation: string }>+ harnessIds: string[]+ githubApp?: true+}++/** HTTP 426 on GET /api/super-tabs, /:tabId, /hosts/:m, /hosts/:m/pools and /hosts/:m/assignments. */+export const UPDATE_REQUIRED = { code: 'UPDATE_REQUIRED', status: 426, message: 'Update Harness to keep using this Swarm.' } as const+/** HTTP 503 on the new routes while a Swarm is still on the old format; clients retry. */+export const SWARM_MIGRATING = { code: 'SWARM_MIGRATING', status: 503, message: 'This Swarm is being upgraded. Try again in a moment.' } as const+diff --git a/backend/src/superTabs/read/cursor.test.ts b/backend/src/superTabs/read/cursor.test.tsnew file mode 100644index 000000000..e1291df92--- /dev/null+++ b/backend/src/superTabs/read/cursor.test.ts@@ -0,0 +1,39 @@+import { describe, expect, it } from 'vitest'+import { cursorFor, readCursor } from './cursor.js'++const T0 = 1_793_010_104_375+const DAY = 86_400_000+const b64 = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')++describe('change cursor (design 4.2)', () => {+ it('starts 30 s before the read began and carries the epoch, as unpadded base64url the daemon proxy passes', () => {+ const cursor = cursorFor(T0, 3)+ expect(cursor).toMatch(/^[A-Za-z0-9_-]+$/)+ expect(JSON.parse(Buffer.from(cursor, 'base64url').toString())).toEqual({ v: 2, t: T0 - 30_000, e: 3 })+ })++ it('reads back a cursor of the current epoch made within tombstone retention', () => {+ expect(readCursor(cursorFor(T0, 3), 3, T0 + 5_000)).toEqual({ since: T0 - 30_000 })+ })++ it.each([+ ['garbage', '!!not-base64!!'],+ ['not JSON', Buffer.from('hello').toString('base64url')],+ ['an older format', b64({ v: 1, t: T0, e: 3 })],+ ['a time that is not a number', b64({ v: 2, t: '1793010104375', e: 3 })],+ ['no epoch', b64({ v: 2, t: T0 })],+ ['a JSON array', b64([2, T0, 3])],+ ])('asks for a reload on %s', (_case, cursor) => {+ expect(readCursor(cursor, 3, T0)).toEqual({ reload: true })+ })++ it('asks for a reload when who may see what changed since the cursor', () => {+ expect(readCursor(cursorFor(T0, 3), 4, T0 + 1_000)).toEqual({ reload: true })+ })++ it('asks for a reload when tombstones made after the cursor may already be purged (7 days, 1 hour margin)', () => {+ const cursor = cursorFor(T0, 3), since = T0 - 30_000+ expect(readCursor(cursor, 3, since + 7 * DAY - 3_600_000)).toEqual({ since })+ expect(readCursor(cursor, 3, since + 7 * DAY - 3_600_000 + 1)).toEqual({ reload: true })+ })+})diff --git a/backend/src/superTabs/read/cursor.ts b/backend/src/superTabs/read/cursor.tsnew file mode 100644index 000000000..9368b9741--- /dev/null+++ b/backend/src/superTabs/read/cursor.ts@@ -0,0 +1,21 @@+import { RETENTION_MS } from '../parts/index.js'++/** The longest a transaction lives (15 s, store.ts) plus the clock drift budget between backend processes (spec ruling 3). */+export const OVERLAP_MS = 30_000+/** A cursor this close to tombstone retention reloads, so a purge running a little early never hides a removal. */+const RETENTION_MARGIN_MS = 3_600_000++/** Made when a read starts, before any query: the next read asks for every change committed after `readStart − overlap`. */+export function cursorFor(readStart: number, epoch: number): string {+ return Buffer.from(JSON.stringify({ v: 2, t: readStart - OVERLAP_MS, e: epoch })).toString('base64url')+}++/** Where to read changes from, or a reload: the cursor is unreadable, from another epoch, or older than tombstones. */+export function readCursor(cursor: string, epoch: number, now: number): { since: number } | { reload: true } {+ let parsed: unknown+ try { parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString()) } catch { return { reload: true } }+ const { v, t, e } = (parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}) as Record<string, unknown>+ if (v !== 2 || !Number.isSafeInteger(t) || e !== epoch) return { reload: true }+ if ((t as number) < now - RETENTION_MS + RETENTION_MARGIN_MS) return { reload: true }+ return { since: t as number }+}diff --git a/backend/src/superTabs/read/dormantPage.ts b/backend/src/superTabs/read/dormantPage.tsnew file mode 100644index 000000000..8e39dbd7e--- /dev/null+++ b/backend/src/superTabs/read/dormantPage.ts@@ -0,0 +1,15 @@+import { fail } from '../model.js'+import type { GroupData, Part } from '../parts/index.js'++/** The dormant list's page cursor: unpadded base64url of `{"la": lastActivityAt ms, "k": key}` (design 4.5). */+export function encodeDormantPage(last: Part<GroupData>): string {+ return Buffer.from(JSON.stringify({ la: Date.parse(last.data!.lastActivityAt!), k: last.key })).toString('base64url')+}++export function decodeDormantPage(cursor: string): { lastActivityAt: number; key: string } {+ try {+ const { la, k } = JSON.parse(Buffer.from(cursor, 'base64url').toString()) as { la?: unknown; k?: unknown }+ if (Number.isSafeInteger(la) && typeof k === 'string' && k) return { lastActivityAt: la as number, key: k }+ } catch { /* answered below */ }+ return fail('INVALID_CURSOR', 'Ask for the first page again.', 400)+}diff --git a/backend/src/superTabs/read/fixture.test-support.ts b/backend/src/superTabs/read/fixture.test-support.tsnew file mode 100644index 000000000..cee1a84a3--- /dev/null+++ b/backend/src/superTabs/read/fixture.test-support.ts@@ -0,0 +1,49 @@+/** Test support only: a Swarm built through real commands, for the read views and the migration tests. */+import { applyCommand, type Command, type CommandContext } from '../commands.js'+import { createSuperTab, type Actor, type AgentConfiguration, type SuperTabState } from '../model.js'++export const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: '100000000000000000000001', email: '[email protected]' }+export const peer: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: '100000000000000000000002', email: '[email protected]' }+export const outsider: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: '100000000000000000000003', email: '[email protected]' }+export const config: AgentConfiguration = { engine: 'codex', model: 'test-model', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }+export const NOW = 1_793_010_000_000++export function swarm(now = NOW) {+ let state = createSuperTab('tab', 'Pilot', { id: owner.userId, email: owner.email }, 'prod')+ let sequence = 0+ const run = (command: Command, actor: Actor = owner, context: Partial<CommandContext> = {}) => {+ const effects = applyCommand(state, actor, command, { now, operationId: `op-${++sequence}`, ...context })+ state = effects.state+ return effects.result+ }+ const join = (person: typeof peer) => {+ const { inviteId } = run({ type: 'invite.create', email: person.email, role: 'collaborator', conversationId: 'lead' })+ run({ type: 'invite.accept', inviteId: inviteId as string }, person)+ }+ const add = (harnessId: string, conversationId: string, lead = false, contributor = owner, machineId = 'host', machineOwnerId = `${contributor.userId}-machine`) =>+ run({ type: 'agent.add', conversationId, machineId, harnessId, name: harnessId, configuration: config, lead }, contributor,+ { contribution: { machineOwnerId, contributorId: contributor.userId } }).agentId as string+ const group = (title: string, projectId?: string, actor: Actor = owner) => run({ type: 'conversation.create', ...(projectId ? { projectId } : {}),+ title, brief: `${title} brief`, checks: [{ description: `${title} works`, independent: false }] }, actor).conversationId as string+ const contribute = (machineId: string, scope?: 'swarm') => run({ type: 'machine.contribute', machineId, name: machineId, cwd: '/repo',+ ...(scope ? { scope } : {}), engines: ['codex'], maxAgents: 3 }, owner, { contribution: { machineOwnerId: owner.userId, contributorId: owner.userId } })+ /** Writes outside commands (store observations, ledger, audiences), as the store would. */+ const edit = (change: (draft: SuperTabState) => void) => { change(state) }+ return { run, join, add, group, contribute, edit, get state(): SuperTabState { return state } }+}++/** Two projects (the Swarm's first, public; "Secret", private to the owner), a Lead, two workers, finished and running work. */+export function richSwarm(now = NOW) {+ const s = swarm(now)+ s.join(peer)+ s.join(outsider)+ const lead = s.add('lead-harness', 'lead', true)+ const secret = s.run({ type: 'project.create', name: 'Secret', visibility: 'private', brief: '' }).projectId as string+ const web = s.group('Web')+ const worker = s.add('worker-harness', web)+ const assignmentId = s.run({ type: 'work.assign', conversationId: web, agentId: worker }).assignmentId as string+ const done = s.group('Done work')+ const secretGroup = s.group('Secret work', secret)+ // Not a spread: `state` stays a live getter.+ return Object.assign(s, { lead, worker, secret, web, done, secretGroup, assignmentId })+}diff --git a/backend/src/superTabs/read/host.ts b/backend/src/superTabs/read/host.tsnew file mode 100644index 000000000..58901f17d--- /dev/null+++ b/backend/src/superTabs/read/host.ts@@ -0,0 +1,161 @@+/**+ * The host form (design 4.10): for one machine, the rows of every Swarm it serves (full), or of the Swarms with a change+ * that concerns it since the cursor (incremental). Grants and billing live outside the parts, so the host asks for a full+ * read at start and at least every 60 s.+ */+import { createHash } from 'node:crypto'+import type { Prisma, PrismaClient } from '@prisma/client'+import type { AuthUser } from '../../lib/ssoAuth.js'+import { machineAlive } from '../../lib/prisma.js'+import { isTeamSession } from '../../lib/teamSession.js'+import { machineBillingAllowsDataPlane } from '../../lib/billingState.js'+import { fail, type AgentStart, type SuperTabState } from '../model.js'+import { transaction, type SuperTabStore } from '../store.js'+import * as parts from '../parts/index.js'+import type { MachineData, Part } from '../parts/index.js'+import { READ_FORMAT, type HostChanges, type HostChangesRequest } from './contract.js'+import { cursorFor, readCursor } from './cursor.js'+import { hostTab, type HostLookups } from './hostRows.js'+import { confidentialSessions } from '../confidential.js'++type Transaction = Prisma.TransactionClient+/** The row hash's length at the front of an etag (read/hostEtag.ts); the input signature follows it. */+const ROW_HASH = 22+/** A full read covers this many of the machine's Swarms, most recently changed first (was 100 full Swarms each second). */+const FULL_TABS = 500++/** A change any host of the Swarm cares about from the part alone: names, pause, observers, its agents and starts. */+function plainlyRelevant(part: Part, machineId: string): boolean {+ switch (part.kind) {+ case 'head': case 'member': return true+ case 'agent': return (part.data as { machineId?: string } | null)?.machineId === machineId+ case 'start': return (part.data as AgentStart | null)?.request.machineId === machineId+ default: return false+ }+}+const PLAIN_KINDS = ['head', 'member', 'agent', 'start'] as const++export class HostReads {+ private readonly db: PrismaClient+ private readonly now: () => number+ /** Reads the store's own database, on its clock unless given one (tests). */+ constructor(private readonly store: SuperTabStore, private readonly options: { now?: () => number; githubApp?: boolean; teamAccountsIdle?: boolean } = {}) {+ this.db = store.db+ this.now = options.now ?? store.now+ }++ async changes(user: AuthUser, machineId: string, request: HostChangesRequest): Promise<HostChanges> {+ const t0 = this.now()+ const from = request.cursor && !request.full ? readCursor(request.cursor, 0, t0) : { reload: true as const }+ return transaction(this.db, async tx => {+ await this.store.hostFor(tx, user, machineId)+ const owned = await tx.machine.findFirst({ where: { machineId, userId: user.sub, autonomousEnv: user.autonomousEnv, ...machineAlive } })+ if (!owned || !machineBillingAllowsDataPlane(owned)) fail('HOST_UNAVAILABLE', 'This execution host is unavailable.', 403)+ // Swarms still in one row are migrated when first opened; the job migrates every one before the new release serves.+ const ids = (await tx.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, format: 2,+ OR: [{ machineIds: { has: machineId } }, { cleanupMachineIds: { has: machineId } }] },+ orderBy: { updatedAt: 'desc' }, take: FULL_TABS, select: { id: true } })).map(r => r.id)+ const teams = isTeamSession(user) || this.options.teamAccountsIdle ? [] : await tx.machine.findMany({ where: { userId: user.sub,+ hostMachineId: machineId, sessionKind: 'team', autonomousEnv: user.autonomousEnv, ...machineAlive }, select: { machineId: true } })+ const newest = await parts.lastChangedAt(tx, ids)+ const full = 'reload' in from+ const woken = full ? null : await this.woken(tx, ids, machineId, from.since)+ const tabs = []+ for (const tabId of ids) {+ if (woken && !woken.has(tabId)) continue+ const lastChangedAt = newest.get(tabId) ?? null, held = request.held?.[tabId]+ // The etag is the rows' hash and then the signature of what they were built from. A matching signature answers+ // 'unchanged' from version columns alone. Never on a full read: grants and billing live outside the parts.+ const inputs = await this.inputs(tx, tabId)+ if (!full && held && inputs && held.slice(ROW_HASH) === inputs) { tabs.push({ tabId, lastChangedAt, etag: held, unchanged: true as const }); continue }+ const state = await this.tabState(tx, tabId, machineId)+ const rows = await hostTab(tabId, state, machineId, user, lastChangedAt, await this.lookups(tx, state, teams))+ const etag = rows.etag + (inputs ?? '')+ // The host already holds these rows: say so instead of sending them again.+ tabs.push(held?.slice(0, ROW_HASH) === rows.etag ? { tabId, lastChangedAt, etag, unchanged: true as const } : { ...rows, etag })+ }+ return { format: READ_FORMAT, full, cursor: cursorFor(t0, 0), tabs,+ removedTabIds: full ? [] : await this.removed(tx, user.autonomousEnv, machineId, from.since, new Set(ids)) }+ })+ }++ /**+ * The Swarms with a change for this machine's host since the cursor. Groups and machine parts go by the markers their+ * writes left (parts/commit.ts), since their new data alone cannot say it: a group concerns the host when its agents or+ * its work were on this machine before or after the write (an agent leaving its last group, review round 1); a machine+ * part when its settings or ledger changed, never when only its reading did (every 15 s; group 5's run, 2026-10-26).+ */+ private async woken(tx: Transaction, ids: string[], machineId: string, since: number): Promise<Set<string>> {+ const after = new Date(since)+ const [changed, groups, machines] = await Promise.all([+ parts.loadChanged(tx, ids, after, PLAIN_KINDS),+ tx.swarmGroup.findMany({ where: { tabId: { in: ids }, changedAt: { gt: after }, hostMachineIds: { has: machineId } }, select: { tabId: true } }),+ tx.swarmMachine.findMany({ where: { tabId: { in: ids }, hostChangedAt: { gt: after } }, select: { tabId: true, key: true, data: true } }),+ ])+ const woken = new Set([...ids.filter(id => changed.get(id)?.some(p => plainlyRelevant(p, machineId))), ...groups.map(g => g.tabId)])+ // This machine's own settings, a team account's pool on this Mac, or the Mac this team account follows.+ const follows = new Map((await tx.swarmMachine.findMany({ where: { tabId: { in: [...new Set(machines.map(m => m.tabId))] }, key: machineId },+ select: { tabId: true, data: true } })).map(m => [m.tabId, (m.data as MachineData | null)?.contribution?.hostMachineId]))+ for (const m of machines) {+ if (m.key === machineId || (m.data as MachineData | null)?.contribution?.hostMachineId === machineId || follows.get(m.tabId) === m.key) woken.add(m.tabId)+ }+ return woken+ }++ /** The Swarm's active parts plus, dormant ones included, every group its agents on this machine are in (a finished+ * group that is not archived still keeps its agent from automatic cleanup) and every group of a start it holds (the+ * host still settles a queued start whose group went quiet). */+ private async tabState(tx: Transaction, tabId: string, machineId: string): Promise<SuperTabState> {+ const [agents, starts] = await Promise.all([+ tx.swarmAgent.findMany({ where: { tabId, machineId, deleted: false }, select: { key: true } }),+ tx.swarmStart.findMany({ where: { tabId, machineId, deleted: false, finishedAt: null }, select: { conversationId: true } }),+ ])+ const groupIds = [...new Set(starts.map(s => s.conversationId))]+ // A pool lists every conversation of a project it has a start in.+ const projectIds = groupIds.length ? [...new Set((await tx.swarmGroup.findMany({ where: { tabId, key: { in: groupIds } }, select: { projectId: true } }))+ .map(g => g.projectId ?? 'lead'))] : []+ // Light conversations (parts/light.ts), and only those host rows read: its agents' (dormant ones too, for `active`),+ // the Lead conversations, running work (assignments, attention, stop requests), and its starts' and their projects'.+ return parts.reassemble(await parts.loadLight(tx, tabId, { groups: 'working', agentIds: agents.map(a => a.key), groupIds, projectIds }))+ }++ /**+ * The signature of everything host rows are built from, read from version columns only (no part data): the head,+ * members, agents and starts by their data stamps, machines by their settings marker (not their readings), and+ * conversations by their host-fields digest and dormancy (a post leaves both). Null while a conversation has no digest+ * yet: a missing digest counts as changed.+ */+ private async inputs(tx: Transaction, tabId: string): Promise<string | null> {+ const live = { tabId, deleted: false }, stamp = { key: true, changedAt: true } as const+ const [head, members, agents, starts, machines, digests] = await Promise.all([+ tx.swarmHead.findUnique({ where: { id: `${tabId}:head` }, select: { changedAt: true } }),+ tx.swarmMember.findMany({ where: live, select: stamp }), tx.swarmAgent.findMany({ where: live, select: stamp }),+ tx.swarmStart.findMany({ where: live, select: stamp }),+ tx.swarmMachine.findMany({ where: live, select: { key: true, hostChangedAt: true } }),+ // Every conversation's digest (which carries its id) and dormancy, in key order, as one string: about 23 bytes each.+ tx.swarmGroup.aggregateRaw({ pipeline: [{ $match: { tabId, deleted: false } }, { $sort: { key: 1 } },+ { $group: { _id: null, missing: { $sum: { $cond: [{ $ifNull: ['$hostDigest', false] }, 0, 1] } },+ all: { $push: { $concat: [{ $ifNull: ['$hostDigest', ''] }, { $cond: ['$dormant', '1', '0'] }] } } } },+ { $project: { _id: 0, missing: 1, all: { $reduce: { input: '$all', initialValue: '', in: { $concat: ['$$value', '$$this'] } } } } }] }),+ ])+ const groups = (digests as unknown as Array<{ missing: number; all: string }>)[0] ?? { missing: 0, all: '' }+ if (!head || groups.missing) return null+ const keyed = <T extends { key: string }>(rows: T[]) => rows.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0)+ return createHash('sha256').update(JSON.stringify([head.changedAt, keyed(members), keyed(agents), keyed(starts), keyed(machines), groups.all]))+ .digest('base64url').slice(0, ROW_HASH)+ }++ private async lookups(tx: Transaction, state: SuperTabState, teams: Array<{ machineId: string }>): Promise<HostLookups> {+ const people = await tx.user.findMany({ where: { id: { in: state.people.map(p => p.id) }, autonomousEnv: state.environment }, select: { id: true, email: true } })+ const confidential = await confidentialSessions(tx, state.agents.map(a => a.id))+ return { people, confidential, teams, githubApp: !!this.options.githubApp, agentGrant: target => this.store.agentGrant(tx, state, target) }+ }++ /** Swarms whose record of this machine changed since the cursor and that no longer list it. */+ private async removed(tx: Transaction, autonomousEnv: string, machineId: string, since: number, listed: Set<string>): Promise<string[]> {+ const rows = await tx.swarmMachine.findMany({ where: { machineId, hostChangedAt: { gt: new Date(since) } }, select: { tabId: true } })+ const gone = [...new Set(rows.map(r => r.tabId))].filter(id => !listed.has(id))+ if (!gone.length) return []+ return (await tx.superTab.findMany({ where: { id: { in: gone }, autonomousEnv }, select: { id: true } })).map(r => r.id)+ }+}diff --git a/backend/src/superTabs/read/hostEtag.ts b/backend/src/superTabs/read/hostEtag.tsnew file mode 100644index 000000000..c6fc32a2a--- /dev/null+++ b/backend/src/superTabs/read/hostEtag.ts@@ -0,0 +1,17 @@+import { createHash } from 'node:crypto'+import type { HostTabRows } from './contract.js'++/** JSON with sorted keys, so equal rows hash equal whatever order their records were built in. */+const sorted = (value: unknown): string => JSON.stringify(value, (_key, item: unknown) => item && typeof item === 'object' && !Array.isArray(item)+ ? Object.fromEntries(Object.entries(item as Record<string, unknown>).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : item)++/**+ * A Swarm's host rows as a short hash (design 4.10, Lead's ruling after group 5's run: an active Swarm cost a full roster+ * per tick). Equal rows, equal hash. Left out: the host's own machine reading, which it sent, and each row's change time,+ * which moves with any change in the Swarm; the entry's own `lastChangedAt` still comes with every answer.+ */+export function hostEtag(tab: Omit<HostTabRows, 'etag'>): string {+ const roster = tab.roster.map(row => 'lastChangedAt' in row ? { ...row, lastChangedAt: undefined } : row)+ const pool = tab.pool && { ...tab.pool, machine: { ...tab.pool.machine, observation: undefined } }+ return createHash('sha256').update(sorted({ roster, pool, assignments: tab.assignments })).digest('base64url').slice(0, 22)+}diff --git a/backend/src/superTabs/read/hostRows.ts b/backend/src/superTabs/read/hostRows.tsnew file mode 100644index 000000000..9699f8604--- /dev/null+++ b/backend/src/superTabs/read/hostRows.ts@@ -0,0 +1,109 @@+/**+ * One Swarm's rows for a machine's host (design 4.10): exactly what `GET /hosts/:m`, `/pools` and `/assignments` gave+ * before parts (the store's old host reads, which this replaced), built from a reassembled state, with `revision`+ * replaced by `lastChangedAt` and the Leads conversation id added to agent rows.+ */+import type { AuthUser } from '../../lib/ssoAuth.js'+import { activeWork, agent, isLeads, SuperTabError, conversation, type Agent, type SuperTabState } from '../model.js'+import { hostLocalGrid, machineContribution, type MachineCleanup } from '../machines.js'+import { agentProjectId, agentSetRole, canWatchAgent, isConfidential, groupProject, ledProject, projectsOf, skillModeOf, skillSetOf } from '../projects.js'+import type { HostAgentRow, HostPool, HostRosterRow, HostTabRows } from './contract.js'+import { hostEtag } from './hostEtag.js'++export interface HostLookups {+ /** The Swarm's people with their account emails (observers). */+ people: Array<{ id: string; email: string }>+ /** Its agents whose session is confidential in some Swarm (confidential.ts): nobody but its machine's person watches them. */+ confidential: Set<string>+ /** Throws a SuperTabError when the agent's machine grant is gone (store.ts agentGrant). */+ agentGrant(target: Agent): Promise<void>+ /** This Mac's Harness Team accounts, which join wherever the Mac was added. */+ teams: Array<{ machineId: string }>+ githubApp: boolean+}++/** Removed machines whose host has not yet said it cleaned up (store.ts cleanups). */+const cleanups = (state: SuperTabState): MachineCleanup[] => [+ ...(state.machines ?? []).flatMap(m => m.removal ? [{ machineId: m.machineId, removalId: m.removal.id, machineOwnerId: m.contributorId }] : []),+ ...(state.machineCleanups ?? [])]++export async function hostTab(tabId: string, state: SuperTabState, machineId: string, user: AuthUser, lastChangedAt: number | null, lookups: HostLookups): Promise<HostTabRows> {+ const rows = { tabId, lastChangedAt, roster: await roster(tabId, state, machineId, user, lastChangedAt, lookups),+ pool: pool(tabId, state, machineId, user, lookups.githubApp), assignments: assignments(tabId, state, machineId, user) }+ return { ...rows, etag: hostEtag(rows) }+}++async function roster(tabId: string, state: SuperTabState, machineId: string, user: AuthUser, lastChangedAt: number | null, lookups: HostLookups): Promise<HostRosterRow[]> {+ const rows: HostRosterRow[] = []+ // Where its owner added this Mac and its team account is missing, this host adds that account (cli/src/superTabs/host.ts).+ const mac = state.machines?.find(m => m.machineId === machineId && m.contributorId === user.sub && m.scope === 'swarm' && !m.removal)+ for (const team of mac ? lookups.teams : []) {+ if (state.machines?.some(m => m.machineId === team.machineId) || state.machineCleanups?.some(c => c.machineId === team.machineId)) continue+ rows.push({ tabId, joinTeam: { machineId: team.machineId, name: mac!.name, maxAgents: mac!.maxAgents } })+ }+ for (const target of state.agents.filter(a => a.machineId === machineId && a.machineOwnerId === user.sub)) {+ try { agent(state, target.id); await lookups.agentGrant(target) } catch (error) { if (error instanceof SuperTabError) continue; throw error }+ rows.push(agentRow(tabId, state, machineId, user, lastChangedAt, lookups, target))+ }+ for (const { agentId: id, harnessId } of (state.closingSessions ?? []).filter(c => c.machineId === machineId && c.machineOwnerId === user.sub)) {+ rows.push({ tabId, agent: { id, harnessId, machineId }, closeSession: true, active: false })+ }+ rows.push(...cleanups(state).filter(c => c.machineId === machineId && c.machineOwnerId === user.sub)+ .map(({ removalId }) => ({ tabId, cleanup: { machineId, removalId } })))+ return rows+}++function agentRow(tabId: string, state: SuperTabState, machineId: string, user: AuthUser, lastChangedAt: number | null, lookups: HostLookups, target: Agent): HostAgentRow {+ const closed = lookups.confidential.has(target.id)+ const waiting = state.conversations.find(c => activeWork(c) && c.assignment!.agentId === target.id &&+ c.assignment!.execution.machineId === machineId && ['needs_human', 'blocked'].includes(c.assignment!.status))?.assignment+ const home = projectsOf(state).find(p => p.id === agentProjectId(state, target))+ const custom = home && skillSetOf(home) === 'custom' ? home : null+ const chosen = custom ? agentSetRole(state, custom, target) : null+ return {+ tabId, tabName: state.name, lastChangedAt, paused: state.paused,+ // `active` lets the host release members that are only in archived groups to automatic cleanup.+ active: state.conversations.some(c => !c.archived && c.agentIds.includes(target.id)),+ attention: waiting ? { assignmentId: waiting.id, status: waiting.status, result: waiting.result?.slice(0, 500) ?? null } : null,+ agent: target,+ joinSwarm: state.ownerId === user.sub && target.contributorId === user.sub && !state.machines?.some(m => m.machineId === machineId)+ && state.conversations.some(c => !c.archived && c.leadId === target.id),+ skillMode: home ? skillModeOf(home) : 'orchestration',+ ...(custom ? { role: chosen && { ...chosen, projectId: custom.id } } : {}),+ lead: !!ledProject(state, target.id),+ leadsConversationId: state.leadsConversationId ?? null,+ stopRequested: target.workDecision === 'stop' && !state.conversations.some(c => activeWork(c) && c.assignment?.agentId === target.id),+ observers: lookups.people.filter(p => p.id !== user.sub && canWatchAgent(state, { kind: 'person', userId: p.id, email: p.email }, target, closed))+ .map(p => ({ email: p.email, userId: p.id })),+ // The host refuses every share of a confidential session, ordinary ones too, and remembers it (cli observers.ts).+ confidential: isConfidential(state, target, closed),+ }+}++function pool(tabId: string, state: SuperTabState, machineId: string, user: AuthUser, githubApp: boolean): HostPool | null {+ let contribution+ try { contribution = machineContribution(state, machineId) } catch (error) { if (error instanceof SuperTabError) return null; throw error }+ if (!contribution || contribution.contributorId !== user.sub) return null+ const starts = (state.starts ?? []).filter(s => s.request.machineId === machineId && s.poolGeneration === contribution.generation+ && (!s.harnessId || !s.poolSettled) && !s.error)+ const reservations = (state.harnessReservations ?? []).filter(r => r.machineId === machineId)+ return { tabId, paused: state.paused, machine: contribution, starts,+ ...(contribution.scope === 'swarm' ? { projects: projectsOf(state).filter(p => starts.some(s =>+ groupProject(state, conversation(state, s.request.conversationId)).id === p.id))+ .map(p => ({ id: p.id, leadConversationId: p.leadConversationId, repository: p.repository,+ // A private conversation is chat only and never runs work here, so its id stays with its audience.+ conversationIds: state.conversations.filter(c => !isLeads(c) && !c.audience && groupProject(state, c).id === p.id).map(c => c.id) })) } : {}),+ ...hostLocalGrid(state),+ reservations: reservations.map(({ harnessId, generation }) => ({ harnessId, generation })),+ harnessIds: [...new Set([...state.agents.filter(a => a.machineId === machineId).map(a => a.harnessId), ...reservations.map(r => r.harnessId),+ ...(state.starts ?? []).filter(s => s.request.machineId === machineId && s.harnessId).map(s => s.harnessId!)])],+ ...(githubApp ? { githubApp: true as const } : {}) }+}++function assignments(tabId: string, state: SuperTabState, machineId: string, user: AuthUser) {+ return state.conversations.filter(activeWork).flatMap(group => {+ const work = group.assignment!+ return work.execution.machineId === machineId && work.execution.machineOwnerId === user.sub+ ? [{ tabId, assignmentId: work.id, harnessId: work.execution.harnessId }] : []+ })+}diff --git a/backend/src/superTabs/read/service.ts b/backend/src/superTabs/read/service.tsnew file mode 100644index 000000000..d2c736585--- /dev/null+++ b/backend/src/superTabs/read/service.ts@@ -0,0 +1,130 @@+/**+ * The read API by parts (design section 4; shapes in contract.ts). Every read takes its time `T0` before any query and+ * makes the next cursor from it, so a write that commits late, inside the overlap, is still seen by the next poll.+ */+import type { Prisma, PrismaClient } from '@prisma/client'+import type { AuthUser } from '../../lib/ssoAuth.js'+import { isTeamSession, TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE } from '../../lib/teamSession.js'+import { author, fail, type Actor, type AgentStart } from '../model.js'+import { mentionsWaiting } from '../mentions.js'+import { transaction, type SuperTabStore } from '../store.js'+import { migrateSwarm } from '../migration/migrate.js'+import * as parts from '../parts/index.js'+import type { SwarmParts } from '../parts/index.js'+import { canReadGroup } from '../projects.js'+import { READ_FORMAT, SWARM_MIGRATING, type Changes, type DormantGroups, type FirstLoad, type OneGroup, type SwarmList } from './contract.js'+import { cursorFor, readCursor } from './cursor.js'+import { changesFor } from './changes.js'+import { envelope, groupView, readerView, type ReaderView } from './views.js'+import { decodeDormantPage, encodeDormantPage } from './dormantPage.js'++type Transaction = Prisma.TransactionClient+type LoadOptions = NonNullable<Parameters<typeof parts.loadActive>[2]> & Pick<NonNullable<Parameters<typeof parts.loadLight>[2]>, 'groups'>+interface Read { parts: SwarmParts; actor: Actor; view: ReaderView; lastChangedAt: number | null }++export class SwarmReads {+ private readonly db: PrismaClient+ private readonly now: () => number+ /** Reads the store's own database, on its clock unless given one (tests). */+ constructor(private readonly store: SuperTabStore, private readonly options: { now?: () => number; githubApp?: boolean } = {}) {+ this.db = store.db+ this.now = options.now ?? store.now+ }++ async firstLoad(user: AuthUser, tabId: string, asAgentId?: string): Promise<FirstLoad> {+ const t0 = this.now()+ return this.read(user, tabId, async tx => {+ const { parts: loaded, view, lastChangedAt } = await this.load(tx, user, tabId, asAgentId, t0, { includeRecentStarts: true })+ return { format: READ_FORMAT, tabId, cursor: cursorFor(t0, loaded.visibilityEpoch), serverTime: t0, lastChangedAt, epoch: loaded.visibilityEpoch,+ ...(this.options.githubApp ? { githubApp: true as const } : {}), ...view.parts, derived: view.derived }+ })+ }++ async changes(user: AuthUser, tabId: string, cursor: string, asAgentId?: string): Promise<Changes> {+ const t0 = this.now()+ return this.read(user, tabId, async tx => {+ // Light (parts/light.ts): changed parts come whole from the change feed; the rest is read only to check visibility and+ // derive values: the Lead conversations, those with running work, and those a person's mentions are in (their count).+ const mentioned = asAgentId ? [] : (await tx.superTabMention.findMany({ where: { tabId, personId: user.sub }, select: { conversationId: true },+ distinct: ['conversationId'] })).map(m => m.conversationId)+ const light = { includeRecentStarts: true, groups: 'working' as const, groupIds: mentioned }+ let read = await this.load(tx, user, tabId, asAgentId, t0, light, parts.loadLight)+ const from = readCursor(cursor, read.parts.visibilityEpoch, t0)+ if ('reload' in from) return from+ const changed = (await parts.loadChanged(tx, [tabId], new Date(from.since))).get(tabId) ?? []+ // A changed start whose group went dormant is read against that group, so its readers alone learn of it.+ const held = new Set(read.parts.groups.map(g => g.key))+ const dormant = [...new Set(changed.flatMap(p => p.kind === 'start' ? [(p.data as AgentStart).request.conversationId] : []))].filter(id => !held.has(id))+ if (dormant.length) read = await this.load(tx, user, tabId, asAgentId, t0, { ...light, groupIds: [...mentioned, ...dormant] }, parts.loadLight)+ return { format: READ_FORMAT, reload: false, cursor: cursorFor(t0, read.parts.visibilityEpoch), serverTime: t0, lastChangedAt: read.lastChangedAt,+ epoch: read.parts.visibilityEpoch, ...changesFor(read.view, changed, read.actor), derived: read.view.derived }+ })+ }++ async dormant(user: AuthUser, tabId: string, page: { projectId?: string; before?: string }, asAgentId?: string): Promise<DormantGroups> {+ return this.read(user, tabId, async tx => {+ const loaded = await parts.loadActive(tx, tabId)+ const state = parts.reassemble(loaded)+ const actor = await this.store.actor(tx, user, state, asAgentId)+ author(state, actor)+ const before = page.before ? decodeDormantPage(page.before) : undefined+ const rows = await parts.loadDormant(tx, tabId, { ...(page.projectId ? { projectId: page.projectId } : {}), ...(before ? { before } : {}) })+ const readable = rows.filter(p => { try { return canReadGroup(state, actor, p.data!) } catch { return false } })+ return { groups: readable.map(p => envelope(p, groupView({ ...p.data!, dormant: true }))),+ next: rows.length === 50 ? encodeDormantPage(rows.at(-1)!) : null }+ })+ }++ async group(user: AuthUser, tabId: string, conversationId: string, asAgentId?: string): Promise<OneGroup> {+ const t0 = this.now()+ return this.read(user, tabId, async tx => {+ const { view, parts: loaded, actor } = await this.load(tx, user, tabId, asAgentId, t0, { groupIds: [conversationId] })+ const active = view.parts.groups.find(g => g.key === conversationId)+ if (active) return { group: active }+ // A dormant group is in no whole-Swarm view; it passes the same read check as on the dormant list.+ const dormant = loaded.groups.find(g => g.key === conversationId && g.dormant)+ if (dormant && canReadGroup(view.state, actor, dormant.data!)) return { group: envelope(dormant, groupView({ ...dormant.data!, dormant: true })) }+ return fail('NOT_FOUND', 'This conversation is unavailable.', 404)+ })+ }++ async list(user: AuthUser, after?: string): Promise<SwarmList> {+ if (isTeamSession(user)) fail(TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE, 403)+ const rows = await this.db.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, memberIds: { has: user.sub },+ ...(after ? { id: { gt: after } } : {}) }, orderBy: { id: 'asc' }, take: 101, select: { id: true, ownerId: true, format: true } })+ const page = rows.slice(0, 100)+ // A Swarm not yet in parts is migrated when it is opened; until then the list names it from its old row.+ const legacy = await this.db.superTab.findMany({ where: { id: { in: page.filter(r => r.format !== 2).map(r => r.id) } }, select: { id: true, state: true } })+ const ids = page.filter(r => r.format === 2).map(r => r.id)+ // Every head changed after the epoch: one read of each listed Swarm's head part.+ const [heads, newest] = await transaction(this.db, tx => Promise.all([parts.loadChanged(tx, ids, new Date(0), ['head']), parts.lastChangedAt(tx, ids)]))+ return { tabs: page.map(row => {+ const head = (heads.get(row.id)?.[0]?.data ?? legacy.find(l => l.id === row.id)?.state) as { name: string; paused: boolean }+ return { id: row.id, name: head.name, ownerId: row.ownerId, paused: head.paused, lastChangedAt: newest.get(row.id) ?? null }+ }), next: rows.length > 100 ? page.at(-1)!.id : null }+ }++ /** Runs a read; a Swarm still in one row is migrated first, as a safety net for one the job did not see (design 6.1),+ * and answers 503 while that cannot be done. The store's own loader refuses a Swarm not in parts. */+ private async read<T>(user: AuthUser, tabId: string, body: (tx: Transaction) => Promise<T>): Promise<T> {+ // The row's format only: a migrated row still holds its old state, as large as the Swarm, until the owner drops it.+ const row = await this.db.superTab.findFirst({ where: { id: tabId, autonomousEnv: user.autonomousEnv }, select: { format: true } })+ if (!row) fail('NOT_FOUND', 'This Super Tab is unavailable.', 404)+ if (row.format !== 2 && !(await migrateSwarm(this.db, tabId)).ok) fail(SWARM_MIGRATING.code, SWARM_MIGRATING.message, SWARM_MIGRATING.status)+ return transaction(this.db, body)+ }++ private async load(tx: Transaction, user: AuthUser, tabId: string, asAgentId: string | undefined, t0: number, opts: LoadOptions,+ loader: (tx: Transaction, tabId: string, opts: LoadOptions) => Promise<SwarmParts> = parts.loadActive): Promise<Read> {+ const loaded = await loader(tx, tabId, opts)+ const state = parts.reassemble(loaded)+ const actor = await this.store.actor(tx, user, state, asAgentId)+ const [teamMachines, mentions, newest] = await Promise.all([+ state.machines?.length ? this.store.teamMachines(tx, state) : [],+ actor.kind === 'person' ? mentionsWaiting(tx, tabId, state, actor, t0) : undefined,+ parts.lastChangedAt(tx, [tabId]),+ ])+ return { parts: loaded, actor, lastChangedAt: newest.get(tabId) ?? null,+ view: readerView(loaded, actor, t0, { teamMachines, ...(mentions !== undefined ? { mentionsWaiting: mentions } : {}) }) }+ }+}diff --git a/backend/src/superTabs/read/views.test.ts b/backend/src/superTabs/read/views.test.tsnew file mode 100644index 000000000..8be19383a--- /dev/null+++ b/backend/src/superTabs/read/views.test.ts@@ -0,0 +1,119 @@+import { describe, expect, it } from 'vitest'+import * as store from '../parts/index.js'+import { readerView } from './views.js'+import { NOW, outsider, owner, peer, richSwarm } from './fixture.test-support.js'+import type { Actor } from '../model.js'++const R = 9_000+const MINUTE = 60_000++/** The rich Swarm with a contributed machine, a private conversation for `peer`, and store-written fields. */+function scene() {+ const s = richSwarm()+ s.contribute('mac', 'swarm')+ const privateId = s.group('Peer and PM')+ s.edit(state => {+ const peerGeneration = state.people.find(p => p.id === peer.userId)!.generation+ state.conversations.find(c => c.id === privateId)!.audience = { people: [{ id: peer.userId, generation: peerGeneration }] }+ const worker = state.agents.find(a => a.id === s.worker)!+ worker.downNamed = 'named'+ worker.limitedUntil = new Date(NOW - MINUTE).toISOString()+ worker.downSince = new Date(NOW - 5 * MINUTE).toISOString()+ state.sharing = { revision: 1 } as never+ state.overlapAlerts = ['a:b']+ state.machines![0]!.observation = { generation: 'g', receivedAt: NOW, resources: {} as never, tools: {}, quotas: [],+ runningHarnessIds: ['lead-harness', 'stranger'], stoppedHarnessIds: [] }+ })+ const parts = store.split(s.state, { tabId: 'tab', version: R, now: NOW })+ return { s, parts, privateId }+}+const agentActor = (agentId: string): Actor => ({ kind: 'agent', agentId, machineOwnerId: `${owner.userId}-machine` })+const keys = (list: Array<{ key: string }>) => list.map(p => p.key)++describe('reader view of the parts (design 4.1, 4.3)', () => {+ it('sends the head without owner-only and internal fields, and projects without their progress', () => {+ const { parts } = scene()+ const { head } = readerView(parts, peer, NOW, { teamMachines: [] }).parts+ expect(head).toMatchObject({ key: 'head', version: R, changedAt: NOW })+ for (const hidden of ['sharing', 'overlapAlerts', 'retiredConversationNumber', 'parkedConversations', 'groupCounter', 'sequenceBase']) {+ expect(head.data).not.toHaveProperty(hidden)+ }+ expect(head.data.projects!.map(p => p.name)).toEqual(['Pilot'])+ expect(head.data.projects!.every(p => !('progress' in p))).toBe(true)+ expect(head.data.invitations).toEqual([])+ })++ it('shows invitations and the private project only to those who may read them', () => {+ const { s, parts } = scene()+ s.run({ type: 'invite.create', email: '[email protected]', role: 'viewer', conversationId: 'lead' })+ const view = readerView(store.split(s.state, { tabId: 'tab', version: R, now: NOW }), owner, NOW, { teamMachines: [] }).parts+ expect(view.head.data.invitations.map(i => i.email)).toEqual(['[email protected]'])+ expect(view.head.data.projects!.map(p => p.name)).toEqual(['Pilot', 'Secret'])+ expect(keys(readerView(parts, peer, NOW, { teamMachines: [] }).parts.groups)).not.toContain(s.secretGroup)+ })++ it('keeps a private conversation from every reader outside its audience, the Swarm owner included', () => {+ const { s, parts, privateId } = scene()+ const groups = (actor: Actor) => keys(readerView(parts, actor, NOW, { teamMachines: [] }).parts.groups)+ expect(groups(peer)).toContain(privateId)+ expect(groups(agentActor(s.lead))).toContain(privateId)+ expect(groups(owner)).not.toContain(privateId)+ expect(groups(outsider)).not.toContain(privateId)+ expect(groups(agentActor(s.worker))).not.toContain(privateId)+ expect(readerView(parts, peer, NOW, { teamMachines: [] }).parts.groups.find(g => g.key === privateId)!.data.audience).toBeDefined()+ })++ it('never names a private conversation to the Swarm owner through an invitation', () => {+ const { s, privateId } = scene()+ s.run({ type: 'invite.create', email: '[email protected]', role: 'viewer', conversationId: 'lead' })+ s.edit(state => { state.invitations[0]!.conversationId = privateId })+ const view = readerView(store.split(s.state, { tabId: 'tab', version: R, now: NOW }), owner, NOW, { teamMachines: [] }).parts+ expect(view.head.data.invitations).toEqual([])+ })++ it('sends groups with their message counter and none of the store-only fields', () => {+ const { s, parts } = scene()+ const web = readerView(parts, peer, NOW, { teamMachines: [] }).parts.groups.find(g => g.key === s.web)!+ expect(web).toMatchObject({ version: R, changedAt: NOW, data: { id: s.web, messageSeq: R, number: 1 } })+ for (const hidden of ['reportSeq', 'lastActivityAt', 'dormant', 'audience']) expect(web.data).not.toHaveProperty(hidden)+ })++ it('shows the Leads conversation to people and Leads, not to another agent', () => {+ const { s, parts } = scene()+ const leads = s.state.leadsConversationId!+ expect(keys(readerView(parts, peer, NOW, { teamMachines: [] }).parts.groups)).toContain(leads)+ expect(keys(readerView(parts, agentActor(s.lead), NOW, { teamMachines: [] }).parts.groups)).toContain(leads)+ expect(keys(readerView(parts, agentActor(s.worker), NOW, { teamMachines: [] }).parts.groups)).not.toContain(leads)+ })++ it('keeps time-based agent values out of the part and puts them in derived', () => {+ const { s, parts } = scene()+ const view = readerView(parts, peer, NOW, { teamMachines: [] })+ const worker = view.parts.agents.find(a => a.key === s.worker)!+ for (const hidden of ['downNamed', 'downSince', 'limitedUntil', 'roleId']) expect(worker.data).not.toHaveProperty(hidden)+ expect(view.derived.agents[s.worker]).toEqual({ downSince: new Date(NOW - 5 * MINUTE).toISOString(), limitedUntil: null, workDecision: null, roleId: null })+ expect(Object.keys(view.derived.agents).sort()).toEqual([s.lead, s.worker].sort())+ })++ // Free slots count every session the machine runs, as today, even ones this reader cannot see.+ it('derives a machine\'s free slots and team work, and cuts its harness ids to what the reader can see', () => {+ const { parts } = scene()+ const view = readerView(parts, peer, NOW, { teamMachines: [] })+ expect(view.parts.machines.map(m => m.key)).toEqual(['mac'])+ expect(view.parts.machines[0]!.data.observation!.runningHarnessIds).toEqual(['lead-harness'])+ expect(view.derived.machines).toEqual({ mac: { availableSlots: 1, teamWork: { allowed: true } } })+ })++ it('gives a Lead the other projects\' work and a person the mentions waiting', () => {+ const { s, parts } = scene()+ expect(readerView(parts, agentActor(s.lead), NOW, { teamMachines: [] }).derived).toHaveProperty('otherProjectsWork', [])+ expect(readerView(parts, agentActor(s.lead), NOW, { teamMachines: [] }).derived).not.toHaveProperty('mentionsWaiting')+ expect(readerView(parts, peer, NOW, { teamMachines: [], mentionsWaiting: 2 }).derived).toMatchObject({ mentionsWaiting: 2 })+ expect(readerView(parts, peer, NOW, { teamMachines: [] }).derived).not.toHaveProperty('otherProjectsWork')+ })++ it('refuses a reader who is not a member', () => {+ const { parts } = scene()+ expect(() => readerView(parts, { kind: 'person', userId: 'nobody', email: '[email protected]' }, NOW, { teamMachines: [] })).toThrow(/no longer have access/)+ })+})diff --git a/backend/src/superTabs/read/views.ts b/backend/src/superTabs/read/views.tsnew file mode 100644index 000000000..f13204e0d--- /dev/null+++ b/backend/src/superTabs/read/views.ts@@ -0,0 +1,101 @@+/**+ * What one reader may see of a Swarm's parts (design 4.1): today's `visibleState` rules applied to the reassembled parts,+ * plus the private-conversation check, each record sent in its part's envelope. Time-based and cross-part values go only+ * in `derived`, so a part never changes without a new version (Lead's ruling).+ */+import { isLeads, visibleState, type Actor, type Agent, type Conversation, type SuperTabState } from '../model.js'+import { machineSlots, teamWorkRefusal, type ContributedMachine } from '../machines.js'+import * as store from '../parts/index.js'+import type { Part, SwarmParts } from '../parts/index.js'+import { canReadGroup } from '../projects.js'+import type { AgentView, Derived, GroupView, HeadView, LivePart, MachineView, MemberView, ProgressView, StartView } from './contract.js'++export interface ReaderParts {+ head: LivePart<HeadView>+ members: LivePart<MemberView>[]+ agents: LivePart<AgentView>[]+ groups: LivePart<GroupView>[]+ machines: LivePart<MachineView>[]+ starts: LivePart<StartView>[]+ progress: LivePart<ProgressView>[]+}+export interface ReaderView {+ /** The reassembled stored state the view was made from, for the read checks of changed parts. */+ state: SuperTabState+ parts: ReaderParts+ derived: Derived+}+export interface ReadExtras {+ /** Machines whose account row is a Harness Team account (store read helper). */+ teamMachines: string[]+ /** A person's open mentions, counted by the store. */+ mentionsWaiting?: number+}++const HEAD_FIELDS = ['version', 'id', 'name', 'project', 'projects', 'leadsConversationId', 'ownerId', 'environment',+ 'routingPolicy', 'rules', 'paused', 'invitations', 'localModels'] as const++export const envelope = <T>(part: Pick<Part, 'key' | 'version' | 'changedAt'>, data: T): LivePart<T> =>+ ({ key: part.key, version: part.version, changedAt: part.changedAt, data })++/** A group as readers get it: its message counter, a dormant flag only when dormant, never the store's bookkeeping. */+export function groupView(group: Conversation): GroupView {+ const { messageSeq, reportSeq: _report, lastActivityAt: _activity, dormant, audience, ...rest } = group+ return { ...rest, messageSeq: messageSeq ?? 0, ...(dormant ? { dormant: true as const } : {}), ...(audience ? { audience } : {}) }+}++/** A conversation's whole data as the reader may see it: the Leads conversation lists only the agents the reader can see. */+export function visibleGroupView(group: Conversation, visibleAgents: ReadonlySet<string>): GroupView {+ return groupView(isLeads(group) ? { ...group, agentIds: group.agentIds.filter(id => visibleAgents.has(id)) } : group)+}++export function agentView(agent: Agent): AgentView {+ const { downNamed: _named, downSince: _since, limitedUntil: _limit, roleId: _role, ...rest } = agent+ return rest+}++export function readerView(parts: SwarmParts, actor: Actor, now: number, extras: ReadExtras): ReaderView {+ const state = store.reassemble(parts)+ const visible = visibleState(state, actor, now)+ const groups = visible.conversations.filter(group => canReadGroup(state, actor, group))+ const readable = new Set(groups.map(g => g.id))+ const part = <T>(list: Part<T>[]) => { const keyed = new Map(list.map(p => [p.key, p])); return (key: string) => keyed.get(key)! }+ const agentPart = part(parts.agents), groupPart = part(parts.groups), machinePart = part(parts.machines), startPart = part(parts.starts)+ const head = Object.fromEntries(HEAD_FIELDS.filter(field => visible[field] !== undefined).map(field => [field, visible[field]])) as HeadView+ if (head.projects) head.projects = head.projects.map(({ progress: _progress, ...project }) => project)+ head.invitations = visible.invitations.filter(i => readable.has(i.conversationId))+ const projects = new Set((visible.projects ?? []).map(p => p.id))+ return {+ state,+ parts: {+ head: envelope(parts.head, head),+ members: parts.members.filter(m => !m.deleted).map(m => envelope(m, m.data!)),+ agents: visible.agents.map(a => envelope(agentPart(a.id), agentView(state.agents.find(s => s.id === a.id)!))),+ groups: groups.map(g => envelope(groupPart(g.id), groupView(g))),+ machines: (visible.machines ?? []).map(m => envelope(machinePart(m.machineId), m)),+ starts: (visible.starts ?? []).filter(s => readable.has(s.request.conversationId)).map(s => envelope(startPart(s.id), s)),+ progress: parts.progress.filter(p => !p.deleted && projects.has(p.key)).map(p => envelope(p, progressView(p.data!))),+ },+ derived: derive(state, visible, actor, now, extras),+ }+}++export const progressView = (data: NonNullable<SwarmParts['progress'][number]['data']>): ProgressView =>+ ({ ...data, requestedAt: data.requestedAt ?? null })++function derive(state: SuperTabState, visible: SuperTabState, actor: Actor, now: number, extras: ReadExtras): Derived {+ const machine = (pool: ContributedMachine) => {+ const stored = state.machines!.find(m => m.machineId === pool.machineId)!+ const refusal = teamWorkRefusal(stored, now, extras.teamMachines.includes(pool.machineId))+ return [pool.machineId, { availableSlots: Math.max(0, pool.maxAgents - machineSlots(state, stored)),+ teamWork: refusal ? { allowed: false as const, ...refusal } : { allowed: true as const } }] as const+ }+ return {+ agents: Object.fromEntries(visible.agents.map(seen => [seen.id, { downSince: seen.downSince ?? null, limitedUntil: seen.limitedUntil ?? null,+ workDecision: seen.workDecision === 'awaiting' && state.agents.find(a => a.id === seen.id)!.workDecision !== 'awaiting' ? 'awaiting' as const : null,+ roleId: seen.roleId ?? null }])),+ machines: Object.fromEntries((visible.machines ?? []).map(machine)),+ ...(visible.otherProjectsWork ? { otherProjectsWork: visible.otherProjectsWork } : {}),+ ...(actor.kind === 'person' && extras.mentionsWaiting !== undefined ? { mentionsWaiting: extras.mentionsWaiting } : {}),+ }+}diff --git a/backend/src/superTabs/sessionScope.ts b/backend/src/superTabs/sessionScope.tsindex bf7166622..4744222db 100644--- a/backend/src/superTabs/sessionScope.ts+++ b/backend/src/superTabs/sessionScope.ts@@ -4,10 +4,13 @@ import { agentProjectId, projectOf } from './projects.js'const scopeId = (state: SuperTabState, projectId: string) => stableId(state.id, projectId)+/** The record every Swarm registering one native session writes. */+export const sessionRecordId = (state: SuperTabState, target: Agent) => stableId('swarm-session', state.environment, target.machineOwnerId, target.id)+export async function bindSession(tx: Prisma.TransactionClient, state: SuperTabState, target: Agent, now = Date.now()) {const project = projectOf(state, agentProjectId(state, target))const scope = scopeId(state, project.id)- const id = stableId('swarm-session', state.environment, target.machineOwnerId, target.id)+ const id = sessionRecordId(state, target)const prior = await tx.superTabSessionScope.findUnique({ where: { id } })if (prior?.releasedTabIds.includes(state.id)) fail('SESSION_RELEASED', 'This session was withdrawn while stopping in this Swarm. Start a new Harness here or use it in another Swarm.')if (prior?.closeLeaseUntil && prior.closeLeaseUntil.getTime() > now) fail('CLOSE_PENDING', 'Another Swarm is stopping this session. Wait up to two minutes, then try again.')@@ -18,12 +21,8 @@ export async function bindSession(tx: Prisma.TransactionClient, state: SuperTabSif (!prior) {// Sessions contributed before project privacy existed may already appear// in more than one tab. Inspect those registrations before binding one.- const rows = await tx.superTab.findMany({ where: { autonomousEnv: state.environment, machineIds: { has: target.machineId } } })- scopes = rows.flatMap(row => {- const other = row.state as unknown as SuperTabState- const contributed = other.agents.find(a => a.id === target.id && a.machineOwnerId === target.machineOwnerId)- return contributed ? [scopeId(other, agentProjectId(other, contributed))] : []- })+ const rows = await tx.swarmAgent.findMany({ where: { key: target.id, machineOwnerId: target.machineOwnerId, deleted: false } })+ scopes = rows.map(row => stableId(row.tabId, (row.data as unknown as Agent).projectId ?? 'lead'))}if (prior?.privateScope && prior.privateScope !== scope ||project.visibility === 'private' && scopes.some(id => id !== scope)) {diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex 8bf5e56c4..3ec1885ee 100644--- a/backend/src/superTabs/store.ts+++ b/backend/src/superTabs/store.ts@@ -1,4 +1,4 @@-import { contributedEngines, expireRemovals, hostLocalGrid, LASTING_TEAM_REFUSALS, machineContribution, machineObservationSchema, machineSlots, observedPrivacy, recordAgentPresence, removalPreview, swarmGridRow, teamWorkRefusal, type MachineObservation } from './machines.js'+import { contributedEngines, expireRemovals, LASTING_TEAM_REFUSALS, machineContribution, machineObservationSchema, machineSlots, observedPrivacy, recordAgentPresence, removalPreview, swarmGridRow, teamWorkRefusal, type MachineObservation } from './machines.js'import { createHash } from 'node:crypto'import type { Prisma, PrismaClient, SuperTab, SuperTabDelivery, SuperTabMessage } from '@prisma/client'import type { AuthUser } from '../lib/ssoAuth.js'@@ -12,9 +12,14 @@ import { attachmentMime, attachmentName, AttachmentTooLarge, checkedType, MAX_ATimport { randomBytes } from 'node:crypto'import type { Readable } from 'node:stream'import { logger } from '../utils/logger.js'-import { agentSetRole, canReadAgent, canReadProject, groupProject, ledProject, projectsOf, agentProjectId, readConversation, roleVersion, skillModeOf, skillSetOf, type ProjectVisibility } from './projects.js'+import { canReadAgent, canReadGroup, canWatchAgent, groupProject, ledProject, projectsOf, agentProjectId, readConversation, roleVersion, type ProjectVisibility } from './projects.js'import { bindSession, makeProjectPrivate } from './sessionScope.js'-import { noteProjectReports, projectUpdateRequest } from './projectUpdates.js'+import { confidentialSessions, otherRegistrations, recordConfidential } from './confidential.js'+import { answersRequest, noteProjectReports, projectUpdateRequest } from './projectUpdates.js'+import { judgedMachines, loseTasks, sweepLiveness, SWEEP_EVERY_MS } from './liveness.js'+import { clock, insertParts, lastChangedAt, loadActive, reassemble, split, type HeadData, type SwarmParts } from './parts/index.js'+import { commitParts, indexesOf, numberMessages, type Touch, type Written } from './parts/commit.js'+import { touchesFor } from './parts/touches.js'import { revokeNativeContexts, SuperTabNativeStore } from './native.js'import {activeWork, actorKey, agent, agentOnly, appendPullRequestUrls, author, conversation, createSuperTab, fail, person, stableId, visibleState, finishWorker,@@ -36,57 +41,72 @@ type SendCommand = Extract<Command, { type: 'message.send' }>// Prisma on MongoDB: `usedBy: null` alone misses rows that never had the field.const unused = { OR: [{ usedBy: null }, { usedBy: { isSet: false } }] }const hash = (value: unknown): string => createHash('sha256').update(JSON.stringify(value)).digest('hex')-const stateOf = (row: SuperTab): SuperTabState => {- const state = row.state as unknown as SuperTabState- if (state.version !== 1) fail('UPDATE_REQUIRED', 'Update Harness to open this Super Tab.', 409)- parkLaterConversations(state)- syncLeads(state)- return state+/** A Swarm whose state still waits for its split into parts (design section 6.1) is not served until it is split. */+function requireParts(row: SuperTab): SuperTab {+ if (row.format !== 2) fail('SWARM_MIGRATING', 'This Swarm is being updated. Try again in a moment.', 503)+ return row}-/** Old groups have no link list. Reconstruct theirs from complete stored history once; current groups accumulate- * links on write. */-async function restorePullRequestUrls(tx: Transaction, tabId: string, state: SuperTabState): Promise<void> {- const missing = state.conversations.filter(group => group.pullRequestUrls === undefined)- if (!missing.length) return- const conversationIds = missing.map(group => group.id)- const [messages, attempts] = await Promise.all([- tx.superTabMessage.findMany({ where: { tabId, conversationId: { in: conversationIds }, text: { contains: 'https://github.com/' } },- select: { conversationId: true, text: true }, orderBy: { sequence: 'asc' } }),- tx.superTabAttempt.findMany({ where: { tabId, conversationId: { in: conversationIds } },- select: { conversationId: true, snapshot: true }, orderBy: { createdAt: 'asc' } }),- ])- for (const group of missing) {- const prior = attempts.filter(attempt => attempt.conversationId === group.id)- .map(attempt => attempt.snapshot as unknown as { checks?: Array<{ evidence?: string | null }>; assignment?: { result?: string | null } })- appendPullRequestUrls(group, [- ...messages.filter(message => message.conversationId === group.id).map(message => message.text),- ...prior.flatMap(attempt => [...(attempt.checks ?? []).map(check => check.evidence), attempt.assignment?.result]),- ...group.checks.map(check => check.evidence), group.assignment?.result,- ])- }+/** What a command or read works on: the index row, the parts it loaded, and the state reassembled from them. */+export interface Loaded { row: SuperTab; parts: SwarmParts; state: SuperTabState }+/** Groups, agents, projects and starts a command names, loaded even when dormant or finished (design section 3.1). */+export interface Named { groupIds?: string[]; agentIds?: string[]; projectIds?: string[]; startIds?: string[]; startAgentIds?: string[]; allGroups?: boolean; includeRecentStarts?: boolean }++/** The groups, agents, projects and starts a command names in its own fields (design section 3.1). */+/** Commands that register a session or can make one a Lead or a private member: checked against the other Swarms'+ * registrations (projects.ts requireSingleRegistration). A rebind is refused onto any terminal registered elsewhere already. */+const REGISTERS = new Set(['agent.add', 'agent.started', 'conversation.agent', 'conversation.create', 'conversation.audience', 'project.create'])+/** The session a command registers, when it names one. */+function registeredBy(state: SuperTabState, command: Command): Array<{ machineId: string; harnessId: string }> {+ if (command.type === 'agent.add') return [{ machineId: command.machineId, harnessId: command.harnessId }]+ if (command.type !== 'agent.started') return []+ const start = state.starts?.find(s => s.id === command.startId)+ return start ? [{ machineId: start.request.machineId, harnessId: command.harnessId }] : []+}++function namedFor(command: Command): Named {+ const has = (key: string) => key in command+ const field = (key: string) => (command as Record<string, unknown>)[key] as string | undefined+ const groupIds = [field('conversationId'), command.type === 'agent.start' ? command.request.conversationId : undefined,+ command.type === 'conversation.create' ? command.reviewOf : undefined,+ 'askedIn' in command ? command.askedIn?.conversationId : undefined].filter((id): id is string => !!id)+ // Deleting a project or changing who reads it reaches every one of its groups, dormant ones too: their terminal+ // contexts are revoked from the groups the command loaded (native.ts revokeNativeContexts).+ return { groupIds, startIds: has('startId') ? [field('startId')!] : [],+ projectIds: command.type === 'project.delete' || command.type === 'project.sharing' ? [command.projectId] : [] }+}++/** What a receipt keeps of a command's reply besides its result: the parts it wrote and when (design section 4.7). */+interface ReceiptParts { written: Written[]; lastChangedAt: number }+const receiptParts = (written: Written[], lastChangedAt: number): ReceiptParts => ({ written, lastChangedAt })++/** A stored receipt's reply, the same as the first one; a receipt from before parts gives its tab revision instead. */+function replyOf(prior: { revision: number; result: unknown; parts: unknown }) {+ const kept = prior.parts as ReceiptParts | null+ return { result: prior.result as Record<string, unknown>, parts: kept?.written ?? [],+ ...(kept ? { lastChangedAt: kept.lastChangedAt } : prior.revision ? { legacyRevision: prior.revision } : {}) }+}++/**+ * What a delivery claim, ack or hold touches (spec ruling 9, narrowed). Removing the receiver or an agent sender, or+ * either changing generation, cancels this delivery row, which the claim writes: they conflict on the row. A person+ * sender can also lose the conversation without leaving (project sharing, a new audience), and only their part says so.+ * Touching the receiving agent made every claim of a Lead's deliveries conflict with the others and with the Lead's own+ * posts (benchmark, mixed lane: the Lead's calls ran out of retries).+ */+function deliveryTouches(delivery: SuperTabDelivery): Touch[] {+ return delivery.authorKind === 'person' ? [{ kind: 'member', key: delivery.authorId }] : []+}++/** Loads one Swarm's parts and the state commands run on. Reads never write (design ruling R8); the migration rebuilt+ * every group's link list from its history. */+export async function loadRow(tx: Transaction, row: SuperTab, named: Named = {}): Promise<Loaded> {+ const parts = await loadActive(tx, row.id, named)+ const state = reassemble(parts)+ parkLaterConversations(state)+ syncLeads(state)+ return { row, parts, state }}-const indexes = (state: SuperTabState) => ({- memberIds: state.people.map(p => p.id), invitedEmails: state.invitations.map(i => i.email),- machineIds: [...new Set([...state.agents.map(a => a.machineId), ...(state.machines ?? []).map(m => m.machineId),- ...state.conversations.filter(activeWork).map(c => c.assignment!.execution.machineId), ...(state.closingSessions ?? []).map(c => c.machineId),- ...(state.machineCleanups ?? []).map(c => c.machineId)])],- cleanupMachineIds: cleanups(state).map(c => c.machineId),-})-/** Removed machines whose host has not yet said it cleaned up: still listed (machine.removal), or past the 24 h fallback. */-const cleanups = (state: SuperTabState) => [- ...(state.machines ?? []).flatMap(m => m.removal ? [{ machineId: m.machineId, removalId: m.removal.id, machineOwnerId: m.contributorId }] : []),- ...(state.machineCleanups ?? [])]--/** A machine its owner removed: its host deletes the Swarm's folders for this tab, then says so (machine.cleaned).- * The row has no agent, so a host from before removals skips it. */-const cleanupRows = (tabId: string, state: SuperTabState, machineId: string, ownerId: string) =>- cleanups(state).filter(c => c.machineId === machineId && c.machineOwnerId === ownerId)- .map(({ removalId }) => ({ tabId, cleanup: { machineId, removalId } }))--/** A host reads its 100 most recently changed Swarms. Unordered, a Swarm just joined could be cut by older ones, such as- * Swarms only waiting for this machine to close a removed agent's session. */-const HOST_TABS = { orderBy: { updatedAt: 'desc' as const }, take: 100 }/*** Retrying a transaction never repeats a host action. All effects here are durable database writes.@@ -151,11 +171,13 @@ export interface SuperTabStoreHooks {/** Persistent coordination. Host adapters own execution and must confirm their local session grants. */export class SuperTabStore {readonly native: SuperTabNativeStore- constructor(private readonly db: PrismaClient, private readonly now: () => number = Date.now,+ constructor(readonly db: PrismaClient, readonly now: () => number = Date.now,private readonly attachments: Attachments | null = null, private readonly hooks: SuperTabStoreHooks = {}) {this.native = new SuperTabNativeStore({transaction: body => transaction(db, body),- row: async (tx, user, tabId) => { const row = await this.row(tx, user, tabId); return { row, state: stateOf(row) } },+ load: (tx, user, tabId, groupIds) => this.load(tx, user, tabId, { groupIds }),+ save: (tx, loaded, next, stamp, touches) => this.save(tx, loaded as Loaded, next, stamp, touches),+ stamp: () => clock.next(),agentGrant: (tx, state, target) => this.agentGrant(tx, state, target),contribution: (tx, state, actor, command) => this.contribution(tx, state, actor, command),teamHost: (tx, user) => this.teamHost(tx, user),@@ -167,13 +189,15 @@ export class SuperTabStore {// of theirs. It may host only its own machine and speak only as the agents running there./** The one machine a team session hosts for; null for any other sign-in. One with no machine to act for does nothing. */- private async teamHost(tx: Transaction, user: AuthUser): Promise<string | null> {+ /** Shared with the read API (superTabs/read, design section 7.2). */+ async teamHost(tx: Transaction, user: AuthUser): Promise<string | null> {if (!isTeamSession(user)) return nullreturn (await teamMachine(user, tx))?.machineId ?? fail(TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE, 403)}/** A host route of a team session must name its own machine. */- private async hostFor(tx: Transaction, user: AuthUser, machineId: string): Promise<void> {+ /** Shared with the read API (superTabs/read, design section 7.2). */+ async hostFor(tx: Transaction, user: AuthUser, machineId: string): Promise<void> {const team = await this.teamHost(tx, user)if (team !== null && team !== machineId) fail(TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE, 403)}@@ -218,7 +242,8 @@ export class SuperTabStore {/** The tab's contributed machines whose account row is signed in as a Harness Team account (`Machine.sessionKind`,* lib/teamSession.ts): one of the two signs routing reads that a machine is a Team machine (machines.ts teamWorkCheck). */- private async teamMachines(tx: Transaction, state: SuperTabState): Promise<string[]> {+ /** Shared with the read API (superTabs/read, design section 7.2). */+ async teamMachines(tx: Transaction, state: SuperTabState): Promise<string[]> {const ids = (state.machines ?? []).map(m => m.machineId)if (!ids.length) return []const rows = await tx.machine.findMany({ where: { machineId: { in: ids }, autonomousEnv: state.environment, sessionKind: 'team', ...machineAlive },@@ -253,8 +278,7 @@ export class SuperTabStore {/** Viewers and agents read the same effective policy; it always comes from the tab owner's account. */async tabPolicy(user: AuthUser, tabId: string, asAgentId?: string) {return transaction(this.db, async tx => {- const row = await this.row(tx, user, tabId)- const state = stateOf(row)+ const { state } = await this.load(tx, user, tabId)author(state, await this.actor(tx, user, state, asAgentId))const account = await tx.routingPolicy.findUnique({ where: { id: stableId('routing-policy', state.ownerId, state.environment) } })// The owner's account policy alone, so a field reset to "use account default" can show its value.@@ -263,12 +287,72 @@ export class SuperTabStore {})}- private async row(tx: Transaction, user: AuthUser, tabId: string) {- return await tx.superTab.findFirst({ where: { id: tabId, autonomousEnv: user.autonomousEnv } }) ??- fail('NOT_FOUND', 'This Super Tab is unavailable.', 404)+ /** Shared with the read API (superTabs/read, design section 7.2). */+ async row(tx: Transaction, user: AuthUser, tabId: string) {+ return requireParts(await tx.superTab.findFirst({ where: { id: tabId, autonomousEnv: user.autonomousEnv } }) ??+ fail('NOT_FOUND', 'This Super Tab is unavailable.', 404))+ }++ /** The Swarm a caller may address, loaded from its parts. */+ async load(tx: Transaction, user: AuthUser, tabId: string, named: Named = {}): Promise<Loaded> {+ return loadRow(tx, await this.row(tx, user, tabId), named)+ }++ /** Loads again with more named groups, agents or starts when the first load lacks one a command needs. */+ private async ensure(tx: Transaction, loaded: Loaded, named: Named): Promise<Loaded> {+ if (named.allGroups) return loadRow(tx, loaded.row, named)+ const has = (ids: string[] | undefined, present: (id: string) => boolean) => (ids ?? []).every(present)+ const { state } = loaded+ if (has(named.groupIds, id => state.conversations.some(c => c.id === id)) && has(named.startIds, id => !!state.starts?.some(s => s.id === id))+ && !named.agentIds?.length && !named.projectIds?.length && !named.startAgentIds?.length) return loaded+ return loadRow(tx, loaded.row, named)+ }++ /** A Swarm with one start loaded even when finished, and the start's group even when dormant. */+ private async loadStart(tx: Transaction, user: AuthUser, tabId: string, startId: string): Promise<Loaded> {+ const loaded = await this.load(tx, user, tabId, { startIds: [startId] })+ const start = loaded.state.starts?.find(s => s.id === startId)+ return start ? this.ensure(tx, loaded, { startIds: [startId], groupIds: [start.request.conversationId] }) : loaded}- private async actor(tx: Transaction, user: AuthUser, state: SuperTabState, agentId?: string): Promise<Actor> {+ /** What a command touches beyond its own fields: a named start's group, a decision's group and start, a delivery's+ * group, and every group of the agents it removes or writes into (dormant ones too, design section 1.1 D8). */+ private async moreNamed(tx: Transaction, tabId: string, state: SuperTabState, command: Command): Promise<Named> {+ const named = namedFor(command)+ const groupIds = [...named.groupIds ?? []], startIds = [...named.startIds ?? []], agentIds: string[] = [], startAgentIds: string[] = []+ const start = 'startId' in command ? state.starts?.find(s => s.id === command.startId) : undefined+ if (start) groupIds.push(start.request.conversationId)+ const decisionId = 'decisionId' in command ? command.decisionId : 'routeDecisionId' in command ? command.routeDecisionId : undefined+ if (decisionId) {+ const decision = await readDecision(tx, tabId, decisionId)+ if (decision) groupIds.push(decision.conversationId)+ if (decision?.final?.kind === 'new') startIds.push(decision.final.startId)+ }+ if (command.type === 'delivery.resolve') {+ const delivery = await tx.superTabDelivery.findFirst({ where: { id: command.deliveryId, tabId }, select: { conversationId: true } })+ if (delivery) groupIds.push(delivery.conversationId)+ }+ if (command.type === 'agent.remove' || command.type === 'agent.input' || command.type === 'agent.alert' || command.type === 'agent.rebind') agentIds.push(command.agentId)+ if (command.type === 'agent.remove') startAgentIds.push(command.agentId)+ if (command.type === 'machine.remove') {+ const pool = state.machines?.find(m => m.machineId === command.machineId)+ const machines = new Set([command.machineId, ...(pool ? state.machines!.filter(m => m.hostMachineId === pool.machineId).map(m => m.machineId) : [])])+ agentIds.push(...state.agents.filter(a => machines.has(a.machineId)).map(a => a.id))+ }+ if (command.type === 'member.remove') {+ const machines = new Set((state.machines ?? []).filter(m => m.contributorId === command.userId).map(m => m.machineId))+ agentIds.push(...state.agents.filter(a => a.contributorId === command.userId || machines.has(a.machineId)).map(a => a.id))+ }+ return { groupIds, startIds, agentIds, startAgentIds, projectIds: named.projectIds }+ }++ /** Writes what changed between the loaded state and `next`, and touches the parts the change relied on. */+ private save(tx: Transaction, loaded: Loaded, next: SuperTabState, stamp: number, touches: Touch[] = []) {+ return commitParts(tx, loaded, next, { stamp, touches })+ }++ /** Shared with the read API (superTabs/read, design section 7.2). */+ async actor(tx: Transaction, user: AuthUser, state: SuperTabState, agentId?: string): Promise<Actor> {const team = await this.teamHost(tx, user)if (!agentId) {// A team session never speaks or reads as the person.@@ -283,7 +367,8 @@ export class SuperTabStore {return { kind: 'agent', agentId, machineOwnerId: user.sub }}- private async agentGrant(tx: Transaction, state: SuperTabState, target: Agent): Promise<void> {+ /** Shared with the read API (superTabs/read, design section 7.2). */+ async agentGrant(tx: Transaction, state: SuperTabState, target: Agent): Promise<void> {const machine = await tx.machine.findFirst({ where: { machineId: target.machineId, userId: target.machineOwnerId,autonomousEnv: state.environment, ...machineAlive } })if (!machine || !machineBillingAllowsDataPlane(machine)) fail('HOST_UNAVAILABLE', 'This execution host is unavailable.', 403)@@ -338,7 +423,9 @@ export class SuperTabStore {return { id, revision: prior.revision }}const state = createSuperTab(id, name, { id: user.sub, email: user.email }, user.autonomousEnv, projectVisibility)- await tx.superTab.create({ data: { id, ownerId: user.sub, autonomousEnv: user.autonomousEnv, ...indexes(state), state: json(state) } })+ // Born in parts: its state lives in the Swarm* parts, and `state` only fences older backends (schema.prisma).+ await tx.superTab.create({ data: { id, ownerId: user.sub, autonomousEnv: user.autonomousEnv, ...indexesOf(state), format: 2, state: { version: 2 } } })+ await insertParts(tx, split({ ...state, sequenceBase: 0 }, { tabId: id, version: 1, now: clock.next() }))await tx.superTabOperation.create({ data: { id, tabId: id, actorKey: `person:${user.sub}`, requestHash, revision: 0, result: { id } } })return { id, revision: 0 }})@@ -348,9 +435,10 @@ export class SuperTabStore {this.personOnly(user)const rows = await this.db.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, memberIds: { has: user.sub },...(after ? { id: { gt: after } } : {}) }, orderBy: { id: 'asc' }, take: 101 })- return { tabs: rows.slice(0, 100).map(row => {- const state = stateOf(row)- return { id: row.id, name: state.name, ownerId: row.ownerId, revision: row.revision, paused: state.paused }+ const heads = await this.heads(rows.slice(0, 100))+ return { tabs: rows.slice(0, 100).flatMap(row => {+ const head = heads.get(row.id)+ return head ? [{ id: row.id, name: head.name, ownerId: row.ownerId, revision: row.revision, paused: head.paused }] : []}), next: rows.length > 100 ? rows[99]!.id : null }}@@ -358,17 +446,25 @@ export class SuperTabStore {this.personOnly(user)const email = user.email.trim().toLowerCase()const rows = await this.db.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, invitedEmails: { has: email } }, take: 100 })+ const heads = await this.heads(rows)return rows.flatMap(row => {- const state = stateOf(row)+ const state = heads.get(row.id)+ if (!state) return []return state.invitations.filter(i => i.email === email && i.expiresAt > this.now()).map(i => ({ tabId: row.id, name: state.name, inviteId: i.id, role: i.role, expiresAt: i.expiresAt }))})}+ /** The heads of Swarms already split into parts, by id. */+ private async heads(rows: SuperTab[]): Promise<Map<string, HeadData>> {+ const heads = await this.db.swarmHead.findMany({ where: { id: { in: rows.filter(r => r.format === 2).map(r => `${r.id}:head`) } } })+ return new Map(heads.map(head => [head.tabId, head.data as unknown as HeadData]))+ }+async sharing(user: AuthUser, tabId: string) {this.personOnly(user)return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId)requireSharingOwner(state, user.sub)return sharingDetails(state)})@@ -378,7 +474,7 @@ export class SuperTabStore {this.personOnly(user)const request = saveSharingSchema.parse(input)return transaction(this.db, async tx => {- const row = await this.row(tx, user, tabId), state = stateOf(row)+ const loaded = await this.load(tx, user, tabId), state = structuredClone(loaded.state)requireSharingOwner(state, user.sub)const receiptId = stableId('swarm-sharing', tabId, user.sub, request.operationId), requestHash = hash(request)const prior = await tx.superTabOperation.findUnique({ where: { id: receiptId } })@@ -390,10 +486,9 @@ export class SuperTabStore {}if ((state.sharing?.revision ?? 0) !== request.revision) fail('REVISION_CHANGED', 'Sharing changed elsewhere. Reload it and try again.')state.sharing = configureSharing(state.sharing, request.access, request.rotateLink)- const revision = row.revision + 1- await tx.superTab.update({ where: { id: tabId, revision: row.revision }, data: { revision, state: json(state) } })+ const stamp = clock.next(), { written } = await this.save(tx, loaded, state, stamp, [{ kind: 'member', key: user.sub }])await tx.superTabOperation.create({ data: { id: receiptId, tabId, actorKey: `person:${user.sub}`, requestHash,- revision, result: { generation: state.sharing.generation } } })+ revision: 0, parts: json(receiptParts(written, stamp)), result: { generation: state.sharing.generation } } })return sharingDetails(state)})}@@ -402,7 +497,7 @@ export class SuperTabStore {async previewJoin(user: AuthUser, tabId: string, token?: string) {this.personOnly(user)return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId)const sharing = authorizeSwarmJoin(state, user.email, token)const member = state.people.find(p => p.id === user.sub)return { id: tabId, name: state.name, role: member?.role ?? sharing.access.role, alreadyMember: !!member }@@ -413,7 +508,7 @@ export class SuperTabStore {this.personOnly(user)const request = joinSwarmSchema.parse(input)return transaction(this.db, async tx => {- const row = await this.row(tx, user, tabId), state = stateOf(row)+ const loaded = await this.load(tx, user, tabId), state = structuredClone(loaded.state)// Recheck the current grant before an old receipt. Disabling, replacing, or// changing access can never revive a removed membership through a retry.const sharing = authorizeSwarmJoin(state, user.email, request.token)@@ -426,7 +521,7 @@ export class SuperTabStore {if (result.sharingGeneration !== sharing.generation || !member || (member.generation ?? null) !== result.membershipGeneration) {fail('JOIN_CHANGED', 'This join request is no longer current. Open the latest Swarm link again.')}- return { id: tabId, revision: prior.revision, role: member.role, alreadyMember: result.alreadyMember === true }+ return { id: tabId, role: member.role, alreadyMember: result.alreadyMember === true }}const alreadyMember = !!memberif (!member) {@@ -435,30 +530,25 @@ export class SuperTabStore {}// Existing people retain their role and private-project grants. A general// access link does not promote a viewer or grant a private project.- const revision = row.revision + 1- await tx.superTab.update({ where: { id: tabId, revision: row.revision }, data: { revision, state: json(state), ...indexes(state) } })- await tx.superTabOperation.create({ data: { id: receiptId, tabId, actorKey: `person:${user.sub}`, requestHash, revision,+ // The join relied on the sharing generation the head holds: a concurrent sharing change conflicts with it.+ const stamp = clock.next(), { written } = await this.save(tx, loaded, state, stamp, [{ kind: 'head', key: 'head' }])+ await tx.superTabOperation.create({ data: { id: receiptId, tabId, actorKey: `person:${user.sub}`, requestHash, revision: 0,+ parts: json(receiptParts(written, stamp)),result: { sharingGeneration: sharing.generation, membershipGeneration: member.generation ?? null, alreadyMember } } })- return { id: tabId, revision, role: member.role, alreadyMember }+ return { id: tabId, role: member.role, alreadyMember }})}async read(user: AuthUser, tabId: string, asAgentId?: string) {return transaction(this.db, async tx => {- const row = await this.row(tx, user, tabId)- const state = stateOf(row)+ // A first load shows finished starts until they expire (design section 4.3).+ const { state } = await this.load(tx, user, tabId, { includeRecentStarts: true })const actor = await this.actor(tx, user, state, asAgentId)- if (state.conversations.some(group => group.pullRequestUrls === undefined)) {- await restorePullRequestUrls(tx, tabId, state)- // Keep the revision: this adds optional metadata and does not change work or messages. A concurrent- // command with a newer revision owns the state; its write also reconstructs any missing link lists.- await tx.superTab.updateMany({ where: { id: tabId, revision: row.revision }, data: { state: json(state) } })- }const now = this.now()const visible = visibleState(state, actor, now)const mentions = actor.kind === 'person' ? { mentionsWaiting: await mentionsWaiting(tx, tabId, state, actor, now) } : {}const teamMachines = visible.machines?.length ? await this.teamMachines(tx, state) : []- return { revision: row.revision, state: { ...visible, ...mentions, machines: visible.machines?.map(pool => {+ return { lastChangedAt: (await lastChangedAt(tx, [tabId])).get(tabId) ?? 0, state: { ...visible, ...mentions, machines: visible.machines?.map(pool => {const stored = state.machines!.find(m => m.machineId === pool.machineId)!// Whether it takes teammates' projects now, and if not why (machines.ts teamWorkRefusal): what routing leaves it// out for, and what Desktop can show on the machine.@@ -471,7 +561,7 @@ export class SuperTabStore {async start(user: AuthUser, tabId: string, startId: string, asAgentId?: string, hostMachineId?: string) {return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const state = (await this.loadStart(tx, user, tabId, startId)).stateconst actor = hostMachineId ? await this.poolHostActor(tx, user, state, hostMachineId, startId) : await this.actor(tx, user, state, asAgentId)author(state, actor, true)const start = state.starts?.find(s => s.id === startId) ?? fail('NOT_FOUND', 'This agent start is unavailable.', 404)@@ -498,8 +588,10 @@ export class SuperTabStore {const command = input.commandif (command?.type === 'agent.startDispatch' && hostMachineId && error instanceof SuperTabError && LASTING_TEAM_REFUSALS.includes(error.code)) {// Only one never launched: a repeated dispatch of a launched start is admitted again too, and its agent may be starting.- const row = await this.db.superTab.findFirst({ where: { id: tabId, autonomousEnv: user.autonomousEnv } })- const start = row ? stateOf(row).starts?.find(s => s.id === command.startId) : undefined+ const start = await transaction(this.db, async tx => {+ const row = await tx.superTab.findFirst({ where: { id: tabId, autonomousEnv: user.autonomousEnv } })+ return row?.format === 2 ? (await loadRow(tx, row, { startIds: [command.startId] })).state.starts?.find(s => s.id === command.startId) : undefined+ })if (start && !start.dispatched && !start.harnessId && !start.error) {await this.executeOnce(user, tabId, { operationId: `team-refused-${command.startId}`,command: { type: 'agent.startFailed', startId: command.startId, error: error.message } }, asAgentId, hostMachineId)@@ -516,8 +608,10 @@ export class SuperTabStore {const done = await transaction(this.db, async tx => {// A retried attempt starts again: only the attempt that commits says which tasks ended.ended = []- const row = await this.row(tx, user, tabId)- const original = stateOf(row)+ const stamp = clock.next()+ const first = await this.load(tx, user, tabId, namedFor(command))+ const loaded = await this.ensure(tx, first, await this.moreNamed(tx, tabId, first.state, command))+ const original = loaded.stateconst team = await this.teamHost(tx, user)// Removal retries can arrive after the actor itself left. Return only this host's exact prior receipt.if (command.type === 'agent.remove' && asAgentId === command.agentId && !original.agents.some(a => a.id === asAgentId)) {@@ -525,7 +619,7 @@ export class SuperTabStore {const result = prior?.result as Record<string, unknown> | undefined// A team session's only if the removed agent ran on its machine; a receipt from before that was recorded is not.if (prior && prior.requestHash === hash(command) && result?.releasedBy === user.sub && (team === null || result.releasedMachineId === team)) {- return { revision: prior.revision, result: prior.result }+ return replyOf(prior)}fail('FORBIDDEN', 'Only the execution host can confirm this removal.', 403)}@@ -566,10 +660,12 @@ export class SuperTabStore {!projectsOf(original).some(p => p.id === (prior.result as Record<string, unknown>).projectId)) {fail('NOT_FOUND', 'This project was deleted. Create a new project.', 404)}- return { revision: prior.revision, result: prior.result }+ return replyOf(prior)}if (command.type !== 'invite.accept' && command.type !== 'agent.sessionClosed' && command.type !== 'machine.cleaned') author(original, actor)const context: CommandContext = { operationId, now: this.now() }+ if (command.type === 'agent.screen' || command.type === 'agent.input') context.confidentialSession = await this.confidential(tx, command.agentId)+ if (REGISTERS.has(command.type)) context.registrations = await otherRegistrations(tx, original, registeredBy(original, command))if ('startId' in command && ['agent.startDispatch', 'agent.started', 'agent.startFailed', 'agent.startSettled', 'route.modelResult'].includes(command.type)) {const start = original.starts?.find(s => s.id === command.startId)if (start?.poolGeneration && !hostMachineId) fail('HOST_REQUIRED', 'Only the contributed machine can confirm this start.', 403)@@ -648,7 +744,6 @@ export class SuperTabStore {// A dispatch reads its start's decision only to see whether a person chose this start by hand (rules.ts).const dispatched = command.type === 'agent.startDispatch' ? original.starts?.find(s => s.id === command.startId)?.routeDecisionId : undefinedif (dispatched) context.routeDecision = await readDecision(tx, tabId, dispatched) ?? undefined- await restorePullRequestUrls(tx, tabId, original)const effects = applyCommand(original, actor, command, context)// An agent-only notice changes nothing people see: no link, no unread mark, no project report.const shown = effects.messages.filter(message => !agentOnly(message.source))@@ -662,10 +757,8 @@ export class SuperTabStore {const target = agent(effects.state, command.agentId)// A terminal can already belong to a different project or Swarm on this host. The pure// transition checks this tab; inspect the other registrations inside the same transaction.- const registrations = await tx.superTab.findMany({ where: { autonomousEnv: original.environment,- machineIds: { has: target.machineId } } })- if (registrations.some(row => stateOf(row).agents.some(a => a.machineId === target.machineId- && a.harnessId === command.harnessId && a.id !== target.id))) {+ const registrations = await tx.swarmAgent.findMany({ where: { machineId: target.machineId, deleted: false } })+ if (registrations.some(row => (row.data as unknown as Agent).harnessId === command.harnessId && row.key !== target.id)) {fail('SESSION_CONTRIBUTED', 'The replacement terminal already belongs to another member.')}if (target.harnessId !== agent(original, target.id).harnessId) {@@ -679,10 +772,28 @@ export class SuperTabStore {const target = agent(effects.state, effects.result.agentId as string)await bindSession(tx, effects.state, target, context.now)}+ // A session that just became confidential writes the record its registrations write (confidential.ts).+ for (const target of effects.state.agents) {+ if (target.confidential && !original.agents.find(a => a.id === target.id)?.confidential) await recordConfidential(tx, effects.state, target, context.now)+ }if (command.type === 'project.sharing' && command.visibility === 'private') {await makeProjectPrivate(tx, effects.state, command.projectId)}await revokeNativeContexts(tx, original, effects.state)+ // Rule (b) for claims (design D10): a change to who a conversation's deliveries may reach writes those delivery rows,+ // so a claim of one conflicts with it. Archiving keeps them for when it reopens, as before.+ const regrouped = command.type === 'conversation.archive' && command.archived || command.type === 'conversation.audience'+ || command.type === 'conversation.agent' && !command.present+ if (regrouped) {+ await tx.superTabDelivery.updateMany({ where: { tabId, conversationId: command.conversationId, status: { in: ['queued', 'claimed', 'uncertain'] },+ ...(command.type === 'conversation.agent' ? { agentId: command.agentId } : {}) }, data: { updatedAt: new Date(context.now) } })+ }+ if (command.type === 'conversation.audience') {+ const kept = new Set(conversation(effects.state, command.conversationId).audience?.people.map(p => p.id))+ const removed = (conversation(original, command.conversationId).audience?.people ?? []).filter(p => !kept.has(p.id)).map(p => p.id)+ if (removed.length) await tx.superTabDelivery.updateMany({ where: { tabId, conversationId: command.conversationId, authorKind: 'person',+ authorId: { in: removed }, status: { in: ['queued', 'claimed', 'uncertain'] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } })+ }const removedGroups = original.conversations.filter(c => !effects.state.conversations.some(n => n.id === c.id))if (removedGroups.length) {// Keep immutable history and operation receipts for audit/replay; all@@ -690,38 +801,25 @@ export class SuperTabStore {await tx.superTabDelivery.updateMany({ where: { tabId, conversationId: { in: removedGroups.map(c => c.id) },status: { in: ['queued', 'claimed', 'uncertain'] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } })}- const revision = row.revision + 1+ // Each conversation numbers its own messages; a shown one is its latest and counts toward its project's reports.+ const sequences = numberMessages(effects.state, effects.messages, context.now)+ noteProjectReports(effects.state, shown, sequences, context.now)if (command.type === 'work.assign' || command.type === 'work.status' || command.type === 'message.send') {const group = conversation(effects.state, command.conversationId)const assignment = group.assignmentif (assignment && (command.type !== 'message.send' || actor.kind === 'agent' && actor.agentId === assignment.agentId)) {// Even an unchanged working status is fresh evidence that the agent// continued. An older queued gap must not turn that progress into Stuck.- assignment.recordingProgress = { at: context.now, revision }- }- }- if (command.type === 'agent.add' || command.type === 'agent.started' || command.type === 'agent.configuration' || command.type === 'agent.rebind') {- for (const target of effects.state.agents) {- if (target.configurationVersion !== receiptId) continue- const previous = original.agents.find(a => a.id === target.id)- if (previous?.configurationVersion === target.configurationVersion) continue- await tx.superTabConfiguration.create({ data: {- id: stableId(tabId, target.id, operationId), tabId, agentId: target.id, revision,- configuration: json(target.configuration), actorKey: actorKey(actor), observedAt: new Date(context.now),- assignmentIds: effects.state.conversations.filter(group => activeWork(group) && group.assignment?.agentId === target.id)- .map(group => group.assignment!.id),- } })+ assignment.recordingProgress = { at: context.now, revision: group.messageSeq ?? 0 }}}- for (const message of shown) conversation(effects.state, message.conversationId).lastMessageSequence = revision- noteProjectReports(effects.state, shown, revision, context.now)if (command.type === 'agent.release' && command.decision === 'stop') {const target = agent(effects.state, command.agentId)const assignmentId = `release-${target.releaseId}`const running = await tx.superTabRun.findUnique({ where: { id: target.id } })if (running && (running.tabId !== tabId || running.assignmentId !== assignmentId)) fail('AGENT_BUSY', 'This agent already owns active work in a Swarm or is stopping elsewhere.')- const registrations = await tx.superTab.findMany({ where: { autonomousEnv: original.environment, machineIds: { has: target.machineId }, id: { not: tabId } } })- if (registrations.some(row => stateOf(row).agents.some(a => a.id === target.id && a.machineOwnerId === target.machineOwnerId))) {+ const registrations = await tx.swarmAgent.findMany({ where: { key: target.id, deleted: false, tabId: { not: tabId } } })+ if (registrations.some(row => row.machineOwnerId === target.machineOwnerId)) {fail('SESSION_SHARED', 'This session is still shared with another Swarm. Withdraw it there before stopping it here.')}// Serialize new contributions with stop intent; bindSession writes this same native-session record.@@ -764,9 +862,21 @@ export class SuperTabStore {await tx.superTabDelivery.updateMany({ where: { tabId, assignmentId: group.assignment!.id,status: { in: ['queued', 'claimed', 'uncertain'] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } })}- await tx.superTab.update({ where: { id: tabId, revision: row.revision }, data: {- revision, state: json(effects.state), ...indexes(effects.state),- } })+ const committed = await this.save(tx, loaded, effects.state, stamp, touchesFor(command, actor, original, effects, context))+ if (command.type === 'agent.add' || command.type === 'agent.started' || command.type === 'agent.configuration' || command.type === 'agent.rebind') {+ for (const target of effects.state.agents) {+ if (target.configurationVersion !== receiptId) continue+ const previous = original.agents.find(a => a.id === target.id)+ if (previous?.configurationVersion === target.configurationVersion) continue+ // Ordered by the agent part's version, which never resets and starts above every older tab revision.+ await tx.superTabConfiguration.create({ data: {+ id: stableId(tabId, target.id, operationId), tabId, agentId: target.id, revision: committed.versions.get(`agent:${target.id}`) ?? 0,+ configuration: json(target.configuration), actorKey: actorKey(actor), observedAt: new Date(context.now),+ assignmentIds: effects.state.conversations.filter(group => activeWork(group) && group.assignment?.agentId === target.id)+ .map(group => group.assignment!.id),+ } })+ }+ }ended = endedHolds(original, effects.state)await writeRouteEffects(tx, tabId, effects.routeDecisions, context.now)if (command.type === 'agent.startFailed') {@@ -795,7 +905,7 @@ export class SuperTabStore {if (command.type === 'work.status' && (command.status === 'done' || command.status === 'stopped')) {await closeAssignment(tx, tabId, command.assignmentId, command.status, context.now)}- await this.writeMessages(tx, tabId, effects.state, effects.messages, revision)+ await this.writeMessages(tx, tabId, effects.state, effects.messages, sequences)if (command.type === 'message.send' && actor.kind === 'person') await resolveByReply(tx, tabId, command.conversationId, actor.userId, context.now)await writeMentions(tx, tabId, effects.state, effects.messages, context.now)if (command.type === 'mention.done') await markDone(tx, tabId, command.mentionId, context.mention!.personId, context.now)@@ -813,8 +923,9 @@ export class SuperTabStore {data: { status: 'answered', answeredAt: new Date(context.now), holdReason: null, holdSince: null } })}if (command.type === 'project.report' && actor.kind === 'agent') {- const progress = projectsOf(original).find(p => p.id === command.projectId)?.progress- if (progress?.requestMessageId && command.throughRevision >= progress.requestedRevision) {+ // Judged on the progress after this report summarized what it names.+ const progress = projectsOf(effects.state).find(p => p.id === command.projectId)?.progress+ if (progress?.requestMessageId && answersRequest(progress, command.throughRevision)) {await tx.superTabDelivery.updateMany({ where: { tabId, agentId: actor.agentId, messageId: progress.requestMessageId,status: { in: ['queued', 'claimed', 'uncertain', 'delivered', 'confirmed'] } },data: { status: 'answered', answeredAt: new Date(context.now), holdReason: null, holdSince: null } })@@ -835,8 +946,8 @@ export class SuperTabStore {await tx.superTabAttempt.create({ data: { id: attempt.assignment.id, tabId, conversationId: attempt.conversationId, snapshot: json(attempt) } })}await tx.superTabOperation.create({ data: { id: receiptId, tabId, actorKey: actorKey(actor), requestHash,- revision, result: json(effects.result) } })- return { revision, result: effects.result }+ revision: 0, parts: json(receiptParts(committed.written, stamp)), result: json(effects.result) } })+ return { result: effects.result, parts: committed.written, lastChangedAt: stamp }})this.endWork(tabId, ended)return done@@ -855,7 +966,7 @@ export class SuperTabStore {async githubAssignment(user: AuthUser, tabId: string, asAgentId: string | undefined, machineId: string) {if (!asAgentId) fail('AGENT_REQUIRED', 'Ask for a GitHub token as the agent doing the work (asAgentId).', 400)return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId)const actor = await this.actor(tx, user, state, asAgentId)// A read-only contribution reads; it does not push.author(state, actor, true)@@ -884,7 +995,7 @@ export class SuperTabStore {*/async githubStart(user: AuthUser, tabId: string, startId: string, machineId: string) {return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.loadStart(tx, user, tabId, startId)const actor = await this.poolHostActor(tx, user, state, machineId, startId)const start = state.starts?.find(s => s.id === startId) ?? fail('NOT_FOUND', 'This agent start is unavailable.', 404)if (start.harnessId || start.error) fail('START_SETTLED', 'This start has already started or failed; its folder is not prepared again.', 409)@@ -939,7 +1050,7 @@ export class SuperTabStore {/** The actor, once it may post in this conversation. */private async poster(tx: Transaction, user: AuthUser, tabId: string, conversationId: string, asAgentId?: string) {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId, { groupIds: [conversationId] })const actor = await this.actor(tx, user, state, asAgentId)author(state, actor, true)readConversation(state, actor, conversationId)@@ -979,7 +1090,7 @@ export class SuperTabStore {* in their roster changes). Anyone else, like a missing role, reads it as unavailable. */async roleText(user: AuthUser, tabId: string, projectId: string, roleId: string, asAgentId?: string) {return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId)const unavailable = () => fail('NOT_FOUND', 'This role is unavailable.', 404)const project = projectsOf(state).find(p => p.id === projectId) ?? unavailable()const role = project.roles?.find(r => r.id === roleId) ?? unavailable()@@ -1027,14 +1138,14 @@ export class SuperTabStore {const deadline = Date.now() + waitMsfor (;;) {const answer = await transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId)const actor = await this.actor(tx, user, state, asAgentId)author(state, actor)const now = this.now()const row = await tx.superTabTerminalRequest.findFirst({ where: { id: requestId, tabId, createdAt: { gte: new Date(now - TERMINAL_EXPIRY_MS) } } })if (!row || row.requesterKey !== actorKey(actor)) fail('NOT_FOUND', 'This terminal request is unavailable.', 404)// A sender who has since lost write access, or is no longer the agent's project Lead, gets nothing.- mayDrive(state, actor, agent(state, row.agentId))+ mayDrive(state, actor, agent(state, row.agentId), await this.confidential(tx, row.agentId))const late = row.status === 'pending' && now - row.createdAt.getTime() > TERMINAL_PICKUP_MS? 'The agent’s machine did not pick up the request within 10 seconds. It may be offline or asleep.': row.status === 'claimed' && now - row.claimedAt!.getTime() > TERMINAL_ANSWER_MS@@ -1065,7 +1176,7 @@ export class SuperTabStore {for (const row of rows) {if (!states.has(row.tabId)) {const tab = await tx.superTab.findFirst({ where: { id: row.tabId, autonomousEnv: user.autonomousEnv } })- states.set(row.tabId, tab && stateOf(tab))+ states.set(row.tabId, tab?.format === 2 ? (await loadRow(tx, tab)).state : null)}const refusal = now - row.createdAt.getTime() > TERMINAL_PICKUP_MS? 'The agent’s machine did not pick up the request within 10 seconds. It may be offline or asleep.'@@ -1095,7 +1206,7 @@ export class SuperTabStore {try {agent(state, target.id)await this.agentGrant(tx, state, target)- mayDrive(state, requester, target)+ mayDrive(state, requester, target, await this.confidential(tx, target.id))} catch (error) {if (error instanceof SuperTabError) return 'This request is no longer allowed.'throw error@@ -1103,11 +1214,11 @@ export class SuperTabStore {return null}- /** Records committed messages and one delivery per recipient, at the tab revision that carried them. */- private async writeMessages(tx: Transaction, tabId: string, state: SuperTabState, messages: MessageDraft[], revision: number) {+ /** Records committed messages, each at the sequence its conversation gave it, and one delivery per recipient. */+ private async writeMessages(tx: Transaction, tabId: string, state: SuperTabState, messages: MessageDraft[], sequences: ReadonlyMap<string, number>) {for (const message of messages) {await tx.superTabMessage.create({ data: { id: message.id, tabId, conversationId: message.conversationId,- sequence: revision, author: json(message.author), ...(message.source ? { source: json(message.source) } : {}),+ sequence: sequences.get(message.id)!, author: json(message.author), ...(message.source ? { source: json(message.source) } : {}),...(message.attachments ? { attachments: json(message.attachments) } : {}),text: message.text, replyTo: message.replyTo, recipientIds: message.recipients, mentions: message.mentions ?? [] } })for (const recipient of message.recipients) {@@ -1123,31 +1234,37 @@ export class SuperTabStore {}}- async messages(user: AuthUser, tabId: string, conversationId: string, cursor: { after?: number; before?: number; messageId?: string }, asAgentId?: string) {+ /** One page of a conversation, read by (sequence, id): rows written by one command before the store by parts share a+ * sequence, so a page edge inside such a run must not skip any (design section 4.6). `after` alone reads strictly after+ * a sequence, which is enough to poll for new messages. */+ async messages(user: AuthUser, tabId: string, conversationId: string,+ cursor: { after?: number; afterId?: string; before?: number; beforeId?: string; messageId?: string }, asAgentId?: string) {return transaction(this.db, async tx => {- const row = await this.row(tx, user, tabId)- const state = stateOf(row)+ const { state } = await this.load(tx, user, tabId, { groupIds: [conversationId] })const actor = await this.actor(tx, user, state, asAgentId)readConversation(state, actor, conversationId)const forward = cursor.after !== undefined+ const past = (sequence: number, id: string | undefined, direction: 'gt' | 'lt') => id === undefined ? { sequence: { [direction]: sequence } }+ : { OR: [{ sequence: { [direction]: sequence } }, { sequence, id: { [direction]: id } }] }const where = { tabId, conversationId,...(cursor.messageId ? { id: cursor.messageId } : {}),- ...(forward ? { sequence: { gt: cursor.after } } : cursor.before !== undefined ? { sequence: { lt: cursor.before } } : {}) }+ ...(forward ? past(cursor.after!, cursor.afterId, 'gt') : cursor.before !== undefined ? past(cursor.before, cursor.beforeId, 'lt') : {}) }// An agent-only notice is listed for its own recipient alone. 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.const rows: SuperTabMessage[] = []for (let skip = 0; rows.length <= 100; skip += 101) {- const batch = await tx.superTabMessage.findMany({ where, orderBy: { sequence: forward ? 'asc' : 'desc' }, skip, take: 101 })+ const order = forward ? 'asc' as const : 'desc' as const+ const batch = await tx.superTabMessage.findMany({ where, orderBy: [{ sequence: order }, { id: order }], skip, take: 101 })rows.push(...batch.filter(m => !agentOnly(m.source) || (actor.kind === 'agent' && m.recipientIds.includes(actor.agentId))))if (batch.length < 101) break}const page = rows.slice(0, 100)- const next = rows.length > 100 ? page.at(-1)!.sequence : null+ const next = rows.length > 100 ? { sequence: page.at(-1)!.sequence, id: page.at(-1)!.id } : nullif (!forward) page.reverse()const deliveries = page.length ? await tx.superTabDelivery.findMany({ where: { tabId, messageId: { in: page.map(m => m.id) } },select: { id: true, messageId: true, agentId: true, status: true, receipt: true,holdReason: true, holdSince: true, deliveredAt: true, answeredAt: true, createdAt: true, updatedAt: true } }) : []- return { messages: page.map(m => ({ ...m, mentions: m.mentions ?? [], deliveries: deliveries.filter(d => d.messageId === m.id) })), next, revision: row.revision }+ return { messages: page.map(m => ({ ...m, mentions: m.mentions ?? [], deliveries: deliveries.filter(d => d.messageId === m.id) })), next }})}@@ -1155,8 +1272,8 @@ export class SuperTabStore {async mentions(user: AuthUser, tabId: string, state: 'waiting' | 'earlier') {this.personOnly(user)return transaction(this.db, async tx => {- const row = await this.row(tx, user, tabId)- return { mentions: await listMentions(tx, tabId, stateOf(row), { kind: 'person', userId: user.sub, email: user.email }, this.now(), state === 'waiting') }+ const { state: tab } = await this.load(tx, user, tabId, { allGroups: true })+ return { mentions: await listMentions(tx, tabId, tab, { kind: 'person', userId: user.sub, email: user.email }, this.now(), state === 'waiting') }})}@@ -1167,7 +1284,7 @@ export class SuperTabStore {*/async attempts(user: AuthUser, tabId: string, conversationId: string, asAgentId?: string) {return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId, { groupIds: [conversationId] })readConversation(state, await this.actor(tx, user, state, asAgentId), conversationId)const rows = await tx.superTabAttempt.findMany({ where: { tabId, conversationId }, orderBy: { createdAt: 'desc' }, take: 50 })return rows.map(row => {@@ -1179,9 +1296,11 @@ export class SuperTabStore {async routeDecisions(user: AuthUser, tabId: string, asAgentId?: string) {return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId, { allGroups: true })const actor = await this.actor(tx, user, state, asAgentId)- const groups = visibleState(state, actor).conversations.map(c => c.id)+ author(state, actor)+ // Dormant conversations count too: their decisions stay readable (the list loads every group for this).+ const groups = state.conversations.filter(c => canReadGroup(state, actor, c)).map(c => c.id)const rows = await tx.superTabRouteDecision.findMany({ where: { tabId, conversationId: { in: groups } }, orderBy: { createdAt: 'desc' }, take: 100 })return rows.map(timedDecisionOf)})@@ -1189,12 +1308,13 @@ export class SuperTabStore {async routeDecision(user: AuthUser, tabId: string, decisionId: string, asAgentId?: string) {return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const row = await tx.superTabRouteDecision.findFirst({ where: { id: decisionId, tabId }, select: { conversationId: true } })+ const { state } = await this.load(tx, user, tabId, { groupIds: row ? [row.conversationId] : [] })const actor = await this.actor(tx, user, state, asAgentId)author(state, actor)- const row = await tx.superTabRouteDecision.findFirst({ where: { id: decisionId, tabId } })- if (row) readConversation(state, actor, row.conversationId)- return row ? timedDecisionOf(row) : fail('NOT_FOUND', 'This routing decision is unavailable.', 404)+ const decision = await tx.superTabRouteDecision.findFirst({ where: { id: decisionId, tabId } })+ if (decision) readConversation(state, actor, decision.conversationId)+ return decision ? timedDecisionOf(decision) : fail('NOT_FOUND', 'This routing decision is unavailable.', 404)})}@@ -1223,36 +1343,10 @@ export class SuperTabStore {return actor}- async hostPools(user: AuthUser, machineId: string) {- return transaction(this.db, async tx => {- await this.hostFor(tx, user, machineId)- const owned = await tx.machine.findFirst({ where: { machineId, userId: user.sub, autonomousEnv: user.autonomousEnv, ...machineAlive } })- if (!owned || !machineBillingAllowsDataPlane(owned)) fail('HOST_UNAVAILABLE', 'This execution host is unavailable.', 403)- const rows = await tx.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, machineIds: { has: machineId } }, ...HOST_TABS })- return rows.flatMap(row => {- const state = stateOf(row)- let pool- try { pool = machineContribution(state, machineId) } catch (error) { if (error instanceof SuperTabError) return []; throw error }- if (!pool || pool.contributorId !== user.sub) return []- const starts = (state.starts ?? []).filter(s => s.request.machineId === machineId && s.poolGeneration === pool.generation && (!s.harnessId || !s.poolSettled) && !s.error)- return [{ tabId: row.id, paused: state.paused, machine: pool, starts,- ...(pool.scope === 'swarm' ? { projects: projectsOf(state).filter(p => starts.some(s =>- groupProject(state, conversation(state, s.request.conversationId)).id === p.id))- .map(p => ({ id: p.id, leadConversationId: p.leadConversationId, repository: p.repository,- conversationIds: state.conversations.filter(c => !isLeads(c) && groupProject(state, c).id === p.id).map(c => c.id) })) } : {}),- // The Swarm's grid while the Local models add-on is on: the host reports the models it serves there, and asks grid- // nothing while it is off.- ...hostLocalGrid(state),- reservations: (state.harnessReservations ?? []).filter(r => r.machineId === machineId).map(({ harnessId, generation }) => ({ harnessId, generation })),- harnessIds: [...new Set([...state.agents.filter(a => a.machineId === machineId).map(a => a.harnessId), ...(state.harnessReservations ?? []).filter(r => r.machineId === machineId).map(r => r.harnessId), ...(state.starts ?? []).filter(s => s.request.machineId === machineId && s.harnessId).map(s => s.harnessId!)])] }]- })- })- }-/** What removing a machine would do, for its owner's confirmation (machines.ts removalPreview). */async machineRemoval(user: AuthUser, tabId: string, machineId: string) {return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId)const actor = await this.actor(tx, user, state)author(state, actor)return removalPreview(state, actor, machineId)@@ -1262,15 +1356,31 @@ export class SuperTabStore {/** The owner's Swarms with the Local models add-on: what the owner's computer creates on grid and keeps in step. */async hostGrids(user: AuthUser) {this.personOnly(user)- const rows = await this.db.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, ownerId: user.sub }, take: 100 })- return rows.flatMap(row => swarmGridRow(row.id, stateOf(row)) ?? [])+ const rows = await this.db.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, ownerId: user.sub, format: 2 }, take: 100 })+ return transaction(this.db, async tx => {+ const grids = []+ for (const row of rows) { const grid = swarmGridRow(row.id, (await loadRow(tx, row)).state); if (grid) grids.push(grid) }+ return grids+ })+ }++ /** When each Swarm's time checks last ran on a machine's report, on this server (liveness.ts SWEEP_EVERY_MS). */+ private readonly swept = new Map<string, number>()++ /** Whether a machine's report runs its Swarm's time checks now; decided once per report, not per transaction attempt. */+ private sweepDue(tabId: string, now: number): boolean {+ const last = this.swept.get(tabId)+ if (last !== undefined && now - last < SWEEP_EVERY_MS) return false+ this.swept.set(tabId, now)+ return true}async observeMachine(user: AuthUser, tabId: string, machineId: string, input: MachineObservation) {const observation = machineObservationSchema.parse(input)+ const sweep = this.sweepDue(tabId, this.now())return transaction(this.db, async tx => {await this.hostFor(tx, user, machineId)- const row = await this.row(tx, user, tabId), state = structuredClone(stateOf(row))+ const loaded = await this.load(tx, user, tabId), state = structuredClone(loaded.state)const pool = machineContribution(state, machineId)if (!pool || pool.contributorId !== user.sub || pool.generation !== observation.generation) fail('CONTRIBUTION_REVOKED', 'Read the current machine contribution.', 403)const owned = await tx.machine.findFirst({ where: { machineId, userId: user.sub, autonomousEnv: user.autonomousEnv, ...machineAlive } })@@ -1279,20 +1389,27 @@ export class SuperTabStore {// A machine that went silent while cleaning takes the fallback before this fresh reading can bring it back: its records// go, its cleanup waits for this host, as the next sweep would have done (machines.ts expireRemovals).expireRemovals(state, now)- if (!state.machines?.includes(pool)) {- await tx.superTab.update({ where: { id: tabId, revision: row.revision }, data: {- state: json(state), revision: row.revision + 1, ...indexes(state),- } })- return { revision: row.revision + 1 }+ const stamp = clock.next()+ // A reading writes only its machine's part, and an agent's part only when its presence changes (spec); a group's only+ // when a task there is lost.+ const saved = async (lost: MessageDraft[] = []) => {+ const sequences = numberMessages(state, lost, now)+ const touches = judgedMachines(state, lost).filter(t => t.key !== machineId)+ const version = (await this.save(tx, loaded, state, stamp, touches)).versions.get(`machine:${machineId}`) ?? 0+ await this.writeMessages(tx, tabId, state, lost, sequences)+ return { version }}+ if (!state.machines?.includes(pool)) return saved()recordAgentPresence(state, machineId, observation.runningHarnessIds, now)const team = isTeamSession(user)// Its privacy check counts only from the Harness Team account's own session; an ordinary sign-in's claim is dropped.- const { privacy: reported, ...reading } = observation+ // Progress is kept for running sessions only: their leases are read from it (liveness.ts).+ const { privacy: reported, harnessProgress, ...reading } = observation+ const progress = harnessProgress && Object.fromEntries(Object.entries(harnessProgress).filter(([id]) => observation.runningHarnessIds.includes(id)))const privacy = observedPrivacy(pool.observation?.privacy, reported, team, now)pool.observation = { ...reading, quotas: observation.quotas.filter(q => contributedEngines(pool, observation).includes(q.engine)), receivedAt: now,// How the machine is signed in, from the session that reported and never from the report (lib/teamSession.ts).- sessionKind: team ? 'team' : 'computer', ...(privacy ? { privacy } : {}) }+ sessionKind: team ? 'team' : 'computer', ...(privacy ? { privacy } : {}), ...(progress ? { harnessProgress: progress } : {}) }// Current-generation physical stop proof also finishes a close whose membership was already withdrawn.for (const proof of observation.stoppedReservations ?? []) {if (!observation.stoppedHarnessIds.includes(proof.harnessId)) continue@@ -1305,72 +1422,9 @@ export class SuperTabStore {await tx.superTabSessionScope.updateMany({ where: { id, closeLeaseGeneration: proof.generation },data: { closeLeaseId: null, closeLeaseUntil: null, closeLeaseGeneration: null } })}- await tx.superTab.update({ where: { id: tabId, revision: row.revision }, data: { state: json(state), revision: row.revision + 1 } })- return { revision: row.revision + 1 }- })- }-- async hostTabs(user: AuthUser, machineId: string) {- return transaction(this.db, async tx => {- await this.hostFor(tx, user, machineId)- const owned = await tx.machine.findFirst({ where: { machineId, userId: user.sub, autonomousEnv: user.autonomousEnv, ...machineAlive } })- if (!owned || !machineBillingAllowsDataPlane(owned)) fail('HOST_UNAVAILABLE', 'This execution host is unavailable.', 403)- const rows = await tx.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, machineIds: { has: machineId } }, ...HOST_TABS })- // A cleanup is never cut by that limit: a machine in more than 100 Swarms would otherwise keep a removed Swarm's folders.- const cleaning = await tx.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, cleanupMachineIds: { has: machineId },- id: { notIn: rows.map(r => r.id) } } })- // This Mac's Harness Team account, which joins wherever this Mac is added (machines.ts): asked of the owner's own daemon only.- const teams = isTeamSession(user) || this.hooks.teamAccountsIdle ? [] : await tx.machine.findMany({ where: { userId: user.sub, hostMachineId: machineId, sessionKind: 'team',- autonomousEnv: user.autonomousEnv, ...machineAlive }, select: { machineId: true } })- const result = []- for (const row of rows) {- const state = stateOf(row)- // Where its owner added this Mac and its team account is missing, this host adds that account, prepared by its own- // daemon (cli/src/superTabs/host.ts); the backend gives it the Mac's name, slots and pause (commands.ts).- const mac = state.machines?.find(m => m.machineId === machineId && m.contributorId === user.sub && m.scope === 'swarm' && !m.removal)- for (const team of mac ? teams : []) {- if (state.machines?.some(m => m.machineId === team.machineId) || state.machineCleanups?.some(c => c.machineId === team.machineId)) continue- result.push({ tabId: row.id, joinTeam: { machineId: team.machineId, name: mac!.name, maxAgents: mac!.maxAgents } })- }- const people = await tx.user.findMany({ where: { id: { in: state.people.map(p => p.id) }, autonomousEnv: state.environment }, select: { id: true, email: true } })- for (const target of state.agents.filter(a => a.machineId === machineId && a.machineOwnerId === user.sub)) {- try { agent(state, target.id); await this.agentGrant(tx, state, target) }- catch (error) { if (error instanceof SuperTabError) continue; throw error }- // `active` lets the host release members that are only in archived groups to automatic cleanup.- const active = state.conversations.some(c => !c.archived && c.agentIds.includes(target.id))- // The agent's own work waiting on a person, for this host's Harness Pro (cli/src/superTabs/attention.ts): the- // assignment it runs here that needs a decision or is stuck, and what it said. Nothing the agent cannot read itself.- const waiting = state.conversations.find(c => activeWork(c) && c.assignment!.agentId === target.id &&- c.assignment!.execution.machineId === machineId && ['needs_human', 'blocked'].includes(c.assignment!.status))?.assignment- const attention = waiting ? { assignmentId: waiting.id, status: waiting.status, result: waiting.result?.slice(0, 500) ?? null } : null- // The owner's own machine runs the owner's own Lead of this Swarm but is not one of its machines: the host adds it- // (cli/src/superTabs/host.ts). A collaborator's Lead on a machine shared with them must not open it to every member.- const joinSwarm = state.ownerId === user.sub && target.contributorId === user.sub && !state.machines?.some(m => m.machineId === machineId)- && state.conversations.some(c => !c.archived && c.leadId === target.id)- // Which skill texts this agent runs; the host reads it here rather than fetching each tab's state per poll. A row- // whose project is gone reads like one from before skill modes instead of failing the host's whole poll.- const home = projectsOf(state).find(p => p.id === agentProjectId(state, target))- const skillMode = home ? skillModeOf(home) : 'orchestration'- // On Custom, the role it runs and its text's version, never the text (roleText); null when its kind has no role there.- // The project lets the host fetch that text (roleText).- const custom = home && skillSetOf(home) === 'custom' ? home : null- const chosen = custom ? agentSetRole(state, custom, target) : null- const role = custom ? { role: chosen && { ...chosen, projectId: custom.id } } : {}- result.push({ tabId: row.id, tabName: state.name, revision: row.revision, paused: state.paused, active, attention, agent: target, joinSwarm, skillMode, ...role,- lead: !!ledProject(state, target.id),- stopRequested: target.workDecision === 'stop' && !state.conversations.some(c => activeWork(c) && c.assignment?.agentId === target.id),- observers: people.filter(p => p.id !== user.sub &&- canReadAgent(state, { kind: 'person', userId: p.id, email: p.email }, target))- .map(p => ({ email: p.email, userId: p.id })) })- }- // Not `active`, so a host from before close requests leaves the session to its automatic cleanup.- for (const { agentId: id, harnessId } of (state.closingSessions ?? []).filter(c => c.machineId === machineId && c.machineOwnerId === user.sub)) {- result.push({ tabId: row.id, agent: { id, harnessId, machineId }, closeSession: true as const, active: false })- }- result.push(...cleanupRows(row.id, state, machineId, user.sub))- }- for (const row of cleaning) result.push(...cleanupRows(row.id, stateOf(row), machineId, user.sub))- return result+ // Its own agents lose their tasks at once (a stopped session); every 30 seconds it runs the Swarm's time checks too, so+ // they keep running when the Lead's own machine is the one that died.+ return saved([...loseTasks(state, now, worker => worker.machineId === machineId), ...sweep ? sweepLiveness(state, now) : []])})}@@ -1379,32 +1433,28 @@ export class SuperTabStore {if (isTeamSession(user)) return falsetry {return await transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId)person(state, user.sub)const target = state.agents.find(a => a.machineId === machineId && a.harnessId === harnessId && a.machineOwnerId === machineOwnerId)if (!target) return falseagent(state, target.id)- if (!canReadAgent(state, { kind: 'person', userId: user.sub, email: user.email }, target)) return false+ if (!canWatchAgent(state, { kind: 'person', userId: user.sub, email: user.email }, target, await this.confidential(tx, target.id))) return falseawait this.agentGrant(tx, state, target)return true})} catch (error) { if (error instanceof SuperTabError) return false; throw error }}- /** Execution identity survives removing a contributor. The host sees only- * its outstanding native sessions, without regaining conversation access. */- async hostAssignments(user: AuthUser, machineId: string) {- return transaction(this.db, async tx => {- await this.hostFor(tx, user, machineId)- const owned = await tx.machine.findFirst({ where: { machineId, userId: user.sub, autonomousEnv: user.autonomousEnv, ...machineAlive } })- if (!owned || !machineBillingAllowsDataPlane(owned)) fail('HOST_UNAVAILABLE', 'This execution host is unavailable.', 403)- const rows = await tx.superTab.findMany({ where: { autonomousEnv: user.autonomousEnv, machineIds: { has: machineId } }, ...HOST_TABS })- return rows.flatMap(row => stateOf(row).conversations.filter(activeWork).flatMap(group => {- const work = group.assignment!- return work.execution.machineId === machineId && work.execution.machineOwnerId === user.sub- ? [{ tabId: row.id, assignmentId: work.id, harnessId: work.execution.harnessId }] : []- }))- })+ /** Whether an agent's session is confidential in any Swarm (confidential.ts). */+ private async confidential(tx: Transaction, agentId: string): Promise<boolean> {+ return (await confidentialSessions(tx, [agentId])).has(agentId)+ }++ /** Whether a terminal share may open, wherever it came from (routes/harnessShares.ts): a confidential session's only for+ * its machine's person, even an ordinary share made outside any Swarm; a Swarm's share only while that Swarm allows it. */+ async mayOpenShare(user: AuthUser, share: { superTabId: string | null; machineId: string; agentId: string; ownerId: string }): Promise<boolean> {+ if (user.sub !== share.ownerId && await transaction(this.db, tx => this.confidential(tx, stableId(share.machineId, share.agentId)))) return false+ return !share.superTabId || this.mayObserve(user, share.superTabId, share.machineId, share.agentId, share.ownerId)}private deliveryAllowed(state: SuperTabState, delivery: SuperTabDelivery): boolean {@@ -1417,9 +1467,10 @@ export class SuperTabStore {? { kind: 'person', userId: delivery.authorId, email: '' }: { kind: 'agent', agentId: delivery.authorId, machineOwnerId: (sender as Agent).machineOwnerId }// The Leads conversation belongs to no project: its members are the Leads, and an agent posts there only as a Lead.- if (isLeads(group) ? actor.kind === 'agent' && !ledProject(state, actor.agentId) : !canReadProject(state, actor, groupProject(state, group))) return false+ // A private conversation's sender and receiver must still be in its audience or be its Lead (projects.ts canReadGroup).+ if (isLeads(group) ? actor.kind === 'agent' && !ledProject(state, actor.agentId) : !canReadGroup(state, actor, group)) return falseif (!canReadAgent(state, { kind: 'agent', agentId: target.id, machineOwnerId: target.machineOwnerId }, target) || !isLeads(group) &&- !canReadProject(state, { kind: 'agent', agentId: target.id, machineOwnerId: target.machineOwnerId }, groupProject(state, group))) return false+ !canReadGroup(state, { kind: 'agent', agentId: target.id, machineOwnerId: target.machineOwnerId }, group)) return falseconst generation = 'generation' in sender ? sender.generation : sender.membershipGenerationreturn generation === delivery.authorGeneration && (!('role' in sender) || sender.role !== 'viewer')}@@ -1433,33 +1484,31 @@ export class SuperTabStore {async deliveries(user: AuthUser, tabId: string, agentId: string) {return transaction(this.db, async tx => {- const row = await this.row(tx, user, tabId)- const state = stateOf(row)+ const loaded = await this.load(tx, user, tabId), state = structuredClone(loaded.state)author(state, await this.actor(tx, user, state, agentId), true)const target = agent(state, agentId)+ // A Lead's poll runs the time checks (liveness.ts): lost work wakes it in this same poll.+ const written = ledProject(state, agentId) ? sweepLiveness(state, this.now()) : []const update = projectUpdateRequest(state, target, this.now())+ let woken = falseif (update) {- const project = groupProject(state, conversation(state, update.conversationId))- // A worker down two hours asks for a wake-up even when no report has come in yet.- const progress = project.progress ??= { dirtyRevision: 0, summarizedRevision: 0, requestedRevision: 0, since: this.now() }+ const progress = groupProject(state, conversation(state, update.conversationId)).progress!const pending = progress.requestMessageId? await tx.superTabDelivery.findFirst({ where: { tabId, agentId, messageId: progress.requestMessageId,status: { in: ['queued', 'claimed', 'uncertain', 'delivered'] } } }): nullif (!pending) {- if (update.source!.throughRevision === progress.dirtyRevision) {- progress.requestedRevision = progress.dirtyRevision- progress.requestedAt = this.now()- }+ progress.requested = { ...progress.requested, ...update.source!.through as Record<string, number> }+ progress.requestedAt = this.now()progress.requestMessageId = update.id- for (const { agentId, since } of (update.source!.down ?? []) as Array<{ agentId: string; since: string }>) {- state.agents.find(a => a.id === agentId)!.downNamed = since- }- const revision = row.revision + 1- await this.writeMessages(tx, tabId, state, [update], revision)- await tx.superTab.update({ where: { id: tabId, revision: row.revision }, data: { revision, state: json(state) } })+ written.push(update)+ woken = true}}+ // One write for both: the time checks' changes and the wake-up's.+ const sequences = numberMessages(state, written, this.now())+ await this.save(tx, loaded, state, clock.next(), [...judgedMachines(state, written), ...woken ? [{ kind: 'agent' as const, key: agentId }] : []])+ await this.writeMessages(tx, tabId, state, written, sequences)const rows = await tx.superTabDelivery.findMany({ where: { tabId, agentId, status: { in: ['queued', 'claimed', 'uncertain'] } },orderBy: { createdAt: 'asc' }, take: 100 })const allowed: SuperTabDelivery[] = []@@ -1474,7 +1523,7 @@ export class SuperTabStore {* conversation access. Machine ownership is captured when input is created. */async deliveryReceipt(user: AuthUser, tabId: string, agentId: string, deliveryId: string) {return transaction(this.db, async tx => {- const state = stateOf(await this.row(tx, user, tabId))+ const { state } = await this.load(tx, user, tabId)const row = await tx.superTabDelivery.findFirst({ where: { id: deliveryId, tabId, agentId } })if (!row) fail('NOT_FOUND', 'This delivery is unavailable.', 404)const previous = state.agents.find(a => a.id === agentId && a.membershipGeneration === row.membershipGeneration)@@ -1493,8 +1542,8 @@ export class SuperTabStore {action: { type: 'claim'; claimId: string } | { type: 'ack'; claimId: string; receipt: string; uncertain: boolean }| { type: 'hold'; claimId: string; reason: HoldReason }) {return transaction(this.db, async tx => {- const row = await this.row(tx, user, tabId)- const state = stateOf(row)+ const named = await tx.superTabDelivery.findFirst({ where: { id: deliveryId, tabId, agentId }, select: { conversationId: true } })+ const loaded = await this.load(tx, user, tabId, { groupIds: named ? [named.conversationId] : [] }), state = loaded.stateauthor(state, await this.actor(tx, user, state, agentId), true)const delivery = await tx.superTabDelivery.findFirst({ where: { id: deliveryId, tabId, agentId } })if (!delivery || !this.deliveryAllowed(state, delivery) || delivery.status === 'cancelled' ||@@ -1505,13 +1554,14 @@ export class SuperTabStore {}if (delivery.claimId && delivery.claimId !== action.claimId) fail('CLAIM_CONFLICT', 'Reconcile the existing delivery before claiming it again.')if (action.type !== 'claim' && !delivery.claimId) fail('NOT_CLAIMED', 'Claim this instruction before acknowledging it.')- if (action.type === 'hold') return this.holdNotice(tx, row, state, delivery, action.reason)+ if (action.type === 'hold') return this.holdNotice(tx, loaded, delivery, action.reason)const status = action.type === 'claim' ? delivery.status === 'queued' ? 'claimed' : delivery.status : action.uncertain ? 'uncertain' : 'delivered'if (delivery.status === 'delivered' && action.type === 'ack' && (action.uncertain || delivery.receipt !== action.receipt)) {fail('RECEIPT_CONFLICT', 'A delivered instruction keeps its original host receipt.')}- // This write conflicts with concurrent revocation, even when only the delivery record changed.- await tx.superTab.update({ where: { id: tabId, revision: row.revision }, data: { revision: { increment: 1 } } })+ // No Swarm-wide write: revocation and group changes write this delivery row, and the claim relies on its receiver and+ // its sender, whose parts it touches (spec ruling 9, design section 3.5).+ await this.save(tx, loaded, state, clock.next(), deliveryTouches(delivery))const updated = await tx.superTabDelivery.update({ where: { id: delivery.id }, data: { status, claimId: action.claimId,...(action.type === 'ack' ? { receipt: action.receipt, holdReason: null, holdSince: null,...(!action.uncertain ? { deliveredAt: delivery.deliveredAt ?? new Date(this.now()) } : {}) } : {}) } })@@ -1521,7 +1571,8 @@ export class SuperTabStore {}/** The host cannot type a claimed instruction yet. Say so once in the group, as the waiting agent; nobody is asked to act on it. */- private async holdNotice(tx: Transaction, row: SuperTab, state: SuperTabState, delivery: SuperTabDelivery, reason: HoldReason) {+ private async holdNotice(tx: Transaction, loaded: Loaded, delivery: SuperTabDelivery, reason: HoldReason) {+ const state = structuredClone(loaded.state)const id = stableId('hold-notice', delivery.tabId, delivery.id)if (delivery.status !== 'claimed') return { noticed: false }// Nobody can see an agent-only notice, so nobody is told it waits; the host keeps holding it.@@ -1534,15 +1585,15 @@ export class SuperTabStore {} })const group = conversation(state, delivery.conversationId), waiting = agent(state, delivery.agentId)const sender = author(state, { kind: 'agent', agentId: waiting.id, machineOwnerId: waiting.machineOwnerId })- const revision = row.revision + 1- if (!notice) group.lastMessageSequence = revision// The Lead gets it too, like a host-stop notice; a waiting Lead has no one above it to tell.const lead = group.leadId && group.leadId !== waiting.id && group.agentIds.includes(group.leadId) ? group.leadId : nullconst host = !notice && reason === 'team_waiting_user' ? await this.holdHost(tx, state, waiting) : undefined- await tx.superTab.update({ where: { id: row.id, revision: row.revision }, data: { revision, state: json(state) } })- if (!notice) await this.writeMessages(tx, row.id, state, [{ id, conversationId: group.id, replyTo: null, recipients: lead ? [lead] : [],+ const notices: MessageDraft[] = notice ? [] : [{ id, conversationId: group.id, replyTo: null, recipients: lead ? [lead] : [],source: { kind: 'delivery-hold', messageId: delivery.messageId, deliveryId: delivery.id, agentId: delivery.agentId },- text: holdNoticeText(sender.displayName ?? sender.name, reason, host), author: sender }], revision)+ text: holdNoticeText(sender.displayName ?? sender.name, reason, host), author: sender }]+ const sequences = numberMessages(state, notices, this.now())+ await this.save(tx, loaded, state, clock.next(), deliveryTouches(delivery))+ await this.writeMessages(tx, loaded.row.id, state, notices, sequences)return { noticed: !notice }}@@ -1560,8 +1611,7 @@ export class SuperTabStore {let ended: WorkHold[] = []const done = await transaction(this.db, async tx => {ended = []- const row = await this.row(tx, user, tabId)- const state = stateOf(row)+ const loaded = await this.load(tx, user, tabId), state = structuredClone(loaded.state)const before = { agents: state.agents, conversations: structuredClone(state.conversations) }const group = state.conversations.find(c => c.assignment?.id === assignmentId)const assignment = group?.assignment@@ -1573,7 +1623,6 @@ export class SuperTabStore {const id = stableId('stop', tabId, assignmentId)const prior = await tx.superTabStopReceipt.findUnique({ where: { id } })if (prior && prior.receipt !== receipt) fail('RECEIPT_CONFLICT', 'This stop already has a host receipt.')- const revision = row.revision + 1const notices: MessageDraft[] = []if (group && activeWork(group)) {assignment.status = 'stopped'@@ -1594,13 +1643,13 @@ export class SuperTabStore {notices.push({ id: stableId('stop-notice', tabId, assignmentId), conversationId: group.id,author: author(state, { kind: 'agent', agentId: worker.id, machineOwnerId: worker.machineOwnerId }),text: `Stopped\n\n${assignment.result} If this work should continue, assign a new attempt.`, replyTo: null, recipients: lead ? [lead] : [] })- group.lastMessageSequence = revision}}- await tx.superTab.update({ where: { id: tabId, revision: row.revision }, data: {- revision, state: json(state), ...indexes(state),- } })- await this.writeMessages(tx, tabId, state, notices, revision)+ const sequences = numberMessages(state, notices, this.now())+ // A confirmed stop finishes its worker, as work.status stopped does (design ruling R5).+ const project = group ? groupProject(state, group).id : undefined+ await this.save(tx, loaded, state, clock.next(), project && state.projects ? [{ kind: 'progress', key: project }] : [])+ await this.writeMessages(tx, tabId, state, notices, sequences)if (!prior) await tx.superTabStopReceipt.create({ data: { id, tabId, assignmentId, ...execution, receipt } })ended = endedHolds(before, state)return { confirmed: true }diff --git a/backend/src/superTabs/sweeps.ts b/backend/src/superTabs/sweeps.tsnew file mode 100644index 000000000..24609ba52--- /dev/null+++ b/backend/src/superTabs/sweeps.ts@@ -0,0 +1,128 @@+import type { Prisma, PrismaClient } from '@prisma/client'+import type { AgentStart, Conversation } from './model.js'+import { clock, guardedWrite, PartConflict, type HeadData, type ProgressData } from './parts/index.js'+import { DORMANT_AFTER_MS, RETENTION_MS } from './parts/types.js'+import { logger } from '../utils/logger.js'++/** Parts whose key is never used twice (conversations, starts, projects' progress) lose their tombstone at `purgeAt`.+ * A person, agent or machine can come back under the same key, so its tombstone is kept for good, compacted to its+ * version (`compactTombstones`): versions never reset (spec ruling 6, review round 1). Run by the singleton worker at+ * startup, like the terminal and mention expiry indexes. */+export async function ensurePartExpiry(db: PrismaClient): Promise<void> {+ for (const collection of ['SwarmHead', 'SwarmGroup', 'SwarmStart', 'SwarmProgress']) {+ await db.$runCommandRaw({ createIndexes: collection, indexes: [{ key: { purgeAt: 1 }, name: 'part_purge', expireAfterSeconds: 0 }] })+ }+}++/** 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> {+ 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+ }+ return compacted+}++const BATCH = 500++/** One guarded write in its own transaction. A part that changed since it was read is left for the next sweep. */+async function guarded(db: PrismaClient, write: Parameters<typeof guardedWrite>[2] & { tabId: string }): Promise<boolean> {+ try {+ await db.$transaction(tx => guardedWrite(tx, write.tabId, write, clock.next()))+ return true+ } catch (error) {+ if (error instanceof PartConflict) return false+ throw error+ }+}++/**+ * A conversation leaves the active set (spec, Archive) when its work is done or cancelled and it has had no message for a+ * day, or when it was archived by hand, and in both cases only once its Lead acknowledged its reports: a dormant+ * conversation is never read by ordinary loads, so it must owe its project nothing (design section 3.6). A project's+ * Lead conversation and the Leads conversation never sleep; a message wakes any of them. Candidates are read oldest+ * first with a cursor, so rejected ones never hold later ones back.+ */+async function sleepQuietGroups(db: PrismaClient, now: number): Promise<number> {+ const base = { deleted: false, dormant: false, kind: null, OR: [{ lastActivityAt: { lt: new Date(now - DORMANT_AFTER_MS) } }, { archived: true }] }+ const leads = new Map<string, Set<string>>(), progress = new Map<string, ProgressData | null>()+ const leadsOf = async (tabId: string) => {+ if (!leads.has(tabId)) {+ const head = await db.swarmHead.findUnique({ where: { id: `${tabId}:head` } })+ const projects = (head?.data as unknown as HeadData | undefined)?.projects+ leads.set(tabId, new Set(projects ? projects.map(p => p.leadConversationId) : ['lead']))+ }+ return leads.get(tabId)!+ }+ const progressOf = async (tabId: string, projectId: string) => {+ const id = `${tabId}:${projectId}`+ if (!progress.has(id)) progress.set(id, ((await db.swarmProgress.findUnique({ where: { id } }))?.data as unknown as ProgressData | undefined) ?? null)+ return progress.get(id)!+ }+ let slept = 0, after: { at: Date; id: string } | null = null+ for (;;) {+ const cursor: Prisma.SwarmGroupWhereInput = after ? { AND: [{ OR: [{ lastActivityAt: { gt: after.at } }, { lastActivityAt: after.at, id: { gt: after.id } }] }] } : {}+ const rows: Array<{ id: string; tabId: string; key: string; version: number; lastActivityAt: Date; data: Prisma.JsonValue }> = await db.swarmGroup.findMany({ where: { ...base, ...cursor }, orderBy: [{ lastActivityAt: 'asc' }, { id: 'asc' }], take: BATCH })+ for (const row of rows) {+ const group = row.data as unknown as Conversation+ const quiet = row.lastActivityAt.getTime() < now - DORMANT_AFTER_MS && ['done', 'cancelled'].includes(group.assignment?.status ?? '')+ if (!group.archived && !quiet) continue+ if ((await leadsOf(row.tabId)).has(group.id)) continue+ const reports = group.audience ? null : await progressOf(row.tabId, group.projectId ?? 'lead')+ if (reports && (group.reportSeq ?? 0) > (reports.summarized[group.id] ?? reports.summarizedFloor)) continue+ if (await guarded(db, { tabId: row.tabId, op: 'update', kind: 'group', key: row.key, seen: row.version, data: { ...group, dormant: true } })) slept+++ }+ if (rows.length < BATCH) return slept+ after = { at: rows.at(-1)!.lastActivityAt, id: rows.at(-1)!.id }+ }+}++/** 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> {+ const rows = await db.swarmStart.findMany({ where: { deleted: false, finishedAt: { lt: new Date(now - RETENTION_MS) } }, take: BATCH })+ let expired = 0+ for (const row of rows) {+ if (await guarded(db, { tabId: row.tabId, op: 'remove', kind: 'start', key: row.key, seen: 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 } })+ let expired = 0+ for (const head of heads) {+ const data = head.data as unknown as HeadData+ const kept = data.invitations.filter(i => i.expiresAt > now)+ if (kept.length === data.invitations.length) continue+ try {+ await db.$transaction(async tx => {+ await guardedWrite(tx, head.tabId, { op: 'update', kind: 'head', key: 'head', seen: head.version, data: { ...data, invitations: kept },+ head: { groupCounter: head.groupCounter, visibilityEpoch: head.visibilityEpoch, sequenceBase: head.sequenceBase } }, clock.next())+ const row = await tx.superTab.findUniqueOrThrow({ where: { id: head.tabId } })+ const updated = await tx.superTab.updateMany({ where: { id: head.tabId, revision: row.revision },+ data: { revision: row.revision + 1, invitedEmails: kept.map(i => i.email) } })+ if (!updated.count) throw new PartConflict('head', 'index')+ })+ expired += data.invitations.length - kept.length+ } catch (error) { if (!(error instanceof PartConflict)) throw error }+ }+ return expired+}++/** One pass of every sweep (spec, Archive). Each part it changes is a guarded write, so a command in between wins. */+export async function sweepSwarms(db: PrismaClient, now = Date.now()) {+ return { slept: await sleepQuietGroups(db, now), startsExpired: await expireStarts(db, now), invitationsExpired: await expireInvitations(db, now),+ tombstonesCompacted: await compactTombstones(db, now) }+}++/** Runs the sweeps every hour in the singleton worker. */+export function startSwarmSweeps(db: PrismaClient, everyMs = 3_600_000): () => void {+ const run = () => void sweepSwarms(db).then(result => logger.info('[swarm-sweeps] done', result))+ .catch(error => logger.warn('[swarm-sweeps] failed', { error: error instanceof Error ? error.message : String(error) }))+ run()+ const timer = setInterval(run, everyMs)+ timer.unref()+ return () => clearInterval(timer)+}diff --git a/backend/src/superTabs/teamRouting.test.ts b/backend/src/superTabs/teamRouting.test.tsindex 90063e326..7f3246f36 100644--- a/backend/src/superTabs/teamRouting.test.ts+++ b/backend/src/superTabs/teamRouting.test.ts@@ -533,7 +533,7 @@ describe('one machine: the Mac\'s agent slots', () => {describe('one machine: a Mac whose Harness Team account was made again', () => {// `harness team remove`, then `harness team setup`: a new account, computer and machine, while the old team machine's- // pool is still in the Swarm, silent. The Mac joins with the new one too (store.ts hostTabs).+ // pool is still in the Swarm, silent. The Mac joins with the new one too (read/hostRows.ts).function remade() {const f = swarm()Object.assign(f.machine('mate-team'), { hostMachineId: 'mate-mac', name: 'MacBook Pro', cwd: '/old-team', observation: reading('team', PASSED, NOW - 3_600_000) })diff --git a/backend/src/superTabs/terminal.test.ts b/backend/src/superTabs/terminal.test.tsindex 69df8f63e..80b7f274a 100644--- a/backend/src/superTabs/terminal.test.ts+++ b/backend/src/superTabs/terminal.test.ts@@ -84,8 +84,13 @@ describe('reading and typing in an agent terminal', () => {it('logs input to the Lead in the project\'s Lead conversation', () => {const s = swarm()- expect(s.run({ type: 'agent.input', agentId: s.lead, keys: ['Esc', '2'] }).messages[0])- .toMatchObject({ conversationId: 'lead', text: `owner typed Esc + 2 in ${name(s, s.lead)}'s terminal` })+ // Only the person whose machine runs the Lead may type in it (final review, Critical 1).+ const machineOwner: Actor = { kind: 'person', userId: 'host-owner', email: '[email protected]' }+ const invited = s.run({ type: 'invite.create', email: '[email protected]', role: 'collaborator', conversationId: 'lead' })+ s.run({ type: 'invite.accept', inviteId: invited.result.inviteId as string }, machineOwner)+ expect(s.run({ type: 'agent.input', agentId: s.lead, keys: ['Esc', '2'] }, machineOwner).messages[0])+ .toMatchObject({ conversationId: 'lead', text: `host typed Esc + 2 in ${name(s, s.lead)}'s terminal` })+ expect(() => s.run({ type: 'agent.input', agentId: s.lead, keys: ['Esc'] })).toThrow('Only the person whose machine runs this agent')})it('accepts only printable text and named keys, and needs one of them', () => {diff --git a/backend/src/superTabs/terminal.ts b/backend/src/superTabs/terminal.tsindex 860c7f733..4c648360c 100644--- a/backend/src/superTabs/terminal.ts+++ b/backend/src/superTabs/terminal.ts@@ -2,7 +2,7 @@ import type { PrismaClient } from '@prisma/client'import { activeWork, actorKey, agent, author, conversation, fail, isLeads, stableId, type Actor, type Agent, type Author, type Conversation, type MessageDraft,type SuperTabState } from './model.js'import { downSince } from './machines.js'-import { agentProjectId, projectOf, readAgent } from './projects.js'+import { agentProjectId, isConfidential, ownSession, projectOf, readAgent } from './projects.js'import { redactCredentials } from './credentials.js'/** The Lead reads and types in an agent's terminal through the host of the agent's machine (spec/2026-10-23-lead-sees-agent-terminal.md).@@ -30,12 +30,20 @@ export type TerminalEffect =export interface TerminalRequest { id: string; agentId: string; harnessId: string; kind: TerminalKind; status: 'pending' | 'claimed' | 'done' }/** Only the Lead of the agent's project, or a person with write access who can see the agent, reads or types in its terminal. */-export function mayDrive(state: SuperTabState, actor: Actor, target: Agent): void {+/** `elsewhere`: the agent's session is confidential in another Swarm (confidential.ts). */+export function mayDrive(state: SuperTabState, actor: Actor, target: Agent, elsewhere = false): void {+ // For both kinds of requester: no person or agent reads a confidential session but its own (final review, Critical 1).+ const closed = () => {+ if (isConfidential(state, target, elsewhere) && !ownSession(actor, target)) {+ fail('TERMINAL_PRIVATE', 'Only the person whose machine runs this agent can read or type in its terminal: it holds people’s private chats with the Product Manager.', 403)+ }+ }if (actor.kind === 'person') {author(state, actor, true)readAgent(state, actor, target.id)- return+ return closed()}+ closed()if (conversation(state, projectOf(state, agentProjectId(state, target)).leadConversationId).leadId !== actor.agentId) {fail('LEAD_REQUIRED', 'Only the Lead of this agent’s project, or a person with write access, can read or type in its terminal.', 403)}@@ -45,16 +53,16 @@ export function mayDrive(state: SuperTabState, actor: Actor, target: Agent): voi* Swarm-wide Leads conversation), else its project's Lead chat. */export function currentGroup(state: SuperTabState, target: Agent): Conversation {return state.conversations.find(c => activeWork(c) && c.assignment!.agentId === target.id)- ?? state.conversations.findLast(c => !c.archived && !isLeads(c) && c.agentIds.includes(target.id) && c.leadId !== target.id)+ ?? state.conversations.findLast(c => !c.archived && !isLeads(c) && !c.audience && c.agentIds.includes(target.id) && c.leadId !== target.id)?? conversation(state, projectOf(state, agentProjectId(state, target)).leadConversationId)}const nameOf = (target: Agent) => target.displayName ?? target.nameexport function terminalRequest(state: SuperTabState, actor: Actor, sender: Author, id: string, now: number,- command: { type: 'agent.screen' | 'agent.input'; agentId: string; scrollback?: number; text?: string; keys?: string[] }) {+ command: { type: 'agent.screen' | 'agent.input'; agentId: string; scrollback?: number; text?: string; keys?: string[] }, elsewhere = false) {const target = agent(state, command.agentId)- mayDrive(state, actor, target)+ mayDrive(state, actor, target, elsewhere)if (downSince(state, target, now)) fail('HOST_OFFLINE', `${nameOf(target)}’s terminal is not running or its machine is offline.`)const { type: _type, agentId: _agentId, ...detail } = commandconst effect: TerminalEffect = { op: 'request', id, kind: command.type === 'agent.screen' ? 'screen' : 'input', agentId: target.id,@@ -98,8 +106,6 @@ export function terminalAlert(state: SuperTabState, actor: Actor, sender: Authorif (alerting.includes(command.alert)) return []target.alerting = [...alerting, command.alert]const group = currentGroup(state, target)- const chat = conversation(state, projectOf(state, agentProjectId(state, target)).leadConversationId)- const lead = chat.leadId && chat.leadId !== target.id ? chat.leadId : nulllet text = `${nameOf(target)} is waiting at a prompt in its terminal.`const source: Record<string, unknown> = { kind: 'terminal-alert', agentId: target.id, alert: command.alert }if (command.alert === 'limit') {@@ -110,7 +116,21 @@ export function terminalAlert(state: SuperTabState, actor: Actor, sender: Author// Its engine has been retrying its model for 10 minutes (2026-10-24: a Builder on a small local model retried for an// hour while its Lead waited on it).if (command.alert === 'model') text = `${nameOf(target)} can't get answers from its model: its requests keep failing. Stop it, or give the work to another model.`- const here = !!lead && group.agentIds.includes(lead)- const row = { id, conversationId: group.id, author: sender, replyTo: null, recipients: here ? [lead] : [], text, source }- return here || !lead || !chat.agentIds.includes(lead) ? [row] : [row, { ...row, id: stableId(id, 'lead'), conversationId: chat.id, recipients: [lead] }]+ return toLead(state, target, { id, conversationId: group.id, author: sender, replyTo: null, recipients: [], text, source })+}++/** The project Lead of an agent, unless the agent is that Lead. */+export function leadOf(state: SuperTabState, target: Agent): Agent | undefined {+ const lead = conversation(state, projectOf(state, agentProjectId(state, target)).leadConversationId).leadId+ return lead && lead !== target.id ? state.agents.find(a => a.id === lead) : undefined+}++/** A row about an agent, delivered to its project Lead: in the row's group when the Lead is there, else by a second row in+ * the Lead's chat. */+export function toLead(state: SuperTabState, target: Agent, row: MessageDraft): MessageDraft[] {+ const chat = conversation(state, projectOf(state, agentProjectId(state, target)).leadConversationId)+ const lead = leadOf(state, target)?.id+ const here = !!lead && conversation(state, row.conversationId).agentIds.includes(lead)+ const first = { ...row, recipients: here ? [lead] : [] }+ return here || !lead || !chat.agentIds.includes(lead) ? [first] : [first, { ...first, id: stableId(row.id, 'lead'), conversationId: chat.id, recipients: [lead] }]}diff --git a/backend/src/worker.ts b/backend/src/worker.tsindex f27bcb9a7..7e5d5aab3 100644--- a/backend/src/worker.ts+++ b/backend/src/worker.ts@@ -17,6 +17,7 @@ import { prisma } from './lib/prisma.js'import { ensureProductUsageExpiry } from './lib/productUsage.js'import { ensureTerminalExpiry } from './superTabs/terminal.js'import { ensureMentionExpiry } from './superTabs/mentions.js'+import { ensurePartExpiry, startSwarmSweeps } from './superTabs/sweeps.js'import { machineBillingWorkerService } from './services/MachineBillingWorkerService.js'import { productUsagePeopleRollupService } from './services/ProductUsagePeopleRollupService.js'import { logger } from './utils/logger.js'@@ -34,6 +35,7 @@ async function start(): Promise<void> {await ensureProductUsageExpiry()await ensureTerminalExpiry(prisma)await ensureMentionExpiry(prisma)+ await ensurePartExpiry(prisma)// AFTER the push: it creates the new collections + their unique indexes, and the copy uses $merge// so those indexes survive. Copying first would leave the unique index build to fail silently.await migrateMachineRename()@@ -46,12 +48,14 @@ async function start(): Promise<void> {await backfillMachinePresenceTurnsStarted()await reconcileCommunityLikeCounts()+ let stopSweeps = (): void => {}const shutdown = (signal: string): void => {logger.info(`Received ${signal}, stopping backend worker...`)const hardExit = setTimeout(() => process.exit(0), 5000)hardExit.unref()machineBillingWorkerService.stop()productUsagePeopleRollupService.stop()+ stopSweeps()void Promise.allSettled([prisma.$disconnect(), closeBus()]).finally(() => process.exit(0))}process.on('SIGINT', () => shutdown('SIGINT'))@@ -59,6 +63,7 @@ async function start(): Promise<void> {machineBillingWorkerService.start()productUsagePeopleRollupService.start()+ stopSweeps = startSwarmSweeps(prisma)// PM2 wait_ready gates the singleton worker's "online" state on schema/catalog/backfill startup.// Plain node/tsx runs do not provide process.send and simply continue.process.send?.('ready')diff --git a/backend/vitest.super-tabs.config.ts b/backend/vitest.super-tabs.config.tsindex bf4df8341..e2da28ad8 100644--- a/backend/vitest.super-tabs.config.ts+++ b/backend/vitest.super-tabs.config.ts@@ -1,4 +1,5 @@import { defineConfig } from 'vitest/config'-export default defineConfig({ test: { include: ['integration/superTabs.test.ts', 'integration/superTabSharing.test.ts', 'integration/superTabGithub.test.ts', 'integration/superTabTeam.test.ts'], hookTimeout: 120000, testTimeout: 30000,+export default defineConfig({ test: { include: ['integration/superTabs.test.ts', 'integration/superTabSharing.test.ts', 'integration/superTabGithub.test.ts', 'integration/superTabTeam.test.ts',+ 'integration/superTabRead.test.ts', 'integration/superTabMigration.test.ts', 'integration/superTabLiveness.test.ts'], hookTimeout: 120000, testTimeout: 30000,fileParallelism: false, env: { NODE_ENV: 'test', HARNESS_CREDENTIAL_ENCRYPTION_KEY: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' } } })diff --git a/cli/e2e/agentClient.e2e.ts b/cli/e2e/agentClient.e2e.tsindex e0e728220..22c5cba58 100644--- a/cli/e2e/agentClient.e2e.ts+++ b/cli/e2e/agentClient.e2e.ts@@ -19,6 +19,7 @@ import { LocalClient } from './harness/client.js'import { CLI_ROOT, IsolatedDaemon, until } from './harness/daemon.js'import { FakeBackend, type FakeMachine } from './harness/fakeBackend.js'import { retainedHarnesses } from '../src/superTabs/retention.js'+import { overOldRoutes } from './harness/swarmReads.js'const HARNESS_INSTRUCTIONS = 'You are running in Harness, and the person can watch you. You can hand work to other agents (Claude Code, Codex) that run in their own harnesses: `harness new`, `harness wait`, `harness show`, `harness close` (see `harness --help`). Start one only for work that can run in parallel, needs another model, or takes long; do quick work yourself, and close each one once you have its answer. Only use or close harnesses you started.'const ME: FakeMachine = { machineId: 'b8'.repeat(16), computerId: 'e2e-computer-0000-0000-0000000000b8', name: 'studio', token: 'e2e-token-agent-client' }@@ -250,12 +251,12 @@ describe('Harness for agents, end to end', () => {const joined = await start(second, 'joined')const left = await start(second, 'left')const shared = await start(second, 'shared')- relay.superTabs = async (_method, raw) => {+ relay.superTabs = overOldRoutes(async (_method, raw) => {const path = new URL(raw, relay.httpUrl).pathnamereturn { data: path === `/api/super-tabs/hosts/${ME.machineId}`? [{ tabId: 'retained-team', agent: { id: 'shared-member', harnessId: shared.id, machineId: ME.machineId }, observers: [] }]: [] }- }+ })expect(await client.request('super_tabs', { action: 'wake' })).toMatchObject({ ok: true })await until('the team host to retain its member', () => retainedHarnesses(d.dataDir).has(shared.id) || null, 10_000, 100)client.send('message', { agentId: joined.id, content: 'hello from the person' })diff --git a/cli/e2e/harness/swarmReads.ts b/cli/e2e/harness/swarmReads.tsnew file mode 100644index 000000000..f8218ffaf--- /dev/null+++ b/cli/e2e/harness/swarmReads.ts@@ -0,0 +1,56 @@+/**+ * The Swarm read API (docs/design/2026-10-26-swarm-state-parts.md section 4) over a Super Tab fixture that answers the old+ * routes: `GET /hosts/:m`, `/hosts/:m/pools`, `/hosts/:m/assignments`, `GET /:tab` and `GET /api/super-tabs`. The scenarios+ * keep their fixtures and what they check; only how the daemon reaches them changes (#1726). Every changes read asks for a+ * reload, so each read is a first load of the state the fixture holds now (it keeps no history to send tombstones from), and+ * every host form is full, as the old roster was.+ */+import { partsOf } from '../../src/superTabs/fixtures/read/index.js'+import type { FakeBackend } from './fakeBackend.js'++type Handler = NonNullable<FakeBackend['superTabs']>+type Json = Record<string, any>+const rows = (answer: { data?: unknown }) => Array.isArray(answer.data) ? answer.data as Json[] : []++export function overOldRoutes(handler: Handler): Handler {+ return async (method, raw, body, machine) => {+ const url = new URL(raw, 'http://fixture'), path = url.pathname, query = url.search+ const old = (route: string) => handler('GET', route, {}, machine)+ const host = /^\/api\/super-tabs\/hosts\/([^/]+)\/changes$/.exec(path)+ if (method === 'GET' && host) {+ const roster = await old(`/api/super-tabs/hosts/${host[1]}`)+ if (roster.error) return roster+ // A scenario that never served pools or assignments had them fail, which the daemon's readers took as none.+ const none = () => ({ data: [] })+ const [pools, assignments] = await Promise.all([old(`/api/super-tabs/hosts/${host[1]}/pools`).catch(none), old(`/api/super-tabs/hosts/${host[1]}/assignments`).catch(none)])+ const all = [...rows(roster), ...rows(pools), ...rows(assignments)]+ const tabs = [...new Set(all.map(row => String(row.tabId)))].map(tabId => ({ tabId, lastChangedAt: 1,+ roster: rows(roster).filter(row => row.tabId === tabId), pool: rows(pools).find(row => row.tabId === tabId) ?? null,+ assignments: rows(assignments).filter(row => row.tabId === tabId) }))+ return { data: { format: 2, full: true, cursor: 'fixture-host', tabs, removedTabIds: [] } }+ }+ if (method === 'GET' && path === '/api/super-tabs/list') {+ const list = await old(`/api/super-tabs${query}`)+ if (list.error) return list+ const page = (list.data ?? {}) as Json+ return { data: { tabs: (Array.isArray(page.tabs) ? page.tabs : []).map((tab: Json) => ({ ...tab, lastChangedAt: tab.revision ?? null })), next: page.next ?? null } }+ }+ const tab = /^\/api\/super-tabs\/([^/]+)\/(parts|changes)$/.exec(path)+ if (method === 'GET' && tab && tab[1] !== 'hosts') {+ if (tab[2] === 'changes') return { data: { reload: true } }+ const as = url.searchParams.get('asAgentId')+ const whole = await old(`/api/super-tabs/${tab[1]}${as ? `?asAgentId=${as}` : ''}`)+ if (whole.error) return whole+ const answer = (whole.data ?? {}) as Json+ return { data: partsOf({ id: tab[1], ...(answer.state ?? {}) }, { githubApp: answer.githubApp === true, lastChangedAt: answer.revision }) }+ }+ const group = /^\/api\/super-tabs\/([^/]+)\/groups\/([^/]+)$/.exec(path)+ if (method === 'GET' && group) {+ const whole = await old(`/api/super-tabs/${group[1]}${query}`)+ if (whole.error) return whole+ const found = ((whole.data as Json)?.state?.conversations ?? []).find((c: Json) => c.id === group[2])+ return found ? { data: { group: { key: group[2], version: 1, changedAt: 1, data: found } } } : { status: 404, error: { code: 'NOT_FOUND', message: 'No such group.' } }+ }+ return handler(method, raw, body, machine)+ }+}diff --git a/cli/e2e/superTabMachines.e2e.ts b/cli/e2e/superTabMachines.e2e.tsindex 2d3bc8d1e..be3be306c 100644--- a/cli/e2e/superTabMachines.e2e.ts+++ b/cli/e2e/superTabMachines.e2e.ts@@ -9,6 +9,7 @@ import { LocalClient } from './harness/client.js'import { CLI_ROOT, until, type IsolatedDaemon } from './harness/daemon.js'import { FakeBackend } from './harness/fakeBackend.js'import { signedInDaemon } from './harness/fleet.js'+import { overOldRoutes } from './harness/swarmReads.js'let relay: FakeBackend | undefinedconst daemons: IsolatedDaemon[] = [], clients: LocalClient[] = []@@ -40,7 +41,7 @@ it.each(['project', 'swarm'])('queues a teammate start with %s capacity and resuconst projects = scope === 'swarm' ? [{ id: 'lead', conversationIds: ['lead'],repository: { machineId: memberMachine.machineId, cwd: project, repositoryUrl: null } }] : undefinedconst id = (machine: string, harness: string) => createHash('sha256').update(JSON.stringify([machine, harness])).digest('hex').slice(0, 24)- backend.superTabs = async (method, raw, body, caller) => {+ backend.superTabs = overOldRoutes(async (method, raw, body, caller) => {const path = new URL(raw, backend.httpUrl).pathnameif (path.endsWith('/pools')) {expect(path.split('/')[4]).toBe(caller.machineId)@@ -76,7 +77,7 @@ it.each(['project', 'swarm'])('queues a teammate start with %s capacity and resu}if (path.endsWith('/deliveries')) return { data: [] }throw new Error(`Unexpected pool request ${path}`)- }+ })onTestFailed(() => daemons.forEach(d => console.log(d.log().split('\n').slice(-75).join('\n'))))await Promise.all(daemons.map(d => d.start()))await until('both fixture accounts connected', () => backend.nodeUp(leadMachine.machineId) && backend.nodeUp(memberMachine.machineId), 30000)diff --git a/cli/e2e/superTabRoute.e2e.ts b/cli/e2e/superTabRoute.e2e.tsindex ba8683522..70ed60c4c 100644--- a/cli/e2e/superTabRoute.e2e.ts+++ b/cli/e2e/superTabRoute.e2e.ts@@ -9,6 +9,7 @@ import { superTabCommand } from '../src/superTabs/command.js'import { LocalClient } from './harness/client.js'import { IsolatedDaemon, until } from './harness/daemon.js'import { FakeBackend, type FakeMachine } from './harness/fakeBackend.js'+import { overOldRoutes } from './harness/swarmReads.js'const ME: FakeMachine = { machineId: 'c9'.repeat(16), computerId: 'e2e-super-tab-route-computer', name: 'Fixture', token: 'e2e-super-tab-route-token' }const TAB = 'route-tab'@@ -64,7 +65,7 @@ async function setup(hostedJev: FakeBackend['jev'], options: { workerBusy?: boolconst records: Array<Record<string, any>> = []const commands: Array<Record<string, any>> = []const starts = new Map<string, Record<string, any>>()- relay.superTabs = async (method, raw, body) => {+ relay.superTabs = overOldRoutes(async (method, raw, body) => {const url = new URL(raw, relay.httpUrl), path = url.pathnameif (path === `/api/super-tabs/${TAB}` && method === 'GET') return { data: { revision: records.length, state: { id: TAB, agents, conversations } } }if (path === `/api/super-tabs/${TAB}/routing-policy`) return { data: { policy: POLICY, warnings: [], overridden: [] } }@@ -73,7 +74,10 @@ async function setup(hostedJev: FakeBackend['jev'], options: { workerBusy?: boolrecords.push(body)return { data: { revision: records.length, result: { routeDecisionId: `d-${records.length}` } } }}- if (path === `/api/super-tabs/hosts/${ME.machineId}` || path === `/api/super-tabs/hosts/${ME.machineId}/assignments`) return { data: [] }+ // The roster lists this machine's agents, as a server's does: the daemon learns its caller there (#1726).+ if (path === `/api/super-tabs/hosts/${ME.machineId}`) return { data: agents.filter(agent => agent.machineId === ME.machineId)+ .map(agent => ({ tabId: TAB, agent, lead: agent.id === leadId, leadsConversationId: null, observers: [] })) }+ if (path === `/api/super-tabs/hosts/${ME.machineId}/assignments`) return { data: [] }if (path.startsWith(`/api/super-tabs/${TAB}/starts/`)) return { data: starts.get(path.split('/').at(-1)!) }if (path === `/api/super-tabs/${TAB}/commands`) {const command = body.command@@ -89,7 +93,7 @@ async function setup(hostedJev: FakeBackend['jev'], options: { workerBusy?: boolreturn { data: { result: {} } }}throw new Error(`Unexpected request ${method} ${raw}`)- }+ })const where = { port: d.port, dataDir: d.dataDir, machineId: ME.machineId, harnessPane: true }async function route(group = 'g1') {let answer: Record<string, any> = {}diff --git a/cli/e2e/superTabs.e2e.ts b/cli/e2e/superTabs.e2e.tsindex 39bc12c16..6e0262e22 100644--- a/cli/e2e/superTabs.e2e.ts+++ b/cli/e2e/superTabs.e2e.ts@@ -13,6 +13,7 @@ import { TerminalBinaryKind } from '../src/lib/terminalBinary.js'import { LocalClient } from './harness/client.js'import { CLI_ROOT, IsolatedDaemon, until } from './harness/daemon.js'import { FakeBackend, type FakeMachine } from './harness/fakeBackend.js'+import { overOldRoutes } from './harness/swarmReads.js'const ME: FakeMachine = { machineId: 'b8'.repeat(16), computerId: 'e2e-super-tab-computer', name: 'Fixture', token: 'e2e-super-tab-token' }const TAB = 'fixture-tab'@@ -49,7 +50,7 @@ it('starts either engine once, posts to its captured group and delivers shared ilet loseNativeReply = truelet revision = 0, allowed = true, deliveryReads = 0const idFor = (harnessId: string) => createHash('sha256').update(JSON.stringify([ME.machineId, harnessId])).digest('hex').slice(0, 24)- relay.superTabs = async (method, raw, body) => {+ relay.superTabs = overOldRoutes(async (method, raw, body) => {const url = new URL(raw, relay.httpUrl), path = url.pathnameif (path === `/api/super-tabs/hosts/${ME.machineId}/pools`) return { data: [] }if (path === `/api/super-tabs/hosts/${ME.machineId}/assignments`) return { data: assignments }@@ -139,7 +140,7 @@ it('starts either engine once, posts to its captured group and delivers shared ireturn { data: {} }}throw new Error(`Unexpected request ${method} ${raw}`)- }+ })await d.start()const client = await LocalClient.connect(d, { machineId: ME.machineId }); clients.push(client)const cwd = join(d.projectsDir, 'project'); mkdirSync(cwd, { recursive: true })@@ -385,7 +386,7 @@ it.each(['reported', 'legacy'] as const)('Change agent keeps its member and deliconst agents: Array<Record<string, any>> = []let rebinds = 0const delivery = { id: 'replacement-delivery', status: 'queued', claimId: null as string | null }- relay.superTabs = async (method, raw, body) => {+ relay.superTabs = overOldRoutes(async (method, raw, body) => {const path = new URL(raw, relay.httpUrl).pathnameif (path.endsWith('/pools') || path.endsWith('/assignments')) return { data: [] }if (path === `/api/super-tabs/hosts/${ME.machineId}`) return { data: agents.map(agent => ({ tabId: TAB, agent, observers: [] })) }@@ -408,7 +409,7 @@ it.each(['reported', 'legacy'] as const)('Change agent keeps its member and delireturn { data: { message: { id: 'replacement-message', conversationId: 'feature', author: { name: 'Fixture human' }, text: `verify-switched-${mode}` } } }}throw new Error(`Unexpected request ${method} ${path}`)- }+ })await d.start()onTestFailed(() => console.log(d.log().split('\n').slice(-100).join('\n')))const client = await LocalClient.connect(d, { machineId: ME.machineId }); clients.push(client)diff --git a/cli/e2e/superTabsCollaboration.e2e.ts b/cli/e2e/superTabsCollaboration.e2e.tsindex eb7e5ca62..f378b26ca 100644--- a/cli/e2e/superTabsCollaboration.e2e.ts+++ b/cli/e2e/superTabsCollaboration.e2e.ts@@ -12,6 +12,7 @@ import { LocalClient } from './harness/client.js'import { CLI_ROOT, until, type IsolatedDaemon } from './harness/daemon.js'import { FakeBackend } from './harness/fakeBackend.js'import { signedInDaemon, writeE2ee } from './harness/fleet.js'+import { overOldRoutes } from './harness/swarmReads.js'const TAB = 'shared-work', GROUP = 'offline-editing'let backend: FakeBackend | undefined@@ -46,7 +47,7 @@ it('coordinates an owner-contributed agent while keeping guest machine access selet revision = 0, contributionAllowed = trueconst agentId = (machine: string, harness: string) => createHash('sha256').update(JSON.stringify([machine, harness])).digest('hex').slice(0, 24)const failure = () => ({ status: 403, error: { code: 'FORBIDDEN', message: 'This contribution is no longer shared.' } })- relay.superTabs = async (method, raw, body, caller) => {+ relay.superTabs = overOldRoutes(async (method, raw, body, caller) => {const path = new URL(raw, relay.httpUrl).pathnameif (path.startsWith('/api/super-tabs/hosts/')) {expect(path.split('/')[4]).toBe(caller.machineId)@@ -124,7 +125,7 @@ it('coordinates an owner-contributed agent while keeping guest machine access sereturn { data: {} }}throw new Error(`Unexpected route ${method} ${path}`)- }+ })await Promise.all(daemons.map(daemon => daemon.start()))await until('both accounts connected', () => relay.nodeUp(starter.machineId) && relay.nodeUp(member.machineId), 30_000)const onA = await LocalClient.connect(a, { machineId: starter.machineId }), onB = await LocalClient.connect(b, { machineId: member.machineId })diff --git a/cli/e2e/swarmLegacySkills.e2e.ts b/cli/e2e/swarmLegacySkills.e2e.tsindex dcdce3011..5f9336c0b 100644--- a/cli/e2e/swarmLegacySkills.e2e.ts+++ b/cli/e2e/swarmLegacySkills.e2e.ts@@ -6,6 +6,7 @@ import { LocalClient } from './harness/client.js'import { CLI_ROOT, IsolatedDaemon, until } from './harness/daemon.js'import { FakeBackend, type FakeMachine } from './harness/fakeBackend.js'import { retainContributions } from '../src/superTabs/retention.js'+import { overOldRoutes } from './harness/swarmReads.js'const ME: FakeMachine = { machineId: 'c9'.repeat(16), computerId: 'legacy-sw-test', name: 'Fixture', token: 'legacy-sw-token' }let daemon: IsolatedDaemon | undefined, relay: FakeBackend | undefined, client: LocalClient | undefined@@ -20,12 +21,12 @@ it('old Lead and worker restarts and stopped resume gain only their skill; persomachineId: ME.machineId, expiresAt: Date.now() + 30 * 24 * 3600_000, updatedAt: Date.now(), signInEpoch: 'e2e' }), { mode: 0o600 })onTestFailed(() => console.log(d.log().split('\n').slice(-120).join('\n')))const agents: Array<Record<string, any>> = [], groups: Array<Record<string, any>> = []- b.superTabs = async (_method, raw) => {+ b.superTabs = overOldRoutes(async (_method, raw) => {const path = new URL(raw, b.httpUrl).pathnameif (path === `/api/super-tabs/hosts/${ME.machineId}`) return { data: agents.map(agent => ({ tabId: 'tab', agent, observers: [] })) }if (path === '/api/super-tabs/tab') return { data: { state: { agents: agents.filter(a => a.id !== 'removed'), conversations: groups } } }return { data: [] }- }+ })await d.start(); const c = await LocalClient.connect(d, { machineId: ME.machineId }); client = cconst cwd = join(d.projectsDir, 'legacy'); mkdirSync(cwd)writeFileSync(join(cwd, 'AGENTS.md'), 'Project rules stay here\n')diff --git a/cli/src/lib/swarmSkills.spec.ts b/cli/src/lib/swarmSkills.spec.tsindex 6cbb55949..cc93773f5 100644--- a/cli/src/lib/swarmSkills.spec.ts+++ b/cli/src/lib/swarmSkills.spec.ts@@ -40,6 +40,7 @@ describe('built-in Swarm skills', () => {})// The owner's approved text (2026-10-22, with the Lead recovery guidance of 2026-10-23), byte for byte; the Lead's gains only the approved 2-hour line (2026-10-23).+ // The Builder's three push rules name its checkpoint push beside the review push (v1 liveness, 2026-10-26).const sha = (text: string) => createHash('sha256').update(text).digest('hex')// The approved terminal line (spec/2026-10-23-lead-sees-agent-terminal.md), the Lead's alone, in both modes.const terminal = '- When a worker seems stuck, read its terminal; answer prompts within its task; ask the owner before approving anything risky.\n'@@ -50,10 +51,14 @@ describe('built-in Swarm skills', () => {const localDefault = '- Local models: the route may pick one for low-difficulty, well-specified work; set "local":true only when a person asks for one, set "model" to a model a person names, and start it with the route\'s gridModel and gridName.\n'// The approved mention line (spec/2026-10-24-lead-mentions.md, call 5), the Lead's alone, in both modes.const mention = '- When you need a person to act or decide, tag them in the message.\n'+ // The lost-work and checkpoint lines (Lead's brief for v1 liveness, 2026-10-26; docs: swarm-never-stops): the Lead's and+ // the Builder's alone, in both modes.+ const lost = '- When you are told a task is lost, hand it on at once: route it and assign it to another agent, avoiding what failed (another machine if its machine died, another account or engine if it hit a usage limit). The new brief tells the successor to continue from the lost attempt\'s pushed branch and last result, not to start over.\n'+ const checkpoint = '- Push your work branch at least every 30 minutes, and set your work status to working with a one-line note of what is done and what is next, so another agent can continue if you stop.\n'const twoHours = '- A Builder or Reviewer that has been down for 2 hours (machine offline, session gone or stopped): cancel its task with the reason, route it, and assign it to another agent with what the first one left (branch, last revision, last report).\n'it.each([['lead', '5fc83d8c43b66b44cdab27b48235dbc86b7ab11a57153edc1ae7e92831642a8e'],- ['dev', '86caf697c83365f000317845b0aaa929947a9591d637ab2bd0f8536da8e86763'],+ ['dev', 'e78ce31a71f169d8956a2acd46e8bb43b79bd654b80b0fe3c33dbced9d2c3c75'],['review', '424dc9db5642ed7093128525f30877ffc301eb6957b33e8234916de0f0eaa208'],] as const)('writes the owner\'s Harness orchestration %s skill byte for byte', (role, sha256) => {expect(parseSwarmSkill({ role, key: 'session' })).toEqual({ role, key: 'session' })@@ -67,7 +72,9 @@ describe('built-in Swarm skills', () => {expect(text.split(overlap)).toHaveLength(role === 'lead' ? 2 : 1)expect(text.split(local)).toHaveLength(role === 'lead' ? 2 : 1)expect(text.split(mention)).toHaveLength(role === 'lead' ? 2 : 1)- expect(sha(text.replace(twoHours, '').replace(terminal, '').replace(overlap, '').replace(local, '').replace(mention, ''))).toBe(sha256)+ expect(text.split(lost)).toHaveLength(role === 'lead' ? 2 : 1)+ expect(text.split(checkpoint)).toHaveLength(role === 'dev' ? 2 : 1)+ expect(sha(text.replace(twoHours, '').replace(terminal, '').replace(overlap, '').replace(local, '').replace(mention, '').replace(lost, '').replace(checkpoint, ''))).toBe(sha256)}})it('adds the 2-hour line to section 7 right after the 6-hour rule', () => {@@ -76,7 +83,7 @@ describe('built-in Swarm skills', () => {})it('adds the terminal line where each Lead skill keeps work moving, right after the silent-worker rule', () => {const orchestration = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session' }).file, 'utf8')- expect(orchestration).toContain(`naming the machine owner who can answer.\n${twoHours}${terminal}- Keep each worker supplied`)+ expect(orchestration).toContain(`naming the machine owner who can answer.\n${twoHours}${lost}${terminal}- Keep each worker supplied`)const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session', mode: 'default' }).file, 'utf8')expect(plain).toContain(`- A worker with active work that has said nothing for 20 minutes: ask it.\n${terminal}- A Builder or Reviewer`)})@@ -92,6 +99,21 @@ describe('built-in Swarm skills', () => {const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session', mode: 'default' }).file, 'utf8')expect(plain).toContain(`- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.\n${mention}- Settle ambiguities`)})+ it('adds the lost-work line right after each Lead skill\'s 2-hour rule', () => {+ const orchestration = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session' }).file, 'utf8')+ expect(orchestration).toContain(`${twoHours}${lost}`)+ const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'lead', key: 'session', mode: 'default' }).file, 'utf8')+ expect(plain).toContain(`assign it to another agent with what the first one left (branch, last revision, last report).\n${lost}- Work with no progress`)+ })+ it('adds the checkpoint line where each Builder skill keeps others able to resume its work', () => {+ const orchestration = readFileSync(prepareSwarmSkill(fixture(), { role: 'dev', key: 'session' }).file, 'utf8')+ expect(orchestration).toContain(`never redo a committed step.\n${checkpoint}`)+ // The orchestration Builder pushed only for review; its checkpoint push is now the other exception.+ expect(orchestration).toContain('No merge, PR or push, except pushing your own work branch: at least every 30 minutes, and when the group needs review.')+ expect(orchestration).not.toContain('only for review, only when the group needs it')+ const plain = readFileSync(prepareSwarmSkill(fixture(), { role: 'dev', key: 'session', mode: 'default' }).file, 'utf8')+ expect(plain).toContain(`- Have something to show at least every 20 minutes: a push or a short progress line.\n${checkpoint}`)+ })// The owner's approved Default texts (attached to the spec, 2026-10-23), byte for byte.it.each([['lead', 'a7b8aed240f38edda8a461d87ce83499696588b2da41ed261821985caa63e415'],@@ -105,7 +127,9 @@ describe('built-in Swarm skills', () => {expect(text.split(overlap)).toHaveLength(role === 'lead' ? 2 : 1)expect(text.split(localDefault)).toHaveLength(role === 'lead' ? 2 : 1)expect(text.split(mention)).toHaveLength(role === 'lead' ? 2 : 1)- expect(sha(text.replace(terminal, '').replace(overlap, '').replace(localDefault, '').replace(mention, ''))).toBe(sha256)+ expect(text.split(lost)).toHaveLength(role === 'lead' ? 2 : 1)+ expect(text.split(checkpoint)).toHaveLength(role === 'dev' ? 2 : 1)+ expect(sha(text.replace(terminal, '').replace(overlap, '').replace(localDefault, '').replace(mention, '').replace(lost, '').replace(checkpoint, ''))).toBe(sha256)expect(prepared.instructions).toBe(`Use the swarm-${role} skill for this session: the team process; otherwise work your usual way. Before working, read ${JSON.stringify(prepared.file)} with your file or shell tool.`)})diff --git a/cli/src/lib/swarmSkills.ts b/cli/src/lib/swarmSkills.tsindex b48651771..d6383ac94 100644--- a/cli/src/lib/swarmSkills.ts+++ b/cli/src/lib/swarmSkills.ts@@ -123,6 +123,7 @@ For large work, post the group plan and get the owner's ok before assigning; onc- Rulings, not stalls: when a Builder hits an ambiguity you can settle, settle it and record "Ruling: what — why — cost if wrong". Ask the person only what changes what gets built.- Each time you are woken, look at active work. Ask a worker with active work that has said nothing for 20 minutes; reassign work that has not moved for 6 hours; report on-screen trust, sign-in or permission questions in chat, naming the machine owner who can answer.- A Builder or Reviewer that has been down for 2 hours (machine offline, session gone or stopped): cancel its task with the reason, route it, and assign it to another agent with what the first one left (branch, last revision, last report).+- When you are told a task is lost, hand it on at once: route it and assign it to another agent, avoiding what failed (another machine if its machine died, another account or engine if it hit a usage limit). The new brief tells the successor to continue from the lost attempt's pushed branch and last result, not to start over.- When a worker seems stuck, read its terminal; answer prompts within its task; ask the owner before approving anything risky.- Keep each worker supplied: have its next group ready before it finishes, so nobody waits for you.- Cancel a duplicate, obsolete or wrong task with a reason.@@ -187,7 +188,7 @@ You finish one group's work completely, inside its brief, with proof. Work as if1. No production code without a failing test first.2. No fix without a found root cause.3. No "done", "fixed" or "passing" without running the check now and reading its output.-4. Stay inside your brief and owned code. No subagents to split the work; read-only lookups are fine. No merge, PR or push, except pushing your work branch when the group needs review. Never start a reviewer for your own work.+4. Stay inside your brief and owned code. No subagents to split the work; read-only lookups are fine. No merge, PR or push, except pushing your own work branch: at least every 30 minutes, and when the group needs review. Never start a reviewer for your own work.5. Project instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) outrank this skill.## 1. Take the assignment@@ -208,6 +209,7 @@ You finish one group's work completely, inside its brief, with proof. Work as if- Follow the codebase's existing patterns and the brief's file layout. If a file grows past what the brief intended, or one you change is already tangled, say so in the handoff; do not restructure.- The approved spec outranks the brief, and the brief outranks your plan. When they conflict, or a step turns out wrong, take the smallest change that satisfies the spec and post "Ruling: what — why — cost if wrong". An unrecorded deviation is a decision made in secret.- After each committed step, post one progress line (step, commit, test result) so a fresh session can resume. After a restart, trust those lines and git log over memory, and never redo a committed step.+- Push your work branch at least every 30 minutes, and set your work status to working with a one-line note of what is done and what is next, so another agent can continue if you stop.- Before handoff: every test the brief names exists and ran, every expected result was compared with the real one, and every deviation has a Ruling.## 3. Test first@@ -274,7 +276,7 @@ Record each acceptance check with the exact command, revision and observed resul## 9. Limits- To split the work, ask the Lead to route it. Do not touch other groups' code.-- Merge, push, open a PR, release, force-push or discard only when told; the one exception is pushing your work branch for review.+- Merge, push, open a PR, release, force-push or discard only when told; the one exception is pushing your own work branch, every 30 minutes and for review.- If your task is cancelled, stop and say where you left it.- Print little to save quota. Keep progress and blockers in the group chat.@@ -293,7 +295,7 @@ Record each acceptance check with the exact command, revision and observed resul| "The reviewer is right, fixing" | Check it against the code first. || "A subagent can review my work" | The Lead's Reviewer is the review. || "I'll split this with my subagents" | Ask the Lead to route it. |-| "I'll push so they can see" | Push only the work branch, only for review, only when the group needs it. |+| "I'll push so they can see" | Push only your own work branch: every 30 minutes and for review. |`,review: `---name: swarm-review@@ -396,6 +398,7 @@ Keep each Builder's list a few tasks deep; do the easy, self-contained parts fir- A worker with active work that has said nothing for 20 minutes: ask it.- When a worker seems stuck, read its terminal; answer prompts within its task; ask the owner before approving anything risky.- A Builder or Reviewer that has been down for 2 hours (its machine offline, its session gone, or stopped): cancel its task with the reason, route it, and assign it to another agent with what the first one left (branch, last revision, last report).+- When you are told a task is lost, hand it on at once: route it and assign it to another agent, avoiding what failed (another machine if its machine died, another account or engine if it hit a usage limit). The new brief tells the successor to continue from the lost attempt's pushed branch and last result, not to start over.- Work with no progress for 6 hours goes back to you: reassign it or cut it smaller.- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.- When you need a person to act or decide, tag them in the message.@@ -443,6 +446,7 @@ You finish one group's work completely, inside its brief, as if nobody will come- A fix comes with a test that fails before it and passes after.- Name a known flaky test instead of letting it block you.- Have something to show at least every 20 minutes: a push or a short progress line.+- Push your work branch at least every 30 minutes, and set your work status to working with a one-line note of what is done and what is next, so another agent can continue if you stop.- When an answer is unclear, take its narrowest safe reading and say so. Keep working on whatever doesn't depend on a question, and don't ask twice.- To split the work or take more, ask the Lead. You may propose new work; the Lead decides.diff --git a/cli/src/superTabs/cards.spec.ts b/cli/src/superTabs/cards.spec.tsindex bab9c5c4c..52f0b1c3a 100644--- a/cli/src/superTabs/cards.spec.ts+++ b/cli/src/superTabs/cards.spec.ts@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'import type { CoreApi } from '../core/api.js'import { fakeCore } from '../testing/fakeCore.js'import { lastLeadMessage, leadsOf, SwarmCards, type SwarmCard } from './cards.js'+import { swarmReply } from './fixtures/read/index.js'const agent = (id: string, over: Record<string, unknown> = {}) =>({ id, harnessId: `h-${id}`, machineId: 'm1', machineOwnerId: 'me', configuration: { engine: 'claude' }, ...over })@@ -139,8 +140,8 @@ describe('lastLeadMessage', () => {})})-/** A fake backend: tabs by id with a revision, a message store per conversation, and call counting. */-function setup(tabs: Record<string, { revision: number; state: Record<string, unknown> }>, extra: { activity?: Record<string, 'working' | 'idle'>; elapsed?: number; messages?: (path: string) => unknown } = {}) {+/** A fake backend: tabs by id with the time each last changed, a message store per conversation, and call counting. */+function setup(tabs: Record<string, { lastChangedAt: number; state: Record<string, unknown> }>, extra: { activity?: Record<string, 'working' | 'idle'>; elapsed?: number; messages?: (path: string) => unknown } = {}) {const calls: string[] = []const failing = new Map<string, number>()let listFails = false@@ -149,24 +150,24 @@ function setup(tabs: Record<string, { revision: number; state: Record<string, unconst call = vi.fn(async (method: string, path: string, _body?: unknown) => {calls.push(`${method} ${path}`)const [route, query] = path.split('?')- if (route === '/api/super-tabs') {+ if (route === '/api/super-tabs/list') {if (listFails) throw new Error('offline')const ids = Object.keys(tabs).sort(), after = new URLSearchParams(query).get('after')const rest = ids.filter(id => !after || id > after)let page = pages[after ?? '']?.next !== undefined ? rest.slice(0, 1) : restlet next = pages[after ?? ''] ? pages[after ?? ''].next : nullif (pageSize) { page = rest.slice(0, pageSize); next = page.length < rest.length ? page[page.length - 1] : null }- return { status: 200, body: { success: true, data: { tabs: page.map(id => ({ id, name: String(tabs[id].state.name), ownerId: 'me', revision: tabs[id].revision, paused: false })), next } } }+ return { status: 200, body: { success: true, data: { tabs: page.map(id => ({ id, name: String(tabs[id].state.name), ownerId: 'me', lastChangedAt: tabs[id].lastChangedAt, paused: false })), next } } }}- const tab = /^\/api\/super-tabs\/([^/]+)$/.exec(route)+ const tab = /^\/api\/super-tabs\/([^/]+)\/(parts|changes)$/.exec(route)if (tab) {const code = failing.get(tab[1])if (code) return { status: code, body: { success: false, error: { code: 'FORBIDDEN', message: 'no' } } }- // The real reply of GET /api/super-tabs/:id (backend/src/superTabs/store.ts read): the state sits under `state`, beside the revision.- return { status: 200, body: { success: true, data: { revision: tabs[tab[1]].revision, state: tabs[tab[1]].state } } }+ // A tab is read by parts (design 2026-10-26 4.3): a fake keeps no history, so every changes read asks for a first load.+ return { status: 200, body: { success: true, data: swarmReply(path, tabs[tab[1]].state, { lastChangedAt: tabs[tab[1]].lastChangedAt }) } }}- // The real messages page: { messages, next, revision }.- return { status: 200, body: { success: true, data: { revision: 1, ...(extra.messages?.(path) ?? { messages: [], next: null }) as object } } }+ // The real messages page: { messages, next }, `next` the (sequence, id) cursor of the page before.+ return { status: 200, body: { success: true, data: { ...(extra.messages?.(path) ?? { messages: [], next: null }) as object } } }})const core = fakeCore({account: { backend: call as unknown as CoreApi['account']['backend'], identity: vi.fn(async () => ({ accountId: 'me', email: '[email protected]' })) },@@ -180,13 +181,22 @@ function setup(tabs: Record<string, { revision: number; state: Record<string, uncards.onCards = c => seen.push(c)return { cards, calls, seen, call, core, failing, tabs, paginate: (p: typeof pages) => { pages = p }, pageBy: (n: number) => { pageSize = n }, breakList: (v = true) => { listFails = v }, advance: (ms: number) => { clock += ms } }}-const detailReads = (calls: string[]) => calls.filter(c => /^GET \/api\/super-tabs\/[^/?]+$/.test(c))+/** Each read of a tab, named by the tab: a changes read, or a first load that no changes read of it asked for. */+function detailReads(calls: string[]): string[] {+ const reloading = new Set<string>(), reads: string[] = []+ for (const call of calls) {+ const [, tab, kind] = /^(GET \/api\/super-tabs\/[^/]+)\/(parts|changes)/.exec(call) ?? []+ if (!tab) continue+ if (kind === 'changes') { reloading.add(tab); reads.push(tab) } else if (!reloading.delete(tab)) reads.push(tab)+ }+ return reads+}afterEach(() => { vi.useRealTimers() })describe('SwarmCards.tick', () => {- it('lists, reads every tab once, then reads only a tab whose revision changed', async () => {- const t = setup({ t1: { revision: 1, state: swarm() }, t2: { revision: 4, state: swarm({ name: 'other' }) } })+ it('lists, reads every tab once, then reads only a tab whose change time moved', async () => {+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() }, t2: { lastChangedAt: 4, state: swarm({ name: 'other' }) } })await t.cards.tick()expect(detailReads(t.calls)).toEqual(['GET /api/super-tabs/t1', 'GET /api/super-tabs/t2'])expect(t.seen).toHaveLength(1)@@ -195,7 +205,7 @@ describe('SwarmCards.tick', () => {await t.cards.tick()expect(detailReads(t.calls)).toEqual([])expect(t.seen).toHaveLength(1)- t.tabs.t2.revision = 5+ t.tabs.t2.lastChangedAt = 5t.tabs.t2.state = swarm({ name: 'renamed' })t.calls.length = 0await t.cards.tick()@@ -204,11 +214,11 @@ describe('SwarmCards.tick', () => {})it('follows `next` through the pages of the list and keeps the first 16 tabs', async () => {- const t = setup({ t1: { revision: 1, state: swarm() }, t2: { revision: 1, state: swarm() } })+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() }, t2: { lastChangedAt: 1, state: swarm() } })t.paginate({ '': { next: 't1' }, t1: { next: null } })await t.cards.tick()- expect(t.calls.filter(c => c.includes('?after='))).toEqual(['GET /api/super-tabs?after=t1'])- const wide = Object.fromEntries(Array.from({ length: 20 }, (_, i) => [`t${String(i).padStart(2, '0')}`, { revision: 1, state: swarm() }]))+ expect(t.calls.filter(c => c.includes('?after='))).toEqual(['GET /api/super-tabs/list?after=t1'])+ const wide = Object.fromEntries(Array.from({ length: 20 }, (_, i) => [`t${String(i).padStart(2, '0')}`, { lastChangedAt: 1, state: swarm() }]))const w = setup(wide)await w.cards.tick()expect(w.seen[0]).toHaveLength(16)@@ -216,18 +226,18 @@ describe('SwarmCards.tick', () => {})it('drops a tab gone from the list, keeps the last cards when the list fails, and drops only a tab that answers 403', async () => {- const t = setup({ t1: { revision: 1, state: swarm() }, t2: { revision: 1, state: swarm({ name: 'two' }) } })+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() }, t2: { lastChangedAt: 1, state: swarm({ name: 'two' }) } })await t.cards.tick()t.breakList()await t.cards.tick()expect(t.seen).toHaveLength(1)t.breakList(false)t.failing.set('t2', 403)- t.tabs.t2.revision = 2+ t.tabs.t2.lastChangedAt = 2await t.cards.tick()expect(t.seen.at(-1)?.map(c => c.id)).toEqual(['t1'])t.failing.set('t1', 401)- t.tabs.t1.revision = 2+ t.tabs.t1.lastChangedAt = 2t.failing.delete('t2')await t.cards.tick()expect(t.seen.at(-1)?.map(c => c.id)).toEqual(['t2'])@@ -237,10 +247,10 @@ describe('SwarmCards.tick', () => {})it('keeps a tab it already read when another failure happens on re-read', async () => {- const t = setup({ t1: { revision: 1, state: swarm() } })+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() } })await t.cards.tick()t.failing.set('t1', 500)- t.tabs.t1.revision = 2+ t.tabs.t1.lastChangedAt = 2await t.cards.tick()expect(t.seen).toHaveLength(1)await t.cards.tick()@@ -248,13 +258,13 @@ describe('SwarmCards.tick', () => {})it('keeps a paused tab as a card with every Lead done', async () => {- const t = setup({ t1: { revision: 1, state: swarm({ paused: true, conversations: [...swarm().conversations, work('web', 'needs_human')] }) } })+ const t = setup({ t1: { lastChangedAt: 1, state: swarm({ paused: true, conversations: [...swarm().conversations, work('web', 'needs_human')] }) } })await t.cards.tick()expect(t.seen[0][0].leads.map(l => l.state)).toEqual(['done', 'done'])})it('shows a local Lead in a turn as work, counting `since` from the footer timer, and re-sends only on a change other than since', async () => {- const t = setup({ t1: { revision: 1, state: swarm() } }, { activity: { 'h-a1': 'working' }, elapsed: 20 })+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() } }, { activity: { 'h-a1': 'working' }, elapsed: 20 })await t.cards.tick()expect(t.seen[0][0].leads[0]).toMatchObject({ id: 'a1', state: 'work', since: 20 })t.advance(5000)@@ -268,7 +278,7 @@ describe('SwarmCards.tick', () => {it('re-sends when the clock\'s turn changes (the Lead\'s ends, a worker\'s goes on), not while the same turn runs', async () => {const state = swarm({ agents: [agent('a1'), agent('a2'), agent('b1', { projectId: 'web' })] })- const t = setup({ t1: { revision: 1, state } }, { activity: { 'h-a1': 'working' }, elapsed: 90 })+ const t = setup({ t1: { lastChangedAt: 1, state } }, { activity: { 'h-a1': 'working' }, elapsed: 90 })await t.cards.tick()expect(t.seen[0][0].leads[0]).toMatchObject({ project: 'web', state: 'work', since: 90 })// the worker starts too: the Lead's earlier turn is still the clock, nothing to send@@ -289,13 +299,13 @@ describe('SwarmCards.tick', () => {})it('sends a turn that just began as 1 s in, never 0 (the Pro shows no clock for 0)', async () => {- const t = setup({ t1: { revision: 1, state: swarm() } }, { activity: { 'h-a1': 'working' }, elapsed: 0 })+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() } }, { activity: { 'h-a1': 'working' }, elapsed: 0 })await t.cards.tick()expect(t.seen[0][0].leads[0]).toMatchObject({ id: 'a1', state: 'work', since: 1 })})it('names a remote Lead\'s owner using the signed-in account', async () => {- const t = setup({ t1: { revision: 1, state: swarm({ agents: [agent('a1', { machineId: 'm2', machineOwnerId: 'sam' }), agent('a2')] }) } })+ const t = setup({ t1: { lastChangedAt: 1, state: swarm({ agents: [agent('a1', { machineId: 'm2', machineOwnerId: 'sam' }), agent('a2')] }) } })await t.cards.tick()expect(t.seen[0][0].leads.find(l => l.id === 'a1')).toMatchObject({ owner: '[email protected]', local: '' })})@@ -303,28 +313,29 @@ describe('SwarmCards.tick', () => {describe('SwarmCards.recap', () => {const msg = (sequence: number, who: string, over: Record<string, unknown> = {}) =>- ({ sequence, text: `m${sequence}`, author: { id: who }, createdAt: '2026-10-22T00:00:00.000Z', ...over })+ ({ id: `x${sequence}`, sequence, text: `m${sequence}`, author: { id: who }, createdAt: '2026-10-22T00:00:00.000Z', ...over })const withSequence = (n: number) => swarm({ conversations: [conv('lead-web', 'a1', { projectId: 'web', lastMessageSequence: n }), conv('lead-mobile', 'a2', { projectId: 'mobile' })] })- it('reads the newest page, falls back one page with before, then says none', async () => {- const t = setup({ t1: { revision: 1, state: withSequence(9) } }, { messages: path => path.includes('before=7')- ? { messages: [msg(5, 'a1'), msg(6, 'a2')], next: null } : { messages: [msg(7, 'a2'), msg(8, 'a2', { source: {} })], next: 7 } })+ // Design 4.6: a page ends on a (sequence, id) pair, so a page edge inside messages of equal sequence skips none of them.+ it('reads the newest page, falls back one page with the page\'s own cursor, then says none', async () => {+ const t = setup({ t1: { lastChangedAt: 1, state: withSequence(9) } }, { messages: path => path.includes('before=7&beforeId=x7')+ ? { messages: [msg(5, 'a1'), msg(6, 'a2')], next: null } : { messages: [msg(7, 'a2'), msg(8, 'a2', { source: {} })], next: { sequence: 7, id: 'x7' } } })await t.cards.tick()const recap = await t.cards.recap('t1', 'a1')expect(recap).toEqual({ tabId: 't1', leadId: 'a1', text: 'm5', at: Date.parse('2026-10-22T00:00:00.000Z') / 1000, none: false })expect(t.calls.filter(c => c.includes('/messages'))).toEqual([- 'GET /api/super-tabs/t1/conversations/lead-web/messages', 'GET /api/super-tabs/t1/conversations/lead-web/messages?before=7'])- const none = setup({ t1: { revision: 1, state: withSequence(9) } }, { messages: () => ({ messages: [msg(7, 'a2')], next: 7 }) })+ 'GET /api/super-tabs/t1/conversations/lead-web/messages', 'GET /api/super-tabs/t1/conversations/lead-web/messages?before=7&beforeId=x7'])+ const none = setup({ t1: { lastChangedAt: 1, state: withSequence(9) } }, { messages: () => ({ messages: [msg(7, 'a2')], next: { sequence: 7, id: 'x7' } }) })await none.cards.tick()expect(await none.cards.recap('t1', 'a1')).toMatchObject({ none: true, text: '', at: 0 })- const empty = setup({ t1: { revision: 1, state: withSequence(0) } })+ const empty = setup({ t1: { lastChangedAt: 1, state: withSequence(0) } })await empty.cards.tick()expect(await empty.cards.recap('t1', 'a1')).toMatchObject({ none: true })expect(empty.calls.filter(c => c.includes('/messages'))).toHaveLength(1)})it('answers again from memory while the conversation has not moved, and cuts the text at 1,500 bytes', async () => {- const t = setup({ t1: { revision: 1, state: withSequence(3) } }, { messages: () => ({ messages: [msg(3, 'a1', { text: `${'x'.repeat(1499)}éé` })], next: null }) })+ const t = setup({ t1: { lastChangedAt: 1, state: withSequence(3) } }, { messages: () => ({ messages: [msg(3, 'a1', { text: `${'x'.repeat(1499)}éé` })], next: null }) })await t.cards.tick()const first = await t.cards.recap('t1', 'a1')expect(Buffer.byteLength(first.text)).toBe(1499)@@ -334,7 +345,7 @@ describe('SwarmCards.recap', () => {})it('reads the tab itself when it was not polled yet, and refuses unknown ids and Leads', async () => {- const t = setup({ t1: { revision: 1, state: withSequence(1) } }, { messages: () => ({ messages: [msg(1, 'a1')], next: null }) })+ const t = setup({ t1: { lastChangedAt: 1, state: withSequence(1) } }, { messages: () => ({ messages: [msg(1, 'a1')], next: null }) })expect((await t.cards.recap('t1', 'a1')).none).toBe(false)expect((await t.cards.recap('t1', 'nobody')).none).toBe(true)expect((await t.cards.recap('bad id', 'a1')).none).toBe(true)@@ -342,7 +353,7 @@ describe('SwarmCards.recap', () => {it('pushes the open Lead\'s new recap once when its conversation advanced', async () => {let latest = 1- const t = setup({ t1: { revision: 1, state: withSequence(1) } }, { messages: () => ({ messages: [msg(latest, 'a1')], next: null }) })+ const t = setup({ t1: { lastChangedAt: 1, state: withSequence(1) } }, { messages: () => ({ messages: [msg(latest, 'a1')], next: null }) })const pushed: string[] = []t.cards.onRecap = r => pushed.push(r.text)await t.cards.tick()@@ -350,13 +361,13 @@ describe('SwarmCards.recap', () => {await t.cards.tick()expect(pushed).toEqual([])latest = 2- t.tabs.t1.revision = 2+ t.tabs.t1.lastChangedAt = 2t.tabs.t1.state = withSequence(2)await t.cards.tick()await t.cards.tick()expect(pushed).toEqual(['m2'])t.cards.open('s1', 't1', null)- t.tabs.t1.revision = 3+ t.tabs.t1.lastChangedAt = 3t.tabs.t1.state = withSequence(3)await t.cards.tick()expect(pushed).toEqual(['m2'])@@ -365,7 +376,7 @@ describe('SwarmCards.recap', () => {describe('SwarmCards.say', () => {it('posts the words as the person in the Lead\'s conversation of a harness here, and is false for any other harness', async () => {- const t = setup({ t1: { revision: 1, state: swarm({ agents: [agent('a1', { machineId: 'm2' }), agent('a2')] }) } })+ const t = setup({ t1: { lastChangedAt: 1, state: swarm({ agents: [agent('a1', { machineId: 'm2' }), agent('a2')] }) } })await t.cards.tick()expect(await t.cards.say('h-a2', 'ship it')).toBe(true)const post = t.call.mock.calls.find(c => c[0] === 'POST')!@@ -382,11 +393,11 @@ describe('SwarmCards.say', () => {describe('SwarmCards.want', () => {it('polls every interval while wanted and not at all after want(false)', async () => {vi.useFakeTimers()- const t = setup({ t1: { revision: 1, state: swarm() } })+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() } })t.cards.want(true)t.cards.want(true)await vi.advanceTimersByTimeAsync(0)- const listed = () => t.calls.filter(c => c === 'GET /api/super-tabs').length+ const listed = () => t.calls.filter(c => c === 'GET /api/super-tabs/list').lengthexpect(listed()).toBe(1)await vi.advanceTimersByTimeAsync(5000)expect(listed()).toBe(2)@@ -398,13 +409,13 @@ describe('SwarmCards.want', () => {})describe('SwarmCards polling cost and choice', () => {- const many = (n: number) => Object.fromEntries(Array.from({ length: n }, (_, i) => [`t${String(i).padStart(2, '0')}`, { revision: 1, state: swarm({ name: `S${i}` }) }]))+ const many = (n: number) => Object.fromEntries(Array.from({ length: n }, (_, i) => [`t${String(i).padStart(2, '0')}`, { lastChangedAt: 1, state: swarm({ name: `S${i}` }) }]))it('stops paging the list once 16 tabs are in hand', async () => {const t = setup(many(40))t.pageBy(8)await t.cards.tick()- expect(t.calls.filter(c => c.startsWith('GET /api/super-tabs') && !c.includes('/', 'GET /api/super-tabs'.length)).length).toBe(2)+ expect(t.calls.filter(c => c.startsWith('GET /api/super-tabs/list')).length).toBe(2)expect(t.seen[0]).toHaveLength(16)})@@ -418,9 +429,9 @@ describe('SwarmCards polling cost and choice', () => {t.cards.want(false)})- it('always reads again a tab whose list row has no numeric revision', async () => {- const t = setup({ t1: { revision: 1, state: swarm() } })- ;(t.tabs.t1 as { revision: unknown }).revision = undefined+ it('always reads again a tab whose list row has no numeric change time', async () => {+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() } })+ ;(t.tabs.t1 as { lastChangedAt: unknown }).lastChangedAt = undefinedawait t.cards.tick()t.calls.length = 0await t.cards.tick()@@ -429,7 +440,7 @@ describe('SwarmCards polling cost and choice', () => {it('leaves out a Swarm, a project or a harness whose id the Pro cannot hold (over 47 characters)', async () => {const long = 'x'.repeat(48)- const t = setup({ [long]: { revision: 1, state: swarm() }, t1: { revision: 1, state: swarm({+ const t = setup({ [long]: { lastChangedAt: 1, state: swarm() }, t1: { lastChangedAt: 1, state: swarm({projects: [{ id: long, name: 'long', leadConversationId: 'lead-web' }, { id: 'mobile', name: 'mobile', leadConversationId: 'lead-mobile' }],agents: [agent('a1'), agent('a2', { harnessId: long })] }) } })await t.cards.tick()@@ -444,25 +455,25 @@ describe('SwarmCards open recaps and recap reads', () => {it('keeps the open Lead per session: one Pro closing does not stop another\'s pushes, and one push serves both', async () => {let latest = 1- const t = setup({ t1: { revision: 1, state: withSequence(1) } }, { messages: () => ({ messages: [msg(latest, 'a1')], next: null }) })+ const t = setup({ t1: { lastChangedAt: 1, state: withSequence(1) } }, { messages: () => ({ messages: [msg(latest, 'a1')], next: null }) })const pushed: string[] = []t.cards.onRecap = r => pushed.push(r.text)await t.cards.tick()t.cards.open('s1', 't1', 'a1')t.cards.open('s2', 't1', 'a1')t.cards.open('s1', 't1', null)- latest = 2; t.tabs.t1.revision = 2; t.tabs.t1.state = withSequence(2)+ latest = 2; t.tabs.t1.lastChangedAt = 2; t.tabs.t1.state = withSequence(2)await t.cards.tick()expect(pushed).toEqual(['m2'])t.cards.open('s2', 't1', null)- latest = 3; t.tabs.t1.revision = 3; t.tabs.t1.state = withSequence(3)+ latest = 3; t.tabs.t1.lastChangedAt = 3; t.tabs.t1.state = withSequence(3)await t.cards.tick()expect(pushed).toEqual(['m2'])})it('does not count a push as done before the recap was read: a failed read is tried again next tick', async () => {let fail = true, latest = 1- const t = setup({ t1: { revision: 1, state: withSequence(1) } }, { messages: path => {+ const t = setup({ t1: { lastChangedAt: 1, state: withSequence(1) } }, { messages: path => {if (fail && latest === 2) throw new Error('offline')void pathreturn { messages: [msg(latest, 'a1')], next: null }@@ -471,7 +482,7 @@ describe('SwarmCards open recaps and recap reads', () => {t.cards.onRecap = r => pushed.push(r.text)await t.cards.tick()t.cards.open('s1', 't1', 'a1')- latest = 2; t.tabs.t1.revision = 2; t.tabs.t1.state = withSequence(2)+ latest = 2; t.tabs.t1.lastChangedAt = 2; t.tabs.t1.state = withSequence(2)await t.cards.tick()expect(pushed).toEqual([])fail = false@@ -481,20 +492,20 @@ describe('SwarmCards open recaps and recap reads', () => {it('opened before the tab was read: the first read is the baseline and the next change is pushed', async () => {let latest = 1- const t = setup({ t1: { revision: 1, state: withSequence(1) } }, { messages: () => ({ messages: [msg(latest, 'a1')], next: null }) })+ const t = setup({ t1: { lastChangedAt: 1, state: withSequence(1) } }, { messages: () => ({ messages: [msg(latest, 'a1')], next: null }) })const pushed: string[] = []t.cards.onRecap = r => pushed.push(r.text)t.cards.open('s1', 't1', 'a1')await t.cards.tick()expect(pushed).toEqual([])- latest = 2; t.tabs.t1.revision = 2; t.tabs.t1.state = withSequence(2)+ latest = 2; t.tabs.t1.lastChangedAt = 2; t.tabs.t1.state = withSequence(2)await t.cards.tick()expect(pushed).toEqual(['m2'])})it('has at most two recap reads in flight and refuses a third', async () => {const release: Array<() => void> = []- const t = setup({ t1: { revision: 1, state: swarm({ conversations: [conv('lead-web', 'a1', { projectId: 'web', lastMessageSequence: 4 }), conv('lead-mobile', 'a2', { projectId: 'mobile', lastMessageSequence: 4 })],+ const t = setup({ t1: { lastChangedAt: 1, state: swarm({ conversations: [conv('lead-web', 'a1', { projectId: 'web', lastMessageSequence: 4 }), conv('lead-mobile', 'a2', { projectId: 'mobile', lastMessageSequence: 4 })],agents: [agent('a1'), agent('a2'), agent('a3')] }) } }, {messages: () => new Promise(resolve => { release.push(() => resolve({ messages: [msg(4, 'a1'), msg(4, 'a2')], next: null })) }) as never })// The fake backend returns the promise's value as data.@@ -507,13 +518,13 @@ describe('SwarmCards open recaps and recap reads', () => {})it('forgets the recap of a Lead whose tab is gone', async () => {- const t = setup({ t1: { revision: 1, state: withSequence(2) }, t2: { revision: 1, state: swarm() } }, { messages: () => ({ messages: [msg(2, 'a1')], next: null }) })+ const t = setup({ t1: { lastChangedAt: 1, state: withSequence(2) }, t2: { lastChangedAt: 1, state: swarm() } }, { messages: () => ({ messages: [msg(2, 'a1')], next: null }) })await t.cards.tick()await t.cards.recap('t1', 'a1')delete t.tabs.t1await t.cards.tick()t.calls.length = 0- t.tabs.t1 = { revision: 1, state: withSequence(2) }+ t.tabs.t1 = { lastChangedAt: 1, state: withSequence(2) }await t.cards.tick()await t.cards.recap('t1', 'a1')expect(t.calls.filter(c => c.includes('/messages'))).toHaveLength(1)diff --git a/cli/src/superTabs/cards.ts b/cli/src/superTabs/cards.tsindex 79d43be04..bb64d19bf 100644--- a/cli/src/superTabs/cards.ts+++ b/cli/src/superTabs/cards.ts@@ -2,7 +2,8 @@* The Swarms a Harness Pro shows as cards on Home: for each Swarm (Super Tab) this account is in, one Lead per project with* what it is doing now, plus the last thing a Lead said, for the Pro's recap. Read as the person (never as an agent) from* the same backend routes the desktop uses, every 5 s while a capable Pro is attached (`want`), and a tab's detail is read- * only when its `revision` moved. The service hands the result to the core whole (`onCards`); the core owns the wire.+ * only when its `lastChangedAt` moved, by what changed since the last read (superTabs/swarmReads.ts). The service hands the+ * result to the core whole (`onCards`); the core owns the wire.** Status of a project's Lead, most pressing first: `ask` (an assignment of the project needs a person, `needs_human`),* `stuck` (`blocked`), `work` (an agent of the project, the Lead or a worker, runs here and is in a turn, as the app marks each@@ -14,6 +15,7 @@ import { randomUUID } from 'node:crypto'import type { CoreApi } from '../core/api.js'import { backend, SuperTabHostError } from './host.js'import { identifier, object } from './wire.js'+import { SwarmReads, type SwarmRead } from './swarmReads.js'type Json = Record<string, unknown>export type LeadState = 'ask' | 'stuck' | 'work' | 'done'@@ -106,15 +108,11 @@ export function lastLeadMessage(messages: Json[], leadId: string): { text: strinreturn best && { text: best.text, at: best.at }}-interface TabCache { revision: number; state: Json }+interface TabCache { lastChangedAt: number | null; state: Json }interface Cached { sequence: number; recap: LeadRecap }/** A Lead some Harness Pro has the recap of open, and the sessions (one per Pro) that have it open. */interface Opened { tabId: string; leadId: string; sequence: number | null; sessions: Set<string> }-/** What GET /api/super-tabs/:id answers: `{ revision, state }`. A reply without a numeric revision is never reused (-1). */-const tabOf = (answer: unknown): TabCache => {- const reply = object(answer)- return { revision: typeof reply.revision === 'number' ? reply.revision : -1, state: object(reply.state) }-}+const tabOf = (read: SwarmRead): TabCache => ({ lastChangedAt: read.lastChangedAt, state: read.state })export class SwarmCards {onCards?: (cards: SwarmCard[]) => void@@ -135,10 +133,12 @@ export class SwarmCards {private opened = new Map<string, Opened>()private openBy = new Map<string, string>()private recapsRunning = 0+ private readonly reads: SwarmReads- constructor(private readonly core: CoreApi, private readonly machineId: string, options: { now?: () => number; intervalMs?: number } = {}) {+ constructor(private readonly core: CoreApi, private readonly machineId: string, options: { now?: () => number; intervalMs?: number; reads?: SwarmReads } = {}) {this.now = options.now ?? Date.nowthis.intervalMs = options.intervalMs ?? 5000+ this.reads = options.reads ?? new SwarmReads(core)}/** Poll while a capable Pro is attached; none otherwise (no request at all). `include`: the Swarms the desktop has tabs for, read first. */@@ -190,7 +190,7 @@ export class SwarmCards {const rows: Json[] = []let after = ''for (let page = 0; page < MAX_LIST_PAGES; page++) {- const data = object(await backend(this.core, 'GET', `/api/super-tabs${after ? `?after=${encodeURIComponent(after)}` : ''}`))+ const data = object(await backend(this.core, 'GET', `/api/super-tabs/list${after ? `?after=${encodeURIComponent(after)}` : ''}`))rows.push(...list(data.tabs).filter(r => cardId(r.id)))if (!identifier(data.next)) breakif (rows.length >= MAX_CARDS && this.include.every(id => rows.some(r => r.id === id))) break@@ -205,9 +205,9 @@ export class SwarmCards {const known = new Map<string, TabCache>()await Promise.all(rows.map(async row => {const id = row.id as string, held = this.tabs.get(id)- // A row without a numeric revision cannot say it is unchanged: that tab is always read again.- if (held && typeof row.revision === 'number' && held.revision === row.revision) { known.set(id, held); return }- try { known.set(id, tabOf(await backend(this.core, 'GET', `/api/super-tabs/${id}`))) } catch (error) {+ // A row without a numeric change time cannot say it is unchanged: that tab is always read again.+ if (held && typeof row.lastChangedAt === 'number' && held.lastChangedAt === row.lastChangedAt) { known.set(id, held); return }+ try { known.set(id, tabOf(await this.reads.read(id))) } catch (error) {// Lost access drops only this card; any other failure keeps what was read before.const status = error instanceof SuperTabHostError ? error.status : 0if (held && status !== 401 && status !== 403) known.set(id, held)@@ -282,7 +282,7 @@ export class SwarmCards {if (!found) {if (this.recapsRunning >= MAX_RECAPS_IN_FLIGHT) throw new Error('too many recap reads at once')this.recapsRunning++- try { this.tabs.set(tabId, tabOf(await backend(this.core, 'GET', `/api/super-tabs/${tabId}`))) } finally { this.recapsRunning-- }+ try { this.tabs.set(tabId, tabOf(await this.reads.read(tabId))) } finally { this.recapsRunning-- }found = this.leadConversation(tabId, leadId)}if (!found) return { tabId, leadId, text: '', at: 0, none: true }@@ -293,14 +293,12 @@ export class SwarmCards {this.recapsRunning++try {const path = `/api/super-tabs/${tabId}/conversations/${found.id}/messages`- let page = list(object(await backend(this.core, 'GET', path)).messages)- let said = lastLeadMessage(page, leadId)- if (!said && page.length) {- const oldest = Math.min(...page.map(m => typeof m.sequence === 'number' ? m.sequence : Infinity))- if (Number.isFinite(oldest)) {- page = list(object(await backend(this.core, 'GET', `${path}?before=${oldest}`)).messages)- said = lastLeadMessage(page, leadId)- }+ const newest = object(await backend(this.core, 'GET', path))+ let said = lastLeadMessage(list(newest.messages), leadId)+ // The page before, from the page's own (sequence, id) cursor: a page edge inside equal sequences skips nothing (design 4.6).+ const before = object(newest.next)+ if (!said && typeof before.sequence === 'number' && identifier(before.id)) {+ said = lastLeadMessage(list(object(await backend(this.core, 'GET', `${path}?before=${before.sequence}&beforeId=${before.id}`)).messages), leadId)}const recap: LeadRecap = said ? { tabId, leadId, text: cut(said.text, RECAP_BYTES), at: said.at, none: false } : { tabId, leadId, text: '', at: 0, none: true }this.recaps.set(key, { sequence: found.sequence, recap })diff --git a/cli/src/superTabs/cloneTrust.spec.ts b/cli/src/superTabs/cloneTrust.spec.tsindex 96eadbb26..102028502 100644--- a/cli/src/superTabs/cloneTrust.spec.ts+++ b/cli/src/superTabs/cloneTrust.spec.ts@@ -12,6 +12,7 @@ import { recordTrustIn } from '../engines/kit/folderTrust.js'import { prepareContribution } from './contribution.js'import { prepareSwarmProject } from './projectFolder.js'import { ContributedMachines } from './machines.js'+import { hostForm, swarmReply } from './fixtures/read/index.js'// Never read the person's login profile: the fixture owns the engine locations.vi.mock('../engines/kit/launchExecutable.js', () => ({ launchEnvironment: vi.fn(async () => ({ ...process.env })) }))@@ -54,7 +55,7 @@ function fixture(legacy = false) {const root = join(home, 'harnesses', 'swarms', 'tab'), oldRoot = join(core.dataDir, 'swarm-projects', 'tab'), cwd = legacy ? oldRoot : rootconst row = { tabId: 'tab', machine: { machineId: core.daemon.machineId(), generation: 'grant', scope: 'swarm', cwd, engines: ['claude', 'codex'] },projects: [{ id: 'project', repository: { machineId: 'another', repositoryUrl: 'https://github.com/example/project' }, conversationIds: ['work'] }], starts: [], harnessIds: [] }- const deps = { backend: vi.fn(async () => ({ state: { projects: row.projects, machines: [row.machine] } })),+ const deps = { backend: vi.fn(async (_core: unknown, _method: string, path: string) => swarmReply(path, { projects: row.projects, machines: [row.machine] })),open: vi.fn(async () => ({ request: vi.fn(async () => ({ engines: [{ engine: 'codex', installed: true, signedIn: true }] })), close: vi.fn() })),prepare: vi.fn(async () => join(cwd, 'project')),capacity: vi.fn(async () => ({ ok: true, resources: { projectDiskFreeBytes: 1, memoryTotalBytes: 8 * 1024 ** 3, memoryUsedBytes: 0 } })) }@@ -67,7 +68,7 @@ function expectTrusted(path: string, trusted = true) {describe('consented Swarm clones', () => {it('places new contributions in the visible Swarm root and preserves earlier roots', async () => {const f = fixture()- f.deps.backend.mockResolvedValueOnce({ state: { projects: f.row.projects } } as never)+ f.deps.backend.mockImplementationOnce(async (_core: unknown, _method: string, path: string) => swarmReply(path, { projects: f.row.projects }))expect((await prepareContribution(f.core, { tabId: 'tab', scope: 'swarm' }, f.deps as never)).cwd).toBe(f.root)expect(existsSync(f.root)).toBe(true)f.row.machine.cwd = f.oldRoot@@ -97,7 +98,7 @@ describe('consented Swarm clones', () => {const f = fixture(true), source = clone(join(f.oldRoot, 'project')), current = clone(join(f.root, 'project'))const tree = join(home, 'harnesses', 'worktrees', 'project', 'worker'), unrelated = join(home, 'harnesses', 'worktrees', 'project', 'personal')git(source, 'worktree', 'add', '-q', '-b', 'super-tab/worker', tree); git(source, 'worktree', 'add', '-q', '-b', 'personal', unrelated)- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const start = vi.fn(), close = vi.fn()const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close }), capabilities: f.deps.capacity, start, now: () => 1 } as never)@@ -114,7 +115,7 @@ describe('consented Swarm clones', () => {mkdirSync(profile); writeFileSync(join(profile, 'config.toml'), '')Object.assign(f.row, { harnessIds: ['worker'] })vi.mocked(f.core.agents.all).mockReturnValue([{ agentId: 'worker', engine: 'codex', cwd: tree, codexHome: profile }] as never)- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => 1 } as never)await machine.tick()@@ -135,7 +136,7 @@ describe('consented Swarm clones', () => {const f = fixture(true), source = clone(join(f.oldRoot, 'project'))const config = join(process.env.CODEX_HOME!, 'config.toml')rmSync(config); mkdirSync(config)- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => 1 } as never)await machine.tick()@@ -165,7 +166,7 @@ describe('consented Swarm clones', () => {it('publishes observations before repair and does no trust work on a second successful tick', async () => {const f = fixture(true), source = clone(join(f.oldRoot, 'project'))let now = 1- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => now } as never)await machine.tick()@@ -190,7 +191,7 @@ describe('consented Swarm clones', () => {const f = fixture(true), source = clone(join(f.oldRoot, 'project')), file = join(process.env.CODEX_HOME!, 'config.toml')rmSync(file); mkdirSync(file)let now = 1- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => now } as never)await machine.tick()@@ -227,7 +228,7 @@ describe('consented Swarm clones', () => {const actual = await vi.importActual<typeof import('../lib/gitProject.js')>('../lib/gitProject.js')let unavailable = true, now = 1vi.mocked(readGitProject).mockImplementation(async (path, options) => path === failed && unavailable ? { error: 'GIT_UNAVAILABLE' } : actual.readGitProject(path, options))- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => now } as never)try {@@ -245,7 +246,7 @@ describe('consented Swarm clones', () => {const claude = join(process.env.CLAUDE_CONFIG_DIR!, '.claude.json'), codex = join(process.env.CODEX_HOME!, 'config.toml')writeFileSync(claude, 'invalid JSON'); rmSync(codex); mkdirSync(codex)let now = 1- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => now } as never)await machine.tick()@@ -261,7 +262,7 @@ describe('consented Swarm clones', () => {const f = fixture(true), source = clone(join(f.oldRoot, 'project'))Object.assign(f.row, { starts: [{ id: 'start', dispatched: true }] })let now = 1- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const start = vi.fn(async () => ({ ok: false }))const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start, now: () => now } as never)@@ -288,7 +289,7 @@ describe('consented Swarm clones', () => {const f = fixture(true), source = clone(join(f.oldRoot, 'project')), codex = join(process.env.CODEX_HOME!, 'config.toml')rmSync(codex)let now = 1- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => now } as never)try {@@ -307,7 +308,7 @@ describe('consented Swarm clones', () => {it('repairs a newly registered Codex profile and worktree before the next observation is due', async () => {const f = fixture(true), source = clone(join(f.oldRoot, 'project'))let now = 1- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => now } as never)try {@@ -329,7 +330,7 @@ describe('consented Swarm clones', () => {])('discovers a later clone after one-shot $failure failure (existing=$existing)', async ({ existing, failure }) => {const f = fixture(true), earlier = existing ? clone(join(f.oldRoot, 'earlier')) : undefinedlet now = 1- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => now } as never)try {@@ -353,7 +354,7 @@ describe('consented Swarm clones', () => {const f = fixture(true), source = join(f.oldRoot, 'project')mkdirSync(source, { recursive: true })let now = 1- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => now } as never)try {@@ -367,7 +368,7 @@ describe('consented Swarm clones', () => {const f = fixture(true), source = clone(join(f.oldRoot, 'project'))Object.assign(f.row, { starts: [{ id: 'start', dispatched: true }] })let now = 1- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const start = vi.fn(async () => ({ ok: false }))const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start, now: () => now } as never)@@ -387,7 +388,7 @@ describe('consented Swarm clones', () => {const original = `[projects.${JSON.stringify(source)}]\ntrust_level = "untrusted"\n`writeFileSync(codex, original)let now = 1- const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.endsWith('/pools') ? [f.row] : {})+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => path.includes('/changes') ? hostForm([], { pools: [f.row] }) : {})const machine = new ContributedMachines(f.core, f.core.daemon.machineId(), { backend,open: async () => ({ request: async () => ({}), close: vi.fn() }), capabilities: f.deps.capacity, start: vi.fn(), now: () => now } as never)try {diff --git a/cli/src/superTabs/contribution.spec.ts b/cli/src/superTabs/contribution.spec.tsindex e828d786b..8173304e3 100644--- a/cli/src/superTabs/contribution.spec.ts+++ b/cli/src/superTabs/contribution.spec.ts@@ -4,12 +4,13 @@ import { ContributionPreparations, prepareContribution, prepareTeamContributionimport { mkdtemp, rm, stat } from 'node:fs/promises'import { homedir, tmpdir } from 'node:os'import { join } from 'node:path'+import { swarmReply } from './fixtures/read/index.js'const GiB = 1024 ** 3function fixture() {const core = fakeCore()const state: Record<string, unknown> = { project: { machineId: core.daemon.machineId(), cwd: '/repo', repositoryUrl: 'https://github.com/example/project' } }- const backend = vi.fn(async () => ({ state }))+ const backend = vi.fn(async (_core: unknown, _method: string, path: string) => swarmReply(path, state))const close = vi.fn()const request = vi.fn(async () => ({ engines: [{ engine: 'claude', installed: true, signedIn: true },@@ -26,6 +27,12 @@ function fixture() {return { run, state, deps, core, request, close }}describe('one-field machine preparation', () => {+ // #1726: a whole Swarm is no longer read; its parts are, through the daemon's Swarm reads.+ it('reads the Swarm by parts, as the person', async () => {+ const f = fixture()+ await f.run()+ expect(f.deps.backend.mock.calls.map(c => [c[1], c[2]])).toEqual([['GET', '/api/super-tabs/tab/parts']])+ })it('contributes a swarm workspace without asking for a project or cloning one', async () => {const f = fixture()const dataDir = await mkdtemp(join(tmpdir(), 'harness-swarm-contribution-'))diff --git a/cli/src/superTabs/contribution.ts b/cli/src/superTabs/contribution.tsindex 52e0c48f8..85afa6f15 100644--- a/cli/src/superTabs/contribution.ts+++ b/cli/src/superTabs/contribution.ts@@ -7,22 +7,29 @@ import { mkdir } from 'node:fs/promises'import { readAuthSession } from '../lib/authSession.js'import { randomUUID } from 'node:crypto'import { repairSwarmCloneTrust, swarmCloneRoot, swarmCloneRoots } from './cloneTrust.js'+import { SwarmReads } from './swarmReads.js'type Json = Record<string, unknown>+interface ContributionDeps {+ backend: typeof backend; open: typeof openDaemon; prepare: typeof prepareProjectFolder; capacity: typeof readCapabilities; team?: () => boolean+ /** The daemon's Swarm reads (superTabs/swarmReads.ts); a one-off read of its own when none is given. */+ reads?: SwarmReads+}+const CONTRIBUTION_DEPS = { backend, open: openDaemon, prepare: prepareProjectFolder, capacity: readCapabilities }+/** Owner-only setup. Reuses the regular checkout preparation and engine probe;* it neither launches an agent nor grants the team access to the computer. */-export async function prepareContribution(core: CoreApi, input: Json, deps: {- backend: typeof backend; open: typeof openDaemon; prepare: typeof prepareProjectFolder; capacity: typeof readCapabilities; team?: () => boolean-} = { backend, open: openDaemon, prepare: prepareProjectFolder, capacity: readCapabilities }): Promise<Json> {+export async function prepareContribution(core: CoreApi, input: Json, given: Partial<ContributionDeps> = {}): Promise<Json> {+ const deps: ContributionDeps = { ...CONTRIBUTION_DEPS, ...given }if (!identifier(input.tabId)) throw new Error('Choose a Super Tab.')// A Mac's Harness Team account reads no Swarm as the person (backend lib/teamSession.ts). Its Mac's daemon adds it, as a// swarm workspace in its own clone root (host.ts joinTeams), so it needs no read ("One machine" in// docs/plans/2026-10-24-swarm-team-account.md).const team = (deps.team ?? (() => readAuthSession()?.kind === 'team'))()if (team && input.scope !== 'swarm') throw new Error('A Harness Team account joins a Swarm only as a swarm workspace.')- const answer = team ? {} : object(await deps.backend(core, 'GET', `/api/super-tabs/${input.tabId}`))- const state = object(answer.state), project = object(state.project)+ const state = team ? {} : (await (deps.reads ?? new SwarmReads(core, { backend: deps.backend })).read(input.tabId)).state+ const project = object(state.project)const machineId = core.daemon.machineId()const existing = (Array.isArray(state.machines) ? state.machines.map(object) : []).find(m => m.machineId === machineId)const swarm = input.scope === 'swarm' || Array.isArray(state.projects)diff --git a/cli/src/superTabs/contribution.windows.spec.ts b/cli/src/superTabs/contribution.windows.spec.tsindex 247f96194..8f3a1d955 100644--- a/cli/src/superTabs/contribution.windows.spec.ts+++ b/cli/src/superTabs/contribution.windows.spec.ts@@ -5,6 +5,7 @@ import { mkdir } from 'node:fs/promises'import { beforeEach, describe, expect, it, vi } from 'vitest'import { fakeCore } from '../testing/fakeCore.js'import { prepareContribution } from './contribution.js'+import { swarmReply } from './fixtures/read/index.js'vi.mock('node:path', async (original) => {const real = await original<typeof nodePath>()@@ -19,7 +20,7 @@ function fixture(existing?: string) {const request = vi.fn(async () => ({ engines: [{ engine: 'claude', installed: true, signedIn: true }] }))const close = vi.fn()const machines = existing ? [{ machineId: core.daemon.machineId(), cwd: existing }] : []- const deps = { backend: vi.fn(async () => ({ state: { machines } })), open: vi.fn(async () => ({ request, close })), prepare: vi.fn(),+ const deps = { backend: vi.fn(async (_core: unknown, _method: string, path: string) => swarmReply(path, { machines })), open: vi.fn(async () => ({ request, close })), prepare: vi.fn(),capacity: vi.fn(async () => ({ ok: true, resources: { memoryTotalBytes: 8 * 1024 ** 3, memoryUsedBytes: 0, projectDiskFreeBytes: 1e11 } })) }return { core, deps, close }}diff --git a/cli/src/superTabs/fixtures/read/changes-lead.json b/cli/src/superTabs/fixtures/read/changes-lead.jsonnew file mode 100644index 000000000..8b807484e--- /dev/null+++ b/cli/src/superTabs/fixtures/read/changes-lead.json@@ -0,0 +1,169 @@+{+ "format": 2,+ "reload": false,+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDc3Mzc1LCJlIjozfQ",+ "serverTime": 1793010107375,+ "lastChangedAt": 1793010106120,+ "epoch": 3,+ "head": null,+ "members": [],+ "agents": [+ {+ "key": "a00000000000000000000001",+ "version": 214000,+ "changedAt": 1793010000000,+ "data": {+ "id": "a00000000000000000000001",+ "name": "Overlap duplicate, same version: ignored"+ }+ }+ ],+ "groups": [+ {+ "key": "c00000000000000000000002",+ "version": 214040,+ "changedAt": 1793010106120,+ "data": {+ "id": "c00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "number": 2,+ "title": "Fixture work",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001",+ "a00000000000000000000002"+ ],+ "archived": false,+ "brief": "Goal:\nShip the fixture\n\nChanges:\nOne file\n\nConstraints:\nNone\n\nOwns:\n- cli/src/superTabs",+ "task": {+ "goal": "Ship the fixture",+ "changes": "One file",+ "constraints": "None",+ "owns": [+ "cli/src/superTabs"+ ]+ },+ "checks": [+ {+ "id": "c1",+ "description": "Tests pass",+ "independent": false,+ "evidence": null,+ "passedBy": null+ }+ ],+ "assignment": {+ "id": "w0000000000000000000001",+ "agentId": "a00000000000000000000002",+ "status": "review",+ "result": "Ready at abc123",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ },+ "recordingProgress": {+ "at": 1793010106120,+ "revision": 214041+ }+ },+ "lastMessageSequence": 214041,+ "pullRequestUrls": [],+ "messageSeq": 214041+ }+ },+ {+ "key": "c00000000000000000000003",+ "version": 214042,+ "changedAt": 1793010105000,+ "dormant": true+ }+ ],+ "machines": [+ {+ "key": "d00000000000000000000001",+ "version": 214050,+ "changedAt": 1793010105900,+ "data": {+ "machineId": "d00000000000000000000001",+ "name": "MacBookPro2021",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "generation": "pool-gen-1",+ "scope": "swarm",+ "engines": [+ "claude",+ "codex"+ ],+ "maxAgents": 4,+ "paused": false,+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "observation": {+ "generation": "pool-gen-1",+ "receivedAt": 1793010105000,+ "resources": {+ "cpuPercent": 30,+ "memoryUsedBytes": 9000000000,+ "memoryTotalBytes": 32000000000+ },+ "quotas": [+ {+ "engine": "claude",+ "known": true,+ "windows": []+ }+ ],+ "tools": {+ "git": true+ },+ "runningHarnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "stoppedHarnessIds": []+ }+ }+ }+ ],+ "starts": [+ {+ "key": "e00000000000000000000002",+ "version": 214043,+ "changedAt": 1793010105500,+ "deleted": true+ }+ ],+ "progress": [],+ "derived": {+ "agents": {+ "a00000000000000000000001": {+ "downSince": null,+ "limitedUntil": null,+ "workDecision": null,+ "roleId": null+ },+ "a00000000000000000000002": {+ "downSince": null,+ "limitedUntil": null,+ "workDecision": null,+ "roleId": null+ }+ },+ "machines": {+ "d00000000000000000000001": {+ "availableSlots": 3,+ "teamWork": {+ "allowed": true+ }+ }+ },+ "otherProjectsWork": []+ }+}diff --git a/cli/src/superTabs/fixtures/read/changes-reload.json b/cli/src/superTabs/fixtures/read/changes-reload.jsonnew file mode 100644index 000000000..fa5211f8b--- /dev/null+++ b/cli/src/superTabs/fixtures/read/changes-reload.json@@ -0,0 +1 @@+{ "reload": true }diff --git a/cli/src/superTabs/fixtures/read/host-changes.json b/cli/src/superTabs/fixtures/read/host-changes.jsonnew file mode 100644index 000000000..dc932e2a4--- /dev/null+++ b/cli/src/superTabs/fixtures/read/host-changes.json@@ -0,0 +1,170 @@+{+ "format": 2,+ "full": false,+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDc3Mzc1LCJlIjowfQ",+ "tabs": [+ {+ "tabId": "f1a5c0de0000000000000001",+ "lastChangedAt": 1793010106120,+ "roster": [+ {+ "tabId": "f1a5c0de0000000000000001",+ "tabName": "Fixture Swarm",+ "lastChangedAt": 1793010106120,+ "paused": false,+ "active": true,+ "attention": null,+ "agent": {+ "id": "a00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Lead",+ "displayName": "River",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "auto",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-lead",+ "startedSession": {+ "sessionId": "sess-lead",+ "createdAt": "2026-10-26T09:00:00.000Z",+ "creationId": "super-lead-start"+ }+ },+ "joinSwarm": false,+ "skillMode": "default",+ "lead": true,+ "leadsConversationId": "c00000000000000000000000",+ "stopRequested": false,+ "observers": [+ {+ "email": "[email protected]",+ "userId": "6a0000000000000000000002"+ }+ ]+ },+ {+ "tabId": "f1a5c0de0000000000000001",+ "tabName": "Fixture Swarm",+ "lastChangedAt": 1793010106120,+ "paused": false,+ "active": true,+ "attention": {+ "assignmentId": "w0000000000000000000001",+ "status": "needs_human",+ "result": "Which branch?"+ },+ "agent": {+ "id": "a00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Builder",+ "displayName": "Hugo",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-builder",+ "downSince": "2026-10-26T10:19:51.474Z",+ "limitedUntil": null,+ "workDecision": "awaiting"+ },+ "joinSwarm": false,+ "skillMode": "default",+ "lead": false,+ "leadsConversationId": "c00000000000000000000000",+ "stopRequested": false,+ "observers": [+ {+ "email": "[email protected]",+ "userId": "6a0000000000000000000002"+ }+ ]+ }+ ],+ "pool": {+ "tabId": "f1a5c0de0000000000000001",+ "paused": false,+ "machine": {+ "machineId": "d00000000000000000000001",+ "name": "MacBookPro2021",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "generation": "pool-gen-1",+ "scope": "swarm",+ "engines": [+ "claude",+ "codex"+ ],+ "maxAgents": 4,+ "paused": false,+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "observation": {+ "generation": "pool-gen-1",+ "receivedAt": 1793010099000,+ "resources": {+ "cpuPercent": 12,+ "memoryUsedBytes": 8000000000,+ "memoryTotalBytes": 32000000000+ },+ "quotas": [+ {+ "engine": "claude",+ "known": true,+ "windows": []+ }+ ],+ "tools": {+ "git": true+ },+ "runningHarnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "stoppedHarnessIds": []+ }+ },+ "starts": [],+ "localGrid": "swarm-0123456789ab",+ "reservations": [+ {+ "harnessId": "b00000000000000000000002",+ "generation": "res-gen-1"+ }+ ],+ "harnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "githubApp": true+ },+ "assignments": [+ {+ "tabId": "f1a5c0de0000000000000001",+ "assignmentId": "w0000000000000000000001",+ "harnessId": "b00000000000000000000002"+ }+ ],+ "etag": "etag-tab1-b"+ }+ ],+ "removedTabIds": [+ "f1a5c0de0000000000000009"+ ]+}diff --git a/cli/src/superTabs/fixtures/read/host-full.json b/cli/src/superTabs/fixtures/read/host-full.jsonnew file mode 100644index 000000000..ce19bc351--- /dev/null+++ b/cli/src/superTabs/fixtures/read/host-full.json@@ -0,0 +1,198 @@+{+ "format": 2,+ "full": true,+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjowfQ",+ "tabs": [+ {+ "tabId": "f1a5c0de0000000000000001",+ "lastChangedAt": 1793010101002,+ "roster": [+ {+ "tabId": "f1a5c0de0000000000000001",+ "tabName": "Fixture Swarm",+ "lastChangedAt": 1793010101002,+ "paused": false,+ "active": true,+ "attention": null,+ "agent": {+ "id": "a00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Lead",+ "displayName": "River",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "auto",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-lead",+ "startedSession": {+ "sessionId": "sess-lead",+ "createdAt": "2026-10-26T09:00:00.000Z",+ "creationId": "super-lead-start"+ }+ },+ "joinSwarm": false,+ "skillMode": "default",+ "lead": true,+ "leadsConversationId": "c00000000000000000000000",+ "stopRequested": false,+ "observers": [+ {+ "email": "[email protected]",+ "userId": "6a0000000000000000000002"+ }+ ]+ },+ {+ "tabId": "f1a5c0de0000000000000001",+ "tabName": "Fixture Swarm",+ "lastChangedAt": 1793010101002,+ "paused": false,+ "active": true,+ "attention": null,+ "agent": {+ "id": "a00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Builder",+ "displayName": "Hugo",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-builder",+ "downSince": "2026-10-26T10:19:51.474Z",+ "limitedUntil": null,+ "workDecision": "awaiting"+ },+ "joinSwarm": false,+ "skillMode": "default",+ "lead": false,+ "leadsConversationId": "c00000000000000000000000",+ "stopRequested": false,+ "observers": [+ {+ "email": "[email protected]",+ "userId": "6a0000000000000000000002"+ }+ ]+ }+ ],+ "pool": {+ "tabId": "f1a5c0de0000000000000001",+ "paused": false,+ "machine": {+ "machineId": "d00000000000000000000001",+ "name": "MacBookPro2021",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "generation": "pool-gen-1",+ "scope": "swarm",+ "engines": [+ "claude",+ "codex"+ ],+ "maxAgents": 4,+ "paused": false,+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "observation": {+ "generation": "pool-gen-1",+ "receivedAt": 1793010099000,+ "resources": {+ "cpuPercent": 12,+ "memoryUsedBytes": 8000000000,+ "memoryTotalBytes": 32000000000+ },+ "quotas": [+ {+ "engine": "claude",+ "known": true,+ "windows": []+ }+ ],+ "tools": {+ "git": true+ },+ "runningHarnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "stoppedHarnessIds": []+ }+ },+ "starts": [+ {+ "id": "e00000000000000000000002",+ "request": {+ "conversationId": "c00000000000000000000002",+ "machineId": "d00000000000000000000001",+ "engine": "claude",+ "name": "Reviewer",+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "worktree": true+ },+ "contributorId": "6a0000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "poolGeneration": "pool-gen-1",+ "dispatched": false,+ "creationId": "super-e00000000000000000000002"+ }+ ],+ "localGrid": "swarm-0123456789ab",+ "reservations": [+ {+ "harnessId": "b00000000000000000000002",+ "generation": "res-gen-1"+ }+ ],+ "harnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "githubApp": true+ },+ "assignments": [+ {+ "tabId": "f1a5c0de0000000000000001",+ "assignmentId": "w0000000000000000000001",+ "harnessId": "b00000000000000000000002"+ }+ ],+ "etag": "etag-tab1-a"+ },+ {+ "tabId": "f1a5c0de0000000000000009",+ "lastChangedAt": 1793000000000,+ "roster": [+ {+ "tabId": "f1a5c0de0000000000000009",+ "cleanup": {+ "machineId": "d00000000000000000000001",+ "removalId": "r0000000000000000000001"+ }+ }+ ],+ "pool": null,+ "assignments": [],+ "etag": "etag-tab9-a"+ }+ ],+ "removedTabIds": []+}diff --git a/cli/src/superTabs/fixtures/read/host-quiet.json b/cli/src/superTabs/fixtures/read/host-quiet.jsonnew file mode 100644index 000000000..daf98172c--- /dev/null+++ b/cli/src/superTabs/fixtures/read/host-quiet.json@@ -0,0 +1,7 @@+{+ "format": 2,+ "full": false,+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDgwMzc1LCJlIjowfQ",+ "tabs": [],+ "removedTabIds": []+}\ No newline at end of filediff --git a/cli/src/superTabs/fixtures/read/host-unchanged.json b/cli/src/superTabs/fixtures/read/host-unchanged.jsonnew file mode 100644index 000000000..ea543e735--- /dev/null+++ b/cli/src/superTabs/fixtures/read/host-unchanged.json@@ -0,0 +1,30 @@+{+ "format": 2,+ "full": false,+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDgwMzc1LCJlIjowfQ",+ "tabs": [+ {+ "tabId": "f1a5c0de0000000000000001",+ "etag": "etag-tab1-a",+ "lastChangedAt": 1793010101002,+ "unchanged": true+ },+ {+ "tabId": "f1a5c0de0000000000000009",+ "lastChangedAt": 1793010108000,+ "roster": [+ {+ "tabId": "f1a5c0de0000000000000009",+ "cleanup": {+ "machineId": "d00000000000000000000001",+ "removalId": "r0000000000000000000002"+ }+ }+ ],+ "pool": null,+ "assignments": [],+ "etag": "etag-tab9-b"+ }+ ],+ "removedTabIds": []+}diff --git a/cli/src/superTabs/fixtures/read/index.ts b/cli/src/superTabs/fixtures/read/index.tsnew file mode 100644index 000000000..6c1584363--- /dev/null+++ b/cli/src/superTabs/fixtures/read/index.ts@@ -0,0 +1,60 @@+/** Test-only: the recorded replies of the Swarm read API (design 2026-10-26-swarm-state-parts section 4), kept as JSON so+ * the integration group can replay them. Each call returns a fresh copy, so a test may change what it gets. */+import { readFileSync } from 'node:fs'+import { join } from 'node:path'++export type ReadFixture = 'parts-lead' | 'parts-builder' | 'changes-lead' | 'changes-reload' | 'legacy-tab-lead' | 'legacy-tab-builder'+ | 'host-full' | 'host-changes' | 'host-quiet' | 'host-unchanged' | 'list' | 'messages' | 'update-required' | 'status-lead' | 'status-builder'++const DIR = join(import.meta.dirname, '.')+export function readFixture<T = Record<string, unknown>>(name: ReadFixture): T {+ return JSON.parse(readFileSync(join(DIR, `${name}.json`), 'utf8')) as T+}+/** The fixture's tab, people, agents and machine, by role. */+export const FIXTURE = {+ tabId: 'f1a5c0de0000000000000001', removedTabId: 'f1a5c0de0000000000000009', machineId: 'd00000000000000000000001',+ ownerId: '6a0000000000000000000001', collaboratorId: '6a0000000000000000000002',+ leadId: 'a00000000000000000000001', builderId: 'a00000000000000000000002',+ leadHarness: 'b00000000000000000000001', builderHarness: 'b00000000000000000000002',+ leadsGroup: 'c00000000000000000000000', leadGroup: 'c00000000000000000000001', workGroup: 'c00000000000000000000002', doneGroup: 'c00000000000000000000003',+ startId: 'e00000000000000000000002', projectId: '5000000000000000000000aa',+} as const++/** A backend reply in the envelope `core.account.backend` returns. */+export interface BackendReply { status: number; body: Record<string, unknown> }+export const ok = (data: unknown): BackendReply => ({ status: 200, body: { success: true, data } })+export const refused = (status: number, code: string, message?: string): BackendReply =>+ ({ status, body: { success: false, error: { code, ...(message ? { message } : {}) } } })++type Json = Record<string, unknown>+const asList = (v: unknown): Json[] => Array.isArray(v) ? v as Json[] : []+/** Each fake reply's parts are newer than the last, as a server's would be after any change. */+let version = 1++/** A host form that lists `rows` (old roster rows) Swarm by Swarm, plus Swarms in `tabs` with no rows: an empty Swarm's rows+ * are replaced by none. Pools and assignments go with their Swarm. */+export function hostForm(rows: unknown, options: { tabs?: string[]; pools?: unknown; assignments?: unknown } = {}): Json {+ const roster = asList(rows), pools = asList(options.pools), assignments = asList(options.assignments)+ const ids = [...new Set([...roster, ...pools, ...assignments].map(row => String(row.tabId)).concat(options.tabs ?? []))]+ return { format: 2, full: true, cursor: `host-${++version}`, removedTabIds: [], tabs: ids.map(tabId => ({ tabId, lastChangedAt: version,+ roster: roster.filter(row => row.tabId === tabId), pool: pools.find(pool => pool.tabId === tabId) ?? null,+ assignments: assignments.filter(work => work.tabId === tabId) })) }+}++/** A first load of a Swarm whose state (in the old shape) is `state`: every record a part, nothing derived. */+export function partsOf(state: Json, options: { githubApp?: boolean; lastChangedAt?: number } = {}): Json {+ const v = ++version+ const part = (key: unknown, data: Json) => ({ key: String(key), version: v, changedAt: v, data })+ const { people, agents, conversations, machines, starts, otherProjectsWork, mentionsWaiting, ...head } = state+ return { format: 2, tabId: String(state.id ?? 'tab'), cursor: `tab-${v}`, serverTime: v, lastChangedAt: options.lastChangedAt ?? v, epoch: 1,+ ...(options.githubApp ? { githubApp: true } : {}),+ head: part('head', head), members: asList(people).map(p => part(p.id, p)), agents: asList(agents).map(a => part(a.id, a)),+ groups: asList(conversations).map((c, i) => part(c.id ?? `group-${i}`, c)), machines: asList(machines).map(m => part(m.machineId, m)),+ starts: asList(starts).map(s => part(s.id, s)), progress: [],+ derived: { ...(otherProjectsWork !== undefined ? { otherProjectsWork } : {}), ...(mentionsWaiting !== undefined ? { mentionsWaiting } : {}) } }+}++/** A fake Swarm read: a changes read asks for a reload, so every read is a first load of the state the test holds now (a+ * fake keeps no history to send tombstones from). */+export const swarmReply = (path: string, state: Json, options: { githubApp?: boolean; lastChangedAt?: number } = {}): Json =>+ /\/changes\?cursor=/.test(path) && !path.includes('/hosts/') ? { reload: true } : partsOf(state, options)diff --git a/cli/src/superTabs/fixtures/read/legacy-tab-builder.json b/cli/src/superTabs/fixtures/read/legacy-tab-builder.jsonnew file mode 100644index 000000000..6c708651c--- /dev/null+++ b/cli/src/superTabs/fixtures/read/legacy-tab-builder.json@@ -0,0 +1,270 @@+{+ "revision": 214033,+ "githubApp": true,+ "state": {+ "version": 1,+ "id": "f1a5c0de0000000000000001",+ "name": "Fixture Swarm",+ "ownerId": "6a0000000000000000000001",+ "environment": "prod",+ "paused": false,+ "projects": [+ {+ "id": "5000000000000000000000aa",+ "name": "Fixture project",+ "ownerId": "6a0000000000000000000001",+ "leadConversationId": "c00000000000000000000001",+ "visibility": "public",+ "members": [],+ "updateMinutes": 5,+ "skillMode": "default",+ "skillSet": "default",+ "progress": {+ "since": 1793009900000,+ "dirtyRevision": 214033,+ "summarizedRevision": 213800,+ "requestedRevision": 213800+ }+ }+ ],+ "rules": [],+ "invitations": [],+ "localModels": {+ "grid": "swarm-0123456789ab",+ "enabled": true+ },+ "people": [+ {+ "id": "6a0000000000000000000001",+ "email": "[email protected]",+ "role": "owner",+ "generation": "gen-owner"+ },+ {+ "id": "6a0000000000000000000002",+ "email": "[email protected]",+ "role": "collaborator",+ "generation": "gen-dev"+ }+ ],+ "agents": [+ {+ "id": "a00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Lead",+ "displayName": "River",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "auto",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-lead",+ "startedSession": {+ "sessionId": "sess-lead",+ "createdAt": "2026-10-26T09:00:00.000Z",+ "creationId": "super-lead-start"+ }+ },+ {+ "id": "a00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Builder",+ "displayName": "Hugo",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-builder",+ "downSince": "2026-10-26T10:19:51.474Z",+ "workDecision": "awaiting"+ }+ ],+ "conversations": [+ {+ "id": "c00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "title": "Fixture project",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "",+ "checks": [],+ "assignment": null,+ "lastMessageSequence": 214010,+ "pullRequestUrls": []+ },+ {+ "id": "c00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "number": 2,+ "title": "Fixture work",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001",+ "a00000000000000000000002"+ ],+ "archived": false,+ "brief": "Goal:\nShip the fixture\n\nChanges:\nOne file\n\nConstraints:\nNone\n\nOwns:\n- cli/src/superTabs",+ "task": {+ "goal": "Ship the fixture",+ "changes": "One file",+ "constraints": "None",+ "owns": [+ "cli/src/superTabs"+ ]+ },+ "checks": [+ {+ "id": "c1",+ "description": "Tests pass",+ "independent": false,+ "evidence": null,+ "passedBy": null+ }+ ],+ "assignment": {+ "id": "w0000000000000000000001",+ "agentId": "a00000000000000000000002",+ "status": "working",+ "result": null,+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ },+ "recordingProgress": {+ "at": 1793010104375,+ "revision": 214033+ }+ },+ "lastMessageSequence": 214033,+ "pullRequestUrls": []+ },+ {+ "id": "c00000000000000000000003",+ "projectId": "5000000000000000000000aa",+ "number": 3,+ "title": "Fixture done",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "Done work",+ "checks": [],+ "assignment": {+ "id": "w0000000000000000000002",+ "agentId": "a00000000000000000000002",+ "status": "done",+ "result": "Merged",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ }+ },+ "lastMessageSequence": 213990,+ "pullRequestUrls": [+ "https://github.com/example/repo/pull/7"+ ]+ }+ ],+ "machines": [+ {+ "machineId": "d00000000000000000000001",+ "name": "MacBookPro2021",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "generation": "pool-gen-1",+ "scope": "swarm",+ "engines": [+ "claude",+ "codex"+ ],+ "maxAgents": 4,+ "paused": false,+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "observation": {+ "generation": "pool-gen-1",+ "receivedAt": 1793010099000,+ "resources": {+ "cpuPercent": 12,+ "memoryUsedBytes": 8000000000,+ "memoryTotalBytes": 32000000000+ },+ "quotas": [+ {+ "engine": "claude",+ "known": true,+ "windows": []+ }+ ],+ "tools": {+ "git": true+ },+ "runningHarnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "stoppedHarnessIds": []+ },+ "availableSlots": 2,+ "teamWork": {+ "allowed": true+ }+ }+ ],+ "starts": [+ {+ "id": "e00000000000000000000002",+ "request": {+ "conversationId": "c00000000000000000000002",+ "machineId": "d00000000000000000000001",+ "engine": "claude",+ "name": "Reviewer",+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "worktree": true+ },+ "contributorId": "6a0000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "poolGeneration": "pool-gen-1",+ "dispatched": false,+ "creationId": "super-e00000000000000000000002"+ }+ ]+ }+}diff --git a/cli/src/superTabs/fixtures/read/legacy-tab-lead.json b/cli/src/superTabs/fixtures/read/legacy-tab-lead.jsonnew file mode 100644index 000000000..ba9825b5b--- /dev/null+++ b/cli/src/superTabs/fixtures/read/legacy-tab-lead.json@@ -0,0 +1,299 @@+{+ "revision": 214033,+ "githubApp": true,+ "state": {+ "version": 1,+ "id": "f1a5c0de0000000000000001",+ "name": "Fixture Swarm",+ "ownerId": "6a0000000000000000000001",+ "environment": "prod",+ "paused": false,+ "leadsConversationId": "c00000000000000000000000",+ "projects": [+ {+ "id": "5000000000000000000000aa",+ "name": "Fixture project",+ "ownerId": "6a0000000000000000000001",+ "leadConversationId": "c00000000000000000000001",+ "visibility": "public",+ "members": [],+ "updateMinutes": 5,+ "skillMode": "default",+ "skillSet": "default",+ "progress": {+ "since": 1793009900000,+ "dirtyRevision": 214033,+ "summarizedRevision": 213800,+ "requestedRevision": 213800+ }+ }+ ],+ "rules": [],+ "invitations": [],+ "localModels": {+ "grid": "swarm-0123456789ab",+ "enabled": true+ },+ "people": [+ {+ "id": "6a0000000000000000000001",+ "email": "[email protected]",+ "role": "owner",+ "generation": "gen-owner"+ },+ {+ "id": "6a0000000000000000000002",+ "email": "[email protected]",+ "role": "collaborator",+ "generation": "gen-dev"+ }+ ],+ "agents": [+ {+ "id": "a00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Lead",+ "displayName": "River",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "auto",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-lead",+ "startedSession": {+ "sessionId": "sess-lead",+ "createdAt": "2026-10-26T09:00:00.000Z",+ "creationId": "super-lead-start"+ }+ },+ {+ "id": "a00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Builder",+ "displayName": "Hugo",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-builder",+ "downSince": "2026-10-26T10:19:51.474Z",+ "workDecision": "awaiting"+ }+ ],+ "conversations": [+ {+ "id": "c00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "title": "Fixture project",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "",+ "checks": [],+ "assignment": null,+ "lastMessageSequence": 214010,+ "pullRequestUrls": []+ },+ {+ "id": "c00000000000000000000000",+ "kind": "leads",+ "title": "Leads",+ "leadId": null,+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "",+ "checks": [],+ "assignment": null,+ "lastMessageSequence": 213950,+ "pullRequestUrls": []+ },+ {+ "id": "c00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "number": 2,+ "title": "Fixture work",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001",+ "a00000000000000000000002"+ ],+ "archived": false,+ "brief": "Goal:\nShip the fixture\n\nChanges:\nOne file\n\nConstraints:\nNone\n\nOwns:\n- cli/src/superTabs",+ "task": {+ "goal": "Ship the fixture",+ "changes": "One file",+ "constraints": "None",+ "owns": [+ "cli/src/superTabs"+ ]+ },+ "checks": [+ {+ "id": "c1",+ "description": "Tests pass",+ "independent": false,+ "evidence": null,+ "passedBy": null+ }+ ],+ "assignment": {+ "id": "w0000000000000000000001",+ "agentId": "a00000000000000000000002",+ "status": "working",+ "result": null,+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ },+ "recordingProgress": {+ "at": 1793010104375,+ "revision": 214033+ }+ },+ "lastMessageSequence": 214033,+ "pullRequestUrls": []+ },+ {+ "id": "c00000000000000000000003",+ "projectId": "5000000000000000000000aa",+ "number": 3,+ "title": "Fixture done",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "Done work",+ "checks": [],+ "assignment": {+ "id": "w0000000000000000000002",+ "agentId": "a00000000000000000000002",+ "status": "done",+ "result": "Merged",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ }+ },+ "lastMessageSequence": 213990,+ "pullRequestUrls": [+ "https://github.com/example/repo/pull/7"+ ]+ }+ ],+ "machines": [+ {+ "machineId": "d00000000000000000000001",+ "name": "MacBookPro2021",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "generation": "pool-gen-1",+ "scope": "swarm",+ "engines": [+ "claude",+ "codex"+ ],+ "maxAgents": 4,+ "paused": false,+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "observation": {+ "generation": "pool-gen-1",+ "receivedAt": 1793010099000,+ "resources": {+ "cpuPercent": 12,+ "memoryUsedBytes": 8000000000,+ "memoryTotalBytes": 32000000000+ },+ "quotas": [+ {+ "engine": "claude",+ "known": true,+ "windows": []+ }+ ],+ "tools": {+ "git": true+ },+ "runningHarnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "stoppedHarnessIds": []+ },+ "availableSlots": 2,+ "teamWork": {+ "allowed": true+ }+ }+ ],+ "starts": [+ {+ "id": "e00000000000000000000002",+ "request": {+ "conversationId": "c00000000000000000000002",+ "machineId": "d00000000000000000000001",+ "engine": "claude",+ "name": "Reviewer",+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "worktree": true+ },+ "contributorId": "6a0000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "poolGeneration": "pool-gen-1",+ "dispatched": false,+ "creationId": "super-e00000000000000000000002"+ }+ ],+ "otherProjectsWork": [+ {+ "conversationId": "c0000000000000000000000f",+ "projectName": "Web",+ "title": "Web work",+ "owns": [+ "desktop/lib"+ ],+ "status": "working",+ "agentName": "Iris",+ "pr": null+ }+ ]+ }+}diff --git a/cli/src/superTabs/fixtures/read/list.json b/cli/src/superTabs/fixtures/read/list.jsonnew file mode 100644index 000000000..54af9ba6d--- /dev/null+++ b/cli/src/superTabs/fixtures/read/list.json@@ -0,0 +1,2 @@+{ "tabs": [ { "id": "f1a5c0de0000000000000001", "name": "Fixture Swarm", "ownerId": "6a0000000000000000000001", "paused": false,+ "lastChangedAt": 1793010101002 } ], "next": null }diff --git a/cli/src/superTabs/fixtures/read/messages.json b/cli/src/superTabs/fixtures/read/messages.jsonnew file mode 100644index 000000000..5080472ee--- /dev/null+++ b/cli/src/superTabs/fixtures/read/messages.json@@ -0,0 +1,11 @@+{ "messages": [+ { "id": "f00000000000000000000001", "tabId": "f1a5c0de0000000000000001", "conversationId": "c00000000000000000000001",+ "sequence": 214009, "author": { "kind": "person", "id": "6a0000000000000000000001", "name": "[email protected]" },+ "source": null, "text": "How is it going?", "attachments": null, "replyTo": null, "recipientIds": ["a00000000000000000000001"],+ "mentions": [], "createdAt": "2026-10-26T09:59:00.000Z", "deliveries": [] },+ { "id": "f00000000000000000000002", "tabId": "f1a5c0de0000000000000001", "conversationId": "c00000000000000000000001",+ "sequence": 214010, "author": { "kind": "agent", "id": "a00000000000000000000001", "name": "Lead", "displayName": "River" },+ "source": null, "text": "Work is in review.", "attachments": null, "replyTo": "f00000000000000000000001", "recipientIds": [],+ "mentions": [], "createdAt": "2026-10-26T10:00:00.000Z", "deliveries": [] }+ ],+ "next": { "sequence": 214009, "id": "f00000000000000000000001" } }diff --git a/cli/src/superTabs/fixtures/read/parts-builder.json b/cli/src/superTabs/fixtures/read/parts-builder.jsonnew file mode 100644index 000000000..777ce2490--- /dev/null+++ b/cli/src/superTabs/fixtures/read/parts-builder.json@@ -0,0 +1,355 @@+{+ "format": 2,+ "tabId": "f1a5c0de0000000000000001",+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjozfQ",+ "serverTime": 1793010104375,+ "lastChangedAt": 1793010101002,+ "epoch": 3,+ "githubApp": true,+ "head": {+ "key": "head",+ "version": 213990,+ "changedAt": 1793009000000,+ "data": {+ "version": 1,+ "id": "f1a5c0de0000000000000001",+ "name": "Fixture Swarm",+ "ownerId": "6a0000000000000000000001",+ "environment": "prod",+ "paused": false,+ "projects": [+ {+ "id": "5000000000000000000000aa",+ "name": "Fixture project",+ "ownerId": "6a0000000000000000000001",+ "leadConversationId": "c00000000000000000000001",+ "visibility": "public",+ "members": [],+ "updateMinutes": 5,+ "skillMode": "default",+ "skillSet": "default"+ }+ ],+ "rules": [],+ "invitations": [],+ "localModels": {+ "grid": "swarm-0123456789ab",+ "enabled": true+ }+ }+ },+ "members": [+ {+ "key": "6a0000000000000000000001",+ "version": 213990,+ "changedAt": 1793000000000,+ "data": {+ "id": "6a0000000000000000000001",+ "email": "[email protected]",+ "role": "owner",+ "generation": "gen-owner"+ }+ },+ {+ "key": "6a0000000000000000000002",+ "version": 213990,+ "changedAt": 1793000000000,+ "data": {+ "id": "6a0000000000000000000002",+ "email": "[email protected]",+ "role": "collaborator",+ "generation": "gen-dev"+ }+ }+ ],+ "agents": [+ {+ "key": "a00000000000000000000001",+ "version": 214000,+ "changedAt": 1793010000000,+ "data": {+ "id": "a00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Lead",+ "displayName": "River",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "auto",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-lead",+ "startedSession": {+ "sessionId": "sess-lead",+ "createdAt": "2026-10-26T09:00:00.000Z",+ "creationId": "super-lead-start"+ }+ }+ },+ {+ "key": "a00000000000000000000002",+ "version": 214010,+ "changedAt": 1793010090000,+ "data": {+ "id": "a00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Builder",+ "displayName": "Hugo",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-builder"+ }+ }+ ],+ "groups": [+ {+ "key": "c00000000000000000000001",+ "version": 214010,+ "changedAt": 1793010000000,+ "data": {+ "id": "c00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "title": "Fixture project",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "",+ "checks": [],+ "assignment": null,+ "lastMessageSequence": 214010,+ "pullRequestUrls": [],+ "messageSeq": 214010+ }+ },+ {+ "key": "c00000000000000000000002",+ "version": 214033,+ "changedAt": 1793010101002,+ "data": {+ "id": "c00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "number": 2,+ "title": "Fixture work",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001",+ "a00000000000000000000002"+ ],+ "archived": false,+ "brief": "Goal:\nShip the fixture\n\nChanges:\nOne file\n\nConstraints:\nNone\n\nOwns:\n- cli/src/superTabs",+ "task": {+ "goal": "Ship the fixture",+ "changes": "One file",+ "constraints": "None",+ "owns": [+ "cli/src/superTabs"+ ]+ },+ "checks": [+ {+ "id": "c1",+ "description": "Tests pass",+ "independent": false,+ "evidence": null,+ "passedBy": null+ }+ ],+ "assignment": {+ "id": "w0000000000000000000001",+ "agentId": "a00000000000000000000002",+ "status": "working",+ "result": null,+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ },+ "recordingProgress": {+ "at": 1793010104375,+ "revision": 214033+ }+ },+ "lastMessageSequence": 214033,+ "pullRequestUrls": [],+ "messageSeq": 214033+ }+ },+ {+ "key": "c00000000000000000000003",+ "version": 213995,+ "changedAt": 1793009500000,+ "data": {+ "id": "c00000000000000000000003",+ "projectId": "5000000000000000000000aa",+ "number": 3,+ "title": "Fixture done",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "Done work",+ "checks": [],+ "assignment": {+ "id": "w0000000000000000000002",+ "agentId": "a00000000000000000000002",+ "status": "done",+ "result": "Merged",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ }+ },+ "lastMessageSequence": 213990,+ "pullRequestUrls": [+ "https://github.com/example/repo/pull/7"+ ],+ "messageSeq": 213990+ }+ }+ ],+ "machines": [+ {+ "key": "d00000000000000000000001",+ "version": 214020,+ "changedAt": 1793010100000,+ "data": {+ "machineId": "d00000000000000000000001",+ "name": "MacBookPro2021",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "generation": "pool-gen-1",+ "scope": "swarm",+ "engines": [+ "claude",+ "codex"+ ],+ "maxAgents": 4,+ "paused": false,+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "observation": {+ "generation": "pool-gen-1",+ "receivedAt": 1793010099000,+ "resources": {+ "cpuPercent": 12,+ "memoryUsedBytes": 8000000000,+ "memoryTotalBytes": 32000000000+ },+ "quotas": [+ {+ "engine": "claude",+ "known": true,+ "windows": []+ }+ ],+ "tools": {+ "git": true+ },+ "runningHarnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "stoppedHarnessIds": []+ }+ }+ }+ ],+ "starts": [+ {+ "key": "e00000000000000000000002",+ "version": 214015,+ "changedAt": 1793010095000,+ "data": {+ "id": "e00000000000000000000002",+ "request": {+ "conversationId": "c00000000000000000000002",+ "machineId": "d00000000000000000000001",+ "engine": "claude",+ "name": "Reviewer",+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "worktree": true+ },+ "contributorId": "6a0000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "poolGeneration": "pool-gen-1",+ "dispatched": false,+ "creationId": "super-e00000000000000000000002"+ }+ }+ ],+ "progress": [+ {+ "key": "5000000000000000000000aa",+ "version": 214001,+ "changedAt": 1793009900000,+ "data": {+ "since": 1793009900000,+ "summarizedFloor": 213800,+ "summarized": {},+ "requestedFloor": 213800,+ "requested": {},+ "requestedAt": null+ }+ }+ ],+ "derived": {+ "agents": {+ "a00000000000000000000001": {+ "downSince": null,+ "limitedUntil": null,+ "workDecision": null,+ "roleId": null+ },+ "a00000000000000000000002": {+ "downSince": "2026-10-26T10:19:51.474Z",+ "limitedUntil": null,+ "workDecision": "awaiting",+ "roleId": null+ }+ },+ "machines": {+ "d00000000000000000000001": {+ "availableSlots": 2,+ "teamWork": {+ "allowed": true+ }+ }+ }+ }+}diff --git a/cli/src/superTabs/fixtures/read/parts-lead.json b/cli/src/superTabs/fixtures/read/parts-lead.jsonnew file mode 100644index 000000000..b1ed79e03--- /dev/null+++ b/cli/src/superTabs/fixtures/read/parts-lead.json@@ -0,0 +1,390 @@+{+ "format": 2,+ "tabId": "f1a5c0de0000000000000001",+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjozfQ",+ "serverTime": 1793010104375,+ "lastChangedAt": 1793010101002,+ "epoch": 3,+ "githubApp": true,+ "head": {+ "key": "head",+ "version": 213990,+ "changedAt": 1793009000000,+ "data": {+ "version": 1,+ "id": "f1a5c0de0000000000000001",+ "name": "Fixture Swarm",+ "ownerId": "6a0000000000000000000001",+ "environment": "prod",+ "paused": false,+ "leadsConversationId": "c00000000000000000000000",+ "projects": [+ {+ "id": "5000000000000000000000aa",+ "name": "Fixture project",+ "ownerId": "6a0000000000000000000001",+ "leadConversationId": "c00000000000000000000001",+ "visibility": "public",+ "members": [],+ "updateMinutes": 5,+ "skillMode": "default",+ "skillSet": "default"+ }+ ],+ "rules": [],+ "invitations": [],+ "localModels": {+ "grid": "swarm-0123456789ab",+ "enabled": true+ }+ }+ },+ "members": [+ {+ "key": "6a0000000000000000000001",+ "version": 213990,+ "changedAt": 1793000000000,+ "data": {+ "id": "6a0000000000000000000001",+ "email": "[email protected]",+ "role": "owner",+ "generation": "gen-owner"+ }+ },+ {+ "key": "6a0000000000000000000002",+ "version": 213990,+ "changedAt": 1793000000000,+ "data": {+ "id": "6a0000000000000000000002",+ "email": "[email protected]",+ "role": "collaborator",+ "generation": "gen-dev"+ }+ }+ ],+ "agents": [+ {+ "key": "a00000000000000000000001",+ "version": 214000,+ "changedAt": 1793010000000,+ "data": {+ "id": "a00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Lead",+ "displayName": "River",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "auto",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-lead",+ "startedSession": {+ "sessionId": "sess-lead",+ "createdAt": "2026-10-26T09:00:00.000Z",+ "creationId": "super-lead-start"+ }+ }+ },+ {+ "key": "a00000000000000000000002",+ "version": 214010,+ "changedAt": 1793010090000,+ "data": {+ "id": "a00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Builder",+ "displayName": "Hugo",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-builder"+ }+ }+ ],+ "groups": [+ {+ "key": "c00000000000000000000001",+ "version": 214010,+ "changedAt": 1793010000000,+ "data": {+ "id": "c00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "title": "Fixture project",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "",+ "checks": [],+ "assignment": null,+ "lastMessageSequence": 214010,+ "pullRequestUrls": [],+ "messageSeq": 214010+ }+ },+ {+ "key": "c00000000000000000000000",+ "version": 213990,+ "changedAt": 1793009000000,+ "data": {+ "id": "c00000000000000000000000",+ "kind": "leads",+ "title": "Leads",+ "leadId": null,+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "",+ "checks": [],+ "assignment": null,+ "lastMessageSequence": 213950,+ "pullRequestUrls": [],+ "messageSeq": 213950+ }+ },+ {+ "key": "c00000000000000000000002",+ "version": 214033,+ "changedAt": 1793010101002,+ "data": {+ "id": "c00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "number": 2,+ "title": "Fixture work",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001",+ "a00000000000000000000002"+ ],+ "archived": false,+ "brief": "Goal:\nShip the fixture\n\nChanges:\nOne file\n\nConstraints:\nNone\n\nOwns:\n- cli/src/superTabs",+ "task": {+ "goal": "Ship the fixture",+ "changes": "One file",+ "constraints": "None",+ "owns": [+ "cli/src/superTabs"+ ]+ },+ "checks": [+ {+ "id": "c1",+ "description": "Tests pass",+ "independent": false,+ "evidence": null,+ "passedBy": null+ }+ ],+ "assignment": {+ "id": "w0000000000000000000001",+ "agentId": "a00000000000000000000002",+ "status": "working",+ "result": null,+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ },+ "recordingProgress": {+ "at": 1793010104375,+ "revision": 214033+ }+ },+ "lastMessageSequence": 214033,+ "pullRequestUrls": [],+ "messageSeq": 214033+ }+ },+ {+ "key": "c00000000000000000000003",+ "version": 213995,+ "changedAt": 1793009500000,+ "data": {+ "id": "c00000000000000000000003",+ "projectId": "5000000000000000000000aa",+ "number": 3,+ "title": "Fixture done",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "Done work",+ "checks": [],+ "assignment": {+ "id": "w0000000000000000000002",+ "agentId": "a00000000000000000000002",+ "status": "done",+ "result": "Merged",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ }+ },+ "lastMessageSequence": 213990,+ "pullRequestUrls": [+ "https://github.com/example/repo/pull/7"+ ],+ "messageSeq": 213990+ }+ }+ ],+ "machines": [+ {+ "key": "d00000000000000000000001",+ "version": 214020,+ "changedAt": 1793010100000,+ "data": {+ "machineId": "d00000000000000000000001",+ "name": "MacBookPro2021",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "generation": "pool-gen-1",+ "scope": "swarm",+ "engines": [+ "claude",+ "codex"+ ],+ "maxAgents": 4,+ "paused": false,+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "observation": {+ "generation": "pool-gen-1",+ "receivedAt": 1793010099000,+ "resources": {+ "cpuPercent": 12,+ "memoryUsedBytes": 8000000000,+ "memoryTotalBytes": 32000000000+ },+ "quotas": [+ {+ "engine": "claude",+ "known": true,+ "windows": []+ }+ ],+ "tools": {+ "git": true+ },+ "runningHarnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "stoppedHarnessIds": []+ }+ }+ }+ ],+ "starts": [+ {+ "key": "e00000000000000000000002",+ "version": 214015,+ "changedAt": 1793010095000,+ "data": {+ "id": "e00000000000000000000002",+ "request": {+ "conversationId": "c00000000000000000000002",+ "machineId": "d00000000000000000000001",+ "engine": "claude",+ "name": "Reviewer",+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "worktree": true+ },+ "contributorId": "6a0000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "poolGeneration": "pool-gen-1",+ "dispatched": false,+ "creationId": "super-e00000000000000000000002"+ }+ }+ ],+ "progress": [+ {+ "key": "5000000000000000000000aa",+ "version": 214001,+ "changedAt": 1793009900000,+ "data": {+ "since": 1793009900000,+ "summarizedFloor": 213800,+ "summarized": {},+ "requestedFloor": 213800,+ "requested": {},+ "requestedAt": null+ }+ }+ ],+ "derived": {+ "agents": {+ "a00000000000000000000001": {+ "downSince": null,+ "limitedUntil": null,+ "workDecision": null,+ "roleId": null+ },+ "a00000000000000000000002": {+ "downSince": "2026-10-26T10:19:51.474Z",+ "limitedUntil": null,+ "workDecision": "awaiting",+ "roleId": null+ }+ },+ "machines": {+ "d00000000000000000000001": {+ "availableSlots": 2,+ "teamWork": {+ "allowed": true+ }+ }+ },+ "otherProjectsWork": [+ {+ "conversationId": "c0000000000000000000000f",+ "projectName": "Web",+ "title": "Web work",+ "owns": [+ "desktop/lib"+ ],+ "status": "working",+ "agentName": "Iris",+ "pr": null+ }+ ]+ }+}diff --git a/cli/src/superTabs/fixtures/read/status-builder.json b/cli/src/superTabs/fixtures/read/status-builder.jsonnew file mode 100644index 000000000..dab1b17ee--- /dev/null+++ b/cli/src/superTabs/fixtures/read/status-builder.json@@ -0,0 +1,273 @@+{+ "ok": true,+ "value": {+ "revision": 214033,+ "githubApp": true,+ "state": {+ "version": 1,+ "id": "f1a5c0de0000000000000001",+ "name": "Fixture Swarm",+ "ownerId": "6a0000000000000000000001",+ "environment": "prod",+ "paused": false,+ "projects": [+ {+ "id": "5000000000000000000000aa",+ "name": "Fixture project",+ "ownerId": "6a0000000000000000000001",+ "leadConversationId": "c00000000000000000000001",+ "visibility": "public",+ "members": [],+ "updateMinutes": 5,+ "skillMode": "default",+ "skillSet": "default",+ "progress": {+ "since": 1793009900000,+ "dirtyRevision": 214033,+ "summarizedRevision": 213800,+ "requestedRevision": 213800+ }+ }+ ],+ "rules": [],+ "invitations": [],+ "localModels": {+ "grid": "swarm-0123456789ab",+ "enabled": true+ },+ "people": [+ {+ "id": "6a0000000000000000000001",+ "email": "[email protected]",+ "role": "owner",+ "generation": "gen-owner"+ },+ {+ "id": "6a0000000000000000000002",+ "email": "[email protected]",+ "role": "collaborator",+ "generation": "gen-dev"+ }+ ],+ "agents": [+ {+ "id": "a00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Lead",+ "displayName": "River",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "auto",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-lead",+ "startedSession": {+ "sessionId": "sess-lead",+ "createdAt": "2026-10-26T09:00:00.000Z",+ "creationId": "super-lead-start"+ }+ },+ {+ "id": "a00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Builder",+ "displayName": "Hugo",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-builder",+ "downSince": "2026-10-26T10:19:51.474Z",+ "workDecision": "awaiting"+ }+ ],+ "conversations": [+ {+ "id": "c00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "title": "Fixture project",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "",+ "checks": [],+ "assignment": null,+ "lastMessageSequence": 214010,+ "pullRequestUrls": []+ },+ {+ "id": "c00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "number": 2,+ "title": "Fixture work",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001",+ "a00000000000000000000002"+ ],+ "archived": false,+ "brief": "Goal:\nShip the fixture\n\nChanges:\nOne file\n\nConstraints:\nNone\n\nOwns:\n- cli/src/superTabs",+ "task": {+ "goal": "Ship the fixture",+ "changes": "One file",+ "constraints": "None",+ "owns": [+ "cli/src/superTabs"+ ]+ },+ "checks": [+ {+ "id": "c1",+ "description": "Tests pass",+ "independent": false,+ "evidence": null,+ "passedBy": null+ }+ ],+ "assignment": {+ "id": "w0000000000000000000001",+ "agentId": "a00000000000000000000002",+ "status": "working",+ "result": null,+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ },+ "recordingProgress": {+ "at": 1793010104375,+ "revision": 214033+ }+ },+ "lastMessageSequence": 214033,+ "pullRequestUrls": []+ },+ {+ "id": "c00000000000000000000003",+ "projectId": "5000000000000000000000aa",+ "number": 3,+ "title": "Fixture done",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "Done work",+ "checks": [],+ "assignment": {+ "id": "w0000000000000000000002",+ "agentId": "a00000000000000000000002",+ "status": "done",+ "result": "Merged",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ }+ },+ "lastMessageSequence": 213990,+ "pullRequestUrls": [+ "https://github.com/example/repo/pull/7"+ ]+ }+ ],+ "machines": [+ {+ "machineId": "d00000000000000000000001",+ "name": "MacBookPro2021",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "generation": "pool-gen-1",+ "scope": "swarm",+ "engines": [+ "claude",+ "codex"+ ],+ "maxAgents": 4,+ "paused": false,+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "observation": {+ "generation": "pool-gen-1",+ "receivedAt": 1793010099000,+ "resources": {+ "cpuPercent": 12,+ "memoryUsedBytes": 8000000000,+ "memoryTotalBytes": 32000000000+ },+ "quotas": [+ {+ "engine": "claude",+ "known": true,+ "windows": []+ }+ ],+ "tools": {+ "git": true+ },+ "runningHarnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "stoppedHarnessIds": []+ },+ "availableSlots": 2,+ "teamWork": {+ "allowed": true+ }+ }+ ],+ "starts": [+ {+ "id": "e00000000000000000000002",+ "request": {+ "conversationId": "c00000000000000000000002",+ "machineId": "d00000000000000000000001",+ "engine": "claude",+ "name": "Reviewer",+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "worktree": true+ },+ "contributorId": "6a0000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "poolGeneration": "pool-gen-1",+ "dispatched": false,+ "creationId": "super-e00000000000000000000002"+ }+ ]+ }+ }+}diff --git a/cli/src/superTabs/fixtures/read/status-lead.json b/cli/src/superTabs/fixtures/read/status-lead.jsonnew file mode 100644index 000000000..52832b472--- /dev/null+++ b/cli/src/superTabs/fixtures/read/status-lead.json@@ -0,0 +1,302 @@+{+ "ok": true,+ "value": {+ "revision": 214033,+ "githubApp": true,+ "state": {+ "version": 1,+ "id": "f1a5c0de0000000000000001",+ "name": "Fixture Swarm",+ "ownerId": "6a0000000000000000000001",+ "environment": "prod",+ "paused": false,+ "projects": [+ {+ "id": "5000000000000000000000aa",+ "name": "Fixture project",+ "ownerId": "6a0000000000000000000001",+ "leadConversationId": "c00000000000000000000001",+ "visibility": "public",+ "members": [],+ "updateMinutes": 5,+ "skillMode": "default",+ "skillSet": "default",+ "progress": {+ "since": 1793009900000,+ "dirtyRevision": 214033,+ "summarizedRevision": 213800,+ "requestedRevision": 213800+ }+ }+ ],+ "rules": [],+ "invitations": [],+ "localModels": {+ "grid": "swarm-0123456789ab",+ "enabled": true+ },+ "people": [+ {+ "id": "6a0000000000000000000001",+ "email": "[email protected]",+ "role": "owner",+ "generation": "gen-owner"+ },+ {+ "id": "6a0000000000000000000002",+ "email": "[email protected]",+ "role": "collaborator",+ "generation": "gen-dev"+ }+ ],+ "agents": [+ {+ "id": "a00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Lead",+ "displayName": "River",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "auto",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-lead",+ "startedSession": {+ "sessionId": "sess-lead",+ "createdAt": "2026-10-26T09:00:00.000Z",+ "creationId": "super-lead-start"+ }+ },+ {+ "id": "a00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "hostGrant": null,+ "name": "Builder",+ "displayName": "Hugo",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "configurationVersion": "cv-builder",+ "downSince": "2026-10-26T10:19:51.474Z",+ "workDecision": "awaiting"+ }+ ],+ "conversations": [+ {+ "id": "c00000000000000000000001",+ "projectId": "5000000000000000000000aa",+ "title": "Fixture project",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "",+ "checks": [],+ "assignment": null,+ "lastMessageSequence": 214010,+ "pullRequestUrls": []+ },+ {+ "id": "c00000000000000000000000",+ "kind": "leads",+ "title": "Leads",+ "leadId": null,+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "",+ "checks": [],+ "assignment": null,+ "lastMessageSequence": 213950,+ "pullRequestUrls": []+ },+ {+ "id": "c00000000000000000000002",+ "projectId": "5000000000000000000000aa",+ "number": 2,+ "title": "Fixture work",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001",+ "a00000000000000000000002"+ ],+ "archived": false,+ "brief": "Goal:\nShip the fixture\n\nChanges:\nOne file\n\nConstraints:\nNone\n\nOwns:\n- cli/src/superTabs",+ "task": {+ "goal": "Ship the fixture",+ "changes": "One file",+ "constraints": "None",+ "owns": [+ "cli/src/superTabs"+ ]+ },+ "checks": [+ {+ "id": "c1",+ "description": "Tests pass",+ "independent": false,+ "evidence": null,+ "passedBy": null+ }+ ],+ "assignment": {+ "id": "w0000000000000000000001",+ "agentId": "a00000000000000000000002",+ "status": "working",+ "result": null,+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ },+ "recordingProgress": {+ "at": 1793010104375,+ "revision": 214033+ }+ },+ "lastMessageSequence": 214033,+ "pullRequestUrls": []+ },+ {+ "id": "c00000000000000000000003",+ "projectId": "5000000000000000000000aa",+ "number": 3,+ "title": "Fixture done",+ "leadId": "a00000000000000000000001",+ "agentIds": [+ "a00000000000000000000001"+ ],+ "archived": false,+ "brief": "Done work",+ "checks": [],+ "assignment": {+ "id": "w0000000000000000000002",+ "agentId": "a00000000000000000000002",+ "status": "done",+ "result": "Merged",+ "configuration": {+ "engine": "claude",+ "model": "opus",+ "effort": "high",+ "contextWindow": null,+ "engineVersion": null+ },+ "execution": {+ "machineId": "d00000000000000000000001",+ "harnessId": "b00000000000000000000002",+ "machineOwnerId": "6a0000000000000000000001"+ }+ },+ "lastMessageSequence": 213990,+ "pullRequestUrls": [+ "https://github.com/example/repo/pull/7"+ ]+ }+ ],+ "machines": [+ {+ "machineId": "d00000000000000000000001",+ "name": "MacBookPro2021",+ "contributorId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "generation": "pool-gen-1",+ "scope": "swarm",+ "engines": [+ "claude",+ "codex"+ ],+ "maxAgents": 4,+ "paused": false,+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "observation": {+ "generation": "pool-gen-1",+ "receivedAt": 1793010099000,+ "resources": {+ "cpuPercent": 12,+ "memoryUsedBytes": 8000000000,+ "memoryTotalBytes": 32000000000+ },+ "quotas": [+ {+ "engine": "claude",+ "known": true,+ "windows": []+ }+ ],+ "tools": {+ "git": true+ },+ "runningHarnessIds": [+ "b00000000000000000000001",+ "b00000000000000000000002"+ ],+ "stoppedHarnessIds": []+ },+ "availableSlots": 2,+ "teamWork": {+ "allowed": true+ }+ }+ ],+ "starts": [+ {+ "id": "e00000000000000000000002",+ "request": {+ "conversationId": "c00000000000000000000002",+ "machineId": "d00000000000000000000001",+ "engine": "claude",+ "name": "Reviewer",+ "cwd": "/Users/owner/Harness/swarms/f1a5",+ "worktree": true+ },+ "contributorId": "6a0000000000000000000001",+ "machineOwnerId": "6a0000000000000000000001",+ "membershipGeneration": "gen-owner",+ "poolGeneration": "pool-gen-1",+ "dispatched": false,+ "creationId": "super-e00000000000000000000002"+ }+ ],+ "leadsConversationId": "c00000000000000000000000",+ "otherProjectsWork": [+ {+ "conversationId": "c0000000000000000000000f",+ "projectName": "Web",+ "title": "Web work",+ "owns": [+ "desktop/lib"+ ],+ "status": "working",+ "agentName": "Iris",+ "pr": null+ }+ ]+ }+ }+}diff --git a/cli/src/superTabs/fixtures/read/update-required.json b/cli/src/superTabs/fixtures/read/update-required.jsonnew file mode 100644index 000000000..7f8494812--- /dev/null+++ b/cli/src/superTabs/fixtures/read/update-required.json@@ -0,0 +1 @@+{ "success": false, "error": { "code": "UPDATE_REQUIRED", "message": "Update Harness to keep using this Swarm." } }diff --git a/cli/src/superTabs/fixtures/screens/claude-fable-limit.txt b/cli/src/superTabs/fixtures/screens/claude-fable-limit.txtnew file mode 100644index 000000000..f664a5d6c--- /dev/null+++ b/cli/src/superTabs/fixtures/screens/claude-fable-limit.txt@@ -0,0 +1,11 @@+⏺ Bash(npx vitest run src/superTabs)+ ⎿ Test Files 35 passed (35)+ Tests 893 passed (893)++⏺ All green. Committing step 1 now.+ ⎿ You've reached your Fable limit. Switch to another model to continue.++────────────────────────────────────────────────────────────────────────────────+❯+────────────────────────────────────────────────────────────────────────────────+ ⏵⏵ bypass permissions on (shift+tab to cycle)diff --git a/cli/src/superTabs/fixtures/screens/claude-opus-limit.txt b/cli/src/superTabs/fixtures/screens/claude-opus-limit.txtnew file mode 100644index 000000000..c91ec0194--- /dev/null+++ b/cli/src/superTabs/fixtures/screens/claude-opus-limit.txt@@ -0,0 +1,12 @@+⏺ Bash(npx vitest run src/superTabs)+ ⎿ Test Files 35 passed (35)+ Tests 893 passed (893)++⏺ All green. Committing step 1 now.+ ⎿ You've hit your Opus limit · resets Oct 30, 9am (Asia/Saigon)+ /upgrade to increase your usage limit.++────────────────────────────────────────────────────────────────────────────────+❯+────────────────────────────────────────────────────────────────────────────────+ ⏵⏵ bypass permissions on (shift+tab to cycle)diff --git a/cli/src/superTabs/fixtures/screens/claude-session-limit.txt b/cli/src/superTabs/fixtures/screens/claude-session-limit.txtnew file mode 100644index 000000000..f89381eb6--- /dev/null+++ b/cli/src/superTabs/fixtures/screens/claude-session-limit.txt@@ -0,0 +1,12 @@+⏺ Bash(npx vitest run src/superTabs)+ ⎿ Test Files 35 passed (35)+ Tests 893 passed (893)++⏺ All green. Committing step 1 now.+ ⎿ You've hit your session limit · resets 3pm (Asia/Saigon)+ /upgrade to increase your usage limit.++────────────────────────────────────────────────────────────────────────────────+❯+────────────────────────────────────────────────────────────────────────────────+ ⏵⏵ bypass permissions on (shift+tab to cycle)diff --git a/cli/src/superTabs/fixtures/screens/claude-weekly-limit.txt b/cli/src/superTabs/fixtures/screens/claude-weekly-limit.txtnew file mode 100644index 000000000..8af7f6409--- /dev/null+++ b/cli/src/superTabs/fixtures/screens/claude-weekly-limit.txt@@ -0,0 +1,12 @@+⏺ Bash(npx vitest run src/superTabs)+ ⎿ Test Files 35 passed (35)+ Tests 893 passed (893)++⏺ All green. Committing step 1 now.+ ⎿ You've hit your weekly limit · resets Oct 30, 9am (Asia/Saigon)+ /upgrade to increase your usage limit.++────────────────────────────────────────────────────────────────────────────────+❯+────────────────────────────────────────────────────────────────────────────────+ ⏵⏵ bypass permissions on (shift+tab to cycle)diff --git a/cli/src/superTabs/fixtures/screens/claude-working-a.txt b/cli/src/superTabs/fixtures/screens/claude-working-a.txtnew file mode 100644index 000000000..20337c81b--- /dev/null+++ b/cli/src/superTabs/fixtures/screens/claude-working-a.txt@@ -0,0 +1,15 @@+⏺ I'll read how the host builds its machine report first.++⏺ Read(cli/src/superTabs/machines.ts)+ ⎿ Read 507 lines++⏺ Bash(npx vitest run src/superTabs/machines.spec.ts)+ ⎿ Running…++✻ Pondering… (2m 14s · ↓ 3.1k tokens · esc to interrupt)+ ⎿ Tip: Use /memory to edit what Claude remembers about this project++────────────────────────────────────────────────────────────────────────────────+❯+────────────────────────────────────────────────────────────────────────────────+ ⏵⏵ bypass permissions on (shift+tab to cycle)diff --git a/cli/src/superTabs/fixtures/screens/claude-working-b.txt b/cli/src/superTabs/fixtures/screens/claude-working-b.txtnew file mode 100644index 000000000..e4b0fe2cd--- /dev/null+++ b/cli/src/superTabs/fixtures/screens/claude-working-b.txt@@ -0,0 +1,15 @@+⏺ I'll read how the host builds its machine report first.++⏺ Read(cli/src/superTabs/machines.ts)+ ⎿ Read 507 lines++⏺ Bash(npx vitest run src/superTabs/machines.spec.ts)+ ⎿ Running…++✶ Pondering… (2m 29s · ↓ 3.4k tokens · esc to interrupt)+ ⎿ Tip: Press Shift+Tab to cycle between permission modes++────────────────────────────────────────────────────────────────────────────────+❯+────────────────────────────────────────────────────────────────────────────────+ ⏵⏵ bypass permissions on (shift+tab to cycle)diff --git a/cli/src/superTabs/fixtures/screens/codex-model-limit.txt b/cli/src/superTabs/fixtures/screens/codex-model-limit.txtnew file mode 100644index 000000000..fbc246f3e--- /dev/null+++ b/cli/src/superTabs/fixtures/screens/codex-model-limit.txt@@ -0,0 +1,11 @@+• Ran npx vitest run src/superTabs/terminal.spec.ts+ └ Test Files 1 passed (1)+ Tests 33 passed (33)++■ You've hit your usage limit for gpt-5.5-codex. Switch to another model now, or try+again at 4:05 PM.+++› Ask Codex to do anything++ 100% context left · ? for shortcutsdiff --git a/cli/src/superTabs/fixtures/screens/codex-usage-limit.txt b/cli/src/superTabs/fixtures/screens/codex-usage-limit.txtnew file mode 100644index 000000000..0dfeb5593--- /dev/null+++ b/cli/src/superTabs/fixtures/screens/codex-usage-limit.txt@@ -0,0 +1,12 @@+• Ran npx vitest run src/superTabs/terminal.spec.ts+ └ Test Files 1 passed (1)+ Tests 33 passed (33)++■ You've hit your usage limit. Upgrade to Pro (https://chatgpt.com/explore/pro), visit+https://chatgpt.com/codex/settings/usage to purchase more credits or try again at Oct+27th, 2026 3:05 PM.+++› Ask Codex to do anything++ 100% context left · ? for shortcutsdiff --git a/cli/src/superTabs/fixtures/screens/codex-working-a.txt b/cli/src/superTabs/fixtures/screens/codex-working-a.txtnew file mode 100644index 000000000..2db1f11d9--- /dev/null+++ b/cli/src/superTabs/fixtures/screens/codex-working-a.txt@@ -0,0 +1,13 @@+• Explored+ └ Read machines.ts, terminal.ts++• Ran npx vitest run src/superTabs/terminal.spec.ts+ └ Test Files 1 passed (1)+ Tests 28 passed (28)++• Working (1m 05s • esc to interrupt)+++› Ask Codex to do anything++ 100% context left · ? for shortcutsdiff --git a/cli/src/superTabs/fixtures/screens/codex-working-b.txt b/cli/src/superTabs/fixtures/screens/codex-working-b.txtnew file mode 100644index 000000000..81f5d2a1f--- /dev/null+++ b/cli/src/superTabs/fixtures/screens/codex-working-b.txt@@ -0,0 +1,13 @@+• Explored+ └ Read machines.ts, terminal.ts++• Ran npx vitest run src/superTabs/terminal.spec.ts+ └ Test Files 1 passed (1)+ Tests 28 passed (28)++◦ Working (1m 20s • esc to interrupt)+++› Ask Codex to do anything++ 100% context left · ? for shortcutsdiff --git a/cli/src/superTabs/github.spec.ts b/cli/src/superTabs/github.spec.tsindex 31d51e574..957eb52a6 100644--- a/cli/src/superTabs/github.spec.ts+++ b/cli/src/superTabs/github.spec.ts@@ -6,6 +6,10 @@ import { fakeCore } from '../testing/fakeCore.js'import type { RegisteredSession } from '../lib/registry.js'import { swarmGitHubSessionDir } from '../lib/swarmGitHub.js'import { GitHubTokenRefresher, githubToken, RENEW_BELOW_MS } from './github.js'+import { hostForm } from './fixtures/read/index.js'+import { HostFeed } from './hostFeed.js'+import { SwarmReads } from './swarmReads.js'+import type { CoreApi } from '../core/api.js'const root = mkdtempSync(join(tmpdir(), 'super-tab-github-'))afterAll(() => rmSync(root, { recursive: true, force: true }))@@ -18,6 +22,9 @@ const issued = (token: string, expiresAt = '2026-10-24T13:00:00.000Z') => ok({ ttrailers: ['Co-authored-by: Ada <[email protected]>', 'Harness-Agent: Atlas'] })const row = (tabId: string, agentId: string, harnessId = 'harness-1', extra: Record<string, unknown> = {}) =>({ tabId, agent: { id: agentId, harnessId, machineId: 'machine-1' }, ...extra })+/** The machine's host form and Swarm reads, as the service hands them over. */+const sourcesOf = (core: CoreApi, now?: () => number) => { const held = { feed: new HostFeed(core, 'machine-1', { now }), reads: new SwarmReads(core) }; return () => held }+const HOST = '/api/super-tabs/hosts/machine-1/changes'/** A core whose backend answers by path; one session per harness id, started to use the app unless `plain`. */function setup(routes: (method: string, path: string, body: unknown) => Reply, sessions: Array<{ id: string; plain?: boolean }> = [{ id: 'harness-1' }]) {@@ -32,11 +39,11 @@ function setup(routes: (method: string, path: string, body: unknown) => Reply, sdescribe('a local agent\'s GitHub token', () => {it('is asked for as the agent the roster lists for that harness on this machine, and written into its gh login', async () => {- const { core, backend, hosts, trailers } = setup((method, path) => method === 'GET' ? ok([row('tab-1', 'agent-1')])+ const { core, backend, hosts, trailers } = setup((method, path) => method === 'GET' ? ok(hostForm([row('tab-1', 'agent-1')])): path === '/api/super-tabs/tab-1/github-token?asAgentId=agent-1' ? issued('ghs_fixtureToken0000001') : refuse(404, 'NOT_FOUND'))- const answer = await githubToken(core, 'harness-1')+ const answer = await githubToken(core, 'harness-1', sourcesOf(core)())expect(answer).toMatchObject({ ok: true, value: { token: 'ghs_fixtureToken0000001', repository: 'acme/app', tabId: 'tab-1', agentId: 'agent-1' } })- expect(backend).toHaveBeenCalledWith('GET', '/api/super-tabs/hosts/machine-1', undefined)+ expect(backend).toHaveBeenCalledWith('GET', `${HOST}?full=1`, undefined)expect(backend).toHaveBeenCalledWith('POST', '/api/super-tabs/tab-1/github-token?asAgentId=agent-1', { machineId: 'machine-1' })expect(hosts()).toContain('oauth_token: ghs_fixtureToken0000001')expect(trailers()).toBe('Co-authored-by: Ada <[email protected]>\nHarness-Agent: Atlas\n')@@ -44,48 +51,48 @@ describe('a local agent\'s GitHub token', () => {it('tries the harness\'s next Swarm when one has no task for it, and skips stopping and closing rows and other harnesses', async () => {const { core, backend } = setup((method, path) => method === 'GET'- ? ok([row('tab-0', 'agent-0', 'harness-2'), row('tab-x', 'agent-x', 'harness-1', { stopRequested: true }), row('tab-y', 'agent-y', 'harness-1', { closeSession: true }),- row('tab-1', 'agent-1'), row('tab-2', 'agent-2')])+ ? ok(hostForm([row('tab-0', 'agent-0', 'harness-2'), row('tab-x', 'agent-x', 'harness-1', { stopRequested: true }), row('tab-y', 'agent-y', 'harness-1', { closeSession: true }),+ row('tab-1', 'agent-1'), row('tab-2', 'agent-2')])): path.startsWith('/api/super-tabs/tab-1/') ? refuse(409, 'NO_ASSIGNMENT') : issued('ghs_fixtureToken0000002'))- expect(await githubToken(core, 'harness-1')).toMatchObject({ ok: true, value: { tabId: 'tab-2' } })+ expect(await githubToken(core, 'harness-1', sourcesOf(core)())).toMatchObject({ ok: true, value: { tabId: 'tab-2' } })expect(backend.mock.calls.filter(c => c[0] === 'POST').map(c => c[1])).toEqual(['/api/super-tabs/tab-1/github-token?asAgentId=agent-1', '/api/super-tabs/tab-2/github-token?asAgentId=agent-2'])})it('passes on the most telling refusal and empties the gh login when the server decided', async () => {const answers: Record<string, Reply> = { 'tab-1': refuse(409, 'NO_ASSIGNMENT'), 'tab-2': refuse(409, 'GITHUB_APP_NOT_INSTALLED', 'Install it: https://github.com/apps/x/installations/new') }- const { core, hosts } = setup((method, path) => method === 'GET' ? ok([row('tab-1', 'agent-1'), row('tab-2', 'agent-2')])+ const { core, hosts } = setup((method, path) => method === 'GET' ? ok(hostForm([row('tab-1', 'agent-1'), row('tab-2', 'agent-2')])): path.includes('tab-0') ? issued('x') : answers[path.split('/')[3]!]!)- expect(await githubToken(core, 'harness-1')).toEqual({ error: 'GITHUB_APP_NOT_INSTALLED', detail: 'Install it: https://github.com/apps/x/installations/new', status: 409 })+ expect(await githubToken(core, 'harness-1', sourcesOf(core)())).toEqual({ error: 'GITHUB_APP_NOT_INSTALLED', detail: 'Install it: https://github.com/apps/x/installations/new', status: 409 })expect(hosts()).toBe('{}\n')})it('keeps an unexpired token when the server cannot be reached, and empties it when the app is not configured', async () => {let reply = issued('ghs_fixtureToken0000003')- const { core, hosts } = setup((method) => method === 'GET' ? ok([row('tab-1', 'agent-1')]) : reply)- await githubToken(core, 'harness-1')+ const { core, hosts } = setup((method) => method === 'GET' ? ok(hostForm([row('tab-1', 'agent-1')])) : reply)+ await githubToken(core, 'harness-1', sourcesOf(core)())reply = refuse(503, 'BACKEND_UNAVAILABLE')- expect(await githubToken(core, 'harness-1')).toMatchObject({ error: 'BACKEND_UNAVAILABLE' })+ expect(await githubToken(core, 'harness-1', sourcesOf(core)())).toMatchObject({ error: 'BACKEND_UNAVAILABLE' })expect(hosts()).toContain('ghs_fixtureToken0000003')reply = refuse(503, 'GITHUB_APP_NOT_CONFIGURED')- await githubToken(core, 'harness-1')+ await githubToken(core, 'harness-1', sourcesOf(core)())expect(hosts()).toBe('{}\n')})it('refuses a harness that is not running here, one in no Swarm, and a reply without a token', async () => {- const { core } = setup(method => method === 'GET' ? ok([]) : ok({}))- expect(await githubToken(core, 'harness-9')).toMatchObject({ error: 'AGENT_UNAVAILABLE' })- expect(await githubToken(core, '../x')).toEqual({ error: 'INVALID_REQUEST' })- expect(await githubToken(core, 'harness-1')).toMatchObject({ error: 'NOT_A_SWARM_AGENT' })- const broken = setup(method => method === 'GET' ? ok([row('tab-1', 'agent-1')]) : ok({ token: 7 }))- expect(await githubToken(broken.core, 'harness-1')).toMatchObject({ error: 'GITHUB_UNAVAILABLE' })+ const { core } = setup(method => method === 'GET' ? ok(hostForm([])) : ok({}))+ expect(await githubToken(core, 'harness-9', sourcesOf(core)())).toMatchObject({ error: 'AGENT_UNAVAILABLE' })+ expect(await githubToken(core, '../x', sourcesOf(core)())).toEqual({ error: 'INVALID_REQUEST' })+ expect(await githubToken(core, 'harness-1', sourcesOf(core)())).toMatchObject({ error: 'NOT_A_SWARM_AGENT' })+ const broken = setup(method => method === 'GET' ? ok(hostForm([row('tab-1', 'agent-1')])) : ok({ token: 7 }))+ expect(await githubToken(broken.core, 'harness-1', sourcesOf(broken.core)())).toMatchObject({ error: 'GITHUB_UNAVAILABLE' })const offline = setup(() => refuse(502, 'BACKEND_UNAVAILABLE'))- expect(await githubToken(offline.core, 'harness-1')).toMatchObject({ error: 'BACKEND_UNAVAILABLE' })+ expect(await githubToken(offline.core, 'harness-1', sourcesOf(offline.core)())).toMatchObject({ error: 'BACKEND_UNAVAILABLE' })})it('writes nothing for a person\'s own agent, which keeps its own GitHub login', async () => {- const { core } = setup(method => method === 'GET' ? ok([row('tab-1', 'agent-1')]) : issued('ghs_fixtureToken0000004'), [{ id: 'harness-1', plain: true }])- expect(await githubToken(core, 'harness-1')).toMatchObject({ ok: true })+ const { core } = setup(method => method === 'GET' ? ok(hostForm([row('tab-1', 'agent-1')])) : issued('ghs_fixtureToken0000004'), [{ id: 'harness-1', plain: true }])+ expect(await githubToken(core, 'harness-1', sourcesOf(core)())).toMatchObject({ ok: true })expect(() => readFileSync(join(core.dataDir, 'swarm-github'))).toThrow()})})@@ -97,10 +104,9 @@ describe('keeping gh\'s token fresh', () => {const time = clock()let work = [{ tabId: 'tab-1', assignmentId: 'attempt-1', harnessId: 'harness-1' }]let next = 1- const { core, backend, hosts } = setup((method, path) => path.endsWith('/assignments') ? ok(work)- : method === 'GET' ? ok([row('tab-1', 'agent-1')])+ const { core, backend, hosts } = setup(method => method === 'GET' ? ok(hostForm([row('tab-1', 'agent-1')], { assignments: work })): issued(`ghs_fixtureToken000000${next++}`, new Date(time.now() + 3600_000).toISOString()))- const refresher = new GitHubTokenRefresher(core, { now: time.now })+ const refresher = new GitHubTokenRefresher(core, sourcesOf(core, time.now), { now: time.now })await refresher.tick()expect(hosts()).toContain('ghs_fixtureToken0000001')const asked = () => backend.mock.calls.filter(c => c[0] === 'POST').length@@ -122,14 +128,14 @@ describe('keeping gh\'s token fresh', () => {})it('reads nothing from the backend while no session uses the app, and leaves tokens be while it is away', async () => {- const quiet = setup(() => ok([]), [{ id: 'harness-1', plain: true }])- await new GitHubTokenRefresher(quiet.core).tick()+ const quiet = setup(() => ok(hostForm([])), [{ id: 'harness-1', plain: true }])+ await new GitHubTokenRefresher(quiet.core, sourcesOf(quiet.core)).tick()expect(quiet.backend).not.toHaveBeenCalled()let away = falseconst { core, hosts } = setup((method, path) => away ? refuse(502, 'BACKEND_UNAVAILABLE')- : path.endsWith('/assignments') ? ok([{ tabId: 'tab-1', assignmentId: 'attempt-1', harnessId: 'harness-1' }])- : method === 'GET' ? ok([row('tab-1', 'agent-1')]) : issued('ghs_fixtureToken0000009'))- const refresher = new GitHubTokenRefresher(core)+ : method === 'GET' ? ok(hostForm([row('tab-1', 'agent-1')], { assignments: [{ tabId: 'tab-1', assignmentId: 'attempt-1', harnessId: 'harness-1' }] }))+ : issued('ghs_fixtureToken0000009'))+ const refresher = new GitHubTokenRefresher(core, sourcesOf(core))await refresher.tick()away = trueawait refresher.tick()@@ -139,22 +145,22 @@ describe('keeping gh\'s token fresh', () => {it('starts once, looks again on its interval, and stops', async () => {vi.useFakeTimers()try {- const { core, backend } = setup(path => path === 'GET' ? ok([]) : ok([]))- const refresher = new GitHubTokenRefresher(core, { intervalMs: 1000 })+ const { core, backend } = setup(() => ok(hostForm([])))+ const refresher = new GitHubTokenRefresher(core, sourcesOf(core), { intervalMs: 1000 })refresher.start()refresher.start()await vi.advanceTimersByTimeAsync(2500)- expect(backend.mock.calls.filter(c => String(c[1]).endsWith('/assignments')).length).toBe(3)+ expect(backend.mock.calls.filter(c => String(c[1]).startsWith(HOST)).length).toBe(3)refresher.stop()await vi.advanceTimersByTimeAsync(5000)- expect(backend.mock.calls.filter(c => String(c[1]).endsWith('/assignments')).length).toBe(3)+ expect(backend.mock.calls.filter(c => String(c[1]).startsWith(HOST)).length).toBe(3)} finally { vi.useRealTimers() }})it('logs a look that fails and goes on', async () => {const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})const core = fakeCore({ agents: { live: vi.fn(() => { throw new Error('registry gone') }) } })- await new GitHubTokenRefresher(core).tick()+ await new GitHubTokenRefresher(core, sourcesOf(core)).tick()expect(warn).toHaveBeenCalledWith('[super-tab] GitHub tokens not refreshed · registry gone')warn.mockRestore()})diff --git a/cli/src/superTabs/github.ts b/cli/src/superTabs/github.tsindex ce37a3f61..85c29275a 100644--- a/cli/src/superTabs/github.ts+++ b/cli/src/superTabs/github.ts@@ -8,11 +8,15 @@*/import type { CoreApi } from '../core/api.js'import { swarmGitHubSessionDir, writeSessionGitHub } from '../lib/swarmGitHub.js'-import { backend, identifier, object, SuperTabHostError } from './host.js'+import { backend, identifier, object, SuperTabHostError } from './wire.js'+import type { SwarmSources } from './host.js'type Json = Record<string, unknown>type Session = NonNullable<ReturnType<CoreApi['agents']['byAgent']>>const list = (value: unknown) => Array.isArray(value) ? value.map(object) : []+/** How old a host form a token request may take: git asks for one on every fetch and push, and the server checks the task on+ * each request anyway. */+const ROSTER_FRESH_MS = 5_000/** The session's own folder when it was started to use the app, else null. */function githubDir(core: CoreApi, session: Session | undefined): string | null {@@ -29,7 +33,7 @@ const decided = (error: SuperTabHostError) => (error.status >= 400 && error.stat* nearly always), the first that has a task answering. For a session started to use the app, its gh login and commit* trailers are written from the answer, and its login emptied on a refusal.*/-export async function githubToken(core: CoreApi, harnessId: string): Promise<Json> {+export async function githubToken(core: CoreApi, harnessId: string, sources: SwarmSources): Promise<Json> {const machineId = core.daemon.machineId()if (!identifier(machineId) || !identifier(harnessId)) return { error: 'INVALID_REQUEST' }const session = core.agents.byAgent(harnessId)@@ -37,7 +41,7 @@ export async function githubToken(core: CoreApi, harnessId: string): Promise<Jsoconst dir = githubDir(core, session)let refusal: Json | null = nulltry {- const rows = list(await backend(core, 'GET', `/api/super-tabs/hosts/${machineId}`)).filter(row => {+ const rows = list((await sources.feed.current(ROSTER_FRESH_MS)).roster).filter(row => {const agent = object(row.agent)return identifier(row.tabId) && identifier(agent.id) && agent.machineId === machineId && agent.harnessId === harnessId&& row.closeSession !== true && row.stopRequested !== true@@ -84,7 +88,7 @@ export class GitHubTokenRefresher {private readonly now: () => numberprivate readonly intervalMs: number- constructor(private readonly core: CoreApi, options: { now?: () => number; intervalMs?: number } = {}) {+ constructor(private readonly core: CoreApi, private readonly sources: () => SwarmSources, options: { now?: () => number; intervalMs?: number } = {}) {this.now = options.now ?? Date.nowthis.intervalMs = options.intervalMs ?? REFRESH_INTERVAL_MS}@@ -120,7 +124,8 @@ export class GitHubTokenRefresher {const machineId = this.core.daemon.machineId()if (!identifier(machineId)) returnlet work: Json[]- try { work = list(await backend(this.core, 'GET', `/api/super-tabs/hosts/${machineId}/assignments`)) } catch (error) {+ // A fresh read each minute: a task that ended takes its token away within that minute.+ try { work = list((await this.sources().feed.refresh()).assignments) } catch (error) {if (error instanceof SuperTabHostError) returnthrow error}@@ -135,7 +140,7 @@ export class GitHubTokenRefresher {}const known = this.primed.get(id)if (known && known.assignmentId === task.assignmentId && known.expiresAt - this.now() > RENEW_BELOW_MS) continue- const answer = await githubToken(this.core, id)+ const answer = await githubToken(this.core, id, this.sources())const expiresAt = Date.parse(String(object(answer.value).expiresAt))if (answer.ok === true && Number.isFinite(expiresAt)) this.primed.set(id, { assignmentId: String(task.assignmentId), expiresAt })else this.primed.delete(id)diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.tsindex 83e5b70b7..20887f0a5 100644--- a/cli/src/superTabs/host.spec.ts+++ b/cli/src/superTabs/host.spec.ts@@ -7,28 +7,33 @@ import { afterEach, describe, expect, it, vi } from 'vitest'import type { CoreApi, TurnDelivery } from '../core/api.js'import { fakeCore } from '../testing/fakeCore.js'import { backend, swarmRoleFor, hostJournalFile, SuperTabHost, type SuperTabHostOptions } from './host.js'+import { hostForm, swarmReply } from './fixtures/read/index.js'+import { HostFeed } from './hostFeed.js'+import { SwarmReads } from './swarmReads.js'import { retainedHarnesses, retentionFile } from './retention.js'import { observerSource } from './observers.js'const roots: string[] = []const hosts: SuperTabHost[] = []+/** The machine's host form and Swarm reads, as the service hands them to the host and the role lookup. */+const sourcesOf = (core: CoreApi) => ({ feed: new HostFeed(core, 'machine-1'), reads: new SwarmReads(core) })afterEach(() => { for (const host of hosts.splice(0)) host.stop(); for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) })function setup(messageFields: Record<string, unknown> = {}) {const dir = mkdtempSync(join(tmpdir(), 'super-tab-host-')); roots.push(dir)const listeners = new Set<(e: TurnDelivery) => void>()- const row: { tabId: string; agent: { id: string; harnessId: string; machineId: string }; lead?: boolean } = { tabId: 'tab', agent: { id: 'agent', harnessId: 'harness', machineId: 'machine-1' } }- /** The conversation the delivery comes from, and the ones the agent's own view of the tab lists. */+ const row: { tabId: string; agent: { id: string; harnessId: string; machineId: string }; lead?: boolean; leadsConversationId: string } =+ { tabId: 'tab', agent: { id: 'agent', harnessId: 'harness', machineId: 'machine-1' }, leadsConversationId: 'leads' }+ /** The conversation the delivery comes from. */let from = 'lead'- const views = ['lead']let removed = false, revoked = false, status = 'queued', claimId: string | null = nullconst receipts: Record<string, unknown>[] = []const holds: Record<string, unknown>[] = []let clock = 0const call: CoreApi['account']['backend'] = vi.fn(async (method, path, body) => {let data: unknown- if (path.includes('/hosts/')) data = removed ? [] : [row]- else if (path.includes('?asAgentId=')) data = { state: { conversations: views.map(id => ({ id })) } }+ if (path.includes('/hosts/')) data = hostForm(removed ? [] : [row], { tabs: ['tab'] })+ else if (path.includes('asAgentId=')) data = swarmReply(path, { conversations: [{ id: 'lead' }] })else if (revoked) return { status: 403, body: { success: false, error: { code: 'FORBIDDEN', message: 'Grant removed' } } }else if (method === 'GET') data = status === 'delivered' ? [] : [{ id: 'delivery', conversationId: from, claimId, status }]else {@@ -51,7 +56,7 @@ function setup(messageFields: Record<string, unknown> = {}) {for (const fn of listeners) fn({ deliveryId: 'team:service:superTabs:delivery', sessionId: 'harness', state, reason })}const saved = () => JSON.parse(readFileSync(hostJournalFile(dir, 'machine-1'), 'utf8'))- return { core, call, open, event, receipts, holds, log, row, wait: (ms: number) => { clock += ms }, saved, dir, remove: () => { removed = true }, revoke: (value = true) => { revoked = value }, foreignClaim: () => { claimId = 'another-process' }, from: (id: string) => { from = id }, views }+ return { core, call, open, event, receipts, holds, log, row, wait: (ms: number) => { clock += ms }, saved, dir, remove: () => { removed = true }, revoke: (value = true) => { revoked = value }, foreignClaim: () => { claimId = 'another-process' }, from: (id: string) => { from = id } }}describe('current Swarm role lookup', () => {@@ -60,10 +65,11 @@ describe('current Swarm role lookup', () => {const agent = { id: 'agent', harnessId: 'harness', machineId: 'machine-1', role: 'reviewer' }let groups = [{ leadId: 'other', agentIds: ['agent'] }]vi.mocked(t.call).mockImplementation(async (_method, path) => ({ status: 200, body: { success: true, data:- path.includes('/hosts/') ? [{ tabId: 'tab', agent }] : { state: { agents: [agent], conversations: groups } } } }))- expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toEqual({ role: 'review', mode: 'orchestration' })+ path.includes('/hosts/') ? hostForm([{ tabId: 'tab', agent }]) : swarmReply(path, { agents: [agent], conversations: groups }) } }))+ const sources = sourcesOf(t.core)+ expect(await swarmRoleFor(sources, 'harness')).toEqual({ role: 'review', mode: 'orchestration' })groups = []- expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toBeNull()+ expect(await swarmRoleFor(sources, 'harness')).toBeNull()})it.each(['lead', 'member', 'assigned'] as const)('derives an old %s from current groups on its machine', async kind => {const t = setup()@@ -71,9 +77,10 @@ describe('current Swarm role lookup', () => {const group = { leadId: kind === 'lead' ? 'agent' : 'other', agentIds: kind === 'member' ? ['agent'] : [],assignment: kind === 'assigned' ? { agentId: 'agent', execution: { machineId: 'machine-1' } } : null }vi.mocked(t.call).mockImplementation(async (_method, path) => ({ status: 200, body: { success: true, data:- path.includes('/hosts/') ? [{ tabId: 'tab', agent }] : { state: { agents: [agent], conversations: [group] } } } }))- expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toEqual({ role: kind === 'lead' ? 'lead' : 'dev', mode: 'orchestration' })- expect(await swarmRoleFor(t.core, 'machine-1', 'personal')).toBeNull()+ path.includes('/hosts/') ? hostForm([{ tabId: 'tab', agent }]) : swarmReply(path, { agents: [agent], conversations: [group] }) } }))+ const sources = sourcesOf(t.core)+ expect(await swarmRoleFor(sources, 'harness')).toEqual({ role: kind === 'lead' ? 'lead' : 'dev', mode: 'orchestration' })+ expect(await swarmRoleFor(sources, 'personal')).toBeNull()})it('gives the mode of the project whose group made the role, Lead first', async () => {const t = setup()@@ -81,34 +88,60 @@ describe('current Swarm role lookup', () => {const projects = [{ id: 'lead', skillMode: 'default' }, { id: 'p2', skillMode: 'orchestration' }, { id: 'p3', skillMode: 'default' }]let conversations: unknown[] = [{ projectId: 'p2', leadId: 'other', agentIds: ['agent'] }, { projectId: 'p3', leadId: 'agent', agentIds: [] }]vi.mocked(t.call).mockImplementation(async (_method, path) => ({ status: 200, body: { success: true, data:- path.includes('/hosts/') ? [{ tabId: 'tab', agent }] : { state: { agents: [agent], conversations, projects } } } }))- expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toEqual({ role: 'lead', mode: 'default' })+ path.includes('/hosts/') ? hostForm([{ tabId: 'tab', agent }]) : swarmReply(path, { agents: [agent], conversations, projects }) } }))+ const sources = sourcesOf(t.core)+ expect(await swarmRoleFor(sources, 'harness')).toEqual({ role: 'lead', mode: 'default' })conversations = [{ projectId: 'p2', leadId: 'other', agentIds: ['agent'] }]- expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toEqual({ role: 'dev', mode: 'orchestration' })+ expect(await swarmRoleFor(sources, 'harness')).toEqual({ role: 'dev', mode: 'orchestration' })// A group from before projects is in the first project.conversations = [{ leadId: 'other', agentIds: ['agent'] }]- expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toEqual({ role: 'dev', mode: 'default' })+ expect(await swarmRoleFor(sources, 'harness')).toEqual({ role: 'dev', mode: 'default' })})it.each(['removed-roster', 'foreign', 'removed-state', 'archived', 'released', 'none', 'malformed'] as const)('never adopts a session whose membership is %s', async kind => {const t = setup()const agent = { id: 'agent', harnessId: 'harness', machineId: kind === 'foreign' ? 'other' : 'machine-1' }vi.mocked(t.call).mockImplementation(async (_method, path) => ({ status: 200, body: { success: true, data: path.includes('/hosts/')- ? kind === 'malformed' ? {} : kind === 'removed-roster' ? [] : [{ tabId: 'tab', agent, stopRequested: kind === 'released' }]- : { state: { agents: kind === 'removed-state' ? [] : [agent], conversations:- kind === 'none' ? [] : [{ leadId: 'agent', agentIds: ['agent'], archived: kind === 'archived' }] } } } }))- expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toBeNull()+ ? kind === 'malformed' ? { ...hostForm([]), tabs: [{ tabId: 'tab', roster: {} }] }+ : hostForm(kind === 'removed-roster' ? [] : [{ tabId: 'tab', agent, stopRequested: kind === 'released' }], { tabs: ['tab'] })+ : swarmReply(path, { agents: kind === 'removed-state' ? [] : [agent], conversations:+ kind === 'none' ? [] : [{ leadId: 'agent', agentIds: ['agent'], archived: kind === 'archived' }] }) } }))+ expect(await swarmRoleFor(sourcesOf(t.core), 'harness')).toBeNull()})it('prefers Lead when a session also works in another group and never reuses a stale roster', async () => {const t = setup(), agent = { id: 'agent', harnessId: 'harness', machineId: 'machine-1' }let present = truevi.mocked(t.call).mockImplementation(async (_method, path) => ({ status: 200, body: { success: true, data: path.includes('/hosts/')- ? present ? [{ tabId: 'tab', agent }] : []- : { state: { agents: [agent], conversations: [{ agentIds: ['agent'] }, { leadId: 'agent' }] } } } }))- expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toEqual({ role: 'lead', mode: 'orchestration' })+ ? hostForm(present ? [{ tabId: 'tab', agent }] : [], { tabs: ['tab'] })+ : swarmReply(path, { agents: [agent], conversations: [{ agentIds: ['agent'] }, { leadId: 'agent' }] }) } }))+ const sources = sourcesOf(t.core)+ expect(await swarmRoleFor(sources, 'harness')).toEqual({ role: 'lead', mode: 'orchestration' })present = false- expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toBeNull()- expect(await swarmRoleFor(t.core, 'machine-1', 'harness')).toBeNull()+ expect(await swarmRoleFor(sources, 'harness')).toBeNull()+ expect(await swarmRoleFor(sources, 'harness')).toBeNull()+ })+})++// #1726: a tick read up to 100 whole Swarms every second. It reads the host form: in full first, then only what changed.+describe('the host tick on the host form', () => {+ it('reads every Swarm in full first and then by change, never the old rosters', async () => {+ const t = setup(), host = t.open()+ await host.tick()+ await host.tick()+ const reads = vi.mocked(t.call).mock.calls.map(([, path]) => path).filter(path => path.includes('/hosts/'))+ expect(reads).toEqual(['/api/super-tabs/hosts/machine-1/changes?full=1', expect.stringMatching(/^\/api\/super-tabs\/hosts\/machine-1\/changes\?cursor=host-\d+$/)])+ expect(t.core.turns.deliver).toHaveBeenCalledTimes(1)+ })+ it('says once that Harness needs an update, and asks again only a minute later', async () => {+ const t = setup(), host = t.open()+ vi.mocked(t.call).mockImplementation(async () => ({ status: 426, body: { success: false, error: { code: 'UPDATE_REQUIRED' } } }))+ for (let i = 0; i < 3; i++) { await host.tick(); t.wait(1_000) }+ expect(t.log.mock.calls.map(([line]) => line)).toEqual(['Update Harness to keep using this Swarm.'])+ expect(vi.mocked(t.call).mock.calls.filter(([, path]) => path.includes('/hosts/'))).toHaveLength(1)+ t.wait(57_000)+ await host.tick()+ expect(vi.mocked(t.call).mock.calls.filter(([, path]) => path.includes('/hosts/'))).toHaveLength(2)+ expect(t.log).toHaveBeenCalledTimes(1)})})@@ -137,7 +170,7 @@ describe('Super Tab native delivery handoff', () => {expect(t.core.turns.deliver).toHaveBeenCalledTimes(2)})// Leads see each other's work and talk (spec 2026-10-23): the Leads conversation reaches Leads alone. The server- // delivers it only to them; this host also types into an agent that leads nothing only what its own view can read.+ // delivers it only to them; this host also never types it into an agent that leads nothing.it('never types a Leads conversation message into an agent that leads nothing, and says so once', async () => {const t = setup(), host = t.open()t.from('leads')@@ -145,7 +178,7 @@ describe('Super Tab native delivery handoff', () => {expect(t.core.turns.deliver).not.toHaveBeenCalled()expect(t.call).not.toHaveBeenCalledWith('POST', expect.stringContaining('/deliveries/delivery'), expect.anything())expect(t.log.mock.calls.filter(([line]) => String(line).includes('not in a conversation'))).toHaveLength(1)- t.views.push('leads')+ t.row.lead = trueawait host.tick()expect(t.core.turns.deliver).toHaveBeenCalledTimes(1)})@@ -163,21 +196,20 @@ describe('Super Tab native delivery handoff', () => {expect(t.core.turns.deliver).toHaveBeenCalledTimes(1)expect(t.saved().entries.delivery.stage).toBe('prepared')})- it('reads an agent\'s view once for its own conversation, and never for a Lead', async () => {+ // The design of #1726 (section 5.3): the roster names the Leads conversation, so no delivery costs a read of the Swarm.+ it('reads no Swarm to judge a delivery, for an agent that leads nothing or a Lead', async () => {const t = setup(), host = t.open()await host.tick()expect(t.core.turns.deliver).toHaveBeenCalledTimes(1)- const views = () => vi.mocked(t.call).mock.calls.filter(([, path]) => path === '/api/super-tabs/tab?asAgentId=agent').length- expect(views()).toBe(1)t.event('rejected', 'team_waiting_busy')await host.tick()- expect(views()).toBe(1)+ expect(vi.mocked(t.call).mock.calls.some(([, path]) => path.includes('asAgentId='))).toBe(false)const lead = setup()lead.row.lead = truelead.from('leads')await lead.open().tick()expect(lead.core.turns.deliver).toHaveBeenCalledTimes(1)- expect(vi.mocked(lead.call).mock.calls.some(([, path]) => path.includes('?asAgentId='))).toBe(false)+ expect(vi.mocked(lead.call).mock.calls.some(([, path]) => path.includes('asAgentId='))).toBe(false)})it('names all five task parts in the worker delivery header', async () => {const t = setup()@@ -506,11 +538,11 @@ it('confirms a stopped assignment only with fresh native evidence, including aftt.core.agents.stopped = stoppedconst proof: unknown[] = []vi.mocked(t.core.account.backend).mockImplementation(async (method, path, body) => {- if (method === 'GET') return { status: 200, body: { data: [+ if (method === 'GET') return { status: 200, body: { data: hostForm([], { assignments: [{ tabId: 'tab', assignmentId: 'work-1', harnessId: 'gone' },{ tabId: 'tab', assignmentId: 'work-2', harnessId: 'unconfirmed' },{ tabId: '', assignmentId: 'bad', harnessId: 'gone' },- ] } }+ ] }) } }expect(path).toBe('/api/super-tabs/tab/stopped'); proof.push(body)return { status: 200, body: { data: { confirmed: true } } }})@@ -524,6 +556,34 @@ it('confirms a stopped assignment only with fresh native evidence, including aftexpect(proof).toHaveLength(1)})+describe('a private chat delivered to the PM (final review, Critical 1)', () => {+ it('types the secret into the PM\'s terminal, then refuses every share of that session until it closes here', async () => {+ const secret = 'Only for the PM: the launch slips a week.'+ const t = setup({ conversationId: 'chat', text: secret })+ t.from('chat')+ // The roster as the backend sends it for a PM: no observers, and marked confidential.+ Object.assign(t.row, { lead: true, confidential: true, observers: [] })+ const host = t.open()+ await host.tick()+ expect(vi.mocked(t.core.turns.deliver).mock.calls[0]?.[0]).toBe('harness')+ expect(vi.mocked(t.core.turns.deliver).mock.calls[0]?.[1]).toContain(secret)+ const cache = observerSource(t.dir, () => 'machine-1', () => 1)+ const ordinary = { tab: null, agentId: 'harness', recipientEmail: '[email protected]' } as never+ const swarm = { tab: 'super:tab', agentId: 'harness', recipientEmail: '[email protected]' } as never+ expect(cache.allows(ordinary)).toBe(false)+ expect(cache.allows(swarm)).toBe(false)+ // Its registration is removed while the session still runs on this machine: still refused.+ t.remove()+ await host.tick()+ t.wait(201)+ expect(observerSource(t.dir, () => 'machine-1', () => 300).allows(ordinary)).toBe(false)+ // The session closes here: only now may it be shared again.+ vi.mocked(t.core.agents.byAgent).mockReturnValue(undefined as never)+ await host.tick()+ expect(observerSource(t.dir, () => 'machine-1', () => 600).allows(ordinary)).toBe(true)+ })+})+describe('the super-tab command in delivered input', () => {it('names the short command in every line that names a command, and asks for it once while the input is held', async () => {const t = setup({ replyTo: 'earlier' })@@ -608,7 +668,7 @@ describe('Super Tab waits for the Harness Pro', () => {let rows: unknown[] = [waiting], offline = falseconst call: CoreApi['account']['backend'] = vi.fn(async (_method, path) => {if (offline) throw new Error('Host offline')- return { status: 200, body: { success: true, data: path.includes('/hosts/') ? rows : [] } }+ return { status: 200, body: { success: true, data: path.includes('/hosts/') ? hostForm(rows, { tabs: ['tab'] }) : [] } }})const superTabs = { attention: vi.fn(), cards: vi.fn(), cardRecap: vi.fn(), shareObservers: vi.fn(), screen: vi.fn(), input: vi.fn() }const core = fakeCore({ dataDir: dir, superTabs, account: { backend: call },@@ -645,7 +705,7 @@ describe('Super Tab waits for the Harness Pro', () => {const dir = mkdtempSync(join(tmpdir(), 'super-tab-host-')); roots.push(dir)const rows = [{ tabId: 'tab', tabName: 'Pilot', attention: { assignmentId: 'as-1', status: 'needs_human', result: 'Ship it?' },agent: { id: 'agent', harnessId: 'harness', machineId: 'machine-1' } }]- const call: CoreApi['account']['backend'] = vi.fn(async (_method, path) => ({ status: 200, body: { success: true, data: path.includes('/hosts/') ? rows : [] } }))+ const call: CoreApi['account']['backend'] = vi.fn(async (_method, path) => ({ status: 200, body: { success: true, data: path.includes('/hosts/') ? hostForm(rows, { tabs: ['tab'] }) : [] } }))let here = true, clock = 0const superTabs = { attention: vi.fn(), cards: vi.fn(), cardRecap: vi.fn(), shareObservers: vi.fn(), screen: vi.fn(), input: vi.fn() }const core = fakeCore({ dataDir: dir, superTabs, account: { backend: call },@@ -682,8 +742,8 @@ it('stops a requested worker once, confirms removal, and releases retention on tt.core.agents.closeSwarm = async request => { expect(request.agentId).toBe('harness'); expect(request.expiresAt).toBeLessThanOrEqual(Date.now() + 120_000); closed = true; return { closed: true } }t.core.account.backend = async (method, path, body) => {if ((body as any)?.command?.type === 'agent.stopLease') return { status: 200, body: { data: { result: { expiresAt: Date.now() + 3_600_000, durationMs: 120_000 } } } }- if (path.includes('/hosts/')) return { status: 200, body: { data: removed ? [] : [{ tabId: 'tab', agent: target, stopRequested: true }] } }- if (method === 'GET') return { status: 200, body: { data: { state: { agents: [target], conversations: [] } } } }+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm(removed ? [] : [{ tabId: 'tab', agent: target, stopRequested: true }], { tabs: ['tab'] }) } }+ if (method === 'GET') return { status: 200, body: { data: swarmReply(path, { agents: [target], conversations: [] }) } }acknowledgements++; removed = truereturn { status: 200, body: { data: {} } }}@@ -696,7 +756,9 @@ it('stops a requested worker once, confirms removal, and releases retention on texpect(acknowledgements).toBe(1)})-it('closes the session of a worker whose assignment the Lead cancelled', async () => {+// A lost task (the backend's v1 liveness) has ended for its agent, as a cancelled one has: a stalled agent the Lead stops+// is closed, never kept for work it no longer holds.+it.each(['cancelled', 'lost'])('closes the session of a worker whose assignment is %s', async status => {const t = setup(), host = t.open()vi.mocked(t.core.agents.byAgent).mockReturnValue({ agentId: 'harness', sessionId: 'native', registeredAt: 0, startedBy: 'agent' } as never)let closed = false, removed = false@@ -705,8 +767,8 @@ it('closes the session of a worker whose assignment the Lead cancelled', async (t.core.agents.closeSwarm = async () => { closed = true; return { closed: true } }t.core.account.backend = async (method, path, body) => {if ((body as any)?.command?.type === 'agent.stopLease') return { status: 200, body: { data: { result: { expiresAt: Date.now() + 3_600_000, durationMs: 120_000 } } } }- if (path.includes('/hosts/')) return { status: 200, body: { data: removed ? [] : [{ tabId: 'tab', agent: target, stopRequested: true }] } }- if (method === 'GET') return { status: 200, body: { data: { state: { agents: [target], conversations: [{ id: 'g', assignment: { id: 'a', agentId: 'agent', status: 'cancelled' } }] } } } }+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm(removed ? [] : [{ tabId: 'tab', agent: target, stopRequested: true }], { tabs: ['tab'] }) } }+ if (method === 'GET') return { status: 200, body: { data: swarmReply(path, { agents: [target], conversations: [{ id: 'g', assignment: { id: 'a', agentId: 'agent', status } }] }) } }removed = truereturn { status: 200, body: { data: {} } }}@@ -725,11 +787,11 @@ it.each(['active', 'foreign', 'changed', 'missing', 'refused', 'unconfirmed', 'ut.core.agents.stopped = async () => falset.core.account.backend = async (method, path, body) => {if ((body as any)?.command?.type === 'agent.stopLease') return { status: 200, body: { data: { result: { expiresAt: Date.now() + 3_600_000, durationMs: 120_000 } } } }- if (path.includes('/hosts/')) return { status: 200, body: { data: [{ tabId: 'tab', agent: target, stopRequested: true }] } }- if (method === 'GET') return { status: 200, body: { data: { state: {+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm([{ tabId: 'tab', agent: target, stopRequested: true }], { tabs: ['tab'] }) } }+ if (method === 'GET') return { status: 200, body: { data: swarmReply(path, {agents: kind === 'missing' ? [] : [{ ...target, machineId: kind === 'foreign' ? 'foreign' : target.machineId, releaseId: kind === 'changed' ? 'release-2' : 'release-1' }],conversations: [{ assignment: { agentId: 'agent', status: kind === 'active' ? 'working' : 'done' } }],- } } } }+ }) } }acknowledge(); return { status: 200, body: { data: {} } }}await host.tick()@@ -751,8 +813,8 @@ it('retries a lost removal acknowledgement from native stopped evidence withoutt.core.agents.stopped = async () => stoppedt.core.account.backend = async (method, path, body) => {if ((body as any)?.command?.type === 'agent.stopLease') return { status: 200, body: { data: { result: { expiresAt: Date.now() + 3_600_000, durationMs: 120_000 } } } }- if (path.includes('/hosts/')) return { status: 200, body: { data: [{ tabId: 'tab', agent: target, stopRequested: true }] } }- if (method === 'GET') return { status: 200, body: { data: { state: { agents: [target], conversations: [] } } } }+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm([{ tabId: 'tab', agent: target, stopRequested: true }], { tabs: ['tab'] }) } }+ if (method === 'GET') return { status: 200, body: { data: swarmReply(path, { agents: [target], conversations: [] }) } }attempts++if (attempts === 1) throw new Error('Lost acknowledgement')return { status: 200, body: { data: {} } }@@ -780,8 +842,8 @@ function releaseFixture(nativeKind = 'swarm', result: Record<string, unknown> =if (command?.type === 'agent.stopLease') { lease(); return { status: 200, body: { data: { result: { durationMs: 120_000 } } } } }if (command?.type === 'agent.remove') { remove(); return { status: 200, body: { data: {} } } }if (command?.type === 'message.send') { sent(body); return { status: 200, body: { data: {} } } }- if (path.includes('/hosts/')) return { status: 200, body: { data: [{ tabId: 'tab', agent: target, stopRequested: true }] } }- return { status: 200, body: { data: { state: { agents: [target], conversations: [], ...extra } } } }+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm([{ tabId: 'tab', agent: target, stopRequested: true }], { tabs: ['tab'] }) } }+ return { status: 200, body: { data: swarmReply(path, { agents: [target], conversations: [], ...extra }) } }}const poll = async (advance = 0) => { t.wait(advance); await host.tick(); await new Promise(resolve => setImmediate(resolve)) }return { ...t, host, target, native, lookup, close, lease, remove, sent, poll }@@ -998,6 +1060,25 @@ describe('a Lead\'s terminal requests', () => {})})+describe('the progress a host reports', () => {+ it('sends with its machine\'s reading when each agent\'s screen last changed', async () => {+ const t = setup()+ Object.assign(t.core, { superTabs: { attention: vi.fn(), cards: vi.fn(), cardRecap: vi.fn(), shareObservers: vi.fn(), input: vi.fn(),+ screen: vi.fn(async () => ({ ok: true as const, text: '✻ Editing host.ts…\n❯ ', hold: null })) } })+ const pool = { tabId: 'tab', machine: { machineId: 'machine-1', generation: 'grant', cwd: '/repo', engines: ['claude'] }, harnessIds: ['harness'], starts: [] }+ const roster = vi.mocked(t.call).getMockImplementation()!+ vi.mocked(t.call).mockImplementation(async (method, path, body) => path.includes('/hosts/machine-1/changes')+ ? { status: 200, body: { success: true, data: hostForm([t.row], { pools: [pool] }) } } : roster(method, path, body))+ const local = { machineId: 'machine-1', request: vi.fn(async () => ({})), close: vi.fn() }+ const host = t.open({ machines: { open: async () => local, capabilities: async () => ({ ok: true, resources: {}, tools: {} }) as never } })+ host.start()+ // The first reading may go before the first screen read; the next beat carries it.+ t.wait(16_000)+ await vi.waitFor(() => expect(vi.mocked(t.call).mock.calls.some(([method, path, body]) => method === 'POST'+ && path === '/api/super-tabs/tab/machines/machine-1' && typeof (body as { harnessProgress?: Record<string, unknown> }).harnessProgress?.harness === 'number')).toBe(true), { timeout: 3_000 })+ })+})+describe('the members a host lets watch its agents', () => {it('keeps them watching through a 3 s roster read, wakes Share once, and lets a removed member go at once', async () => {const dir = mkdtempSync(join(tmpdir(), 'super-tab-host-')); roots.push(dir)@@ -1007,7 +1088,7 @@ describe('the members a host lets watch its agents', () => {const call: CoreApi['account']['backend'] = vi.fn(async (_method, path) => {// The roster read takes 3 s when asked to (seen up to 2.8 s, 2026-10-23); everything else answers at once.if (path.includes('/hosts/') && answer === null) await new Promise<void>(resolve => { answer = resolve })- return { status: 200, body: { success: true, data: path.includes('/hosts/') ? rows : [] } }+ return { status: 200, body: { success: true, data: path.includes('/hosts/') ? hostForm(rows, { tabs: ['tab'] }) : [] } }})const superTabs = { attention: vi.fn(), cards: vi.fn(), cardRecap: vi.fn(), shareObservers: vi.fn(), screen: vi.fn(), input: vi.fn() }const core = fakeCore({ dataDir: dir, superTabs, account: { backend: call },@@ -1058,7 +1139,7 @@ describe('adding the machine its own Lead runs on to the Swarm', () => {if (code) return { status: 409, body: { success: false, error: { code, message: `Refused: ${code}` } } }return { status: 200, body: { success: true, data: {} } }}- return { status: 200, body: { success: true, data: path.includes('/hosts/') ? rows : [] } }+ return { status: 200, body: { success: true, data: path.includes('/hosts/') ? hostForm(rows, { tabs: ['tab'] }) : [] } }})const core = fakeCore({ dataDir: dir, account: { backend: call, machineName: vi.fn(() => 'Ken Mac') } })const prepare = vi.fn(async () => ({ ok: true, state: 'ready', cwd: '/data/swarm-projects/own', engines: ['claude', 'codex'], maxAgents: 3, scope: 'swarm' }))@@ -1077,7 +1158,7 @@ describe('adding the machine its own Lead runs on to the Swarm', () => {it('adds it once with the prepared slots and leaves unmarked Swarms alone', async () => {const t = joining()await t.pass(0)- expect(t.prepare).toHaveBeenCalledExactlyOnceWith(t.core, { tabId: 'own', scope: 'swarm' })+ expect(t.prepare).toHaveBeenCalledExactlyOnceWith(t.core, { tabId: 'own', scope: 'swarm' }, { reads: expect.any(SwarmReads) })expect(t.commands).toEqual([{ path: '/api/super-tabs/own/commands', operationId: expect.any(String), command: { type: 'machine.contribute',machineId: 'machine-1', name: 'Ken Mac', cwd: '/data/swarm-projects/own', scope: 'swarm', engines: ['claude', 'codex'], maxAgents: 3, ifMissing: true } }])await t.pass(59_000)@@ -1137,7 +1218,7 @@ describe('adding this Mac\'s Harness Team account where this Mac was added', ()if (code) return { status: 409, body: { success: false, error: { code, message: `Refused: ${code}` } } }return { status: 200, body: { success: true, data: {} } }}- return { status: 200, body: { success: true, data: path.includes('/hosts/') ? rows : [] } }+ return { status: 200, body: { success: true, data: path.includes('/hosts/') ? hostForm(rows, { tabs: ['tab'] }) : [] } }})const core = fakeCore({ dataDir: dir, account: { backend: call, machineName: vi.fn(() => 'MacBook Pro') } })const prepareTeam = vi.fn(async () => ({ ok: true, state: 'ready', cwd: '/Users/harnessteam/harnesses/swarms/own', engines: ['claude'], maxAgents: 8, scope: 'swarm' }))@@ -1220,8 +1301,8 @@ describe('built-in skill text after a CLI update', () => {await Promise.resolve()inFlight--const request = body as any- if (path.includes('/hosts/')) return { status: 200, body: { data: agents.map(agent => ({ tabId: 'tab', agent, ...(skillMode ? { skillMode } : {}),- ...(agent.id in rowRoles ? { role: rowRoles[agent.id] } : {}) })) } }+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm(agents.map(agent => ({ tabId: 'tab', agent, ...(skillMode ? { skillMode } : {}),+ ...(agent.id in rowRoles ? { role: rowRoles[agent.id] } : {}) })), { tabs: ['tab'] }) } }const role = /^\/api\/super-tabs\/tab\/projects\/pilot\/roles\/([a-z0-9]+)$/.exec(path)?.[1]if (role) {fetched.push(role)@@ -1237,7 +1318,7 @@ describe('built-in skill text after a CLI update', () => {if (prior === undefined) { receipts.set(request.operationId, same); sent.push(request) }return { status: 200, body: { data: {} } }}- return { status: 200, body: { data: { state: { agents, conversations: groups } } } }+ return { status: 200, body: { data: swarmReply(path, { agents, conversations: groups }) } }})// The refresh runs beside the poll: wait until no backend call is in flight and the host's own work has had its turn.const pass = async (host = t.open(), advance = 0) => {@@ -1310,7 +1391,7 @@ describe('built-in skill text after a CLI update', () => {// meanwhile must not get its old text installed, nor a re-read notice after the backend's role-gone one.it.each([['its text is fetched', (path: string) => path.includes('/roles/'), false],- ['its notice is about to be sent', (path: string, body: any) => path.includes('?asAgentId=a-lead') && !body, true],+ ['its notice is about to be sent', (path: string, body: any) => path.includes('asAgentId=a-lead') && !body, true],])('drops a refresh whose role is gone while %s', async (_case, match, installed) => {const f = syncFixture(false, 'default')custom(f, 'Plan the work.\n')@@ -1492,7 +1573,7 @@ function lifeFixture(rows: Record<string, unknown>[], options: SuperTabHostOptiot.core.agents.closeMember = closeMembert.core.account.backend = async (_method, path, body) => {if ((body as any)?.command) { commands.push(body as Record<string, unknown>); return { status: 200, body: { data: {} } } }- if (path.includes('/hosts/')) return { status: 200, body: { data: rows } }+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm(rows, { tabs: ['tab'] }) } }return { status: 200, body: { data: [] } }}const poll = async (advance = 0) => { t.wait(advance); await host.tick(); for (let i = 0; i < 5; i++) await new Promise(resolve => setImmediate(resolve)) }@@ -1665,11 +1746,11 @@ describe('a machine its owner removed from a Swarm', () => {mkdirSync(folder, { recursive: true }); mkdirSync(other, { recursive: true })const sent: unknown[] = []vi.mocked(t.call).mockImplementation(async (method, path, body) => {- if (path.includes('/hosts/')) return { status: 200, body: { success: true, data: [+ if (path.includes('/hosts/')) return { status: 200, body: { success: true, data: hostForm([{ tabId: 'tab', cleanup: { machineId: 'machine-1', removalId: 'removal' } },- { tabId: 'other-tab', cleanup: { machineId: 'machine-2', removalId: 'theirs' } }] } }+ { tabId: 'other-tab', cleanup: { machineId: 'machine-2', removalId: 'theirs' } }]) } }if (method === 'POST') sent.push(body)- return { status: 200, body: { success: true, data: method === 'GET' ? { state: { starts: [] } } : { revision: 1 } } }+ return { status: 200, body: { success: true, data: method === 'GET' ? swarmReply(path, { starts: [] }) : { parts: [] } } }})const host = t.open()await host.tick()diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.tsindex f88fed23f..7704cdd89 100644--- a/cli/src/superTabs/host.ts+++ b/cli/src/superTabs/host.ts@@ -1,5 +1,5 @@import { OBSERVER_VALID_MS, publishObservers } from './observers.js'-import { ContributedMachines } from './machines.js'+import { ContributedMachines, type MachineDeps } from './machines.js'import { SwarmGrids } from './swarmGrids.js'import { retainContributions } from './retention.js'import { configurationObservation } from './configuration.js'@@ -19,26 +19,15 @@ import { prepareContribution, prepareTeamContribution } from './contribution.js'import { hostname } from 'node:os'import { replacementObservations } from './replacements.js'import { TerminalHost } from './terminal.js'+import { HostFeed } from './hostFeed.js'+import { SwarmReads } from './swarmReads.js'+import { UPDATE_REQUIRED } from './readContract.js'type Json = Record<string, unknown>-export class SuperTabHostError extends Error {- constructor(readonly code: string, message: string, readonly status = 503) { super(message) }-}-export { identifier, object } from './wire.js'-import { ENDED_WORK, identifier, object } from './wire.js'+export { backend, identifier, object, SuperTabHostError } from './wire.js'+import { backend, ENDED_WORK, identifier, object, SuperTabHostError } from './wire.js'import { recordSwarmSkillNotice, refreshSwarmSkill, type SkillRefresh, type SwarmSkillGrant, type SwarmSkillMode } from '../lib/swarmSkills.js'-/** The core signs each request. Neither the service nor its journal holds an account credential. */-export async function backend(core: CoreApi, method: string, path: string, body?: unknown): Promise<unknown> {- const reply = await core.account.backend(method, path, body)- if (reply.status < 200 || reply.status >= 300 || reply.body.success === false) {- const error = object(reply.body.error)- throw new SuperTabHostError(String(error.code ?? reply.body.code ?? 'BACKEND_UNAVAILABLE'),- String(error.message ?? reply.body.message ?? 'Could not reach this Super Tab.'), reply.status)- }- return reply.body.data-}-/** The skills of a group's project in a tab state: a group from before projects is in the first, and a project from before* modes, or a Swarm from before projects, is orchestration. */export function groupSkillMode(state: Record<string, unknown>, group: Record<string, unknown> | undefined): SwarmSkillMode {@@ -46,20 +35,22 @@ export function groupSkillMode(state: Record<string, unknown>, group: Record<strreturn project?.skillMode === 'default' ? 'default' : 'orchestration'}+/** Where a machine reads its Swarms: the host form of its rosters, and each Swarm by parts (design 2026-10-26 section 5.3). */+export interface SwarmSources { feed: HostFeed; reads: SwarmReads }+/** Restart/resume can include stopped harnesses, so the live process list is not membership proof.* Re-read the exact machine roster and its groups; a removed contribution must never adopt a skill. */-export async function swarmRoleFor(core: CoreApi, machineId: string, harnessId: string): Promise<SwarmSkillGrant | null> {+export async function swarmRoleFor(sources: SwarmSources, harnessId: string): Promise<SwarmSkillGrant | null> {+ const machineId = sources.feed.machineIdif (!identifier(machineId) || !identifier(harnessId)) return null- const rows = await backend(core, 'GET', `/api/super-tabs/hosts/${machineId}`)- if (!Array.isArray(rows)) return null+ const rows = (await sources.feed.refresh()).rosterconst grants = await Promise.all(rows.map(object).filter(row => {const agent = object(row.agent)return identifier(row.tabId) && identifier(agent.id) && agent.machineId === machineId&& agent.harnessId === harnessId && row.stopRequested !== true}).map(async row => {const target = object(row.agent)- const answer = object(await backend(core, 'GET', `/api/super-tabs/${row.tabId}?asAgentId=${target.id}`))- const state = object(answer.state)+ const { state } = await sources.reads.read(String(row.tabId), String(target.id))const agent = Array.isArray(state.agents) && state.agents.map(object).find(agent => agent.id === target.id&& agent.harnessId === harnessId && agent.machineId === machineId && agent.workDecision !== 'stop')if (!agent) return null@@ -84,7 +75,8 @@ interface Entry {}interface Journal { version: 1; machineId: string; entries: Record<string, Entry> }/** `skillMode` is the agent's project's skills; a row without it (an older backend, a project from before modes) is orchestration. */-interface HostAgent { tabId: string; agent: { id: string; harnessId: string; machineId: string; releaseId?: string }; skillMode?: unknown; lead?: unknown; role?: unknown }+interface HostAgent { tabId: string; agent: { id: string; harnessId: string; machineId: string; releaseId?: string }; skillMode?: unknown; lead?: unknown; role?: unknown+ leadsConversationId?: unknown }export interface SuperTabHostOptions {now?: () => numberwrite?: (file: string, journal: Journal) => void@@ -98,6 +90,10 @@ export interface SuperTabHostOptions {agentCommand?: (core: CoreApi, machineId: string) => Promise<string>/** The Swarm start this machine made of a harness (superTabs/reservations.ts), or null. */startReceipt?: (harnessId: string) => string | null+ /** The machine's host form and Swarm reads, shared with the service's other readers (superTabs/service.ts). */+ sources?: SwarmSources+ /** What the contributed-machine executor reaches the local daemon with (superTabs/machines.ts), for a spec. */+ machines?: Partial<MachineDeps>}const defaultAgentCommand = (core: CoreApi, machineId: string) => agentCommandPrefix(core.daemon, machineId,@@ -126,6 +122,10 @@ function skillSetOf(target: HostAgent): string {return role ? JSON.stringify([role.projectId, role.id, role.version, role.name]) : 'none'}const JOIN_RETRY_MAX_MS = 30 * 60_000+/** A server that no longer serves this client's reads (HTTP 426): said once, then asked again a minute later (design 5.1). */+const UPDATE_BACKOFF_MS = 60_000+/** How old the host form may be for the stop check, which runs every 5 s beside the one-second tick that reads it. */+const STOPS_FRESH_MS = 5_000/** Refusals no retry can change while this host runs: the Swarm has all its machines, or this account does not own it. */const JOIN_FINAL = new Set(['MACHINES_FULL', 'OWNER_REQUIRED'])/** A Lead's reopen that failed (an engine that cannot start, a busy pane) waits this long, doubling up to half an hour, so a@@ -167,6 +167,8 @@ export class SuperTabHost {private readonly log: (message: string) => voidprivate retentionError: string | null = nullprivate readonly observers: typeof publishObservers+ /** Whether a session still runs on this machine: a confidential session's mark stays until it closes (observers.ts). */+ private readonly stillRuns = (harnessId: string) => !!this.core.agents.byAgent(harnessId)/** Share was asked to run once a roster here first named someone to show an agent to. */private shareWoken = falseprivate readonly attachedFiles: typeof attachedFiles@@ -204,6 +206,7 @@ export class SuperTabHost {private timer: ReturnType<typeof setTimeout> | null = nullprivate native: NativeRecorder | null = nullprivate machines: ContributedMachines | null = null+ private readonly machineDeps: Partial<MachineDeps>private grids: SwarmGrids | null = null/** The waits last handed to the core (superTabs/attention.ts); null until the first roster, which is always handed* over whole, so a restarted service closes what its predecessor raised and no longer holds. */@@ -227,9 +230,13 @@ export class SuperTabHost {private readonly keepAlives = new Map<string, { running: boolean; failures: number; retryAt: number; reason?: string }>()/** Per session the backend ends: a close or acknowledgement in progress, how far it got, and when the next try may run. */private readonly endings = new Map<string, { running: boolean; closed: boolean; acked: boolean; failures: number; retryAt: number }>()- /** Per agent that leads nothing (tab:agent): the conversations its own view of the tab lists, and the deliveries refused. */- private readonly readable = new Map<string, Set<string>>()+ /** Deliveries withheld from an agent that leads nothing, each said once. */private readonly unreadable = new Set<string>()+ /** The machine's host form and Swarm reads: the tick, stops, releases and skill notices read Swarms only through them. */+ private readonly sources: SwarmSources+ /** Until when the host waits after an update-required answer, and whether it has said so. */+ private updateUntil = 0+ private updateSaid = false/** A Lead's reads of and typing into this machine's agents' terminals, and the stuck and usage-limit alerts. */private readonly terminal: TerminalHost@@ -239,6 +246,7 @@ export class SuperTabHost {this.observers = options.observers ?? publishObserversthis.attachedFiles = options.attachedFiles ?? attachedFilesthis.prepareContribution = options.prepareContribution ?? prepareContribution+ this.machineDeps = options.machines ?? {}this.prepareTeam = options.prepareTeam ?? ((core, input) => prepareTeamContribution(core, input))this.agentCommand = options.agentCommand ?? defaultAgentCommandthis.startReceipt = options.startReceipt ?? (() => null)@@ -246,6 +254,7 @@ export class SuperTabHost {this.write = options.write ?? writeJournalthis.log = options.log ?? (message => console.warn(`[super-tabs] ${message}`))this.terminal = new TerminalHost(core, machineId, { now: this.now, log: this.log })+ this.sources = options.sources ?? { feed: new HostFeed(core, machineId, { now: this.now }), reads: new SwarmReads(core) }this.journal = { version: 1, machineId, entries: {} }if (existsSync(this.file)) {const raw = readFileSync(this.file, 'utf8')@@ -295,7 +304,7 @@ export class SuperTabHost {this.authorized.clear()// An empty roster in force, which Share reads as everyone gone and withdraws their invitations; a lapsed one// would only pause their views (superTabs/observers.ts `known`).- try { this.observers(this.core.dataDir, this.machineId, [], this.now() + OBSERVER_VALID_MS) } catch { /* The old snapshot expires. */ }+ try { this.observers(this.core.dataDir, this.machineId, [], this.now() + OBSERVER_VALID_MS, this.stillRuns) } catch { /* The old snapshot expires. */ }// Signed out or another machine: this host's alerts are no longer anyone's. A core that is gone heard nothing, and// the next host's first roster replaces them anyway.if (this.attention !== null && this.attention !== '[]') {@@ -312,9 +321,13 @@ export class SuperTabHost {this.native ??= new NativeRecorder(this.core, this.machineId)return this.native.prepare(tabId, contextId, renew, closed)}+ /** The machine report sends when each agent's screen last changed, from this host's own screen reads. */+ private contributed(): ContributedMachines {+ return this.machines ??= new ContributedMachines(this.core, this.machineId,+ { ...this.machineDeps, sources: this.sources, progress: ids => this.terminal.progressOf(ids) })+ }private pollMachines() {- this.machines ??= new ContributedMachines(this.core, this.machineId)- void this.machines.tick().catch(error => this.log(error instanceof Error ? error.message : String(error)))+ void this.contributed().tick().catch(error => this.log(error instanceof Error ? error.message : String(error)))this.grids ??= new SwarmGrids(this.core, this.machineId)void this.grids.tick().catch(error => this.log(`Swarm grid: ${error instanceof Error ? error.message : String(error)}`))}@@ -325,23 +338,28 @@ export class SuperTabHost {void this.native.flush().catch(failed)}tick(): Promise<void> {- if (this.stopped) return Promise.resolve()- return this.running ??= this.poll().catch(error => {- this.log(error instanceof Error ? error.message : String(error))- }).finally(() => { this.running = null })+ if (this.stopped || this.now() < this.updateUntil) return Promise.resolve()+ return this.running ??= this.poll().catch(error => this.failed(error)).finally(() => { this.running = null })+ }+ /** Logged, except that an update-required answer is said once and then waits a minute, rather than every second. */+ private failed(error: unknown): void {+ if (error instanceof SuperTabHostError && error.code === UPDATE_REQUIRED) {+ this.updateUntil = this.now() + UPDATE_BACKOFF_MS+ if (this.updateSaid) return+ this.updateSaid = true+ }+ this.log(error instanceof Error ? error.message : String(error))}/** A saved native stop, never a timeout or missing live snapshot, releases* ownership. This also runs for contributions withdrawn while working. */reconcileStops(): Promise<void> {- if (this.stopped || !this.core.agents.stopped || this.now() < this.nextStopsAt) return Promise.resolve()- return this.stopsRunning ??= this.checkStops().catch(error => {- this.log(error instanceof Error ? error.message : String(error))- }).finally(() => { this.stopsRunning = null; this.nextStopsAt = this.now() + 5_000 })+ if (this.stopped || !this.core.agents.stopped || this.now() < Math.max(this.nextStopsAt, this.updateUntil)) return Promise.resolve()+ return this.stopsRunning ??= this.checkStops().catch(error => this.failed(error))+ .finally(() => { this.stopsRunning = null; this.nextStopsAt = this.now() + 5_000 })}private async checkStops(): Promise<void> {- const rows = await backend(this.core, 'GET', `/api/super-tabs/hosts/${this.machineId}/assignments`)- if (!Array.isArray(rows)) throw new Error('Invalid Super Tab execution list.')+ const rows = (await this.sources.feed.current(STOPS_FRESH_MS)).assignmentsfor (const value of rows) {if (this.stopped) returnconst work = object(value)@@ -368,7 +386,7 @@ export class SuperTabHost {this.releaseAttempts.set(key, attempt)this.releases.add(key)try {- const current = object(object(await backend(this.core, 'GET', `/api/super-tabs/${tabId}?asAgentId=${agent.id}`)).state)+ const current = (await this.sources.reads.read(tabId, agent.id)).stateconst member = Array.isArray(current.agents) ? current.agents.map(object).find(a => a.id === agent.id) : undefinedif (this.stopped || member?.workDecision !== 'stop' || member.harnessId !== agent.harnessId || member.machineId !== this.machineId || member.releaseId !== agent.releaseId) returnif (!Array.isArray(current.conversations) || current.conversations.map(object).some(c => {@@ -499,9 +517,8 @@ export class SuperTabHost {return this.core.turns.leaseDeliveries('superTabs', Object.fromEntries(this.authorized))}private async poll(): Promise<void> {- const data = await backend(this.core, 'GET', `/api/super-tabs/hosts/${this.machineId}`)+ const data = (await this.sources.feed.refresh()).rosterif (this.stopped) return- if (!Array.isArray(data)) throw new Error('Invalid Super Tab host roster.')// Multiply was closed by the ordinary 30-minute idle cleanup while still a// shared member. Membership outlives its task, terminal view and host process.// Retention only pauses cleanup when it fails; it must never hold up delivery.@@ -514,7 +531,7 @@ export class SuperTabHost {this.retentionError = message}// Valid from this answer until the next is due, slow reads included, so it never lapses between two reads.- this.observers(this.core.dataDir, this.machineId, data, this.now() + OBSERVER_VALID_MS)+ this.observers(this.core.dataDir, this.machineId, data, this.now() + OBSERVER_VALID_MS, this.stillRuns)this.wakeShare(data)this.publishAttention(data)this.joinSwarms(data)@@ -586,7 +603,7 @@ export class SuperTabHost {// Checked before anything is typed: a new delivery, or one held while its agent may since have stopped leading. A// claimed one with no journal is never typed, only reported as uncertain; a delivered one only acknowledged.const entry = this.journal.entries[delivery.id]- if ((entry ? entry.stage === 'prepared' : !delivery.claimId) && !await this.mayRead(target, delivery)) continue+ if ((entry ? entry.stage === 'prepared' : !delivery.claimId) && !this.mayRead(target, delivery)) continuetry { await this.accept(target, delivery, path) } catch (error) {// Answered (or resolved by a person) between the roster read and this call: nothing is owed, and the// agent's other deliveries go on.@@ -603,7 +620,6 @@ export class SuperTabHost {// A Lead the roster no longer marks (its project deleted) is never reopened again.for (const [harnessId, state] of this.keepAlives) if (!leads.has(harnessId) && !state.running) this.keepAlives.delete(harnessId)for (const [key, state] of this.endings) if (!ended.has(key) && !state.running) this.endings.delete(key)- for (const key of this.readable.keys()) if (!running.some(target => `${target.tabId}:${target.agent.id}` === key)) this.readable.delete(key)for (const deliveryId of this.unreadable) if (!seen.has(deliveryId)) this.unreadable.delete(deliveryId)for (const deliveryId of this.files.keys()) if (!this.journal.entries[deliveryId]) this.files.delete(deliveryId)for (const entry of Object.values(this.journal.entries)) {@@ -732,8 +748,8 @@ export class SuperTabHost {/** False when nothing was sent: no open group, or the roster has moved on (`current`) and the next refresh decides. */private async tellSkill(target: HostAgent, refresh: SkillRefresh, current: () => boolean): Promise<boolean> {const id = target.agent.id- const answer = object(await backend(this.core, 'GET', `/api/super-tabs/${target.tabId}?asAgentId=${id}`))- const groups = (Array.isArray(object(answer.state).conversations) ? object(answer.state).conversations as unknown[] : []).map(object)+ const { state } = await this.sources.reads.read(target.tabId, id)+ const groups = (Array.isArray(state.conversations) ? state.conversations : []).map(object).filter(group => group.archived !== true && identifier(group.id) && Array.isArray(group.agentIds) && group.agentIds.includes(id))const group = groups.find(g => g.leadId === id) ?? groups.find(g => object(g.assignment).agentId === id) ?? groups[0]if (!group || !current()) return false@@ -770,7 +786,7 @@ export class SuperTabHost {join.running = truethis.joins.set(tabId, join)void (async () => {- const prepared = await this.prepareContribution(this.core, { tabId, scope: 'swarm' })+ const prepared = await this.prepareContribution(this.core, { tabId, scope: 'swarm' }, { reads: this.sources.reads })await backend(this.core, 'POST', `/api/super-tabs/${tabId}/commands`, { operationId: randomUUID(), command: {type: 'machine.contribute', machineId: this.machineId, name: this.core.account.machineName() ?? hostname(),cwd: prepared.cwd, scope: 'swarm', engines: prepared.engines, maxAgents: prepared.maxAgents, ifMissing: true } })@@ -822,8 +838,7 @@ export class SuperTabHost {for (const row of rows.map(object)) {const cleanup = object(row.cleanup)if (!identifier(row.tabId) || cleanup.machineId !== this.machineId || !identifier(cleanup.removalId)) continue- this.machines ??= new ContributedMachines(this.core, this.machineId)- void this.machines.clean(row.tabId, cleanup.removalId).catch(error => this.log(error instanceof Error ? error.message : String(error)))+ void this.contributed().clean(row.tabId, cleanup.removalId).catch(error => this.log(error instanceof Error ? error.message : String(error)))}}@@ -866,16 +881,11 @@ export class SuperTabHost {}/** Leads see each other's work and talk (spec 2026-10-23): the Leads conversation reaches Leads alone. The server- * delivers it only to them; an agent that leads nothing is also given only what its own view of the tab lists. */- private async mayRead(target: HostAgent, delivery: Json): Promise<boolean> {- if (target.lead === true) return true- const key = `${target.tabId}:${target.agent.id}`- if (this.readable.get(key)?.has(String(delivery.conversationId))) return true- const state = object(object(await backend(this.core, 'GET', `/api/super-tabs/${target.tabId}?asAgentId=${target.agent.id}`)).state)- const readable = new Set((Array.isArray(state.conversations) ? state.conversations.map(object) : [])- .filter(c => identifier(c.id) && c.kind !== 'leads' && c.id !== state.leadsConversationId).map(c => c.id as string))- this.readable.set(key, readable)- if (readable.has(String(delivery.conversationId))) return true+ * delivers it only to them; an agent that leads nothing is also never given it here. The roster names the Leads+ * conversation, so this needs no read of the Swarm (design 2026-10-26 section 5.3); the server's delivery rules decide+ * every other conversation, a private one's audience included. */+ private mayRead(target: HostAgent, delivery: Json): boolean {+ if (target.lead === true || delivery.conversationId !== target.leadsConversationId) return trueif (!this.unreadable.has(delivery.id as string)) {this.unreadable.add(delivery.id as string)this.log(`Withheld delivery ${String(delivery.id)}: it is not in a conversation ${target.agent.harnessId} can read.`)diff --git a/cli/src/superTabs/hostFeed.spec.ts b/cli/src/superTabs/hostFeed.spec.tsnew file mode 100644index 000000000..b010bacbc--- /dev/null+++ b/cli/src/superTabs/hostFeed.spec.ts@@ -0,0 +1,144 @@+import { describe, expect, it, vi } from 'vitest'+import type { CoreApi } from '../core/api.js'+import { fakeCore } from '../testing/fakeCore.js'+import { FIXTURE, ok, readFixture, refused, type BackendReply } from './fixtures/read/index.js'+import { HostFeed } from './hostFeed.js'++type Json = Record<string, unknown>+const M = FIXTURE.machineId, T = FIXTURE.tabId, T9 = FIXTURE.removedTabId+const FORM = `/api/super-tabs/hosts/${M}/changes`+/** Each read as the feed asked it: a GET while it holds nothing, then a POST that names the Swarms it holds (their etags). */+const FULL = `${FORM}?full=1`, FULL_HELD = 'POST full'+const SINCE = (cursor: string) => `POST since ${cursor}`+const C0 = 'eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjowfQ', C1 = 'eyJ2IjoyLCJ0IjoxNzkzMDEwMDc3Mzc1LCJlIjowfQ'++function feedOf(replies: BackendReply[]) {+ let now = 1_000_000+ const call = vi.fn<CoreApi['account']['backend']>(async () => replies.length > 1 ? replies.shift()! : replies[0])+ const feed = new HostFeed(fakeCore({ account: { backend: call } }), M, { now: () => now })+ const paths = () => call.mock.calls.map(([method, path, body]) => {+ if (method === 'GET') return path+ const sent = body as Json+ if (path !== FORM) return `POST ${path}`+ return sent.full === true ? FULL_HELD : `POST since ${String(sent.cursor)}`+ })+ const held = () => call.mock.calls.filter(([method]) => method === 'POST').map(([, , body]) => (body as Json).held)+ return { call, feed, paths, held, later: (ms: number) => { now += ms } }+}+const agents = (rows: Json[]) => rows.map(row => `${String(row.tabId).slice(-1)}:${row.cleanup ? 'cleanup' : String((row.agent as Json).id).slice(-1)}`)++describe('the host form of a machine\'s Swarms', () => {+ it('reads every Swarm in full first: the roster, the pools and the assignments, Swarm by Swarm', async () => {+ const { feed, paths } = feedOf([ok(readFixture('host-full'))])+ const read = await feed.refresh()+ expect(agents(read.roster)).toEqual(['1:1', '1:2', '9:cleanup'])+ expect(read.roster[0]).toMatchObject({ tabId: T, lead: true, leadsConversationId: FIXTURE.leadsGroup, lastChangedAt: 1793010101002 })+ expect(read.pools).toEqual([readFixture<{ tabs: Json[] }>('host-full').tabs[0].pool])+ expect(read.assignments).toEqual([{ tabId: T, assignmentId: 'w0000000000000000000001', harnessId: FIXTURE.builderHarness }])+ expect(paths()).toEqual([FULL])+ })++ it('then reads what changed: a returned Swarm\'s rows are replaced, a removed Swarm leaves, the others stay', async () => {+ const { feed, paths } = feedOf([ok(readFixture('host-full')), ok(readFixture('host-changes')), ok(readFixture('host-quiet'))])+ await feed.refresh()+ const read = await feed.refresh()+ expect(agents(read.roster)).toEqual(['1:1', '1:2'])+ expect(read.roster[1]).toMatchObject({ attention: { status: 'needs_human' } })+ expect(read.pools).toMatchObject([{ tabId: T, starts: [] }])+ const quiet = await feed.refresh()+ expect(quiet.roster).toEqual(read.roster)+ expect(paths()).toEqual([FULL, SINCE(C0), SINCE(C1)])+ })++ it('reads in full again at least every minute, which drops a Swarm no longer listed', async () => {+ const shrunk = { ...readFixture<Json>('host-full'), tabs: readFixture<{ tabs: Json[] }>('host-full').tabs.slice(1) }+ const { feed, paths, later } = feedOf([ok(readFixture('host-full')), ok(readFixture('host-quiet')), ok(shrunk)])+ await feed.refresh()+ later(59_999)+ await feed.refresh()+ later(1)+ expect(agents((await feed.refresh()).roster)).toEqual(['9:cleanup'])+ expect(paths()).toEqual([FULL, SINCE(C0), FULL_HELD])+ })++ // Review round 1: the server answers in full when the cursor is bad or too old, with no list of removed Swarms.+ it('takes a full answer to a read by change as full: Swarms it omits are dropped, and the minute starts again', async () => {+ const forced = { ...readFixture<Json>('host-full'), cursor: 'forced', tabs: readFixture<{ tabs: Json[] }>('host-full').tabs.slice(0, 1) }+ const { feed, paths, later } = feedOf([ok(readFixture('host-full')), ok(forced), ok(readFixture('host-quiet'))])+ await feed.refresh()+ later(50_000)+ expect(agents((await feed.refresh()).roster)).toEqual(['1:1', '1:2'])+ later(50_000)+ await feed.refresh()+ expect(paths()).toEqual([FULL, SINCE(C0), SINCE('forced')])+ })++ it('keeps its rows and cursor when a read fails, and starts in full again when the first one did', async () => {+ const { feed, paths } = feedOf([refused(503, 'SWARM_BUSY', 'Busy'), ok(readFixture('host-full')), refused(502, 'BAD_GATEWAY'), ok(readFixture('host-quiet'))])+ await expect(feed.refresh()).rejects.toMatchObject({ code: 'SWARM_BUSY' })+ await feed.refresh()+ await expect(feed.refresh()).rejects.toMatchObject({ status: 502 })+ expect(agents((await feed.refresh()).roster)).toEqual(['1:1', '1:2', '9:cleanup'])+ expect(paths()).toEqual([FULL, FULL, SINCE(C0), SINCE(C0)])+ })++ it('shares one read among callers that ask at once, and answers from the last read while it is fresh enough', async () => {+ const { feed, paths, later } = feedOf([ok(readFixture('host-full')), ok(readFixture('host-quiet'))])+ await Promise.all([feed.refresh(), feed.refresh(), feed.current(5_000)])+ later(4_999)+ await feed.current(5_000)+ expect(paths()).toEqual([FULL])+ later(1)+ await feed.current(5_000)+ expect(paths()).toEqual([FULL, SINCE(C0)])+ })++ it('takes no rows from a Swarm whose lists are malformed, and still those of the others', async () => {+ const form = readFixture<{ tabs: Json[] }>('host-full')+ const { feed } = feedOf([ok({ ...form, tabs: [{ tabId: 'odd', roster: {}, pool: 'none', assignments: null }, ...form.tabs] })])+ const read = await feed.refresh()+ expect(agents(read.roster)).toEqual(['1:1', '1:2', '9:cleanup'])+ expect(read.pools).toHaveLength(1)+ expect(read.assignments).toHaveLength(1)+ })++ // The Lead's ruling on #1726: an active Swarm re-sent its whole rows every tick. The host names the rows it holds, by their+ // etag, and the server answers a Swarm whose rows match with no rows at all.+ it('names the rows it holds, and keeps them for a Swarm the server answers unchanged', async () => {+ const { feed, paths, held } = feedOf([ok(readFixture('host-full')), ok(readFixture('host-unchanged'))])+ await feed.refresh()+ const read = await feed.refresh()+ expect(paths()).toEqual([FULL, SINCE(C0)])+ expect(held()).toEqual([{ [T]: 'etag-tab1-a', [T9]: 'etag-tab9-a' }])+ expect(read.roster.filter(row => row.tabId === T)).toEqual(readFixture<{ tabs: Json[] }>('host-full').tabs[0].roster)+ expect(read.pools).toEqual([readFixture<{ tabs: Json[] }>('host-full').tabs[0].pool])+ expect(read.roster.find(row => row.tabId === T9)).toMatchObject({ cleanup: { removalId: 'r0000000000000000000002' } })+ await feed.refresh()+ expect(held().at(-1)).toEqual({ [T]: 'etag-tab1-a', [T9]: 'etag-tab9-b' })+ })++ it('names what it holds in the minute\'s full read too: an unchanged Swarm keeps its rows, one left out is dropped', async () => {+ const unchanged = { format: 2, full: true, cursor: 'after-full', removedTabIds: [], tabs: [{ tabId: T, etag: 'etag-tab1-a', lastChangedAt: 1793010101002, unchanged: true }] }+ const { feed, paths, held, later } = feedOf([ok(readFixture('host-full')), ok(unchanged)])+ await feed.refresh()+ later(60_000)+ const read = await feed.refresh()+ expect(paths()).toEqual([FULL, FULL_HELD])+ expect(held()).toEqual([{ [T]: 'etag-tab1-a', [T9]: 'etag-tab9-a' }])+ expect(agents(read.roster)).toEqual(['1:1', '1:2'])+ })++ it('forgets an unchanged answer for a Swarm it does not hold, so the next read asks for it whole', async () => {+ const stray = { format: 2, full: false, cursor: 'stray', removedTabIds: [], tabs: [{ tabId: 'f1a5c0de000000000000000s', etag: 'x', lastChangedAt: 1, unchanged: true }] }+ const { feed, held } = feedOf([ok(readFixture('host-full')), ok(stray), ok(readFixture('host-quiet'))])+ await feed.refresh()+ expect(agents((await feed.refresh()).roster)).toEqual(['1:1', '1:2', '9:cleanup'])+ await feed.refresh()+ expect(held().at(-1)).toEqual({ [T]: 'etag-tab1-a', [T9]: 'etag-tab9-a' })+ })++ it('tells the person to update Harness when the server answers in a format it cannot read', async () => {+ const { feed } = feedOf([ok({ ...readFixture<Json>('host-full'), format: 3 })])+ await expect(feed.refresh()).rejects.toMatchObject({ code: 'UPDATE_REQUIRED', status: 426 })+ })+})diff --git a/cli/src/superTabs/hostFeed.ts b/cli/src/superTabs/hostFeed.tsnew file mode 100644index 000000000..895bca0f6--- /dev/null+++ b/cli/src/superTabs/hostFeed.ts@@ -0,0 +1,80 @@+/**+ * What a machine's Swarms want of its host, read as the host form (design 2026-10-26-swarm-state-parts section 4.10): for+ * each Swarm its roster rows, its pool of this machine and the assignments running here. It replaces the three rosters the+ * host, the machine pass and the GitHub tokens each read on their own, every one loading up to 100 whole Swarms every 1–5 s.+ * In between, only the Swarms with a change that matters to this machine come back; a full read at start and at least every+ * minute also catches a share or billing change, which lives outside the parts.+ */+import type { CoreApi } from '../core/api.js'+import type { HostChanges, HostChangesRequest, HostTabRows } from './readContract.js'+import { backend, object, readable } from './wire.js'++type Json = Record<string, unknown>+export interface HostRead { roster: Json[]; pools: Json[]; assignments: Json[] }++/** The bound on a roster that lags a revoked share (design section 8, Q2). */+export const HOST_FULL_MS = 60_000++export class HostFeed {+ private readonly now: () => number+ private readonly backend: typeof backend+ /** Each Swarm's rows as last returned, in the order the server first listed them. */+ private tabs = new Map<string, HostTabRows>()+ private cursor: string | null = null+ private fullAt = -Infinity+ private readAt = -Infinity+ private running: Promise<HostRead> | null = null++ constructor(private readonly core: CoreApi, readonly machineId: string, options: { now?: () => number; backend?: typeof backend } = {}) {+ this.now = options.now ?? Date.now+ this.backend = options.backend ?? backend+ }++ /** One read at a time: callers that ask while it runs get its answer. */+ refresh(): Promise<HostRead> {+ return this.running ??= this.read().finally(() => { this.running = null })+ }++ /** The last read while it is at most `maxAgeMs` old, else a new one: for readers off the host's own one-second tick. */+ current(maxAgeMs: number): Promise<HostRead> {+ if (!this.running && this.now() - this.readAt < maxAgeMs) return Promise.resolve(this.snapshot())+ return this.refresh()+ }++ private async read(): Promise<HostRead> {+ const askFull = this.cursor === null || this.now() - this.fullAt >= HOST_FULL_MS+ const startedAt = this.now()+ const form = `/api/super-tabs/hosts/${this.machineId}/changes`+ // The rows it holds, by their etag: a Swarm whose rows still match comes back with none, so an active Swarm no longer+ // costs its whole rows every second (the Lead's ruling on #1726). A host that holds nothing asks as before.+ const held = Object.fromEntries([...this.tabs].flatMap(([tabId, tab]) => typeof tab.etag === 'string' ? [[tabId, tab.etag]] : []))+ const answer = readable<HostChanges>(Object.keys(held).length+ ? await this.backend(this.core, 'POST', form, (askFull ? { full: true, held } : { cursor: this.cursor!, held }) satisfies HostChangesRequest)+ : await this.backend(this.core, 'GET', `${form}?${askFull ? 'full=1' : `cursor=${this.cursor}`}`))+ // The answer says what it is: the server answers a bad or too old cursor in full, with no removed Swarms (review round 1).+ const full = answer.full === true+ const tabs = full ? new Map<string, HostTabRows>() : new Map(this.tabs)+ for (const tabId of answer.removedTabIds ?? []) tabs.delete(tabId)+ for (const tab of answer.tabs) {+ if (!('unchanged' in tab)) { tabs.set(tab.tabId, tab); continue }+ // Unchanged keeps the rows held. One it does not hold (it never named it) is dropped, and comes back whole next time.+ const kept = this.tabs.get(tab.tabId)+ if (kept) tabs.set(tab.tabId, { ...kept, etag: tab.etag, lastChangedAt: tab.lastChangedAt })+ else tabs.delete(tab.tabId)+ }+ this.tabs = tabs+ this.cursor = answer.cursor+ if (full) this.fullAt = startedAt+ this.readAt = this.now()+ return this.snapshot()+ }++ /** Every Swarm's rows in one list each; a Swarm whose lists are not lists gives none, and never stops the others'. */+ private snapshot(): HostRead {+ const tabs = [...this.tabs.values()]+ const rows = (value: unknown) => Array.isArray(value) ? value.map(object) : []+ const isRecord = (value: unknown): value is Json => !!value && typeof value === 'object' && !Array.isArray(value)+ return { roster: tabs.flatMap(tab => rows(tab.roster)), pools: tabs.flatMap(tab => isRecord(tab.pool) ? [tab.pool] : []),+ assignments: tabs.flatMap(tab => rows(tab.assignments)) }+ }+}diff --git a/cli/src/superTabs/machines.spec.ts b/cli/src/superTabs/machines.spec.tsindex d366666e6..64d01761c 100644--- a/cli/src/superTabs/machines.spec.ts+++ b/cli/src/superTabs/machines.spec.ts@@ -6,9 +6,12 @@ import { join } from 'node:path'import { afterEach, describe, expect, it, vi } from 'vitest'import type { RegisteredSession } from '../lib/registry.js'import { fakeCore } from '../testing/fakeCore.js'-import { apisOn, ContributedMachines, liveOn, localModelsStamp, offered, refusedOn, servedOn, sharedWith, swarmWorktreesFile } from './machines.js'+import { apisOn, ContributedMachines, createQuietGit, liveOn, localModelsStamp, offered, refusedOn, servedOn, sharedWith, swarmWorktreesFile } from './machines.js'import { SuperTabHostError } from './host.js'import { startAgent } from './start.js'+import { hostForm, swarmReply } from './fixtures/read/index.js'+import { HostFeed } from './hostFeed.js'+import { SwarmReads } from './swarmReads.js'import type { PrivacyObservation } from '../team/privacy.js'function fixture(env: NodeJS.ProcessEnv = {}, privacy: () => PrivacyObservation | null = () => null) {@@ -19,7 +22,7 @@ function fixture(env: NodeJS.ProcessEnv = {}, privacy: () => PrivacyObservation} })const pool = { tabId: 'tab', machine: { machineId: 'host', generation: 'grant', cwd: '/repo', engines: ['codex'], paused: false },harnessIds: ['running', 'stopped'], starts: [{ id: 'start', dispatched: false }], paused: false }- const backend = vi.fn(async (_core: unknown, method: string, path: string, _body?: unknown): Promise<unknown> => path.endsWith('/pools') ? [pool] : { revision: 1 })+ const backend = vi.fn(async (_core: unknown, method: string, path: string, _body?: unknown): Promise<unknown> => path.includes('/hosts/host/changes') ? hostForm([], { pools: [pool] }) : { revision: 1 })const request = vi.fn(async (_type: string): Promise<Record<string, unknown>> => ({ providers: [{ provider: 'codex', outcome: 'answered', httpStatus: 200,body: { account_email: '[email protected]', secret: 'private-token', rate_limit: { primary_window: { used_percent: 25, reset_at: 1234567890 } } } }] }))const close = vi.fn(), open = vi.fn(async () => ({ machineId: 'host', request, close }))@@ -28,11 +31,35 @@ function fixture(env: NodeJS.ProcessEnv = {}, privacy: () => PrivacyObservationconst prepare = vi.fn(async () => {})const log = vi.fn()const modelsStamp = vi.fn(async () => stamp)- const machine = new ContributedMachines(core, 'host', { backend, open, capabilities, start, prepare, log, env, privacy, modelsStamp, now: () => now } as never)- return { machine, pool, core, backend, open, request, close, capabilities, start, prepare, log, modelsStamp, advance: () => { now += 16000 }, step: (ms: number) => { now += ms },+ const deps = { backend, open, capabilities, start, prepare, log, env, privacy, modelsStamp, now: () => now }+ const machine = new ContributedMachines(core, 'host', deps as never)+ return { deps, machine, pool, core, backend, open, request, close, capabilities, start, prepare, log, modelsStamp, advance: () => { now += 16000 }, step: (ms: number) => { now += ms },stamp: (next: string) => { stamp = next } }}+// #1726: the pass read GET /hosts/:m/pools, up to 100 whole Swarms, every 5 s. Its pools now come with the host form.+describe('the pools of a contributed machine', () => {+ it('come from the host form, never the old pools roster', async () => {+ const f = fixture()+ await f.machine.tick()+ const reads = f.backend.mock.calls.filter(c => c[1] === 'GET').map(c => c[2])+ expect(reads).toEqual(['/api/super-tabs/hosts/host/changes?full=1'])+ expect(f.start).toHaveBeenCalledWith(expect.objectContaining({ tabId: 'tab', startId: 'start' }), expect.any(Function), expect.anything(), f.open)+ })+ it('come from the host\'s own fresh read when it shares one, without reading again', async () => {+ const f = fixture()+ let now = 1000+ const feed = new HostFeed(f.core, 'host', { now: () => now, backend: f.backend })+ await feed.refresh()+ const machine = new ContributedMachines(f.core, 'host', { backend: f.backend, open: f.open, capabilities: f.capabilities, start: f.start, prepare: f.prepare,+ log: f.log, now: () => now, sources: { feed, reads: new SwarmReads(f.core, { backend: f.backend }) } } as never)+ now += 1_999+ await machine.tick()+ expect(f.backend.mock.calls.filter(c => c[1] === 'GET')).toHaveLength(1)+ expect(f.start).toHaveBeenCalledTimes(1)+ })+})+describe('contributed machine executor', () => {it('reports only installed supported engines for a legacy OpenCode contribution', async () => {const f = fixture()@@ -100,7 +127,7 @@ describe('contributed machine executor', () => {const machine = new ContributedMachines(f.core, 'host', { backend: f.backend, open: f.open, capabilities: f.capabilities, start: f.start,log: f.log, env: {}, privacy: () => null, team: () => team, now: () => 1000 } as never)Object.assign(f.pool, { githubApp: true })- f.backend.mockImplementation(async (_core: unknown, _method: string, path: string): Promise<unknown> => path.endsWith('/pools') ? [f.pool]+ f.backend.mockImplementation(async (_core: unknown, _method: string, path: string): Promise<unknown> => path.includes('/hosts/host/changes') ? hostForm([], { pools: [f.pool] }): path.endsWith('/github-token') ? { github: false } : { revision: 1 })await machine.tick()const asked = f.backend.mock.calls.find(c => String(c[2]).endsWith('/github-token'))!@@ -141,8 +168,8 @@ describe('contributed machine executor', () => {it('reuses tool readings across tabs and heartbeat passes without another shell probe', async () => {const f = fixture()const original = f.backend.getMockImplementation()!- f.backend.mockImplementation(async (core, method, path, body) => path.endsWith('/pools')- ? [f.pool, { ...f.pool, tabId: 'second-tab' }]+ f.backend.mockImplementation(async (core, method, path, body) => path.includes('/hosts/host/changes')+ ? hostForm([], { pools: [f.pool, { ...f.pool, tabId: 'second-tab' }] }): original(core, method, path, body))await f.machine.tick()expect(f.capabilities.mock.calls.map(([input]) => input.tools)).toEqual([@@ -169,6 +196,233 @@ describe('contributed machine executor', () => {await f.machine.tick()expect(f.capabilities.mock.lastCall?.[0]).toMatchObject({ tools: ['flutter'] })})+ // v1 routing (#229): the route left out nothing it could not see, and picked machines signed out, without the project or+ // unable to push. The reading now says what the machine is ready for.+ describe('readiness', () => {+ const readings = (f: ReturnType<typeof fixture>) => f.backend.mock.calls.filter(c => c[1] === 'POST' && String(c[2]).includes('/machines/'))+ .map(c => c[3] as Record<string, unknown> & { readiness?: { engines?: unknown[]; checkouts?: Array<Record<string, unknown>> } })+ const withEngines = (f: ReturnType<typeof fixture>) => {+ const usage = f.request.getMockImplementation()!+ f.request.mockImplementation(async (type, ...rest) => type === 'engines_probe'+ ? { engines: [{ engine: 'claude', installed: true, signedIn: false }, { engine: 'codex', installed: true }, { engine: 'cursor', installed: true }] }+ : usage(type, ...rest as []))+ }+ const probes = (f: ReturnType<typeof fixture>) => f.request.mock.calls.filter(c => c[0] === 'engines_probe')++ it('says whether each engine is installed and signed in, probing again only after ten minutes', async () => {+ const f = fixture()+ withEngines(f)+ await f.machine.tick()+ expect(f.request).toHaveBeenCalledWith('engines_probe', { engines: ['claude', 'codex'], accounts: true }, 20_000)+ // An engine that says nothing about its sign-in is unknown, never signed out.+ expect(readings(f)[0]!.readiness).toEqual({ engines: [{ engine: 'claude', installed: true, signedIn: false }, { engine: 'codex', installed: true, signedIn: null }] })+ f.advance(); await f.machine.tick()+ expect(readings(f)).toHaveLength(2)+ expect(readings(f)[1]!.readiness?.engines).toHaveLength(2)+ expect(probes(f)).toHaveLength(1)+ f.step(10 * 60_000); await f.machine.tick()+ expect(probes(f)).toHaveLength(2)+ })++ it('reads an engine the probe calls not installed as unknown, since a timed-out shell probe says the same (review of #1743)', async () => {+ const f = fixture()+ const usage = f.request.getMockImplementation()!+ f.request.mockImplementation(async (type, ...rest) => type === 'engines_probe'+ ? { engines: [{ engine: 'claude', installed: false }, { engine: 'codex', installed: true, signedIn: true }] } : usage(type, ...rest as []))+ await f.machine.tick()+ expect(readings(f)[0]!.readiness?.engines).toEqual([{ engine: 'claude', installed: null, signedIn: null }, { engine: 'codex', installed: true, signedIn: true }])+ })++ it('sends no engine readiness when the probe fails, and asks again a minute later', async () => {+ const f = fixture()+ const usage = f.request.getMockImplementation()!+ f.request.mockImplementation(async (type, ...rest) => type === 'engines_probe' ? Promise.reject(new Error('timed out')) : usage(type, ...rest as []))+ await f.machine.tick()+ expect(readings(f)[0]).not.toHaveProperty('readiness')+ f.advance(); await f.machine.tick()+ expect(probes(f)).toHaveLength(1)+ f.step(60_000); await f.machine.tick()+ expect(probes(f)).toHaveLength(2)+ })++ describe('of its Swarm folder', () => {+ const roots: string[] = []+ afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) })+ const run = (cwd: string, ...args: string[]) => execFileSync('git', args, { cwd, stdio: 'ignore', env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1' } })+ /** A Swarm folder: p1 a checkout of a GitHub repository this login may not push to, p2 a plain folder, p3 a checkout+ * of a repository on disk it can push to. */+ function swarmFolder() {+ const root = mkdtempSync(join(tmpdir(), 'readiness-')); roots.push(root)+ const remote = join(root, 'remote.git'), swarm = join(root, 'swarm')+ mkdirSync(remote); run(remote, 'init', '-q', '--bare')+ for (const name of ['p1', 'p3']) {+ mkdirSync(join(swarm, name), { recursive: true }); const dir = join(swarm, name)+ run(dir, 'init', '-q'); run(dir, '-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'init')+ }+ run(join(swarm, 'p1'), 'remote', 'add', 'origin', 'https://someone:[email protected]/Acme/App.git?access_token=query-secret')+ run(join(swarm, 'p3'), 'remote', 'add', 'origin', remote)+ mkdirSync(join(swarm, 'p2')); mkdirSync(join(swarm, '.hidden')); writeFileSync(join(swarm, 'notes.txt'), '')+ return swarm+ }+ /** git as it is, except that a push to GitHub answers as GitHub does to a login without write access. */+ function gitFor(denied: string) {+ const calls: string[][] = []+ const git = vi.fn(async (cwd: string, args: string[]) => {+ calls.push(args)+ if (args[0] === 'push' && cwd.endsWith('p1')) return { ok: false, stdout: '', stderr: denied }+ try { return { ok: true, stdout: execFileSync('git', ['-C', cwd, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }), stderr: '' } }+ catch (error) { return { ok: false, stdout: '', stderr: String((error as { stderr?: unknown }).stderr ?? '') } }+ })+ return { git, calls }+ }+ function swarmFixture(git: ReturnType<typeof gitFor>['git']) {+ const f = fixture()+ Object.assign(f.pool.machine, { scope: 'swarm', cwd: swarmFolder() })+ const machine = new ContributedMachines(f.core, 'host', { backend: f.backend, open: f.open, capabilities: f.capabilities, start: f.start, prepare: f.prepare,+ log: f.log, now: () => now, git } as never)+ let now = 1000+ return { ...f, machine, step: (ms: number) => { now += ms } }+ }++ it('lists each project folder\'s repository, whether it is a checkout, and whether this login can push, never a credential', async () => {+ const { git, calls } = gitFor("remote: Permission to Acme/App.git denied to someone.\nfatal: unable to access 'https://github.com/Acme/App.git/': The requested URL returned error: 403")+ const f = swarmFixture(git)+ await f.machine.tick()+ // The folder is read beside the pass, never holding it up.+ await vi.waitFor(() => expect(calls.filter(a => a[0] === 'push')).toHaveLength(2))+ f.step(16_000); await f.machine.tick()+ const checkouts = readings(f).at(-1)!.readiness!.checkouts!+ expect(checkouts).toEqual([+ { folder: 'p1', repository: 'github.com/acme/app', git: true, push: false },+ { folder: 'p2', repository: null, git: false, push: null },+ { folder: 'p3', repository: null, git: true, push: true },+ ])+ expect(JSON.stringify(readings(f))).not.toMatch(/secret-token|query-secret/)+ // A dry run that runs no hooks, so nothing is pushed and nothing of the repository's runs.+ expect(calls.find(a => a[0] === 'push')).toEqual(['push', '--dry-run', '--no-verify', '--porcelain', 'origin', 'HEAD:refs/heads/harness-push-check'])+ f.step(16_000); await f.machine.tick()+ expect(calls.filter(a => a[0] === 'push')).toHaveLength(2)+ f.step(10 * 60_000); await f.machine.tick()+ await vi.waitFor(() => expect(calls.filter(a => a[0] === 'push')).toHaveLength(4))+ })++ it('reads a checkout with git itself, which can push to a remote it may write to', async () => {+ const root = mkdtempSync(join(tmpdir(), 'readiness-')); roots.push(root)+ const remote = join(root, 'remote.git'), dir = join(root, 'swarm', 'p1')+ mkdirSync(remote); run(remote, 'init', '-q', '--bare'); mkdirSync(dir, { recursive: true })+ run(dir, 'init', '-q'); run(dir, '-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'init'); run(dir, 'remote', 'add', 'origin', remote)+ const f = fixture()+ Object.assign(f.pool.machine, { scope: 'swarm', cwd: join(root, 'swarm') })+ await f.machine.tick()+ await vi.waitFor(async () => {+ f.advance(); await f.machine.tick()+ expect(readings(f).at(-1)!.readiness?.checkouts).toEqual([{ folder: 'p1', repository: null, git: true, push: true }])+ })+ // A dry run: the remote has nothing.+ expect(execFileSync('git', ['-C', remote, 'for-each-ref'], { encoding: 'utf8' })).toBe('')+ })++ it('says nothing of a Swarm folder it cannot read, and tries again a minute later, not every pass', async () => {+ const { git } = gitFor('')+ const f = swarmFixture(git)+ Object.assign(f.pool.machine, { cwd: join(tmpdir(), 'readiness-missing-folder') })+ await f.machine.tick()+ await vi.waitFor(() => expect(f.log).toHaveBeenCalledWith(expect.stringContaining('Could not read the Swarm folder')))+ // Proving it is not read again needs the time a read would take: each pass is followed by more than a folder read.+ for (let i = 0; i < 3; i++) { f.step(16_000); await f.machine.tick(); await new Promise(done => setTimeout(done, 50)) }+ expect(readings(f)).toHaveLength(4)+ expect(readings(f).at(-1)!.readiness?.checkouts).toBeUndefined()+ expect(f.log.mock.calls.filter(c => String(c[0]).includes('Swarm folder'))).toHaveLength(1)+ f.step(60_000); await f.machine.tick()+ await vi.waitFor(() => expect(f.log.mock.calls.filter(c => String(c[0]).includes('Swarm folder'))).toHaveLength(2))+ })++ it('leaves out a folder whose probe failed rather than calling it no checkout, and reads it again a minute later (review of #1743)', async () => {+ const { git: real, calls } = gitFor('denied')+ let failing = true+ const git = vi.fn(async (cwd: string, args: string[]) => failing && args[0] === 'rev-parse' && cwd.endsWith('p3')+ ? { ok: false, stdout: '', stderr: '', timedOut: true } : real(cwd, args))+ const f = swarmFixture(git)+ await f.machine.tick()+ await vi.waitFor(() => expect(calls.filter(a => a[0] === 'push')).toHaveLength(1))+ f.step(16_000); await f.machine.tick()+ expect(readings(f).at(-1)!.readiness!.checkouts!.map(c => [c.folder, c.git])).toEqual([['p1', true], ['p2', false]])+ failing = false+ f.step(60_000); await f.machine.tick()+ await vi.waitFor(() => expect(calls.filter(a => a[0] === 'push')).toHaveLength(3))+ f.step(16_000); await f.machine.tick()+ expect(readings(f).at(-1)!.readiness!.checkouts!.map(c => c.folder)).toEqual(['p1', 'p2', 'p3'])+ })++ it('ends a git whose helper hangs at its deadline, with everything it started, and settles at once', async () => {+ const root = mkdtempSync(join(tmpdir(), 'readiness-')); roots.push(root)+ const dir = join(root, 'p1'), pidFile = join(root, 'helper.pid'), ssh = join(root, 'ssh.sh')+ // An ssh that leaves a helper behind holding git's output, as a stuck credential helper or ssh agent can.+ writeFileSync(ssh, `#!/bin/sh\nsleep 60 &\necho $! > ${pidFile}\nsleep 60\n`, { mode: 0o755 })+ mkdirSync(dir); run(dir, 'init', '-q'); run(dir, '-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'init')+ run(dir, 'remote', 'add', 'origin', 'ssh://[email protected]/acme/app.git'); run(dir, 'config', 'core.sshCommand', ssh)+ const began = Date.now()+ const answer = await createQuietGit(1_000)(dir, ['push', '--dry-run', '--no-verify', '--porcelain', 'origin', 'HEAD:refs/heads/harness-push-check'])+ expect(answer).toMatchObject({ ok: false, timedOut: true })+ expect(Date.now() - began).toBeLessThan(5_000)+ const helper = Number(readFileSync(pidFile, 'utf8'))+ await vi.waitFor(() => expect(() => process.kill(helper, 0)).toThrow())+ })++ it('ends a helper that outlives git and keeps its output open, before the deadline (re-check of #1743)', async () => {+ const root = mkdtempSync(join(tmpdir(), 'readiness-')); roots.push(root)+ const dir = join(root, 'p1'), pidFile = join(root, 'helper.pid'), ssh = join(root, 'ssh.sh')+ // An ssh that fails at once, so git exits, but leaves a helper behind holding the error output git handed down.+ writeFileSync(ssh, `#!/bin/sh\nsleep 60 </dev/null >/dev/null &\necho $! > ${pidFile}\nexit 1\n`, { mode: 0o755 })+ mkdirSync(dir); run(dir, 'init', '-q'); run(dir, '-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'init')+ run(dir, 'remote', 'add', 'origin', 'ssh://[email protected]/acme/app.git'); run(dir, 'config', 'core.sshCommand', ssh)+ const began = Date.now()+ const answer = await createQuietGit(30_000)(dir, ['push', '--dry-run', '--no-verify', '--porcelain', 'origin', 'HEAD:refs/heads/harness-push-check'])+ expect(answer).toMatchObject({ ok: false })+ expect(Date.now() - began).toBeLessThan(10_000)+ const helper = Number(readFileSync(pidFile, 'utf8'))+ await vi.waitFor(() => expect(() => process.kill(helper, 0)).toThrow())+ })++ it('says a push is unknown, not refused, when the remote could not be reached', async () => {+ const { git, calls } = gitFor("fatal: unable to access 'https://github.com/Acme/App.git/': Could not resolve host: github.com")+ const f = swarmFixture(git)+ await f.machine.tick()+ await vi.waitFor(() => expect(calls.filter(a => a[0] === 'push')).toHaveLength(2))+ f.step(16_000); await f.machine.tick()+ expect(readings(f).at(-1)!.readiness!.checkouts![0]).toEqual({ folder: 'p1', repository: 'github.com/acme/app', git: true, push: null })+ })++ it('reads a credential prompt git could not show as no push access', async () => {+ const { git, calls } = gitFor("fatal: could not read Username for 'https://github.com': terminal prompts disabled")+ const f = swarmFixture(git)+ await f.machine.tick()+ await vi.waitFor(() => expect(calls.filter(a => a[0] === 'push')).toHaveLength(2))+ f.step(16_000); await f.machine.tick()+ expect(readings(f).at(-1)!.readiness!.checkouts![0]).toMatchObject({ folder: 'p1', push: false })+ })+ })++ it('drops only the readiness field for a backend from before it, for ten minutes, keeping privacy', async () => {+ const f = fixture({}, () => ({ mode: 'dedicated' }))+ withEngines(f)+ const original = f.backend.getMockImplementation()!+ f.backend.mockImplementation(async (core, method, path, body) => {+ if (method === 'POST' && (body as Record<string, unknown>)?.readiness) throw new SuperTabHostError('VALIDATION_ERROR', 'Unrecognized key: readiness', 400)+ return original(core, method, path, body)+ })+ await f.machine.tick()+ expect(readings(f)).toHaveLength(2)+ expect(readings(f)[1]).not.toHaveProperty('readiness')+ expect(readings(f)[1]).toMatchObject({ privacy: { mode: 'dedicated' } })+ f.advance(); await f.machine.tick()+ expect(readings(f)).toHaveLength(3)+ f.step(10 * 60_000); await f.machine.tick()+ expect(readings(f).at(-2)).toHaveProperty('readiness')+ expect(readings(f).at(-1)).not.toHaveProperty('readiness')+ })+ })+it('retries a probe-failure observation without its new field for an older backend', async () => {const f = fixture()f.capabilities.mockResolvedValueOnce({ ok: true, resources: { cpuPercent: 20, memoryTotalBytes: 1000, memoryUsedBytes: 200, projectDiskFreeBytes: 1000 },@@ -185,6 +439,58 @@ describe('contributed machine executor', () => {expect(posts[1]![3]).not.toHaveProperty('toolProbeErrors')})+ it('sends when each running harness last showed progress, and only for those running', async () => {+ const f = fixture()+ const progress = vi.fn((ids: readonly string[]) => ({ running: 900, stopped: 800, elsewhere: 700 }) as Record<string, number>)+ const machine = new ContributedMachines(f.core, 'host', { ...f.deps, progress } as never)+ await machine.tick()+ const body = f.backend.mock.calls.find(c => c[1] === 'POST')![3] as Record<string, unknown>+ expect(body.harnessProgress).toEqual({ running: 900 })+ // Nothing read yet for any running harness: the field is left out.+ progress.mockReturnValue({})+ f.advance(); await machine.tick()+ expect(f.backend.mock.calls.filter(c => c[1] === 'POST').at(-1)![3]).not.toHaveProperty('harnessProgress')+ })++ it('drops progress for a backend that refuses it, and offers it again ten minutes later', async () => {+ const f = fixture()+ const original = f.backend.getMockImplementation()!+ f.backend.mockImplementation(async (core, method, path, body) => {+ if (method === 'POST' && (body as Record<string, unknown>)?.harnessProgress) throw new SuperTabHostError('VALIDATION_ERROR', 'Unrecognized key: harnessProgress', 400)+ return original(core, method, path, body)+ })+ const machine = new ContributedMachines(f.core, 'host', { ...f.deps, progress: () => ({ running: 900 }) } as never)+ const posts = () => f.backend.mock.calls.filter(c => c[1] === 'POST' && String(c[2]).includes('/machines/'))+ await machine.tick()+ expect(posts().map(c => 'harnessProgress' in (c[3] as object))).toEqual([true, false])+ f.advance(); await machine.tick()+ expect(posts().map(c => 'harnessProgress' in (c[3] as object))).toEqual([true, false, false])+ f.step(600_000); await machine.tick()+ expect(posts().map(c => 'harnessProgress' in (c[3] as object))).toEqual([true, false, false, true, false])+ })++ it('drops readiness alone for a backend that takes progress, and both, keeping privacy, for one that takes neither', async () => {+ const f = fixture({}, () => ({ mode: 'dedicated' }))+ const usage = f.request.getMockImplementation()!+ f.request.mockImplementation(async (type, ...rest) => type === 'engines_probe' ? { engines: [{ engine: 'codex', installed: true, signedIn: true }] } : usage(type, ...rest as []))+ let refuses = ['readiness']+ const original = f.backend.getMockImplementation()!+ f.backend.mockImplementation(async (core, method, path, body) => {+ const sent = body as Record<string, unknown>+ if (method === 'POST' && refuses.some(key => sent?.[key])) throw new SuperTabHostError('VALIDATION_ERROR', 'Unrecognized key', 400)+ return original(core, method, path, body)+ })+ const machine = new ContributedMachines(f.core, 'host', { ...f.deps, progress: () => ({ running: 900 }) } as never)+ const posts = () => f.backend.mock.calls.filter(c => c[1] === 'POST' && String(c[2]).includes('/machines/')).map(c => c[3] as Record<string, unknown>)+ const fields = (post: Record<string, unknown>) => ['readiness', 'harnessProgress', 'privacy'].filter(key => key in post)+ await machine.tick()+ expect(posts().map(fields)).toEqual([['readiness', 'harnessProgress', 'privacy'], ['harnessProgress', 'privacy']])+ refuses = ['readiness', 'harnessProgress']+ const older = new ContributedMachines(f.core, 'host', { ...f.deps, progress: () => ({ running: 900 }) } as never)+ f.backend.mockClear(); await older.tick()+ expect(posts().map(fields)).toEqual([['readiness', 'harnessProgress', 'privacy'], ['harnessProgress', 'privacy'], ['privacy']])+ })+it('lists the models it serves on the Swarm\'s grid only while the add-on is on, and drops them for an older backend', async () => {const GRID = 'swarm-0123456789ab'const f = fixture()@@ -483,7 +789,7 @@ describe('contributed machine executor', () => {it('does not connect to a daemon without an explicit contribution', async () => {const f = fixture()- f.backend.mockResolvedValue([{ tabId: 'tab', agent: { id: 'existing-agent' } }])+ f.backend.mockResolvedValue(hostForm([{ tabId: 'tab', agent: { id: 'existing-agent' } }]))await f.machine.tick()expect(f.open).not.toHaveBeenCalled()})@@ -516,6 +822,43 @@ describe('contributed machine executor', () => {['Swarm start start is waiting: Waiting for the launched engine.']])})+ describe('a start this machine cannot run', () => {+ const failures = (f: ReturnType<typeof fixture>) => f.backend.mock.calls.filter(c => c[1] === 'POST' && c[2] === '/api/super-tabs/hosts/host/starts/tab/start')+ .map(c => c[3] as { operationId: string; command: { type: string; error?: string } }).filter(body => body.command.type === 'agent.startFailed')++ it('is failed with the machine\'s own reason once it has refused it for a minute', async () => {+ const f = fixture()+ f.start.mockResolvedValue({ error: 'CAPACITY_UNAVAILABLE', startId: 'start', reasons: ['The selected agent engine is not installed on this machine.', 'CPU use is 97%; the requested maximum is 85%.'] } as never)+ await f.machine.tick()+ // A busy minute passes: CPU or memory may free up, and routing saw this machine able a moment ago.+ f.step(30_000); await f.machine.tick()+ expect(failures(f)).toEqual([])+ f.step(30_000); await f.machine.tick()+ expect(failures(f)).toEqual([{ operationId: 'refused-start', command: { type: 'agent.startFailed', startId: 'start',+ error: 'The selected agent engine is not installed on this machine. CPU use is 97%; the requested maximum is 85%.' } }])+ })++ it('starts its minute again after a pass that did not refuse it, and never fails one whose launch is uncertain or pending', async () => {+ const f = fixture()+ f.start.mockResolvedValue({ error: 'CONTRIBUTION_REQUIRED', startId: 'start', detail: 'Ask the machine owner to use Add machine in this Swarm.' } as never)+ await f.machine.tick()+ f.start.mockRejectedValue(new Error('Could not reach the Harness backend.'))+ f.step(30_000); await f.machine.tick()+ f.start.mockResolvedValue({ error: 'CONTRIBUTION_REQUIRED', startId: 'start', detail: 'Ask the machine owner to use Add machine in this Swarm.' } as never)+ f.step(30_000); await f.machine.tick()+ expect(failures(f)).toEqual([])+ for (const error of ['START_UNCERTAIN', 'START_PENDING', 'START_REFUSED']) {+ f.start.mockResolvedValue({ error, startId: 'start', detail: 'The machine did not confirm.' } as never)+ f.step(60_000); await f.machine.tick()+ f.step(60_000); await f.machine.tick()+ }+ // Refused again: its minute starts now, not at the passes before.+ f.start.mockResolvedValue({ error: 'CONTRIBUTION_REQUIRED', startId: 'start', detail: 'Ask the machine owner to use Add machine in this Swarm.' } as never)+ f.step(60_000); await f.machine.tick()+ expect(failures(f)).toEqual([])+ })+ })+it('a lead queues a contributed start without connecting to that computer', async () => {const open = vi.fn()const scoped = vi.fn(async () => ({ ok: true, value: { creationId: 'creation', poolGeneration: 'grant', request: { machineId: 'host', engine: 'claude' } } }))@@ -526,7 +869,7 @@ describe('contributed machine executor', () => {describe('how soon a change is seen', () => {const posts = (f: ReturnType<typeof fixture>) => f.backend.mock.calls.filter(c => c[1] === 'POST' && String(c[2]).includes('/machines/'))- const reads = (f: ReturnType<typeof fixture>) => f.backend.mock.calls.filter(c => c[1] === 'GET' && String(c[2]).endsWith('/pools'))+ const reads = (f: ReturnType<typeof fixture>) => f.backend.mock.calls.filter(c => c[1] === 'GET' && String(c[2]).includes('/hosts/host/changes'))const lastBody = (f: ReturnType<typeof fixture>) => posts(f).at(-1)![3] as { runningHarnessIds: string[]; stoppedHarnessIds: string[] }/** The next host tick, `ms` later. */const after = async (f: ReturnType<typeof fixture>, ms: number) => { f.step(ms); await f.machine.tick() }@@ -552,6 +895,18 @@ describe('contributed machine executor', () => {expect(lastBody(f)).toMatchObject({ runningHarnessIds: ['newcomer'], stoppedHarnessIds: ['running', 'stopped'] })})+ it('reports a session closed by hand, which leaves no stopped record, as stopped on the next look', async () => {+ const f = fixture(); quiet(f)+ await f.machine.tick()+ expect(lastBody(f)).toMatchObject({ runningHarnessIds: ['running'], stoppedHarnessIds: ['stopped'] })+ // Closed or crashed: gone from the registry, and kept nowhere as a stopped agent.+ vi.mocked(f.core.agents.byAgent).mockImplementation(() => undefined)+ Object.assign(f.core.agents, { gone: vi.fn(async (id: string) => id === 'running') })+ await after(f, 5_000)+ expect(posts(f)).toHaveLength(2)+ expect(lastBody(f)).toMatchObject({ runningHarnessIds: [], stoppedHarnessIds: ['running', 'stopped'] })+ })+it('publishes at once when new work is paused or allowed again', async () => {const f = fixture(); quiet(f)await f.machine.tick()@@ -626,7 +981,7 @@ describe('contributed machine executor', () => {for (const ms of [1_000, 5_000, 10_000, 20_000]) { f.step(ms); void f.machine.tick() }await Promise.resolve()expect(reads(f)).toHaveLength(1)- release([f.pool])+ release(hostForm([], { pools: [f.pool] }))await firstexpect(reads(f)).toHaveLength(1)expect(posts(f)).toHaveLength(1)@@ -643,7 +998,7 @@ describe('contributed machine executor', () => {await after(f, 5_000)expect(reads(f)).toHaveLength(2)- f.backend.mockImplementation(async (_core, method, path) => path.endsWith('/pools') ? [f.pool] : method === 'POST' ? Promise.reject(new Error('refused')) : { revision: 1 })+ f.backend.mockImplementation(async (_core, method, path) => path.includes('/hosts/host/changes') ? hostForm([], { pools: [f.pool] }) : method === 'POST' ? Promise.reject(new Error('refused')) : { revision: 1 })await after(f, 15_000)expect(posts(f)).toHaveLength(2)await after(f, 5_000); await after(f, 5_000)@@ -665,7 +1020,7 @@ describe('contributed machine executor', () => {const f = fixture(); quiet(f)await f.machine.tick()const pools = f.backend.getMockImplementation()!- f.backend.mockImplementation(async (core, method, path, body) => path.endsWith('/pools') ? [] : pools(core, method, path, body))+ f.backend.mockImplementation(async (core, method, path, body) => path.includes('/hosts/host/changes') ? hostForm([], { tabs: ['tab'] }) : pools(core, method, path, body))await after(f, 5_000)f.backend.mockImplementation(pools)await after(f, 5_000)@@ -717,7 +1072,7 @@ describe('removed machine cleanup', () => {closeStarted: vi.fn(async (agentId: string) => { live = live.filter(s => s.agentId !== agentId); return { closed: true } as never }),} })const backend = vi.fn(async (_core: unknown, method: string, path: string, _body?: unknown): Promise<unknown> =>- method === 'GET' && path === '/api/super-tabs/tab' ? { state: { starts } } : { revision: 1 })+ method === 'GET' && path.startsWith('/api/super-tabs/tab/') ? swarmReply(path, { starts }) : { parts: [] })const log = vi.fn()let now = 0const open = () => new ContributedMachines(core, 'host', { backend, log, now: () => now } as never)@@ -768,7 +1123,7 @@ describe('removed machine cleanup', () => {it('waits longer after each failed acknowledgement instead of cleaning again every pass', async () => {const m = machine()const host = m.open()- m.backend.mockImplementationOnce(async () => ({ state: { starts: [] } })).mockRejectedValueOnce(new Error('Backend offline'))+ m.backend.mockImplementationOnce(async (_core, _method, path) => swarmReply(path, { starts: [] })).mockRejectedValueOnce(new Error('Backend offline'))await expect(host.clean('tab', 'removal')).rejects.toThrow('Backend offline')const calls = m.backend.mock.calls.lengthawait host.clean('tab', 'removal')@@ -801,7 +1156,7 @@ describe('removed machine cleanup', () => {it('finishes a cleanup after a restart that interrupted its acknowledgement', async () => {const m = machine()- m.backend.mockImplementationOnce(async () => ({ state: { starts: [] } })).mockRejectedValueOnce(new Error('Backend offline'))+ m.backend.mockImplementationOnce(async (_core, _method, path) => swarmReply(path, { starts: [] })).mockRejectedValueOnce(new Error('Backend offline'))await expect(m.open().clean('tab', 'removal')).rejects.toThrow('Backend offline')expect(existsSync(m.recorded)).toBe(false)await m.open().clean('tab', 'removal')@@ -823,7 +1178,7 @@ describe('removed machine cleanup', () => {const core = fakeCore({ dataDir: root, agents: { byAgent: vi.fn(id => id === 'h-new' ? session('h-new', '/worktrees/project/new', 'agent') : undefined) } })const pool = { tabId: 'tab', machine: { machineId: 'host', generation: 'grant', cwd: '/repo', engines: ['codex'], paused: false },harnessIds: [], starts: [{ id: 'new', dispatched: true, request: { worktree: true, cwd: '/clone' } }], paused: false }- const backend = vi.fn(async (_core: unknown, _method: string, path: string, _body?: unknown): Promise<unknown> => path.endsWith('/pools') ? [pool] : { revision: 1 })+ const backend = vi.fn(async (_core: unknown, _method: string, path: string, _body?: unknown): Promise<unknown> => path.includes('/hosts/host/changes') ? hostForm([], { pools: [pool] }) : { revision: 1 })const open = vi.fn(async () => ({ machineId: 'host', request: vi.fn(async () => ({})), close: vi.fn() }))const start = vi.fn(async () => ({ ok: true, harnessId: 'h-new' }))await new ContributedMachines(core, 'host', { backend, open, start, now: () => 0,diff --git a/cli/src/superTabs/machines.ts b/cli/src/superTabs/machines.tsindex 97216757f..6fdd034e7 100644--- a/cli/src/superTabs/machines.ts+++ b/cli/src/superTabs/machines.ts@@ -1,11 +1,14 @@+import { spawn } from 'node:child_process'import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'import { lstat, readdir, readFile, realpath, rm, stat } from 'node:fs/promises'import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'import type { CoreApi } from '../core/api.js'import { openDaemon } from '../agentClient/daemon.js'import { codingRefusal } from '../lib/codingModel.js'-import { backend, SuperTabHostError } from './host.js'-import { identifier, object } from './wire.js'+import { backend, identifier, object, SuperTabHostError } from './wire.js'+import type { SwarmSources } from './host.js'+import { HostFeed } from './hostFeed.js'+import { SwarmReads } from './swarmReads.js'import { readCapabilities, quotaOf, meteredEngine } from './capacity.js'import { startAgent, type ScopedRequest } from './start.js'import { prepareSwarmStart } from './projectFolder.js'@@ -16,6 +19,7 @@ import { projectsRoot } from '../lib/projectFolder.js'import { worktreeFolderName } from '../lib/agentNames.js'import { teamPrivacyObserver } from '../team/observer.js'import type { PrivacyObservation } from '../team/privacy.js'+import { repositoryKey } from './route.js'const finite = (v: unknown) => typeof v === 'number' && Number.isFinite(v) ? v : nullconst list = (v: unknown) => Array.isArray(v) ? v.map(object) : []@@ -23,10 +27,18 @@ const list = (v: unknown) => Array.isArray(v) ? v.map(object) : []// include tools from pending starts. An uncommon tool first named during routing remains unverified and is refused.const COMMON_TOOLS = ['git', 'node', 'npm', 'flutter', 'gh', 'cargo', 'python3']const VERIFIED_TOOL_TTL_MS = 10 * 60_000-/** After a backend refuses the privacy field (one from before the Harness Team account), how long the reading goes- * without it before the field is offered again: a backend deployed meanwhile is heard from within this long. */-const PRIVACY_REFUSED_MS = 10 * 60_000+/** After a backend refuses a new field (privacy, from before the Harness Team account; harnessProgress, from before+ * task leases), how long the reading goes without it before the field is offered again: a backend deployed meanwhile+ * is heard from within this long. */+const FIELD_REFUSED_MS = 10 * 60_000const UNVERIFIED_TOOL_TTL_MS = 60_000+/** How long this machine refuses a start before failing it with its reason, so the Lead starts it elsewhere: a minute of+ * busy CPU or memory may pass, and routing saw this machine able a moment ago. A refusal no one reported left starts+ * "Queued" for hours (DESKTOP-0TFH0OJ, 2026-10-23). */+const START_REFUSED_MS = 60_000+/** What a start answers while its launch may already have happened or is under way: never failed from here, or an agent+ * could run with no start to show for it. The failures already reported say so themselves. */+const NOT_REFUSED = new Set(['START_UNCERTAIN', 'START_PENDING', 'START_REFUSED', 'START_FAILED', 'SWARM_ENGINE'])/** How often the executor asks the backend what its tabs want of it (a start waiting, a pause) and compares what it* would report with what it last did. Only this read is this frequent: the resource readers run when there is@@ -35,6 +47,8 @@ export const MACHINE_POLL_MS = 5_000/** How long an observation stands before it is sent again unchanged, so the Desktop can tell a machine that is* silent from one that has nothing new (its offline threshold is counted in these beats). */export const MACHINE_HEARTBEAT_MS = 15_000+/** How old a host form this pass may take: the host reads one every second, so a pass beside it reads nothing itself. */+const POOLS_FRESH_MS = 2_000/** The worktrees this machine's Swarm starts made, by tab: what a removal may delete besides the tab's Swarm folders. */export const swarmWorktreesFile = (dataDir: string, machineId: string) => join(dataDir, 'super-tabs', `swarm-worktrees-${machineId}.json`)@@ -72,6 +86,28 @@ async function swarmWorktree(path: string, source: string, startId: string): Pro} catch { return false }}+export interface MachineDeps {+ backend: typeof backend; open: typeof openDaemon; capabilities: typeof readCapabilities; start: typeof startAgent; now: () => number+ log?: (message: string) => void; env?: NodeJS.ProcessEnv+ /** Readies a queued start before its agent is created (superTabs/projectFolder.ts `prepareSwarmStart`): whom the+ * work is for when it uses the Harness GitHub App, else null. */+ prepare?: (core: CoreApi, row: Record<string, unknown>, start: Record<string, unknown>) => Promise<{ requester: string } | null | void>+ /** Whether this daemon runs team work only (a Harness Team account, `harness team on`): it has no git login of its own. */+ team?: () => boolean+ /** The Harness Team account's privacy check (team/privacy.ts): null for the owner's own daemon. */+ privacy?: () => PrivacyObservation | null+ /** What says this machine's Swarm models changed, read every pass without asking the daemon ([localModelsStamp]). */+ modelsStamp?: () => Promise<string>+ /** The machine's host form and Swarm reads, shared with its host (superTabs/host.ts). */+ sources?: SwarmSources+ /** git for the readiness of the Swarm folder's checkouts ([quietGit]). */+ git?: GitRun+ /** When each of these harnesses' screens last changed, epoch ms (superTabs/terminal.ts `progressOf`): the backend+ * renews a task's lease from it, so work never sits with a dead owner (docs: swarm-never-stops). */+ progress?: (harnessIds: readonly string[]) => Record<string, number>+}+const MACHINE_DEPS = { backend, open: openDaemon, capabilities: readCapabilities, start: startAgent, now: Date.now }+/** Separate from chat delivery: slow resource readers and agent launches never* hold up a delivery lease. Only a tab's explicit owner grant wakes this queue. */export class ContributedMachines {@@ -90,6 +126,8 @@ export class ContributedMachines {private readonly toolCache = new Map<string, { value: boolean | null; detail?: string; until: number }>()/** Per waiting start, why it was last not started, so the log says it once per reason, not every pass. */private readonly waiting = new Map<string, string>()+ /** Per waiting start, since when this machine has refused it without a break. */+ private readonly refusedSince = new Map<string, number>()/** Removals cleaned and acknowledged by this host, and the one in progress per removal. */private readonly cleaned = new Set<string>()private readonly cleaning = new Map<string, Promise<void>>()@@ -97,6 +135,47 @@ export class ContributedMachines {private readonly cleanupRetries = new Map<string, { failures: number; at: number }>()/** Until when the reading leaves out its privacy field, which the backend refused. */private privacyRefusedUntil = 0+ /** Until when the reading leaves out its progress, which the backend refused. */+ private progressRefusedUntil = 0+ /** Until when the reading leaves out its readiness field, which the backend refused. */+ private readinessRefusedUntil = 0+ /** Whether each engine is installed and signed in, and until when that stands: one probe starts login shells and reads+ * the engines' accounts, so it runs every [READINESS_MS] (a failed one again after [READINESS_RETRY_MS]). */+ private engineRead: { value: ReadyEngine[] | null; until: number } | null = null+ /** Per Swarm folder, its checkouts' readiness and until when it stands, and the folders being read now. A push check+ * asks the remote, so it is read beside the pass, never holding up a start. */+ private readonly checkoutReads = new Map<string, { value: ReadyCheckout[] | null; until: number }>()+ private readonly checkoutReading = new Set<string>()+ private async engineReadiness(local: { request: (type: string, payload: Record<string, unknown>, timeoutMs: number) => Promise<unknown> }): Promise<ReadyEngine[] | null> {+ const now = this.deps.now()+ if (this.engineRead && now < this.engineRead.until) return this.engineRead.value+ const answer = await local.request('engines_probe', { engines: ['claude', 'codex'], accounts: true }, 20_000).catch(() => null)+ const engines = object(answer).engines+ // An engine that says nothing of its sign-in (an older daemon, an engine not installed) is unknown, never signed out.+ // Not installed is unknown too: the probe answers the same for a login shell that timed out (lib/engineProbe.ts), and+ // such a machine fails its first start loudly instead (review of #1743).+ const value = Array.isArray(engines) ? list(engines).filter(e => e.engine === 'claude' || e.engine === 'codex')+ .map((e): ReadyEngine => ({ engine: String(e.engine), installed: e.installed === true ? true : null, signedIn: e.installed === true && typeof e.signedIn === 'boolean' ? e.signedIn : null })) : null+ this.engineRead = { value, until: now + (value ? READINESS_MS : READINESS_RETRY_MS) }+ return value+ }+ /** The last readiness of [root]'s checkouts, reading them again beside the pass once it is [READINESS_MS] old. Null+ * until the first read is in. */+ private checkoutReadiness(root: string): ReadyCheckout[] | null {+ const read = this.checkoutReads.get(root)+ if ((!read || this.deps.now() >= read.until) && !this.checkoutReading.has(root)) {+ this.checkoutReading.add(root)+ void readCheckouts(root, this.deps.git ?? quietGit)+ // A folder whose probe failed is left out and read again a minute later, not taken for ten.+ .then(({ checkouts, unsure }) => { this.checkoutReads.set(root, { value: checkouts, until: this.deps.now() + (unsure ? READINESS_RETRY_MS : READINESS_MS) }) }, error => {+ // An unreadable folder says nothing, and is read again a minute later, not on every pass.+ this.checkoutReads.set(root, { value: null, until: this.deps.now() + READINESS_RETRY_MS })+ this.log(`Could not read the Swarm folder's checkouts: ${error instanceof Error ? error.message : String(error)}`)+ })+ .finally(() => this.checkoutReading.delete(root))+ }+ return read?.value ?? null+ }/** This pass's privacy reading, read once a pass (the check itself runs at most every five minutes). */private privacy(): PrivacyObservation | null {try { return (this.deps.privacy ?? teamPrivacyObserver)() } catch (error) {@@ -114,19 +193,13 @@ export class ContributedMachines {if (Array.isArray(object(answer).grids)) this.gridModelsRead = { at: now, answer }return answer}- constructor(private readonly core: CoreApi, private readonly machineId: string,- private readonly deps: { backend: typeof backend; open: typeof openDaemon; capabilities: typeof readCapabilities;- start: typeof startAgent; now: () => number; log?: (message: string) => void; env?: NodeJS.ProcessEnv- /** Readies a queued start before its agent is created (superTabs/projectFolder.ts `prepareSwarmStart`): whom the- * work is for when it uses the Harness GitHub App, else null. */- prepare?: (core: CoreApi, row: Record<string, unknown>, start: Record<string, unknown>) => Promise<{ requester: string } | null | void>- /** Whether this daemon runs team work only (a Harness Team account, `harness team on`): it has no git login of its own. */- team?: () => boolean- /** The Harness Team account's privacy check (team/privacy.ts): null for the owner's own daemon. */- privacy?: () => PrivacyObservation | null- /** What says this machine's Swarm models changed, read every pass without asking the daemon ([localModelsStamp]). */- modelsStamp?: () => Promise<string> } =- { backend, open: openDaemon, capabilities: readCapabilities, start: startAgent, now: Date.now }) {}+ private readonly deps: MachineDeps+ private readonly sources: SwarmSources+ constructor(private readonly core: CoreApi, private readonly machineId: string, deps: Partial<MachineDeps> = {}) {+ this.deps = { ...MACHINE_DEPS, ...deps }+ this.sources = deps.sources ?? { feed: new HostFeed(core, machineId, { now: this.deps.now, backend: this.deps.backend }),+ reads: new SwarmReads(core, { backend: this.deps.backend }) }+ }stop() { this.stopped = true }/** DESKTOP-0TFH0OJ, 2026-10-23: every Claude start there was refused (CLI 0.4.57 took an API-key Claude for one not* signed in) and the refusal was dropped, so two starts stayed "Queued" for hours with nothing in the log. */@@ -148,10 +221,11 @@ export class ContributedMachines {}private async poll(began: number) {const where = { dataDir: this.core.dataDir, port: this.core.daemon.port, machineId: this.machineId }- const pools = list(await this.deps.backend(this.core, 'GET', `/api/super-tabs/hosts/${this.machineId}/pools`)).filter(row => identifier(row.tabId) && object(row.machine).machineId === this.machineId && identifier(object(row.machine).generation))+ const pools = list((await this.sources.feed.current(POOLS_FRESH_MS)).pools).filter(row => identifier(row.tabId) && object(row.machine).machineId === this.machineId && identifier(object(row.machine).generation))if (this.stopped || pools.length === 0) { this.published.clear(); this.waiting.clear(); return }const pendingIds = new Set(pools.flatMap(row => list(row.starts).map(start => start.id)))for (const id of this.waiting.keys()) if (!pendingIds.has(id)) this.waiting.delete(id)+ for (const id of this.refusedSince.keys()) if (!pendingIds.has(id)) this.refusedSince.delete(id)for (const tab of this.published.keys()) if (!pools.some(row => row.tabId === tab)) this.published.delete(tab)const privacy = this.privacy()// A model run or stopped for a Swarm, or an API shared with it, is sent on this pass, not on the next beat: the@@ -169,7 +243,12 @@ export class ContributedMachines {if (!identifier(pool.generation) || pool.machineId !== this.machineId || typeof pool.cwd !== 'string') continueconst ids = Array.isArray(row.harnessIds) ? row.harnessIds.filter(identifier) : []const stopped: string[] = []- for (const id of ids) if (await this.core.agents.stopped?.(id)) stopped.push(id)+ // A stopped agent keeps a saved record; one closed by hand or whose session crashed away is kept nowhere (`gone`).+ // Both are reported, so the backend hands its task on at once rather than when its lease runs out. Only one the+ // registry no longer lists is asked about, so a pass costs no more for the agents that run.+ for (const id of ids) {+ if (await this.core.agents.stopped?.(id) || (!this.core.agents.byAgent(id) && await this.core.agents.gone?.(id))) stopped.push(id)+ }const running = ids.filter(id => !!this.core.agents.byAgent(id) && !stopped.includes(id))const pending = list(row.starts)const tools = [...new Set([...COMMON_TOOLS, ...pending.flatMap(start => {@@ -233,7 +312,14 @@ export class ContributedMachines {...offered(sharedWith(await this.gridModels(local), row.localGrid),await local.request('grid_swarm_offers', { grid: row.localGrid }, 10_000).catch(() => ({}))),].slice(0, MAX_LOCAL_MODELS) : null- const observation = { generation: pool.generation, tools: reportedTools, ...(localModels ? { localModels } : {}),+ const readyEngines = await this.engineReadiness(local)+ const checkouts = pool.scope === 'swarm' ? this.checkoutReadiness(pool.cwd) : null+ const readiness = { ...(readyEngines ? { engines: readyEngines } : {}), ...(checkouts ? { checkouts } : {}) }+ const shown = began >= this.progressRefusedUntil ? this.deps.progress?.(running) ?? {} : {}+ const progress = Object.fromEntries(running.flatMap(id => typeof shown[id] === 'number' ? [[id, shown[id]]] : []))+ const observation = { generation: pool.generation, tools: reportedTools,+ ...(Object.keys(progress).length ? { harnessProgress: progress } : {}), ...(localModels ? { localModels } : {}),+ ...((readyEngines || checkouts) && began >= this.readinessRefusedUntil ? { readiness } : {}),...(privacy && began >= this.privacyRefusedUntil ? { privacy } : {}),...(refusedModels.length ? { refusedModels } : {}),...(Object.keys(toolProbeErrors).length ? { toolProbeErrors } : {}),@@ -252,15 +338,18 @@ export class ContributedMachines {try {const path = `/api/super-tabs/${row.tabId}/machines/${this.machineId}`const refused = (error: unknown) => error instanceof SuperTabHostError && error.status === 400 && error.code === 'VALIDATION_ERROR'- // Older backends reject the additive fields. The privacy field is the newest, so it goes alone first: a backend+ // Older backends reject the additive fields. The newest go alone first, readiness, progress, then privacy: a backend// that takes everything else keeps the local models it reads. Their boolean-only view still safely refuses an// unverified tool, and a reading without privacy is never one a Team machine passes on.- const { privacy: _privacy, ...withoutPrivacy } = observation+ const { readiness: _readiness, ...ready } = observation+ const { harnessProgress: _progress, ...withoutProgress } = ready+ const { privacy: _privacy, ...withoutPrivacy } = withoutProgressconst { toolProbeErrors: _probeErrors, localModels: _served, refusedModels: _refused, ...legacy } = withoutPrivacy// A backend before `starting` refuses it: it gets the models the grid lists, as before, not none at all.const listedOnly = localModels?.some(m => m.starting)? [{ ...withoutPrivacy, localModels: localModels.filter(m => !m.starting) }] : []- const attempts = [observation, ...('privacy' in observation ? [withoutPrivacy] : []), ...listedOnly,+ const attempts = [...('readiness' in observation ? [observation] : []), ready, ...('harnessProgress' in ready ? [withoutProgress] : []),+ ...('privacy' in withoutProgress ? [withoutPrivacy] : []), ...listedOnly,...('toolProbeErrors' in observation || 'localModels' in observation || 'refusedModels' in observation ? [legacy] : [])]for (const [index, attempt] of attempts.entries()) {try {@@ -268,7 +357,9 @@ export class ContributedMachines {break} catch (error) {if (!refused(error) || index === attempts.length - 1) throw error- if (attempt === observation && 'privacy' in observation) this.privacyRefusedUntil = began + PRIVACY_REFUSED_MS+ if ('readiness' in attempt) this.readinessRefusedUntil = began + FIELD_REFUSED_MS+ else if ('harnessProgress' in attempt) this.progressRefusedUntil = began + FIELD_REFUSED_MS+ else if ('privacy' in attempt) this.privacyRefusedUntil = began + FIELD_REFUSED_MS}}this.published.set(String(row.tabId), { at: began, signature, starting: !!localModels?.some(m => m.starting) })@@ -313,6 +404,8 @@ export class ContributedMachines {}}const result = await this.deps.start({ tabId: row.tabId, startId: start.id, hostDispatch: true, ...(github ? { github } : {}) }, scoped, where, this.deps.open)+ const refused = result.ok !== true && !start.dispatched && !NOT_REFUSED.has(String(result.error))+ if (!refused) this.refusedSince.delete(start.id)if (result.ok === true && identifier(result.harnessId)) {this.waiting.delete(start.id)// Before the start settles: a settled start is no longer listed, so a missed record would never be made.@@ -320,11 +413,17 @@ export class ContributedMachines {await scoped({ action: 'command', operationId: `settled-${start.id}`,command: { type: 'agent.startSettled', startId: start.id, warning: result.modelWarning ?? null } })} else if (result.ok !== true) {- this.noteWaiting(start.id, String(result.detail ?? (Array.isArray(result.reasons) ? result.reasons.join(' ') : result.error)))+ const reason = String(result.detail ?? (Array.isArray(result.reasons) ? result.reasons.join(' ') : result.error))+ this.noteWaiting(start.id, reason)+ const since = this.refusedSince.get(start.id) ?? began+ if (refused) this.refusedSince.set(start.id, since)+ if (refused && began - since >= START_REFUSED_MS) {+ await scoped({ action: 'command', operationId: `refused-${start.id}`, command: { type: 'agent.startFailed', startId: start.id, error: reason } })+ }}}// Keep its durable receipt; another start must not be starved by this failure.- catch (error) { this.noteWaiting(start.id, error instanceof Error ? error.message : String(error)) }+ catch (error) { this.refusedSince.delete(start.id); this.noteWaiting(start.id, error instanceof Error ? error.message : String(error)) }}} catch { /* Revocation or one unavailable project cannot block another contribution. */ }}@@ -366,7 +465,7 @@ export class ContributedMachines {// very agent the registry lists as agent-started in it. A start receipt read is required; a tab gone or no longer// readable by this owner leaves only the record.let starts: Record<string, unknown>[] = []- try { starts = list(object(object(await this.deps.backend(this.core, 'GET', `/api/super-tabs/${tabId}`)).state).starts) }+ try { starts = list((await this.sources.reads.read(tabId)).state.starts) }catch (error) { if (!(error instanceof SuperTabHostError) || ![403, 404].includes(error.status)) throw error }const swarm = new Set(recorded.map(w => w.harnessId))const candidates = recorded.map(w => ({ source: w.source, path: w.path, startId: w.startId, proven: true }))@@ -407,6 +506,82 @@ export class ContributedMachines {}}+// ── Readiness (#229 v1 routing) ─────────────────────────────────────────────────────────────────────────────────────+// The route picked a Windows machine that never started agents, machines without the project and machines that could not+// push, because nothing told it so. The reading says what this machine is ready for; the route leaves out only what it+// says cannot work (routeCommand.ts), and anything unknown stays a candidate.++/** How long an engine's sign-in and a checkout's push access stand before they are read again, and how soon an engine+ * probe that failed is tried again. */+const READINESS_MS = 10 * 60_000+const READINESS_RETRY_MS = 60_000+/** The backend's limit on one reading's checkouts (`machineObservationSchema`). */+const MAX_CHECKOUTS = 64+type ReadyEngine = { engine: string; installed: true | null; signedIn: boolean | null }+type ReadyCheckout = { folder: string; repository: string | null; git: boolean; push: boolean | null }+type GitRun = (cwd: string, args: string[]) => Promise<{ ok: boolean; stdout: string; stderr: string; timedOut?: boolean }>++/** git that never waits on a person (Lead, #229: a machine missing credentials must never hang on a password prompt): no+ * terminal or askpass prompt, no credential manager window, and a session of its own, so ssh has no terminal to ask on.+ * At [timeoutMs] its whole process group is killed, the helpers it started with it, and the answer settles then, even+ * while a helper that got away still holds its output (review of #1743: one could keep a refresh pending for good). */+export function createQuietGit(timeoutMs = 15_000): GitRun {+ return (cwd, args) => new Promise(resolve => {+ const env: NodeJS.ProcessEnv = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '', SSH_ASKPASS: '', SSH_ASKPASS_REQUIRE: 'never',+ GCM_INTERACTIVE: 'never', GIT_OPTIONAL_LOCKS: '0' }+ for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE']) delete env[key]+ const child = spawn('git', ['-C', cwd, ...args], { env, detached: true, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })+ let stdout = '', stderr = '', settled = false+ const settle = (answer: { ok: boolean; timedOut?: boolean }) => { if (!settled) { settled = true; clearTimeout(timer); resolve({ ...answer, stdout, stderr }) } }+ child.stdout.setEncoding('utf8').on('data', (text: string) => { stdout = (stdout + text).slice(0, 65_536) })+ child.stderr.setEncoding('utf8').on('data', (text: string) => { stderr = (stderr + text).slice(0, 65_536) })+ // Its own group (detached), so the group id is its pid; Windows has no groups, and kills git alone. A helper it left+ // behind holding its pipes is ended too, whether git hung or had already gone (re-check of #1743: one left per check).+ const end = () => {+ try { if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, 'SIGKILL'); else child.kill('SIGKILL') } catch { /* already gone */ }+ child.stdout.destroy(); child.stderr.destroy()+ }+ const timer = setTimeout(() => { end(); settle({ ok: false, timedOut: true }) }, timeoutMs)+ child.on('error', () => settle({ ok: false }))+ // Its output is all read once its pipes close; a helper it left running may hold them, so its exit is enough a second on.+ child.on('close', code => settle({ ok: code === 0 }))+ child.on('exit', code => { setTimeout(() => { if (!settled) { end(); settle({ ok: code === 0 }) } }, 1_000).unref() })+ })+}+const quietGit = createQuietGit()++/** What git or the remote says when this login may not push: refused, signed out, or a credential it could not ask for.+ * Anything else (a host it could not reach, a timeout) says nothing about access. */+const NO_PUSH = /permission|denied|returned error: 40[13]|could not read (username|password)|terminal prompts disabled|authentication failed|invalid username or password|repository not found/i++/** What git says of a folder that is no repository at all: the one failure that tells it is not a checkout. */+const NOT_A_REPOSITORY = /not a git repository/i++/** Each project folder in a Swarm folder: the repository its origin names (without credentials), whether it is a+ * checkout of its own, and whether this machine's login can push there, by a dry run that runs no hooks. git's own+ * words never leave the machine. A folder whose probe failed (a timeout, git that would not start, an unreadable+ * repository) is left out, which the route reads as unknown, and [unsure] says to read it again soon. */+export async function readCheckouts(root: string, run: GitRun): Promise<{ checkouts: ReadyCheckout[]; unsure: boolean }> {+ const folders = (await readdir(root, { withFileTypes: true })).filter(e => e.isDirectory() && !e.name.startsWith('.'))+ .map(e => e.name).sort().slice(0, MAX_CHECKOUTS)+ const out: ReadyCheckout[] = []+ let unsure = false+ for (const folder of folders) {+ const dir = join(root, folder)+ const top = await run(dir, ['rev-parse', '--show-toplevel'])+ if (!top.ok && !top.timedOut && NOT_A_REPOSITORY.test(top.stderr)) { out.push({ folder, repository: null, git: false, push: null }); continue }+ const [own, here] = top.ok ? await Promise.all([realpath(top.stdout.trim()).catch(() => null), realpath(dir).catch(() => null)]) : [null, null]+ if (!own || !here) { unsure = true; continue }+ // A folder inside some other checkout is not a checkout of its own.+ if (own !== here) { out.push({ folder, repository: null, git: false, push: null }); continue }+ const origin = await run(dir, ['remote', 'get-url', 'origin'])+ if (!origin.ok) { out.push({ folder, repository: null, git: true, push: null }); continue }+ const pushed = await run(dir, ['push', '--dry-run', '--no-verify', '--porcelain', 'origin', 'HEAD:refs/heads/harness-push-check'])+ out.push({ folder, repository: repositoryKey(origin.stdout.trim()), git: true, push: pushed.ok ? true : !pushed.timedOut && NO_PUSH.test(pushed.stderr) ? false : null })+ }+ return { checkouts: out, unsure }+}+/** The backend's limit on one machine's local models (`machineObservationSchema`). */const MAX_LOCAL_MODELS = 64/** How often the grids this machine may use are read again for its Swarms. */diff --git a/cli/src/superTabs/observers.spec.ts b/cli/src/superTabs/observers.spec.tsindex e79e64e5d..ebb9ea186 100644--- a/cli/src/superTabs/observers.spec.ts+++ b/cli/src/superTabs/observers.spec.ts@@ -71,3 +71,31 @@ it('tells a lapsed roster apart from one in force that names nobody, and acceptsexpect(source.known()).toBeNull()} finally { rmSync(dir, { recursive: true, force: true }) }})++it('refuses every share of a session a roster marks confidential, an ordinary one too, until the session closes on this machine', () => {+ const dir = mkdtempSync(join(tmpdir(), 'super-observer-'))+ let now = 1_000_000+ const source = observerSource(dir, () => 'machine', () => now)+ const row = (harnessId: string, confidential: boolean, tabId = 'tab') => ({ tabId, agent: { machineId: 'machine', harnessId, name: harnessId, configuration: {} },+ observers: [], confidential })+ // Shared the ordinary way, outside any Swarm: a PM that reads private chats, and a Builder.+ const pm = { tab: null, agentId: 'pm', recipientEmail: '[email protected]' } as never+ const builder = { tab: null, agentId: 'builder', recipientEmail: '[email protected]' } as never+ const running = new Set(['pm', 'builder'])+ const live = (harnessId: string) => running.has(harnessId)+ try {+ expect(source.allows(pm)).toBe(true)+ publishObservers(dir, 'machine', [row('pm', true), row('builder', false)], now + OBSERVER_VALID_MS, live); now += 201+ expect(source.allows(pm)).toBe(false)+ expect(source.allows(builder)).toBe(true)+ // Its registration is removed while the session still runs, and another Swarm's row calls it ordinary: still closed.+ publishObservers(dir, 'machine', [], now + OBSERVER_VALID_MS, live); now += OBSERVER_VALID_MS + 1+ expect(source.allows(pm)).toBe(false)+ publishObservers(dir, 'machine', [row('pm', false, 'other')], now + OBSERVER_VALID_MS, live); now += 201+ expect(source.allows(pm)).toBe(false)+ // The session closes on this machine: only then is the mark gone.+ running.delete('pm')+ publishObservers(dir, 'machine', [], now + OBSERVER_VALID_MS, live); now += 201+ expect(source.allows(pm)).toBe(true)+ } finally { rmSync(dir, { recursive: true, force: true }) }+})diff --git a/cli/src/superTabs/observers.ts b/cli/src/superTabs/observers.tsindex fe24bff81..ce686b5eb 100644--- a/cli/src/superTabs/observers.ts+++ b/cli/src/superTabs/observers.ts@@ -20,12 +20,26 @@ export const OBSERVER_VALID_MS = OBSERVER_REFRESH_MS + OBSERVER_SLOW_READ_MSexport function observerSnapshotFile(dataDir: string, machineId: string) {return join(dataDir, 'super-tabs', `observers-${machineId}.json`)}+/** The sessions the last snapshot recorded as confidential (a Lead, or in a private chat, in some Swarm). */+function savedConfidential(file: string, machineId: string): string[] {+ try {+ const saved = object(JSON.parse(readFileSync(file, 'utf8')))+ return saved.machineId === machineId && Array.isArray(saved.confidential) ? saved.confidential.filter(identifier) : []+ } catch { return [] }+}+/** Ephemeral authorization, not a durable grant. A stalled or dead producer's- * snapshot expires; restarting Share never extends it from the clock alone. */-export function publishObservers(dataDir: string, machineId: string, rows: unknown[], until: number) {+ * snapshot expires; restarting Share never extends it from the clock alone.+ * Confidential sessions are the exception: a session a roster marked confidential keeps refusing every share, ordinary ones+ * too, until it closes on this machine (`live` says it no longer runs), whatever later rosters from any Swarm say (final+ * review, Critical 1). Without `live` nothing is cleared. */+export function publishObservers(dataDir: string, machineId: string, rows: unknown[], until: number, live?: (harnessId: string) => boolean) {const wanted: Wanted[] = []+ const dir = join(dataDir, 'super-tabs'), file = observerSnapshotFile(dataDir, machineId)+ const confidential = new Set(savedConfidential(file, machineId).filter(id => !live || live(id)))for (const value of rows) {const row = object(value), agent = object(row.agent)+ if (identifier(agent.harnessId) && agent.machineId === machineId && row.confidential === true) confidential.add(agent.harnessId)if (!identifier(row.tabId) || !identifier(agent.harnessId) || agent.machineId !== machineId || !Array.isArray(row.observers)) continuefor (const observer of row.observers.map(object)) {if (typeof observer.email !== 'string') continue@@ -33,13 +47,12 @@ export function publishObservers(dataDir: string, machineId: string, rows: unknoname: typeof agent.name === 'string' ? agent.name : 'Agent', engine: typeof object(agent.configuration).engine === 'string' ? String(object(agent.configuration).engine) : null })}}- const dir = join(dataDir, 'super-tabs'), file = observerSnapshotFile(dataDir, machineId)mkdirSync(dir, { recursive: true, mode: 0o700 })- writeFileSync(`${file}.next`, JSON.stringify({ machineId, until, wanted }), { mode: 0o600 })+ writeFileSync(`${file}.next`, JSON.stringify({ machineId, until, wanted, confidential: [...confidential] }), { mode: 0o600 })renameSync(`${file}.next`, file)}export function observerSource(dataDir: string, machine: () => string, now = Date.now) {- let readAt = -Infinity, id = '', until = 0, wanted: Wanted[] = []+ let readAt = -Infinity, id = '', until = 0, wanted: Wanted[] = [], confidential: string[] = []const read = (): Wanted[] => {const machineId = machine(), time = now()if (time - readAt >= 200 || machineId !== id) {@@ -48,6 +61,8 @@ export function observerSource(dataDir: string, machine: () => string, now = Datconst raw = readFileSync(observerSnapshotFile(dataDir, machineId), 'utf8')if (raw.length <= 4 * 1024 * 1024) {const saved = object(JSON.parse(raw))+ // Kept whatever the snapshot's age: a lapsed roster must not reopen a confidential session.+ confidential = saved.machineId === machineId && Array.isArray(saved.confidential) ? saved.confidential.filter(identifier) : confidentialif (saved.machineId === machineId && typeof saved.until === 'number' && saved.until <= time + OBSERVER_VALID_MS + 500 && Array.isArray(saved.wanted)) {until = saved.untilwanted = saved.wanted.filter(w => {@@ -70,7 +85,8 @@ export function observerSource(dataDir: string, machine: () => string, now = Dat* and sending them all again. Viewing is still withheld meanwhile (`allows`). A host that stops publishes an* empty roster that is in force, which does withdraw them. */known: (): Wanted[] | null => { const rows = read(); return live() ? rows : null },- allows: (grant: HarnessGrant): boolean => !superTabOf(grant) || current().some(w =>- w.tab === grant.tab && w.agentId === grant.agentId && w.email === grant.recipientEmail),+ /** A confidential session refuses every share, Swarm or ordinary; another Swarm share needs the roster in force. */+ allows: (grant: HarnessGrant): boolean => { read(); return !confidential.includes(grant.agentId) && (!superTabOf(grant) || current().some(w =>+ w.tab === grant.tab && w.agentId === grant.agentId && w.email === grant.recipientEmail)) },}}diff --git a/cli/src/superTabs/partsStore.spec.ts b/cli/src/superTabs/partsStore.spec.tsnew file mode 100644index 000000000..786e06155--- /dev/null+++ b/cli/src/superTabs/partsStore.spec.ts@@ -0,0 +1,84 @@+import { describe, expect, it } from 'vitest'+import { FIXTURE, readFixture } from './fixtures/read/index.js'+import { mergeChanges, storeOf, type PartsStore } from './partsStore.js'+import type { ChangedParts, FirstLoad } from './readContract.js'++const first = () => storeOf(readFixture<FirstLoad>('parts-lead'))+const keys = (store: PartsStore, kind: Parameters<PartsStore['parts']['get']>[0]) => [...store.parts.get(kind)!.keys()]+const changes = (patch: Partial<ChangedParts>): ChangedParts => ({ format: 2, reload: false, cursor: 'next', serverTime: 2, lastChangedAt: 2, epoch: 3,+ head: null, members: [], agents: [], groups: [], machines: [], starts: [], progress: [], derived: { agents: {}, machines: {} }, ...patch })++describe('a Swarm read as parts', () => {+ it('keeps every part of a first load in its order, with the cursor, epoch, change time and derived values', () => {+ const store = first()+ expect(store).toMatchObject({ cursor: 'eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjozfQ', epoch: 3, lastChangedAt: 1793010101002, githubApp: true })+ expect(store.head?.version).toBe(213990)+ expect(keys(store, 'group')).toEqual([FIXTURE.leadGroup, FIXTURE.leadsGroup, FIXTURE.workGroup, FIXTURE.doneGroup])+ expect(keys(store, 'agent')).toEqual([FIXTURE.leadId, FIXTURE.builderId])+ expect(keys(store, 'start')).toEqual([FIXTURE.startId])+ expect(store.derived.machines).toEqual({ [FIXTURE.machineId]: { availableSlots: 2, teamWork: { allowed: true } } })+ })++ it('applies the recorded changes: a newer group, a dormant one leaves, a tombstoned start goes, an overlap duplicate is ignored', () => {+ const store = mergeChanges(first(), readFixture<ChangedParts>('changes-lead'))+ expect(keys(store, 'group')).toEqual([FIXTURE.leadGroup, FIXTURE.leadsGroup, FIXTURE.workGroup])+ expect(store.parts.get('group')!.get(FIXTURE.workGroup)).toMatchObject({ version: 214040, data: { assignment: { status: 'review' } } })+ expect(store.dormant.get(FIXTURE.doneGroup)).toEqual({ key: FIXTURE.doneGroup, version: 214042, changedAt: 1793010105000, dormant: true })+ expect(keys(store, 'start')).toEqual([])+ // Same version as held: the copy in the overlap window is the same part, kept as first read.+ expect(store.parts.get('agent')!.get(FIXTURE.leadId)!.data).toMatchObject({ displayName: 'River' })+ expect(store).toMatchObject({ cursor: 'eyJ2IjoyLCJ0IjoxNzkzMDEwMDc3Mzc1LCJlIjozfQ', lastChangedAt: 1793010106120, githubApp: true })+ expect(store.derived.machines).toEqual({ [FIXTURE.machineId]: { availableSlots: 3, teamWork: { allowed: true } } })+ expect(store.head?.version).toBe(213990)+ })++ // Review round 1: an update moved its part to the end, so ordinary activity reordered status.+ it('keeps every updated part where it was, and puts only new parts at the end', () => {+ const live = (key: string, version: number) => ({ key, version, changedAt: 9, data: { id: key } })+ const store = mergeChanges(first(), changes({+ groups: [live(FIXTURE.workGroup, 214100), live(FIXTURE.leadGroup, 214101), live('c0000000000000000000000a', 214102)],+ agents: [live(FIXTURE.leadId, 214103), live(FIXTURE.builderId, 214104)],+ members: [live(FIXTURE.ownerId, 214105)],+ }))+ expect(keys(store, 'group')).toEqual([FIXTURE.leadGroup, FIXTURE.leadsGroup, FIXTURE.workGroup, FIXTURE.doneGroup, 'c0000000000000000000000a'])+ expect(store.parts.get('group')!.get(FIXTURE.workGroup)!.version).toBe(214100)+ expect(keys(store, 'agent')).toEqual([FIXTURE.leadId, FIXTURE.builderId])+ expect(keys(store, 'member')).toEqual([FIXTURE.ownerId, FIXTURE.collaboratorId])+ })++ it('never lets an older version replace a newer one, nor a tombstone older than what it holds', () => {+ const held = first()+ const older = mergeChanges(held, changes({+ groups: [{ key: FIXTURE.workGroup, version: 214000, changedAt: 1, data: { id: FIXTURE.workGroup, title: 'stale' } }],+ starts: [{ key: FIXTURE.startId, version: 214014, changedAt: 1, deleted: true }],+ }))+ expect(older.parts.get('group')!.get(FIXTURE.workGroup)!.version).toBe(214033)+ expect(keys(older, 'start')).toEqual([FIXTURE.startId])+ })++ it('brings a dormant group back when it changes again, after the groups it had', () => {+ const asleep = mergeChanges(first(), changes({ groups: [{ key: FIXTURE.leadGroup, version: 214011, changedAt: 1, dormant: true }] }))+ expect(keys(asleep, 'group')).toEqual([FIXTURE.leadsGroup, FIXTURE.workGroup, FIXTURE.doneGroup])+ const back = mergeChanges(asleep, changes({ groups: [{ key: FIXTURE.leadGroup, version: 214012, changedAt: 2, data: { id: FIXTURE.leadGroup } }] }))+ expect(keys(back, 'group')).toEqual([FIXTURE.leadsGroup, FIXTURE.workGroup, FIXTURE.doneGroup, FIXTURE.leadGroup])+ expect(back.dormant.has(FIXTURE.leadGroup)).toBe(false)+ })++ it('adds parts it did not know, takes a newer head, and ignores a tombstone for a part it never had', () => {+ const store = mergeChanges(first(), changes({+ head: { key: 'head', version: 214100, changedAt: 3, data: { name: 'Renamed' } },+ agents: [{ key: 'a00000000000000000000009', version: 214101, changedAt: 3, data: { id: 'a00000000000000000000009' } }],+ machines: [{ key: 'd00000000000000000000009', version: 214102, changedAt: 3, deleted: true }],+ }))+ expect(store.head).toMatchObject({ version: 214100, data: { name: 'Renamed' } })+ expect(keys(store, 'agent')).toEqual([FIXTURE.leadId, FIXTURE.builderId, 'a00000000000000000000009'])+ expect(keys(store, 'machine')).toEqual([FIXTURE.machineId])+ })++ it('leaves the store it merged into unchanged', () => {+ const held = first()+ mergeChanges(held, readFixture<ChangedParts>('changes-lead'))+ expect(keys(held, 'group')).toHaveLength(4)+ expect(held.cursor).toBe('eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjozfQ')+ })+})diff --git a/cli/src/superTabs/partsStore.ts b/cli/src/superTabs/partsStore.tsnew file mode 100644index 000000000..20e7e1964--- /dev/null+++ b/cli/src/superTabs/partsStore.ts@@ -0,0 +1,53 @@+/**+ * One Swarm as the client holds it: its parts by kind and key, and the cursor that reads what changed since (design+ * 2026-10-26-swarm-state-parts sections 4.4 and 5.1). A higher version wins, an equal one is the same part seen again in+ * the 30 s overlap, a tombstone removes the part, and a dormant stub moves a group out of the active list. A store is never+ * changed in place: a merge returns a new one, so a read in flight never sees half of another.+ */+import type { ChangedParts, Derived, FirstLoad, PartEnvelope, PartKind, PartsPayload } from './readContract.js'++type ListedKind = Exclude<PartKind, 'head'>+export interface PartsStore {+ cursor: string+ epoch: number+ lastChangedAt: number | null+ githubApp: boolean+ head: PartEnvelope | null+ /** Live parts by kind, in the order the server listed them; new keys go last. */+ parts: Map<ListedKind, Map<string, PartEnvelope>>+ /** Groups that went dormant, as their stub: out of the active list until they change again. */+ dormant: Map<string, PartEnvelope>+ derived: Derived+}++const LISTS: Array<[keyof PartsPayload, ListedKind]> = [+ ['members', 'member'], ['agents', 'agent'], ['groups', 'group'], ['machines', 'machine'], ['starts', 'start'], ['progress', 'progress'],+]++export function storeOf(first: FirstLoad): PartsStore {+ const parts = new Map<ListedKind, Map<string, PartEnvelope>>(LISTS.map(([field, kind]) =>+ [kind, new Map((first[field] as PartEnvelope[]).map(part => [part.key, part]))]))+ return { cursor: first.cursor, epoch: first.epoch, lastChangedAt: first.lastChangedAt, githubApp: first.githubApp === true,+ head: first.head, parts, dormant: new Map(), derived: first.derived }+}++export function mergeChanges(store: PartsStore, changes: ChangedParts): PartsStore {+ const parts = new Map([...store.parts].map(([kind, held]) => [kind, new Map(held)]))+ const dormant = new Map(store.dormant)+ for (const [field, kind] of LISTS) {+ const held = parts.get(kind)!+ for (const part of changes[field] as PartEnvelope[]) {+ const known = held.get(part.key) ?? (kind === 'group' ? dormant.get(part.key) : undefined)+ if (known && known.version >= part.version) continue+ dormant.delete(part.key)+ // A live part replaced in place keeps its position: Map.set on a key it holds does not move it, so status keeps its+ // order while parts change (review round 1). A part new to the active list goes at the end.+ if (part.dormant || part.deleted) held.delete(part.key)+ if (part.dormant) dormant.set(part.key, part)+ else if (!part.deleted) held.set(part.key, part)+ }+ }+ const head = changes.head && (!store.head || changes.head.version > store.head.version) ? changes.head : store.head+ return { cursor: changes.cursor, epoch: changes.epoch, lastChangedAt: changes.lastChangedAt, githubApp: store.githubApp,+ head, parts, dormant, derived: changes.derived }+}diff --git a/cli/src/superTabs/readContract.ts b/cli/src/superTabs/readContract.tsnew file mode 100644index 000000000..05b7ff0e4--- /dev/null+++ b/cli/src/superTabs/readContract.ts@@ -0,0 +1,82 @@+/**+ * The Swarm read API as the CLI reads it (docs/design/2026-10-26-swarm-state-parts.md section 4). Mirrored by hand from the+ * backend's `backend/src/superTabs/read/contract.ts` at cd004bf5c, the one source of truth; a change there is announced+ * before it merges (design 7.2). Records inside parts keep their JSON shape and are read as plain objects here. Times are+ * epoch milliseconds.+ */+type Json = Record<string, unknown>++/** The only format this client reads (design 4.3). Another one is a newer server: Harness needs an update. */+export const READ_FORMAT = 2+export const UPDATE_REQUIRED = 'UPDATE_REQUIRED'+/** The text every client shows for HTTP 426 (design 4.11, 5.1; the contract's `UPDATE_REQUIRED.message`). */+export const UPDATE_MESSAGE = 'Update Harness to keep using this Swarm.'++export type PartKind = 'head' | 'member' | 'agent' | 'group' | 'machine' | 'start' | 'progress'+/** A live part (`data`), a removed one (`deleted`, never with data), or a group that left the active set (`dormant`).+ * A group's `data` has its own `messageSeq`, and `dormant`/`audience` only when set; an agent's never has the values that+ * come in `derived` (`downSince`, `limitedUntil`, `roleId`). */+export interface PartEnvelope<T = Json> {+ key: string+ version: number+ changedAt: number+ data?: T+ deleted?: true+ dormant?: true+}++/** Values the server recomputes for every response and the client overlays on the parts (design 4.1). */+export interface Derived {+ /** Every agent the reader can see. `workDecision` null when the stored value stands; `roleId` null outside Custom. */+ agents: Record<string, { downSince: string | null; limitedUntil: string | null; workDecision: 'awaiting' | null; roleId: string | null }>+ /** Every contributed machine the reader can see. */+ machines: Record<string, Json>+ /** A Lead agent only. */+ otherProjectsWork?: Json[]+ /** A person only. */+ mentionsWaiting?: number+}++interface ReadMeta {+ format: number+ /** Opaque: unpadded base64url, sent back unchanged. */+ cursor: string+ serverTime: number+ /** The newest data change of any part of this Swarm; null for a Swarm with no parts yet. */+ lastChangedAt: number | null+ epoch: number+}+/** What first load and changes share: the parts by kind, `head` null in changes when it did not change. */+export interface PartsPayload extends ReadMeta {+ head: PartEnvelope | null+ members: PartEnvelope[]+ agents: PartEnvelope[]+ groups: PartEnvelope[]+ machines: PartEnvelope[]+ starts: PartEnvelope[]+ progress: PartEnvelope[]+ derived: Derived+}+/** `GET /api/super-tabs/:tabId/parts` (design 4.3). */+export interface FirstLoad extends PartsPayload { tabId: string; githubApp?: true }+/** `GET /api/super-tabs/:tabId/changes?cursor=` (design 4.4); `{ reload: true }` asks for a first load instead. */+export type ChangedParts = PartsPayload & { reload: false }+export type Changes = ChangedParts | { reload: true }++/** `GET /api/super-tabs/list` (design 4.9). */+export interface ListPage { tabs: Array<{ id: string; name: string; ownerId: string; paused: boolean; lastChangedAt: number | null }>; next: string | null }++/** One Swarm's rows in the host form (design 4.10): today's roster, pool and assignments, and `etag`, a short hash of those+ * rows without this machine's own reading or the rows' change times, sent back in `held`. */+export interface HostTabRows { tabId: string; lastChangedAt: number | null; etag: string; roster: Json[]; pool: Json | null; assignments: Json[] }+/** The rows still hash to the `etag` the host sent in `held`: keep them (only `lastChangedAt` may have moved). */+export interface HostTabUnchanged { tabId: string; lastChangedAt: number | null; etag: string; unchanged: true }+export type HostTab = HostTabRows | HostTabUnchanged+/** The body of `POST /api/super-tabs/hosts/:machineId/changes`, used once the host holds etags (up to 500 Swarms do not fit+ * in a URL); a host that holds nothing asks by `GET` with `?cursor=` or `?full=1`. */+export interface HostChangesRequest { cursor?: string; full?: boolean; held?: Record<string, string> }+export interface HostChanges { format: number; full: boolean; cursor: string; tabs: HostTab[]; removedTabIds: string[] }++/** A conversation's messages, ordered by `(sequence, id)` (design 4.6). With no cursor, the newest 100, `next` naming the+ * oldest row: sent back as `before` and `beforeId` for the page before. `next` is null at the end. */+export interface MessagePage { messages: Json[]; next: { sequence: number; id: string } | null }diff --git a/cli/src/superTabs/reassemble.spec.ts b/cli/src/superTabs/reassemble.spec.tsnew file mode 100644index 000000000..8e48b81d6--- /dev/null+++ b/cli/src/superTabs/reassemble.spec.ts@@ -0,0 +1,70 @@+import { describe, expect, it } from 'vitest'+import { FIXTURE, readFixture } from './fixtures/read/index.js'+import { mergeChanges, storeOf } from './partsStore.js'+import { reassemble } from './reassemble.js'+import type { ChangedParts, FirstLoad, PartEnvelope } from './readContract.js'++type Json = Record<string, unknown>+const legacy = (name: 'legacy-tab-lead' | 'legacy-tab-builder') => readFixture<{ state: Json }>(name).state+const list = (v: unknown) => v as Json[]++describe('the old Swarm state, rebuilt from parts', () => {+ it('equals what the full read gave a Lead, field by field', () => {+ expect(reassemble(storeOf(readFixture<FirstLoad>('parts-lead')))).toEqual(legacy('legacy-tab-lead'))+ })++ it('equals what the full read gave a Builder, field by field', () => {+ expect(reassemble(storeOf(readFixture<FirstLoad>('parts-builder')))).toEqual(legacy('legacy-tab-builder'))+ })++ it('follows the recorded changes: the dormant group leaves, the start goes, slots and the stored agent values come back', () => {+ const state = reassemble(mergeChanges(storeOf(readFixture<FirstLoad>('parts-lead')), readFixture<ChangedParts>('changes-lead')))+ expect(list(state.conversations).map(c => c.id)).toEqual([FIXTURE.leadGroup, FIXTURE.leadsGroup, FIXTURE.workGroup])+ expect(list(state.conversations)[2]).toMatchObject({ lastMessageSequence: 214041, assignment: { status: 'review' } })+ expect(state.starts).toEqual([])+ expect(list(state.machines)[0]).toMatchObject({ availableSlots: 3, observation: { receivedAt: 1793010105000 } })+ // Down no longer, no limit, and the decision the server stored.+ const builder = list(state.agents)[1]+ expect(builder).not.toHaveProperty('downSince')+ expect(builder).not.toHaveProperty('workDecision')+ expect(builder).not.toHaveProperty('limitedUntil')+ expect(state.otherProjectsWork).toEqual([])+ expect(list(state.projects)[0].progress).toEqual({ since: 1793009900000, dirtyRevision: 214041, summarizedRevision: 213800, requestedRevision: 213800 })+ })++ it('counts a group a Lead summarized in its project progress, and carries the request it last made', () => {+ const first = readFixture<FirstLoad>('parts-lead')+ first.progress[0].data = { since: 5, summarizedFloor: 213800, summarized: { [FIXTURE.workGroup]: 214020 },+ requestedFloor: 213700, requested: { [FIXTURE.workGroup]: 214030, [FIXTURE.doneGroup]: 213990 }, requestedAt: 6, requestMessageId: 'r1' }+ expect(list(reassemble(storeOf(first)).projects)[0].progress)+ .toEqual({ since: 5, dirtyRevision: 214033, summarizedRevision: 214020, requestedRevision: 214030, requestedAt: 6, requestMessageId: 'r1' })+ })++ it('shows a usage limit while it lasts', async () => {+ const first = readFixture<FirstLoad>('parts-lead')+ first.derived.agents[FIXTURE.builderId].limitedUntil = '2026-10-26T12:00:00.000Z'+ expect(list(reassemble(storeOf(first)).agents)[1].limitedUntil).toBe('2026-10-26T12:00:00.000Z')+ })++ it('shows the role on Custom skills, none when its kind has no role there, and no role elsewhere', () => {+ const first = readFixture<FirstLoad>('parts-lead')+ const project = list((first.head!.data as Json).projects)[0]+ project.skillMode = 'custom'+ project.skillSet = 'custom'+ first.derived.agents![FIXTURE.leadId].roleId = 'lead-role'+ expect(list(reassemble(storeOf(first)).agents).map(a => a.roleId)).toEqual(['lead-role', null])+ const plain = readFixture<FirstLoad>('parts-lead')+ ;(plain.agents[0].data as Json).roleId = 'left-from-custom'+ expect(list(reassemble(storeOf(plain)).agents)[0]).not.toHaveProperty('roleId')+ })++ it('gives a person their waiting mentions, and a Swarm from before projects no progress', () => {+ const first = readFixture<FirstLoad>('parts-builder')+ first.derived.mentionsWaiting = 2+ delete (first.head!.data as Json).projects+ first.progress = [] as PartEnvelope[]+ const state = reassemble(storeOf(first))+ expect(state.mentionsWaiting).toBe(2)+ expect(state).not.toHaveProperty('projects')+ })+})diff --git a/cli/src/superTabs/reassemble.ts b/cli/src/superTabs/reassemble.tsnew file mode 100644index 000000000..13d2866ee--- /dev/null+++ b/cli/src/superTabs/reassemble.ts@@ -0,0 +1,66 @@+/**+ * The Swarm state in the shape the full read gave it (`SuperTabState` as `visibleState` made it), built from the parts the+ * client holds, so `status`, routing, the host and the Pro cards read what they always read (design+ * 2026-10-26-swarm-state-parts sections 5.1 and 6.2; the backend's `parts/shape.ts` is the reference). `derived` carries+ * what changes without a part changing (time and values across parts) and is laid over the parts here.+ */+import type { PartsStore } from './partsStore.js'+import { object } from './wire.js'++type Json = Record<string, unknown>+/** What a group part adds to a conversation for the server's own bookkeeping; the old state never had them (design 6.2). */+const GROUP_INTERNALS = ['messageSeq', 'dormant']++const dataOf = (store: PartsStore, kind: Parameters<PartsStore['parts']['get']>[0]): Json[] =>+ [...store.parts.get(kind)?.values() ?? []].map(part => structuredClone(object(part.data)))+const highest = (floor: unknown, marks: unknown) =>+ Math.max(typeof floor === 'number' ? floor : 0, ...Object.values(object(marks)).filter((v): v is number => typeof v === 'number'))++/** A project's progress in its old fields, for reading only: dirty up to its groups' newest message (a reader is not sent the+ * server's per-group report mark, which leaves out hold and stop notices), summarized and requested up to the furthest+ * mark the Lead's reports and the wake-ups reached. */+function progressOf(stored: Json, projectId: unknown, leadConversationId: unknown, groups: Json[]): Json {+ const reported = groups.filter(g => g.projectId === projectId && g.id !== leadConversationId && g.kind !== 'leads')+ .map(g => typeof g.lastMessageSequence === 'number' ? g.lastMessageSequence : 0)+ return { since: stored.since, dirtyRevision: Math.max(0, ...reported),+ summarizedRevision: highest(stored.summarizedFloor, stored.summarized), requestedRevision: highest(stored.requestedFloor, stored.requested),+ ...(typeof stored.requestedAt === 'number' ? { requestedAt: stored.requestedAt } : {}),+ ...(typeof stored.requestMessageId === 'string' ? { requestMessageId: stored.requestMessageId } : {}) }+}++/** `visibleState`'s per-agent rules: down since the computed time or not down; a limit while it lasts (a part never holds+ * one, so one that ran out is simply absent); the stored decision unless one is derived (`awaiting`); on Custom skills the+ * role it runs (null when its kind has none), else no role. */+function overlayAgent(agent: Json, derived: Json | undefined, projects: Json[]): Json {+ if (!derived) return agent+ if (typeof derived.downSince === 'string') agent.downSince = derived.downSince+ else delete agent.downSince+ if (typeof derived.limitedUntil === 'string') agent.limitedUntil = derived.limitedUntil+ if (typeof derived.workDecision === 'string') agent.workDecision = derived.workDecision+ if (projects.find(p => p.id === agent.projectId)?.skillSet === 'custom') agent.roleId = typeof derived.roleId === 'string' ? derived.roleId : null+ else delete agent.roleId+ return agent+}++export function reassemble(store: PartsStore): Json {+ const head = structuredClone(object(store.head?.data))+ const derived = store.derived+ const groups = dataOf(store, 'group')+ const progress = new Map([...store.parts.get('progress')?.entries() ?? []].map(([key, part]) => [key, object(part.data)]))+ const projects = Array.isArray(head.projects) ? head.projects.map(object) : null+ const state: Json = { ...head,+ people: dataOf(store, 'member'),+ agents: dataOf(store, 'agent').map(agent => overlayAgent(agent, object(derived.agents)[String(agent.id)] as Json | undefined, projects ?? [])),+ conversations: groups.map(group => Object.fromEntries(Object.entries(group).filter(([key]) => !GROUP_INTERNALS.includes(key)))),+ machines: dataOf(store, 'machine').map(machine => ({ ...machine, ...object(object(derived.machines)[String(machine.machineId)]) })),+ starts: dataOf(store, 'start') }+ if (projects) {+ state.projects = projects.map(project => {+ const stored = progress.get(String(project.id))+ return stored ? { ...project, progress: progressOf(stored, project.id, project.leadConversationId, groups) } : project+ })+ }+ if (derived.otherProjectsWork !== undefined) state.otherProjectsWork = derived.otherProjectsWork+ if (derived.mentionsWaiting !== undefined) state.mentionsWaiting = derived.mentionsWaiting+ return state+}diff --git a/cli/src/superTabs/route.spec.ts b/cli/src/superTabs/route.spec.tsindex 6028b2adf..d7d98364a 100644--- a/cli/src/superTabs/route.spec.ts+++ b/cli/src/superTabs/route.spec.ts@@ -1,6 +1,6 @@// cli/src/superTabs/route.spec.tsimport { describe, expect, it } from 'vitest'-import { API_BUILDERS, LOCAL_NONE, breaks, choose, decide, floorFor, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, type Assessment, type Commitment, type MemberFrame, type Policy, type Probe, type SwarmRule, type TaskFolder } from './route.js'+import { API_BUILDERS, LOCAL_NONE, breaks, choose, decide, floorFor, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, repositoryKey, type Assessment, type Commitment, type MemberFrame, type Policy, type Probe, type SwarmRule, type TaskFolder } from './route.js'const object = (v: unknown) => v as Record<string, unknown>@@ -403,6 +403,22 @@ describe('candidate labels', () => {})})+describe('repositoryKey', () => {+ it('names a repository the same way over HTTPS and SSH, without credentials or case', () => {+ for (const url of ['https://github.com/Acme/App.git', 'https://someone:[email protected]/acme/app/', '[email protected]:Acme/App.git',+ 'ssh://[email protected]:22/acme/app.git', ' HTTPS://GitHub.com/acme/app ']) expect(repositoryKey(url)).toBe('github.com/acme/app')+ })+ it('keeps nothing of a query or fragment, where a credential can be too', () => {+ for (const url of ['https://example.test/Acme/Repo.git?access_token=SYNTHETIC_SECRET', 'https://example.test/acme/repo#token=SYNTHETIC_SECRET',+ '[email protected]:acme/repo.git?access_token=SYNTHETIC_SECRET', 'ssh://[email protected]/acme/repo.git#SYNTHETIC_SECRET']) {+ expect(repositoryKey(url)).toBe('example.test/acme/repo')+ }+ })+ it('names nothing for a folder on disk or an address it cannot read', () => {+ for (const url of ['/srv/remote.git', 'file:///srv/remote.git', '', 'https://github.com', 'not a url']) expect(repositoryKey(url)).toBeNull()+ })+})+describe('repoMatch', () => {it('marks a member as in the task\'s repository by remote, then root, then folder', () => {expect(repoMatch(null, frame(), true)).toBeUndefined()diff --git a/cli/src/superTabs/route.ts b/cli/src/superTabs/route.tsindex 6e4dc01b0..2e13fb36f 100644--- a/cli/src/superTabs/route.ts+++ b/cli/src/superTabs/route.ts@@ -166,6 +166,26 @@ export function repoMatch(folder: TaskFolder | null, frame: MemberFrame | null,return (folder.root ?? folder.cwd) === theirs ? 'same' : 'different'}+/** A repository's name for comparing two addresses of it: host and path, lowercase, without credentials, port or `.git`,+ * the same over HTTPS and SSH. Null for a folder on disk or an address it cannot read. A machine reports its checkouts'+ * origins this way (machines.ts readCheckouts), so no credential in an origin leaves it. */+export function repositoryKey(url: string): string | null {+ const text = url.trim()+ // Only the host and the path are kept: userinfo, a port, a query and a fragment can all carry what is not the repository's+ // name, a token among them (review of #1743).+ const scp = /^[\w.-]+@([\w.-]+):(?!\/)([^?#]+)/.exec(text)+ let host: string | undefined, path: string | undefined+ if (scp) [, host, path] = scp+ else {+ try {+ const parsed = new URL(text)+ if (['http:', 'https:', 'ssh:', 'git:'].includes(parsed.protocol)) [host, path] = [parsed.hostname, decodeURIComponent(parsed.pathname)]+ } catch { /* Not an address: a folder on disk, or nothing readable. */ }+ }+ const clean = path?.replace(/^\/+|\/+$/g, '').replace(/\.git$/i, '')+ return host && clean ? `${host}/${clean}`.toLowerCase() : null+}+/** A member's model is what its engine reported after work: Claude's full id (`claude-opus-4-7`, `claude-sonnet-4-5[1m]`),* Codex's slug (`gpt-5.5`). The policy names Claude families and a Codex `default`, so the id is reduced to its family* first, and an id with no row of its own takes the engine's `default` row before the floor. */diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.tsindex 2d3f04b47..dbdecfcb9 100644--- a/cli/src/superTabs/routeCommand.spec.ts+++ b/cli/src/superTabs/routeCommand.spec.ts@@ -101,11 +101,67 @@ describe('routeTask', () => {expect(offered.length).toBeGreaterThan(0)expect(offered.some(c => /^(Lead|Multiply) ·/.test(c))).toBe(false)})- it('does not offer a member that is already working on a task', async () => {- const s = scoped({ tab: tab({ id: 'x', agentId: 'a1', status: 'working' }) })+ // A lost task's agent died, stalled or hit a limit: its work goes to someone else (v1 liveness), never back to it. The+ // backend marks the agent in the same write that loses the task (backend superTabs/liveness.ts).+ it.each(['working', 'lost'])('does not offer a member whose task is %s', async status => {+ const state = tab({ id: 'x', agentId: 'a1', status })+ if (status === 'lost') state.state.agents = agents.map(a => a.id === 'a1' ? { ...a, lostTask: { conversationId: 'g1', assignmentId: 'x', reason: 'stalled', at: 1 } } : a)+ const s = scoped({ tab: state })await routeTask(input, s, where as never, opener(id => daemon(id, { agents: ['h1'] })))expect((recorded(s).command.decision.candidates as Array<{ title: string }>).some(c => c.title.startsWith('Multiply'))).toBe(false)})+ // Final review, Important 3: cancelling or reassigning lost work must not make its old worker routable again.+ describe('a member whose last task was lost', () => {+ const lostTask = { conversationId: 'g0', assignmentId: 'x', reason: 'no progress for 30 minutes', at: 1 }+ const healthy = { id: 'a3', name: 'Healthy', machineId: 'm1', harnessId: 'h3', configuration: { engine: 'claude', model: 'sonnet', effort: 'medium' } }+ const earlier = (assignment: Record<string, unknown>, more: Record<string, unknown> = {}) =>+ ({ id: 'g0', title: 'Old', leadId: 'lead', agentIds: ['lead', 'a1'], archived: false, brief: 'Old work.', checks: [], assignment, ...more })+ const lost = { id: 'x', agentId: 'a1', lost: { reason: lostTask.reason, at: 1 } }+ const route = async (members: unknown[], groups: unknown[]) => {+ const state = tab(); Object.assign(state.state, { agents: members, conversations: [...state.state.conversations, ...groups] })+ const s = scoped({ tab: state })+ const result = await routeTask(input, s, where as never, opener(id => daemon(id, { agents: ['h1', 'h3'] })), () => 'op')+ const decision = recorded(s).command.decision+ return { result, candidates: (decision.candidates as Array<{ title: string; agentId?: string }>), excluded: decision.excluded as Array<{ title: string; reason: string }> }+ }+ const marked = agents.map(a => a.id === 'a1' ? { ...a, lostTask } : a)+ const reason = 'It lost its last task (no progress for 30 minutes). It takes work again once a person assigns it by hand or the Lead replaces it.'++ it('stays out after the Lead cancels the lost task, and a healthy member is offered instead', async () => {+ const { result, candidates, excluded } = await route([...marked, healthy], [earlier({ ...lost, status: 'cancelled' })])+ expect(candidates.some(c => c.title.startsWith('Multiply'))).toBe(false)+ expect(excluded).toContainEqual({ title: 'Multiply · Claude sonnet medium · remote-1', reason })+ expect(result).toMatchObject({ ok: true, pick: { kind: 'member', agentId: 'a3' } })+ })+ it('stays out after the Lead hands the lost task to another agent', async () => {+ const { result, candidates, excluded } = await route([...marked, healthy],+ [earlier({ id: 'y', agentId: 'a3', status: 'working' }, { lostAttempt: { id: 'x', agentId: 'a1' } })])+ expect(candidates.some(c => c.title.startsWith('Multiply'))).toBe(false)+ expect(excluded).toContainEqual({ title: 'Multiply · Claude sonnet medium · remote-1', reason })+ expect(result).toMatchObject({ ok: true, pick: { kind: 'new' } })+ })+ it('is offered again once it finished a new task, which clears its mark', async () => {+ const { candidates } = await route([...agents, healthy],+ [earlier({ ...lost, status: 'cancelled' }), earlier({ id: 'z', agentId: 'a1', status: 'done' }, { id: 'g2' })])+ expect(candidates.some(c => c.title.startsWith('Multiply'))).toBe(true)+ })+ it('stays out while its task is still lost', async () => {+ const { excluded } = await route(marked, [earlier({ ...lost, status: 'lost' })])+ expect(excluded).toContainEqual({ title: 'Multiply · Claude sonnet medium · remote-1', reason })+ })+ // Re-check of #1749: recovery clears the mark while the old task may still be lost; that task alone must not refuse it.+ it('is offered again after its terminal was replaced, though its old task is still lost', async () => {+ const replaced = agents.map(a => a.id === 'a1' ? { ...a, harnessId: 'h1b' } : a)+ const state = tab(); Object.assign(state.state, { agents: replaced, conversations: [...state.state.conversations, earlier({ ...lost, status: 'lost' })] })+ const s = scoped({ tab: state })+ await routeTask(input, s, where as never, opener(id => daemon(id, { agents: ['h1b'] })), () => 'op')+ expect((recorded(s).command.decision.candidates as Array<{ title: string }>).some(c => c.title.startsWith('Multiply'))).toBe(true)+ })+ it('is offered again after it finished a newer task, though its old task is still lost', async () => {+ const { candidates } = await route(agents, [earlier({ ...lost, status: 'lost' }), earlier({ id: 'z', agentId: 'a1', status: 'done' }, { id: 'g2' })])+ expect(candidates.some(c => c.title.startsWith('Multiply'))).toBe(true)+ })+ })it('leaves out what breaks the owner\'s rules in the tab, and ignores a rule it cannot read', async () => {const ruled = tab(); (ruled.state as Record<string, unknown>).rules = [{ id: 'r1', rule: { kind: 'forbidModel', model: 'sonnet' }, text: 'No Sonnet.' }, { id: 'r2', text: 7 }]const s = scoped({ tab: ruled })@@ -212,6 +268,19 @@ describe('routeTask', () => {expect(open.mock.calls.map(c => c[1])).toEqual(['m1'])expect(recorded(s).command.decision.candidates.some((c: { title: string }) => c.title.startsWith('New agent') && c.title.includes('m1'))).toBe(true)})+ it('starts nothing on an account machine that says it runs Windows, or whose last two starts started nothing', async () => {+ const windows = opener(id => daemon(id, { agents: id === 'm1' ? ['h1'] : [], capacity: { resources: { memoryTotalBytes: 8e9, memoryUsedBytes: 1e9, cpuPercent: 10, projectDiskFreeBytes: 1e11, os: 'Windows' }, tools: { git: true }, devices: {} } }))+ const s = scoped()+ expect(await routeTask(input, s, where, windows)).toMatchObject({ ok: true, pick: { kind: 'member' } })+ expect(recorded(s).command.decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({ title: expect.stringContaining('New agent'),+ reason: expect.stringContaining('Swarm agents do not run on Windows yet.') })]))+ const failed = { id: 's', request: { machineId: 'm1' }, harnessId: null, dispatched: true, error: 'The engine did not start.' }+ const t = tab(); Object.assign(t.state, { starts: [failed, { ...failed, id: 's2' }] })+ const stuck = scoped({ tab: t })+ await routeTask(input, stuck, where, opener())+ expect(recorded(stuck).command.decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({ title: expect.stringContaining('remote-1'),+ reason: expect.stringContaining('last 2 starts') })]))+ })it('says a listed machine without the project folder needs it cloned, not that its disk could not be verified', async () => {const needs = { cwd: '/repo/api' }const noFolder = { ok: true, resources: { memoryTotalBytes: 8e9, memoryUsedBytes: 1e9, cpuPercent: 10 }, tools: {}, devices: {} }@@ -655,10 +724,13 @@ describe('routing contributed capacity', () => {const healthy = () => ({ machineId: 'm1', name: 'Contributed laptop', cwd: '/owner/project', engines: ['claude'], paused: false,observation: { receivedAt: Date.now(), resources: { memoryTotalBytes: 32e9, memoryUsedBytes: 2e9, projectDiskFreeBytes: 200e9 },tools: { git: true }, runningHarnessIds: ['h1'], quotas: [{ engine: 'claude', known: true, windows: [{ name: '5-hour', usedPercent: 20, resetsAt: Date.now() + 3600000 }] }] } })- async function runPool(pool: Record<string, any>, members = false, needs: Record<string, unknown> = {}, project?: Record<string, unknown>) {+ async function runPool(pool: Record<string, any>, members = false, needs: Record<string, unknown> = {}, project?: Record<string, unknown>,+ more: { state?: Record<string, unknown>; tab?: Record<string, unknown>; review?: boolean } = {}) {const groups = conversations()if (project) Object.assign(groups[1]!, { projectId: project.id })- const s = scoped({ context: { ok: true, value: { agentId: 'lead', tab: { state: { id: 'tab', agents: members ? agents : [agents[1]], conversations: groups, machines: [pool], ...(project ? { projects: [project] } : {}) } }, policy: { policy, warnings: [] }, machines: [] } } })+ if (more.review) Object.assign(groups[1]!, { reviewOf: 'g0' })+ const crew = members ? agents.map(a => more.review && a.id === 'a1' ? { ...a, role: 'reviewer' } : a) : [agents[1]]+ const s = scoped({ context: { ok: true, value: { agentId: 'lead', tab: { ...more.tab, state: { id: 'tab', agents: crew, conversations: groups, machines: [pool], ...(project ? { projects: [project] } : {}), ...more.state } }, policy: { policy, warnings: [] }, machines: [] } } })const open = opener()const answer = await routeTask({ ...input, assessment: { ...input.assessment, needs } }, s, where, open)expect(open).not.toHaveBeenCalled()@@ -736,6 +808,91 @@ describe('routing contributed capacity', () => {expect((await runPool(shared, false, {}, { id: 'project-two' })).answer.ok).not.toBe(true)expect((await runPool(shared)).answer.ok).not.toBe(true)})+ // v1 routing (#229): the route sent work to a Windows machine that never started agents, to machines without the+ // project and to machines that could not push. A machine that says it cannot do the work is left out, with why; one+ // that says nothing is not.+ describe('what a machine says it is ready for', () => {+ const reasons = (answer: Record<string, unknown>) => (answer.excluded as Array<{ title: string; reason: string }>)+ const project = { id: 'p2', ownerId: 'owner', repository: { machineId: 'other', cwd: '/elsewhere', repositoryUrl: 'https://github.com/Example/Two.git' } }+ const swarm = (checkouts?: unknown[], engines?: unknown[]) => {+ const pool: Record<string, any> = { ...healthy(), scope: 'swarm', cwd: '/swarm-root', contributorId: 'owner' }+ pool.observation.readiness = { ...(checkouts ? { checkouts } : {}), ...(engines ? { engines } : {}) }+ return pool+ }+ const checkout = (extra: Record<string, unknown> = {}) => ({ folder: 'p2', repository: 'github.com/example/two', git: true, push: true, ...extra })++ it('never starts a Swarm agent on Windows, and keeps a member already there', async () => {+ const windows = healthy(); Object.assign(windows.observation.resources, { os: 'Windows' })+ const { answer } = await runPool(windows)+ expect(answer).toMatchObject({ error: 'NO_CANDIDATE' })+ expect(reasons(answer)[0]!.reason).toContain('Swarm agents do not run on Windows yet')+ expect((await runPool(windows, true)).answer).toMatchObject({ ok: true, pick: { kind: 'member' } })+ })++ it('leaves out an engine the machine says is signed out or not installed, and keeps one whose sign-in is unknown', async () => {+ const out = await runPool(swarm(undefined, [{ engine: 'claude', installed: true, signedIn: false }]), false, {}, project)+ expect(out.answer).toMatchObject({ error: 'NO_CANDIDATE' })+ expect(reasons(out.answer)[0]!.reason).toContain('Claude Code is not signed in to a subscription on this machine.')+ const missing = await runPool(swarm(undefined, [{ engine: 'claude', installed: false, signedIn: null }]), false, {}, project)+ expect(reasons(missing.answer)[0]!.reason).toContain('Claude Code is not installed on this machine.')+ for (const engines of [[{ engine: 'claude', installed: true, signedIn: null }], [{ engine: 'claude', installed: null, signedIn: null }], [{ engine: 'codex', installed: true, signedIn: false }], [{ engine: 'cursor', installed: false, signedIn: null }], []]) {+ expect((await runPool(swarm(undefined, engines), false, {}, project)).answer.ok).toBe(true)+ }+ })++ it('still offers a local model on a machine whose engine is signed out, since the grid needs no subscription', async () => {+ const grid = 'swarm-0123456789ab', pool = swarm(undefined, [{ engine: 'claude', installed: true, signedIn: false }])+ pool.observation.localModels = [{ grid, model: 'qwen3' }]+ const { answer, s } = await runPool(pool, false, {}, project, { state: { localModels: { grid, enabled: true } } })+ expect(answer).toMatchObject({ ok: true, pick: { gridModel: 'qwen3' } })+ expect(recorded(s).command.decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({ reason: expect.stringContaining('not signed in') })]))+ })++ it('leaves out a project folder that is not a checkout of the project\'s repository', async () => {+ const plain = await runPool(swarm([checkout({ git: false, repository: null, push: null })]), false, {}, project)+ expect(plain.answer).toMatchObject({ error: 'NO_CANDIDATE' })+ expect(reasons(plain.answer)[0]!.reason).toContain('is not a git checkout')+ const other = await runPool(swarm([checkout({ repository: 'github.com/example/other' })]), false, {}, project)+ expect(reasons(other.answer)[0]!.reason).toContain('checkout of another repository')+ // Its own repository under another address, no folder yet (it is cloned on start), or a remote it cannot name.+ for (const checkouts of [[checkout()], [checkout({ folder: 'p9', git: false })], [checkout({ repository: null })]]) {+ expect((await runPool(swarm(checkouts), false, {}, project)).answer.ok).toBe(true)+ }+ expect((await runPool(swarm([checkout({ repository: 'github.com/example/other' })]), false, {}, { ...project, repository: { ...project.repository, repositoryUrl: undefined, machineId: 'm1' } })).answer.ok).toBe(true)+ })++ it('leaves out a machine whose login cannot push when the work needs a push, members too', async () => {+ const denied = swarm([checkout({ push: false })])+ const work = await runPool(denied, true, {}, project)+ expect(work.answer).toMatchObject({ error: 'NO_CANDIDATE' })+ expect(reasons(work.answer).map(r => r.reason)).toEqual(expect.arrayContaining([expect.stringContaining('cannot push to the project repository')]))+ expect(reasons(work.answer).some(r => r.title.includes('Multiply'))).toBe(true)+ // A review pushes nothing, and an unknown push is no refusal.+ expect((await runPool(swarm([checkout({ push: false })]), true, {}, project, { review: true })).answer.ok).toBe(true)+ expect((await runPool(swarm([checkout({ push: null })]), false, {}, project)).answer.ok).toBe(true)+ })++ it('ignores the machine\'s own login when a teammate\'s project pushes through the Harness GitHub App', async () => {+ const mates = { ...project, ownerId: 'mate' }+ expect((await runPool(swarm([checkout({ push: false })]), false, {}, mates, { tab: { githubApp: true } })).answer.ok).toBe(true)+ // The owner's own project still pushes with the owner's login, and without the App so does a teammate's.+ expect((await runPool(swarm([checkout({ push: false })]), false, {}, project, { tab: { githubApp: true } })).answer.ok).not.toBe(true)+ expect((await runPool(swarm([checkout({ push: false })]), false, {}, mates)).answer.ok).not.toBe(true)+ })++ it('leaves out a machine whose last two starts started nothing, until one does', async () => {+ const start = (extra: Record<string, unknown>) => ({ id: `s${Math.random()}`, request: { machineId: 'm1' }, harnessId: null, dispatched: false, error: null, ...extra })+ const failed = start({ error: 'Claude Code is not signed in.' }), queued = start({}), started = start({ harnessId: 'h9', dispatched: true })+ const stuck = await runPool(healthy(), true, {}, undefined, { state: { starts: [started, failed, queued] } })+ expect(stuck.answer).toMatchObject({ ok: true, pick: { kind: 'member' } })+ expect(recorded(stuck.s).command.decision.excluded).toEqual(expect.arrayContaining([expect.objectContaining({+ title: expect.stringContaining('New agent'), reason: expect.stringContaining('last 2 starts') })]))+ for (const starts of [[failed, started], [failed], [failed, start({ dispatched: true })], [failed, queued].map(s => ({ ...s, request: { machineId: 'm9' } }))]) {+ expect((await runPool(healthy(), false, {}, undefined, { state: { starts } })).answer.ok).toBe(true)+ }+ })+ })+it.each([['stale', (p: any) => { p.observation.receivedAt = 0 }],['paused', (p: any) => { p.paused = true }],diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.tsindex 5546c25c1..2c125bcb9 100644--- a/cli/src/superTabs/routeCommand.ts+++ b/cli/src/superTabs/routeCommand.ts@@ -7,7 +7,7 @@ import { openDaemon, type Daemon, type Where } from '../agentClient/daemon.js'import { requiredToolReason, startRequirements } from './capacity.js'import { inspectCapacity, type ScopedRequest } from './start.js'import { ENDED_WORK, object, within } from './wire.js'-import { API_BUILDERS, choose, decide, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, type Assessment, type Commitment, type HeldModel, type MemberFrame, type Policy, type Probe, type SwarmRule, type TaskFolder } from './route.js'+import { API_BUILDERS, choose, decide, parseAssessment, quotaOf2, rateFor, recordOf, repoMatch, repositoryKey, type Assessment, type Commitment, type HeldModel, type MemberFrame, type Policy, type Probe, type SwarmRule, type TaskFolder } from './route.js'import { stat } from 'node:fs/promises'import { describeScmProject } from '../scm/scmProjects.js'@@ -23,6 +23,48 @@ const OFFLINE = 'Machine is offline or unreachable.'const UNKNOWN_QUOTA: Probe['quota'] = { known: false, leftPercent: null, resetsAt: null }const UNKNOWN_LOAD: NonNullable<Probe['load']> = { agents: null, freeMemoryBytes: null, hasFolder: null }const EXHAUSTED_WINDOW = 'The subscription has an exhausted usage window. Wait for a fresh allowance reading or choose another account.'+/** Temporary (Scholes, 2026-10-26): grid's CLI does not run on Windows yet, so a Swarm agent started there never comes up+ * (WIN-DELL took starts that silently never ran). Lifting it is emptying this list. Compared with the OS every reading+ * has (lib/machineHardware.ts names it `Windows`), so a host from before readiness is left out too. */+const NO_SWARM_AGENTS_ON: readonly string[] = ['Windows']+const ENGINE_NAME: Record<string, string> = { claude: 'Claude Code', codex: 'Codex' }+const NO_PUSH = "This machine's git login cannot push to the project repository. Its owner can sign in to GitHub there (gh auth login, then gh auth setup-git)."+const STALLED = 'Its last 2 starts on this machine started no agent (they failed or were never picked up), so it is left out until a start there succeeds. Its owner can check the machine.'+/** What a machine says it cannot do for this task (#229 v1 routing): `all` keeps out its new agents, `engines` those of an+ * engine, `push` its new agents and members alike. Only a known failure is said; anything unknown says nothing. */+interface Unready { all: string[]; engines: Record<string, string>; push: string | null }+const READY: Unready = { all: [], engines: {}, push: null }+/** Whether the Swarm's last 2 starts on [machineId] both started nothing: failed, or queued and never picked up. A start+ * being created (dispatched, no agent yet) is not counted, nor is a machine with fewer than 2 starts. */+function stalled(starts: Json[], machineId: string): boolean {+ const last = starts.filter(s => object(s.request).machineId === machineId).slice(-2)+ return last.length === 2 && last.every(s => !s.harnessId && (!!s.error || s.dispatched !== true))+}+/** What a contributed machine's reading says it is not ready for, for work in [projectId] ([needsPush] unless a review).+ * Its own login's push access counts only when it is the one that pushes: not for a teammate's project where the server+ * has the Harness GitHub App, whose token the agent pushes with (start.ts). */+function unreadyPool(pool: Json, project: Json | undefined, projectId: string, needsPush: boolean, githubApp: boolean, projectOwner: unknown): Unready {+ const observed = object(pool.observation), readiness = object(observed.readiness), repository = object(project?.repository)+ const engines: Record<string, string> = {}+ for (const e of list(readiness.engines)) {+ const name = ENGINE_NAME[String(e.engine)]+ if (!name) continue+ if (e.installed === false) engines[String(e.engine)] = `${name} is not installed on this machine.`+ // Worded as a subscription's, so a Builder on a local model, which runs through the grid without one, is not kept out.+ else if (e.signedIn === false) engines[String(e.engine)] = `${name} is not signed in to a subscription on this machine. Its owner can sign in there; the next reading clears this.`+ }+ // Only a Swarm folder's own checkout of the project is read; the repository's machine runs it from the Lead's checkout.+ const checkout = pool.scope === 'swarm' && repository.machineId !== pool.machineId ? list(readiness.checkouts).find(c => c.folder === projectId) : undefined+ const wanted = typeof repository.repositoryUrl === 'string' ? repositoryKey(repository.repositoryUrl) : null+ const all = [+ ...(NO_SWARM_AGENTS_ON.includes(String(object(observed.resources).os)) ? [`Swarm agents do not run on ${String(object(observed.resources).os)} yet.`] : []),+ ...(checkout?.git === false ? ['The project folder on this machine is not a git checkout. Its owner can remove it, and the next start clones the project.'] : []),+ ...(checkout?.git === true && wanted && typeof checkout.repository === 'string' && checkout.repository !== wanted+ ? ['The project folder on this machine is a checkout of another repository. Its owner can remove it, and the next start clones the project.'] : []),+ ]+ const app = githubApp && projectOwner !== pool.contributorId+ return { all, engines, push: needsPush && !app && checkout?.push === false ? NO_PUSH : null }+}/** A running member keeps its engine and memory, but still needs a live terminal, account allowance and the task's tools. */function memberRefusals(running: boolean | null, quota: Probe['quota'], tools: string[], devices: string[], reportedTools: Json, reportedDevices: Json, toolProbeErrors: Json): string[] {return [@@ -143,7 +185,7 @@ export async function routeTask(input: { tabId: string; conversationId: string;// (production, 2026-10-21). A member may run on a machine only its collaborator can open; the Lead tries that machine// too, but a member there is unknown, never offline.const swarmMachines = new Set([where.machineId, ...list(state.machines).map(m => String(m.machineId)), ...agents.map(a => String(a.machineId))])- const machines = new Map<string, { name: string; status: string; account: boolean; pool?: Json; folded?: boolean }>()+ const machines = new Map<string, { name: string; status: string; account: boolean; pool?: Json; folded?: boolean; unready?: Unready; stalled?: boolean }>()for (const m of list(value.machines)) if (swarmMachines.has(String(m.machineId))) machines.set(String(m.machineId), { name: String(m.name), status: String(m.status ?? 'unknown'), account: true })// The Lead's own machine is the account's even when the list could not be read.if (!machines.has(where.machineId)) machines.set(where.machineId, { name: where.machineId, status: 'unknown', account: true })@@ -164,8 +206,10 @@ export async function routeTask(input: { tabId: string; conversationId: string;...(original.scope === 'swarm' && repository.machineId !== original.machineId && typeof repository.repositoryUrl !== 'string'? { repositoryUnavailable: true } : {}),}- machines.set(String(pool.machineId), { name: String(pool.name), status: 'contributed', account: false, pool })+ machines.set(String(pool.machineId), { name: String(pool.name), status: 'contributed', account: false, pool,+ unready: unreadyPool(original, project, projectId, !review, object(value.tab).githubApp === true, projectOwner) })}+ for (const [machineId, machine] of machines) machine.stalled = stalled(list(state.starts), machineId)// One machine (docs/plans/2026-10-24-swarm-team-account.md): a Mac's Harness Team account is that Mac, under its name. A// teammate's project starts only in the team account and the Mac's owner's own projects only with the owner, so only one// of the two offers new agents here, and the other is not listed as unfit; agents already on either stay members.@@ -196,8 +240,17 @@ export async function routeTask(input: { tabId: string; conversationId: string;const until = Date.parse(String(members.find(m => m.id === agentId)?.limitedUntil))return until > Date.now() ? [`Its screen showed a usage limit until ${new Date(until).toISOString()}.`] : []}+ // Nor does the agent of a lost task take work: it died, stalled or hit a limit, and its work goes to another (v1 liveness).+ // The backend keeps that mark on the agent until it recovers (backend superTabs/model.ts lostTask), since cancelling or+ // reassigning the task leaves it idle, and the task's group drops out of this read once it goes quiet (final review,+ // Important 3). The mark alone decides: recovery clears it while the old task may still be lost (re-check of #1749).+ const lostTask = (agentId: string | undefined) => {+ const marked = members.find(m => m.id === agentId)?.lostTask+ // The backend writes the mark with its loss's reason (backend superTabs/liveness.ts loseTask).+ return marked ? [`It lost its last task (${String(object(marked).reason)}). It takes work again once a person assigns it by hand or the Lead replaces it.`] : []+ }const probes = probed.flat().map(p => p.kind === 'member' ? { ...p, repo: repoMatch(folder, p.frame ?? null, p.machineId === where.machineId),- refusals: [...p.refusals, ...limited(p.agentId)],+ refusals: [...p.refusals, ...limited(p.agentId), ...lostTask(p.agentId)],earlier: ended.filter(e => e.agentId === p.agentId).reverse().slice(0, 3).map(e => ({ group: e.group, outcome: e.outcome })) } : p)probes.push(...localProbes(state, policy, probes, assessment, review))// Picks started or assigned and still at work hold part of their account's quota; the log, and so this, is per Swarm.@@ -316,7 +369,7 @@ export function localProbes(state: Json, policy: Policy, probes: Probe[], a: Assrefusals: base.refusals.filter(r => !SUBSCRIPTION.test(r)), gridModel: m.model, gridName: m.grid, gridLabel: m.label, gridKind: m.kind })))}-async function probeMachine(machineId: string, { name: machineName, status, account, pool, folded }: { name: string; status: string; account: boolean; pool?: Json; folded?: boolean },+async function probeMachine(machineId: string, { name: machineName, status, account, pool, folded, unready = READY, stalled: stuck = false }: { name: string; status: string; account: boolean; pool?: Json; folded?: boolean; unready?: Unready; stalled?: boolean },members: Json[], allModels: Policy['models'], policy: Policy, a: Assessment, where: Where, open: typeof openDaemon): Promise<Probe[]> {const listedEngines = Array.isArray(pool?.engines) ? pool.engines.filter((engine): engine is string => typeof engine === 'string') : []const legacy = listedEngines.some(engine => !ENGINES.includes(engine))@@ -352,15 +405,17 @@ async function probeMachine(machineId: string, { name: machineName, status, acco...(!finite(resources.projectDiskFreeBytes) || resources.projectDiskFreeBytes < needs.diskBytes ? ['The project has insufficient measured free disk.'] : []),...(!finite(resources.memoryTotalBytes) || !finite(resources.memoryUsedBytes) || resources.memoryTotalBytes - resources.memoryUsedBytes < needs.memoryBytes ? ['Insufficient measured free memory.'] : []),...needs.tools.map(t => requiredToolReason(t, tools[t], object(observed.toolProbeErrors)[t])).filter((reason): reason is string => reason !== null),- ...(needs.devices.length ? ['Required devices have not been reported.'] : [])]+ ...(needs.devices.length ? ['Required devices have not been reported.'] : []),+ ...unready.all, ...(unready.push ? [unready.push] : []), ...(stuck ? [STALLED] : [])]return [...members.map(m => {const allowance = quota(String(object(m.configuration).engine))const running = Array.isArray(observed.runningHarnessIds) ? observed.runningHarnessIds.includes(m.harnessId) : nullreturn memberProbe(m, fresh ? [...memberRefusals(running, allowance, needs.tools, needs.devices, tools, object(observed.devices), object(observed.toolProbeErrors)),- ...teammates(m.contributorId)] : [OFFLINE],+ ...teammates(m.contributorId), ...(unready.push ? [unready.push] : [])] : [OFFLINE],allowance, null, fresh && running === null)}),- ...models.map(m => newProbe(m, [...newReasons, ...(quota(m.engine).leftPercent === 0 ? ['Subscription exhausted.'] : [])], quota(m.engine), fresh && quota(m.engine).known,+ ...models.map(m => newProbe(m, [...newReasons, ...(unready.engines[m.engine] ? [unready.engines[m.engine]!] : []),+ ...(quota(m.engine).leftPercent === 0 ? ['Subscription exhausted.'] : [])], quota(m.engine), fresh && quota(m.engine).known,{ agents: Array.isArray(observed.runningHarnessIds) ? observed.runningHarnessIds.length : null,freeMemoryBytes: finite(resources.memoryTotalBytes) && finite(resources.memoryUsedBytes) ? resources.memoryTotalBytes - resources.memoryUsedBytes : null,hasFolder: finite(resources.projectDiskFreeBytes) }))]@@ -404,7 +459,10 @@ async function probeMachine(machineId: string, { name: machineName, status, acco// could not measure the named folder's disk, a missing folder is the likely cause; a failed or unsupported read says nothing.const noFolder = !!a.needs.cwd && machineId !== where.machineId && object(inspected.capacity).ok === true && !finite(resources.projectDiskFreeBytes)const reasons = noFolder ? inspected.reasons.map(r => r === DISK_UNVERIFIED ? NO_PROJECT_FOLDER : r) : inspected.reasons- probes.push(newProbe(m, inspected.allowed ? [] : reasons, quotaOf2(inspected.quota), inspected.unknown.length === 0 && inspected.quota.known, load))+ // A machine reached directly says its OS in the same capacity read (lib/machineHardware.ts).+ const os = String(resources.os)+ const unfit = [...(NO_SWARM_AGENTS_ON.includes(os) ? [`Swarm agents do not run on ${os} yet.`] : []), ...(stuck ? [STALLED] : [])]+ probes.push(newProbe(m, [...(inspected.allowed ? [] : reasons), ...unfit], quotaOf2(inspected.quota), inspected.unknown.length === 0 && inspected.quota.known, load))}return probes} finally { target.close() }diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.tsindex 99e1c0ce0..65da53a30 100644--- a/cli/src/superTabs/service.spec.ts+++ b/cli/src/superTabs/service.spec.ts@@ -7,15 +7,28 @@ import { fakeCore } from '../testing/fakeCore.js'import type { CoreApi } from '../core/api.js'import { sharedSwarm, superTabService } from './service.js'import { object } from './wire.js'+import { hostForm, swarmReply } from './fixtures/read/index.js'+import { HostFeed } from './hostFeed.js'+import { SwarmReads } from './swarmReads.js'const list = (value: unknown) => Array.isArray(value) ? value.map(object) : []import { hostJournalFile, SuperTabHostError, type SuperTabHost, type SuperTabHostOptions } from './host.js'const owner = { local: true, owner: true }, visitor = { local: false, owner: false }+/** The backend's Lead rule: an agent leads a project when it leads that project's Lead conversation ('lead' before projects). */+const leads = (state: Record<string, unknown>, agentId: unknown) => {+ const ids = Array.isArray(state.projects) ? list(state.projects).map(p => p.leadConversationId) : ['lead']+ return list(state.conversations).some(c => ids.includes(c.id) && c.leadId === agentId)+}+/** This test's Swarm as the backend serves it: the host form lists [agent] on its machine (a Lead by the backend's rule), a read+ * of the tab gets [state] by parts, and anything else gets [state] as the whole Swarm's read once did. */+const swarmData = (agent: Record<string, unknown>, path: string, state: Record<string, unknown> = { agents: [agent] }): unknown =>+ path.includes('/hosts/') ? hostForm([{ tabId: 'tab', agent, lead: leads(state, agent.id) }], { tabs: ['tab'] })+ : /^\/api\/super-tabs\/tab\/(parts|changes)/.test(path) ? swarmReply(path, state) : { state }function setup(options: { prepareContribution?: typeof import('./contribution.js').prepareContribution } = {}) {const agentId = createHash('sha256').update(JSON.stringify(['machine-1', 'native'])).digest('hex').slice(0, 24)const agent = { id: agentId, machineId: 'machine-1', harnessId: 'native' }- const call = vi.fn<CoreApi['account']['backend']>(async () => ({ status: 200, body: { success: true, data: { state: { agents: [agent] } } } }))+ const call = vi.fn<CoreApi['account']['backend']>(async (_method, path) => ({ status: 200, body: { success: true, data: swarmData(agent, path) } }))const core = fakeCore({ account: { backend: call }, agents: { byAgent: vi.fn(() => ({ agentId: 'native' }) as never) } })const start = vi.fn(), stop = vi.fn()const service = superTabService(core, { host: () => ({ machineId: 'machine-1', start, stop }) as unknown as SuperTabHost, ...options })@@ -24,7 +37,7 @@ function setup(options: { prepareContribution?: typeof import('./contribution.jsdescribe('restart role lookup through the service', () => {it('does not start the delivery loop when a personal session restarts', async () => {const host = vi.fn(() => ({ machineId: 'machine-1', start: vi.fn(), stop: vi.fn(), swarmRole: async () => null }) as never)- const core = fakeCore({ account: { backend: vi.fn(async () => ({ status: 200, body: { data: [] } })) } })+ const core = fakeCore({ account: { backend: vi.fn(async () => ({ status: 200, body: { data: hostForm([]) } })) } })const service = superTabService(core, { host })expect(await service.port.swarmRole('personal')).toBeNull()expect(await service.requests.super_tabs({ action: 'swarmRole', harnessId: 'personal' }, owner)).toEqual({ ok: true, role: null })@@ -34,7 +47,7 @@ describe('restart role lookup through the service', () => {it('answers the same current role in inline and process requests, for the owner only', async () => {const agent = { id: 'agent', machineId: 'machine-1', harnessId: 'old-native' }const call = vi.fn<CoreApi['account']['backend']>(async (_method, path) => ({ status: 200, body: { data:- path.includes('/hosts/') ? [{ tabId: 'tab', agent }] : { state: { agents: [agent], conversations: [{ leadId: 'agent' }] } } } }))+ path.includes('/hosts/') ? hostForm([{ tabId: 'tab', agent }]) : swarmReply(path, { agents: [agent], conversations: [{ leadId: 'agent' }] }) } }))const service = superTabService(fakeCore({ account: { backend: call } }))expect(await service.port.swarmRole('old-native')).toEqual({ role: 'lead', mode: 'orchestration' })expect(await service.requests.super_tabs({ action: 'swarmRole', harnessId: 'old-native' }, owner)).toEqual({ ok: true, role: 'lead', mode: 'orchestration' })@@ -213,7 +226,7 @@ it('explains to a Lead other projects\' work and the Leads conversation', asyncit('resolves a native caller to its exact contribution and rechecks it before every agent command', async () => {const t = setup()expect(await t.ask({ action: 'status', tabId: 'tab', harnessId: 'native' }, owner)).toMatchObject({ ok: true })- expect(t.call).toHaveBeenLastCalledWith('GET', `/api/super-tabs/tab?asAgentId=${t.agentId}`, undefined)+ expect(t.call).toHaveBeenLastCalledWith('GET', `/api/super-tabs/tab/parts?asAgentId=${t.agentId}`, undefined)const command = { type: 'message.send', conversationId: 'lead', text: 'Ready', replyTo: null, recipientIds: [] }expect(await t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'op', command }, owner)).toMatchObject({ ok: true, operationId: 'op' })expect(t.call).toHaveBeenLastCalledWith('POST', '/api/super-tabs/tab/commands', { operationId: 'op', command, asAgentId: t.agentId })@@ -236,7 +249,7 @@ describe('other projects\' work in status', () => {const state = { agents: [t.agent], leadsConversationId: 'leads', ...(legacy ? {} : { projects: [{ id: 'pilot', name: 'Pilot', leadConversationId: 'pilot' }] }),conversations: [{ id: lead, leadId, agentIds: [t.agentId] }, ...groups, { id: 'leads', kind: 'leads', title: 'Leads', leadId: null, agentIds: [t.agentId] }],otherProjectsWork: [{ ...work, assignmentId: 'internal', brief: 'The whole brief' }] }- t.call.mockImplementation(async () => ({ status: 200, body: { success: true, data: { revision: 7, state } } }))+ t.call.mockImplementation(async (_method, path) => ({ status: 200, body: { success: true, data: swarmData(t.agent, path, state) } }))}const status = async (t: ReturnType<typeof setup>) => object(object(object(await t.ask({ action: 'status', tabId: 'tab', agentId: t.agentId }, owner)).value).state)@@ -279,10 +292,8 @@ describe('other projects\' work in status', () => {it('resolves a replacement terminal to the original stable member', async () => {const t = setup()t.agent.harnessId = 'replacement'- t.call.mockImplementation(async (_method, path) => ({ status: 200, body: { data: path.includes('/hosts/')- ? [{ tabId: 'tab', agent: t.agent }] : { state: { agents: [t.agent] } } } }))expect(await t.ask({ action: 'status', tabId: 'tab', harnessId: 'replacement' }, owner)).toMatchObject({ ok: true })- expect(t.call).toHaveBeenLastCalledWith('GET', `/api/super-tabs/tab?asAgentId=${t.agentId}`, undefined)+ expect(t.call).toHaveBeenLastCalledWith('GET', `/api/super-tabs/tab/parts?asAgentId=${t.agentId}`, undefined)expect(await t.ask({ action: 'status', tabId: 'tab', harnessId: 'native' }, owner)).toMatchObject({ error: 'AGENT_UNAVAILABLE' })})@@ -349,12 +360,12 @@ it('returns the routing context to a verified contribution', async () => {const t = setup()vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => path.includes('/routing-policy')? { status: 200, body: { success: true, data: { policy: { version: 1 }, warnings: [], overridden: [] } } }- : { status: 200, body: { success: true, data: { state: { agents: [t.agent] } } } })+ : { status: 200, body: { success: true, data: swarmData(t.agent, path) } })t.core.account.machines = vi.fn(async () => ({ status: 200, body: { success: true, data: {machines: [{ machineId: 'm1', name: 'remote-1', status: 'online' }],sharedMachines: [{ machineId: 'm2', name: 'shared', status: 'online', share: { added: true } }, { machineId: 'm3', name: 'not added', status: 'online' }] } } }))expect(await t.ask({ action: 'routeContext', tabId: 'tab', harnessId: 'native' }, owner)).toEqual({ ok: true, value: {- agentId: t.agentId, tab: { state: { agents: [t.agent] } }, policy: { policy: { version: 1 }, warnings: [], overridden: [] },+ agentId: t.agentId, tab: { lastChangedAt: expect.any(Number), state: expect.objectContaining({ agents: [t.agent] }) }, policy: { policy: { version: 1 }, warnings: [], overridden: [] },machines: [{ machineId: 'm1', name: 'remote-1', status: 'online' }, { machineId: 'm2', name: 'shared', status: 'online' }] } })expect(t.call).toHaveBeenCalledWith('GET', `/api/super-tabs/tab/routing-policy?asAgentId=${t.agentId}`, undefined)})@@ -363,7 +374,9 @@ describe('routeHistory', () => {const state = { agents: [{ ...t.agent, name: 'Boss' }, { id: 'a2', name: 'Multiply' }, { id: 'a3', name: 'Reader' }], conversations: [{ id: 'g1', leadId: lead ?? t.agentId }] }vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => {if (path.includes('/messages') || path.includes('/route-decisions') || path.includes('/attempts')) return await read(path) as never- return { status: 200, body: { success: true, data: path.includes('/routing-policy') ? { policy: { version: 1 }, warnings: [] } : { state } } }+ // The one group by id (design 4.5), from the same state.+ if (path.startsWith('/api/super-tabs/tab/groups/g1?')) return { status: 200, body: { success: true, data: { group: { key: 'g1', version: 1, changedAt: 1, data: state.conversations[0] } } } }+ return { status: 200, body: { success: true, data: path.includes('/routing-policy') ? { policy: { version: 1 }, warnings: [] } : swarmData(t.agent, path, state) } }})t.core.account.machines = vi.fn(async () => ({ status: 200, body: { data: { machines: [] } } }))return t.ask({ action: 'routeHistory', tabId: 'tab', harnessId: 'native', conversationId: 'g1' }, owner) as Promise<{ value: Record<string, unknown> }>@@ -456,7 +469,7 @@ it('says the machine list could not be read, instead of offering none', async ()const t = setup()vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => path.includes('/routing-policy')? { status: 200, body: { success: true, data: { policy: { version: 1 }, warnings: [], overridden: [] } } }- : { status: 200, body: { success: true, data: { state: { agents: [t.agent] } } } })+ : { status: 200, body: { success: true, data: swarmData(t.agent, path) } })for (const answer of [async () => ({ status: 503, body: { error: 'SERVICE_UNAVAILABLE' } }), async () => { throw new Error('link lost') }]) {t.core.account.machines = vi.fn(answer)expect(await t.ask({ action: 'routeContext', tabId: 'tab', harnessId: 'native' }, owner)).toMatchObject({ ok: true, value: { machines: [], machinesUnreadable: true } })@@ -497,7 +510,7 @@ describe('which messages still need an answer', () => {it('marks messages addressed to the caller as answered or not, and leaves the rest unmarked', async () => {const t = setup()vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => ({ status: 200, body: { success: true,- data: path.includes('/messages') ? { messages: rows(t.agentId), next: null } : { state: { agents: [t.agent] } } } }))+ data: path.includes('/messages') ? { messages: rows(t.agentId), next: null } : swarmData(t.agent, path) } }))const value = (await t.ask({ action: 'messages', tabId: 'tab', agentId: t.agentId, conversationId: 'lead' }, owner) as { value: { messages: Record<string, unknown>[] } }).valueexpect(value.messages.map(m => m.answered)).toEqual([true, false, undefined, undefined, false])// A person's email is passed as the backend sent it.@@ -507,7 +520,7 @@ describe('which messages still need an answer', () => {const t = setup()vi.mocked(t.core.account.backend).mockImplementation(async (_method, path) => {const all = rows(t.agentId)- const data = path.includes('messageId=m1') ? { messages: [all[0]] } : path.includes('after=1') ? { messages: all.slice(1) } : { state: { agents: [t.agent] } }+ const data = path.includes('messageId=m1') ? { messages: [all[0]] } : path.includes('after=1') ? { messages: all.slice(1) } : swarmData(t.agent, path)return { status: 200, body: { success: true, data } }})const value = (await t.ask({ action: 'message', tabId: 'tab', agentId: t.agentId, conversationId: 'lead', messageId: 'm1' }, owner) as { value: { messages: Record<string, unknown>[] } }).value@@ -523,7 +536,7 @@ describe('which messages still need an answer', () => {const all = rows(t.agentId)if (path.includes('after=') && failAfter) return { status: 500, body: { success: false, error: { code: 'DOWN', message: 'down' } } }const data = path.includes('messageId=m3') ? { messages: [all[2]] } : path.includes('messageId=m1') ? { messages: [all[0]] }- : path.includes('after=') ? { messages: all.slice(1) } : { state: { agents: [t.agent] } }+ : path.includes('after=') ? { messages: all.slice(1) } : swarmData(t.agent, path)return { status: 200, body: { success: true, data } }})const ask = (messageId: string) => t.ask({ action: 'message', tabId: 'tab', agentId: t.agentId, conversationId: 'lead', messageId }, owner) as Promise<{ ok?: boolean; value: { messages: Record<string, unknown>[] } }>@@ -541,12 +554,12 @@ describe('post --attach steps', () => {const t = setup()const messageId = createHash('sha256').update(JSON.stringify(['tab', `agent:${t.agentId}`, 'op'])).digest('hex').slice(0, 24)vi.mocked(t.core.account.backend).mockImplementation(async (_method: string, path: string) => ({ status: 200, body: { success: true, data:- path.includes('/messages?') ? { messages: [{ id: messageId, attachments: [{ id: 'f0' }] }] } : { state: { agents: [t.agent] } } } }))+ path.includes('/messages?') ? { messages: [{ id: messageId, attachments: [{ id: 'f0' }] }] } : swarmData(t.agent, path) } }))expect(await t.ask({ action: 'attachment', step: 'sent', tabId: 'tab', agentId: t.agentId, conversationId: 'lead', operationId: 'op' }, owner)).toEqual({ ok: true, value: { agentId: t.agentId, attachmentIds: ['f0'] } })expect(t.call).toHaveBeenLastCalledWith('GET', `/api/super-tabs/tab/conversations/lead/messages?asAgentId=${t.agentId}&messageId=${messageId}`, undefined)vi.mocked(t.core.account.backend).mockImplementation(async (_method: string, path: string) => ({ status: 200, body: { success: true, data:- path.includes('/messages?') ? { messages: [] } : { state: { agents: [t.agent] } } } }))+ path.includes('/messages?') ? { messages: [] } : swarmData(t.agent, path) } }))expect(await t.ask({ action: 'attachment', step: 'sent', tabId: 'tab', agentId: t.agentId, conversationId: 'lead', operationId: 'op' }, owner)).toEqual({ ok: true, value: { agentId: t.agentId, attachmentIds: null } })})@@ -563,7 +576,7 @@ it('says a server from before rules does not support them, and passes a malformeconst t = setup()const refuse = (message: string) => t.call.mockImplementation(async (...args: unknown[]) => args[0] === 'POST'? { status: 400, body: { success: false, error: { code: 'VALIDATION_ERROR', message } } } as never- : { status: 200, body: { success: true, data: { state: { agents: [t.agent] } } } })+ : { status: 200, body: { success: true, data: swarmData(t.agent, args[1] as string) } })const send = (command: object) => t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'rule', command }, owner)refuse("command.type: Invalid discriminator value. Expected 'machine.contribute'")expect(await send({ type: 'rule.set', rule: { kind: 'preferIdle' }, text: 'Idle first.' })).toEqual({ error: 'RULES_UNSUPPORTED', detail: 'This Swarm\'s server does not support rules yet.' })@@ -580,7 +593,7 @@ it('documents finished worker decisions and explains an older backend without reexpect(help.release).toContain('prefer stop')t.call.mockImplementation(async (...args: unknown[]) => args[0] === 'POST'? { status: 400, body: { success: false, error: { code: 'VALIDATION_ERROR', message: 'Invalid request' } } } as never- : { status: 200, body: { success: true, data: { state: { agents: [t.agent] } } } })+ : { status: 200, body: { success: true, data: swarmData(t.agent, args[1] as string) } })const reply = await t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'release', command: { type: 'agent.release', agentId: 'worker', decision: 'stop' } }, owner)expect(reply).toMatchObject({ detail: 'This backend does not support releasing Builders yet. Update the backend and try again.' })})@@ -656,7 +669,7 @@ describe('a Lead\'s terminal result', () => {it('reads the result of its own terminal request as the calling agent, and nothing for a bad id', async () => {const t = setup()t.call.mockImplementation(async (_method, path) => ({ status: 200, body: { success: true, data: path.includes('/terminal/')- ? { ok: true, text: 'Allow? 1. Yes' } : { state: { agents: [t.agent] } } } }))+ ? { ok: true, text: 'Allow? 1. Yes' } : swarmData(t.agent, path) } }))expect(await t.ask({ action: 'terminalResult', tabId: 'tab', agentId: t.agentId, terminalRequestId: 'r1', requestId: 'transport-1' }, owner)).toEqual({ ok: true, value: { ok: true, text: 'Allow? 1. Yes' } })expect(t.call.mock.calls.at(-1)!.slice(0, 2)).toEqual(['GET', `/api/super-tabs/tab/terminal/r1?asAgentId=${t.agentId}`])@@ -666,8 +679,8 @@ describe('a Lead\'s terminal result', () => {describe('GitHub App tokens through the service', () => {it('gives a local agent its task\'s token, never one asked for through the relay', async () => {- const call = vi.fn<CoreApi['account']['backend']>(async (method, path) => ({ status: 200, body: { success: true, data: method === 'GET' && path.endsWith('/machine-1')- ? [{ tabId: 'tab-1', agent: { id: 'agent-1', machineId: 'machine-1', harnessId: 'native' } }]+ const call = vi.fn<CoreApi['account']['backend']>(async (method, path) => ({ status: 200, body: { success: true, data: method === 'GET' && path.includes('/hosts/machine-1/changes')+ ? hostForm([{ tabId: 'tab-1', agent: { id: 'agent-1', machineId: 'machine-1', harnessId: 'native' } }]): { token: 'ghs_fixtureToken0000001', expiresAt: '2026-10-24T13:00:00.000Z', repository: 'acme/app', trailers: [] } } }))const service = superTabService(fakeCore({ account: { backend: call }, agents: { byAgent: vi.fn(() => ({ agentId: 'native' }) as never) } }),{ githubTokens: () => ({ start: vi.fn(), stop: vi.fn() }) })@@ -751,19 +764,24 @@ describe('the Harness Team account, offered by Desktop on this Mac', () => {it('at app start, counts a Swarm this Mac is in with anyone else in it', async () => {const answers = (pools: unknown, tabs: Record<string, unknown>) => vi.fn<CoreApi['account']['backend']>(async (_method, path) => {- if (path.endsWith('/pools')) return pools instanceof Error ? { status: 503, body: { success: false } } : { status: 200, body: { success: true, data: pools } }- const tab = tabs[path.split('/').pop()!]- return tab ? { status: 200, body: { success: true, data: tab } } : { status: 403, body: { success: false, error: { code: 'FORBIDDEN' } } }+ if (path.includes('/hosts/')) return pools instanceof Error ? { status: 503, body: { success: false } }+ : { status: 200, body: { success: true, data: Array.isArray(pools) ? hostForm([], { pools }) : pools } }+ const tab = tabs[path.split('/')[3]!]+ return tab ? { status: 200, body: { success: true, data: swarmReply(path, tab as Record<string, unknown>) } } : { status: 403, body: { success: false, error: { code: 'FORBIDDEN' } } }})- const core = (call: CoreApi['account']['backend'], machineId = 'machine-1') => fakeCore({ account: { backend: call }, daemon: { machineId: () => machineId } as never })+ const sources = (call: CoreApi['account']['backend'], machineId = 'machine-1') => {+ const core = fakeCore({ account: { backend: call }, daemon: { machineId: () => machineId } as never })+ return { feed: new HostFeed(core, machineId), reads: new SwarmReads(core) }+ }const shared = answers([{ tabId: 'solo' }, { tabId: 'gone' }, { tabId: 'team' }],- { solo: { state: { people: [{ id: 'me' }] } }, team: { state: { people: [{ id: 'me' }, { id: 'kim' }] } } })- expect(await sharedSwarm(core(shared))).toBe(true)- expect(shared).toHaveBeenCalledWith('GET', '/api/super-tabs/hosts/machine-1/pools', undefined)- expect(await sharedSwarm(core(answers([{ tabId: 'solo' }, { tabId: '../x' }], { solo: { state: { people: [{ id: 'me' }] } } })))).toBe(false)- expect(await sharedSwarm(core(answers(new Error('down'), {})))).toBe(false)- expect(await sharedSwarm(core(answers({ not: 'a list' }, {})))).toBe(false)- expect(await sharedSwarm(core(answers([], {}), ''))).toBe(false)+ { solo: { people: [{ id: 'me' }] }, team: { people: [{ id: 'me' }, { id: 'kim' }] } })+ expect(await sharedSwarm(sources(shared))).toBe(true)+ expect(shared.mock.calls.map(c => c[1])).toEqual(['/api/super-tabs/hosts/machine-1/changes?full=1',+ '/api/super-tabs/solo/parts', '/api/super-tabs/gone/parts', '/api/super-tabs/team/parts'])+ expect(await sharedSwarm(sources(answers([{ tabId: 'solo' }, { tabId: '../x' }], { solo: { people: [{ id: 'me' }] } })))).toBe(false)+ expect(await sharedSwarm(sources(answers(new Error('down'), {})))).toBe(false)+ expect(await sharedSwarm(sources(answers({ not: 'a host form' }, {})))).toBe(false)+ expect(await sharedSwarm(sources(answers([], {}), ''))).toBe(false)})})@@ -774,7 +792,7 @@ describe('mentions on a post', () => {const swarm = (t: ReturnType<typeof setup>, leadId: string | null) => {const state = { agents: [t.agent], people, projects: [{ id: 'pilot', name: 'Pilot', leadConversationId: 'pilot' }],conversations: [{ id: 'pilot', leadId, agentIds: [t.agentId] }, { id: 'work', projectId: 'pilot', leadId: t.agentId, agentIds: [t.agentId] }] }- t.call.mockImplementation(async () => ({ status: 200, body: { success: true, data: { revision: 7, state } } }))+ t.call.mockImplementation(async (_method, path) => ({ status: 200, body: { success: true, data: swarmData(t.agent, path, state) } }))}const post = (t: ReturnType<typeof setup>, mentions: unknown) => t.ask({ action: 'command', tabId: 'tab', agentId: t.agentId, operationId: 'op',command: { type: 'message.send', conversationId: 'pilot', text: 'Please confirm', replyTo: null, recipientIds: [], mentions } }, owner)@@ -829,7 +847,7 @@ describe('mentions on a post', () => {expect(String((await help(t, { tabId: 'tab' })).post)).not.toContain('--mention')t.call.mockRejectedValue(new Error('Offline'))expect(String((await help(t, { tabId: 'tab', agentId: t.agentId })).post)).not.toContain('--mention')- t.call.mockResolvedValue({ status: 200, body: { success: true, data: { state: { agents: [] } } } })+ t.call.mockResolvedValue({ status: 200, body: { success: true, data: hostForm([], { tabs: ['tab'] }) } })expect(String((await help(t, { tabId: 'tab', agentId: t.agentId })).post)).not.toContain('--mention')})})diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.tsindex 0ee430fd2..1ff274730 100644--- a/cli/src/superTabs/service.ts+++ b/cli/src/superTabs/service.ts@@ -3,7 +3,9 @@ import { existsSync } from 'node:fs'import { readAuthSession } from '../lib/authSession.js'import { createHash } from 'node:crypto'import type { CoreApi, ServiceRequests, SuperTabsPort } from '../core/api.js'-import { backend, swarmRoleFor, hostJournalFile, identifier, object, SuperTabHost, SuperTabHostError, type SuperTabHostOptions } from './host.js'+import { backend, swarmRoleFor, hostJournalFile, identifier, object, SuperTabHost, SuperTabHostError, type SuperTabHostOptions, type SwarmSources } from './host.js'+import { HostFeed } from './hostFeed.js'+import { SwarmReads, type SwarmRead } from './swarmReads.js'import { within } from './wire.js'import { machineChoices } from '../lib/newCommand.js'import { START_REQUIREMENTS } from './capacity.js'@@ -35,7 +37,7 @@ const HELP = {model: 'opus', effort: 'high', routeDecisionId: 'DECISION' },command: 'command OPERATION_ID JSON: send one of the commands below. Reuse exactly the same ID and JSON after an interrupted request. On Custom skills, work.assign takes "roleId" too, a role of the agent\'s kind. When your assignment needs a person to decide, set work.status needs_human; when you cannot go on, blocked. Set working again once it moves. rule.set and rule.remove change one project\'s routing rules: only the project owner does (naming projectId), or that project\'s Lead passing on the project owner\'s request, with askedIn naming the project owner\'s message in that project\'s chat. project.skills switches a project between the Default, Harness orchestration and Custom skills (Custom once its owner has made the project\'s roles): only its project owner does, or its Lead passing on that owner\'s own chat message, with askedIn naming it. A start, assignment or route that breaks a hard rule (forbidModel, machines, minEffort) is refused for agents; preferEngine and preferIdle only rank.',commands: [- { type: 'project.report', projectId: 'PROJECT', throughRevision: 123, text: 'What changed, what is blocked, and what comes next. Use null when nothing merits repeating.' },+ { type: 'project.report', projectId: 'PROJECT', through: { GROUP: 214031 }, text: 'What changed, what is blocked, and what comes next. Use null when nothing merits repeating.' },{ type: 'project.repository', projectId: 'PROJECT', repositoryUrl: 'https://github.com/OWNER/REPOSITORY' },{ type: 'project.skills', projectId: 'PROJECT', mode: 'default|orchestration|custom', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },{ type: 'message.send', conversationId: 'GROUP', text: 'A message addressed to an agent', replyTo: null, recipientIds: ['AGENT'] },@@ -62,9 +64,14 @@ const HELP = {}const list = (value: unknown) => Array.isArray(value) ? value.map(object) : []+/** A Swarm read as `GET /api/super-tabs/:id` answered it, `lastChangedAt` in place of `revision` (design 2026-10-26 5.3). */+const answerOf = (read: SwarmRead) => ({ lastChangedAt: read.lastChangedAt, state: read.state, ...(read.githubApp ? { githubApp: true } : {}) })+const OFF_ROSTER = 'This agent is not on this machine\'s Swarm roster right now. That can mean this machine has no access to it, or its billing does not allow it. Check how this machine is shared.'/** Only a project's Lead may tag people (spec 2026-10-24-lead-mentions), so only a Lead's help offers it. */const LEAD_HELP = { ...HELP, post: `post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... [--mention PERSON]...: ${POST_HELP} --mention tags a person, by the id or email shown in status (up to 5), when you need them to act or decide; it shows in their notifications.` }const OTHER_WORK_FIELDS = ['conversationId', 'projectName', 'title', 'owns', 'status', 'agentName', 'pr'] as const+/** How old a host form a one-off question about this machine's Swarms may take: the host reads one every second. */+const POOLS_FRESH_MS = 5_000/** A project's Lead is its Lead conversation's, as the backend reads it; a Swarm from before projects has one, 'lead'. */function isLead(state: Record<string, unknown>, agentId: string): boolean {@@ -85,10 +92,11 @@ function statusView(answer: Record<string, unknown>, agentId: string): Record<st}/** A post's mentions name people by id or email; the backend takes person ids. A name that is nobody in the Swarm is refused- * here, before anything is sent. Whether this agent may tag them in this conversation is the backend's to judge. */-function mentionCommand(command: Record<string, unknown>, state: Record<string, unknown>): Record<string, unknown> {+ * here, before anything is sent. Whether this agent may tag them in this conversation is the backend's to judge. Only such+ * a post reads the Swarm, for its people. */+async function mentionCommand(command: Record<string, unknown>, swarm: () => Promise<Record<string, unknown>>): Promise<Record<string, unknown>> {if (command.type !== 'message.send' || !Array.isArray(command.mentions)) return command- const people = list(state.people)+ const people = list((await swarm()).people)const ids = command.mentions.map(name => {const person = people.find(p => p.id === name || typeof name === 'string' && typeof p.email === 'string' && p.email.toLowerCase() === name.toLowerCase())if (!person) throw new SuperTabHostError('MENTION_UNKNOWN', `${String(name)} is not a person in this Swarm. Tag a person by the id or email shown in status.`, 400)@@ -131,14 +139,12 @@ function markAnswered(page: unknown, later: unknown[], agentId: string): unknown/** Whether this machine is in a Swarm with other people in it: a contribution of its own to a tab whose people are more* than its owner. False when that cannot be read. */-export async function sharedSwarm(core: CoreApi): Promise<boolean> {- const machineId = core.daemon.machineId()- if (!identifier(machineId)) return false- const pools = await backend(core, 'GET', `/api/super-tabs/hosts/${machineId}/pools`).catch(() => [])- for (const row of Array.isArray(pools) ? pools.map(object) : []) {+export async function sharedSwarm(sources: SwarmSources): Promise<boolean> {+ if (!identifier(sources.feed.machineId)) return false+ const pools = await sources.feed.current(POOLS_FRESH_MS).then(read => read.pools, () => [])+ for (const row of pools) {if (!identifier(row.tabId)) continue- const tab = object(await backend(core, 'GET', `/api/super-tabs/${row.tabId}`).catch(() => ({})))- const people = object(tab.state).people+ const people = await sources.reads.read(row.tabId).then(read => read.state.people, () => null)if (Array.isArray(people) && people.length > 1) return true}return false@@ -162,6 +168,13 @@ export interface SuperTabServiceOptions {}export function superTabService(core: CoreApi, options: SuperTabServiceOptions = {}): { requests: ServiceRequests; port: SuperTabsPort } {const preparations = new ContributionPreparations(input => (options.prepareContribution ?? prepareContribution)(core, input))+ // One host form and one set of Swarm reads per machine, shared by the host and every action here (design 2026-10-26 5.3).+ let held: SwarmSources | null = null+ const sources = (): SwarmSources => {+ const machine = core.daemon.machineId()+ if (held?.feed.machineId !== machine) held = { feed: new HostFeed(core, machine), reads: new SwarmReads(core) }+ return held+ }let host: SuperTabHost | null = nulllet book: ReservationBook | null = null, bookMachine: string | null = nullconst reservations = () => {@@ -174,7 +187,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =const machine = core.daemon.machineId()if (host?.machineId !== machine) { host?.stop(); host = null }host ??= (options.host ?? ((api, id, given) => new SuperTabHost(api, id, given)))(core, machine,- { startReceipt: harnessId => reservations().creationOf(harnessId) })+ { startReceipt: harnessId => reservations().creationOf(harnessId), sources: sources() })host.start()return host}@@ -184,18 +197,18 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =const machine = core.daemon.machineId()if (cardsMachine !== machine) { swarmCards?.want(false); swarmCards = null; cardsMachine = machine }if (!swarmCards) {- swarmCards = (options.cards ?? ((api, id) => new SwarmCards(api, id)))(core, machine)+ swarmCards = (options.cards ?? ((api, id) => new SwarmCards(api, id, { reads: sources().reads })))(core, machine)swarmCards.onCards = items => core.superTabs?.cards(items)swarmCards.onRecap = recap => core.superTabs?.cardRecap(recap)}return swarmCards}// Sessions doing another person's project work keep a live GitHub App token while their task lasts, and none after.- const tokens = (options.githubTokens ?? (api => new GitHubTokenRefresher(api)))(core)+ const tokens = (options.githubTokens ?? (api => new GitHubTokenRefresher(api, sources)))(core)// In the Harness Team account only: whether its Claude Code and Codex are installed and signed in, for its owner to read.const engines = (options.teamEngines ?? teamEngineReporter)()let autoSetup: Promise<Pick<TeamAutoSetup, 'offer'>> | null = null- const disconnect = () => { preparations.clear(); host?.stop(); host = null; book?.stop(); book = null; bookMachine = null; swarmCards?.want(false); swarmCards = null; cardsMachine = null; tokens.stop(); engines.stop() }+ const disconnect = () => { preparations.clear(); host?.stop(); host = null; held = null; book?.stop(); book = null; bookMachine = null; swarmCards?.want(false); swarmCards = null; cardsMachine = null; tokens.stop(); engines.stop() }const port = {connected: () => {tokens.start()@@ -208,7 +221,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =},disconnected: disconnect,stop: disconnect,- swarmRole: async (harnessId: string) => (await within(swarmRoleFor(core, core.daemon.machineId(), harnessId).then(grant => ({ grant }))))?.grant,+ swarmRole: async (harnessId: string) => (await within(swarmRoleFor(sources(), harnessId).then(grant => ({ grant }))))?.grant,}const requests: ServiceRequests = {super_tabs: async (payload, asker, closed) => {@@ -231,7 +244,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =// which goes to this computer's own processes alone, never to another machine through the relay.if (payload.action === 'githubToken') {if (!asker.local) return { error: 'OWNER_REQUIRED' }- return await githubToken(core, String(payload.harnessId ?? ''))+ return await githubToken(core, String(payload.harnessId ?? ''), sources())}// Desktop on this Mac, as the person joins a Swarm, adds this Mac to one, or opens the app (team/autoSetup.ts): the// Harness Team account, behind macOS's own administrator prompt. Never through the relay, with nobody at this Mac.@@ -245,7 +258,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =}autoSetup ??= (options.teamSetup ?? (() => realTeamAutoSetup(core.dataDir, line => console.log(`[team] ${line}`))))().catch(error => { autoSetup = null; throw error })- return { ok: true, ...await (await autoSetup).offer(payload.reason as AutoSetupReason, () => sharedSwarm(core)) }+ return { ok: true, ...await (await autoSetup).offer(payload.reason as AutoSetupReason, () => sharedSwarm(sources())) }}if (payload.action === 'swarmRole') {const grant = await port.swarmRole(String(payload.harnessId ?? ''))@@ -281,53 +294,65 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =const value = await backend(core, method as string, path, payload.body)return { ok: true, value }}- let agentId = identifier(payload.agentId) ? payload.agentId- : identifier(payload.harnessId) ? createHash('sha256').update(JSON.stringify([core.daemon.machineId(), payload.harnessId])).digest('hex').slice(0, 24) : null- if (payload.action === 'help' && (!identifier(payload.tabId) || !agentId)) return { ok: true, help: HELP }- if (!identifier(payload.tabId) || !agentId) return { error: 'INVALID_REQUEST' }- if (!identifier(payload.agentId) && identifier(payload.harnessId)) {- const rows = await backend(core, 'GET', `/api/super-tabs/hosts/${core.daemon.machineId()}`)- const member = list(rows).find(row => row.tabId === payload.tabId && object(row.agent).machineId === core.daemon.machineId()- && object(row.agent).harnessId === payload.harnessId && row.stopRequested !== true)- if (identifier(object(member?.agent).id)) agentId = String(object(member?.agent).id)+ const named = identifier(payload.agentId) ? payload.agentId : null+ const hashed = identifier(payload.harnessId) ? createHash('sha256').update(JSON.stringify([core.daemon.machineId(), payload.harnessId])).digest('hex').slice(0, 24) : null+ if (payload.action === 'help' && (!identifier(payload.tabId) || !(named ?? hashed))) return { ok: true, help: HELP }+ if (!identifier(payload.tabId) || !(named ?? hashed)) return { error: 'INVALID_REQUEST' }+ // The caller is one of this machine's running agents, as the host roster lists it now: no Swarm is read to know that+ // (design 2026-10-26 5.3), and the roster is read again for every call, as the whole Swarm once was, by its changes+ // since the host's last read. A replacement terminal is still its original member, found by its harness.+ const { feed, reads } = sources()+ const callerIn = (roster: Record<string, unknown>[]) => {+ const rows = roster.filter(row => row.tabId === payload.tabId && row.closeSession !== true && object(row.agent).machineId === core.daemon.machineId())+ const member = rows.find(row => object(row.agent).harnessId === payload.harnessId && row.stopRequested !== true)+ const id = named ?? (identifier(object(member?.agent).id) ? object(member?.agent).id : hashed)+ return rows.find(row => object(row.agent).id === id)}- const path = `/api/super-tabs/${payload.tabId}`- const identity = `asAgentId=${agentId}`- const answer = object(await backend(core, 'GET', `${path}?${identity}`))- const state = object(answer.state)- const agent = Array.isArray(state.agents) ? state.agents.map(object).find(a => a.id === agentId) : undefined- if (!agent || agent.machineId !== core.daemon.machineId() || typeof agent.harnessId !== 'string'- || identifier(payload.harnessId) && agent.harnessId !== payload.harnessId || !core.agents.byAgent(agent.harnessId)) {+ const caller = callerIn((await feed.refresh()).roster)+ const agent = object(caller?.agent)+ if (payload.action === 'help' && (!caller || !identifier(agent.id))) return { ok: true, help: HELP }+ // The server leaves an agent off the roster when this machine has no access or billing for it; it gives no reason,+ // and the server enforces the grant anyway, so the text says where to look (Lead's ruling, #1726 G5).+ if (!caller || !identifier(agent.id)) return { error: 'AGENT_UNAVAILABLE', detail: OFF_ROSTER }+ if (typeof agent.harnessId !== 'string' || identifier(payload.harnessId) && agent.harnessId !== payload.harnessId || !core.agents.byAgent(agent.harnessId)) {return payload.action === 'help' ? { ok: true, help: HELP } : { error: 'AGENT_UNAVAILABLE', detail: 'This agent is not a running contribution on this machine.' }}- if (payload.action === 'help') return { ok: true, help: isLead(state, agentId) ? LEAD_HELP : HELP }+ const agentId = agent.id+ const path = `/api/super-tabs/${payload.tabId}`+ const identity = `asAgentId=${agentId}`+ const swarm = () => reads.read(String(payload.tabId), agentId)+ if (payload.action === 'help') return { ok: true, help: caller.lead === true ? LEAD_HELP : HELP }wake()if (payload.action === 'startStatus' && identifier(payload.startId)) {return { ok: true, value: await backend(core, 'GET', `${path}/starts/${payload.startId}?${identity}`) }}- if (payload.action === 'status') return { ok: true, value: statusView(answer, agentId) }+ if (payload.action === 'status') return { ok: true, value: statusView(answerOf(await swarm()), agentId) }// A Lead's terminal read or typing (`screen`, `type`): the backend answers only the agent that asked.if (payload.action === 'terminalResult') {if (!identifier(payload.terminalRequestId)) return { error: 'INVALID_REQUEST' }return { ok: true, value: await backend(core, 'GET', `${path}/terminal/${payload.terminalRequestId}?${identity}`) }}if (payload.action === 'routeContext') {- const [policy, machines] = await Promise.all([+ const [read, policy, machines] = await Promise.all([+ swarm(),backend(core, 'GET', `${path}/routing-policy?${identity}`),core.account.machines().catch(() => null),])// A list that could not be read is not an empty one: the Lead's route says so.const readable = machines?.status === 200// Machines shared with the account but not yet added refuse it, so they are not offered.- return { ok: true, value: { tab: answer, policy, agentId,+ return { ok: true, value: { tab: answerOf(read), policy, agentId,machines: readable ? machineChoices(object(object(machines.body).data), null).filter(m => !m.toAdd).map(m => ({ machineId: m.machineId, name: m.label, status: m.status })) : [],...(readable ? {} : { machinesUnreadable: true }) } }}// The route log and the group's attempts, for the quota open picks hold and what members did before. Apart from// `routeContext` so the Lead reads it while it probes the machines; the group's Lead only, like the route itself.if (payload.action === 'routeHistory') {- const group = list(state.conversations).find(c => c.id === payload.conversationId)- if (!group || group.leadId !== agentId) return { error: 'LEAD_REQUIRED', detail: 'The coordinating Lead of this group owns routing.', status: 403 }+ // The one group by id, active or dormant (design 4.5): a group that left the active set still has its history, and+ // a group this agent cannot read answers 404, refused like one it does not lead (review round 1).+ const group = identifier(payload.conversationId) ? object(object(await backend(core, 'GET', `${path}/groups/${payload.conversationId}?${identity}`)+ .catch(error => { if (error instanceof SuperTabHostError && [403, 404].includes(error.status)) return null; throw error })).group).data : null+ if (!group || object(group).leadId !== agentId) return { error: 'LEAD_REQUIRED', detail: 'The coordinating Lead of this group owns routing.', status: 403 }const [logged, tried] = await Promise.all([within(backend(core, 'GET', `${path}/route-decisions?${identity}`)),// An older backend has no such route: its 404 is unreadable like any other failure.@@ -364,7 +389,7 @@ export function superTabService(core: CoreApi, options: SuperTabServiceOptions =} catch { return { ok: true, value: page } }}if (payload.action === 'command' && identifier(payload.operationId) && payload.command && typeof payload.command === 'object' && !Array.isArray(payload.command)) {- const command = mentionCommand(taskCommand(object(payload.command)), state)+ const command = await mentionCommand(taskCommand(object(payload.command)), async () => (await swarm()).state)const send = (command: Record<string, unknown>) => backend(core, 'POST', `${path}/commands`,{ operationId: payload.operationId, command, asAgentId: agentId })let value: unknowndiff --git a/cli/src/superTabs/serviceReads.spec.ts b/cli/src/superTabs/serviceReads.spec.tsnew file mode 100644index 000000000..95b4f64ba--- /dev/null+++ b/cli/src/superTabs/serviceReads.spec.ts@@ -0,0 +1,154 @@+import { describe, expect, it, vi } from 'vitest'+import type { CoreApi } from '../core/api.js'+import { fakeCore } from '../testing/fakeCore.js'+import { FIXTURE, ok, readFixture, type BackendReply } from './fixtures/read/index.js'+import type { SuperTabHost } from './host.js'+import { superTabService } from './service.js'++type Json = Record<string, unknown>+const T = FIXTURE.tabId, M = FIXTURE.machineId+const owner = { local: true, owner: true }++/** The fixture Swarm on its own machine: the host form lists the Lead and the Builder, each reads its own view by parts. */+function swarm(extra: (method: string, path: string, body?: unknown) => BackendReply | undefined = () => undefined) {+ const call = vi.fn<CoreApi['account']['backend']>(async (method, path, body) => {+ const answer = extra(method, path, body)+ if (answer) return answer+ if (path.startsWith(`/api/super-tabs/hosts/${M}/changes`)) return ok(readFixture('host-full'))+ if (path === `/api/super-tabs/${T}/parts?asAgentId=${FIXTURE.leadId}`) return ok(readFixture('parts-lead'))+ if (path === `/api/super-tabs/${T}/parts?asAgentId=${FIXTURE.builderId}`) return ok(readFixture('parts-builder'))+ if (path.startsWith(`/api/super-tabs/${T}/changes?`)) return ok(readFixture('changes-reload'))+ return ok({ messages: [], next: null })+ })+ const core = fakeCore({ account: { backend: call }, daemon: { machineId: () => M } as never,+ agents: { byAgent: vi.fn((id: string) => ([FIXTURE.leadHarness, FIXTURE.builderHarness] as string[]).includes(id) ? { agentId: id } as never : undefined) } })+ const service = superTabService(core, { host: () => ({ machineId: M, start: vi.fn(), stop: vi.fn() }) as unknown as SuperTabHost })+ const reads = () => call.mock.calls.map(c => c[1]).filter(path => /\/parts|\/changes\?cursor|\/super-tabs\/[A-Za-z0-9]+\?/.test(path) && !path.includes('/hosts/'))+ return { call, core, ask: service.requests.super_tabs, reads }+}+/** What the status action printed before #1726, recorded from that code with the same Swarm; `revision` is gone now. */+const golden = (who: 'lead' | 'builder') => {+ const { value, ...rest } = readFixture<{ value: Json }>(`status-${who}`)+ const { revision: _revision, ...kept } = value+ return { ...rest, value: { ...kept, lastChangedAt: 1793010101002 } }+}++describe('status from parts', () => {+ it('prints for a Lead what it printed before, with lastChangedAt in place of revision', async () => {+ expect(await swarm().ask({ action: 'status', tabId: T, agentId: FIXTURE.leadId }, owner)).toEqual(golden('lead'))+ })+ it('prints for a Builder what it printed before, with lastChangedAt in place of revision', async () => {+ expect(await swarm().ask({ action: 'status', tabId: T, agentId: FIXTURE.builderId }, owner)).toEqual(golden('builder'))+ })+ it('finds the caller by its harness, as the roster lists it on this machine', async () => {+ const s = swarm()+ expect(await s.ask({ action: 'status', tabId: T, harnessId: FIXTURE.builderHarness }, owner)).toEqual(golden('builder'))+ })+})++describe('what each action reads of the Swarm', () => {+ it.each([+ ['messages', { conversationId: FIXTURE.workGroup }],+ ['message', { conversationId: FIXTURE.workGroup, messageId: 'f00000000000000000000001' }],+ ['terminalResult', { terminalRequestId: 'r1' }],+ ['startStatus', { startId: FIXTURE.startId }],+ ['attachment', { conversationId: FIXTURE.workGroup, step: 'sent', operationId: 'op-1' }],+ ['command', { operationId: 'op-2', command: { type: 'message.send', conversationId: FIXTURE.workGroup, text: 'Hi', replyTo: null, recipientIds: [] } }],+ ['help', {}],+ ])('reads nothing of it for %s', async (action, payload) => {+ const s = swarm()+ const answer = await s.ask({ action, tabId: T, agentId: FIXTURE.builderId, ...payload }, owner)+ expect(answer).not.toHaveProperty('error')+ expect(s.reads()).toEqual([])+ })+ it('reads the people only for a post that tags someone', async () => {+ const s = swarm()+ await s.ask({ action: 'command', tabId: T, agentId: FIXTURE.leadId, operationId: 'op-3',+ command: { type: 'message.send', conversationId: FIXTURE.leadGroup, text: 'Please decide', replyTo: null, recipientIds: [], mentions: ['[email protected]'] } }, owner)+ expect(s.reads()).toEqual([`/api/super-tabs/${T}/parts?asAgentId=${FIXTURE.leadId}`])+ expect(s.call).toHaveBeenCalledWith('POST', `/api/super-tabs/${T}/commands`, expect.objectContaining({+ command: expect.objectContaining({ mentions: [FIXTURE.collaboratorId] }) }))+ })+ it('offers a Lead its own help by the roster, without reading the Swarm', async () => {+ const s = swarm()+ const lead = await s.ask({ action: 'help', tabId: T, agentId: FIXTURE.leadId }, owner)+ const builder = await s.ask({ action: 'help', tabId: T, agentId: FIXTURE.builderId }, owner)+ expect(String(object(lead.help).post)).toContain('--mention')+ expect(String(object(builder.help).post)).not.toContain('--mention')+ expect(s.reads()).toEqual([])+ })+ it('reads the roster as it is now for every call, so an agent started a moment ago is known at once', async () => {+ let started = false+ const s = swarm((_method, path) => path.startsWith(`/api/super-tabs/hosts/${M}/changes`) && !started+ ? ok({ ...readFixture<Json>('host-full'), tabs: [] }) : undefined)+ expect(await s.ask({ action: 'messages', tabId: T, agentId: FIXTURE.builderId, conversationId: FIXTURE.workGroup }, owner)).toMatchObject({ error: 'AGENT_UNAVAILABLE' })+ started = true+ expect(await s.ask({ action: 'messages', tabId: T, agentId: FIXTURE.builderId, conversationId: FIXTURE.workGroup }, owner)).toMatchObject({ ok: true })+ expect(s.call.mock.calls.map(c => c[1]).filter(path => path.includes('/hosts/')))+ .toEqual([`/api/super-tabs/hosts/${M}/changes?full=1`, `/api/super-tabs/hosts/${M}/changes?cursor=eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjowfQ`])+ })+ // The server leaves an agent off the roster when this machine has no access or billing for it: the error says where to look.+ it('refuses a caller the roster does not list here, or whose session is not running, saying which', async () => {+ const s = swarm()+ expect(await s.ask({ action: 'messages', tabId: T, agentId: 'a0000000000000000000000z', conversationId: FIXTURE.workGroup }, owner))+ .toEqual({ error: 'AGENT_UNAVAILABLE', detail: 'This agent is not on this machine\'s Swarm roster right now. That can mean this machine has no access to it, or its billing does not allow it. Check how this machine is shared.' })+ vi.mocked(s.core.agents.byAgent).mockReturnValue(undefined)+ expect(await s.ask({ action: 'messages', tabId: T, agentId: FIXTURE.builderId, conversationId: FIXTURE.workGroup }, owner))+ .toEqual({ error: 'AGENT_UNAVAILABLE', detail: 'This agent is not a running contribution on this machine.' })+ })+ it('tells the person to update Harness when the server needs a newer one', async () => {+ const s = swarm((_method, path) => path.includes('/parts') ? { status: 426, body: { success: false, error: { code: 'UPDATE_REQUIRED' } } } : undefined)+ expect(await s.ask({ action: 'status', tabId: T, agentId: FIXTURE.leadId }, owner))+ .toEqual({ error: 'UPDATE_REQUIRED', detail: 'Update Harness to keep using this Swarm.', status: 426 })+ })+})++const object = (v: unknown): Json => v && typeof v === 'object' && !Array.isArray(v) ? v as Json : {}++// Design 3.6: groups number their messages apart, so a Lead's report names how far it read in each group, not one revision.+describe('the project report a Lead is shown how to send', () => {+ it('names how far it read in each group, never one revision of the Swarm', async () => {+ const { help } = await swarm().ask({ action: 'help' }, owner) as { help: { commands: Json[] } }+ const report = help.commands.find(c => c.type === 'project.report')+ expect(report).toEqual({ type: 'project.report', projectId: 'PROJECT', through: { GROUP: 214031 },+ text: 'What changed, what is blocked, and what comes next. Use null when nothing merits repeating.' })+ expect(JSON.stringify(help)).not.toContain('throughRevision')+ })+})++// Review round 1: a group that left the active set (archived, or finished and idle) is not in the cached parts, yet its own+// Lead still reads its route history. The group is read by id, as the backend serves an active or a dormant one.+describe('route history of a group outside the active set', () => {+ const DORMANT = 'c0000000000000000000000d'+ const history = (leadId: string | null) => swarm((_method, path) => {+ if (path.startsWith(`/api/super-tabs/${T}/groups/${DORMANT}?`)) return leadId === null+ ? { status: 404, body: { success: false, error: { code: 'NOT_FOUND', message: 'No such group.' } } }+ : ok({ group: { key: DORMANT, version: 214200, changedAt: 1, data: { id: DORMANT, leadId, agentIds: [leadId], archived: true, dormant: true } } })+ if (path.includes('/route-decisions') || path.includes('/attempts')) return ok([])+ return undefined+ })+ const ask = (s: ReturnType<typeof swarm>, agentId: string) => s.ask({ action: 'routeHistory', tabId: T, agentId, conversationId: DORMANT }, owner)+ const logReads = (s: ReturnType<typeof swarm>) => s.call.mock.calls.filter(c => c[1].includes('/route-decisions')).length++ it('gives a dormant group\'s own Lead its history', async () => {+ const s = history(FIXTURE.leadId)+ expect(await ask(s, FIXTURE.leadId)).toEqual({ ok: true, value: { decisions: [], attempts: [] } })+ expect(s.call).toHaveBeenCalledWith('GET', `/api/super-tabs/${T}/groups/${DORMANT}?asAgentId=${FIXTURE.leadId}`, undefined)+ })+ it('refuses a caller that does not lead it, and a group the caller cannot read, before reading any history', async () => {+ const other = history(FIXTURE.leadId)+ expect(await ask(other, FIXTURE.builderId)).toMatchObject({ error: 'LEAD_REQUIRED', status: 403 })+ expect(logReads(other)).toBe(0)+ const unreadable = history(null)+ expect(await ask(unreadable, FIXTURE.leadId)).toMatchObject({ error: 'LEAD_REQUIRED', status: 403 })+ expect(logReads(unreadable)).toBe(0)+ })+})++describe('route history when the group cannot be read for another reason', () => {+ it('says so, rather than calling the caller no Lead', async () => {+ const s = swarm((_method, path) => path.includes('/groups/') ? { status: 503, body: { success: false, error: { code: 'SWARM_BUSY', message: 'Busy' } } } : undefined)+ expect(await s.ask({ action: 'routeHistory', tabId: T, agentId: FIXTURE.leadId, conversationId: FIXTURE.workGroup }, owner))+ .toEqual({ error: 'SWARM_BUSY', detail: 'Busy', status: 503 })+ })+})diff --git a/cli/src/superTabs/start.spec.ts b/cli/src/superTabs/start.spec.tsindex f733c4c78..18759553f 100644--- a/cli/src/superTabs/start.spec.ts+++ b/cli/src/superTabs/start.spec.ts@@ -324,7 +324,8 @@ it('closes a refused start only after the machine durably fences its creation reconst input = { action: 'resume', tabId: 'tab', startId: 'start' }expect(await startAgent(input, f.scoped, where, f.open)).toMatchObject({ error: 'START_FAILED', detail: 'This agent does not support that permission mode.' })expect(f.request.mock.calls.map(c => c[0]).filter(type => type.startsWith('agent_create'))).toEqual(['agent_create_status', 'agent_create', 'agent_create_cancel'])- expect(f.start.error).toContain('before starting an agent')+ // The Lead is told the machine's own reason, so it can start the work elsewhere.+ expect(f.start.error).toBe('This agent does not support that permission mode.')expect(await startAgent(input, f.scoped, where, f.open)).toMatchObject({ error: 'START_FAILED' })expect(f.open).toHaveBeenCalledOnce()expect(f.scoped.mock.calls.some(c => (c[0].command as any)?.type === 'agent.started')).toBe(false)@@ -340,14 +341,16 @@ it('recovers a lost cancellation reply without dispatching another start', asyncexpect(f.close).toHaveBeenCalledTimes(2)})-it('retries the exact shared failure command after a lost acknowledgement', async () => {+it('fails the start after a lost acknowledgement of its refusal, with only the fenced receipt left to say why', async () => {const f = fixture({ refuse: 'INVALID_PERMISSION_MODE', loseFailure: true })const input = { action: 'resume', tabId: 'tab', startId: 'start' }await expect(startAgent(input, f.scoped, where, f.open)).rejects.toThrow('Failure receipt interrupted')expect(await startAgent(input, f.scoped, where, f.open)).toMatchObject({ error: 'START_FAILED' })const failures = f.scoped.mock.calls.map(c => c[0]).filter(p => (p.command as any)?.type === 'agent.startFailed')- expect(failures).toHaveLength(2)- expect(failures[0]).toEqual(failures[1])+ // Each under its own operation: the refusal is known only to the invocation that saw it.+ expect(failures.map(p => [p.operationId, (p.command as any).error])).toEqual([+ ['refused-start', 'This agent does not support that permission mode.'],+ ['failed-start', 'The machine cancelled this request before starting an agent. Review its settings and create a new start request.']])expect(f.request.mock.calls.filter(c => c[0] === 'agent_create')).toHaveLength(1)})diff --git a/cli/src/superTabs/start.ts b/cli/src/superTabs/start.tsindex a6647daf9..c0dff330d 100644--- a/cli/src/superTabs/start.ts+++ b/cli/src/superTabs/start.ts@@ -227,10 +227,12 @@ export async function startAgent(input: Json, scoped: ScopedRequest, where: Wherif (native.state === 'failed' || native.state === 'cancelled') {await target.request('super_tabs', { action: 'observeCapacity', creationId }, 10_000).catch(() => {})const failure = object(native.failure)- // The shared command stays byte-identical if its reply is lost and the- // next invocation sees only the durable cancellation tombstone.const detail = native.state === 'cancelled' ? CANCELLED_START : String(failure.detail ?? failure.code ?? 'Native creation failed.')- requireSuccess(await scoped({ action: 'command', operationId: `failed-${startId}`, command: { type: 'agent.startFailed', startId, error: detail } }))+ // The machine's own refusal tells the Lead where else the work can run. Only the invocation that saw it knows it,+ // so it goes under its own operation; one that finds only the durable cancellation tombstone sends the generic+ // text under the other, byte-identical on every retry. Whichever the backend records first fails the start.+ const command = refusal ? { operationId: `refused-${startId}`, error: refusal } : { operationId: `failed-${startId}`, error: detail }+ requireSuccess(await scoped({ action: 'command', operationId: command.operationId, command: { type: 'agent.startFailed', startId, error: command.error } }))return { error: 'START_FAILED', startId, detail: refusal ?? detail }}const frame = object(native.agent)diff --git a/cli/src/superTabs/swarmReads.spec.ts b/cli/src/superTabs/swarmReads.spec.tsnew file mode 100644index 000000000..ae30d03bf--- /dev/null+++ b/cli/src/superTabs/swarmReads.spec.ts@@ -0,0 +1,104 @@+import { describe, expect, it, vi } from 'vitest'+import type { CoreApi } from '../core/api.js'+import { fakeCore } from '../testing/fakeCore.js'+import { FIXTURE, ok, readFixture, refused, type BackendReply } from './fixtures/read/index.js'+import { SuperTabHostError } from './host.js'+import { UPDATE_MESSAGE } from './readContract.js'+import { SwarmReads } from './swarmReads.js'++type Json = Record<string, unknown>+const T = FIXTURE.tabId, LEAD = FIXTURE.leadId+const FIRST = `/api/super-tabs/${T}/parts?asAgentId=${LEAD}`+const CHANGES = (cursor = 'eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjozfQ') => `/api/super-tabs/${T}/changes?cursor=${cursor}&asAgentId=${LEAD}`++/** A backend that answers each path from a queue of replies, in order; the last reply of a path repeats. */+function backendOf(routes: Record<string, BackendReply[]>) {+ const call = vi.fn<CoreApi['account']['backend']>(async (_method, path) => {+ const queue = routes[path]+ if (!queue?.length) return refused(500, 'UNEXPECTED', path)+ return queue.length > 1 ? queue.shift()! : queue[0]+ })+ return { call, reads: new SwarmReads(fakeCore({ account: { backend: call } })) }+}+const paths = (call: ReturnType<typeof backendOf>['call']) => call.mock.calls.map(c => c[1])+const conversations = (state: Json) => (state.conversations as Json[]).map(c => c.id)++describe('the daemon\'s Swarm reads', () => {+ it('first loads a Swarm once as the agent, then reads only what changed', async () => {+ const { call, reads } = backendOf({ [FIRST]: [ok(readFixture('parts-lead'))], [CHANGES()]: [ok(readFixture('changes-lead'))] })+ const first = await reads.read(T, LEAD)+ expect(first).toEqual({ state: readFixture<{ state: Json }>('legacy-tab-lead').state, lastChangedAt: 1793010101002, githubApp: true })+ const next = await reads.read(T, LEAD)+ expect(conversations(next.state)).toEqual([FIXTURE.leadGroup, FIXTURE.leadsGroup, FIXTURE.workGroup])+ expect(next.lastChangedAt).toBe(1793010106120)+ expect(paths(call)).toEqual([FIRST, CHANGES()])+ })++ it('loads again in full when the server asks it to, or no longer knows the Swarm or the agent', async () => {+ for (const answer of [ok(readFixture('changes-reload')), refused(404, 'NOT_FOUND'), refused(403, 'FORBIDDEN')]) {+ const { call, reads } = backendOf({ [FIRST]: [ok(readFixture('parts-lead'))], [CHANGES()]: [answer] })+ await reads.read(T, LEAD)+ expect((await reads.read(T, LEAD)).state).toEqual(readFixture<{ state: Json }>('legacy-tab-lead').state)+ expect(paths(call)).toEqual([FIRST, CHANGES(), FIRST])+ }+ })++ it('fails as today when the first load is refused, and starts from a first load after that', async () => {+ const { call, reads } = backendOf({ [FIRST]: [refused(403, 'FORBIDDEN', 'No access'), ok(readFixture('parts-lead'))] })+ await expect(reads.read(T, LEAD)).rejects.toMatchObject({ code: 'FORBIDDEN', status: 403 })+ await reads.read(T, LEAD)+ expect(paths(call)).toEqual([FIRST, FIRST])+ })++ it('keeps nothing of a Swarm whose access was taken away, so a later read never resumes from it', async () => {+ const { call, reads } = backendOf({ [FIRST]: [ok(readFixture('parts-lead')), refused(403, 'FORBIDDEN'), ok(readFixture('parts-lead'))],+ [CHANGES()]: [refused(403, 'FORBIDDEN')] })+ await reads.read(T, LEAD)+ await expect(reads.read(T, LEAD)).rejects.toMatchObject({ status: 403 })+ await reads.read(T, LEAD)+ expect(paths(call)).toEqual([FIRST, CHANGES(), FIRST, FIRST])+ })++ it('keeps what it holds when a changes read fails for another reason, and asks from the same cursor next time', async () => {+ const { call, reads } = backendOf({ [FIRST]: [ok(readFixture('parts-lead'))],+ [CHANGES()]: [refused(503, 'SWARM_BUSY', 'Busy'), ok(readFixture('changes-lead'))] })+ await reads.read(T, LEAD)+ await expect(reads.read(T, LEAD)).rejects.toMatchObject({ code: 'SWARM_BUSY' })+ expect(conversations((await reads.read(T, LEAD)).state)).toHaveLength(3)+ expect(paths(call)).toEqual([FIRST, CHANGES(), CHANGES()])+ })++ it('tells the person to update Harness for HTTP 426 and for a format it cannot read', async () => {+ const old = backendOf({ [FIRST]: [{ status: 426, body: { success: false, error: { code: 'UPDATE_REQUIRED' } } }] })+ await expect(old.reads.read(T, LEAD)).rejects.toEqual(new SuperTabHostError('UPDATE_REQUIRED', UPDATE_MESSAGE, 426))+ const newer = backendOf({ [FIRST]: [ok({ ...readFixture<Json>('parts-lead'), format: 3 })] })+ await expect(newer.reads.read(T, LEAD)).rejects.toEqual(new SuperTabHostError('UPDATE_REQUIRED', UPDATE_MESSAGE, 426))+ const changed = backendOf({ [FIRST]: [ok(readFixture('parts-lead'))], [CHANGES()]: [ok({ ...readFixture<Json>('changes-lead'), format: 3 })] })+ await changed.reads.read(T, LEAD)+ await expect(changed.reads.read(T, LEAD)).rejects.toMatchObject({ code: 'UPDATE_REQUIRED', status: 426 })+ })++ it('reads as the person without an agent, and keeps each reader\'s view apart', async () => {+ const person = `/api/super-tabs/${T}/parts`+ const { call, reads } = backendOf({ [person]: [ok(readFixture('parts-builder'))], [FIRST]: [ok(readFixture('parts-lead'))] })+ expect(conversations((await reads.read(T)).state)).not.toContain(FIXTURE.leadsGroup)+ expect(conversations((await reads.read(T, LEAD)).state)).toContain(FIXTURE.leadsGroup)+ expect(paths(call)).toEqual([person, FIRST])+ })++ it('runs one read of a Swarm at a time, each from what the last one left', async () => {+ const { call, reads } = backendOf({ [FIRST]: [ok(readFixture('parts-lead'))], [CHANGES()]: [ok(readFixture('changes-lead'))],+ [CHANGES('eyJ2IjoyLCJ0IjoxNzkzMDEwMDc3Mzc1LCJlIjozfQ')]: [ok(readFixture('changes-lead'))] })+ await Promise.all([reads.read(T, LEAD), reads.read(T, LEAD), reads.read(T, LEAD)])+ expect(paths(call)).toEqual([FIRST, CHANGES(), CHANGES('eyJ2IjoyLCJ0IjoxNzkzMDEwMDc3Mzc1LCJlIjozfQ')])+ })++ it('holds a bounded number of Swarms, dropping the one read longest ago', async () => {+ const call = vi.fn<CoreApi['account']['backend']>(async (_method, path) => path.includes('/changes')+ ? ok(readFixture('changes-lead')) : ok(readFixture('parts-lead')))+ const reads = new SwarmReads(fakeCore({ account: { backend: call } }), { maxSwarms: 2 })+ for (const agent of ['a1', 'a2', 'a1', 'a3', 'a1', 'a2']) await reads.read(T, agent)+ expect(paths(call).map(p => `${p.includes('/changes') ? 'changes' : 'first'} ${p.slice(-2)}`))+ .toEqual(['first a1', 'first a2', 'changes a1', 'first a3', 'changes a1', 'first a2'])+ })+})diff --git a/cli/src/superTabs/swarmReads.ts b/cli/src/superTabs/swarmReads.tsnew file mode 100644index 000000000..d6229960d--- /dev/null+++ b/cli/src/superTabs/swarmReads.ts@@ -0,0 +1,65 @@+/**+ * The daemon's Swarm reads (design 2026-10-26-swarm-state-parts section 5.3): each Swarm, as each reader sees it (a person,+ * or an agent through `asAgentId`), is first loaded once and then read by what changed since. The daemon is long-lived, so a+ * one-shot `harness super-tab` call costs one changes read, not the whole Swarm it once downloaded every time.+ */+import type { CoreApi } from '../core/api.js'+import { mergeChanges, storeOf, type PartsStore } from './partsStore.js'+import type { ChangedParts, FirstLoad } from './readContract.js'+import { reassemble } from './reassemble.js'+import { backend, object, readable, SuperTabHostError } from './wire.js'++type Json = Record<string, unknown>+/** A Swarm as `GET /api/super-tabs/:id` gave it: its state in the old shape, `lastChangedAt` in place of `revision`. */+export interface SwarmRead { state: Json; lastChangedAt: number | null; githubApp: boolean }++/** One per running agent and Swarm on a machine, plus up to 16 the Pro cards read as the person; one of the largest Swarms+ * holds about a megabyte. */+const MAX_SWARMS = 48++export class SwarmReads {+ private readonly held = new Map<string, PartsStore>()+ /** Each reader's last read, so reads of one Swarm run one after another, each from where the last left the cursor. */+ private readonly queue = new Map<string, Promise<unknown>>()+ private readonly maxSwarms: number+ private readonly backend: typeof backend++ constructor(private readonly core: CoreApi, options: { maxSwarms?: number; backend?: typeof backend } = {}) {+ this.maxSwarms = options.maxSwarms ?? MAX_SWARMS+ this.backend = options.backend ?? backend+ }++ read(tabId: string, asAgentId?: string): Promise<SwarmRead> {+ const key = `${tabId}:${asAgentId ?? ''}`+ const run = (this.queue.get(key) ?? Promise.resolve()).catch(() => undefined).then(() => this.refresh(key, tabId, asAgentId))+ this.queue.set(key, run)+ void run.catch(() => undefined).finally(() => { if (this.queue.get(key) === run) this.queue.delete(key) })+ return run+ }++ private async refresh(key: string, tabId: string, asAgentId: string | undefined): Promise<SwarmRead> {+ const as = asAgentId ? `asAgentId=${asAgentId}` : ''+ const held = this.held.get(key)+ let store: PartsStore | null = null+ if (held) {+ try {+ const changes = object(await this.backend(this.core, 'GET', `/api/super-tabs/${tabId}/changes?cursor=${held.cursor}${as ? `&${as}` : ''}`))+ // The epoch moved (who sees what changed) or the cursor outlived the tombstones: only a first load is right now. The+ // answer is `{ reload: true }` alone (design 4.2), so it is read before the format of a reply with parts.+ if (changes.reload !== true) store = mergeChanges(held, readable<ChangedParts>(changes))+ } catch (error) {+ // The Swarm or this reader's access is gone or changed: what is held may show what it can no longer see.+ if (!(error instanceof SuperTabHostError) || ![403, 404].includes(error.status)) throw error+ }+ }+ // Dropped before the first load: a refused one leaves nothing that a later read could resume from.+ this.held.delete(key)+ store ??= storeOf(readable<FirstLoad>(await this.backend(this.core, 'GET', `/api/super-tabs/${tabId}/parts${as ? `?${as}` : ''}`)))+ this.held.set(key, store)+ for (const oldest of this.held.keys()) {+ if (this.held.size <= this.maxSwarms) break+ this.held.delete(oldest)+ }+ return { state: reassemble(store), lastChangedAt: store.lastChangedAt, githubApp: store.githubApp }+ }+}diff --git a/cli/src/superTabs/terminal.spec.ts b/cli/src/superTabs/terminal.spec.tsindex e838bb858..b3d0458d0 100644--- a/cli/src/superTabs/terminal.spec.ts+++ b/cli/src/superTabs/terminal.spec.ts@@ -1,3 +1,4 @@+import { readFileSync } from 'node:fs'import { describe, expect, it, vi } from 'vitest'import type { CoreApi, SuperTabScreen } from '../core/api.js'import { fakeCore } from '../testing/fakeCore.js'@@ -30,6 +31,8 @@ function setup(options: { live?: string[]; screen?: (harnessId: string) => Superpolls: () => vi.mocked(backend).mock.calls.filter(([, path]) => path === '/api/super-tabs/hosts/m1/terminal').length,alerts: () => sent.filter(s => s.body.command.type === 'agent.alert').map(s => s.body.command) }}+/** A screen as the engine draws it (fixtures/screens). */+const fixture = (name: string) => readFileSync(new URL(`./fixtures/screens/${name}.txt`, import.meta.url), 'utf8')const screenRequest = (over: Record<string, unknown> = {}) => ({ tabId: 'tab', agentId: 'a1', harnessId: 'h1', request: { id: 'r1', kind: 'screen' }, ...over })describe('a host serving its Lead\'s terminal requests', () => {@@ -208,6 +211,13 @@ describe('the stuck and usage-limit alerts', () => {expect(t.alerts()).toEqual([{ type: 'agent.alert', agentId: 'a1', alert: 'model', active: true }])})+ it.each(['claude-session-limit', 'claude-weekly-limit', 'claude-opus-limit', 'claude-fable-limit', 'codex-usage-limit', 'codex-model-limit'])(+ 'alerts for the %s screen', async name => {+ const t = setup({ screen: () => ({ ok: true, text: fixture(name), hold: null }) })+ await t.host.tick([row()])+ expect(t.alerts()).toEqual([expect.objectContaining({ type: 'agent.alert', agentId: 'a1', alert: 'limit', active: true })])+ })+it('tries an alert the backend did not take again on the next read', async () => {const t = setup({ screen: () => ({ ok: true, text: 'Claude usage limit reached. Your limit will reset at 3pm.', hold: null }) })const real = vi.mocked(t.backend).getMockImplementation()!@@ -222,6 +232,48 @@ describe('the stuck and usage-limit alerts', () => {})})+describe('progress for the machine report', () => {+ const showing = (text: string) => (): SuperTabScreen => ({ ok: true, text, hold: null })++ it('records when each running agent\'s screen last changed, from the reads the watch already makes', async () => {+ const t = setup({ screen: showing('✻ Reading files…\n❯ ') })+ await t.host.tick([row()])+ expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_000_000 })+ t.wait(15_000); await t.host.tick([row()])+ expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_000_000 })+ t.showing(showing('✻ Editing host.ts…\n❯ ')); t.wait(15_000); await t.host.tick([row()])+ expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_030_000 })+ expect(t.core.superTabs!.screen).toHaveBeenCalledTimes(3)+ })++ it('names only running agents, and forgets one once it stops or leaves', async () => {+ const t = setup({ live: ['h1', 'h2'] })+ await t.host.tick([row(), row('a2', 'h2', { stopRequested: true }), row('a3', 'h3')])+ expect(t.host.progressOf(['h1', 'h2', 'h3'])).toEqual({ h1: 1_000_000 })+ t.wait(15_000); await t.host.tick([row('a2', 'h2')])+ expect(t.host.progressOf(['h1', 'h2'])).toEqual({ h2: 1_015_000 })+ await t.host.tick([])+ expect(t.host.progressOf(['h1', 'h2'])).toEqual({})+ })++ it.each(['claude', 'codex'])('does not count %s redrawing only its spinner, elapsed time, token counter or tip, and counts new work', async engine => {+ const t = setup({ screen: showing(fixture(`${engine}-working-a`)) })+ await t.host.tick([row()])+ t.showing(showing(fixture(`${engine}-working-b`))); t.wait(15_000); await t.host.tick([row()])+ expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_000_000 })+ t.showing(showing(fixture(`${engine}-working-b`).replace('\n\n', '\n\nEdited cli/src/superTabs/terminal.ts\n\n'))); t.wait(15_000); await t.host.tick([row()])+ expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_030_000 })+ })++ it('does not count a screen that only shows its model retrying, nor one that could not be read', async () => {+ const t = setup({ screen: showing('✻ Waiting for API response · will retry in 2m 38s · check your network\n❯ ') })+ await t.host.tick([row()])+ t.showing(showing('✻ Waiting for API response · will retry in 2m 23s · check your network\n❯ ')); t.wait(15_000); await t.host.tick([row()])+ t.showing(() => ({ ok: false, error: 'pane gone' })); t.wait(15_000); await t.host.tick([row()])+ expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_000_000 })+ })+})+describe('reading a usage limit off a screen', () => {const now = new Date(2026, 9, 23, 14, 10).getTime()it.each([@@ -238,11 +290,26 @@ describe('reading a usage limit off a screen', () => {])('reads %s', (line, reset) => {expect(limitOf(`some work\n${line}\n> `, now)).toEqual({ resetAt: reset.toISOString() })})+ // Whole screens as Claude Code 2.1.310 and Codex 0.154 draw them, their limit lines in the engines' own words+ // (fixtures/screens): Claude Code names the limit hit, and Codex wraps its long line and dates a reset after today.+ it.each([+ ['claude-session-limit', { resetAt: new Date(2026, 9, 23, 15, 0).toISOString() }],+ ['claude-weekly-limit', { resetAt: new Date(2026, 9, 30, 9, 0).toISOString() }],+ ['claude-opus-limit', { resetAt: new Date(2026, 9, 30, 9, 0).toISOString() }],+ ['claude-fable-limit', {}],+ ['codex-usage-limit', { resetAt: new Date(2026, 9, 27, 15, 5).toISOString() }],+ ['codex-model-limit', { resetAt: new Date(2026, 9, 23, 16, 5).toISOString() }],+ ])('reads the %s screen', (name, limit) => {+ expect(limitOf(fixture(name), now)).toEqual(limit)+ })it('knows a limit without a reset time, and ignores the words in an agent\'s own prose or far above the prompt', () => {expect(limitOf('⎿ API Error: Usage limit reached\n> ', now)).toEqual({})expect(limitOf('I will add a check for when the usage limit reached message shows.\n> ', now)).toBeNull()expect(limitOf(`5-hour limit reached ∙ resets 3pm\n${'line\n'.repeat(30)}> `, now)).toBeNull()expect(limitOf('> ', now)).toBeNull()+ // A full context is not a usage limit; a workspace out of credits is one.+ expect(limitOf(' ⎿ Context limit reached · /compact or /clear to continue\n> ', now)).toBeNull()+ expect(limitOf('■ You\'ve reached your workspace credit limit\n› ', now)).toEqual({})})})diff --git a/cli/src/superTabs/terminal.ts b/cli/src/superTabs/terminal.tsindex d7dd807fd..34e268c05 100644--- a/cli/src/superTabs/terminal.ts+++ b/cli/src/superTabs/terminal.ts@@ -4,8 +4,10 @@* only a person at that machine could see and clear it. The backend relays the Lead's request to the host of the agent's* machine; the host reads or types with the core's own capture and input (core/superTabTerminal.ts) and answers as that* agent. It also tells the Lead, once per episode, when a worker has sat on a prompt for 3 minutes or its screen shows- * a usage limit.+ * a usage limit. The same reads tell the machine report when each agent's screen last changed: the backend renews the+ * agent's lease on its task from that (docs: swarm-never-stops, v1 liveness).*/+import { createHash } from 'node:crypto'import type { CoreApi } from '../core/api.js'import type { MessageHold } from '../engines/facets/screen.js'import { backend } from './host.js'@@ -55,9 +57,12 @@ export function typedKeys(keys: unknown[]): string[] | string {/** The engines' own limit lines, at the start of a line: Claude Code's "5-hour limit reached ∙ resets 3pm", "Claude usage* limit reached. Your limit will reset at 3pm", "You've hit your limit · resets 3pm" and "API Error: Usage limit- * reached", and Codex's "You've hit your usage limit. … try again in 2 hours". Only near the prompt, so an agent writing- * about limits in its own words, or an old banner far up the screen, is not one. */-const LIMIT_LINE = /^[^A-Za-z]*(?:api error:\s*)?(?:claude\s+)?(?:(?:usage|5-hour|weekly|session|opus|sonnet)\s+limit reached|you['’]ve hit your (?:usage )?limit|you['’]ve reached your usage limit)/i+ * reached", and Codex's "You've hit your usage limit. … try again in 2 hours". Claude Code 2.1 names the limit it hit+ * ("You've hit your session limit", "… weekly limit", "… Opus limit", "You've reached your Fable limit"), and Codex 0.154+ * one for a model or a workspace ("You've hit your usage limit for gpt-5.5-codex", "You've reached your workspace credit+ * limit"): none of those alerted until 2026-10-26. Only near the prompt, so an agent writing about limits in its own+ * words, or an old banner far up the screen, is not one. */+const LIMIT_LINE = /^[^A-Za-z]*(?:api error:\s*)?(?:claude\s+)?(?:(?:usage|5-hour|weekly|session|opus|sonnet|fable)\s+limit reached|you['’]ve (?:hit|reached) your (?:[\w-]+ ){0,2}limit)/iconst LIMIT_NEAR_LINES = 15const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec']@@ -98,20 +103,33 @@ function resetOf(said: string, now: number): number | null {}if (ms) return now + ms}- // The engines say a local time ("3pm", "4:05 PM"), with a date when it is not today ("Oct 25, 9am").- const time = /(?:resets?(?: at)?|try again at)\s+(?:([a-z]{3})[a-z]*\s+(\d{1,2}),?\s+(?:at\s+)?)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?/i.exec(said)+ // The engines say a local time ("3pm", "4:05 PM"), with a date when it is not today ("Oct 25, 9am"; Codex's+ // "Oct 27th, 2026 3:05 PM").+ const time = /(?:resets?(?: at)?|try again at)\s+(?:([a-z]{3})[a-z]*\s+(\d{1,2})(?:st|nd|rd|th)?,?\s+(?:(\d{4})\s+)?(?:at\s+)?)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?/i.exec(said)if (!time) return null- const [, month, day, hour, minute, half] = time+ const [, month, day, year, hour, minute, half] = time// "3pm" and "12am" are 12-hour; "15:00" and "0:30", with no am or pm, are 24-hour.const h = half ? Number(hour) % 12 + (half.toLowerCase() === 'pm' ? 12 : 0) : Number(hour)const date = new Date(now)- if (month && MONTHS.includes(month.toLowerCase())) date.setMonth(MONTHS.indexOf(month.toLowerCase()), Number(day))+ if (month && MONTHS.includes(month.toLowerCase())) date.setFullYear(year ? Number(year) : date.getFullYear(), MONTHS.indexOf(month.toLowerCase()), Number(day))date.setHours(h, Number(minute ?? 0), 0, 0)- // A time already past today is tomorrow's; a date already past is next year's.- if (date.getTime() <= now) month ? date.setFullYear(date.getFullYear() + 1) : date.setDate(date.getDate() + 1)+ // A time already past today is tomorrow's; a date already past is next year's, unless the engine named the year.+ if (date.getTime() <= now && !year) month ? date.setFullYear(date.getFullYear() + 1) : date.setDate(date.getDate() + 1)return date.getTime()}+/** What Claude Code and Codex redraw every second while they work, whether or not the work moves: the spinner line with+ * its elapsed time and token counter ("✻ Pondering… (2m 14s · ↓ 3.1k tokens · esc to interrupt)", "• Working (1m 05s •+ * esc to interrupt)"), Claude Code's rotating tip under it, and a retry's countdown. A stuck agent's screen changes all+ * the time through them (Lead, 2026-10-26), so they are left out of what counts as progress. */+const STATUS_LINE = /esc to (?:interrupt|cancel)|^\W*[A-Za-z][\w ]*…\s*\(|^\s*⎿\s+tip:|will retry in/i++/** A short digest of the screen without its status lines: two screens with the same one show the same work. */+function screenDigest(text: string): string {+ const lines = text.split('\n').filter(line => !STATUS_LINE.test(line)).map(line => line.trimEnd())+ return createHash('sha256').update(lines.join('\n')).digest('base64url')+}+type Episode = { since: number; alerted: boolean } | nullinterface Watched { prompt: Episode; limit: Episode; model: Episode; retried?: number }@@ -121,6 +139,8 @@ export class TerminalHost {private serving: Promise<void> | null = nullprivate watching: Promise<void> | null = nullprivate readonly watched = new Map<string, Watched>()+ /** Per running harness here, its last screen's digest and when that last changed. */+ private readonly progress = new Map<string, { digest: string; at: number }>()private readonly now: () => numberprivate readonly log: (message: string) => void@@ -133,7 +153,7 @@ export class TerminalHost {* the host never waits on it, so a slow screen read never delays deliveries. */tick(rows: unknown[]): Promise<void> {const here = this.here(rows)- if (!here.length) { this.watched.clear(); return Promise.resolve() }+ if (!here.length) { this.watched.clear(); this.progress.clear(); return Promise.resolve() }const own = here.filter(agent => agent.running)const now = this.now()if (!this.serving && now >= this.nextServeAt) {@@ -147,6 +167,15 @@ export class TerminalHost {return Promise.all([this.serving, this.watching]).then(() => {})}+ /** When each of these harnesses' screens last changed, epoch ms, for those running here that the watch has read. An+ * agent's first read counts as a change: the host cannot know what its screen showed before. */+ progressOf(harnessIds: readonly string[]): Record<string, number> {+ return Object.fromEntries(harnessIds.flatMap(id => {+ const seen = this.progress.get(id)+ return seen ? [[id, seen.at]] : []+ }))+ }+/** This machine's Swarm agents, as the roster names them, and whether each runs here: a stopping one, or one whose* session is gone, is no longer anyone's to drive, but its requests are still this host's to answer. */private here(rows: unknown[]): Array<Own & { running: boolean }> {@@ -203,6 +232,8 @@ export class TerminalHost {private async watch(own: Own[]): Promise<void> {const keys = new Set(own.map(a => `${a.tabId}:${a.agentId}`))for (const key of this.watched.keys()) if (!keys.has(key)) this.watched.delete(key)+ const harnesses = new Set(own.map(a => a.harnessId))+ for (const id of this.progress.keys()) if (!harnesses.has(id)) this.progress.delete(id)for (const agent of own) {const key = `${agent.tabId}:${agent.agentId}`const state = this.watched.get(key) ?? { prompt: null, limit: null, model: null }@@ -211,6 +242,9 @@ export class TerminalHost {const read = await this.core.superTabs!.screen(agent.harnessId, 0).catch(() => null)if (!read?.ok) continueconst now = this.now()+ const digest = screenDigest(read.text), seen = this.progress.get(agent.harnessId)+ // A model being retried is not the agent's work moving, whatever else the screen shows meanwhile.+ if (!seen || (seen.digest !== digest && !modelFailing(read.text))) this.progress.set(agent.harnessId, { digest, at: now })state.prompt = await this.episode(agent, 'prompt', state.prompt, read.hold !== null && WAITING.has(read.hold), now, since => now - since >= PROMPT_WAIT_MS, {})const limit = limitOf(read.text, now)state.limit = await this.episode(agent, 'limit', state.limit, limit !== null, now, () => true, limit ?? {})diff --git a/cli/src/superTabs/wire.ts b/cli/src/superTabs/wire.tsindex 0975ae915..520d33769 100644--- a/cli/src/superTabs/wire.ts+++ b/cli/src/superTabs/wire.ts@@ -1,3 +1,6 @@+import type { CoreApi } from '../core/api.js'+import { READ_FORMAT, UPDATE_MESSAGE, UPDATE_REQUIRED } from './readContract.js'+type Json = Record<string, unknown>export const object = (v: unknown): Json => v && typeof v === 'object' && !Array.isArray(v) ? v as Json : {}export const identifier = (v: unknown): v is string => typeof v === 'string' && /^[A-Za-z0-9_-]{1,160}$/.test(v)@@ -6,5 +9,29 @@ export async function within<T>(read: Promise<T>, ms = 3000): Promise<T | null>let timer: NodeJS.Timeout | undefinedtry { return await Promise.race([read, new Promise<null>(resolve => { timer = setTimeout(resolve, ms, null) })]) } catch { return null } finally { clearTimeout(timer) }}-/** Assignment statuses (and route outcomes) that mean the work is over; the backend's `activeWork` lists the same ones. */-export const ENDED_WORK = ['done', 'stopped', 'cancelled']+/** Assignment statuses (and route outcomes) that mean the work is over; the backend's `activeWork` lists the same ones.+ * `lost`: its agent died, stalled or hit a limit, and the Lead hands it on (the backend's v1 liveness). */+export const ENDED_WORK = ['done', 'stopped', 'cancelled', 'lost']++export class SuperTabHostError extends Error {+ constructor(readonly code: string, message: string, readonly status = 503) { super(message) }+}++/** The core signs each request. Neither the service nor its journal holds an account credential. HTTP 426 is a server that no+ * longer serves this client's reads: whatever it says, the person is told to update Harness (design 4.11, 5.1). */+export async function backend(core: CoreApi, method: string, path: string, body?: unknown): Promise<unknown> {+ const reply = await core.account.backend(method, path, body)+ if (reply.status === 426) throw new SuperTabHostError(UPDATE_REQUIRED, UPDATE_MESSAGE, 426)+ if (reply.status < 200 || reply.status >= 300 || reply.body.success === false) {+ const error = object(reply.body.error)+ throw new SuperTabHostError(String(error.code ?? reply.body.code ?? 'BACKEND_UNAVAILABLE'),+ String(error.message ?? reply.body.message ?? 'Could not reach this Super Tab.'), reply.status)+ }+ return reply.body.data+}++/** A read reply in a format this client cannot read comes from a newer server: the person updates Harness (design 5.1). */+export function readable<T>(reply: unknown): T {+ if (object(reply).format !== READ_FORMAT) throw new SuperTabHostError(UPDATE_REQUIRED, UPDATE_MESSAGE, 426)+ return reply as T+}diff --git a/desktop/lib/settings/sections/tab_invites_section.dart b/desktop/lib/settings/sections/tab_invites_section.dartindex cd2f941d3..474740869 100644--- a/desktop/lib/settings/sections/tab_invites_section.dart+++ b/desktop/lib/settings/sections/tab_invites_section.dart@@ -53,7 +53,7 @@ class _TabInvitesSectionState extends State<TabInvitesSection> {final client = widget.notifier.superTabs;final answers = await Future.wait([client.request('GET', '/api/super-tabs/invitations'),- client.request('GET', '/api/super-tabs'),+ client.request('GET', '/api/super-tabs/list'),]);if (!mounted || read != _read) return;setState(() {diff --git a/desktop/lib/super_tabs/agent_details.dart b/desktop/lib/super_tabs/agent_details.dartindex 44dc9dadf..e4e9b0bcc 100644--- a/desktop/lib/super_tabs/agent_details.dart+++ b/desktop/lib/super_tabs/agent_details.dart@@ -40,7 +40,7 @@ class SuperTabAgentInfo {controller.snapshot?.conversations.where((g) =>- !g.archived &&+ !g.closed &&g.assignment?['agentId'] == agent.id &&!const {'done',diff --git a/desktop/lib/super_tabs/agent_group_picker.dart b/desktop/lib/super_tabs/agent_group_picker.dartindex a7efd6cc1..da19292f9 100644--- a/desktop/lib/super_tabs/agent_group_picker.dart+++ b/desktop/lib/super_tabs/agent_group_picker.dart@@ -38,7 +38,7 @@ class _SuperTabAgentGroupPickerState extends State<SuperTabAgentGroupPicker> {return const [];}return snapshot!.conversations- .where((g) => !g.archived && g.agentIds.contains(widget.agentId))+ .where((g) => !g.closed && g.agentIds.contains(widget.agentId)).toList();}diff --git a/desktop/lib/super_tabs/client.dart b/desktop/lib/super_tabs/client.dartindex 08fa4a34a..6464abf45 100644--- a/desktop/lib/super_tabs/client.dart+++ b/desktop/lib/super_tabs/client.dart@@ -9,6 +9,7 @@ import 'attachment_upload.dart';import 'controller.dart';import 'model.dart';import 'notifications.dart';+import 'parts.dart';import 'reading.dart';import 'saved_view.dart';@@ -334,7 +335,7 @@ class SuperTabClient {do {final page = await map('GET',- '/api/super-tabs${after == null ? '' : '?after=${Uri.encodeComponent(after)}'}',+ '/api/super-tabs/list${after == null ? '' : '?after=${Uri.encodeComponent(after)}'}',);if (generation != _generation) return;if (page['tabs'] is! List) {@@ -400,6 +401,15 @@ class SuperTabClient {Map<String, dynamic>? body,}) async => superTabMap(await request(method, path, body: body));+ /// The Swarm as it is now, read once with a first load: for a check outside+ /// an open tab (a launch revalidating its destination).+ Future<SuperTabSnapshot> readSnapshot(String id) async {+ final parts = SuperTabParts.firstLoad(+ await map('GET', '/api/super-tabs/${Uri.encodeComponent(id)}/parts'),+ );+ return SuperTabSnapshot.fromJson(parts.state);+ }+Future<SuperTabController> open(String id) =>_controllers.putIfAbsent(id, () {final generation = _generation;@@ -437,7 +447,7 @@ class SuperTabClient {upload: upload,reading: _reading,)..away = _isAway(id);- var seenRevision = -1;+ var seenChange = (lastChangedAt: -1, mentionsWaiting: -1);var seenSelected = controller.selectedId;controller.addListener(() {if (_reading.drawsSaved && generation == _generation) {@@ -454,9 +464,15 @@ class SuperTabClient {seenSelected = controller.selectedId;onSelection?.call(controller);}- if (controller.snapshot != null && controller.revision != seenRevision) {- seenRevision = controller.revision;- onSnapshot?.call(controller);+ if (controller.snapshot case final snapshot?) {+ final change = (+ lastChangedAt: controller.lastChangedAt,+ mentionsWaiting: snapshot.mentionsWaiting,+ );+ if (change != seenChange) {+ seenChange = change;+ onSnapshot?.call(controller);+ }}});// What discovery already announced is not news when the Swarm opens.diff --git a/desktop/lib/super_tabs/controller.dart b/desktop/lib/super_tabs/controller.dartindex bd68d5333..824dc64b9 100644--- a/desktop/lib/super_tabs/controller.dart+++ b/desktop/lib/super_tabs/controller.dart@@ -2,14 +2,15 @@ import 'dart:async';import 'dart:math';import 'package:clock/clock.dart';-import 'package:collection/collection.dart' show DeepCollectionEquality;import 'package:dio/dio.dart' show CancelToken, DioException, DioExceptionType;import 'package:flutter/foundation.dart';import '../logging/app_log.dart';import '../state/harness_attachments.dart';import 'attachment_upload.dart';+import 'identity.dart';import 'model.dart';+import 'parts.dart';import 'reading.dart';import 'review_verdict.dart';@@ -123,7 +124,20 @@ class SuperTabController extends ChangeNotifier {final Duration uploadTimeout;SuperTabSnapshot? snapshot;String selectedId = 'lead';- int revision = -1;++ /// The newest change of the Swarm this tab has read, in epoch milliseconds: what tells the app and the tag list+ /// that it changed (spec ruling 8).+ int lastChangedAt = -1;++ /// The backend no longer serves this build's reads (HTTP 426): the tab says+ /// to update Harness and asks nothing more (section 5.1).+ bool updateRequired = false;++ /// What the tab says once [updateRequired] (docs/naming-system.md).+ static const updateMessage = 'Update Harness to keep using this Swarm.';++ /// The Swarm's parts as last read: what the next read asks changes for, and what [snapshot] is built from.+ SuperTabParts? _parts;String? error, operationError, operationErrorCode;/// One line for the sender after a command succeeds, from the backend: that a@@ -146,8 +160,8 @@ class SuperTabController extends ChangeNotifier {SuperTabReading _policy;DateTime? _startedAt, _lastFullRead;- /// The state last drawn, while the reading adapts ([_read]).- Map<String, dynamic>? _shownState;+ /// When the parts held were last read: how old a [savedView] of them is.+ DateTime? _partsReadAt;/// The rows each conversation's messages were read from, kept only to save/// the view ([SuperTabReading.drawsSaved]).@@ -196,7 +210,8 @@ class SuperTabController extends ChangeNotifier {/// The latest read of the Swarm's state failed (and the tab is still ours). While it is, what the/// machines last reported cannot be told from what they report now: a machine is neither online nor/// offline, and the Swarm says its backend is unreachable instead of calling machines offline.- bool get backendUnreachable => _refreshFailing && !accessRevoked;+ bool get backendUnreachable =>+ _refreshFailing && !accessRevoked && !updateRequired;bool _refreshFailing = false;/// Since when the reads have been failing, while [backendUnreachable]: the first failure of this run of them.@@ -220,7 +235,11 @@ class SuperTabController extends ChangeNotifier {({String conversationId, List<HarnessAttachment> files})? _sending;int _uploadRun = 0;final _messages = <String, List<SuperTabMessage>>{};- final _before = <String, int?>{};++ /// Where each conversation's older history continues: the oldest message+ /// read, as the backend's page cursor names it (section 4.6). Null at the+ /// start of the conversation.+ final _before = <String, SuperTabPage?>{};final _reading = <String, Future<void>>{};final expandedProjects = <String>{};final expandedMachines = <String>{};@@ -248,7 +267,10 @@ class SuperTabController extends ChangeNotifier {bool offlineMachinesOpen = false;void toggleProject(String id) {- if (!expandedProjects.remove(id)) expandedProjects.add(id);+ if (!expandedProjects.remove(id)) {+ expandedProjects.add(id);+ unawaited(loadDormant(id));+ }_saveSoon();_changed();}@@ -410,7 +432,7 @@ class SuperTabController extends ChangeNotifier {/// [after] is what is left of the poll once a read took the rest of it.void _schedule([Duration? after]) {_poll?.cancel();- if (_disposed || pollInterval <= Duration.zero) return;+ if (_disposed || updateRequired || pollInterval <= Duration.zero) return;if (!_policy.adapts) {_poll = Timer.periodic(pollInterval, (_) => unawaited(refresh()));return;@@ -453,11 +475,13 @@ class SuperTabController extends ChangeNotifier {}/// The view to keep on this device ([SuperTabReading.drawsSaved]): the- /// state as last read and the open conversation's last page, or null.+ /// Swarm's parts as last read, with the cursor the next read starts at,+ /// and the open conversation's last page; or null.Map<String, dynamic>? get savedView {- final state = _shownState;+ final parts = _parts, readAt = _partsReadAt;if (!_policy.drawsSaved ||- state == null ||+ parts == null ||+ readAt == null ||accessRevoked ||_showingSaved) {return null;@@ -469,25 +493,40 @@ class SuperTabController extends ChangeNotifier {: shown;final rows = [for (final message in page) ?_rows[id]?[message.id]];return {- 'revision': revision,- 'state': state,+ 'format': superTabReadFormat,+ 'savedAt': readAt.millisecondsSinceEpoch,+ 'lastChangedAt': lastChangedAt,+ 'parts': parts.toJson(),'conversationId': id,'messages': rows,- 'next': page.length < shown.length ? page.first.sequence : _before[id],+ 'next': page.length < shown.length+ ? SuperTabPage.of(page.first).toJson()+ : _before[id]?.toJson(),};}/// A conversation's page as the backend reads it.static const _savedPage = 100;+ /// How long a saved view's cursor is good for: the backend keeps+ /// tombstones 7 days and reloads older cursors an hour before that.+ static const _savedFor = Duration(days: 6, hours: 23);+/// Draws a [savedView] kept from an earlier visit while the first read is- /// on its way: that read replaces it. One for another Swarm, one that no- /// longer parses, or one after a read has landed, draws nothing.+ /// on its way, and holds its parts: the first read asks only for what+ /// changed since, and replaces it. One for another Swarm, one too old for+ /// its cursor, one that no longer parses, or one after a read has landed,+ /// draws nothing.void drawSaved(Map<String, dynamic> view) {if (!_policy.drawsSaved || snapshot != null || stateReads > 0) return;try {- final state = superTabMap(view['state']);- final saved = SuperTabSnapshot.fromJson(state);+ if (view['format'] != superTabReadFormat) return;+ final savedAt = DateTime.fromMillisecondsSinceEpoch(+ (view['savedAt'] as num).toInt(),+ );+ if (clock.now().difference(savedAt) >= _savedFor) return;+ final parts = SuperTabParts.fromJson(superTabMap(view['parts']));+ final saved = SuperTabSnapshot.fromJson(parts.state);if (saved.id != tabId) return;final id = view['conversationId'];final rows = [@@ -495,17 +534,17 @@ class SuperTabController extends ChangeNotifier {superTabMap(row),];final messages = rows.map(SuperTabMessage.fromJson).toList();- final revisionSaved = (view['revision'] as num).toInt();+ final changedAt = (view['lastChangedAt'] as num).toInt();snapshot = saved;- revision = revisionSaved;- _shownState = state;+ lastChangedAt = changedAt;+ _parts = parts;+ _partsReadAt = savedAt;if (id == selectedId &&saved.conversation(id as String) != null &&messages.every((m) => m.conversationId == id)) {- _messages[id] = messages- ..sort((a, b) => a.sequence.compareTo(b.sequence));+ _messages[id] = messages..sort(superTabMessageOrder);_keepRows(id, rows);- _before[id] = (view['next'] as num?)?.toInt();+ _before[id] = SuperTabPage.read(view['next']);}_showingSaved = true;loading = false;@@ -520,8 +559,9 @@ class SuperTabController extends ChangeNotifier {/// A view from an older shape: draw nothing, read as usual.void _dropSaved() {snapshot = null;- revision = -1;- _shownState = null;+ lastChangedAt = -1;+ _parts = null;+ _partsReadAt = null;_messages.clear();_rows.clear();_before.clear();@@ -551,6 +591,7 @@ class SuperTabController extends ChangeNotifier {devicesSelected = false;error = message;snapshot = null;+ _parts = null;_messages.clear();_poll?.cancel();_changed();@@ -622,17 +663,82 @@ class SuperTabController extends ChangeNotifier {Map<String, String> mentions(String conversationId) =>Map.unmodifiable(_mentions[conversationId] ?? const {});- void select(String id) {- if (snapshot?.conversation(id) == null ||- (id == selectedId && !devicesSelected)) {- return;+ /// Makes conversation [id] part of [snapshot]: one not held (a closed+ /// group a link or Work details names) is read by id. False when it cannot+ /// be read.+ Future<bool> loadGroup(String id) async {+ if (snapshot == null) return false;+ if (snapshot!.conversation(id) != null) return true;+ final parts = _parts;+ try {+ if (parts == null || !await _readGroup(parts, id)) return false;+ } catch (failure) {+ _readFailure(failure, revokeTab: false);+ _changed();+ return false;+ }+ _redraw();+ return !_disposed && snapshot?.conversation(id) != null;+ }++ /// The signed-in person's private chat with [projectId]'s Product Manager:+ /// that project's private conversation whose audience is them alone.+ SuperTabConversation? pmChat(String projectId) => snapshot?.conversations+ .where(+ (g) =>+ g.projectId == projectId &&+ g.audience?.length == 1 &&+ g.audience!.single == accountId,+ )+ .firstOrNull;++ /// Opens [pmChat], creating it on first use: chat only, for this person+ /// alone, named after them, with the project's Lead in it. The create is one+ /// fixed request per person, membership and project, so a second click or+ /// another window gets the same conversation back from the server's receipt,+ /// while a person who left and rejoined, whom the old chat no longer admits,+ /// gets a new one.+ Future<bool> openPmChat(String projectId) async {+ if (pmChat(projectId) case final chat?) return select(chat.id);+ final me = snapshot?.people.where((p) => p.id == accountId).firstOrNull;+ final email = me?.email;+ final result = await command({+ 'type': 'conversation.create',+ 'projectId': projectId,+ 'title': email == null || email.isEmpty+ ? 'Chat with PM'+ : superTabPersonName(email),+ 'brief': '',+ 'checks': <dynamic>[],+ 'audience': {+ 'personIds': [accountId],+ },+ }, operationId: _pmChatOperation(projectId, me?.generation));+ final id = result?['conversationId'];+ return id is String && await select(id);+ }++ String _pmChatOperation(String projectId, String? generation) {+ final id = 'pm-chat-$projectId-$accountId-${generation ?? ''}';+ // The backend's operation ids are at most 160 characters.+ return id.length > 160 ? id.substring(0, 160) : id;+ }++ /// Opens conversation [id], reading it first when it is not held+ /// ([loadGroup]); false when it cannot be read.+ Future<bool> select(String id) async {+ // A held group is selected at once, before this returns.+ if (snapshot?.conversation(id) == null && !await loadGroup(id)) {+ return false;}+ if (id == selectedId && !devicesSelected) return true;devicesSelected = false;_acted();if (!snapshot!.isProjectLead(id)) {final group = snapshot!.conversation(id)!;expandedProjects.add(group.projectId);- if (group.archived) closedOpenProjects.add(group.projectId);+ unawaited(loadDormant(group.projectId));+ if (group.closed) closedOpenProjects.add(group.projectId);}selectedId = id;_viewVersion++;@@ -640,6 +746,7 @@ class SuperTabController extends ChangeNotifier {_saveSoon();_changed();unawaited(loadMessages(id));+ return true;}/// A visible transcript passes the boundary it displayed. The loaded messages@@ -657,7 +764,7 @@ class SuperTabController extends ChangeNotifier {}Future<void> refresh() {- if (_disposed || accessRevoked) return Future.value();+ if (_disposed || accessRevoked || updateRequired) return Future.value();return _refreshing ??= _read().whenComplete(() => _refreshing = null);}@@ -686,36 +793,47 @@ class SuperTabController extends ChangeNotifier {..ignore()): null;try {- final answer = await request('GET', _path);+ final read = await _readParts();if (_disposed || accessRevoked) return;+ final parts = _parts!;_refreshFailing = false;unreachableSince = null;_waitingForMachine = false;_graceEnd?.cancel();stateReads++;- final nextRevision = (answer['revision'] as num).toInt();// How long the Swarm took to answer, and nothing it said: the log shows a slow or failing// backend, which the sidebar's ages and the machines' states otherwise only hint at.appLog.debug('swarm',- 'state read in ${took.elapsedMilliseconds} ms (revision $nextRevision)',+ 'state read in ${took.elapsedMilliseconds} ms '+ '(${read.full ? 'first load' : 'changes'}, last changed ${parts.lastChangedAt})',);- final raw = superTabMap(answer['state']);- // Some of the state is worked out at read time (an agent seen down, a- // limit that ran out) and changes with no new revision.- if (_policy.adapts) {- stateChanged = !const DeepCollectionEquality().equals(raw, _shownState);- _shownState = raw;- if (stateChanged) _viewVersion++;- }- final next = SuperTabSnapshot.fromJson(raw);- if (next.id != tabId) {- throw const FormatException('A different Swarm was returned.');- }- // The first read over a saved view wins, whatever revision was saved.- if (nextRevision >= revision || _showingSaved) {+ // A part or a value worked out at read time (an agent seen down, a+ // limit that ran out) changed: the snapshot is built again. The first+ // read over a saved view wins, whatever it saved.+ final moved = read.changed || _showingSaved;+ if (moved) {+ // A closed group named by the saved selection is read by id: a first+ // load has only the active groups.+ if (read.full && !parts.holdsGroup(selectedId)) {+ await _readGroup(parts, selectedId);+ if (_disposed || accessRevoked) return;+ }+ final raw = parts.state;+ if (_policy.adapts) {+ stateChanged = true;+ _viewVersion++;+ }+ final next = SuperTabSnapshot.fromJson(raw);+ if (next.id != tabId) {+ throw const FormatException('A different Swarm was returned.');+ }snapshot = next;final allowed = next.conversations.map((c) => c.id).toSet();+ // What this device keeps of a group goes with the group itself (a+ // tombstone), not when a read leaves it out: a closed group is out of+ // every first load and still has its drafts and read marks.+ final removed = read.removed;final localAccessChanged =!allowed.contains(selectedId) ||[@@ -723,32 +841,43 @@ class SuperTabController extends ChangeNotifier {..._terminals.keys,..._mentions.keys,..._readAt.keys,- ].any((id) => !allowed.contains(id)) ||+ ].any(removed.contains) ||expandedProjects.any((id) => !next.projects.any((project) => project.id == id),);_messages.removeWhere((id, _) => !allowed.contains(id));_rows.removeWhere((id, _) => !allowed.contains(id));- _drafts.removeWhere((id, _) => !allowed.contains(id));+ _drafts.removeWhere((id, _) => removed.contains(id));_attachments.removeWhere((id, files) {if (allowed.contains(id)) return false;files.dispose();return true;});- _terminals.removeWhere((id, _) => !allowed.contains(id));- _mentions.removeWhere((id, _) => !allowed.contains(id));+ _terminals.removeWhere((id, _) => removed.contains(id));+ _mentions.removeWhere((id, _) => removed.contains(id));_before.removeWhere((id, _) => !allowed.contains(id));- _readAt.removeWhere((id, _) => !allowed.contains(id));+ _readAt.removeWhere((id, _) => removed.contains(id));expandedProjects.removeWhere((id) => !next.projects.any((project) => project.id == id),);if (!allowed.contains(selectedId)) {selectedId = next.projects.firstOrNull?.leadConversationId ?? 'lead';}- revision = nextRevision;- error = null;if (localAccessChanged) _saveSoon();+ // A new store holds no closed groups yet, nor one a saved view drew:+ // the open projects read theirs.+ if (read.full || stateReads == 1) {+ // A read for the parts before has nothing to give these.+ _dormantPages.clear();+ _dormantReads.clear();+ for (final project in expandedProjects) {+ unawaited(loadDormant(project));+ }+ }}+ lastChangedAt = parts.lastChangedAt;+ _partsReadAt = clock.now();+ error = null;await (selectedId == earlyId && messagesRead != null? messagesRead: _readMessages(@@ -786,10 +915,163 @@ class SuperTabController extends ChangeNotifier {}}+ /// One read of the Swarm's parts: changes since the cursor once a first load+ /// is held, else a first load. A reload answer, or a change read refused (the+ /// Swarm or the reader's access moved), reads in full at once.+ Future<({bool full, bool changed, Set<String> removed})> _readParts() async {+ final held = _parts;+ if (held != null) {+ try {+ final answer = await request(+ 'GET',+ '$_path/changes?cursor=${Uri.encodeQueryComponent(held.cursor)}',+ );+ if (answer['reload'] != true) {+ final SuperTabPartsChange change;+ try {+ change = held.apply(answer);+ } catch (_) {+ // Half merged: the next read starts again from a first load.+ if (identical(_parts, held)) _parts = null;+ rethrow;+ }+ final refreshed = await _refreshStale(held);+ return (+ full: false,+ changed: change.changed || refreshed,+ removed: change.removedGroups,+ );+ }+ } on SuperTabFailure catch (failure) {+ if (!const {'FORBIDDEN', 'NOT_FOUND'}.contains(failure.code)) rethrow;+ }+ _parts = null;+ }+ final parts = SuperTabParts.firstLoad(await request('GET', '$_path/parts'));+ if (parts.state['id'] != tabId) {+ throw const FormatException('A different Swarm was returned.');+ }+ _parts = parts;+ return (full: true, changed: true, removed: const <String>{});+ }++ /// A stub says a held group closed, not how: its data is read again by id.+ /// Best effort, after the change read is merged: a failed read leaves the+ /// group as it was and is tried at the next read; only an update answer+ /// stops the tab. True when a group's data was read.+ Future<bool> _refreshStale(SuperTabParts parts) async {+ var read = false;+ for (final id in parts.staleGroups) {+ try {+ if (await _readGroup(parts, id)) {+ read = true;+ } else {+ // Gone or no longer the reader's: its tombstone or a reload follows.+ parts.forgetStale(id);+ }+ } catch (failure) {+ if (_isUpdateRequired(failure)) rethrow;+ appLog.warn(+ 'swarm',+ 'closed group read failed: '+ '${failure is SuperTabFailure ? '${failure.code} (status ${failure.statusCode})' : failure.runtimeType}',+ );+ }+ }+ return read;+ }++ /// Reads group [id] by id into [parts], active or closed (section 4.5).+ /// False when the reader cannot read it (gone, or no longer theirs).+ Future<bool> _readGroup(SuperTabParts parts, String id) async {+ try {+ final answer = await request(+ 'GET',+ '$_path/groups/${Uri.encodeComponent(id)}',+ );+ if (!identical(parts, _parts) && _parts != null) return false;+ parts.addDormant([answer['group']]);+ return true;+ } on SuperTabFailure catch (failure) {+ if (const {'FORBIDDEN', 'NOT_FOUND'}.contains(failure.code)) return false;+ rethrow;+ }+ }++ /// The closed groups read for each project: where the next earlier page+ /// starts, null when there is none. A project not here has not been read.+ final _dormantPages = <String, String?>{};+ final _dormantReads = <String, Future<void>>{};++ /// Whether [projectId]'s closed groups have been read.+ bool dormantLoaded(String projectId) => _dormantPages.containsKey(projectId);++ /// Whether a read of [projectId]'s closed groups is under way.+ bool dormantLoading(String projectId) => _dormantReads.containsKey(projectId);++ /// Whether [projectId] has closed groups older than those read.+ bool hasEarlierDormant(String projectId) => _dormantPages[projectId] != null;++ /// Reads [projectId]'s closed groups, newest first, a page at a time: the+ /// first page once, [earlier] the next one. Joins a read under way.+ Future<void> loadDormant(String projectId, {bool earlier = false}) {+ if (_disposed || accessRevoked || _parts == null) return Future.value();+ if (_dormantReads[projectId] case final reading?) return reading;+ if (earlier ? !hasEarlierDormant(projectId) : dormantLoaded(projectId)) {+ return Future.value();+ }+ _changed();+ late final Future<void> reading;+ reading = _readDormant(projectId, earlier).whenComplete(() {+ if (identical(_dormantReads[projectId], reading)) {+ _dormantReads.remove(projectId);+ }+ _changed();+ });+ return _dormantReads[projectId] = reading;+ }++ Future<void> _readDormant(String projectId, bool earlier) async {+ final parts = _parts!;+ final before = earlier ? _dormantPages[projectId] : null;+ try {+ final answer = await request(+ 'GET',+ '$_path/groups?dormant=1&projectId=${Uri.encodeQueryComponent(projectId)}'+ '${before == null ? '' : '&before=${Uri.encodeQueryComponent(before)}'}',+ );+ if (_disposed || accessRevoked || !identical(parts, _parts)) return;+ final change = parts.addDormant(answer['groups'] as List);+ _dormantPages[projectId] = answer['next'] as String?;+ // Nothing new read changes nothing drawn, nor the view kept.+ if (change.changed) _redraw();+ } catch (failure) {+ if (_isUpdateRequired(failure)) {+ _requireUpdate();+ return;+ }+ // Not read: the next open of the list asks again.+ appLog.warn(+ 'swarm',+ 'closed groups read failed: '+ '${failure is SuperTabFailure ? '${failure.code} (status ${failure.statusCode})' : failure.runtimeType}',+ );+ }+ }++ /// Builds the snapshot again from the parts held, after a read on demand.+ void _redraw() {+ final parts = _parts;+ if (parts == null || snapshot == null) return;+ snapshot = SuperTabSnapshot.fromJson(parts.state);+ _viewVersion++;+ _changed();+ }+/// What a state read can change on screen, beside the messages.- ({int revision, String? error, bool failing, bool revoked, bool loading})+ ({int lastChangedAt, String? error, bool failing, bool revoked, bool loading})get _shown => (- revision: revision,+ lastChangedAt: lastChangedAt,error: error,failing: _refreshFailing,revoked: accessRevoked,@@ -842,7 +1124,10 @@ class SuperTabController extends ChangeNotifier {/// What a read of [id]'s messages asks for: the page before the oldest/// shown, what came after the newest, or the latest page.String _query(String id, {bool older = false}) {- if (older) return '?before=${_before[id]}';+ if (older) {+ final page = _before[id]!;+ return '?before=${page.sequence}&beforeId=${Uri.encodeQueryComponent(page.id)}';+ }// A saved page may be stale in its receipts as well as short of new// messages: the first read after it takes the latest page whole.if (_showingSaved) return '';@@ -861,8 +1146,22 @@ class SuperTabController extends ChangeNotifier {return known ? _query(id) : null;}+ /// A refusal that says this build is too old for the backend.+ static bool _isUpdateRequired(Object failure) =>+ failure is SuperTabFailure &&+ (failure.statusCode == 426 ||+ (failure.code == 'UPDATE_REQUIRED' && failure.statusCode != 400));++ /// Says to update Harness and stops the poll: no read can succeed now.+ void _requireUpdate() {+ updateRequired = true;+ error = updateMessage;+ _poll?.cancel();+ }+void _readFailure(Object failure, {bool revokeTab = true}) {if (_disposed) return;+ if (_isUpdateRequired(failure)) return _requireUpdate();error = failure is SuperTabFailure? failure.message: 'Could not refresh this conversation. Try again.';@@ -872,6 +1171,7 @@ class SuperTabController extends ChangeNotifier {accessRevoked = true;devicesSelected = false;snapshot = null;+ _parts = null;_messages.clear();_poll?.cancel();}@@ -995,13 +1295,12 @@ class SuperTabController extends ChangeNotifier {}_keepRows(id, receipt['messages'] as List);}- final next = combined.values.toList()- ..sort((a, b) => a.sequence.compareTo(b.sequence));+ final next = combined.values.toList()..sort(superTabMessageOrder);// An adapting read that found nothing new changes nothing on screen.final same = _policy.adapts && _sameMessages(_messages[id], next);_messages[id] = next;if (older || replacing || !_before.containsKey(id)) {- _before[id] = (answer['next'] as num?)?.toInt();+ _before[id] = SuperTabPage.read(answer['next']);}// Something new in the conversation on screen keeps the full poll.if (arrived && id == selectedId) _acted();@@ -1021,13 +1320,18 @@ class SuperTabController extends ChangeNotifier {}}- Future<Map<String, dynamic>?> command(Map<String, dynamic> command) async {+ /// Sends [command] once, under [operationId] when the caller fixes one so+ /// that a repeat is the same request (a new one by default).+ Future<Map<String, dynamic>?> command(+ Map<String, dynamic> command, {+ String? operationId,+ }) async {if (_disposed || !_maySend(command) || saving || _pending != null) {return null;}_acted();_pending = {- 'operationId': superTabOperationId(),+ 'operationId': operationId ?? superTabOperationId(),'command': Map<String, dynamic>.of(command),};return retry();@@ -1086,14 +1390,22 @@ class SuperTabController extends ChangeNotifier {_pending = pending;rethrow;}+ // What the command wrote is in the next change read.await refresh();- if (!_disposed &&- revision < ((answer['revision'] as num?)?.toInt() ?? revision)) {- await refresh();- }return result;} catch (failure) {- if (!_disposed) {+ if (!_disposed && _isUpdateRequired(failure)) {+ _requireUpdate();+ operationError = updateMessage;+ operationErrorCode = 'UPDATE_REQUIRED';+ // Refused by the backend: nothing was done, nothing to retry.+ _pending = null;+ try {+ await _persist();+ } catch (_) {+ _pending = pending;+ }+ } else if (!_disposed) {operationError = failure is SuperTabFailure? failure.message: 'The action is not confirmed. Retry to check it.';diff --git a/desktop/lib/super_tabs/launch.dart b/desktop/lib/super_tabs/launch.dartindex aec6135cf..29a820c5d 100644--- a/desktop/lib/super_tabs/launch.dart+++ b/desktop/lib/super_tabs/launch.dart@@ -57,11 +57,7 @@ class SuperTabLaunch {saved['phase'] == 'starting' || saved['phase'] == 'joining';List<HarnessLaunchRole>? roles;if (saved['lead'] != true && tab.superTabId != null) {- final current = await app.superTabs.map(- 'GET',- '/api/super-tabs/${tab.superTabId}',- );- final snapshot = SuperTabSnapshot.fromJson(superTabMap(current['state']));+ final snapshot = await app.superTabs.readSnapshot(tab.superTabId!);final project = snapshot.projectFor(conversationId);if (project?.skillSet == 'custom') {roles = [@@ -293,12 +289,8 @@ class SuperTabLaunch {app.superTabs.deferTabDiscovery(saved['tabId'] as String);// Revalidate a journal's destination before native submission. A project// deleted on another computer must not leave an unattached native session.- final current = await app.superTabs.map(- 'GET',- '/api/super-tabs/${saved['tabId']}',- );+ final snapshot = await app.superTabs.readSnapshot(saved['tabId'] as String);checkAccount();- final snapshot = SuperTabSnapshot.fromJson(superTabMap(current['state']));final conversationId = saved['conversationId'] as String;if (snapshot.conversation(conversationId) == null) {if (started) throw projectUnavailable;@@ -609,12 +601,10 @@ class SuperTabLaunch {return;}try {- final current = await app.superTabs.map(- 'GET',- '/api/super-tabs/${saved['tabId']}',+ final snapshot = await app.superTabs.readSnapshot(+ saved['tabId'] as String,);checkAccount();- final snapshot = SuperTabSnapshot.fromJson(superTabMap(current['state']));if (!snapshot.projects.any((p) => p.id == projectId) ||snapshot.agents.any((a) => a.projectId == projectId)) {return;diff --git a/desktop/lib/super_tabs/machines.dart b/desktop/lib/super_tabs/machines.dartindex b91b40836..05c10a744 100644--- a/desktop/lib/super_tabs/machines.dart+++ b/desktop/lib/super_tabs/machines.dart@@ -1651,7 +1651,7 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {}if (c.snapshot?.conversations.any((group) =>- !group.archived &&+ !group.closed &&group.assignment?['agentId'] == agent.id &&superTabWorkWaits(group.assignment?['status']),) ==diff --git a/desktop/lib/super_tabs/model.dart b/desktop/lib/super_tabs/model.dartindex ca3b676ea..3a8f49ff7 100644--- a/desktop/lib/super_tabs/model.dart+++ b/desktop/lib/super_tabs/model.dart@@ -26,8 +26,13 @@ class SuperTabPerson {SuperTabPerson.fromJson(Map<String, dynamic> row): id = _text(row, 'id'),email = _text(row, 'email'),- role = _text(row, 'role');+ role = _text(row, 'role'),+ generation = row['generation'] as String?;final String id, email, role;++ /// This membership: a new one each time the person joins the Swarm. Null+ /// from a backend that does not send it.+ final String? generation;bool get canWrite => role == 'owner' || role == 'collaborator';}@@ -89,6 +94,15 @@ class SuperTabConversation {leadId = row['leadId'] as String?,agentIds = List.unmodifiable((row['agentIds'] as List).cast<String>()),archived = row['archived'] == true,+ dormant = row['dormant'] == true,+ audience = row['audience'] is Map+ ? List.unmodifiable([+ for (final person+ in superTabMap(row['audience'])['people'] as List? ??+ const [])+ if (person is Map && person['id'] is String) person['id'],+ ])+ : null,checks = _list(row['checks'] ?? const [],(check) => Map<String, dynamic>.unmodifiable(check),@@ -112,6 +126,17 @@ class SuperTabConversation {final String? leadId;final List<String> agentIds;final bool archived;++ /// A private conversation's people, who read it with the project's Lead+ /// and nobody else; null for a conversation the project shares.+ final List<String>? audience;++ /// Out of the Swarm's active groups: archived, or finished and quiet for a+ /// day. Read on demand; a new message brings it back.+ final bool dormant;++ /// Listed with the project's closed groups, not its active ones.+ bool get closed => archived || dormant;final List<Map<String, dynamic>> checks;/// Persisted links may be absent on older backends; loaded messages still supply links.@@ -551,6 +576,35 @@ SuperTabAttachment? _tryAttachment(Object? row) {}}+/// Messages in the order a conversation shows them: by sequence, then id, as+/// the backend pages them (messages from before the parts migration can share+/// a sequence).+int superTabMessageOrder(SuperTabMessage a, SuperTabMessage b) {+ final bySequence = a.sequence.compareTo(b.sequence);+ return bySequence != 0 ? bySequence : a.id.compareTo(b.id);+}++/// Where a conversation's older history continues: the message a page ended+/// on (docs/design/2026-10-26-swarm-state-parts.md, section 4.6).+class SuperTabPage {+ const SuperTabPage(this.sequence, this.id);+ SuperTabPage.of(SuperTabMessage message) : this(message.sequence, message.id);++ /// The backend's `next`, or null at the start of the conversation.+ static SuperTabPage? read(Object? next) => switch (next) {+ {'sequence': final num sequence, 'id': final String id} => SuperTabPage(+ sequence.toInt(),+ id,+ ),+ null => null,+ _ => throw const FormatException('Invalid Swarm page.'),+ };++ final int sequence;+ final String id;+ Map<String, dynamic> toJson() => {'sequence': sequence, 'id': id};+}+/// Optional timing/hold fields keep messages from older backends readable.class SuperTabDelivery {SuperTabDelivery.fromJson(Map<String, dynamic> row)diff --git a/desktop/lib/super_tabs/notifications.dart b/desktop/lib/super_tabs/notifications.dartindex d00d9447f..625fa95ce 100644--- a/desktop/lib/super_tabs/notifications.dart+++ b/desktop/lib/super_tabs/notifications.dart@@ -69,7 +69,7 @@ class SuperTabMentions extends ChangeNotifier {List<SuperTabMention> waiting = const [], earlier = const [];String? error;int? _count;- int _revision = -1;+ int _lastChangedAt = -1;// Null until the first read: tags waiting then are not news.Set<String>? _seen;Future<void>? _loading;@@ -93,8 +93,8 @@ class SuperTabMentions extends ChangeNotifier {// A tag that expires moves the count without changing the Swarm.final count = snapshot.mentionsWaiting;final moved = count != _count;- if (!moved && controller.revision == _revision) return;- _revision = controller.revision;+ if (!moved && controller.lastChangedAt == _lastChangedAt) return;+ _lastChangedAt = controller.lastChangedAt;_count = count;if (count == 0 && (!moved || _seen == null)) {_seen ??= {};@@ -221,6 +221,13 @@ class _SuperTabNotificationsState extends State<SuperTabNotifications> {Widget _row(SuperTabMention mention, {required bool waiting}) {final time = mention.createdAt;+ // The reader's own chat with the Product Manager is named as the sidebar+ // names it, not by the reader's own name.+ final place =+ widget.mentions.controller.pmChat(mention.projectId)?.id ==+ mention.conversationId+ ? 'Chat with PM'+ : mention.conversationTitle;return Padding(padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 1),child: Material(@@ -260,7 +267,7 @@ class _SuperTabNotificationsState extends State<SuperTabNotifications> {],),Text(- '${mention.projectName} · ${mention.conversationTitle}',+ '${mention.projectName} · $place',maxLines: 1,overflow: TextOverflow.ellipsis,style: DesktopChrome.metadata(),diff --git a/desktop/lib/super_tabs/parts.dart b/desktop/lib/super_tabs/parts.dartnew file mode 100644index 000000000..76aa2308e--- /dev/null+++ b/desktop/lib/super_tabs/parts.dart@@ -0,0 +1,352 @@+import 'package:collection/collection.dart' show DeepCollectionEquality;++import 'model.dart';++/// The response shape a Swarm read answers in (docs/design/2026-10-26-swarm-state-parts.md, section 4), mirrored by+/// hand from backend `superTabs/read/contract.ts` (final at cd004bf5c). A first load of any other format is from a+/// backend this build cannot read.+const superTabReadFormat = 2;++/// The part lists a first load and a change read carry, by their names there. The head is a single part.+const _lists = [+ 'members',+ 'agents',+ 'groups',+ 'machines',+ 'starts',+ 'progress',+];++/// What one change read or dormant page did to the store.+class SuperTabPartsChange {+ const SuperTabPartsChange({+ required this.changed,+ this.removedGroups = const {},+ this.dormantGroups = const {},+ });++ /// Some part or a derived value is new: what the screens draw may differ.+ final bool changed;++ /// Groups whose part was deleted: nothing of them stays on this device.+ final Set<String> removedGroups;++ /// Groups that left the active set: they stay readable on demand.+ final Set<String> dormantGroups;+}++/// The parts of one Swarm as this reader last saw them (section 5.1): every part by kind and key at the newest+/// version read, the values worked out at read time (`derived`), and where the next change read starts. The screens+/// keep reading the old whole-Swarm shape, which [state] builds from the parts.+class SuperTabParts {+ SuperTabParts._(+ this._head,+ this._derived, {+ required this.cursor,+ required this.epoch,+ required this.lastChangedAt,+ required this.githubApp,+ });++ /// A first load (section 4.3). Throws a [FormatException] for a response of another format.+ factory SuperTabParts.firstLoad(Map<String, dynamic> answer) {+ if (answer['format'] != superTabReadFormat) {+ throw const FormatException('Update Harness to open this Swarm.');+ }+ final parts = SuperTabParts._(+ _envelope(answer['head'], live: true),+ superTabMap(answer['derived'] ?? const {}),+ cursor: _cursor(answer),+ epoch: _int(answer['epoch']),+ // Null for a Swarm with no part changed yet (contract.ts `ReadMeta`).+ lastChangedAt: _int(answer['lastChangedAt'] ?? 0),+ githubApp: answer['githubApp'] == true,+ );+ parts._seen['head'] = _int(parts._head['version']);+ for (final kind in _lists) {+ final held = parts._live[kind] = <String, Map<String, dynamic>>{};+ for (final raw in answer[kind] as List? ?? const []) {+ final part = _envelope(raw, live: true);+ held[part['key'] as String] = part;+ parts._seen['$kind:${part['key']}'] = _int(part['version']);+ }+ }+ return parts;+ }++ /// What [toJson] kept, or a [FormatException] for anything else.+ factory SuperTabParts.fromJson(Map<String, dynamic> json) {+ final parts = SuperTabParts.firstLoad(superTabMap(json['load']));+ for (final raw in json['dormant'] as List? ?? const []) {+ final part = _envelope(raw, live: true);+ parts._dormant[part['key'] as String] = part;+ }+ parts._stale.addAll(+ (json['stale'] as List? ?? const []).whereType<String>(),+ );+ final seen = json['seen'];+ if (seen is Map) {+ for (final entry in seen.entries) {+ if (entry.key is String && entry.value is num) {+ parts._seen[entry.key as String] = (entry.value as num).toInt();+ }+ }+ }+ return parts;+ }++ /// Where the next change read starts: opaque, the server's (section 4.2).+ String cursor;++ /// The visibility epoch of the last read. The server answers a change read with a reload when it moves.+ int epoch;++ /// The newest change of any part, in epoch milliseconds (spec ruling 8): what tells a list or a cache that this+ /// Swarm changed. 0 before any part changed.+ int lastChangedAt;++ /// Whether the backend has the GitHub app, as the first load says.+ final bool githubApp;++ Map<String, dynamic> _head;+ Map<String, dynamic> _derived;+ final _live = <String, Map<String, Map<String, dynamic>>>{};++ /// Groups out of the active set whose data this reader has: read on demand, or held when they went dormant.+ final _dormant = <String, Map<String, dynamic>>{};++ /// The newest version seen of every part, deleted and dormant ones included: an older copy the overlap sends+ /// again never replaces it or brings it back (section 4.4).+ final _seen = <String, int>{};++ /// Dormant groups held with their data from before a stub closed them: a read by id at the stub's version is+ /// their current data.+ final _stale = <String>{};++ /// The values worked out at read time, as the last read sent them.+ Map<String, dynamic> get derived => _derived;++ /// Whether this reader holds group [groupId], active or dormant.+ bool holdsGroup(String groupId) =>+ _live['groups']?.containsKey(groupId) == true ||+ _dormant.containsKey(groupId);++ /// Dormant groups held with data from before a stub closed them, to read again by id.+ List<String> get staleGroups => _stale.toList();++ /// Keeps [groupId]'s held data as it is: it cannot be read again.+ void forgetStale(String groupId) => _stale.remove(groupId);++ /// Whether [groupId] is a dormant group this reader holds.+ bool isDormant(String groupId) => _dormant.containsKey(groupId);++ /// Merges one change read (section 4.4): a higher version wins, a tombstone removes the part, a dormant stub moves+ /// the group out of the active ones, `derived` is replaced, and the cursor moves. A reload answer is the caller's.+ SuperTabPartsChange apply(Map<String, dynamic> changes) {+ var changed = false;+ final removed = <String>{}, dormant = <String>{};+ if (changes['head'] != null) {+ final head = _envelope(changes['head'], live: true);+ if (_newer('head', head)) {+ _head = head;+ changed = true;+ }+ }+ for (final kind in _lists) {+ final held = _live.putIfAbsent(kind, () => {});+ for (final raw in changes[kind] as List? ?? const []) {+ final part = _envelope(raw, live: false);+ final key = part['key'] as String;+ if (!_newer('$kind:$key', part)) continue;+ changed = true;+ if (part['deleted'] == true) {+ held.remove(key);+ if (kind == 'groups') {+ _dormant.remove(key);+ _stale.remove(key);+ removed.add(key);+ }+ } else if (kind == 'groups' && part['dormant'] == true) {+ final last = held.remove(key) ?? _dormant[key];+ if (last != null) {+ _stale.add(key);+ _dormant[key] = {+ ...last,+ 'version': part['version'],+ 'changedAt': part['changedAt'],+ 'data': {...superTabMap(last['data']), 'dormant': true},+ };+ }+ dormant.add(key);+ } else {+ if (part['data'] == null) {+ throw const FormatException('A Swarm part arrived without data.');+ }+ held[key] = part;+ if (kind == 'groups') {+ _dormant.remove(key);+ _stale.remove(key);+ }+ }+ }+ }+ final derived = superTabMap(changes['derived'] ?? const {});+ if (!const DeepCollectionEquality().equals(derived, _derived)) {+ _derived = derived;+ changed = true;+ }+ cursor = _cursor(changes);+ epoch = _int(changes['epoch'] ?? epoch);+ lastChangedAt = _int(changes['lastChangedAt'] ?? lastChangedAt);+ return SuperTabPartsChange(+ changed: changed,+ removedGroups: removed,+ dormantGroups: dormant,+ );+ }++ /// Takes dormant groups read on demand (section 4.5): a page of the dormant list, or one group by id. Each is kept+ /// unless this reader already holds a newer version of it; one that is active here at a lower version moves out.+ SuperTabPartsChange addDormant(List groups) {+ var changed = false;+ final active = _live.putIfAbsent('groups', () => {});+ for (final raw in groups) {+ final part = _envelope(raw, live: true);+ final key = part['key'] as String;+ final current =+ _stale.contains(key) && _int(part['version']) == _seen['groups:$key'];+ if (!current && !_newer('groups:$key', part)) continue;+ _stale.remove(key);+ changed = true;+ if (superTabMap(part['data'])['dormant'] == true) {+ active.remove(key);+ _dormant[key] = part;+ } else {+ active[key] = part;+ _dormant.remove(key);+ }+ }+ return SuperTabPartsChange(changed: changed);+ }++ /// The old whole-Swarm shape (section 5.1, "Reassemble a state"), from the head, the parts and `derived`. Active+ /// groups come first in the order they were read, then the dormant groups held.+ Map<String, dynamic> get state {+ final agentsDerived = _derivedMap('agents');+ final machinesDerived = _derivedMap('machines');+ final state = <String, dynamic>{+ ...superTabMap(_head['data']),+ 'format': superTabReadFormat,+ 'people': [for (final p in _data('members')) p],+ 'agents': [+ for (final agent in _data('agents'))+ _overlay(agent, agentsDerived[agent['id']], keepNull: 'workDecision'),+ ],+ 'conversations': [+ ..._data('groups'),+ for (final part in _dormant.values) superTabMap(part['data']),+ ],+ 'machines': [+ for (final machine in _data('machines'))+ _overlay(machine, machinesDerived[machine['machineId']]),+ ],+ 'starts': [for (final start in _data('starts')) start],+ 'githubApp': githubApp,+ };+ if (_derived['otherProjectsWork'] case final List work) {+ state['otherProjectsWork'] = work;+ }+ if (_derived['mentionsWaiting'] case final num waiting) {+ state['mentionsWaiting'] = waiting.toInt();+ }+ return state;+ }++ /// What to keep on this device to read the same store back ([SuperTabParts.fromJson]).+ Map<String, dynamic> toJson() => {+ 'load': {+ 'format': superTabReadFormat,+ 'cursor': cursor,+ 'epoch': epoch,+ 'lastChangedAt': lastChangedAt,+ 'githubApp': githubApp,+ 'head': _head,+ for (final kind in _lists)+ kind: (_live[kind] ?? const {}).values.toList(),+ 'derived': _derived,+ },+ 'dormant': _dormant.values.toList(),+ 'seen': Map<String, int>.of(_seen),+ 'stale': _stale.toList(),+ };++ /// [json] (from [toJson]) without what the screens never draw: agent starts carry their tasks, and project+ /// progress is never shown. A store read back from it gets them again as they change.+ static Map<String, dynamic> drawnOnly(Map<String, dynamic> json) {+ const undrawn = {'starts', 'progress'};+ final seen = json['seen'];+ return {+ ...json,+ 'load': {+ ...superTabMap(json['load']),+ for (final kind in undrawn) kind: const <dynamic>[],+ },+ 'seen': {+ if (seen is Map)+ for (final entry in seen.entries)+ if (!undrawn.contains((entry.key as String).split(':').first))+ entry.key: entry.value,+ },+ };+ }++ Iterable<Map<String, dynamic>> _data(String kind) =>+ (_live[kind] ?? const {}).values.map((part) => superTabMap(part['data']));++ Map<String, dynamic> _derivedMap(String name) =>+ _derived[name] is Map ? superTabMap(_derived[name]) : const {};++ /// [record] with the derived values over it. A null [keepNull] value means the stored one stands.+ static Map<String, dynamic> _overlay(+ Map<String, dynamic> record,+ Object? derived, {+ String? keepNull,+ }) {+ if (derived is! Map) return record;+ final next = {...record};+ for (final entry in derived.entries) {+ if (entry.key == keepNull && entry.value == null) continue;+ next[entry.key as String] = entry.value;+ }+ return next;+ }++ /// Whether [part] is newer than what was seen of [id], recording it when it is.+ bool _newer(String id, Map<String, dynamic> part) {+ final version = _int(part['version']);+ final seen = _seen[id];+ if (seen != null && version <= seen) return false;+ _seen[id] = version;+ return true;+ }++ static Map<String, dynamic> _envelope(Object? raw, {required bool live}) {+ final part = superTabMap(raw);+ if (part['key'] is! String || part['version'] is! num) {+ throw const FormatException('Invalid Swarm part.');+ }+ if (live && part['data'] is! Map) {+ throw const FormatException('A Swarm part arrived without data.');+ }+ return part;+ }++ static String _cursor(Map<String, dynamic> answer) =>+ answer['cursor'] is String+ ? answer['cursor'] as String+ : throw const FormatException('Missing Swarm cursor.');++ static int _int(Object? value) => value is num+ ? value.toInt()+ : throw const FormatException('Invalid Swarm read.');+}diff --git a/desktop/lib/super_tabs/project_sidebar.dart b/desktop/lib/super_tabs/project_sidebar.dartindex 04c27698e..3aa03cee3 100644--- a/desktop/lib/super_tabs/project_sidebar.dart+++ b/desktop/lib/super_tabs/project_sidebar.dart@@ -1,3 +1,5 @@+import 'dart:async';+import 'package:flutter/material.dart';import '../core/machine_resources.dart';@@ -145,6 +147,7 @@ class ProjectSidebar extends StatelessWidget {SuperTabProject? project,String? label,IconData? icon,+ String? key,}) {final selected =!devicesSelected &&@@ -153,7 +156,7 @@ class ProjectSidebar extends StatelessWidget {final groups = project == null? [group]: controller.snapshot!.conversations.where(- (g) => g.projectId == project.id && !g.archived,+ (g) => g.projectId == project.id && !g.closed,);final waiting = groups.any((g) => needsHuman(g) > 0);final unread = groups.any(controller.unread);@@ -166,7 +169,7 @@ class ProjectSidebar extends StatelessWidget {borderRadius: BorderRadius.circular(DesktopChrome.rowRadius),clipBehavior: Clip.antiAlias,child: InkWell(- key: ValueKey('super-group-${group.id}'),+ key: ValueKey(key ?? 'super-group-${group.id}'),onTap: () => onSelect(group.id),hoverColor: grid.AppSurface.hoverFill,focusColor: grid.AppSurface.hoverFill,@@ -285,14 +288,16 @@ class ProjectSidebar extends StatelessWidget {);}- /// A project's "Closed (N)" row and, when it is open, the archived groups under it.+ /// A project's "Closed (N)" row and, when it is open, the closed groups under it: archived ones and finished+ /// ones that left the active set, as read for the project so far.List<Widget> _closed(SuperTabProject project) {final groups = controller.snapshot!.conversations.where((g) =>g.projectId == project.id &&g.id != project.leadConversationId &&- g.archived,+ g.id != controller.pmChat(project.id)?.id &&+ g.closed,).toList();if (groups.isEmpty) return const [];@@ -347,17 +352,52 @@ class ProjectSidebar extends StatelessWidget {),),),- if (open)+ if (open) ...[for (final group in groups) _row(group),+ if (controller.hasEarlierDormant(project.id))+ _navigationRow(+ key: 'super-closed-earlier-${project.id}',+ label: controller.dormantLoading(project.id)+ ? 'Loading…'+ : 'Show earlier',+ icon: AppIcons.chevronDown,+ onTap: controller.dormantLoading(project.id)+ ? null+ : () => unawaited(+ controller.loadDormant(project.id, earlier: true),+ ),+ ),+ ],];}+ /// The signed-in person's private chat with the project's Product Manager,+ /// above its workgroups; the first click opens it.+ Widget? _pmChat(SuperTabProject project) {+ const label = 'Chat with PM';+ final key = 'super-pm-chat-${project.id}';+ if (controller.pmChat(project.id) case final chat?) {+ return _row(chat, label: label, icon: AppIcons.messageSquare, key: key);+ }+ if (!controller.canWrite) return null;+ return _navigationRow(+ key: key,+ label: label,+ icon: AppIcons.messageSquare,+ onTap: controller.saving || controller.hasPendingAction+ ? null+ : () => unawaited(controller.openPmChat(project.id)),+ );+ }+List<Widget> _workgroups(SuperTabProject project) {+ final pmChat = controller.pmChat(project.id)?.id;final groups = controller.snapshot!.conversations.where((g) =>g.projectId == project.id &&g.id != project.leadConversationId &&- !g.archived,+ g.id != pmChat &&+ !g.closed,);return groups.isEmpty? [@@ -452,6 +492,7 @@ class ProjectSidebar extends StatelessWidget {children: [_row(lead, project: project),if (controller.expandedProjects.contains(project.id)) ...[+ ?_pmChat(project),..._workgroups(project),..._closed(project),],diff --git a/desktop/lib/super_tabs/roles_editor.dart b/desktop/lib/super_tabs/roles_editor.dartindex cea6d0c5e..03bc9d45b 100644--- a/desktop/lib/super_tabs/roles_editor.dart+++ b/desktop/lib/super_tabs/roles_editor.dart@@ -56,6 +56,7 @@ Keep each Builder's list a few tasks deep; do the easy, self-contained parts fir- A worker with active work that has said nothing for 20 minutes: ask it.- When a worker seems stuck, read its terminal; answer prompts within its task; ask the owner before approving anything risky.- A Builder or Reviewer that has been down for 2 hours (its machine offline, its session gone, or stopped): cancel its task with the reason, route it, and assign it to another agent with what the first one left (branch, last revision, last report).+- When you are told a task is lost, hand it on at once: route it and assign it to another agent, avoiding what failed (another machine if its machine died, another account or engine if it hit a usage limit). The new brief tells the successor to continue from the lost attempt's pushed branch and last result, not to start over.- Work with no progress for 6 hours goes back to you: reassign it or cut it smaller.- Needs a person: get the decision now. Blocked: change something (context, model, size or plan); never resend the same thing.- When you need a person to act or decide, tag them in the message.@@ -104,6 +105,7 @@ You finish one group's work completely, inside its brief, as if nobody will come- A fix comes with a test that fails before it and passes after.- Name a known flaky test instead of letting it block you.- Have something to show at least every 20 minutes: a push or a short progress line.+- Push your work branch at least every 30 minutes, and set your work status to working with a one-line note of what is done and what is next, so another agent can continue if you stop.- When an answer is unclear, take its narrowest safe reading and say so. Keep working on whatever doesn't depend on a question, and don't ask twice.- To split the work or take more, ask the Lead. You may propose new work; the Lead decides.diff --git a/desktop/lib/super_tabs/roster.dart b/desktop/lib/super_tabs/roster.dartindex 710b4bf09..795b6930b 100644--- a/desktop/lib/super_tabs/roster.dart+++ b/desktop/lib/super_tabs/roster.dart@@ -181,7 +181,7 @@ class _SuperTabRosterState extends State<SuperTabRoster> {}if (c.snapshot?.conversations.any((group) =>- !group.archived &&+ !group.closed &&group.assignment?['agentId'] == agent.id &&superTabWorkWaits(group.assignment?['status']),) ==@@ -269,16 +269,20 @@ class _SuperTabRosterState extends State<SuperTabRoster> {.where((p) => p.id == _agentProjectId(agent)).firstOrNull;final customRole = c.snapshot!.activeRoleForAgent(agent);- final role = customRole?.name ?? (c.snapshot!.isLead(agent.id)- ? 'Product Manager'- : agent.isReviewer- ? 'Reviewer'- : 'Engineer');- final badge = customRole?.name ?? (c.snapshot!.isLead(agent.id)- ? 'PM'- : agent.isReviewer- ? 'Rev'- : 'Dev');+ final role =+ customRole?.name ??+ (c.snapshot!.isLead(agent.id)+ ? 'Product Manager'+ : agent.isReviewer+ ? 'Reviewer'+ : 'Engineer');+ final badge =+ customRole?.name ??+ (c.snapshot!.isLead(agent.id)+ ? 'PM'+ : agent.isReviewer+ ? 'Rev'+ : 'Dev');final status = info.status ?? 'Status unavailable';final tooltip = [[name, role, ?project?.name].join(' · '),@@ -389,17 +393,25 @@ class _SuperTabRosterState extends State<SuperTabRoster> {final projectId = c.selected?.projectId == ''? null: c.selected?.projectId;+ // A private conversation lists only who reads it: its people and the+ // agents in it, the project's Lead.+ final audience = c.selected?.audience;final members =state?.agents.where((agent) =>- projectId == null || _agentProjectId(agent) == projectId,+ (projectId == null || _agentProjectId(agent) == projectId) &&+ (audience == null || c.selected!.agentIds.contains(agent.id)),).toList() ??const <SuperTabAgent>[];final leads = members.where((a) => state!.isLead(a.id)).toList();final agents = members.where((a) => !state!.isLead(a.id)).toList();- final people = state?.people ?? const <SuperTabPerson>[];+ final people =+ state?.people+ .where((p) => audience == null || audience.contains(p.id))+ .toList() ??+ const <SuperTabPerson>[];final shownPeople = _allPeople ? people : people.take(_peopleShown);final compact = workspaceIsCompact(context);return [@@ -469,11 +481,13 @@ class _SuperTabRosterState extends State<SuperTabRoster> {const SizedBox(height: 16),SuperTabSectionHeading('Agents',- // An agent joins the Product Managers' conversation by leading a project.+ // An agent joins the Product Managers' conversation by leading a project,+ // and a private conversation holds only the project's Lead.onAdd:c.canWrite &&c.selected != null &&- c.selected!.id != c.snapshot?.leadsConversationId+ c.selected!.id != c.snapshot?.leadsConversationId &&+ audience == null? () => widget.onAddAgent(c.selected!): null,addTooltip: 'Add agent',diff --git a/desktop/lib/super_tabs/saved_view.dart b/desktop/lib/super_tabs/saved_view.dartindex 5157db943..93be11022 100644--- a/desktop/lib/super_tabs/saved_view.dart+++ b/desktop/lib/super_tabs/saved_view.dart@@ -1,6 +1,7 @@import 'dart:convert';import '../core/local_key_value_store.dart';+import 'parts.dart';/// The last view of a Swarm tab as read: the state the tab draws and the open/// conversation's last page, kept on this device so the next open draws it at@@ -16,26 +17,6 @@ class SuperTabSavedViews {/// How many Swarms an account keeps a view of, most recently used first.static const maxTabs = 3;- /// What `SuperTabSnapshot.fromJson` reads: everything else in a state is- /// never drawn, so it is never kept (agent starts carry their tasks).- static const _drawn = {- 'version',- 'id',- 'name',- 'ownerId',- 'paused',- 'project',- 'people',- 'agents',- 'machines',- 'conversations',- 'invitations',- 'leadsConversationId',- 'localModels',- 'mentionsWaiting',- 'projects',- };-String _key(String account, String tabId) => 'super_tab.view.$account.$tabId';String _index(String account) => 'super_tab.views.$account';@@ -88,9 +69,11 @@ class SuperTabSavedViews {final raw = await storage.read(_key(account, tabId));if (raw == null) return null;final view = jsonDecode(raw);+ // A view an older build kept (a whole state, not parts) is none.if (view is! Map<String, dynamic> ||- view['state'] is! Map<String, dynamic> ||- view['revision'] is! int) {+ view['format'] != superTabReadFormat ||+ view['parts'] is! Map<String, dynamic> ||+ view['lastChangedAt'] is! int) {return null;}try {@@ -110,13 +93,11 @@ class SuperTabSavedViews {// Only for the account using this device: after a sign-out in// another tab, or another account's claim, a late write keeps nothing.if (await storage.read(_owner) != account) return false;- final state = view['state'] as Map<String, dynamic>;final text = jsonEncode({...view,- 'state': {- for (final entry in state.entries)- if (_drawn.contains(entry.key)) entry.key: entry.value,- },+ 'parts': SuperTabParts.drawnOnly(+ view['parts'] as Map<String, dynamic>,+ ),});if (_utf8Length(text) > maxBytes) {await _forget(account, tabId);diff --git a/desktop/lib/super_tabs/view.dart b/desktop/lib/super_tabs/view.dartindex 8b214d3be..49007a0dc 100644--- a/desktop/lib/super_tabs/view.dart+++ b/desktop/lib/super_tabs/view.dart@@ -425,7 +425,7 @@ class _SuperTabViewState extends State<SuperTabView>).toList();groups.sort((a, b) {- final active = (a.archived ? 1 : 0).compareTo(b.archived ? 1 : 0);+ final active = (a.closed ? 1 : 0).compareTo(b.closed ? 1 : 0);if (active != 0) return active;final project = (a.projectId == projectId ? 0 : 1).compareTo(b.projectId == projectId ? 0 : 1,@@ -647,6 +647,9 @@ class _SuperTabViewState extends State<SuperTabView>Future<void> _archived() async {final c = this.c;var query = '';+ // Archived groups are out of the active set: read the project's now.+ final projectId = c.selected?.projectId;+ if (projectId != null) unawaited(c.loadDormant(projectId));final selected = await showAppDialog<String>(context: context,builder: (context) => SuperTabDialogScope(@@ -684,8 +687,13 @@ class _SuperTabViewState extends State<SuperTabView>const SizedBox(height: 12),Expanded(child: groups.isEmpty- ? const Center(- child: Text('No archived conversations.'),+ ? Center(+ child: Text(+ projectId != null &&+ c.dormantLoading(projectId)+ ? 'Loading archived conversations…'+ : 'No archived conversations.',+ ),): ListView(children: [@@ -701,6 +709,26 @@ class _SuperTabViewState extends State<SuperTabView>],),),+ // Older closed groups are a page away whatever the+ // rows above show: newer finished groups or a search+ // can leave none of them archived or matching.+ if (projectId != null && c.hasEarlierDormant(projectId))+ ListTile(+ key: const ValueKey('super-archived-earlier'),+ title: Text(+ c.dormantLoading(projectId)+ ? 'Loading…'+ : 'Show earlier',+ style: DesktopChrome.control(+ color: DesktopChrome.muted,+ ),+ ),+ onTap: c.dormantLoading(projectId)+ ? null+ : () => unawaited(+ c.loadDormant(projectId, earlier: true),+ ),+ ),],),),@@ -862,6 +890,10 @@ class _SuperTabViewState extends State<SuperTabView>bool get _terminalsVisible =>!_devicesVisible && (widget.terminalsVisible || widget.terminal != null);+ /// The reader's own private chat with its project's Product Manager.+ bool _isPmChat(SuperTabConversation group) =>+ c.pmChat(group.projectId)?.id == group.id;+/// The open conversation's name, or what the pane shows instead of one.Widget _title(SuperTabConversation? group) => Text(_devicesVisible@@ -876,6 +908,8 @@ class _SuperTabViewState extends State<SuperTabView>? c.snapshot!.projectFor(group.id)!.name: group.id == c.snapshot!.leadsConversationId? 'Product Managers'+ : _isPmChat(group)+ ? 'Chat with PM': group.label,maxLines: 1,overflow: TextOverflow.ellipsis,@@ -1138,7 +1172,9 @@ class _SuperTabViewState extends State<SuperTabView>if (editable && project?.ownerId == c.accountId)item('Delete Project', () => _groupAction('delete', group)),] else ...[- item('Work details', () => _groupAction('work', group)),+ // A private conversation is chat only: it has no work.+ if (group.audience == null)+ item('Work details', () => _groupAction('work', group)),if (editable) ...[item('Rename', () => _groupAction('rename', group)),item(@@ -1154,10 +1190,14 @@ class _SuperTabViewState extends State<SuperTabView>),],],- if (c.snapshot?.conversations.any(- (g) => g.archived && g.projectId == group.projectId,- ) ==- true)+ // Until all of the project's closed groups are read, it may have+ // archived ones: the list reads them when it opens.+ if (!c.dormantLoaded(group.projectId) ||+ c.hasEarlierDormant(group.projectId) ||+ c.snapshot?.conversations.any(+ (g) => g.archived && g.projectId == group.projectId,+ ) ==+ true)item('Archived conversations', () => _groupAction('archived', group)),],builder: (context, menu, _) => AppIconButton(@@ -1298,7 +1338,7 @@ class _SuperTabViewState extends State<SuperTabView>textAlign: TextAlign.center,style: DesktopChrome.text(color: DesktopChrome.muted),),- if (!c.accessRevoked) ...[+ if (!c.accessRevoked && !c.updateRequired) ...[const SizedBox(height: 12),TextButton(style: _thumb,@@ -1401,7 +1441,7 @@ class _SuperTabViewState extends State<SuperTabView>child: Row(children: [Expanded(child: Text(c.error!, style: DesktopChrome.control())),- if (!c.accessRevoked)+ if (!c.accessRevoked && !c.updateRequired)TextButton(onPressed: () => unawaited(c.refresh()),child: const Text('Retry'),@@ -1423,6 +1463,8 @@ class _SuperTabViewState extends State<SuperTabView>? 'Loading conversation…': c.snapshot!.isProjectLead(group.id)? 'Discuss the plan with your product manager.'+ : _isPmChat(group)+ ? 'Only you and the Product Manager read this chat.': 'Start the conversation.',style: DesktopChrome.text(color: DesktopChrome.muted),),@@ -1826,8 +1868,9 @@ class _SuperTabViewState extends State<SuperTabView>? 'Loading conversation…': c.canWrite? c.snapshot!.isProjectLead(- group.id,- )+ group.id,+ ) ||+ _isPmChat(group)? 'Message Product Manager': group.id ==cdiff --git a/desktop/lib/super_tabs/work_details.dart b/desktop/lib/super_tabs/work_details.dartindex 9eb166d00..467bcee00 100644--- a/desktop/lib/super_tabs/work_details.dart+++ b/desktop/lib/super_tabs/work_details.dart@@ -1,3 +1,5 @@+import 'dart:async';+import 'package:flutter/material.dart';import '../shared/widgets/app_dialog.dart';@@ -12,6 +14,16 @@ Future<void> showSuperTabWork(BuildContext context,SuperTabController c,String groupId,+) {+ // A closed group stays readable here: one not held yet is read by id.+ unawaited(c.loadGroup(groupId));+ return _showWork(context, c, groupId);+}++Future<void> _showWork(+ BuildContext context,+ SuperTabController c,+ String groupId,) => showAppDialog<void>(context: context,builder: (context) => ListenableBuilder(diff --git a/desktop/lib/super_tabs/workspace.dart b/desktop/lib/super_tabs/workspace.dartindex 453b55d92..0fc28bf27 100644--- a/desktop/lib/super_tabs/workspace.dart+++ b/desktop/lib/super_tabs/workspace.dart@@ -397,7 +397,7 @@ class _SuperTabWorkspaceState extends State<SuperTabWorkspace> {) async {final groups =controller.snapshot?.conversations- .where((g) => !g.archived && g.agentIds.contains(agent.id))+ .where((g) => !g.closed && g.agentIds.contains(agent.id)).toList() ??<SuperTabConversation>[];if (groups.isEmpty) return;diff --git a/desktop/test/settings_saved_super_tabs_test.dart b/desktop/test/settings_saved_super_tabs_test.dartindex 5e760935a..a35308a16 100644--- a/desktop/test/settings_saved_super_tabs_test.dart+++ b/desktop/test/settings_saved_super_tabs_test.dart@@ -162,10 +162,10 @@ void main() {final server = ConversationServer()..append('Hello');final client = SuperTabClient(transport: (method, path, {body}) async =>- Uri.parse(path).path == '/api/super-tabs'+ Uri.parse(path).path == '/api/super-tabs/list'? {'tabs': [- {'id': 'tab', 'name': 'Pilot'},+ {'id': 'tab', 'name': 'Pilot', 'lastChangedAt': 1},],'next': null,}diff --git a/desktop/test/super_tab_closed_groups_test.dart b/desktop/test/super_tab_closed_groups_test.dartindex e7377f573..11457b3d2 100644--- a/desktop/test/super_tab_closed_groups_test.dart+++ b/desktop/test/super_tab_closed_groups_test.dart@@ -169,4 +169,44 @@ void main() {},);}++ testWidgets(+ 'closed groups read a page at a time; Show earlier reads the next',+ (tester) async {+ await tester.binding.setSurfaceSize(const Size(1280, 800));+ addTearDown(() => tester.binding.setSurfaceSize(null));+ final server = ConversationServer()..parts.dormantPage = 1;+ final groups = server.state['conversations'] as List;+ groups[1]['archived'] = true;+ groups.add({+ ...conversationFixture('second', 'Second closed'),+ 'projectId': 'lead',+ 'archived': true,+ });+ final controller = server.controller();+ await controller.refresh();+ await tester.pumpWidget(_app(server, controller));+ await tester.pumpAndSettle();+ if (closedRow.evaluate().isEmpty) {+ await tester.tap(+ find.byKey(const ValueKey('super-project-expand-lead')),+ );+ await tester.pumpAndSettle();+ }+ expect(find.text('Closed (1)'), findsOneWidget);+ await tester.tap(closedRow);+ await tester.pumpAndSettle();+ final earlier = find.byKey(const ValueKey('super-closed-earlier-lead'));+ expect(earlier, findsOneWidget);+ await tester.tap(earlier);+ await tester.pumpAndSettle();+ expect(find.text('Closed (2)'), findsOneWidget);+ expect(earlier, findsNothing);+ expect(find.byKey(const ValueKey('super-group-offline')), findsOneWidget);+ expect(find.byKey(const ValueKey('super-group-second')), findsOneWidget);+ await tester.pumpWidget(const SizedBox());+ await controller.flush();+ controller.dispose();+ },+ );}diff --git a/desktop/test/super_tab_discovery_test.dart b/desktop/test/super_tab_discovery_test.dartindex a21f36507..003baa124 100644--- a/desktop/test/super_tab_discovery_test.dart+++ b/desktop/test/super_tab_discovery_test.dart@@ -31,7 +31,7 @@ class _Catalog {String path, {Map<String, dynamic>? body,}) async {- if (Uri.parse(path).path != '/api/super-tabs') {+ if (Uri.parse(path).path != '/api/super-tabs/list') {return server.request(method, path, body: body);}expectSync(method, 'GET');@@ -537,7 +537,7 @@ void main() {await _close(app, tab);expect(app.closedSuperTabs, hasLength(1));store.values['super_tab.hidden.other'] = '["${tab.superTabId}"]';- catalog.fail = '/api/super-tabs';+ catalog.fail = '/api/super-tabs/list';app.currentUser = const CurrentUserProfile(id: 'other',email: '[email protected]',@@ -696,7 +696,7 @@ void main() {() async {final catalog = _Catalog()..tabs.add({'id': '1123456789abcdef01234567', 'name': 'Build'})- ..fail = '/api/super-tabs?after=0123456789abcdef01234567';+ ..fail = '/api/super-tabs/list?after=0123456789abcdef01234567';final app = _computer(catalog, MemoryStore());await app.superTabs.refreshTabs();expect(app.swarms.where((s) => s.isSuperTab), isEmpty);@@ -764,7 +764,7 @@ void main() {testWidgets('sign-in discovers tabs and retries while the app stays open', (tester,) async {- final catalog = _Catalog()..fail = '/api/super-tabs';+ final catalog = _Catalog()..fail = '/api/super-tabs/list';final seen = <List<SuperTabListing>>[];final client = SuperTabClient(storage: MemoryStore(),diff --git a/desktop/test/super_tab_dormant_groups_test.dart b/desktop/test/super_tab_dormant_groups_test.dartnew file mode 100644index 000000000..9da654e83--- /dev/null+++ b/desktop/test/super_tab_dormant_groups_test.dart@@ -0,0 +1,231 @@+import 'dart:async';++import 'package:flutter_test/flutter_test.dart';+import 'package:harness/super_tabs/controller.dart';++import 'support/super_tab_fixture.dart';++/// Archived and finished groups leave the active set: they are not in a first+/// load or in changes, and are read on demand+/// (docs/design/2026-10-26-swarm-state-parts.md, sections 4.5 and 5.2).+void main() {+ late ConversationServer server;+ late List<String> reads;++ Map<String, dynamic> group(String id) =>+ (server.state['conversations'] as List)+ .cast<Map<String, dynamic>>()+ .firstWhere((g) => g['id'] == id);++ SuperTabController open({Map<String, dynamic>? initial}) {+ reads = [];+ return SuperTabController(+ tabId: 'tab',+ accountId: 'owner',+ initial: initial ?? const {},+ request: (method, path, {body}) {+ if (method == 'GET' && path.contains('/groups')) reads.add(path);+ return server.request(method, path, body: body);+ },+ save: server.save,+ pollInterval: Duration.zero,+ );+ }++ setUp(() {+ server = ConversationServer();+ (server.state['conversations'] as List)+ ..add({...conversationFixture('old', 'Old work'), 'archived': true})+ ..add({+ ...conversationFixture('finished', 'Finished work'),+ 'dormant': true,+ });+ });++ test('a first load has only active groups; expanding the project reads the others', () async {+ final c = open();+ await c.refresh();+ expect(c.snapshot!.conversation('old'), isNull);+ expect(c.dormantLoaded('lead'), isFalse);+ c.toggleProject('lead');+ await c.loadDormant('lead');+ expect(reads, ['/api/super-tabs/tab/groups?dormant=1&projectId=lead']);+ expect(c.dormantLoaded('lead'), isTrue);+ final old = c.snapshot!.conversation('old')!;+ expect(old.archived, isTrue);+ expect(old.closed, isTrue);+ final finished = c.snapshot!.conversation('finished')!;+ expect(finished.archived, isFalse);+ expect(finished.closed, isTrue);+ expect(c.snapshot!.conversation('offline')!.closed, isFalse);+ // Read once: collapsing and expanding again reads nothing more.+ c+ ..toggleProject('lead')+ ..toggleProject('lead');+ await c.loadDormant('lead');+ expect(reads, hasLength(1));+ });++ test('an earlier page of closed groups is read on demand', () async {+ server.parts.dormantPage = 1;+ final c = open();+ await c.refresh();+ c.toggleProject('lead');+ await c.loadDormant('lead');+ expect(c.hasEarlierDormant('lead'), isTrue);+ final first = c.snapshot!.conversations.where((g) => g.closed).length;+ expect(first, 1);+ await c.loadDormant('lead', earlier: true);+ expect(reads.last, contains('&before='));+ expect(c.hasEarlierDormant('lead'), isFalse);+ expect(c.snapshot!.conversations.where((g) => g.closed), hasLength(2));+ });++ test(+ 'a group archived elsewhere moves to the closed groups with its new data',+ () async {+ final c = open();+ await c.refresh();+ group('offline')['archived'] = true;+ await c.refresh();+ expect(reads, ['/api/super-tabs/tab/groups/offline']);+ final offline = c.snapshot!.conversation('offline')!;+ expect(offline.archived, isTrue);+ expect(offline.closed, isTrue);+ // Reopened: it comes back with the active groups.+ group('offline')['archived'] = false;+ await c.refresh();+ expect(c.snapshot!.conversation('offline')!.closed, isFalse);+ },+ );++ test('a saved selection of a closed group opens it by id', () async {+ final c = open(+ initial: {'tabId': 'tab', 'accountId': 'owner', 'selectedId': 'old'},+ );+ await c.refresh();+ expect(c.selectedId, 'old');+ expect(c.selected!.archived, isTrue);+ expect(reads, contains('/api/super-tabs/tab/groups/old'));+ });++ test('a saved selection of a deleted group falls back to the Lead', () async {+ final c = open(+ initial: {'tabId': 'tab', 'accountId': 'owner', 'selectedId': 'gone'},+ );+ await c.refresh();+ expect(c.selectedId, 'lead');+ });++ test('selecting a closed group not read yet reads it by id', () async {+ final c = open();+ await c.refresh();+ await c.select('finished');+ expect(c.selectedId, 'finished');+ expect(reads, contains('/api/super-tabs/tab/groups/finished'));+ expect(await c.select('gone'), isFalse);+ expect(c.selectedId, 'finished');+ });++ test(+ 'read marks and drafts of a closed group survive opening again',+ () async {+ group('finished')['dormant'] = false;+ group('finished')['lastMessageSequence'] = 4;+ final first = open();+ await first.refresh();+ first.setDraft('finished', 'A last note');+ server.append('Done', conversationId: 'finished');+ await first.refresh();+ await first.loadMessages('finished');+ first.markRead('finished');+ group('finished')['dormant'] = true;+ await first.refresh();+ await first.flush();+ first.dispose();++ final again = open(initial: server.saved);+ await again.refresh();+ await again.flush();+ expect(again.draft('finished'), 'A last note');+ again.toggleProject('lead');+ await again.loadDormant('lead');+ expect(again.unread(again.snapshot!.conversation('finished')!), isFalse);+ },+ );++ test('a reload while closed groups are being read reads them again for the new parts', () async {+ Completer<void>? hold;+ reads = [];+ final c = SuperTabController(+ tabId: 'tab',+ accountId: 'owner',+ request: (method, path, {body}) async {+ if (method == 'GET' && path.contains('/groups')) {+ reads.add(path);+ if (hold case final wait?) await wait.future;+ }+ return server.request(method, path, body: body);+ },+ save: server.save,+ pollInterval: Duration.zero,+ );+ await c.refresh();+ hold = Completer<void>();+ c.toggleProject('lead');+ final stale = c.loadDormant('lead');+ // Who may see what changed meanwhile: the next read loads in full.+ server.parts.epoch++;+ await c.refresh();+ final waiting = hold;+ hold = null;+ waiting.complete();+ await stale;+ // The reload asked for them again by itself: nothing else asks.+ await pumpEventQueue();+ expect(reads.where((p) => p.contains('dormant=1')), hasLength(2));+ expect(c.dormantLoaded('lead'), isTrue);+ expect(c.snapshot!.conversation('old')!.closed, isTrue);+ });++ test('a failed fetch of a closed group still applies the rest of the change read', () async {+ (server.state['conversations'] as List).add(+ conversationFixture('doomed', 'Deleted soon'),+ );+ var failGroup = false;+ reads = [];+ final c = SuperTabController(+ tabId: 'tab',+ accountId: 'owner',+ request: (method, path, {body}) async {+ if (method == 'GET' && path.contains('/groups')) {+ reads.add(path);+ if (failGroup && path.endsWith('/groups/offline')) {+ failGroup = false;+ throw StateError('Connection lost');+ }+ }+ return server.request(method, path, body: body);+ },+ save: server.save,+ pollInterval: Duration.zero,+ );+ await c.refresh();+ expect(c.snapshot!.conversation('doomed'), isNotNull);+ // One change read: a group archived, another deleted. Fetching the+ // archived one fails.+ group('offline')['archived'] = true;+ (server.state['conversations'] as List).removeWhere(+ (g) => (g as Map)['id'] == 'doomed',+ );+ failGroup = true;+ await c.refresh();+ expect(c.snapshot!.conversation('doomed'), isNull);+ expect(c.snapshot!.conversation('offline')!.closed, isTrue);+ // The next poll changes nothing more, and still gets it right.+ await c.refresh();+ expect(c.snapshot!.conversation('doomed'), isNull);+ expect(c.snapshot!.conversation('offline')!.archived, isTrue);+ expect(reads.where((p) => p.endsWith('/groups/offline')), hasLength(2));+ });+}diff --git a/desktop/test/super_tab_launch_test.dart b/desktop/test/super_tab_launch_test.dartindex c23463238..10fcedd93 100644--- a/desktop/test/super_tab_launch_test.dart+++ b/desktop/test/super_tab_launch_test.dart@@ -150,7 +150,7 @@ class SuperTabFixtureConnection extends WsConn {if (type == 'super_tabs') {if (changeAccountOnProjectRead &&payload['method'] == 'GET' &&- payload['path'] == '/api/super-tabs/$tabId') {+ payload['path'] == '/api/super-tabs/$tabId/parts') {app.currentUser = const CurrentUserProfile(id: 'different',email: '[email protected]',diff --git a/desktop/test/super_tab_local_backend_test.dart b/desktop/test/super_tab_local_backend_test.dartnew file mode 100644index 000000000..4cda40afa--- /dev/null+++ b/desktop/test/super_tab_local_backend_test.dart@@ -0,0 +1,142 @@+import 'dart:convert';+import 'dart:io';++import 'package:flutter_test/flutter_test.dart';+import 'package:harness/super_tabs/controller.dart';+import 'package:harness/super_tabs/model.dart';+import 'package:harness/super_tabs/parts.dart';++/// The Swarm client against a real, local, isolated backend (#1726 group 4,+/// check 2). Opt-in: it runs only with `SWARM_LOCAL_BACKEND` set to a+/// loopback backend started as in the group 3 recipe (fake SSO tokens, local+/// MongoDB and Redis), and `SWARM_LOCAL_TAB` naming a Swarm both test people+/// belong to. It never reaches any other host.+///+/// `SWARM_LOCAL_BACKEND=http://127.0.0.1:18085 SWARM_LOCAL_TAB=ID \+/// flutter test test/super_tab_local_backend_test.dart`+void main() {+ final backend = Platform.environment['SWARM_LOCAL_BACKEND'];+ final tabId = Platform.environment['SWARM_LOCAL_TAB'];+ final skip = backend == null || tabId == null+ ? 'needs SWARM_LOCAL_BACKEND and SWARM_LOCAL_TAB'+ : Uri.parse(backend).host != '127.0.0.1'+ ? 'SWARM_LOCAL_BACKEND must be a loopback backend'+ : null;+ const owner = 'local-owner-token', peer = 'local-peer-token';++ /// Response bytes by read kind, in order.+ final bytes = <String, List<int>>{};++ /// The last first load answered.+ Map<String, dynamic>? firstLoad;++ Future<Map<String, dynamic>> call(+ String token,+ String method,+ String path, {+ Map<String, dynamic>? body,+ }) async {+ final client = HttpClient();+ try {+ final request = await client.openUrl(method, Uri.parse('$backend$path'));+ request.headers+ ..set('authorization', 'Bearer $token')+ ..contentType = ContentType.json;+ if (body != null) request.write(jsonEncode(body));+ final response = await request.close();+ final text = await response.transform(utf8.decoder).join();+ final kind = Uri.parse(path).pathSegments.length > 3+ ? Uri.parse(path).pathSegments[3]+ : 'tab';+ (bytes[kind] ??= []).add(utf8.encode(text).length);+ final answer = jsonDecode(text) as Map<String, dynamic>;+ if (answer['success'] != true) {+ final error = superTabMap(answer['error']);+ throw SuperTabFailure(+ error['code'] as String? ?? 'ERROR',+ error['message'] as String? ?? 'Failed.',+ statusCode: response.statusCode,+ );+ }+ final data = superTabMap(answer['data']);+ if (kind == 'parts') firstLoad = data;+ return data;+ } finally {+ client.close();+ }+ }++ test('a Swarm opens with one first load, then reads only what another client changed', () async {+ final c = SuperTabController(+ tabId: tabId!,+ accountId: 'local-owner',+ request: (method, path, {body}) => call(owner, method, path, body: body),+ save: (_) async {},+ pollInterval: Duration.zero,+ );+ await c.refresh();+ expect(c.error, isNull);+ final lead = c.snapshot!.projects.first.leadConversationId;+ final before = c.snapshot!.conversation(lead)!.lastMessageSequence;++ // An idle poll: nothing changed but what the overlap sends again.+ await c.refresh();+ expect(c.error, isNull);++ // Another client posts, as the second person.+ final text = 'From the second client ${DateTime.now().toIso8601String()}';+ await call(+ peer,+ 'POST',+ '/api/super-tabs/$tabId/commands',+ body: {+ 'operationId': superTabOperationId(),+ 'command': {+ 'type': 'message.send',+ 'conversationId': lead,+ 'text': text,+ 'replyTo': null,+ 'recipientIds': <String>[],+ },+ },+ );+ await c.refresh();+ expect(c.error, isNull);+ expect(+ c.snapshot!.conversation(lead)!.lastMessageSequence,+ greaterThan(before),+ );+ await c.loadMessages(lead);+ expect(c.messages(lead).map((m) => m.text), contains(text));++ // The old whole-Swarm read is refused for old clients.+ Object? old;+ try {+ await call(owner, 'GET', '/api/super-tabs/$tabId');+ } catch (failure) {+ old = failure;+ }+ expect(+ old,+ isA<SuperTabFailure>()+ .having((f) => f.statusCode, 'status', 426)+ .having((f) => f.code, 'code', 'UPDATE_REQUIRED'),+ );++ // What a poll costs now, against today's full read of this Swarm:+ // the old route sent the whole visible state every 3 s.+ final state = jsonEncode({+ 'success': true,+ 'data': {+ 'revision': 0,+ 'state': SuperTabParts.firstLoad(firstLoad!).state,+ },+ });+ // ignore: avoid_print+ print(+ 'bytes: first load ${bytes['parts']}, change reads ${bytes['changes']}, '+ 'today\'s full read of the same Swarm ~${utf8.encode(state).length}',+ );+ c.dispose();+ }, skip: skip);+}diff --git a/desktop/test/super_tab_machine_freshness_test.dart b/desktop/test/super_tab_machine_freshness_test.dartindex 1c8568a51..94c84f875 100644--- a/desktop/test/super_tab_machine_freshness_test.dart+++ b/desktop/test/super_tab_machine_freshness_test.dart@@ -819,7 +819,7 @@ void main() {});test(- 'records how long a read took and its revision, nothing it said',+ 'records how long a read took, its kind and last change, nothing it said',() async {final server = ConversationServer();server.state['name'] = 'PRIVATE_SWARM_NAME';@@ -829,7 +829,10 @@ void main() {expect(read,matches(- RegExp(r'^debug swarm state read in \d+ ms \(revision \d+\)$'),+ RegExp(+ r'^debug swarm state read in \d+ ms '+ r'\((first load|changes), last changed \d+\)$',+ ),),);expect(log.lines.join('\n'), isNot(contains('PRIVATE')));diff --git a/desktop/test/super_tab_mentions_test.dart b/desktop/test/super_tab_mentions_test.dartindex f61604f5b..21b716c2e 100644--- a/desktop/test/super_tab_mentions_test.dart+++ b/desktop/test/super_tab_mentions_test.dart@@ -547,7 +547,8 @@ void main() {var counted = 0;final client = SuperTabClient(storage: MemoryStore(),- transport: (method, path, {body}) async => path == '/api/super-tabs'+ transport: (method, path, {body}) async =>+ path == '/api/super-tabs/list'? {'tabs': [{'id': 'tab', 'name': 'Pilot'},@@ -589,7 +590,7 @@ void main() {final client = SuperTabClient(storage: MemoryStore(),transport: (method, path, {body}) async {- if (path == '/api/super-tabs') {+ if (path == '/api/super-tabs/list') {return {'tabs': [{'id': 'gone', 'name': 'Older'},diff --git a/desktop/test/super_tab_message_paging_test.dart b/desktop/test/super_tab_message_paging_test.dartnew file mode 100644index 000000000..059040b93--- /dev/null+++ b/desktop/test/super_tab_message_paging_test.dart@@ -0,0 +1,54 @@+import 'package:flutter_test/flutter_test.dart';++import 'support/super_tab_fixture.dart';++/// Older history pages by (sequence, id): messages from before the parts+/// migration can share a sequence, and a page edge inside such a run must not+/// skip any (docs/design/2026-10-26-swarm-state-parts.md, section 4.6).+void main() {+ test(+ 'older pages continue after the last message read, ties included',+ () async {+ final server = ConversationServer()..messagePage = 2;+ for (final text in ['one', 'two', 'three', 'four', 'five']) {+ server.append(text);+ }+ // One old command posted three of them: they share its sequence.+ for (final m in server.messages.skip(1).take(3)) {+ m['sequence'] = 2;+ }+ final reads = <String>[];+ final paging = server.controller();+ await paging.refresh();+ expect(paging.messages('lead').map((m) => m.text), ['four', 'five']);+ expect(paging.hasOlder('lead'), isTrue);+ server.onRead = reads.add;+ await paging.loadMessages('lead', older: true);+ await paging.loadMessages('lead', older: true);+ expect(paging.hasOlder('lead'), isFalse);+ expect(paging.messages('lead').map((m) => m.text), [+ 'one',+ 'two',+ 'three',+ 'four',+ 'five',+ ]);+ expect(reads.first, endsWith('messages?before=2&beforeId=message-4'));+ },+ );++ test('a new message is read after the newest one', () async {+ final server = ConversationServer()..append('one');+ final c = server.controller();+ await c.refresh();+ final reads = <String>[];+ server.onRead = reads.add;+ server.append('two');+ await c.refresh();+ expect(+ reads.where((p) => p.contains('/messages')).first,+ endsWith('messages?after=1'),+ );+ expect(c.messages('lead').map((m) => m.text), ['one', 'two']);+ });+}diff --git a/desktop/test/super_tab_parts_reading_test.dart b/desktop/test/super_tab_parts_reading_test.dartnew file mode 100644index 000000000..d3dfaa373--- /dev/null+++ b/desktop/test/super_tab_parts_reading_test.dart@@ -0,0 +1,252 @@+import 'package:flutter_test/flutter_test.dart';++import 'support/memory_key_value_store.dart';++import 'package:harness/super_tabs/client.dart';+import 'package:harness/super_tabs/controller.dart';++import 'support/super_tab_fixture.dart';++/// Desktop and the web read a Swarm once, then only what changed since+/// (docs/design/2026-10-26-swarm-state-parts.md, section 5.2).+void main() {+ late ConversationServer server;+ late List<String> reads;++ SuperTabController open() {+ reads = [];+ return SuperTabController(+ tabId: 'tab',+ accountId: 'owner',+ request: (method, path, {body}) {+ if (method == 'GET' && !path.contains('/messages')) reads.add(path);+ return server.request(method, path, body: body);+ },+ save: server.save,+ pollInterval: Duration.zero,+ );+ }++ setUp(() => server = ConversationServer());++ test(+ 'opens with one first load, then reads changes since its cursor',+ () async {+ final c = open();+ await c.refresh();+ expect(reads, ['/api/super-tabs/tab/parts']);+ expect(c.snapshot!.conversation('offline')!.lastMessageSequence, 0);++ // Another client posts.+ server.append('From another client', conversationId: 'offline');+ await c.refresh();+ expect(reads.last, startsWith('/api/super-tabs/tab/changes?cursor='));+ expect(reads.where((p) => p.endsWith('/parts')), hasLength(1));+ expect(c.snapshot!.conversation('offline')!.lastMessageSequence, 1);+ expect(c.lastChangedAt, greaterThan(0));+ },+ );++ test(+ 'each change read starts at the cursor the last read returned',+ () async {+ final c = open();+ await c.refresh();+ final first = server.parts.reads.last;+ expect(first, '/api/super-tabs/tab/parts');+ await c.refresh();+ await c.refresh();+ final cursors = [+ for (final path in reads.skip(1))+ Uri.parse(path).queryParameters['cursor'],+ ];+ expect(cursors, hasLength(2));+ // The second change read starts later than the first: the cursor moved.+ expect(cursors[0], isNot(cursors[1]));+ },+ );++ test('a reload answer reads the Swarm again in full', () async {+ final c = open();+ await c.refresh();+ server.parts.epoch++;+ (server.state['conversations'] as List).add(+ conversationFixture('private', 'Ken and the PM'),+ );+ await c.refresh();+ expect(reads, [+ '/api/super-tabs/tab/parts',+ startsWith('/api/super-tabs/tab/changes?cursor='),+ '/api/super-tabs/tab/parts',+ ]);+ expect(c.snapshot!.conversation('private'), isNotNull);+ expect(c.error, isNull);+ });++ test(+ 'a refused change read reads in full; a refused first load closes the tab',+ () async {+ final c = open();+ await c.refresh();+ var refuse = 1;+ final inner = server.request;+ final closing = SuperTabController(+ tabId: 'tab',+ accountId: 'owner',+ request: (method, path, {body}) {+ if (method == 'GET' && !path.contains('/messages')) reads.add(path);+ if (path.contains('/changes') && refuse-- > 0) {+ throw const SuperTabFailure('NOT_FOUND', 'Gone.', statusCode: 404);+ }+ if (path.endsWith('/parts') && reads.length > 2) {+ throw const SuperTabFailure(+ 'FORBIDDEN',+ 'No access.',+ statusCode: 403,+ );+ }+ return inner(method, path, body: body);+ },+ save: server.save,+ pollInterval: Duration.zero,+ );+ reads = [];+ await closing.refresh();+ await closing.refresh();+ expect(reads, [+ '/api/super-tabs/tab/parts',+ startsWith('/api/super-tabs/tab/changes?cursor='),+ '/api/super-tabs/tab/parts',+ ]);+ expect(closing.accessRevoked, isTrue);+ expect(c.accessRevoked, isFalse);+ },+ );++ test(+ 'a removed group leaves the snapshot and its local state goes',+ () async {+ final c = open();+ await c.refresh();+ c.setDraft('offline', 'An unsent note');+ c.markRead('offline');+ (server.state['conversations'] as List).removeWhere(+ (g) => (g as Map)['id'] == 'offline',+ );+ await c.refresh();+ await c.flush();+ expect(c.snapshot!.conversation('offline'), isNull);+ expect(c.draft('offline'), '');+ expect(server.saved!['drafts'], isNot(contains('offline')));+ },+ );++ test('a command is followed by one change read', () async {+ final c = open();+ await c.refresh();+ reads.clear();+ c.setDraft('lead', 'Hello');+ await c.send();+ expect(reads, [startsWith('/api/super-tabs/tab/changes?cursor=')]);+ expect(c.snapshot!.conversation('lead')!.lastMessageSequence, 1);+ });++ test('nothing reads the whole Swarm any more', () async {+ final c = open();+ await c.refresh();+ await c.refresh();+ expect(reads, isNot(contains('/api/super-tabs/tab')));+ expect(c.error, isNull);+ });++ test('a one-off read of a Swarm is one first load', () async {+ final paths = <String>[];+ final client = SuperTabClient(+ storage: MemoryKeyValueStore(),+ discoveryInterval: Duration.zero,+ transport: (method, path, {body}) {+ paths.add(path);+ return server.request(method, path, body: body);+ },+ )..bind('owner');+ final snapshot = await client.readSnapshot('tab');+ expect(paths, ['/api/super-tabs/tab/parts']);+ expect(snapshot.conversation('offline')!.title, 'Offline editing');+ client.dispose();+ });++ test(+ 'an answer that does not read is not kept: the next read loads in full',+ () async {+ final c = open();+ await c.refresh();+ var broken = true;+ final inner = server.request;+ final reading = SuperTabController(+ tabId: 'tab',+ accountId: 'owner',+ request: (method, path, {body}) async {+ if (method == 'GET' && !path.contains('/messages')) reads.add(path);+ final answer = await inner(method, path, body: body);+ if (path.contains('/changes') && broken) {+ broken = false;+ return {...answer, 'cursor': null};+ }+ return answer;+ },+ save: server.save,+ pollInterval: Duration.zero,+ );+ reads = [];+ await reading.refresh();+ await reading.refresh();+ expect(reading.error, isNotNull);+ await reading.refresh();+ expect(reads, [+ '/api/super-tabs/tab/parts',+ startsWith('/api/super-tabs/tab/changes?cursor='),+ '/api/super-tabs/tab/parts',+ ]);+ expect(reading.error, isNull);+ },+ );++ test('a first load of another Swarm is not kept', () async {+ server.state['id'] = 'another';+ final c = open();+ await c.refresh();+ expect(c.snapshot, isNull);+ expect(c.error, isNotNull);+ server.state['id'] = 'tab';+ await c.refresh();+ expect(reads.last, '/api/super-tabs/tab/parts');+ expect(c.snapshot!.id, 'tab');+ });++ test('a private conversation the reader leaves is gone after the reload', () async {+ (server.state['conversations'] as List).add({+ ...conversationFixture('private', 'Ken and the PM'),+ 'audience': {+ 'people': [+ {'id': 'owner', 'generation': 'g1'},+ ],+ },+ });+ server.append('Just us', conversationId: 'private');+ final c = open();+ await c.refresh();+ await c.select('private');+ await c.loadMessages('private');+ expect(c.messages('private').single.text, 'Just us');+ // The audience changed: the server moves the epoch and no longer sends it.+ (server.state['conversations'] as List).removeWhere(+ (g) => (g as Map)['id'] == 'private',+ );+ server.messages.removeWhere((m) => m['conversationId'] == 'private');+ server.parts.epoch++;+ await c.refresh();+ expect(c.snapshot!.conversation('private'), isNull);+ expect(c.messages('private'), isEmpty);+ expect(c.selectedId, 'lead');+ });+}diff --git a/desktop/test/super_tab_parts_test.dart b/desktop/test/super_tab_parts_test.dartnew file mode 100644index 000000000..9bef4edd8--- /dev/null+++ b/desktop/test/super_tab_parts_test.dart@@ -0,0 +1,345 @@+import 'dart:convert';+import 'dart:io';++import 'package:flutter_test/flutter_test.dart';+import 'package:harness/super_tabs/model.dart';+import 'package:harness/super_tabs/parts.dart';++/// The design's section 4 examples, recorded (test/super_tab_read_fixtures).+Map<String, dynamic> recorded(String name) => jsonDecode(+ File('test/super_tab_read_fixtures/$name.json').readAsStringSync(),+) as Map<String, dynamic>;++Map<String, dynamic> group(Map<String, dynamic> state, String id) =>+ (state['conversations'] as List).cast<Map<String, dynamic>>().firstWhere(+ (g) => g['id'] == id,+ );++void main() {+ test('a first load reassembles the state the screens read', () {+ final parts = SuperTabParts.firstLoad(recorded('first_load'));+ final state = parts.state;+ final snapshot = SuperTabSnapshot.fromJson(state);++ expect(parts.cursor, 'eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjozfQ');+ expect(parts.epoch, 3);+ expect(parts.lastChangedAt, 1793010101002);+ expect(snapshot.id, 'c51479bd73b59e58176ad9e4');+ expect(snapshot.name, 'openharness');+ expect(snapshot.leadsConversationId, 'leads');+ expect(snapshot.people.single.email, '[email protected]');+ expect(snapshot.projects.single.leadConversationId, 'lead5701');+ expect(snapshot.conversations.map((g) => g.id), [+ 'leads',+ 'lead5701',+ 'aeef',+ ]);+ expect(snapshot.conversation('aeef')!.lastMessageSequence, 219804);+ expect(snapshot.agents.map((a) => a.displayName), ['River', 'Hugo']);+ expect(snapshot.localModels!.grid, 'swarm-c514');+ expect(snapshot.mentionsWaiting, 0);+ expect(state['githubApp'], true);+ // The machine and its values worked out at read time.+ expect(snapshot.pool('7835')!['teamWork'], {'allowed': true});+ expect(snapshot.pool('7835')!['availableSlots'], 3);+ });++ test(+ 'derived values overlay the agents; a null decision keeps the stored one',+ () {+ final state = SuperTabParts.firstLoad(recorded('first_load')).state;+ final agents = (state['agents'] as List).cast<Map<String, dynamic>>();+ final hugo = agents.firstWhere((a) => a['id'] == '0540');+ final river = agents.firstWhere((a) => a['id'] == '0fcb');+ expect(hugo['downSince'], '2026-10-26T10:19:51.474Z');+ expect(hugo['workDecision'], 'awaiting');+ expect(river['downSince'], isNull);+ expect(river.containsKey('workDecision'), isFalse);++ final changed = recorded('changes');+ final parts = SuperTabParts.firstLoad(recorded('first_load'))+ ..apply(changed);+ final after = (parts.state['agents'] as List)+ .cast<Map<String, dynamic>>()+ .firstWhere((a) => a['id'] == '0540');+ // Derived says nothing more about the decision: the stored one stands.+ expect(after['workDecision'], 'release');+ expect(after['downSince'], isNull);+ },+ );++ test('a first load of another format is refused', () {+ expect(+ () => SuperTabParts.firstLoad({...recorded('first_load'), 'format': 1}),+ throwsFormatException,+ );+ expect(+ () => SuperTabParts.firstLoad({'revision': 4, 'state': {}}),+ throwsFormatException,+ );+ });++ test(+ 'changes replace newer parts, drop tombstones and move dormant groups out',+ () {+ final parts = SuperTabParts.firstLoad(recorded('first_load'))+ ..addDormant([]);+ // 77ab and 9c1d were read earlier: active then.+ parts.apply({+ ...recorded('changes'),+ 'derived': recorded('first_load')['derived'],+ 'groups': [+ {+ 'key': '77ab',+ 'version': 214000,+ 'changedAt': 1793010100000,+ 'data': {+ 'id': '77ab',+ 'projectId': '5701',+ 'title': 'Gone soon',+ 'agentIds': <String>[],+ 'archived': false,+ 'brief': '',+ 'checks': <dynamic>[],+ 'assignment': null,+ 'lastMessageSequence': 0,+ },+ },+ {+ 'key': '9c1d',+ 'version': 214001,+ 'changedAt': 1793010100000,+ 'data': {+ 'id': '9c1d',+ 'projectId': '5701',+ 'title': 'Finished',+ 'agentIds': <String>[],+ 'archived': false,+ 'brief': '',+ 'checks': <dynamic>[],+ 'assignment': null,+ 'lastMessageSequence': 5,+ },+ },+ ],+ 'machines': <dynamic>[],+ });+ expect(group(parts.state, '77ab')['title'], 'Gone soon');++ final change = parts.apply(recorded('changes'));+ final state = parts.state;+ expect(change.changed, isTrue);+ expect(change.removedGroups, {'77ab'});+ expect(change.dormantGroups, {'9c1d'});+ expect(parts.cursor, 'eyJ2IjoyLCJ0IjoxNzkzMDEwMDc3Mzc1LCJlIjozfQ');+ expect(parts.lastChangedAt, 1793010106120);+ expect(group(state, 'aeef')['lastMessageSequence'], 219810);+ expect((state['conversations'] as List).map((g) => g['id']), [+ 'leads',+ 'lead5701',+ 'aeef',+ // Its data is kept, marked dormant, after the active groups.+ '9c1d',+ ]);+ expect(group(state, '9c1d')['dormant'], true);+ expect(SuperTabSnapshot.fromJson(state).pool('7835')!['paused'], true);+ expect(+ SuperTabSnapshot.fromJson(state).pool('7835')!['availableSlots'],+ 2,+ );+ expect(state['mentionsWaiting'], 1);+ },+ );++ test('the overlap sends parts again: equal versions change nothing', () {+ final parts = SuperTabParts.firstLoad(recorded('first_load'));+ expect(parts.apply(recorded('changes')).changed, isTrue);+ final before = jsonEncode(parts.state);+ final again = parts.apply(recorded('changes'));+ expect(again.changed, isFalse);+ expect(again.removedGroups, isEmpty);+ expect(again.dormantGroups, isEmpty);+ expect(jsonEncode(parts.state), before);+ });++ test(+ 'an older copy never replaces a newer one, nor brings a removed part back',+ () {+ final parts = SuperTabParts.firstLoad(recorded('first_load'));+ final older = {+ ...recorded('changes'),+ 'derived': recorded('first_load')['derived'],+ 'groups': [+ {+ 'key': 'aeef',+ 'version': 214000,+ 'changedAt': 1793010000000,+ 'data': {...group(parts.state, 'aeef'), 'title': 'Stale'},+ },+ ],+ 'machines': <dynamic>[],+ };+ expect(parts.apply(older).changed, isFalse);+ expect(group(parts.state, 'aeef')['title'], '1726 G1: design doc');++ parts.apply({+ ...older,+ 'groups': [+ {+ 'key': 'aeef',+ 'version': 214050,+ 'changedAt': 1793010200000,+ 'deleted': true,+ },+ ],+ });+ expect(+ (parts.state['conversations'] as List).map((g) => g['id']),+ isNot(contains('aeef')),+ );+ parts.apply(older);+ expect(+ (parts.state['conversations'] as List).map((g) => g['id']),+ isNot(contains('aeef')),+ );+ },+ );++ test(+ 'a dormant group that changes again comes back to the active groups',+ () {+ final parts = SuperTabParts.firstLoad(recorded('first_load'));+ final dormant = recorded('dormant_groups');+ expect(parts.addDormant(dormant['groups'] as List).changed, isTrue);+ expect(group(parts.state, '9c1d')['dormant'], true);+ expect(parts.isDormant('9c1d'), isTrue);++ final back = {+ ...(dormant['groups'] as List).single as Map<String, dynamic>,+ 'version': 214100,+ };+ back['data'] = {+ ...back['data'] as Map,+ 'dormant': false,+ 'archived': false,+ };+ parts.apply({+ ...recorded('changes'),+ 'groups': [back],+ });+ expect(parts.isDormant('9c1d'), isFalse);+ expect(group(parts.state, '9c1d')['dormant'], false);+ expect(+ (parts.state['conversations'] as List).map((g) => g['id']).last,+ '9c1d',+ );+ },+ );++ test('a dormant list cannot replace a group held at a newer version', () {+ final parts = SuperTabParts.firstLoad(recorded('first_load'));+ final stale = {+ 'key': 'aeef',+ 'version': 1,+ 'changedAt': 1,+ 'data': {...group(parts.state, 'aeef'), 'dormant': true},+ };+ expect(parts.addDormant([stale]).changed, isFalse);+ expect(parts.isDormant('aeef'), isFalse);+ });++ test('a new part is listed after the ones read before it', () {+ final parts = SuperTabParts.firstLoad(recorded('first_load'));+ parts.apply({+ ...recorded('changes'),+ 'head': {+ 'key': 'head',+ 'version': 214060,+ 'changedAt': 1793010106000,+ 'data': {+ ...(recorded('first_load')['head'] as Map)['data'] as Map,+ 'name': 'Renamed',+ },+ },+ 'members': [+ {+ 'key': '6a87',+ 'version': 214061,+ 'changedAt': 1793010106000,+ 'data': {+ 'id': '6a87',+ 'email': '[email protected]',+ 'role': 'collaborator',+ },+ },+ ],+ });+ final snapshot = SuperTabSnapshot.fromJson(parts.state);+ expect(snapshot.name, 'Renamed');+ expect(snapshot.people.map((p) => p.id), ['6a86', '6a87']);+ });++ test('what it keeps reads back as the same store', () {+ final parts = SuperTabParts.firstLoad(recorded('first_load'))+ ..apply(recorded('changes'))+ ..addDormant(recorded('dormant_groups')['groups'] as List);+ final kept = SuperTabParts.fromJson(+ jsonDecode(jsonEncode(parts.toJson())) as Map<String, dynamic>,+ );+ expect(jsonEncode(kept.state), jsonEncode(parts.state));+ expect(kept.cursor, parts.cursor);+ expect(kept.epoch, parts.epoch);+ expect(kept.lastChangedAt, parts.lastChangedAt);+ // Versions are kept too: the overlap changes nothing on the copy.+ expect(kept.apply(recorded('changes')).changed, isFalse);+ });++ test(+ 'a group a stub closed takes its data read by id at the same version',+ () {+ final parts = SuperTabParts.firstLoad(recorded('first_load'));+ parts.apply({+ ...recorded('changes'),+ 'groups': [+ {+ 'key': 'aeef',+ 'version': 214100,+ 'changedAt': 1793010200000,+ 'dormant': true,+ },+ ],+ });+ // Held from before it closed: stale until read again.+ expect(group(parts.state, 'aeef')['archived'], false);+ final read = {+ 'key': 'aeef',+ 'version': 214100,+ 'changedAt': 1793010200000,+ 'data': {+ ...group(parts.state, 'aeef'),+ 'archived': true,+ 'dormant': true,+ },+ };+ expect(parts.addDormant([read]).changed, isTrue);+ expect(group(parts.state, 'aeef')['archived'], true);+ // Read once: the same copy again changes nothing.+ expect(parts.addDormant([read]).changed, isFalse);+ },+ );++ test(+ 'a Swarm with no change yet reads (the contract allows lastChangedAt null)',+ () {+ final parts = SuperTabParts.firstLoad({+ ...recorded('first_load'),+ 'lastChangedAt': null,+ });+ expect(parts.lastChangedAt, 0);+ parts.apply({...recorded('changes'), 'lastChangedAt': null});+ expect(parts.lastChangedAt, 0);+ parts.apply(recorded('changes'));+ expect(parts.lastChangedAt, 1793010106120);+ },+ );+}diff --git a/desktop/test/super_tab_picker_test.dart b/desktop/test/super_tab_picker_test.dartindex 9d1fbd158..9c07386c4 100644--- a/desktop/test/super_tab_picker_test.dart+++ b/desktop/test/super_tab_picker_test.dart@@ -13,6 +13,7 @@ import 'package:harness/shortcuts/app_keymap.dart';import 'package:harness/state/harness_placement.dart';import 'package:harness/state/new_harness.dart';import 'package:harness/state/swarm_catalog.dart';+import 'package:harness/super_tabs/project_sidebar.dart';import 'package:harness/widgets/new_harness_form.dart';import 'package:harness/widgets/swarm_switcher.dart';@@ -126,8 +127,24 @@ void main() {await tester.tap(find.byTooltip('Conversations'));await tester.pumpAndSettle();}- // The teammate's machine is not online here, so it sits under the closed "Offline" disclosure.+ // The sidebar builds only the rows near its view: at a large text size the+ // Machines group starts below it.+ final sidebar = find+ .descendant(+ of: find.byType(ProjectSidebar),+ matching: find.byType(Scrollable),+ )+ .first;+ // The teammate's machine is not online here, so it may sit under the closed "Offline" disclosure.final offline = find.byKey(const ValueKey('super-machines-offline'));+ for (+ var i = 0;+ i < 50 && machine.evaluate().isEmpty && offline.evaluate().isEmpty;+ i+++ ) {+ await tester.drag(sidebar, const Offset(0, -100));+ await tester.pumpAndSettle();+ }if (machine.evaluate().isEmpty && offline.evaluate().isNotEmpty) {await tester.ensureVisible(offline);await tester.tap(offline);diff --git a/desktop/test/super_tab_pm_chat_local_test.dart b/desktop/test/super_tab_pm_chat_local_test.dartnew file mode 100644index 000000000..82bf96d00--- /dev/null+++ b/desktop/test/super_tab_pm_chat_local_test.dart@@ -0,0 +1,176 @@+import 'dart:convert';+import 'dart:io';++import 'package:flutter_test/flutter_test.dart';+import 'package:harness/super_tabs/controller.dart';+import 'package:harness/super_tabs/model.dart';++/// Each person's private chat with the Product Manager, against a real, local,+/// isolated backend. Opt-in: it runs only with `SWARM_LOCAL_BACKEND` set to a+/// loopback backend started as in the local backend recipe (fake SSO tokens,+/// local MongoDB and Redis), `SWARM_LOCAL_TAB` naming a Swarm both test people+/// belong to, and `SWARM_LOCAL_LEAD` its Lead agent, on a machine of the+/// owner's. It never reaches any other host.+///+/// `SWARM_LOCAL_BACKEND=http://127.0.0.1:18085 SWARM_LOCAL_TAB=ID \+/// SWARM_LOCAL_LEAD=AGENT flutter test test/super_tab_pm_chat_local_test.dart`+void main() {+ final backend = Platform.environment['SWARM_LOCAL_BACKEND'];+ final tabId = Platform.environment['SWARM_LOCAL_TAB'];+ final lead = Platform.environment['SWARM_LOCAL_LEAD'];+ final skip = backend == null || tabId == null || lead == null+ ? 'needs SWARM_LOCAL_BACKEND, SWARM_LOCAL_TAB and SWARM_LOCAL_LEAD'+ : Uri.parse(backend).host != '127.0.0.1'+ ? 'SWARM_LOCAL_BACKEND must be a loopback backend'+ : null;+ const owner = 'local-owner-token', peer = 'local-peer-token';++ Future<Map<String, dynamic>> call(+ String token,+ String method,+ String path, {+ Map<String, dynamic>? body,+ }) async {+ final client = HttpClient();+ try {+ final request = await client.openUrl(method, Uri.parse('$backend$path'));+ request.headers+ ..set('authorization', 'Bearer $token')+ ..contentType = ContentType.json;+ if (body != null) request.write(jsonEncode(body));+ final response = await request.close();+ final answer = jsonDecode(+ await response.transform(utf8.decoder).join(),+ ) as Map<String, dynamic>;+ if (answer['success'] != true) {+ final error = superTabMap(answer['error']);+ throw SuperTabFailure(+ error['code'] as String? ?? 'ERROR',+ error['message'] as String? ?? 'Failed.',+ statusCode: response.statusCode,+ );+ }+ return superTabMap(answer['data']);+ } finally {+ client.close();+ }+ }++ SuperTabController person(String token, String accountId) =>+ SuperTabController(+ tabId: tabId!,+ accountId: accountId,+ request: (method, path, {body}) =>+ call(token, method, path, body: body),+ save: (_) async {},+ pollInterval: Duration.zero,+ );++ Future<Object?> refusal(Future<void> Function() read) async {+ try {+ await read();+ } catch (failure) {+ return failure;+ }+ return null;+ }++ test("each person's chat reaches the Lead, the Lead's reply reaches only that person", () async {+ // Each person's account id, as the backend named them on first use.+ final members = await call(peer, 'GET', '/api/super-tabs/$tabId/parts');+ String idOf(String email) =>+ [+ for (final member in members['members'] as List)+ if ((member as Map)['data']['email'] == email) member['key'],+ ].single+ as String;+ final peerId = idOf('[email protected]');+ final ken = person(peer, peerId);+ final secondWindow = person(peer, peerId);+ final boss = person(owner, idOf('[email protected]'));+ addTearDown(ken.dispose);+ addTearDown(secondWindow.dispose);+ addTearDown(boss.dispose);+ await ken.refresh();+ await secondWindow.refresh();+ await boss.refresh();+ expect(ken.error, isNull);+ final project = ken.snapshot!.projects.first.id;++ // Two windows open the chat: one conversation, the Lead in it.+ expect(await ken.openPmChat(project), isTrue);+ expect(await secondWindow.openPmChat(project), isTrue);+ final chat = ken.pmChat(project)!;+ expect(secondWindow.selectedId, chat.id);+ expect(chat.audience, [peerId]);+ expect(chat.agentIds, contains(lead));+ expect(chat.title, 'peer');+ expect(await boss.openPmChat(project), isTrue);+ final bossChat = boss.pmChat(project)!;+ expect(bossChat.id, isNot(chat.id));++ // The person writes; the message is delivered to the Lead.+ final ask = 'Which build should I try? ${DateTime.now().toIso8601String()}';+ await ken.select(chat.id);+ ken.setDraft(chat.id, ask);+ expect(await ken.send(), isNotNull);+ await ken.loadMessages(chat.id);+ final asked = ken.messages(chat.id).firstWhere((m) => m.text == ask);+ expect(asked.deliveries.map((d) => d['agentId']), [lead]);++ // The Lead answers there, as its host posts for it.+ final answer = 'Try build 42. ${DateTime.now().toIso8601String()}';+ await call(+ owner,+ 'POST',+ '/api/super-tabs/$tabId/commands',+ body: {+ 'operationId': superTabOperationId(),+ 'asAgentId': lead,+ 'command': {+ 'type': 'message.send',+ 'conversationId': chat.id,+ 'text': answer,+ 'replyTo': asked.id,+ 'recipientIds': <String>[],+ },+ },+ );+ await ken.refresh();+ expect(ken.unread(ken.pmChat(project)!), isTrue);+ await ken.loadMessages(chat.id);+ expect(ken.messages(chat.id).map((m) => m.text), contains(answer));++ // Nobody else reads it: not the Swarm's owner, not even by its id.+ await boss.refresh();+ expect(boss.snapshot!.conversation(chat.id), isNull);+ expect(+ await refusal(+ () => call(+ owner,+ 'GET',+ '/api/super-tabs/$tabId/conversations/${chat.id}/messages',+ ),+ ),+ isA<SuperTabFailure>(),+ );+ expect(+ await refusal(+ () => call(owner, 'GET', '/api/super-tabs/$tabId/groups/${chat.id}'),+ ),+ isA<SuperTabFailure>().having((f) => f.statusCode, 'status', 404),+ );+ expect(ken.snapshot!.conversation(bossChat.id), isNull);++ // The Lead reads both people's chats.+ final asLead = await call(+ owner,+ 'GET',+ '/api/super-tabs/$tabId/parts?asAgentId=$lead',+ );+ final seen = [+ for (final group in asLead['groups'] as List) (group as Map)['key'],+ ];+ expect(seen, containsAll([chat.id, bossChat.id]));+ }, skip: skip);+}diff --git a/desktop/test/super_tab_pm_chat_test.dart b/desktop/test/super_tab_pm_chat_test.dartnew file mode 100644index 000000000..b0f5bcd77--- /dev/null+++ b/desktop/test/super_tab_pm_chat_test.dart@@ -0,0 +1,411 @@+import 'package:flutter/material.dart';+import 'package:flutter_test/flutter_test.dart';+import 'package:harness/shared/theme/app_theme.dart' as grid;+import 'package:harness/super_tabs/controller.dart';+import 'package:harness/super_tabs/project_sidebar.dart';+import 'package:harness/super_tabs/view.dart';++import 'support/super_tab_fixture.dart';++/// Each person's private chat with a project's Product Manager: one per person+/// and project, read by that person and the Lead alone.+void main() {+ ConversationServer swarm() {+ final server = ConversationServer();+ server.state['people'] = [+ {'id': 'owner', 'email': '[email protected]', 'role': 'owner'},+ {'id': 'peer', 'email': '[email protected]', 'role': 'collaborator'},+ ];+ server.state['agents'] = [+ {+ 'id': 'lead-agent',+ 'name': 'Lead',+ 'machineId': 'm1',+ 'harnessId': 'h1',+ 'contributorId': 'owner',+ 'configuration': {'engine': 'claude', 'model': 'opus'},+ },+ ];+ (server.state['conversations'] as List).first+ ..['leadId'] = 'lead-agent'+ ..['agentIds'] = ['lead-agent'];+ return server;+ }++ List<Map<String, dynamic>> creates(ConversationServer server) => [+ for (final post in server.posts)+ if ((post['command'] as Map)['type'] == 'conversation.create') post,+ ];++ group('the controller', () {+ test('the first open creates a private conversation for the person alone, named after them', () async {+ final server = swarm();+ final c = server.controller(account: 'peer');+ addTearDown(c.dispose);+ await c.refresh();+ expect(c.pmChat('lead'), isNull);++ expect(await c.openPmChat('lead'), isTrue);++ expect(creates(server), hasLength(1));+ expect(creates(server).single['command'], {+ 'type': 'conversation.create',+ 'projectId': 'lead',+ 'title': 'ken.tran',+ 'brief': '',+ 'checks': <dynamic>[],+ 'audience': {+ 'personIds': ['peer'],+ },+ });+ final chat = c.pmChat('lead');+ expect(chat, isNotNull);+ expect(chat!.audience, ['peer']);+ expect(chat.agentIds, ['lead-agent']);+ expect(c.selectedId, chat.id);+ });++ test(+ 'a later open reopens the same conversation and sends nothing',+ () async {+ final server = swarm();+ final c = server.controller(account: 'peer');+ addTearDown(c.dispose);+ await c.refresh();+ await c.openPmChat('lead');+ final id = c.pmChat('lead')!.id;+ await c.select('lead');+ final sent = server.posts.length;++ expect(await c.openPmChat('lead'), isTrue);++ expect(server.posts, hasLength(sent));+ expect(c.selectedId, id);+ },+ );++ test('two windows opening it at once get one conversation: the create repeats one request', () async {+ final server = swarm();+ final first = server.controller(account: 'peer');+ final second = server.controller(account: 'peer');+ addTearDown(first.dispose);+ addTearDown(second.dispose);+ await first.refresh();+ await second.refresh();++ // The second window read before the first one's create landed.+ await first.openPmChat('lead');+ await second.openPmChat('lead');++ expect(creates(server), hasLength(2));+ expect(+ creates(server).map((p) => p['operationId']).toSet(),+ hasLength(1),+ );+ final groups = (server.state['conversations'] as List).where(+ (g) => (g as Map)['audience'] != null,+ );+ expect(groups, hasLength(1));+ expect(second.selectedId, first.pmChat('lead')!.id);+ expect(second.pmChat('lead')!.id, first.pmChat('lead')!.id);+ });++ test('each person and project has its own create request', () async {+ final server = swarm();+ final peer = server.controller(account: 'peer');+ final owner = server.controller(account: 'owner');+ addTearDown(peer.dispose);+ addTearDown(owner.dispose);+ await peer.refresh();+ await owner.refresh();+ await peer.openPmChat('lead');+ await owner.openPmChat('lead');++ final ids = creates(server).map((p) => p['operationId']).toList();+ expect(ids, hasLength(2));+ expect(ids.toSet(), hasLength(2));+ expect(peer.pmChat('lead')!.id, isNot(owner.pmChat('lead')!.id));+ });++ test('a person who left and rejoined gets a new chat, not the one they can no longer read', () async {+ final server = swarm();+ final people = (server.state['people'] as List).cast<Map>();+ people.firstWhere((p) => p['id'] == 'peer')['generation'] = 'first';+ final c = server.controller(account: 'peer');+ addTearDown(c.dispose);+ await c.refresh();+ expect(await c.openPmChat('lead'), isTrue);+ final before = c.pmChat('lead')!.id;++ // Removed and invited back: the same person at a new membership, which+ // the old chat's audience no longer lets read it. A rejoin has readers+ // reload in full (backend parts/commit.ts visibilityChanged).+ people.firstWhere((p) => p['id'] == 'peer')['generation'] = 'second';+ server.parts.epoch++;+ await c.refresh();+ expect(c.snapshot!.conversation(before), isNull);+ expect(c.pmChat('lead'), isNull);++ expect(await c.openPmChat('lead'), isTrue);++ final after = c.pmChat('lead')!;+ expect(after.id, isNot(before));+ expect(c.selectedId, after.id);+ expect(+ creates(server).map((p) => p['operationId']).toSet(),+ hasLength(2),+ );+ });++ test("another member, the owner included, does not see a person's chat and opens their own", () async {+ final server = swarm();+ final peer = server.controller(account: 'peer');+ addTearDown(peer.dispose);+ await peer.refresh();+ await peer.openPmChat('lead');+ final mine = peer.pmChat('lead')!.id;++ final owner = server.controller(account: 'owner');+ addTearDown(owner.dispose);+ await owner.refresh();++ expect(owner.snapshot!.conversation(mine), isNull);+ expect(owner.pmChat('lead'), isNull);+ });++ test(+ 'a private conversation shared with someone else too is not the PM chat',+ () async {+ final server = swarm();+ (server.state['conversations'] as List).add({+ ...conversationFixture('pair', 'Ken and owner'),+ 'projectId': 'lead',+ 'audience': {+ 'people': [+ {'id': 'peer', 'generation': 'g'},+ {'id': 'owner', 'generation': 'g'},+ ],+ },+ });+ final c = server.controller(account: 'peer');+ addTearDown(c.dispose);+ await c.refresh();++ expect(c.snapshot!.conversation('pair')!.audience, ['peer', 'owner']);+ expect(c.pmChat('lead'), isNull);+ },+ );+ });++ group('the sidebar', () {+ Future<SuperTabController> show(+ WidgetTester tester,+ ConversationServer server, {+ String account = 'peer',+ }) async {+ await tester.binding.setSurfaceSize(const Size(1280, 800));+ addTearDown(() => tester.binding.setSurfaceSize(null));+ final c = server.controller(account: account);+ await c.refresh();+ await tester.pumpWidget(+ MaterialApp(+ theme: grid.buildAppTheme(brightness: Brightness.light),+ home: Scaffold(+ body: SuperTabView(+ controller: c,+ onInvite: () {},+ onAddAgent: (_) {},+ onOpenTerminal: (_) {},+ machineName: (_) => 'Team Mac',+ ),+ ),+ ),+ );+ await tester.pumpAndSettle();+ if (!c.expandedProjects.contains('lead')) c.toggleProject('lead');+ await tester.pumpAndSettle();+ return c;+ }++ Future<void> close(WidgetTester tester, SuperTabController c) async {+ await tester.pumpWidget(const SizedBox());+ await c.flush();+ c.dispose();+ }++ final entry = find.byKey(const ValueKey('super-pm-chat-lead'));++ testWidgets('a project shows Chat with PM above its workgroups', (+ tester,+ ) async {+ final c = await show(tester, swarm());+ expect(entry, findsOneWidget);+ expect(+ find.descendant(of: entry, matching: find.text('Chat with PM')),+ findsOneWidget,+ );+ final workgroup = find.byKey(const ValueKey('super-group-offline'));+ expect(+ tester.getTopLeft(entry).dy,+ lessThan(tester.getTopLeft(workgroup).dy),+ );+ await close(tester, c);+ });++ testWidgets(+ 'the first click opens a new chat, named Chat with PM in the header, not listed again among the workgroups',+ (tester) async {+ final server = swarm();+ final c = await show(tester, server);+ await tester.tap(entry);+ await tester.pumpAndSettle();++ expect(creates(server), hasLength(1));+ final chat = c.pmChat('lead')!;+ expect(c.selectedId, chat.id);+ expect(find.byKey(ValueKey('super-group-${chat.id}')), findsNothing);+ expect(find.text('Chat with PM'), findsNWidgets(2));+ expect(find.text('Message Product Manager'), findsOneWidget);++ await tester.tap(find.byKey(const ValueKey('super-group-offline')));+ await tester.pumpAndSettle();+ await tester.tap(entry);+ await tester.pumpAndSettle();+ expect(creates(server), hasLength(1));+ expect(c.selectedId, chat.id);+ await close(tester, c);+ },+ );++ testWidgets(+ 'the chat lists only its own people: the person and the Product Manager',+ (tester) async {+ final server = swarm();+ (server.state['agents'] as List).add({+ 'id': 'builder',+ 'name': 'Builder',+ 'machineId': 'm1',+ 'harnessId': 'h2',+ 'contributorId': 'owner',+ 'configuration': {'engine': 'claude', 'model': 'opus'},+ });+ final c = await show(tester, server);+ expect(+ find.byKey(const ValueKey('super-person-owner')),+ findsOneWidget,+ );+ await tester.tap(entry);+ await tester.pumpAndSettle();++ expect(find.byKey(const ValueKey('super-person-peer')), findsOneWidget);+ expect(find.byKey(const ValueKey('super-person-owner')), findsNothing);+ expect(find.text('Lead'), findsWidgets);+ expect(find.text('Builder'), findsNothing);+ await close(tester, c);+ },+ );++ testWidgets(+ 'the chat offers no Add agent: the Product Manager is its only agent',+ (tester) async {+ final c = await show(tester, swarm());+ final addAgent = find.byTooltip('Add agent');+ expect(addAgent, findsOneWidget);+ await tester.tap(entry);+ await tester.pumpAndSettle();++ expect(c.selectedId, c.pmChat('lead')!.id);+ expect(addAgent, findsNothing);+ await close(tester, c);+ },+ );++ testWidgets('a reply from the Product Manager marks the entry unread', (+ tester,+ ) async {+ final server = swarm();+ final c = await show(tester, server);+ await tester.tap(entry);+ await tester.pumpAndSettle();+ final chat = c.pmChat('lead')!;+ await tester.tap(find.byKey(const ValueKey('super-group-offline')));+ await tester.pumpAndSettle();++ server.append('Here is the plan.', conversationId: chat.id);+ await c.refresh();+ await tester.pumpAndSettle();++ expect(c.unread(c.pmChat('lead')!), isTrue);+ expect(+ find.descendant(+ of: entry,+ matching: find.byWidgetPredicate(+ (w) => w is Semantics && w.properties.label == 'Unread messages',+ ),+ ),+ findsOneWidget,+ );+ await close(tester, c);+ });++ testWidgets(+ "a Product Manager's tag in the chat is in Notifications under Chat with PM, and opens it",+ (tester) async {+ final server = swarm();+ final c = await show(tester, server);+ await tester.tap(entry);+ await tester.pumpAndSettle();+ final chat = c.pmChat('lead')!.id;+ await tester.tap(find.byKey(const ValueKey('super-group-offline')));+ await tester.pumpAndSettle();+ server.append('Which build should I ship?', conversationId: chat);+ server.tag(+ 'message-${server.revision}',+ conversationId: chat,+ text: 'Which build should I ship?',+ );+ server.mentions.last['conversationTitle'] = 'ken.tran';+ await c.refresh();+ await tester.pumpAndSettle();++ await tester.tap(find.byKey(const ValueKey('super-notifications')));+ await tester.pumpAndSettle();+ final row = find.byKey(const ValueKey('super-mention-mention-1'));+ expect(+ find.descendant(+ of: row,+ matching: find.text('web-project · Chat with PM'),+ ),+ findsOneWidget,+ );+ await tester.tap(row);+ await tester.pumpAndSettle();+ expect(c.selectedId, chat);+ await close(tester, c);+ },+ );++ testWidgets("the owner's sidebar never lists a member's chat", (+ tester,+ ) async {+ final server = swarm();+ final peer = server.controller(account: 'peer');+ await peer.refresh();+ await peer.openPmChat('lead');+ final id = peer.pmChat('lead')!.id;+ peer.dispose();++ final c = await show(tester, server, account: 'owner');+ expect(find.byKey(ValueKey('super-group-$id')), findsNothing);+ expect(+ find.descendant(+ of: find.byType(ProjectSidebar),+ matching: find.text('ken.tran'),+ ),+ findsNothing,+ );+ expect(entry, findsOneWidget);+ await close(tester, c);+ });+ });+}diff --git a/desktop/test/super_tab_read_fixtures/changes.json b/desktop/test/super_tab_read_fixtures/changes.jsonnew file mode 100644index 000000000..165a3d0c6--- /dev/null+++ b/desktop/test/super_tab_read_fixtures/changes.json@@ -0,0 +1,33 @@+{+ "format": 2, "reload": false,+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDc3Mzc1LCJlIjozfQ",+ "serverTime": 1793010107375, "lastChangedAt": 1793010106120, "epoch": 3,+ "head": null,+ "members": [], "agents": [],+ "groups": [+ { "key": "aeef", "version": 214033, "changedAt": 1793010106120,+ "data": { "id": "aeef", "projectId": "5701", "number": 204, "title": "1726 G1: design doc",+ "leadId": "0fcb", "agentIds": ["0fcb", "0540"], "archived": false,+ "brief": "Goal: design", "checks": [], "assignment": null,+ "lastMessageSequence": 219810, "messageSeq": 219810, "pullRequestUrls": [] } },+ { "key": "9c1d", "version": 214040, "changedAt": 1793010105000, "dormant": true },+ { "key": "77ab", "version": 214041, "changedAt": 1793010105500, "deleted": true }+ ],+ "machines": [+ { "key": "7835", "version": 214050, "changedAt": 1793010105900,+ "data": { "machineId": "7835", "name": "MacBookPro2021", "contributorId": "6a91", "scope": "swarm",+ "engines": ["claude", "codex"], "maxAgents": 4, "paused": true, "cwd": "/Users/ken",+ "generation": "g1", "membershipGeneration": "m1",+ "observation": { "receivedAt": 1793010105000, "resources": {}, "quotas": [],+ "runningHarnessIds": ["2973"], "stoppedHarnessIds": [] } } }+ ],+ "starts": [], "progress": [],+ "derived": {+ "agents": {+ "0fcb": { "downSince": null, "limitedUntil": null, "workDecision": null, "roleId": null },+ "0540": { "downSince": null, "limitedUntil": null, "workDecision": null, "roleId": null }+ },+ "machines": { "7835": { "availableSlots": 2, "teamWork": { "allowed": true } } },+ "mentionsWaiting": 1+ }+}diff --git a/desktop/test/super_tab_read_fixtures/dormant_groups.json b/desktop/test/super_tab_read_fixtures/dormant_groups.jsonnew file mode 100644index 000000000..be088ef2e--- /dev/null+++ b/desktop/test/super_tab_read_fixtures/dormant_groups.json@@ -0,0 +1,9 @@+{+ "groups": [+ { "key": "9c1d", "version": 214040, "changedAt": 1793010105000,+ "data": { "id": "9c1d", "projectId": "5701", "number": 150, "title": "Old work", "leadId": "0fcb",+ "agentIds": ["0fcb"], "archived": true, "brief": "", "checks": [], "assignment": null,+ "lastMessageSequence": 200100, "messageSeq": 200100, "pullRequestUrls": [], "dormant": true } }+ ],+ "next": "eyJsYSI6MTc5MzAwMDAwMDAwMCwiayI6IjljMWQifQ"+}diff --git a/desktop/test/super_tab_read_fixtures/first_load.json b/desktop/test/super_tab_read_fixtures/first_load.jsonnew file mode 100644index 000000000..be93e7c13--- /dev/null+++ b/desktop/test/super_tab_read_fixtures/first_load.json@@ -0,0 +1,83 @@+{+ "format": 2,+ "tabId": "c51479bd73b59e58176ad9e4",+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjozfQ",+ "serverTime": 1793010104375,+ "lastChangedAt": 1793010101002,+ "epoch": 3,+ "githubApp": true,+ "head": {+ "key": "head", "version": 213990, "changedAt": 1793009000000,+ "data": {+ "version": 1, "id": "c51479bd73b59e58176ad9e4", "name": "openharness", "ownerId": "6a86",+ "environment": "prod", "paused": false, "leadsConversationId": "leads",+ "projects": [+ { "id": "5701", "name": "openharness", "ownerId": "6a86", "leadConversationId": "lead5701",+ "visibility": "public", "members": [], "updateMinutes": 5, "skillMode": "default", "skillSet": "default" }+ ],+ "rules": [], "invitations": [], "localModels": { "grid": "swarm-c514", "enabled": true }+ }+ },+ "members": [+ { "key": "6a86", "version": 213990, "changedAt": 1793000000000,+ "data": { "id": "6a86", "email": "[email protected]", "role": "owner", "generation": "c514" } }+ ],+ "agents": [+ { "key": "0fcb", "version": 213990, "changedAt": 1793000000000,+ "data": { "id": "0fcb", "projectId": "5701", "machineId": "7835", "harnessId": "1111",+ "machineOwnerId": "6a91", "contributorId": "6a91", "membershipGeneration": "02c4",+ "hostGrant": null, "name": "Lead", "displayName": "River",+ "configuration": { "engine": "claude", "model": "opus", "effort": "high",+ "contextWindow": null, "engineVersion": null } } },+ { "key": "0540", "version": 214010, "changedAt": 1793010090000,+ "data": { "id": "0540", "projectId": "5701", "machineId": "7835", "harnessId": "2973",+ "machineOwnerId": "6a91", "contributorId": "6a91", "membershipGeneration": "02c4",+ "hostGrant": null, "name": "Builder", "displayName": "Hugo", "workDecision": "release",+ "configuration": { "engine": "claude", "model": "opus", "effort": "high",+ "contextWindow": null, "engineVersion": null } } }+ ],+ "groups": [+ { "key": "leads", "version": 213990, "changedAt": 1793000000000,+ "data": { "id": "leads", "kind": "leads", "title": "Product Managers", "leadId": null, "agentIds": ["0fcb"],+ "archived": false, "brief": "", "checks": [], "assignment": null,+ "lastMessageSequence": 0, "messageSeq": 213990, "pullRequestUrls": [] } },+ { "key": "lead5701", "version": 213990, "changedAt": 1793000000000,+ "data": { "id": "lead5701", "projectId": "5701", "title": "Lead", "leadId": "0fcb", "agentIds": ["0fcb"],+ "archived": false, "brief": "", "checks": [], "assignment": null,+ "lastMessageSequence": 213000, "messageSeq": 213990, "pullRequestUrls": [] } },+ { "key": "aeef", "version": 214031, "changedAt": 1793010101002,+ "data": { "id": "aeef", "projectId": "5701", "number": 204, "title": "1726 G1: design doc",+ "leadId": "0fcb", "agentIds": ["0fcb", "0540"], "archived": false,+ "brief": "Goal: design",+ "task": { "goal": "Design", "changes": "A doc", "constraints": "None", "owns": ["docs/design/"] },+ "checks": [ { "id": "b936", "description": "Doc reviewed", "independent": false, "evidence": null, "passedBy": null } ],+ "assignment": { "id": "09d0", "agentId": "0540", "status": "working", "result": null,+ "configuration": { "engine": "claude", "model": "opus", "effort": "high",+ "contextWindow": null, "engineVersion": null },+ "execution": { "machineId": "7835", "harnessId": "2973", "machineOwnerId": "6a91" },+ "recordingProgress": { "at": 1793010104375, "revision": 219804 } },+ "lastMessageSequence": 219804, "messageSeq": 219804, "pullRequestUrls": [] } }+ ],+ "machines": [+ { "key": "7835", "version": 214020, "changedAt": 1793010100000,+ "data": { "machineId": "7835", "name": "MacBookPro2021", "contributorId": "6a91", "scope": "swarm",+ "engines": ["claude", "codex"], "maxAgents": 4, "paused": false, "cwd": "/Users/ken",+ "generation": "g1", "membershipGeneration": "m1",+ "observation": { "receivedAt": 1793010099000, "resources": {}, "quotas": [],+ "runningHarnessIds": ["2973"], "stoppedHarnessIds": [] } } }+ ],+ "starts": [],+ "progress": [+ { "key": "5701", "version": 214001, "changedAt": 1793009900000,+ "data": { "since": 1793009900000, "summarizedFloor": 213800, "summarized": { "aeef": 219700 },+ "requestedFloor": 213800, "requested": {}, "requestedAt": null } }+ ],+ "derived": {+ "agents": {+ "0fcb": { "downSince": null, "limitedUntil": null, "workDecision": null, "roleId": null },+ "0540": { "downSince": "2026-10-26T10:19:51.474Z", "limitedUntil": null, "workDecision": "awaiting", "roleId": null }+ },+ "machines": { "7835": { "availableSlots": 3, "teamWork": { "allowed": true } } },+ "mentionsWaiting": 0+ }+}diff --git a/desktop/test/super_tab_read_fixtures/reload.json b/desktop/test/super_tab_read_fixtures/reload.jsonnew file mode 100644index 000000000..fa5211f8b--- /dev/null+++ b/desktop/test/super_tab_read_fixtures/reload.json@@ -0,0 +1 @@+{ "reload": true }diff --git a/desktop/test/super_tab_read_fixtures/update_required.json b/desktop/test/super_tab_read_fixtures/update_required.jsonnew file mode 100644index 000000000..7c3ee2d0b--- /dev/null+++ b/desktop/test/super_tab_read_fixtures/update_required.json@@ -0,0 +1 @@+{ "error": { "code": "UPDATE_REQUIRED", "message": "Update Harness to keep using this Swarm." } }diff --git a/desktop/test/super_tab_reading_client_test.dart b/desktop/test/super_tab_reading_client_test.dartindex cda75fcc7..e6fa8f54d 100644--- a/desktop/test/super_tab_reading_client_test.dart+++ b/desktop/test/super_tab_reading_client_test.dart@@ -38,7 +38,7 @@ class _Backend {'Connect one of your machines to open Swarm.',);}- if (path.startsWith('/api/super-tabs?') || path == '/api/super-tabs') {+ if (Uri.parse(path).path == '/api/super-tabs/list') {return {'tabs': [{'id': 'tab', 'name': 'Pilot'},@@ -51,10 +51,16 @@ class _Backend {return servers[id]!.request(method, path, body: body);}- int states(String id) =>- paths.where((p) => p == '/api/super-tabs/$id').length;+ /// Reads of the Swarm itself: first loads and change reads.+ int states(String id) => paths+ .where(+ (p) =>+ p == '/api/super-tabs/$id/parts' ||+ p.startsWith('/api/super-tabs/$id/changes?'),+ )+ .length;int get discoveries =>- paths.where((p) => Uri.parse(p).path == '/api/super-tabs').length;+ paths.where((p) => Uri.parse(p).path == '/api/super-tabs/list').length;}SuperTabClient _client(diff --git a/desktop/test/super_tab_reading_test.dart b/desktop/test/super_tab_reading_test.dartindex 4bd34d079..e4522d69d 100644--- a/desktop/test/super_tab_reading_test.dart+++ b/desktop/test/super_tab_reading_test.dart@@ -16,6 +16,14 @@ const _web = SuperTabReading(messagesWithState: true,);+/// A read of the Swarm itself: its first load, or its changes since a cursor.+bool _isStateRead(String path) =>+ path == '/api/super-tabs/tab/parts' ||+ path.startsWith('/api/super-tabs/tab/changes?');++/// A poll's read of what changed since the last one.+final _changesRead = startsWith('/api/super-tabs/tab/changes?cursor=');+/// Every read the controller made, in order.class _Reads {_Reads(this.server);@@ -43,7 +51,7 @@ class _Reads {),);}- if (holdState case final held? when path == '/api/super-tabs/tab') {+ if (holdState case final held? when _isStateRead(path)) {final wait = Completer<void>();held.add(wait);return wait.future.then((_) => server.request(method, path, body: body));@@ -57,7 +65,7 @@ class _Reads {return server.request(method, path, body: body);}- int get states => paths.where((p) => p == '/api/super-tabs/tab').length;+ int get states => paths.where(_isStateRead).length;int get pages => paths.where((p) => p.contains('messages?before=')).length;int get tails => paths.where((p) => p.contains('messages?after=')).length;int get receipts => paths.where((p) => p.contains('messageId=')).length;@@ -116,7 +124,7 @@ void main() {server.holdReads = Completer<void>();reads.clear();async.elapse(const Duration(seconds: 3));- expect(reads.paths, ['/api/super-tabs/tab']);+ expect(reads.paths, [_changesRead]);server.holdReads!.complete();server.holdReads = null;async.flushMicrotasks();@@ -153,7 +161,7 @@ void main() {},)..start();async.flushMicrotasks();- expect(reads.paths, ['/api/super-tabs/tab']);+ expect(reads.paths, ['/api/super-tabs/tab/parts']);server.holdReads!.complete();server.holdReads = null;async.flushMicrotasks();@@ -286,7 +294,7 @@ void main() {async.elapse(const Duration(seconds: 3));expect(reads.paths, ['/api/super-tabs/tab/conversations/lead/messages?after=1',- '/api/super-tabs/tab',+ _changesRead,]);_reply(server, 'Done.');server.holdReads!.complete();@@ -428,7 +436,7 @@ void main() {async.flushMicrotasks();expect(reads.paths, ['/api/super-tabs/tab/conversations/offline/messages',- '/api/super-tabs/tab',+ '/api/super-tabs/tab/parts',]);server.holdReads!.complete();server.holdReads = null;diff --git a/desktop/test/super_tab_reading_workspace_test.dart b/desktop/test/super_tab_reading_workspace_test.dartindex b568cda6d..d723ad919 100644--- a/desktop/test/super_tab_reading_workspace_test.dart+++ b/desktop/test/super_tab_reading_workspace_test.dart@@ -15,7 +15,8 @@ import 'super_tab_launch_test.dart'show SuperTabFixtureConnection, SuperTabLaunchFixture, tabId;import 'swarm_state_test.dart' show MemoryStore;-/// The Swarm state reads the fixture's machine has answered.+/// The Swarm state reads (first loads and change reads) the fixture's machine+/// has answered.int _stateReads(SuperTabLaunchFixture f) => _connectionReads(f.connection);int _connectionReads(SuperTabFixtureConnection connection) => connection.calls@@ -23,7 +24,10 @@ int _connectionReads(SuperTabFixtureConnection connection) => connection.calls(c) =>c.$1 == 'super_tabs' &&c.$2['method'] == 'GET' &&- c.$2['path'] == '/api/super-tabs/$tabId',+ (c.$2['path'] == '/api/super-tabs/$tabId/parts' ||+ (c.$2['path'] as String).startsWith(+ '/api/super-tabs/$tabId/changes?',+ )),).length;diff --git a/desktop/test/super_tab_saved_view_test.dart b/desktop/test/super_tab_saved_view_test.dartindex 14c7782cb..bd15025cf 100644--- a/desktop/test/super_tab_saved_view_test.dart+++ b/desktop/test/super_tab_saved_view_test.dart@@ -6,13 +6,15 @@ import 'package:flutter_test/flutter_test.dart';import 'package:harness/core/local_key_value_store.dart';import 'package:harness/super_tabs/client.dart';import 'package:harness/super_tabs/controller.dart';+import 'package:harness/super_tabs/model.dart';+import 'package:harness/super_tabs/parts.dart';import 'package:harness/super_tabs/reading.dart';import 'package:harness/super_tabs/saved_view.dart';import 'support/super_tab_fixture.dart';import 'swarm_state_test.dart' show MemoryStore;-/// A view as a controller hands it over: the state as read, the open+/// A view as a controller hands it over: the Swarm's parts as read, the open/// conversation and its last page.Map<String, dynamic> _view({String tab = 'tab', int pad = 0}) {final server = ConversationServer()..append('Hello');@@ -24,9 +26,12 @@ Map<String, dynamic> _view({String tab = 'tab', int pad = 0}) {},];if (pad > 0) server.state['name'] = 'x' * pad;+ final load = server.parts.read('/api/super-tabs/$tab/parts', server.state)!;return {- 'revision': 7,- 'state': server.state,+ 'format': 2,+ 'savedAt': DateTime.now().millisecondsSinceEpoch,+ 'lastChangedAt': 7,+ 'parts': SuperTabParts.firstLoad(load).toJson(),'conversationId': 'lead','messages': server.messages,'next': null,@@ -49,15 +54,32 @@ void main() {await views.claim('owner');await views.write('owner', 'tab', _view());final read = (await views.read('owner', 'tab'))!;- expect(read['revision'], 7);+ expect(read['lastChangedAt'], 7);expect(read['conversationId'], 'lead');expect((read['messages'] as List).single['text'], 'Hello');- final state = read['state'] as Map<String, dynamic>;+ final state = SuperTabParts.fromJson(superTabMap(read['parts'])).state;expect(state['name'], 'Pilot');- expect(state.containsKey('starts'), isFalse);+ expect(state['starts'], isEmpty);expect(store.values.values.join(), isNot(contains('never draws')));});+ test('a view an older build saved is not drawn', () async {+ final store = MemoryStore();+ final views = SuperTabSavedViews(store);+ await views.claim('owner');+ await store.write(+ 'super_tab.view.owner.tab',+ jsonEncode({+ 'revision': 7,+ 'state': ConversationServer().state,+ 'conversationId': 'lead',+ 'messages': <dynamic>[],+ 'next': null,+ }),+ );+ expect(await views.read('owner', 'tab'), isNull);+ });+test('a view over the size cap is not kept, and an older one goes', () async {final store = MemoryStore();final views = SuperTabSavedViews(store, maxBytes: 4096);@@ -200,10 +222,11 @@ void _controllerTests() {c.start();async.flushMicrotasks();expect(c.loading, isFalse);- // The state and the latest page: receipts and new messages in one read.+ // What changed since the view was saved, and the latest page:+ // receipts and new messages in one read.expect(reads.paths, ['/api/super-tabs/tab/conversations/lead/messages',- '/api/super-tabs/tab',+ startsWith('/api/super-tabs/tab/changes?cursor='),]);server.holdReads!.complete();server.holdReads = null;@@ -243,7 +266,9 @@ void _controllerTests() {final broken = _controller(_Reads(server))..drawSaved({...view,- 'state': {'id': 'tab'},+ 'parts': {+ 'load': {'format': 2},+ },});expect(broken.snapshot, isNull);expect(broken.showingSaved, isFalse);@@ -272,6 +297,51 @@ void _controllerTests() {});});+ test(+ 'a saved view from another epoch draws, then the first read loads in full',+ () {+ final server = ConversationServer()..append('Hello');+ final view = _saved(server);+ fakeAsync((async) {+ server.parts.epoch++;+ final reads = _Reads(server);+ final c = _controller(reads)..drawSaved(view);+ expect(c.showingSaved, isTrue);+ c.start();+ async.flushMicrotasks();+ expect(reads.paths.where((p) => !p.contains('/messages')), [+ startsWith('/api/super-tabs/tab/changes?cursor='),+ '/api/super-tabs/tab/parts',+ ]);+ expect(c.showingSaved, isFalse);+ expect(c.snapshot!.name, 'Pilot');+ c.dispose();+ });+ },+ );++ test('a saved view older than seven days is not drawn', () {+ final server = ConversationServer()..append('Hello');+ final view = _saved(server);+ fakeAsync((async) {+ final reads = _Reads(server);+ final c = _controller(reads)+ ..drawSaved({+ ...view,+ 'savedAt': DateTime.now()+ .subtract(const Duration(days: 7))+ .millisecondsSinceEpoch,+ });+ expect(c.snapshot, isNull);+ c.start();+ async.flushMicrotasks();+ expect(reads.paths.where((p) => !p.contains('/messages')), [+ '/api/super-tabs/tab/parts',+ ]);+ c.dispose();+ });+ });+test('Desktop reading keeps no saved view and draws none', () {final server = ConversationServer()..append('Hello');final view = _saved(server);@@ -300,7 +370,7 @@ class _Transport {}) async {if (hold case final wait?) await wait.future;if (refuse case final failure?) throw failure;- if (Uri.parse(path).path == '/api/super-tabs') {+ if (Uri.parse(path).path == '/api/super-tabs/list') {return {'tabs': [{'id': 'tab', 'name': 'Pilot'},@@ -721,7 +791,10 @@ void _reviewTests() {final client =SuperTabClient(transport: (method, path, {body}) {- if (path == '/api/super-tabs/tab') reads.add(path);+ if (path == '/api/super-tabs/tab/parts' ||+ path.startsWith('/api/super-tabs/tab/changes?')) {+ reads.add(path);+ }return transport.call(method, path, body: body);},storage: store,@@ -824,7 +897,7 @@ void _reviewTests() {// Finding 6.test('the first read wins over a saved view, whatever its revision', () {final server = ConversationServer()..append('Hello');- final view = _saved(server)..['revision'] = 999;+ final view = _saved(server)..['lastChangedAt'] = 1 << 50;fakeAsync((async) {server.state['name'] = 'Pilot, renamed';final c = _controller(_Reads(server))diff --git a/desktop/test/super_tab_update_required_test.dart b/desktop/test/super_tab_update_required_test.dartnew file mode 100644index 000000000..2e968a063--- /dev/null+++ b/desktop/test/super_tab_update_required_test.dart@@ -0,0 +1,129 @@+import 'package:fake_async/fake_async.dart';+import 'package:flutter/material.dart';+import 'package:flutter_test/flutter_test.dart';+import 'package:harness/super_tabs/controller.dart';+import 'package:harness/super_tabs/view.dart';++import 'support/super_tab_fixture.dart';++/// A backend that no longer serves this build's reads answers 426+/// UPDATE_REQUIRED: the Swarm says to update Harness and stops asking+/// (docs/design/2026-10-26-swarm-state-parts.md, sections 4.11 and 5.1).+void main() {+ const update = 'Update Harness to keep using this Swarm.';+ late ConversationServer server;+ late List<String> reads;+ var refuse = false;++ SuperTabController open({Duration poll = Duration.zero}) {+ reads = [];+ return SuperTabController(+ tabId: 'tab',+ accountId: 'owner',+ request: (method, path, {body}) {+ if (method == 'GET') reads.add(path);+ if (refuse) throw superTabUpdateRequired;+ return server.request(method, path, body: body);+ },+ save: server.save,+ pollInterval: poll,+ );+ }++ setUp(() {+ server = ConversationServer();+ refuse = false;+ });++ test('an update answer shows the update message and stops the poll', () {+ fakeAsync((async) {+ final c = open(poll: const Duration(seconds: 3))..start();+ async.flushMicrotasks();+ expect(c.snapshot, isNotNull);+ refuse = true;+ async.elapse(const Duration(seconds: 3));+ expect(c.updateRequired, isTrue);+ expect(c.error, update);+ // The backend answered: it is not unreachable.+ expect(c.backendUnreachable, isFalse);+ final asked = reads.length;+ async.elapse(const Duration(minutes: 1));+ expect(reads, hasLength(asked));+ // Nor does a machine connecting, or a refresh, ask again.+ c.machineAvailable();+ c.refresh();+ async.flushMicrotasks();+ expect(reads, hasLength(asked));+ c.dispose();+ });+ });++ test('a refused message read or command says the same and stops', () async {+ final c = open();+ await c.refresh();+ refuse = true;+ c.setDraft('lead', 'Hello');+ await c.send();+ expect(c.operationError, update);+ expect(c.updateRequired, isTrue);+ expect(c.error, update);+ });++ test('a refused closed-groups read alone says the same and stops', () async {+ final c = SuperTabController(+ tabId: 'tab',+ accountId: 'owner',+ request: (method, path, {body}) {+ if (method == 'GET') reads.add(path);+ if (path.contains('/groups?dormant=1')) throw superTabUpdateRequired;+ return server.request(method, path, body: body);+ },+ save: server.save,+ pollInterval: Duration.zero,+ );+ reads = [];+ await c.refresh();+ c.toggleProject('lead');+ await c.loadDormant('lead');+ expect(c.updateRequired, isTrue);+ expect(c.error, update);+ final asked = reads.length;+ await c.refresh();+ expect(reads, hasLength(asked));+ });++ test('a refused first load says to update Harness', () async {+ refuse = true;+ final c = open();+ await c.refresh();+ expect(c.snapshot, isNull);+ expect(c.error, update);+ expect(c.accessRevoked, isFalse);+ });++ testWidgets('the update message offers no Retry', (tester) async {+ final c = open();+ await c.refresh();+ refuse = true;+ await c.refresh();+ await tester.pumpWidget(+ MaterialApp(+ home: Scaffold(+ body: SuperTabView(+ controller: c,+ onInvite: () {},+ onAddAgent: (_) {},+ onOpenTerminal: (_) {},+ machineName: (_) => 'Test Mac',+ ),+ ),+ ),+ );+ await tester.pumpAndSettle();+ expect(find.text(update), findsOneWidget);+ expect(find.text('Retry'), findsNothing);+ await tester.pumpWidget(const SizedBox());+ await c.flush();+ c.dispose();+ });+}diff --git a/desktop/test/super_tab_view_test.dart b/desktop/test/super_tab_view_test.dartindex 97720384e..2c1313767 100644--- a/desktop/test/super_tab_view_test.dart+++ b/desktop/test/super_tab_view_test.dart@@ -58,6 +58,67 @@ void main() {controller.dispose();},);+ testWidgets(+ 'older archived conversations stay reachable behind newer closed ones',+ (tester) async {+ final server = ConversationServer()..parts.dormantPage = 1;+ (server.state['conversations'] as List)[1]['archived'] = true;+ // Finished later and quiet: closed, not archived, and newer.+ (server.state['conversations'] as List).add({+ ...conversationFixture('finished', 'Finished work'),+ 'dormant': true,+ });+ final controller = server.controller();+ await controller.refresh();+ await tester.pumpWidget(+ MaterialApp(+ home: Scaffold(+ body: SuperTabView(+ controller: controller,+ onInvite: () {},+ onAddAgent: (_) {},+ onOpenTerminal: (_) {},+ machineName: (_) => 'Test Mac',+ ),+ ),+ ),+ );+ await tester.pumpAndSettle();+ Future<void> openList() async {+ await tester.tap(find.byTooltip('Project options'));+ await tester.pumpAndSettle();+ await tester.tap(find.text('Archived conversations'));+ await tester.pumpAndSettle();+ }++ final earlier = find.byKey(const ValueKey('super-archived-earlier'));+ await openList();+ // The first page holds only the newer closed group: nothing archived+ // shows, and paging is still there, whatever the search.+ expect(find.text('Offline editing'), findsNothing);+ await tester.enterText(+ find.descendant(+ of: find.byType(Dialog),+ matching: find.byType(TextField),+ ),+ 'offline',+ );+ await tester.pumpAndSettle();+ expect(earlier, findsOneWidget);+ await tester.tap(find.text('Close'));+ await tester.pumpAndSettle();+ // Another page exists: the menu keeps the list.+ await openList();+ await tester.tap(earlier);+ await tester.pumpAndSettle();+ expect(find.text('Offline editing'), findsOneWidget);+ expect(earlier, findsNothing);+ await tester.pumpWidget(const SizedBox());+ await controller.flush();+ controller.dispose();+ },+ );+testWidgets('archived conversations remain searchable and can be reopened', (tester,) async {diff --git a/desktop/test/super_tab_work_details_test.dart b/desktop/test/super_tab_work_details_test.dartindex b67445d36..fa477aa5d 100644--- a/desktop/test/super_tab_work_details_test.dart+++ b/desktop/test/super_tab_work_details_test.dart@@ -41,9 +41,7 @@ void main() {);expect(prompt,- contains(- 'goal, changes, constraints, owned paths, checks',- ),+ contains('goal, changes, constraints, owned paths, checks'),);expect(prompt.length, lessThanOrEqualTo(2000));}@@ -114,4 +112,41 @@ void main() {},);}++ testWidgets('work details of a closed group not read yet read it by id', (+ tester,+ ) async {+ final server = ConversationServer();+ final row =+ (server.state['conversations'] as List)[1] as Map<String, dynamic>;+ row+ ..['archived'] = true+ ..['task'] = task;+ final controller = server.controller();+ addTearDown(controller.dispose);+ await controller.refresh();+ expect(controller.snapshot!.conversation('offline'), isNull);+ await tester.pumpWidget(+ MaterialApp(+ home: Builder(+ builder: (context) => Scaffold(+ body: TextButton(+ onPressed: () => showSuperTabWork(context, controller, 'offline'),+ child: const Text('Open'),+ ),+ ),+ ),+ ),+ );+ await tester.tap(find.text('Open'));+ await tester.pumpAndSettle();+ expect(find.text('Goal'), findsOneWidget);+ expect(+ tester+ .widgetList<SuperTabMessageText>(find.byType(SuperTabMessageText))+ .map((widget) => widget.text),+ contains('Keep drafts'),+ );+ expect(tester.takeException(), isNull);+ });}diff --git a/desktop/test/support/super_tab_fixture.dart b/desktop/test/support/super_tab_fixture.dartindex a83e06563..62f9f8ac4 100644--- a/desktop/test/support/super_tab_fixture.dart+++ b/desktop/test/support/super_tab_fixture.dart@@ -1,5 +1,6 @@import 'dart:async';import 'dart:convert';+import 'dart:math';import 'dart:typed_data';import 'package:dio/dio.dart' show CancelToken;@@ -33,8 +34,340 @@ Map<String, dynamic> projectFixture('updateMinutes': 5,};+/// What the backend's Swarm reads answer (docs/design/2026-10-26-swarm-state-parts.md, section 4), worked out from+/// a test's whole-Swarm state. Each read compares every part with what it held: a part whose JSON changed gets the+/// next version and a new `changedAt`, a part that is gone gets a tombstone. Tests keep changing the state as they+/// did; the reads see exactly those changes.+class SwarmPartsBackend {+ /// The server's clock, one tick per change; a cursor is a tick.+ int clock = 1000;+ int _version = 100;++ /// The visibility epoch: a test moves it to have the next change read answer a reload.+ int epoch = 1;++ /// The ticks a change read sends again, as the 30 s overlap does.+ int overlap = 3;++ /// Every read answered, by path, in order.+ final reads = <String>[];++ /// The size of each first load and change read answered, in JSON bytes.+ final bytes = <String, List<int>>{};++ final _parts = <String, _HeldPart>{};++ /// The parts of [state], by `kind:key`. Groups marked dormant leave the active set.+ static Map<String, Map<String, dynamic>> split(Map<String, dynamic> state) {+ final parts = <String, Map<String, dynamic>>{};+ parts['head:head'] = {+ for (final entry in state.entries)+ if (!const {+ 'people',+ 'agents',+ 'conversations',+ 'machines',+ 'starts',+ 'mentionsWaiting',+ 'otherProjectsWork',+ 'githubApp',+ }.contains(entry.key))+ entry.key: entry.value,+ };+ void each(String kind, String list, String id) {+ for (final row in state[list] as List? ?? const []) {+ final data = Map<String, dynamic>.from(row as Map);+ parts['$kind:${data[id]}'] = data;+ }+ }++ each('members', 'people', 'id');+ each('agents', 'agents', 'id');+ each('groups', 'conversations', 'id');+ each('machines', 'machines', 'machineId');+ each('starts', 'starts', 'id');+ return parts;+ }++ /// Whether this backend leaves [group] out of the active set: archived by+ /// hand, or marked dormant as the backend's sweep marks finished, quiet work.+ static bool dormant(Map<String, dynamic> group) =>+ group['dormant'] == true || group['archived'] == true;++ void _sync(Map<String, dynamic> state) {+ final now = split(jsonDecode(jsonEncode(state)) as Map<String, dynamic>);+ for (final entry in now.entries) {+ final json = jsonEncode(entry.value);+ final held = _parts[entry.key];+ if (held != null && !held.deleted && held.json == json) continue;+ _parts[entry.key] = _HeldPart(+ version: ++_version,+ changedAt: ++clock,+ json: json,+ ordinal: held?.ordinal ?? _parts.length,+ );+ }+ for (final entry in _parts.entries.toList()) {+ if (entry.value.deleted || now.containsKey(entry.key)) continue;+ _parts[entry.key] = _HeldPart(+ version: ++_version,+ changedAt: ++clock,+ json: entry.value.json,+ ordinal: entry.value.ordinal,+ deleted: true,+ );+ }+ }++ Map<String, dynamic> _envelope(String id, _HeldPart part) => {+ 'key': id.substring(id.indexOf(':') + 1),+ 'version': part.version,+ 'changedAt': part.changedAt,+ if (part.deleted)+ 'deleted': true+ else if (id.startsWith('groups:') && dormant(part.data))+ 'dormant': true+ else+ 'data': part.data,+ };++ String _cursor(int tick) => 'c${tick}e$epoch';++ Map<String, dynamic> _derived(Map<String, dynamic> state) => {+ 'agents': <String, dynamic>{},+ 'machines': <String, dynamic>{},+ if (state['mentionsWaiting'] != null)+ 'mentionsWaiting': state['mentionsWaiting'],+ if (state['otherProjectsWork'] != null)+ 'otherProjectsWork': state['otherProjectsWork'],+ };++ List<MapEntry<String, _HeldPart>> _ordered() =>+ _parts.entries.toList()+ ..sort((a, b) => a.value.ordinal.compareTo(b.value.ordinal));++ /// Whether [reader] may not read [part]: a private conversation is read only+ /// by its audience (and the project's Lead, an agent), owners included, and+ /// by each person only at the membership generation they were listed with+ /// (backend projects.ts canReadGroup), when [state] gives them one.+ static bool _hidden(+ String id,+ _HeldPart part,+ String? reader,+ Map<String, dynamic> state,+ ) {+ if (reader == null || part.deleted || !id.startsWith('groups:')) {+ return false;+ }+ final audience = part.data['audience'];+ if (audience is! Map) return false;+ final generation = (state['people'] as List?)+ ?.cast<Map>()+ .where((p) => p['id'] == reader)+ .firstOrNull?['generation'];+ return !(audience['people'] as List).any(+ (p) =>+ (p as Map)['id'] == reader &&+ (generation == null || p['generation'] == generation),+ );+ }++ /// The answer to a Swarm read of [state] at [path] by [reader], or null for a path that is not one. With no+ /// reader, every group is read.+ Map<String, dynamic>? read(+ String path,+ Map<String, dynamic> state, {+ String? reader,+ }) {+ final uri = Uri.parse(path);+ final segments = uri.pathSegments;+ if (segments.length < 4 || segments[0] != 'api') return null;+ final route = segments[3];+ // Time passes between reads, changed or not.+ clock++;+ if (segments.length == 4 && route == 'parts') {+ _sync(state);+ reads.add(path);+ final answer = <String, dynamic>{+ 'format': 2,+ 'tabId': state['id'],+ 'cursor': _cursor(clock - overlap),+ 'serverTime': clock,+ 'lastChangedAt': _lastChangedAt(),+ 'epoch': epoch,+ 'githubApp': state['githubApp'] ?? false,+ 'head': _envelope('head:head', _parts['head:head']!),+ for (final kind in _kinds) kind: <dynamic>[],+ 'derived': _derived(state),+ };+ for (final entry in _ordered()) {+ final kind = entry.key.substring(0, entry.key.indexOf(':'));+ if (kind == 'head' || entry.value.deleted) continue;+ if (kind == 'groups' && dormant(entry.value.data)) continue;+ if (_hidden(entry.key, entry.value, reader, state)) continue;+ (answer[kind] as List).add(_envelope(entry.key, entry.value));+ }+ return _measured('parts', answer);+ }+ if (segments.length == 4 && route == 'changes') {+ reads.add(path);+ final cursor = RegExp(r'^c(\d+)e(\d+)$')+ .firstMatch(uri.queryParameters['cursor'] ?? '');+ if (cursor == null || int.parse(cursor.group(2)!) != epoch) {+ return _measured('changes', {'reload': true});+ }+ final since = int.parse(cursor.group(1)!);+ final start = clock;+ _sync(state);+ final answer = <String, dynamic>{+ 'format': 2,+ 'reload': false,+ 'cursor': _cursor(start - overlap),+ 'serverTime': clock,+ 'lastChangedAt': _lastChangedAt(),+ 'epoch': epoch,+ 'head': null,+ for (final kind in _kinds) kind: <dynamic>[],+ 'derived': _derived(state),+ };+ for (final entry in _ordered()) {+ if (entry.value.changedAt <= since) continue;+ if (_hidden(entry.key, entry.value, reader, state)) continue;+ final kind = entry.key.substring(0, entry.key.indexOf(':'));+ if (kind == 'head') {+ answer['head'] = _envelope(entry.key, entry.value);+ } else {+ (answer[kind] as List).add(_envelope(entry.key, entry.value));+ }+ }+ return _measured('changes', answer);+ }+ if (route == 'groups') {+ _sync(state);+ reads.add(path);+ if (segments.length == 5) {+ final held = _parts['groups:${segments[4]}'];+ if (held == null ||+ held.deleted ||+ _hidden('groups:${segments[4]}', held, reader, state)) {+ throw const SuperTabFailure(+ 'NOT_FOUND',+ 'Conversation not found.',+ statusCode: 404,+ );+ }+ return {'group': _dormantEnvelope('groups:${segments[4]}', held)};+ }+ final projectId = uri.queryParameters['projectId'];+ final before = uri.queryParameters['before'];+ final groups = [+ for (final entry in _ordered().reversed)+ if (entry.key.startsWith('groups:') &&+ !entry.value.deleted &&+ dormant(entry.value.data) &&+ !_hidden(entry.key, entry.value, reader, state) &&+ (projectId == null ||+ (entry.value.data['projectId'] ?? 'lead') == projectId))+ entry,+ ];+ final from = before == null+ ? 0+ : groups.indexWhere((e) => e.key == 'groups:$before') + 1;+ final page = groups.skip(from).take(dormantPage).toList();+ return {+ 'groups': [for (final e in page) _dormantEnvelope(e.key, e.value)],+ 'next': from + page.length < groups.length+ ? page.last.key.substring('groups:'.length)+ : null,+ };+ }+ return null;+ }++ /// Groups per page of the dormant list.+ int dormantPage = 50;++ Map<String, dynamic> _dormantEnvelope(String id, _HeldPart part) => {+ 'key': id.substring(id.indexOf(':') + 1),+ 'version': part.version,+ 'changedAt': part.changedAt,+ 'data': {...part.data, if (dormant(part.data)) 'dormant': true},+ };++ Map<String, dynamic> _measured(String kind, Map<String, dynamic> answer) {+ final copy = jsonDecode(jsonEncode(answer)) as Map<String, dynamic>;+ (bytes[kind] ??= []).add(utf8.encode(jsonEncode(copy)).length);+ return copy;+ }++ int _lastChangedAt() => _parts.values.fold(0, (t, p) => max(t, p.changedAt));++ /// What a command reply says it wrote: the parts that changed since [tick].+ List<Map<String, dynamic>> writtenSince(+ int tick,+ Map<String, dynamic> state,+ ) {+ _sync(state);+ return [+ for (final entry in _ordered())+ if (entry.value.changedAt > tick)+ {+ 'kind': switch (entry.key.substring(0, entry.key.indexOf(':'))) {+ 'members' => 'member',+ 'agents' => 'agent',+ 'groups' => 'group',+ 'machines' => 'machine',+ 'starts' => 'start',+ final kind => kind,+ },+ 'key': entry.key.substring(entry.key.indexOf(':') + 1),+ 'version': entry.value.version,+ },+ ];+ }++ static const _kinds = [+ 'members',+ 'agents',+ 'groups',+ 'machines',+ 'starts',+ 'progress',+ ];+}++class _HeldPart {+ _HeldPart({+ required this.version,+ required this.changedAt,+ required this.json,+ required this.ordinal,+ this.deleted = false,+ });+ final int version, changedAt, ordinal;+ final String json;+ final bool deleted;+ Map<String, dynamic> get data => jsonDecode(json) as Map<String, dynamic>;+}++/// What the backend answers an old whole-Swarm read with (section 4.11).+const superTabUpdateRequired = SuperTabFailure(+ 'UPDATE_REQUIRED',+ 'Update Harness to keep using this Swarm.',+ statusCode: 426,+);+class ConversationServer {int revision = 0;++ /// The Swarm reads this server answers, worked out from [state].+ final parts = SwarmPartsBackend();++ /// Messages per page, as the backend pages them.+ int messagePage = 100;++ /// Told of every messages read, by path.+ void Function(String path)? onRead;bool loseReply = false, reject = false, failSave = false, failReads = false;Map<String, dynamic>? saved;// While set, every read waits for it: a slow server.@@ -147,11 +480,15 @@ class ConversationServer {};}+ /// Answers [path] as the backend answers the account of the [controller]+ /// asking ([_reader]); with none, as it answers someone who reads every+ /// conversation.Future<Map<String, dynamic>> request(String method,String path, {Map<String, dynamic>? body,}) async {+ final reader = Zone.current[_reader] as String?;if (method == 'POST') {posts.add(Map<String, dynamic>.from(body!));if (reject) {@@ -170,6 +507,7 @@ class ConversationServer {}final operationId = body['operationId'] as String;if (receipts[operationId] case final receipt?) return receipt;+ final tick = parts.clock;final command = body['command'] as Map;final output = <String, dynamic>{};if (command['type'] == 'message.send') {@@ -192,9 +530,38 @@ class ConversationServer {} else if (command['type'] == 'conversation.create') {revision++;final id = 'group-$revision';+ final projectId = command['projectId'] ?? 'lead';+ // The project's Lead is in every new group, a private one included.+ final leadConversationId =+ (state['projects'] as List?)+ ?.cast<Map<String, dynamic>>()+ .where((p) => p['id'] == projectId)+ .firstOrNull?['leadConversationId'] ??+ 'lead';+ final leadId = (state['conversations'] as List)+ .cast<Map<String, dynamic>>()+ .where((g) => g['id'] == leadConversationId)+ .firstOrNull?['leadId'];(state['conversations'] as List).add({...conversationFixture(id, command['title'] as String),- 'projectId': command['projectId'] ?? 'lead',+ 'projectId': projectId,+ 'leadId': leadId,+ 'agentIds': [?leadId],+ if (command['audience'] case {'personIds': final List people})+ 'audience': {+ 'people': [+ for (final person in people)+ {+ 'id': person,+ 'generation':+ (state['people'] as List?)+ ?.cast<Map>()+ .where((p) => p['id'] == person)+ .firstOrNull?['generation'] ??+ 'fixture',+ },+ ],+ },});output['conversationId'] = id;} else if (command['type'] == 'project.create') {@@ -267,7 +634,11 @@ class ConversationServer {}}output.addAll(commandResult);- final result = {'revision': revision, 'result': output};+ final result = {+ 'result': output,+ 'parts': parts.writtenSince(tick, state),+ 'lastChangedAt': parts.clock,+ };receipts[operationId] = result;if (loseReply) {loseReply = false;@@ -309,30 +680,71 @@ class ConversationServer {return jsonDecode(jsonEncode(decision)) as Map<String, dynamic>;}if (uri.pathSegments.last == 'messages') {+ onRead?.call(path);final conversationId = uri.pathSegments[4];- final after = int.tryParse(uri.queryParameters['after'] ?? '');- final before = int.tryParse(uri.queryParameters['before'] ?? '');- final messageId = uri.queryParameters['messageId'];- var rows = messages- .where(- (m) =>- m['conversationId'] == conversationId &&- (messageId == null || m['id'] == messageId) &&- (after == null || (m['sequence'] as int) > after) &&- (before == null || (m['sequence'] as int) < before),- )- .toList();+ final query = uri.queryParameters;+ final after = int.tryParse(query['after'] ?? '');+ final before = int.tryParse(query['before'] ?? '');+ final afterId = query['afterId'], beforeId = query['beforeId'];+ final messageId = query['messageId'];+ // Pages run in (sequence, id) order (section 4.6).+ int order(Map<String, dynamic> a, Map<String, dynamic> b) {+ final bySequence = (a['sequence'] as int).compareTo(+ b['sequence'] as int,+ );+ return bySequence != 0+ ? bySequence+ : (a['id'] as String).compareTo(b['id'] as String);+ }++ bool past(Map<String, dynamic> m, int sequence, String? id, int sign) {+ final s = (m['sequence'] as int).compareTo(sequence) * sign;+ if (s != 0 || id == null) return s > 0;+ return (m['id'] as String).compareTo(id) * sign > 0;+ }++ var rows =+ messages+ .where(+ (m) =>+ m['conversationId'] == conversationId &&+ (messageId == null || m['id'] == messageId) &&+ (after == null || past(m, after, afterId, 1)) &&+ (before == null || past(m, before, beforeId, -1)),+ )+ .toList()+ ..sort(order);if (after == null) rows = rows.reversed.toList();- final page = rows.take(100).toList();- final next = rows.length > 100 ? page.last['sequence'] : null;+ final page = rows.take(messagePage).toList();+ final next = rows.length > messagePage+ ? {'sequence': page.last['sequence'], 'id': page.last['id']}+ : null;+ return jsonDecode(+ jsonEncode({+ 'messages': after == null ? page.reversed.toList() : page,+ 'next': next,+ }),+ ) as Map<String, dynamic>;+ }+ if (parts.read(path, state, reader: reader) case final answer?) {+ return answer;+ }+ if (uri.path == '/api/super-tabs/list') {return {- 'messages': after == null ? page.reversed.toList() : page,- 'next': next,- 'revision': revision,+ 'tabs': [+ {+ 'id': state['id'],+ 'name': state['name'],+ 'ownerId': state['ownerId'],+ 'paused': state['paused'] ?? false,+ 'lastChangedAt': parts.clock,+ },+ ],+ 'next': null,};}- return jsonDecode(jsonEncode({'revision': revision, 'state': state}))- as Map<String, dynamic>;+ // The whole-Swarm reads are gone (section 4.11): nothing may still ask.+ throw superTabUpdateRequired;}/// The Lead tags the reader in [conversationId], as the backend records it.@@ -357,8 +769,19 @@ class ConversationServer {});state['mentionsWaiting'] = ((state['mentionsWaiting'] as int?) ?? 0) + 1;revision++;+ // The Lead's message carrying the tag moves its conversation.+ final group = (state['conversations'] as List)+ .cast<Map<String, dynamic>>()+ .where((g) => g['id'] == conversationId)+ .firstOrNull;+ group?['lastMessageSequence'] = revision;}+ /// Who asks, for the reads a [controller] makes: a private conversation is+ /// read by its audience alone. A zone value, so that subclasses overriding+ /// [request] keep it.+ static final _reader = Object();+SuperTabController controller({Map<String, dynamic>? initial,String account = 'owner',@@ -366,7 +789,10 @@ class ConversationServer {}) => SuperTabController(tabId: 'tab',accountId: account,- request: request,+ request: (method, path, {body}) => runZoned(+ () => request(method, path, body: body),+ zoneValues: {_reader: account},+ ),save: save,upload: upload ?? this.upload,initial: initial ?? const {},diff --git a/desktop/tool/super_tab_local_review.dart b/desktop/tool/super_tab_local_review.dartnew file mode 100644index 000000000..d570c883b--- /dev/null+++ b/desktop/tool/super_tab_local_review.dart@@ -0,0 +1,130 @@+/// The Super Tab against a local, isolated backend, for review screenshots.+///+/// Build for web with `--dart-define=HARNESS_TEST=true` and serve it from a+/// loopback origin that passes `/api/` to the local backend of the local+/// backend recipe (fake SSO tokens, local MongoDB and Redis). Open it with+/// `?tab=<id>&as=owner|peer` and optionally `&open=pm` (that person's Chat+/// with PM, created on first use) or `&group=<id>`. It refuses any origin but+/// 127.0.0.1 and knows only the recipe's two fake test tokens: it never+/// reaches a real account or production data.+library;++import 'dart:convert';+import 'dart:js_interop';++import 'package:flutter/material.dart';+import 'package:harness/shared/theme/app_theme.dart' as grid;+import 'package:harness/shared/theme/color_palette.dart';+import 'package:harness/super_tabs/controller.dart';+import 'package:harness/super_tabs/model.dart';+import 'package:harness/super_tabs/view.dart';+import 'package:web/web.dart' as web;++const _people = {+ 'owner': ('local-owner-token', '[email protected]'),+ 'peer': ('local-peer-token', '[email protected]'),+};++Future<void> main() async {+ WidgetsFlutterBinding.ensureInitialized();+ try {+ await _review();+ } catch (error, stack) {+ // A review page that cannot load says why, on the page and in the console.+ debugPrint('Local review failed: $error\n$stack');+ runApp(+ MaterialApp(home: Scaffold(body: Text('Local review failed: $error'))),+ );+ }+}++Future<void> _review() async {+ final query = Uri.base.queryParameters;+ final person = _people[query['as'] ?? 'owner'];+ final tabId = query['tab'];+ if (Uri.base.host != '127.0.0.1' || person == null || tabId == null) {+ throw StateError('Local review needs a loopback origin, ?tab= and ?as=');+ }+ final (token, email) = person;+ Future<Map<String, dynamic>> request(+ String method,+ String path, {+ Map<String, dynamic>? body,+ }) async {+ final response = await web.window+ .fetch(+ path.toJS,+ web.RequestInit(+ method: method,+ headers:+ {+ 'authorization': 'Bearer $token',+ 'content-type': 'application/json',+ }.jsify()!+ as web.HeadersInit,+ body: body == null ? null : jsonEncode(body).toJS,+ ),+ )+ .toDart;+ final answer = superTabMap(+ jsonDecode((await response.text().toDart).toDart),+ );+ if (answer['success'] != true) {+ final error = superTabMap(answer['error']);+ throw SuperTabFailure(+ error['code'] as String? ?? 'ERROR',+ error['message'] as String? ?? 'Failed.',+ statusCode: response.status,+ );+ }+ return superTabMap(answer['data']);+ }++ // The account id the backend gave this person on first use.+ final first = await request('GET', '/api/super-tabs/$tabId/parts');+ debugPrint('review: first load read');+ final accountId = [+ for (final member in first['members'] as List)+ if ((member as Map)['data']['email'] == email) member['key'] as String,+ ].single;+ const palette = HarnessPalette.paper;+ grid.AppTheme.palette.value = palette;+ grid.AppTheme.brightness.value = palette.brightness;+ final controller = SuperTabController(+ tabId: tabId,+ accountId: accountId,+ request: request,+ save: (_) async {},+ pollInterval: Duration.zero,+ );+ debugPrint('review: account $accountId');+ await controller.refresh();+ debugPrint('review: refreshed, error ${controller.error}');+ final project = controller.snapshot!.projects.first.id;+ if (!controller.expandedProjects.contains(project)) {+ controller.toggleProject(project);+ }+ if (query['open'] == 'pm') {+ await controller.openPmChat(project);+ } else if (query['group'] case final group?) {+ await controller.select(group);+ }+ debugPrint('review: opened ${controller.selectedId}');+ await controller.loadMessages(controller.selectedId);+ debugPrint('review: messages loaded');+ runApp(+ MaterialApp(+ debugShowCheckedModeBanner: false,+ theme: grid.buildAppTheme(brightness: palette.brightness),+ home: Scaffold(+ body: SuperTabView(+ controller: controller,+ onInvite: () {},+ onAddAgent: (_) {},+ onOpenTerminal: (_) {},+ machineName: (_) => 'Local machine',+ ),+ ),+ ),+ );+}diff --git a/docs/design/2026-10-26-swarm-state-parts.md b/docs/design/2026-10-26-swarm-state-parts.mdnew file mode 100644index 000000000..f9f86e7fd--- /dev/null+++ b/docs/design/2026-10-26-swarm-state-parts.md@@ -0,0 +1,1201 @@+# Design: Swarm state by parts (#1726)++Group 1 design doc, 2026-10-26. Engineer (Hugo). Spec: [docs/plans/2026-10-26-swarm-state-parts.md](../plans/2026-10-26-swarm-state-parts.md)+(draft 2, its rulings, and the 2026-10-26 private conversations addendum). Issue: https://github.com/autonomous-ai/openharness/issues/1726++This document is the contract for groups 2–5. Where it says **must**, a builder implements exactly that; where it+says **Ruling**, it settles a point the spec left open or got wrong against the code, with the reason and the cost if+wrong. Section 8 lists those that need the Product Manager's or owner's confirmation before groups 2–5 start.++Citations are `path:line` on `feat/swarm-state-parts` at `83312cb7d`.++## 0. Summary++- Seven part collections replace `SuperTab.state`: **head**, **member** (one per person), **group**, **agent**,+ **machine**, **start**, **progress** (one per project). The `SuperTab` row stays as the Swarm's index row (member,+ invitation and machine lookups) and keeps the old `state` read-only.+- Every part has `version` (bumped by every write and every touch, never reset) and `changedAt` (stamped only when+ its data changes). Part `data` keeps today's JSON shape for that record, so the pure command layer+ (`applyCommand`) runs unchanged on a state reassembled from the parts a command loads.+- A command loads the Swarm's **active** parts (everything except dormant groups and finished starts, plus the ones+ it names, 3.1), runs+ `applyCommand`, writes only the parts whose data changed, and **touches** (version-guarded no-op bump) the parts+ whose invariants it read. Section 1 lists both for every command and writer.+- Reads: first load, changes since a cursor (`changedAt > cursor`, cursor = server read start − 30 s), dormant groups+ on demand, and a host form for the CLI. A visibility epoch on the head forces a full reload when who-sees-what+ changes. Old full-state routes answer HTTP 426 `UPDATE_REQUIRED`.+- Messages are numbered per group from the group's `messageSeq`, which starts at the tab's final revision; old+ numbers are kept.+- A conversation can carry an explicit **audience** (chosen people plus the project's Lead); it is enforced in one+ predicate used by every read path (section 4.8).++### Notation used in the tables++| Symbol | Part |+|---|---|+| `H` | head |+| `M(p)` | member part of person `p` |+| `A(a)` | agent part of agent `a` |+| `G(g)` | group part of conversation `g`; `GL` is the Leads conversation; `GP(p)` is project `p`'s Lead conversation |+| `Mc(m)` | machine part of machine `m` (exists for every machine the Swarm references, contributed or not; Ruling R1) |+| `S(s)` | start part |+| `P(p)` | progress part of project `p` |+| `X` | the `SuperTab` index row (not a part; never in the change feed) |+| `SA` | the actor's own part: `M(person)` for a person, `A(agent)` for an agent (spec ruling 2) |+| `Δrows` | rows in existing collections (messages, deliveries, receipts, runs, …) |++**W** = written (data changes, `changedAt` stamped). **T** = touched: read and guarded, `version` bumped, data+unchanged. A part that is written is never also listed as touched.++## 1. Commands and writers: parts read, written and guarded++### 1.1 Rules that apply to every row++These defaults hold for every command; the table adds what is specific.++- **D1 Actor.** Every command touches `SA` (spec ruling 2). Removing a person writes (tombstones) `M(p)`; removing an+ agent writes `A(a)`. An agent actor's contributor membership (`model.ts:294-300`) is guarded by rule (b):+ `member.remove` writes every agent the member contributed (`commands.ts:1290`).+- **D2 Groups it relies on.** A command that checks a group exists, is open, or reads its `agentIds`/`leadId`, and+ does not write it, touches it. `controls()` (`commands.ts:292-297`) reads the target group's `leadId`; the target+ group is then written or touched.+- **D3 Agents it names.** A command that names an agent (`agentId`, a recipient, a route candidate) and does not+ write it touches `A(agent)`.+- **D4 Messages.** A message written into group `g` writes `G(g)`: `messageSeq += 1` per message, and+ `lastMessageSequence`, `reportSeq`, `pullRequestUrls`, `lastActivityAt`, `dormant=false`. A shown message in a+ non-Lead project group writes `P(p)` only when the project goes from clean to dirty (spec ruling 1; section 3.6).+- **D5 Leads.** A change to `leadId` of a project's Lead conversation, or removal of an agent listed in `GL`,+ writes `GL` (its `agentIds`) and `H` (visibility epoch). That is the only place `syncLeads` writes (spec ruling 10).+- **D6 New agent.** Creating an agent (`agent.add`, `agent.started`) touches `H` (display names must stay unique,+ spec ruling 10) and `M(contributor)`, writes `Mc(machine)` (harness reservation, `commands.ts:1574-1584`) and+ writes `X` (machine reference).+- **D7 Finished work.** `finishWorker` (`model.ts:278-284`) writes `A(worker)` and every Reviewer whose decision+ changes, and writes `P(p)` (the project's worker-decision fence, Ruling R5).+- **D8 Group removals.** A command that removes an agent from groups finds them by the `agentIds` index, **dormant+ groups included**, and writes each (today `removeAgent` filters every conversation, `commands.ts:536-540`).+- **D9 Roles.** A command that chooses a custom role (`roleId` on `agent.add`, `agent.start`, `work.assign`) touches+ `H`, which holds the role sets, so a concurrent `project.role.*` conflicts.+- **D10 Delivery rows follow group rules (rule b).** `conversation.archive`, `conversation.agent` (`present:false`) and+ `conversation.audience` change what `deliveryAllowed` (`store.ts:1410-1425`) accepts without cancelling rows today.+ They must bump `updatedAt` on the affected queued/claimed/uncertain delivery rows (no status change; archive keeps+ today's "comes back when reopened" behavior), so a concurrent claim conflicts on the row (section 3.5).+ `conversation.audience` additionally cancels rows authored by people it removes.+- Side writes into existing collections (`SuperTabRun`, session scopes, configurations, role texts, route decisions,+ terminal requests, mentions, attachments, attempts, native contexts) are unchanged from today's `executeOnce`+ (`store.ts:661-838`) and are not repeated below.++### 1.2 Commands (all 61 command types)++`commandSchema` (`commands.ts:63-138`) defines 60 types; `conversation.audience` is added by the private+conversations addendum (4.8).++| Command | W (writes) | T (touches) | Invariants and the rule that guards each |+|---|---|---|---|+| `machine.contribute` | `Mc(m)`; `Mc` of the Mac's team pools (name, slots, pause, `commands.ts:832`); `S` of abandoned starts (error); `GP` of each project told; `X` when `m` is new | `H` when `m` is new | Not cleaning, no pending start on `m` (`commands.ts:806,823`): every start on `m` writes `Mc(m)`, rule (a). At most 32 machines: a new contribution touches `H`, rule (a). |+| `machine.pause` | `Mc(m)`, `Mc` of team pools | — | Contributor only, not removed: data of `Mc(m)`, written. |+| `machine.remove` | `Mc(m)` and team pools (removal or cleanup); `A` of every removed agent (tombstone); `G` of every group containing them (D8) with notices; `S` of pending starts on `m` (error); `H` (rules lose `m`, `commands.ts:572-582`); `X`; `Δrows` deliveries cancelled | — | No start dispatched on `m` (`commands.ts:550`): dispatch touches `Mc(m)`, (a). A Lead is never removed (`protectLead`, `commands.ts:307-312`): `agent.add` and `conversation.agent` that make an agent a Lead write or touch its `A`, which conflicts with the tombstone, (a). |+| `machine.cleaned` | `Mc(m)` (contribution or cleanup dropped); `X` (`cleanupMachineIds`) | — (the host may have left; no `SA`) | Removal id matches: data of `Mc(m)`. |+| `localModels.set` | `H` | — | Owner only: `H.ownerId`, immutable. |+| `localModels.status` | `H` | — | Grid matches: `H`. |+| `tab.rename` | `H` | `G('lead')` when the actor is an agent (`controls`) | Lead check, D2. |+| `tab.project` | `H` | `G('lead')` when agent | Not set yet: `H`. |+| `tab.pause` | `H` | `G('lead')` when agent | — |+| `tab.routingPolicy` | `H` | — | Owner only. |+| `rule.set` | `H` (rules); `GP(p)` (rule row) | — | At most 50 rules a project: `H`. Lead quoting the owner: `GP(p).leadId`, written. `askedIn` message is immutable. |+| `rule.remove` | `H`; `GP(p)` | — | as `rule.set` |+| `project.create` | `H` (projects); `G` of the new Lead conversation (insert) | — | At most 100 projects, not paused: `H`. |+| `project.rename` | `H` | — | Project owner: `H`. |+| `project.delete` | `H` (projects, rules, invitations, `retiredConversationNumber`, epoch); `G` of every group of the project, dormant included (tombstones); `A` of the project's agents incl. its Lead (tombstones); `S` of its starts (tombstones); `P(p)` (tombstone); `Mc` of their machines (closing sessions); `GL` (D5); `X`; `Δrows` deliveries cancelled, role texts | — | No active work, no pending start (`projects.ts:156-161`): `work.assign` writes `G`, `agent.start` touches `G`, (a). |+| `project.sharing` | `H` (visibility, members, epoch) | `M(p)` of every person who loses access | Readers of the project: rule (b), every command of a person touches `M(person)` (D1); claims touch the sender's `M` (3.5). |+| `project.cadence` | `H` | — | — |+| `project.report` | `P(p)` (`summarized` map, 3.6); `GP(p)` when `text` | `GP(p)` when `text` is null (Lead check) | Lead of the project: `GP(p).leadId`. Answers the wake-up delivery (`store.ts:815-822`). |+| `project.repository` | `H` | `GP(p)` when agent | Not already set: `H`. |+| `project.skills` | `H`; `GP(p)` (row); `G` of each "role gone" notice (`commands.ts:710-715`) | `GP(p)` if no row | Owner or Lead quoting the owner: `GP(p)`. |+| `project.roles.create` | `H` | — | No roles yet: `H`. |+| `project.role.set` | `H` | — | Roles in use (`commands.ts:273-283`): role choices touch `H` (D9), (a). |+| `project.role.remove` | `H` | — | as above |+| `project.roles.reset` | `H` | — | as above |+| `conversation.create` | `G` (insert, with `audience` when given, 4.8); `H` (group counter; `overlapAlerts` when an alert is added); `GL` (overlap row) | `GP(p)` (`controls`); `G(reviewOf)` | Numbering: `H.groupCounter`, written (spec ruling 10). Not paused: `H`. Reviewed group open: touched. |+| `conversation.rename` | `G` | — | Open: `G`. |+| `conversation.archive` | `G` (`archived`, `dormant`); `Δrows` delivery `updatedAt` (D10) | — | No active work: `G`. |+| `conversation.audience` *(new, 4.8)* | `G` (`audience`); `H` (epoch); `Δrows` deliveries (D10), native contexts revoked | `M(p)` of every person removed from the audience; `GP(p)` | Rule (b) for readers removed. Who may change it: `GP(p).leadId` or a person in the audience. |+| `agent.add` | `A` (insert, or existing); `G` (`agentIds`, `leadId`, initial message); `GL`+`H` when it becomes a project Lead (D5); `H` when it sets the project's repository; `Mc(m)` (D6); `X` | `H` (D6, D9); `M(contributor)` | `ALREADY_SHARED`: unique part key `(tabId, agentId)`, an insert race is P2002 (retryable). `STOP_REQUESTED`/existing kind: `A` written. |+| `agent.start` | `S` (insert); `G` override/rule rows when written | `G` (open, D2); `H` (pending starts ≤ 32, paused, rules, D9); `Mc(m)` and every `Mc` that `machineSlots` counts (Mac and team pool, `machines.ts:335-339`); `M(contributor)`; `P(p)` (worker decisions, R5) | Slots: rule (a), every slot consumer writes or touches `Mc`. 32 pending starts: `H` touch, (a). Route decision link: route decision row written. |+| `agent.startDispatch` | `S` (`dispatched`) | `Mc(m)` (re-admission); `H` (paused, rules); `G` (open); `P(p)` | Claimed once: `S`. |+| `agent.started` | `S`; `A` (insert); `G` (`agentIds`, row); `Mc(m)` (D6); `X` | `H` (D6); `M(contributor)` | `ALREADY_SHARED`: unique key. Start not failed: `S`. |+| `agent.startSettled` | `S`; `G` (row) | — | — |+| `agent.startFailed` | `S`; `G` (row) | — | Not started: `S`. |+| `agent.stopLease` | — (session scope row) | `A(target)` (= `SA`) | `releaseId` current: `A`. |+| `agent.remove` | `A` (tombstone); `G` of every group containing it (D8); `Mc(m)` (closing session, release, reservation); `X`; `Δrows` deliveries cancelled | — | No active work: `work.assign` writes or touches `A(worker)`, (a). Not a Lead: as `machine.remove`. |+| `agent.release` | `A(target)` | `GP(project)` (Lead check) | No active work and not reviewing: `work.assign` writes or touches the worker and the group's Reviewers, (a). |+| `agent.sessionClosed` | `Mc(m)` (closing dropped, harness released); `X` | — (no `SA`) | Closing request exists: `Mc(m)`. |+| `agent.configuration` | `A` | — | `previousVersion` matches: `A`. |+| `agent.rebind` | `A`; `G` of its active assignment | `Mc(m)` | One member per terminal (`commands.ts:1145`): every rebind on `m` touches `Mc(m)`, (a). |+| `conversation.agent` | `G`; `A(member)` when a Reviewer's decision clears; `GL`+`H` on a Lead change (D5); `Δrows` delivery `updatedAt` on removal (D10) | `A(member)` otherwise; `H` (rules) | Not stopping, same project: `A`. Active work: `G`. |+| `invite.create` | `H` (invitations); `X` (`invitedEmails`) | — | Not a member: `invite.accept` writes `H`, (a). |+| `invite.revoke` | `H`; `X` | — | — |+| `invite.accept` | `M` (insert); `H` (invitation removed); `X` (`memberIds`) | — (not yet a member) | Invitation valid: `H`. |+| `member.remove` | `M(p)` (tombstone); `Mc` of their machines (removal); `A` of agents they contributed and agents on their machines (tombstones); `G` containing them (D8); `S` pending on their machines (error); `H` (invitations, rules, epoch); `GL` (D5); `X`; `Δrows` deliveries cancelled, native contexts revoked | — | Their in-flight commands touch `M(p)` or their agents' `A`, (b). |+| `message.send` | `G` (D4); `P(p)` clean→dirty | `A` of each recipient (D3) | Postable (open, sender in `agentIds`): `G`. Recipient still a member: `A`. Lead↔worker loop bound reads the last 6 messages, immutable. |+| `mention.done` | — (mention row) | — | Own mention: mention row. |+| `delivery.resolve` | `G` (row); delivery row | `A(target)`; sender's `M` or `A` | `deliveryAllowed` on resend: as a claim (3.5). |+| `work.define` | `G`; D7 for the previous worker; `H`+`GL` when an overlap alert is added | — | No active work: `G`. |+| `work.assign` | `G`; `A(worker)` when its `workDecision`/`releaseId` clears; `A` of the group's Reviewers whose decision clears; `H`+`GL` on an overlap alert | `A(worker)` when nothing on it changes; `A` of the group's other Reviewers; `H` (paused, rules, D9); `P(p)` (R5); `S` of the worker's unsettled start (`commands.ts:1439`) | One active assignment per agent (`commands.ts:1458`): `A(worker)` written or touched, so two assignments of one agent conflict, (a); `SuperTabRun` unique id still backs it across Swarms. |+| `work.status` | `G`; on `done`/`stopped`, D7 | — | Current assignment: `G`. Stop proof: stop receipt row, immutable. |+| `work.cancel` | `G`; D7 | `GP(p)` (Lead check) | Current assignment: `G`. |+| `work.check` | `G` | — | Current assignment; independence: `G`. |+| `route.record` | `G` (route row); route decision row | `H` (rules); `A(candidate)`; `P(p)` (R5) | Pick allowed by rules: `H`. 30 routes an hour: route decision rows (insert-only count; a 31st concurrent record is tolerated, as today). |+| `route.override` | `G` (row); route decision row | `A(candidate)` | Decision open: route decision row. |+| `route.modelResult` | route decision row | `G(decision group)` (`controls`) | — |+| `agent.screen` | terminal request row | `A(target)`; `GP(target's project)` (`mayDrive`) | Ten waiting requests: terminal rows, as today. |+| `agent.input` | terminal request row; `G(currentGroup)` (row) | `A(target)`; `GP` | as above |+| `agent.screenResult` | terminal request row | `A(target)` (= `SA`) | Claimed request: terminal row. |+| `agent.inputResult` | terminal request row | `A(target)` | as above |+| `agent.alert` | `A` (`alerting`, `limitedUntil`); `G(currentGroup)` and `GP` rows | — | One row per episode: `A`. |++`currentGroup` (`terminal.ts:46-50`) picks the newest open group the agent is in; it must search dormant groups too+(D8 index) and the row wakes that group (D4), so terminal rows land where they land today.++### 1.3 Writers outside commands++| Writer | W | T | Invariants and guard |+|---|---|---|---|+| `create` (`store.ts:330-345`) | `H`, `M(owner)`, `G('lead')`, `GL`; `X` (insert) | — | New ids. |+| `observeMachine` (`store.ts:1269-1311`) | `Mc(m)` only, in the steady state (observation). Also, only when the value changes: `A(x).downSince` (`recordAgentPresence`, `machines.ts:264-271`); `Mc(m)` ledger when a stop proof matches a reservation; `Mc` of any machine of the tab whose removal expired (`expireRemovals`, `machines.ts:326-331`); `X` when a removal expired | — | Contribution current (`store.ts:1274-1275`): `member.remove` writes `Mc` of the member's machines, (b), so no `M` touch is needed. |+| Native turn append (`native.ts:179-230`) | `G` (D4: message, `messageSeq`, PR links, assignment `blocked` on a required recovery); `P(p)` clean→dirty; `Δrows` message, delivery to the Lead, native context `lastEventId`, receipt | `A(target)`; `M(operator)` | Operator still a writer, context valid (`native.ts:56-78`): `M(operator)` touched; agent binding: `A` touched; group open and agent present: `G` written; project access: `project.sharing` writes `M`, (b). |+| Delivery claim / ack (`store.ts:1492-1521`) | delivery row only | `A(receiver)`; sender's `M` or `A` (spec ruling 9) | Section 3.5. No Swarm-wide bump any more (`store.ts:1514` goes). |+| Hold notice (`store.ts:1524-1547`) | delivery row; on the first notice `G` (row) and a delivery to the Lead | `A(waiting agent)` | As a claim. |+| Deliveries wake-up (`store.ts:1434-1471`, a GET that writes) | `GP(p)` (update request message); `P(p)` (`requested` map, `requestedAt`, `requestMessageId`); `A(x).downNamed` of each down worker named | `A(Lead)` (= `SA`) | One request per state: stable message id, P2002 on a race (retryable, as today). |+| Stopped receipt (`store.ts:1559-1610`) | `G` (assignment `stopped`, notice); D7; `A(worker).downSince` | — (host is the machine owner, maybe not a member) | Execution matches: `G`. |+| `saveSharing` (`store.ts:377-399`) | `H` (`sharing`) | `M(owner)` | `sharing.revision` matches: `H`. No epoch (sharing is owner-only and never in a read). |+| `join` (`store.ts:412-444`) | `M` (insert) when new; `X` (`memberIds`) | `H` (sharing generation) | A concurrent `saveSharing` writes `H`, (a). |+| `read()` backfill (`store.ts:451-456`) | **removed** | — | The migration backfills `pullRequestUrls` for every group (section 6); reads never write (Ruling R8). |+| Archive sweep (new, worker) | `G` (`dormant=true`) for groups idle 24 h with work done or cancelled | — | Guarded write on `G.version`; a message in between bumps the version and the sweep skips it. |+| Expiry sweep (new, worker) | `S` (tombstone) for starts finished 7 days; `H` (expired invitations removed); purge of tombstones older than 7 days (TTL index) | — | Guarded writes. |++### 1.4 Whole-state passes (spec ruling 10)++| Pass (today) | Today runs | Serializes on | New behavior |+|---|---|---|---|+| `syncLeads` (`model.ts:336-342`) | every read and command | `GL` | Written only by D5. Readers derive nothing. |+| `numberConversations`, `nextConversationNumber`, `retiredConversationNumber` (`model.ts:346-355`) | every command | `H.groupCounter` | `conversation.create` takes `++groupCounter`. The migration fills missing numbers and sets the counter to `nextConversationNumber − 1`; `project.delete` no longer needs a retired number (the counter never decreases), but the old field is kept on `H.data` for reassembly. |+| `placeRules` (`projects.ts:178-185`) | every command and read | `H` | The migration places every rule; `rule.set` always sets `projectId`. No runtime pass. |+| `expireRemovals` (`machines.ts:326-331`) | every command, read and observation | `Mc(m)` | Applied as a view on every read; written by `observeMachine` and by any command that writes that `Mc`. |+| `assignAgentDisplayNames` (`agentNames.ts:21-42`) | every command and read | `H` (touch) | Run at agent creation over all agents (D6). The migration persists every name. |+| `appendPullRequestUrls` (`model.ts:140-149`) | every command, all groups | `G(g)` | Only for groups the command writes. |+| `restorePullRequestUrls` (`store.ts:49-68`) | every read and command | — | Migration only (R8). |+| `noteProjectReports` (`projectUpdates.ts:7-18`) | every shown message | `P(p)` | Clean→dirty only (3.6). |+| `parkLaterConversations` (`model.ts:310-317`) | every load | — | A group part of an unknown `kind` is skipped by the loader; nothing to park. |+| `awaitingWorkers` / `finishWorker` (`model.ts:261-284`) | start, assign, route | `P(p)` (R5) | The migration persists the derived `awaiting` decision of legacy workers. |+| `alertOverlaps` pruning (`commands.ts:602`) | create, define, assign | `H` | Prunes only pairs whose group part is tombstoned (existence by id, dormant groups count as existing). |+| `recordingProgress` stamp (`store.ts:694-702`), `lastMessageSequence` (`store.ts:716`) | message commands | `G(g)` | `recordingProgress.revision` becomes the group's `messageSeq` after the command (3.6). |+| `revokeNativeContexts`, `endedHolds` (`native.ts:234-263`, `store.ts:770`) | every command (diff) | — | Diff of the parts the command wrote; every change they detect is in a written part. |+| `TAB_TOO_LARGE` 8 MiB (`commands.ts:1561`) | every command | — | Per part: refuse a write whose part `data` exceeds 4 MiB (`PART_TOO_LARGE`, 413). No whole-Swarm limit. |+| `indexes()` (`store.ts:69-75`) | every write | `X` | Written only by commands that add or remove a person, invitation or machine reference (listed above); those always write `X`, so two of them conflict instead of one losing an id. |++## 2. Storage: Prisma models++### 2.1 Common shape++Every part model has these fields. Group 2 may name the Prisma models; the names below are used in this doc.++```prisma+model SwarmGroup { // likewise SwarmHead, SwarmMember, SwarmAgent, SwarmMachine, SwarmStart, SwarmProgress+ id String @id @map("_id") // `${tabId}:${key}`+ tabId String+ key String // conversation id (agent id, person id, machineId, start id, project id; "head" for SwarmHead)+ version Int // bumped by every write and touch; never reset (spec ruling 6)+ changedAt DateTime // stamped when data changes or the part is tombstoned (3.3)+ deleted Boolean @default(false) // tombstone+ purgeAt DateTime? // tombstone: changedAt + 7 d (TTL index); finished start: see SwarmStart+ ordinal Float // reassembly order (6.2): migrated index, then the creation time in ms+ data Json // today's record, in today's JSON shape+ // per-model extracted fields below+ @@unique([tabId, key])+ @@index([tabId, changedAt])+}+```++- `version` starts at the tab's final revision `R` for migrated parts. A part created later starts at+ `H.sequenceBase + 1` (`R + 1` in a migrated Swarm, 1 in a new one), so a recreated key whose tombstone was+ already purged still sorts after its old configuration rows. A part recreated while its tombstone exists (an+ agent contributed again) updates the tombstone: `deleted=false`, `version+1`.+- `changedAt` is not bumped by a touch. Clients merge by `version` (a higher version replaces a lower one), so a+ touched part they hold at a lower version is simply replaced at its next data change.+- TTL index on `purgeAt` (`expireAfterSeconds: 0`), created by the worker at startup like `ensureTerminalExpiry`+ (`terminal.ts:17-20`).++### 2.2 Per-model fields++| Model | `data` holds (today's shape) | Extracted fields and indexes |+|---|---|---|+| `SwarmHead` (one per Swarm) | `SuperTabState` scalars and settings: `version:1`, `id`, `name`, `project`, `projects` (**without** `progress`), `leadsConversationId`, `overlapAlerts`, `ownerId`, `environment`, `routingPolicy`, `rules`, `sharing`, `paused`, `invitations`, `retiredConversationNumber`, `localModels` | `groupCounter Int`, `visibilityEpoch Int`, `sequenceBase Int` (the migration's `R`; 0 for a new Swarm). Index `[tabId]` via the unique key. |+| `SwarmMember` (one per person) | `Person` `{id, email, role, generation}` | `personId String`. People live only here, not on the head (Ruling R2). |+| `SwarmGroup` (one per conversation, Leads included) | `Conversation` as today, plus `messageSeq`, `reportSeq`, `dormant`, `lastActivityAt` (ISO), `audience?` (4.8) | `projectId String?`, `kind String?`, `archived Boolean`, `dormant Boolean`, `agentIds String[]`, `executionMachineId String?` (active assignment), `messageSeq Int`, `reportSeq Int`, `lastActivityAt DateTime`. Indexes: `[tabId, dormant, changedAt]`, `[tabId, agentIds]`, `[tabId, projectId, dormant, lastActivityAt]`, `[tabId, projectId, dormant, reportSeq]`, `[dormant, lastActivityAt]` (sweep), `[executionMachineId]`. |+| `SwarmAgent` | `Agent` as today | `machineId`, `machineOwnerId`, `contributorId`. Indexes `[machineId, deleted]`, `[tabId, contributorId]`. |+| `SwarmMachine` (per machine the Swarm references) | `{ machineId, contribution: ContributedMachine \| null (incl. observation), reservations: [{harnessId, generation, renewed}], released: [harnessId] (newest last, capped at 200), closingSessions: [{agentId, harnessId, machineOwnerId}], cleanups: [{removalId, machineOwnerId}] }` | `machineId`, `contributed Boolean`, `cleanupOwnerIds String[]`. Index `[machineId, deleted]`. |+| `SwarmStart` | `AgentStart` as today | `machineId`, `conversationId`, `agentId String?` (once it has a harness, 3.1), `finishedAt DateTime?` (set when it errors, or has a harness and is settled or not pooled). The expiry sweep tombstones a start 7 days after `finishedAt`; until then a command that matches it loads it by key or `agentId`. Index `[tabId, finishedAt]`, `[machineId, finishedAt]`, `[tabId, agentId]`. |+| `SwarmProgress` (one per project with stored projects) | `{ since, summarizedFloor, summarized: {groupId: seq}, requestedFloor, requested: {groupId: seq}, requestedAt?, requestMessageId? }` (3.6) | `projectId`. |++**Group `data` fields added:**+- `messageSeq`: the last sequence given to a message in this group. A group created after the migration starts at+ `H.sequenceBase`, so its sequences are always above every pre-migration value (needed by the legacy+ `throughRevision` rule in 3.6).+- `reportSeq`: the sequence of its last message that counts for project reports (today's `noteProjectReports` set).+- `dormant` and `lastActivityAt`: the active set (Ruling R3).+- `audience`: section 4.8.++`lastMessageSequence` keeps its meaning: the sequence of the last shown message.++### 2.3 What stays in existing collections++- `SuperTab` (`schema.prisma:996-1014`) becomes the **index row**. It keeps `memberIds`, `invitedEmails`,+ `machineIds` and `cleanupMachineIds`, maintained as in 1.4, and `revision`, which the migration sets to `R+1`. It+ gains `format Int @default(1)` (2 once migrated), `migratedAt DateTime?` and `legacyState Json?`. The migration+ moves the old state there unchanged and read-only, and leaves `state = { "version": 2 }` as the data fence+ against old processes (6.1.1, R14).+ - `machineIds` stays the union of agents', contributions', closing sessions' and cleanups' machines. Active+ assignments' machines are dropped from the union: an assignment's machine is its agent's, or a closing session's+ once the agent is removed (`commands.ts:529-533`).+- Unchanged collections: messages, deliveries, operations, native contexts, runs, attempts, route decisions, stop+ receipts, role texts, terminal requests, mentions, attachments, session scopes and routing policies. Their only+ changes:+ - `SuperTabMessage.sequence` is the group sequence for new rows. The index `[tabId, conversationId, sequence]`+ (`schema.prisma:1050`) becomes `[tabId, conversationId, sequence, id]` for the `(sequence, id)` page cursor (4.6).+ - `SuperTabOperation` gains `parts Json?`, the reply's part versions (4.7). `revision` keeps its stored value on+ old receipts and is `0` on new ones (spec ruling 8).+ - `SuperTabConfiguration.revision` stores the agent part's new `version`. Versions start at `R`, so a new row+ always sorts after every older row of that agent (`schema.prisma:1234`).++## 3. Concurrency++### 3.1 Transaction shape (every command)++```text+transaction(db, async tx => { // store.ts:101-123, unchanged retry/backoff, timeout 15 s+ stamp = clock.next() // per attempt (3.3)+ view = loadActive(tx, tabId, named) // H, all M, all live A, non-dormant G, all Mc, unfinished S, all P,+ // plus groups the command names by id (dormant ones too),+ // plus D8 groups by agentIds when the command removes agents,+ // plus finished starts it matches (below)+ state = reassemble(view) // SuperTabState shape, parts in ordinal order (6.2)+ ...actor, team, receipt and context reads exactly as executeOnce today (store.ts:519-650)+ effects = applyCommand(state, actor, command, context) // pure, unchanged except the audience rule (4.8)+ plan = diffParts(view, effects.state) // per part key: insert / update data / tombstone+ touch = touchesFor(command, actor, view, effects) // section 1 T column, minus parts already in plan+ for p in plan ∪ touch: guardedWrite(p) // 3.2+ messages: per group in plan, seq = ++messageSeq per message, in draft order+ side collections exactly as today, minus every use of the tab revision+ receipt: { result, parts: [{kind, key, version}] }+})+```++- **Finished starts a command matches stay loadable** until the expiry sweep tombstones them, 7 days after+ `finishedAt`. Two places look a finished start up:+ - `work.assign` with a `routeDecisionId` loads the start named by the decision's `final.startId`, so+ `started(d)` matches the routed worker as today (`commands.ts:1471-1478`).+ - `agent.remove` by the agent itself loads the start whose `agentId` equals the removed agent, to close its route+ hold (`store.ts:785-789`).+ - `SwarmStart` therefore extracts `agentId = stableId(request.machineId, harnessId)` once it has a harness+ (`commands.ts:1109`, 2.2).+ - Slot counts do not need finished starts. A started harness is also counted through its agent or its+ reservation, which a person's removal keeps (`commands.ts:1216-1219`, `machines.ts:341-364`).+- The loaders read with snapshot semantics. A stale read is caught only by a write to the same part, which is+ why section 1 lists touches.+- `loadActive` costs what today's full read costs, minus dormant groups and finished starts. Group 0's benchmark+ measures it.++### 3.2 Guarded write++- Every part write and touch is+ `updateMany({ where: { id, version: seen }, data: { version: seen + 1, ...dataFields } })`. `dataFields` is+ `{ data, changedAt: stamp, deleted, purgeAt, ...extracted }` for a write and empty for a touch.+- A count of 0 throws a `PartConflict` (code `P2034` so `retryable()`, `store.ts:119-123`, keeps working+ unchanged).+- An insert is `create` on the unique `[tabId, key]`. A race raises P2002, which is already retryable.+- The guard does not depend on the transaction's read concern. It checks the committed version at write time.+ Mongo's own write conflict, a `TransientTransactionError`, also retries.++### 3.3 Retry, timeout and the `changedAt` clock++- Retry stays #1722's: 8 attempts, jittered backoff from 50 ms capped at 1.5 s, `SWARM_BUSY` (503) at the end,+ `maxWait 5 s`, `timeout 15 s` (`store.ts:101-123`). The timeout must stay ≤ 15 s, because the cursor overlap+ depends on it.+- **Backend processes.** The number is not fixed in this repository. Production runs `Dockerfile.k8s`: one `node+ dist/server.js` per container. ArgoCD sets the replica count outside this repo (`.github/workflows/production-be-build.yaml:69`,+ `backend/README.md:85-88`). The Docker image runs a pm2 cluster with `instances: 'max'`+ (`backend/ecosystem.config.cjs.docker`), plus one `backend-worker`. Several processes write Swarm state at once.+ The design assumes **N ≥ 2 writers on different hosts** and does not depend on N.+- **Clock source.** Each process's wall clock (`Date.now()`), made strictly increasing per process:+ `next() = max(Date.now(), last + 1)`, in ms. One stamp covers all parts of one attempt, and is taken again on+ retry.+ - Mongo's server clock (`$currentDate`) would remove cross-host drift. Prisma's `updateMany` cannot express it+ without raw commands, so it is not used.+- **Overlap.** 30 s = the 15 s transaction timeout + 15 s budget for clock drift between pods. Nodes are assumed+ NTP-synced well inside that budget (section 8, Q6). A part committed after the read start `T0` has+ `changedAt ≥ T0 − 15 s − drift > T0 − 30 s`, so the next poll (cursor `T0 − 30 s`) sees it.++### 3.4 The actor part touch (spec ruling 2)++- `SA` is touched by every command (D1) and by native appends, claims, acks and holds (1.3).+- A person's removal tombstones `M(p)`, and an agent's removal tombstones `A(a)`. An action already in flight by+ that actor then conflicts and retries against the new state, where `author()` refuses it.+- Cost:+ - An agent's own commands serialize with each other, which they already are in practice (one session).+ - They also serialize with claims of its own deliveries (same host), and with `observeMachine` only when its+ presence actually flips.+ - The Lead's part is the busiest. It is touched by its commands and by claims of its deliveries, all from one+ host.++### 3.5 Delivery claim, ack and hold (spec ruling 9)++- **Loads:** `H`, all `M`, the receiving and sending agents' `A`, the delivery's group, and `GP` of its project.+ Not the whole active state.+- **Checks:** `deliveryAllowed` and `senderAllowed` stay as they are (`store.ts:1410-1432`), plus the audience+ rule (4.8).+- **Touches:** `A(receiver)`, and `M(sender)` or `A(sender)`. **Writes:** the delivery row only.+- **Revocation** keeps cancelling delivery rows (`store.ts:823-833`, `native.ts:259-261`), so a claim and a cancel+ conflict on the row.+- **Group-level changes** that do not cancel rows today (archive, removal from a group, a new audience) bump the+ rows' `updatedAt` (D10), so they conflict on the row too.+- **Exactly once** is unchanged: `claimId` on the row. The existing integration cases must pass unmodified:+ "allows one claim winner and preserves the original native receipt", "serializes revocation against claims and+ exposes no pending instruction after removal", and "durably resumes a claim, never steals it on timeout…"+ (`backend/integration/superTabs.test.ts:1535-1582`).++### 3.6 Project progress watermark (spec ruling 1) and `recordingProgress`++- **Per group:** `reportSeq` is set by every message that `noteProjectReports` counts today: shown messages and+ native turns in a non-Lead project group. Hold notices and stop notices bump `lastMessageSequence` but not+ `reportSeq`, as today (`store.ts:1538`, `store.ts:1597`). They do not mark a project dirty. Ruling R12.+- **Dirty on read:** group `g` of project `p` is dirty when `g.reportSeq > (P.summarized[g] ?? P.summarizedFloor)`.+ The project is dirty when any of its groups is. Private groups never count (4.8).+- **Dormant groups stay in the report check until the Lead acknowledges them** (review round 1). The dirty check+ reads the project's active groups plus its dormant groups with `reportSeq > P.summarizedFloor`. That is one query+ on the extracted `reportSeq` (index `[tabId, projectId, dormant, reportSeq]`, 2.2), filtered by the `summarized`+ map. A dormant group leaves the check once `summarized[g] ≥ reportSeq`.+ - `message.send` and native appends use the same check to decide the clean→dirty write.+ - The wake-up's `through` map includes those dormant groups.+- **Write on the change from clean to dirty only:** `P.since = now`. Posts in different groups of a dirty project+ never write `P`.+- **Wake-up (`projectUpdateRequest`, `projectUpdates.ts:35-66`).**+ - `through` = `{g: reportSeq}` for the dirty groups.+ - Reports are due when some dirty group has `reportSeq > (P.requested[g] ?? P.requestedFloor)` and+ `now ≥ max(requestedAt, since) + cadence`.+ - Writing the request sets `P.requested = through`, `requestedAt` and `requestMessageId`.+ - The message id is `stableId('project-update', tab, project, canonical JSON of through, …down)`.+ - The text names the groups by number and sequence (for example "#12 after 213990, #14 after 214002") in place of+ "with lastMessageSequence after N".+ - The JSON it asks for is `{"type":"project.report","projectId":"…","through":{"<groupId>":214031,…},"text":"…"}`.+- **`project.report`.** The schema accepts `through: Record<id, int>`. The legacy scalar `throughRevision` is+ accepted only when it is ≤ `H.sequenceBase`, meaning a wake-up from before the migration; it then applies to+ every group. Anything else fails with 400 `THROUGH_REQUIRED`.+ - Effect: `summarized[g] = max(summarized[g] ?? floor, min(through[g], g.reportSeq))`.+ - The wake-up delivery is answered when `through[g] ≥ requested[g]` for every `g` in `requested`.+- **Worker-decision fence (Ruling R5).**+ - `P(p)` is also the part that `requireWorkerDecisions` (`model.ts:270-276`) serializes on. `finishWorker` writes+ `P(p)` (D7).+ - The Lead commands that run the check touch `P(p)`: `agent.start`, `agent.startDispatch`, `work.assign` and+ `route.record`.+ - Without this, a worker finishing in group A while the Lead assigns in group B would let the assignment pass+ over a decision that is now due.+- **`recordingProgress`** (`model.ts:105`, stamped at `store.ts:694-702`). Its `revision` is now the group's+ `messageSeq` after the command.+ - Native recovery (`native.ts:157-162`) looks up `{conversationId, sequence: revision}` as today. Stored values+ from before the migration are tab revisions ≤ `R`, which are still valid message sequences in that group+ (spec ruling 7).++### 3.7 `lastChangedAt` (spec ruling 8): computed when read++- **Choice:** computed, not stored (spec ruling 8 leaves the choice to this group). A stored head field written on every command is the hotspot again. A+ best-effort write after commit can be lost by a crash, and the host form must not miss a change.+- **Single Swarm:** `max(changedAt)` over its seven collections. That is seven index-only `findFirst` calls on+ `[tabId, changedAt]`, done once per response.+- **List and host form:** one aggregate per collection:+ `{$match:{tabId:{$in:ids}}},{$sort:{tabId:1,changedAt:-1}},{$group:{_id:'$tabId',t:{$first:'$changedAt'}}}`.+ It uses the `[tabId, changedAt]` index, so Mongo can use a DISTINCT_SCAN. That is seven queries for up to 100+ Swarms. Group 0's benchmark records the cost.+- A touch does not move `changedAt`, so `lastChangedAt` moves only when data changes.++## 4. Read API contract++### 4.1 Conventions++- All responses use the existing envelope and `respond()` error mapping (`backend/src/routes/superTabs.ts:55-60`).+ The examples show the `data` payload.+- Times are epoch milliseconds (numbers). Part `data` keeps today's ISO strings where today's record has them.+- **Paths must match the daemon proxy's pattern** `^/api/super-tabs(/[A-Za-z0-9_-]+)*(\?[A-Za-z0-9_=&%-]+)?$`+ (`cli/src/superTabs/service.ts:275-282`), because Desktop and web reach the backend through it. Cursors are+ therefore unpadded base64url.+- `asAgentId` works on every read as it does today (`agentQuery`, `backend/src/routes/superTabs.ts:25`).+- **Part envelope.** Live: `{ "key": "<id>", "version": 213995, "changedAt": 1793010101002, "data": { … } }`.+ Tombstone: `{ "key": "<id>", "version": 213996, "changedAt": 1793010102000, "deleted": true }`. A group that went+ dormant (4.4): `{ "key": "<id>", "version": 214000, "changedAt": …, "dormant": true }`.+- **`data` is the reader's view** of the part: today's `visibleState` (`model.ts:392-459`) applied per part. That+ means: `sharing`, `overlapAlerts`, the machine ledger, `downNamed`, `parkedConversations` and+ `retiredConversationNumber` are dropped. Projects, rules, groups, agents, starts and invitations are filtered by+ what the reader may see. The Leads group is shown only to people and Leads, with its `agentIds` cut to visible+ agents. `privacy.detail` goes only to the contributor. Invitations go only to the owner. A machine's observed+ harness ids are cut to the reader's visible agents and starts.+- **`derived`** is recomputed in full on every response (spec ruling 4). It holds the values that change without a+ part changing: time-based values, and values that depend on several parts. Clients overlay it on the parts.++```jsonc+"derived": {+ "agents": { "<agentId>": { "downSince": "2026-10-26T10:19:51.474Z", "limitedUntil": null,+ "workDecision": "awaiting", "roleId": "dev" } },+ "machines": { "<machineId>": { "availableSlots": 2, "teamWork": { "allowed": true } } },+ "otherProjectsWork": [ { "conversationId": "…", "projectName": "Web", "title": "…", "owns": ["desktop/lib"],+ "status": "working", "agentName": "Hugo", "pr": null } ], // a Lead agent only+ "mentionsWaiting": 2 // a person only+}+```++Every agent the reader can see has an entry in `derived.agents`; `workDecision` is `null` when the stored value+stands. Every contributed machine has an entry in `derived.machines`. These are the fields `store.ts:461-468` and+`model.ts:403-456` compute today.++### 4.2 Cursor, epoch and reload++- The cursor is opaque to clients: base64url of `{"v":2,"t":<ms>,"e":<epoch>}`. The server makes it at the+ **start** of handling the read: `t = T0 − 30 000` (spec ruling 3), where `T0` is the server's clock when the+ handler starts, before any query.+- `GET …/changes` answers `{"reload": true}` (HTTP 200) instead of changes in any of these cases:+ - the cursor does not parse or has `v ≠ 2`;+ - `e` differs from the head's current `visibilityEpoch` (spec ruling 4);+ - `t < now − 7 d + 1 h`, because tombstones are purged after 7 days (spec ruling 6).+ The client then does a first load.+- **The visibility epoch is bumped by:**+ - `project.sharing`, `project.delete`, `member.remove` (including leaving), and `conversation.audience`;+ - any write of `GL`'s `agentIds` (D5), because who is a Lead decides who sees the Leads group;+ - `invite.accept` and `join` do **not** bump it: a new member's own client does a first load, and nobody else's+ view changes.++### 4.3 First load++`GET /api/super-tabs/:tabId/parts[?asAgentId=]`++```jsonc+{+ "format": 2,+ "tabId": "c51479bd73b59e58176ad9e4",+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDc0Mzc1LCJlIjozfQ",+ "serverTime": 1793010104375,+ "lastChangedAt": 1793010101002,+ "epoch": 3,+ "githubApp": true, // as today (routes/superTabs.ts:151)+ "head": { "key": "head", "version": 213990, "changedAt": 1793009000000,+ "data": { "version": 1, "id": "c51479bd73b59e58176ad9e4", "name": "openharness", "ownerId": "6a86…",+ "environment": "prod", "paused": false, "leadsConversationId": "…",+ "projects": [ { "id": "5701…", "name": "openharness", "ownerId": "6a86…", "leadConversationId": "…",+ "visibility": "public", "members": [], "updateMinutes": 5, "skillMode": "default",+ "skillSet": "default" } ],+ "rules": [], "invitations": [], "localModels": { "grid": "swarm-…", "enabled": true } } },+ "members": [ { "key": "6a86…", "version": 213990, "changedAt": 1793000000000,+ "data": { "id": "6a86…", "email": "[email protected]", "role": "owner", "generation": "c514…" } } ],+ "agents": [ { "key": "0540…", "version": 214010, "changedAt": 1793010090000,+ "data": { "id": "0540…", "projectId": "5701…", "machineId": "7835…", "harnessId": "2973…",+ "machineOwnerId": "6a91…", "contributorId": "6a91…", "membershipGeneration": "02c4…",+ "hostGrant": null, "name": "Builder", "displayName": "Hugo",+ "configuration": { "engine": "claude", "model": "opus", "effort": "high",+ "contextWindow": null, "engineVersion": null } } } ],+ "groups": [ { "key": "aeef…", "version": 214031, "changedAt": 1793010101002,+ "data": { "id": "aeef…", "projectId": "5701…", "number": 204, "title": "1726 G1: design doc…",+ "leadId": "0fcb…", "agentIds": ["0fcb…", "0540…"], "archived": false,+ "brief": "Goal: …", "task": { "goal": "…", "changes": "…", "constraints": "…", "owns": ["docs/design/…"] },+ "checks": [ { "id": "b936…", "description": "…", "independent": false, "evidence": null, "passedBy": null } ],+ "assignment": { "id": "09d0…", "agentId": "0540…", "status": "working", "result": null,+ "configuration": { "engine": "claude", "model": "opus", "effort": "high",+ "contextWindow": null, "engineVersion": null },+ "execution": { "machineId": "7835…", "harnessId": "2973…", "machineOwnerId": "6a91…" },+ "recordingProgress": { "at": 1793010104375, "revision": 219804 } },+ "lastMessageSequence": 219804, "messageSeq": 219804, "pullRequestUrls": [] } } ],+ "machines": [ { "key": "7835…", "version": 214020, "changedAt": 1793010100000,+ "data": { "machineId": "7835…", "name": "MacBookPro2021", "contributorId": "6a91…", "scope": "swarm",+ "engines": ["claude", "codex"], "maxAgents": 4, "paused": false, "cwd": "/Users/…",+ "generation": "…", "membershipGeneration": "…",+ "observation": { "receivedAt": 1793010099000, "resources": { … }, "quotas": [ … ],+ "runningHarnessIds": ["2973…"], "stoppedHarnessIds": [] } } } ],+ "starts": [ ],+ "progress": [ { "key": "5701…", "version": 214001, "changedAt": 1793009900000,+ "data": { "since": 1793009900000, "summarizedFloor": 213800, "summarized": { "aeef…": 219700 },+ "requestedFloor": 213800, "requested": {}, "requestedAt": null } } ],+ "derived": { "agents": { "0540…": { "downSince": null, "limitedUntil": null, "workDecision": null, "roleId": null } },+ "machines": { "7835…": { "availableSlots": 3, "teamWork": { "allowed": true } } },+ "mentionsWaiting": 0 }+}+```++- **Machine `data`** is the contribution as `state.machines[]` has it today (`machines.ts:7-31`). Machines with no+ contribution are not sent: the ledger is never readable (`model.ts:410-415`).+- **Groups** are the reader's visible non-dormant groups. Dormant ones are fetched on demand (4.4).+- **Starts** are unfinished starts and starts finished within 7 days, as today minus the expired ones.++### 4.4 Changes since a cursor++`GET /api/super-tabs/:tabId/changes?cursor=<cursor>[&asAgentId=]`++```jsonc+{+ "format": 2, "reload": false,+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDc3Mzc1LCJlIjozfQ",+ "serverTime": 1793010107375, "lastChangedAt": 1793010106120, "epoch": 3,+ "head": null, // or the head envelope when it changed+ "members": [], "agents": [],+ "groups": [ { "key": "aeef…", "version": 214033, "changedAt": 1793010106120, "data": { …whole group… } },+ { "key": "9c1d…", "version": 214040, "changedAt": 1793010105000, "dormant": true },+ { "key": "77ab…", "version": 214041, "changedAt": 1793010105500, "deleted": true } ],+ "machines": [ { "key": "7835…", "version": 214050, "changedAt": 1793010105900, "data": { … } } ],+ "starts": [], "progress": [],+ "derived": { … complete, as in 4.1 … }+}+```++- **The server returns** every part the reader can see with `changedAt > cursor.t`, each whole. Dormant groups+ come back as the one-line stub until they change again (spec ruling 5).+- **A part the reader can no longer see** never appears with data: any change that makes one invisible bumps the epoch.+- **Tombstones and dormant stubs pass the same read check as live parts.**+ - A tombstone keeps the part's last live `data` on the server; it is never sent.+ - A stub or tombstone goes only to a reader who could read that last data: `canReadGroup` for a group (audience+ included), `canReadAgent` for an agent, a start's group for a start, the machine rules for a machine. Members+ and the head are visible to every member.+ - Where the check cannot be made because the project is gone, the change bumps the epoch, and every reader reloads.+ `project.delete` already bumps the epoch (4.2).+ - A private group's stub, removal or key never reaches anyone outside its audience.+- **The client merges** by `(kind, key)`, keeping the higher `version`. A tombstone removes the part. A dormant stub+ moves the group out of the active list. The client replaces `derived` and moves to the returned `cursor`.+ Overlap duplicates have equal versions and are ignored.+- **Messages are not in the feed.** A group's `lastMessageSequence` tells the client there is something to read,+ and it pages messages per group as today (4.6).++### 4.5 Dormant groups on demand++- `GET /api/super-tabs/:tabId/groups?dormant=1[&projectId=<id>][&before=<cursor>][&asAgentId=]`: dormant groups+ the reader may see, newest activity first, 50 per page.++```jsonc+{ "groups": [ { "key": "9c1d…", "version": 214040, "changedAt": 1793010105000, "data": { …whole group, "dormant": true… } } ],+ "next": "eyJsYSI6MTc5MzAwMDAwMDAwMCwiayI6IjljMWQifQ" } // base64url {"la":lastActivityAt,"k":key}; null at the end+```++- `GET /api/super-tabs/:tabId/groups/:conversationId[?asAgentId=]`: one group, active or dormant.+ Returns `{ "group": <envelope> }`, or 404 `NOT_FOUND` when unreadable.+- The messages, attempts and route-decision routes accept a dormant group's id as they accept an archived one today.++### 4.6 Messages (unchanged path, new sequence source)++- `GET /api/super-tabs/:tabId/conversations/:conversationId/messages?after=|before=|messageId=` is unchanged+ (`store.ts:1126-1152`), except that the response drops `revision`.+- `sequence` is per group and strictly increasing for new messages. Old messages keep theirs, ties included+ (spec ruling 7).+- **Pages use a stable `(sequence, id)` cursor** (review round 1). Today a page boundary inside a run of equal+ sequences skips rows (`store.ts:1135`, `1145`).+ - Rows are ordered by `(sequence, id)`, ascending forward and descending backward.+ - Request: `after=<sequence>&afterId=<id>` or `before=<sequence>&beforeId=<id>`, two plain parameters so the+ daemon's path pattern still passes.+ - `after` without `afterId` means strictly after that sequence. That is enough for polling new messages, which+ always have fresh sequences.+ - `before` without `beforeId` means strictly before.+ - Forward: `sequence > s OR (sequence = s AND id > i)`. Backward: the mirror.+ - Response: `"next": { "sequence": 213990, "id": "9f2c…" }`, or `null`.+ - Index: `SuperTabMessage` `[tabId, conversationId, sequence, id]`, which replaces `[tabId, conversationId, sequence]`+ (2.3).+- A message posted to a dormant group makes it active: it comes back in the feed as a full group.++### 4.7 Command reply++`POST /api/super-tabs/:tabId/commands` (body unchanged except the schema changes in 3.6 and 4.8):++```jsonc+{ "result": { "messageId": "…" },+ "parts": [ { "kind": "group", "key": "aeef…", "version": 214033 },+ { "kind": "progress", "key": "5701…", "version": 214034 } ],+ "lastChangedAt": 1793010106120 }+```++- `parts` lists the parts the command **wrote**, never the ones it only touched. `kind` is one of `head`, `member`,+ `agent`, `group`, `machine`, `start`, `progress`. This replaces `revision` (spec ruling 8).+- A replayed receipt returns the stored `parts`. A receipt from before the migration returns+ `{ "result": …, "parts": [], "legacyRevision": 213990 }`.+- Other replies that carried `revision`:+ - `POST /api/super-tabs` → `{ "id" }`+ - `POST …/join` → `{ "id", "role", "alreadyMember" }`+ - `POST …/machines/:m` (observation) → `{ "version" }` of `Mc(m)`+ - native append → `{ "eventId", "sequence" }`+ - `POST …/stopped` → `{ "confirmed": true }`, unchanged++### 4.8 Private conversations: audience (addendum)++**Storage.** `G.data.audience?: { people: Array<{ id: string; generation: string }> }`.+- Absent: the group is visible to whoever may read its project, as today.+- Present: the group is a private conversation. Generations are captured as `projectMembers` captures them+ (`projects.ts:202-207`), so leaving and rejoining does not restore access.+- The Leads conversation and project Lead conversations never have an audience.++**One predicate.** `readConversation` (`projects.ts:107-116`) gains the rule. Every read path goes through it, or+through `canReadGroup(state, actor, group)`, which group 2 adds next to it:++```text+canReadGroup(state, actor, g) =+ isLeads(g) → today's rule+ !canReadProject(…) → false+ !g.audience → true+ actor is a person → g.audience.people has { id: actor.userId, generation: member.generation }+ || (PRIVATE_VISIBLE_TO_OWNERS && actor is the project owner or the Swarm owner)+ actor is an agent → actor is the project's Lead (ledProject(state, actor.agentId)?.id === project.id)+```++The project owner and the Swarm owner are **not** implied: only the listed people and the Lead (addendum).+This is one constant, `PRIVATE_VISIBLE_TO_OWNERS = false`, next to `canReadGroup`. The owner (Ken) decided it stays+off: owners do not see private channels (section 8, Q3a). It stays one constant, and no other path may decide owner+visibility on its own.++**Where it is enforced** (each must use `canReadGroup`, not `canReadProject`):++| Path | Today | Change |+|---|---|---|+| First load, changes, dormant list, one group | `visibleState` filter (`model.ts:432`) | per-group filter |+| Messages, attempts, route decisions | `readConversation` (`store.ts:1131`, `1171`, `1184`) | through `readConversation` |+| Commands naming a group | `authorizeCommandAccess` (`commands.ts:340-343`) | through `readConversation` |+| Uploads, native terminal open | `poster`, `native.open` (`store.ts:941-948`, `native.ts:88`) | through `readConversation` |+| Mentions: tagging, list, waiting count | `canReadProject` (`mentions.ts:32`, `mentions.ts:71`) | `canReadGroup`; a Lead may tag only people in the audience |+| Deliveries | `deliveryAllowed` (`store.ts:1420-1422`) | the sender must be in the audience or be the Lead; recipients can only be the Lead (below) |+| `otherProjectsWork`, overlap alerts | `crossProjectActive` (`model.ts:320-321`) | private groups excluded |+| Project progress and wake-ups | `noteProjectReports` | private groups never mark a project dirty, so the Lead's summary to everyone never draws on them |+| Host roster `active` / `attention` | `store.ts:1340-1345` | unchanged (host rows are the agent's own) |+| Terminal rows (`currentGroup`) | `terminal.ts:46-50` | private groups excluded (only the Lead is in them, and the Lead's rows already skip groups it leads) |++**Rules for private groups.**+- `agentIds` holds only the project's Lead. `conversation.agent` with `present:true` for any other agent fails 403+ `AUDIENCE_LEAD_ONLY`.+- A private group is chat only. `work.define`, `work.assign`, `agent.start`, `route.record` and `reviewOf` targeting+ it fail 400 `AUDIENCE_CHAT_ONLY`, which keeps private work out of `otherProjectsWork`, holds and reviews.+- Attachments are stored and listed like messages and follow the group's readers. Their bucket URLs stay+ unguessable public URLs, as in private projects today (section 8, Q3).++**Commands.**++```jsonc+// create, by a writer person who can read the project (they must list themselves) or by the project's Lead:+{ "type": "conversation.create", "projectId": "5701…", "title": "Ken ↔ PM", "brief": "", "checks": [],+ "audience": { "personIds": ["6a86…"] } }+// change, by the project's Lead or a person in the audience; an empty list leaves only the Lead:+{ "type": "conversation.audience", "conversationId": "…", "personIds": ["6a86…", "6a87…"] }+```++- Each id must be a member who can read the project. Generations are captured from the member parts.+- `conversation.audience` replaces the list, bumps the epoch, and revokes native contexts of people removed. It+ also cancels queued, claimed or uncertain deliveries **authored** by people removed, and bumps the others (D10).+- An audience is never removed: a private conversation does not turn public. A group without `audience` cannot be+ given one, since its history was shared. Both fail 400 `AUDIENCE_FIXED`.++### 4.9 Swarm list++`GET /api/super-tabs/list[?after=<id>]` replaces `GET /api/super-tabs` (`store.ts:347-355`):++```jsonc+{ "tabs": [ { "id": "c514…", "name": "openharness", "ownerId": "6a86…", "paused": false, "lastChangedAt": 1793010106120 } ],+ "next": null }+```++### 4.10 Host form for the CLI++`GET /api/super-tabs/hosts/:machineId/changes?cursor=<cursor>[&full=1]`. It replaces `GET /hosts/:m`,+`GET /hosts/:m/pools` and `GET /hosts/:m/assignments` (`store.ts:1226-1250`, `1313-1375`, `1396-1408`).++```jsonc+{+ "format": 2, "full": false,+ "cursor": "eyJ2IjoyLCJ0IjoxNzkzMDEwMDc3Mzc1LCJlIjowfQ",+ "tabs": [ {+ "tabId": "c514…", "lastChangedAt": 1793010106120,+ "roster": [ // exactly today's GET /hosts/:m rows for this tab, `revision` replaced by `lastChangedAt`+ { "tabId": "c514…", "tabName": "openharness", "lastChangedAt": 1793010106120, "paused": false, "active": true,+ "attention": null, "agent": { …Agent… }, "joinSwarm": false, "skillMode": "default", "lead": false,+ "leadsConversationId": "…", // new: lets the host's mayRead skip the full read (cli host.ts:874-876)+ "stopRequested": false, "observers": [ { "email": "[email protected]", "userId": "6a86…" } ] },+ { "tabId": "c514…", "agent": { "id": "…", "harnessId": "…", "machineId": "7835…" }, "closeSession": true, "active": false },+ { "tabId": "c514…", "cleanup": { "machineId": "7835…", "removalId": "…" } },+ { "tabId": "c514…", "joinTeam": { "machineId": "…", "name": "MacBookPro2021", "maxAgents": 4 } } ],+ "pool": { "tabId": "c514…", "paused": false, "machine": { …ContributedMachine… }, "starts": [ … ], "localGrid": "swarm-…",+ "reservations": [ { "harnessId": "…", "generation": "…" } ], "harnessIds": [ "…" ], "githubApp": true }, // or null+ "assignments": [ { "tabId": "c514…", "assignmentId": "09d0…", "harnessId": "2973…" } ]+ } ],+ "removedTabIds": [ "…" ] // incremental only: Swarms that no longer list this machine+}+```++- **Incremental** (no `full`):+ - The server finds the Swarms that list the machine through `X` (`machineIds`, `cleanupMachineIds`). It keeps+ the ones with a **host-relevant** part whose `changedAt > cursor.t`:+ - the head or any member (names, pause, observers);+ - an agent on this machine;+ - a group whose `agentIds` include such an agent, or whose `executionMachineId` is this machine;+ - `Mc` of this machine or its team pools;+ - a start on this machine.+ - For those Swarms it returns all three row sets in full. The client replaces that Swarm's rows and keeps every+ other Swarm's rows.+ - A post in a group with no agent on this machine does not wake the host.+- **Full** (`full=1`): every Swarm of the machine. The client replaces everything and drops Swarms not listed.+ `removedTabIds` is empty.+- **The CLI must ask for `full=1`** on start and **at least every 60 s**. Grants and billing live in the `Machine`+ and `MachineShare` collections, which are not parts (`store.ts:286-300`), so a revoked share changes no part.+ Section 8 Q2 covers the bound. Commands, claims and deliveries still check grants on every call, so the delay+ affects only the roster.+- The cursor epoch is unused here (`e: 0`).+- The 100-Swarm cap (`store.ts:89`) is replaced by a 500 cap on full reads. Incremental reads are bounded by what+ changed.++### 4.11 `UPDATE_REQUIRED` on old routes++These routes answer **HTTP 426** with+`{ "error": { "code": "UPDATE_REQUIRED", "message": "Update Harness to keep using this Swarm." } }`:++- `GET /api/super-tabs`+- `GET /api/super-tabs/:tabId`+- `GET /api/super-tabs/hosts/:machineId`+- `GET /api/super-tabs/hosts/:machineId/pools`+- `GET /api/super-tabs/hosts/:machineId/assignments`++Every other route keeps working for any client. Every old client reads one of the 426 routes before or right after+any action: the CLI reads full state for every action (`cli/src/superTabs/service.ts:294-296`), the old host reads+`/hosts/:m` every second (`host.ts:502`), and Desktop reads full state after every command (`controller.dart:1089-1093`).+So an old client meets the error at once.+- The daemon passes the status and code through (`cli/src/superTabs/host.ts:24-38`, `service.ts:406-408`).+- Old Desktop shows the message in its error banner (`desktop/lib/super_tabs/view.dart:1296-1306`).+- Old CLI prints it as JSON with exit 1.+- An old daemon's host loop only logs it (`host.ts:329-331`). The person sees the error on their Desktop of the same+ version.++Until a Swarm is migrated (6.1), its new routes answer 503 `SWARM_MIGRATING`, which every client retries.++## 5. Client contract++### 5.1 Shared rules for every client++- **Parts store.** Keep a map `(kind, key) → envelope`, plus `derived`, `cursor`, `epoch` and `lastChangedAt`.+ - Merge rule (4.4): a higher `version` wins, a tombstone deletes, and a dormant stub moves the group to the+ dormant cache.+ - On `reload: true`, a 404 or a 403, drop the store and do a first load. A 403 or 404 on first load revokes the+ tab, as today.+- **Reassemble a state.** Build the old `SuperTabState` shape from the store so existing screens and code keep+ working: head `data`, plus `people` (member `data`), `agents` (with `derived.agents` overlaid), `conversations`+ (active groups), `machines` (with `derived.machines` overlaid), `starts`, `progress` (on each project), and+ `otherProjectsWork`/`mentionsWaiting` from `derived`.+ - Both clients get a reassembler; each group writes its own (Dart, TypeScript). The backend's reassembler (6.2)+ is the reference.+- **Order.** Parts come back in `ordinal` order on first load. Clients keep insertion order for new keys. Lists+ sort as today (conversations by number, messages by sequence).+- **Sequences.** `lastMessageSequence` and message `sequence` are compared **within one group** only, as both+ clients already do. Stored read marks keyed by conversation stay valid: sequences continue from `R`.+- **426 / `UPDATE_REQUIRED`.** Show "Update Harness to keep using this Swarm." and stop polling that Swarm (no retry+ loop). The CLI prints it and exits 1. The host logs it once and backs off 60 s.+- **503 `SWARM_BUSY` / `SWARM_MIGRATING`.** Retry with backoff, as for any 5xx.++### 5.2 Desktop and web (`desktop/lib/super_tabs`)++Today: a full `GET /:tabId` every 3 s per open Swarm (`controller.dart:52`, `414-416`). Web adapts the interval+(`web/shell/web_chrome.dart:51-58`, `controller.dart:429-442`). Changes are found by revision or deep compare+(`controller.dart:704-716`).++| Area | Change |+|---|---|+| `client.dart` | New calls: `parts`, `changes`, `groups?dormant=1`, `groups/:id`, `list`. Remove the full-state `GET /:tabId` and `GET /api/super-tabs`. |+| `controller.dart` refresh | First load once, then `changes` on the same timers (3 s desktop; the web's adaptive 15 s/light-read schedule stays). Drop the revision acceptance rule (`:716`) and the deep compare (`:704-710`): the snapshot changes exactly when a part or `derived` changes. Keep the cleanup for conversations no longer listed (`:718-747`), driven by tombstones, dormant stubs and reloads. |+| `model.dart` | `SuperTabSnapshot` is built by the reassembler. Replace the `version != 1` check (`:194-196`) with `format == 2`. Parse `progress` if needed (not used today). |+| After a command (`controller.dart:1089-1093`) | Call `changes` once. Drop the second refresh keyed by `revision`; the reply's `parts` versions may be used to skip a redundant fetch. |+| Saved web view (`saved_view.dart:21-36`, `controller.dart:457-478`) | Store `{cursor, parts, derived, …}` keyed by `lastChangedAt` in place of `{revision, state}`. A saved cursor older than 7 days, or with another epoch, reloads. |+| `onSnapshot` (`client.dart:433-436`), mentions reload (`notifications.dart:90-104`) | Fire on `lastChangedAt` or `mentionsWaiting` change in place of `revision`. |+| Swarm list (`client.dart:311-331`, `tab_invites_section.dart:56-63`) | `GET /api/super-tabs/list`; it reads `id`, `name` (and may use `lastChangedAt`). |+| Work details and archived groups (`work_details.dart`, `view.dart:646-690`, `project_sidebar.dart:288-295`) | The active list comes from active groups. Archived and auto-dormant groups load on demand from `groups?dormant=1` when the person opens the archived or earlier list, and one group by id when a link or mention names it. Selecting one pages its messages through the unchanged route (`controller.dart:625-643`). |+| Unread, scroll, read marks (`controller.dart:393-401`, `647-657`, `view.dart:188-193`) | No change: per-group sequence. |+| Message paging (`controller.dart:839-851`, `918-934`) | Older history sends `before` and `beforeId` from the response's `next` object (4.6). Polling for new messages keeps `after=<last sequence>`. Merge by id and sort by `(sequence, id)`. |+| Errors (`controller.dart:864-878`, `1096-1113`) | Map 426 to the update message (5.1). A first-load 426 shows the full-page error on web (`view.dart:1188-1210`). |+| Private conversations | No UI in this project. The client must not assume every member sees every group of a project. It renders what it receives and reloads on an epoch change. |++**Stops fetching:** the whole Swarm every 3 s (now only parts changed since the cursor), every archived group's+record, and the whole list on every poll.++### 5.3 CLI (`cli/src/superTabs`)++- **Per-tab parts cache in the daemon.** A cache keyed by `(tabId, asAgentId)`, refreshed with `changes`, used by+ every action that needs Swarm data. The daemon is long-lived (`service.ts` handles `super_tabs`), so one-shot+ `harness super-tab` calls cost one `changes` poll instead of a full read.++**What each part of the CLI uses:**++| Part of the CLI | Today | New |+|---|---|---|+| Host tick (`host.ts:280`, `:502`) | `GET /hosts/:m` every 1 s | `GET /hosts/:m/changes?cursor=` every 1 s; `full=1` at start and every 60 s (4.10). Keep the rows per Swarm and replace a Swarm's rows when it is returned. |+| Pools (`machines.ts:151`, 5 s) | `GET /hosts/:m/pools` | `tabs[].pool` from the same host form. |+| Assignments (`host.ts:343`, 5 s; `github.ts:123`, 60 s) | `GET /hosts/:m/assignments` | `tabs[].assignments` from the host form. |+| `mayRead` (`host.ts:874-876`) | full read per tab:agent | roster `lead` and `leadsConversationId`. |+| `releaseWorker`, `tellSkill`, `swarmRoleFor` (`host.ts:371-410`, `735-738`, `61-71`) | full read | parts cache with `asAgentId` (rare events). |+| Deliveries (`host.ts:577-589`, `936`, `924-930`, `1011-1012`, `477-495`) | per agent per tick | unchanged routes and bodies. Claims no longer bump the Swarm (3.5). |+| Native recorder (`native.ts:139-146`, `290-294`) | reads `result.eventId` | unchanged; the reply's `revision` becomes `sequence` and is not read. |+| `observeMachine` (`machines.ts:236-273`) | `POST /:tab/machines/:m` | unchanged body; the reply is `{ version }`. |+| Pro cards (`cards.ts:141-213`, `285`, `296-301`) | list plus full read when `revision` moves | `list` plus the parts cache when `lastChangedAt` moves. Recap reads use the per-group `lastMessageSequence` (`cards.ts:272-339`), with no logic change. |+| `sharedSwarm` (`service.ts:134-145`), contribution (`contribution.ts:24`), machine cleanup (`machines.ts:369`) | full read | parts cache (only `members`, `machines` and `agents` needed). |+| `harness super-tab` actions (`service.ts:294-302`) | full read before every action | parts cache. `messages`, `message`, `screen`, `type`, `remove-machine` and `start`/`resume` status polling stop fetching Swarm state at all. `post`/`command` read the cache only for `--mention` (members). `help` reads it only for `isLead`. |+| `route` (`routeCommand.ts`, `service.ts:314-330`) | full read twice | the parts cache once. Machines carry `availableSlots` and `teamWork` from `derived`, and agents carry `limitedUntil`; the fields it reads are unchanged (`routeCommand.ts:116-177`, `252-297`, `339-366`). |+| `project.report` help example (`service.ts:38`) | `throughRevision` | `through` map (3.6). |+| Message paging (`service.ts:360-362`; `cards.ts:101-102`, `299-301`) | `after=`/`before=` a sequence | `message` keeps `after=<sequence>` (new messages). Card recaps page back with `before` and `beforeId` from `next` (4.6). |++**`harness super-tab status` keeps its output.**+- It prints `{"ok":true,"value":{…}}` (`command.ts:152`), where `value.state` is built by `statusView`+ (`service.ts:77-85`) from the reassembled state. The keys, shapes and the Lead/non-Lead filtering are unchanged.+- Two differences:+ - `value.revision` is replaced by `value.lastChangedAt` (section 8, Q5);+ - `state.conversations` lists only active groups, because dormant ones leave the active set (the spec's archive).+- Each active group still carries `lastMessageSequence`, now per group, and the wake-up text names groups with+ their sequence (3.6).++**Stops fetching:**+- the full state before every agent action;+- the three per-machine rosters, each loading up to 100 full Swarms, every 1–5 s;+- the full state when a card's revision moves.++## 6. Migration++### 6.1 Algorithm (one transaction per Swarm, idempotent)++The migration runs as a one-off job of the new image (`node dist/migrate.js`, group 3) inside a maintenance window+in which **no old backend process is running** (6.1.1). A Swarm whose `SuperTab.format` is still 1 answers 503+`SWARM_MIGRATING` on the new routes (4.11); the new backend also migrates such a row on first access with the same+code, as a safety net for a row the job did not see.++#### 6.1.1 Deploy sequence and the gate on old writers++A guarded bump of `revision` alone does not fence old processes. An old process that reads the row after the+migration sees `R+1`, and its own guarded write (`store.ts:519-521`, `767-769`; `observeMachine` `1273`, `1308`)+succeeds. So old writers are stopped first, and the data is fenced as well. This matches the owner's decision that+every client moves at once (spec, owner decisions).++1. **Prepare.** The release's backend image, CLI and Desktop builds are ready and the local dry run (6.5) passed. Do+ not publish the CLI or Desktop yet: they need the new routes.+2. **Gate: stop every old writer.**+ - Kubernetes: scale the old API Deployment and the old job Deployment to 0 replicas. Suspend ArgoCD sync for+ them so they are not scaled back up, and serve 503 from the ingress during the window.+ - Docker/pm2 installs: `pm2 stop all`.+ - Clients retry 5xx. Hosts log and retry, and Desktop shows its reconnecting state (`controller.dart:773-776`).+3. **Verify no old writer remains.**+ - The orchestrator shows 0 running pods of the old image for both Deployments.+ - The job's preflight reads `max(SuperTab.updatedAt)`, `max(SuperTabMessage.createdAt)` and+ `max(SuperTabDelivery.updatedAt)`, waits 60 s, and reads them again. Any change aborts with "a writer is still+ running".+ - While any host is online, a live old API process writes within 15 s: hosts observe every 5–15 s+ (`cli/src/superTabs/machines.ts:34`, `37`, `140-146`) and claim deliveries every second.+4. **Migrate** every `format = 1` row (6.1.2). The job's report must say `ok` for every Swarm. If any+ Swarm fails, fix and rerun, or roll back (6.4); no new write has happened yet.+5. **Deploy the new backend** (API and job), then lift the gate.+6. **Publish the CLI and Desktop.** Old clients get 426 from now on (4.11).++**Data fence (backstop).**+- Step 6 of the migration moves the old state to `legacyState` and leaves `state = { "version": 2 }`.+- Every old code path reads `state` through `stateOf` before it writes, and `stateOf` refuses any `version ≠ 1`+ with `UPDATE_REQUIRED` (`store.ts:39-45`). The paths:+ - commands (`store.ts:520`), observations (`1273`), native recording (`158`, then `native.ts:85`, `111`);+ - claims, acks and holds (`1497`), the deliveries wake-up (`1437`), stopped receipts (`1564`);+ - sharing (`381`), join (`416`), the read backfill (`449`), and terminal relays (`1030`, `1068`).+- So an old process that somehow survives the gate fails before writing.+- The only old write that skips `stateOf` is `create` (`store.ts:330-345`), which inserts a new `format = 1` row;+ the new backend migrates it on first access.+- The spec's "old `state` kept read-only" holds: the old state is kept unchanged in `legacyState` until the owner+ says it can go (Ruling R14).++#### 6.1.2 Per-Swarm steps++For each `SuperTab` row with `format = 1`, in one transaction (`transaction()` with a 60 s timeout for this job only):++1. Read the row at revision `R` and `state = stateOf(row)` (`store.ts:39-45`).+2. **Normalize**, applying exactly what the next read or command would do, so behavior is identical:+ - `parkLaterConversations`, `syncLeads`, `numberConversations`, `placeRules`, `assignAgentDisplayNames`+ (persist every name);+ - `restorePullRequestUrls` (`store.ts:49-68`; reads messages and attempts);+ - fill `agent.projectId` with `agentProjectId(state, agent)` when `state.projects` exists and the field is+ absent (`projects.ts:77-80`);+ - persist `workDecision: 'awaiting'` for the workers `awaitingWorkers` derives it for (`model.ts:261-269`);+ - group numbers in legacy append order.+ - Not applied: `expireRemovals` (time-based; the first observation or command applies it) and the+ `releasedHarnesses` cap (applied on the next write of that `Mc`).+3. **Split** into parts with `version = R` and `changedAt = now`. `ordinal` is the index in the source array.+ - **Head:** `data` = the head fields (2.2); `groupCounter = nextConversationNumber(state) − 1`;+ `visibilityEpoch = 1`; `sequenceBase = R`.+ - **Members:** one per `people[]`.+ - **Groups:** one per `conversations[]` and `parkedConversations[]`:+ - `messageSeq = R`;+ - `reportSeq = min(lastMessageSequence, P.dirtyRevision ?? 0)` for a non-Lead project group, else 0;+ - `lastActivityAt` = its newest message's `createdAt`, from one aggregate over `SuperTabMessage` for the tab;+ - `dormant` = archived, or (assignment `done`/`cancelled` and `lastActivityAt` older than 24 h, and not a+ Lead conversation or the Leads conversation).+ - **Agents**, **starts:** one each. Starts get `finishedAt` when finished; the time is unknown, so use migration+ time.+ - **Machines:** one per machine id found in `machines`, `harnessReservations`, `releasedHarnesses`,+ `closingSessions` and `machineCleanups`, holding those records.+ - **Progress:** one per stored project with `progress`, converted as follows:+ - `since`, `requestedAt`, `requestMessageId` copied;+ - `summarizedFloor = summarizedRevision`, `summarized = {}`;+ - `requestedFloor = requestedRevision`, `requested = {}`.+4. **Keep every sequence** (spec ruling 7). Messages are not touched. Every stored reference stays valid unchanged:+ `lastMessageSequence`, `recordingProgress.revision`, `checkpoint.sequence` in message sources, the progress+ floors, and `throughRevision` values in old wake-up texts. All are tab revisions ≤ `R`, and every group continues+ numbering after `R`.+5. **Verify** (6.3). On any difference, throw: the transaction aborts, nothing is written, and the Swarm stays at+ `format 1` (503 `SWARM_MIGRATING`) with the difference logged.+6. **Insert** the parts (`createMany` per model). Update the row:+ `{ format: 2, revision: R + 1, migratedAt: now, legacyState: <the old state, unchanged>, state: { version: 2 } }`,+ guarded by `where: { id, revision: R }`.++**Freeze.**+- Old writes are frozen for the whole migration by the gate (6.1.1, steps 2–3), and afterwards by the data fence.+- The guarded update in step 6 only protects against the new backend's own lazy migration racing the job.++**Idempotent.** A Swarm with `format = 2` is skipped. A failed Swarm wrote nothing and is retried on the next start+or by the dry-run tool.++### 6.2 Reassembly (the reference for verification and rollback)++`reassemble(parts) → SuperTabState`, owned by group 2 (`backend/src/superTabs/parts/shape.ts`):+- head `data`;+- `people` from members, sorted by `ordinal`;+- `agents`, `conversations` (with `messageSeq`, `reportSeq`, `dormant` and `lastActivityAt` removed) and `starts`,+ each sorted by `ordinal`; `parkedConversations` are the groups of unknown `kind`;+- `machines`, `harnessReservations`, `releasedHarnesses`, `closingSessions` and `machineCleanups` from the machine+ parts;+- `projects[].progress` rebuilt from progress plus groups: `dirtyRevision = max(reportSeq)` over the project's+ non-Lead groups; `summarizedRevision = summarizedFloor` while `summarized` is empty; `requestedRevision`+ likewise.++The same function serves commands (3.1), the CLI's `status` (5.3), verification and rollback.++### 6.3 Verification (every Swarm, inside its migration transaction)++- **State:** `canonical(reassemble(parts))` deep-equals `canonical(normalize(old state))`, field by field.+ `canonical` sorts these arrays, which carry no order: `harnessReservations`, `releasedHarnesses`,+ `closingSessions`, `machineCleanups`, `overlapAlerts`. Every other array keeps its order. The first differing path+ is logged.+- **Messages:** before and after, `count` and `sha256` of the ordered list of `(conversationId, sequence, id)` for+ the tab match. Because messages are not written, this proves the migration did not touch them. It also checks+ that every message's `conversationId` has a group part, so no history is orphaned.+- **Counts unchanged:** deliveries, route decisions, attempts and operations for the tab.+- **Reports:** a per-Swarm line `{tabId, bytes, groups, dormant, parts, ms, ok}` and a total, written to the worker+ log and to `artifacts/swarm-parts-migration-<date>.json` by the dry-run tool.++### 6.4 Rollback++- Every rollback runs behind the same gate (6.1.1, steps 2–3), with the new backend stopped and verified quiet.+- **Before any new write** (failure at step 4 or 5): run `scripts/swarm-parts/rollback --legacy`. For every+ `format = 2` row it sets `state = legacyState`, `format = 1`, and leaves `revision = R+1`. Then redeploy the+ previous backend; it reads the old state and works. Drop the part collections.+- **After new writes:** run `scripts/swarm-parts/rollback` (group 3). For each `format = 2` Swarm, it does+ `state = reassemble(parts)`, checks it with the old `stateOf`, and writes+ `{ state, revision: max(R+1, highest message sequence, highest part version) + 1, format: 1 }`. Then redeploy the+ previous backend and lift the gate.+ - Old code numbers new messages from that revision. Old code also numbers per tab: it gives every new message, in+ any group, `row.revision + 1`. Starting `revision` above every sequence written in parts mode keeps each group+ strictly increasing.+ - **Refused for a Swarm the previous backend would misread** (final review, Critical 2; Lead ruling for v1). The+ previous backend checks no audience: it filters conversations and messages by project alone. It also ends work+ only on done, stopped or cancelled. So `rollbackFromParts` refuses, before changing any row, a Swarm with:+ - any private conversation, which would become readable by every project reader;+ - any task with status `lost`, which would read as active;+ - any task cancelled after it was lost (it keeps `assignment.lost`). The previous backend reads it as finished, but+ ignores the marker, so the fenced worker would read as an ordinary finished worker awaiting a decision.+ - The refusal names the Swarm and the reason. The Swarm stays in parts. Recovery is to roll forward with a fix: the+ parts stay authoritative, so nothing is lost or made public.+ - A reassigned task whose `lostAttempt` names an earlier worker is not refused. The current assignment is the new+ worker's, and the previous backend accepts status only for the current assignment id and its agent.+- Part collections are dropped only after the owner says so. The old `state` field is likewise kept until the owner+ says it can go (spec).++### 6.5 Local dry run (no production data; spec PM ruling)++- **Stack:** a local isolated stack (spec "Constraints all groups share"): a MongoDB replica set on localhost with+ its own data directory and port (or MongoMemoryReplSet), and no remote URLs.+- **Seed:** `backend/scripts/swarm-parts/seed.ts` builds synthetic Swarms by running real commands through+ `applyCommand` and the store on the **old** code path, so states have production shape:+ - one Swarm of about 1.16 MB with 195 groups (≈ 20 agents, 6 machines, 3 projects, mixed done, cancelled,+ archived, reconciling and active groups, starts in every state, rules, invitations, a legacy group without+ `pullRequestUrls`, a parked unknown-kind group), with about 40 000 messages;+ - one of about 422 KB with 50 groups;+ - ten small ones;+ - one legacy Swarm without `projects`.+- **Run:**+ 1. migrate;+ 2. verify;+ 3. migrate again, with no change expected;+ 4. run the new backend's integration suites against the migrated data;+ 5. post commands through the new store, then write a private chat into one Swarm and a lost task into another;+ 6. roll back: those two are refused with their rows unchanged (6.4), the rest roll back;+ 7. read every rolled-back Swarm with this branch's `visibleState`. This checks the old shape still reads. It does+ not run the previous backend's binary or its access checks, so it is not evidence that the previous backend reads+ the state safely; the refusal in 6.4 keeps out what it would misread.+ Time each step. Group 6 repeats it on the integrated branch.++## 7. Group split for 2–5++### 7.1 Owned paths (no overlaps)++| Group | Owns |+|---|---|+| **2 Backend storage and commands** | `backend/prisma/schema.prisma` (part models, `SuperTab.format/migratedAt/legacyState`, `SuperTabOperation.parts`, the message index); `backend/src/superTabs/parts/**` (new: models, `loadActive`, `reassemble`, `split`, `diffParts`, `guardedWrite`, `clock`, `touchesFor`); `store.ts`, `commands.ts`, `model.ts`, `projects.ts` (incl. `canReadGroup`), `machines.ts`, `native.ts`, `projectUpdates.ts`, `mentions.ts`, `terminal.ts`, `sessionScope.ts`, `agentNames.ts`, `holdNotice.ts`, `routeDecisions.ts`; sweeps in `backend/src/worker.ts` and `backend/src/superTabs/sweeps.ts` (new); `backend/src/superTabs/*.test.ts`; `backend/integration/superTabs.test.ts`, `superTabSharing.test.ts`, `superTabTeam.test.ts`, `superTabGithub.test.ts` (adapted, never weakened) |+| **3 Backend read API and migration** | `backend/src/routes/superTabs.ts`; `backend/src/superTabs/read/**` (new: `parts`, `changes`, `groups`, `list`, host form, per-part visible views, `derived`, cursor codec, `lastChangedAt`); `backend/src/superTabs/migration/**` (new); `backend/scripts/swarm-parts/**` (seed, dry run, rollback); `backend/integration/superTabRead.test.ts`, `backend/integration/superTabMigration.test.ts` (new) |+| **4 Desktop and web** | `desktop/lib/super_tabs/**`; `desktop/lib/settings/sections/tab_invites_section.dart`; the Swarm list calls in `desktop/lib/state/app_state.dart` (`:1723-1771` only); `desktop/test/super_tab*`, `desktop/test/support/super_tab_fixture.dart`, `desktop/tool/super_tab_mobile_fixture.dart` |+| **5 CLI** | `cli/src/superTabs/**` (host, machines, cards, service, command, start, routeCommand, contribution, github, native, attach, swarmGrids) and their specs; Lead-facing texts that name `throughRevision` or `lastMessageSequence` outside the backend (`cli/src/superTabs/service.ts`) |++`docs/` changes for user-facing behavior go with the group that changes it.++### 7.2 Interfaces between groups++**Group 2 → group 3** (TypeScript, in `backend/src/superTabs/parts/index.ts`; group 3 codes against it as soon as+this doc is accepted, with a stub until group 2 lands):++```ts+export type PartKind = 'head' | 'member' | 'agent' | 'group' | 'machine' | 'start' | 'progress'+export interface Part<T = unknown> { kind: PartKind; key: string; version: number; changedAt: number;+ deleted?: true; dormant?: true; ordinal: number; data: T | null }+export interface SwarmParts { head: Part<HeadData>; members: Part<Person>[]; agents: Part<Agent>[]; groups: Part<GroupData>[];+ machines: Part<MachineData>[]; starts: Part<AgentStart>[]; progress: Part<ProgressData>[]; sequenceBase: number; epoch: number }+export function loadActive(tx: Transaction, tabId: string, opts?: { groupIds?: string[]; agentIds?: string[] }): Promise<SwarmParts>+export function loadChanged(tx: Transaction, tabIds: string[], since: Date, kinds?: PartKind[]): Promise<Map<string, Part[]>>+export function loadDormant(tx: Transaction, tabId: string, page: { projectId?: string; before?: { lastActivityAt: number; key: string } }): Promise<Part<GroupData>[]>+export function reassemble(parts: SwarmParts): SuperTabState // 6.2+export function split(state: SuperTabState, opts: { version: number; now: number; lastActivity: Map<string, number> }): SwarmParts+export function lastChangedAt(tx: Transaction, tabIds: string[]): Promise<Map<string, number>> // 3.7+export function canReadGroup(state: SuperTabState, actor: Actor, group: Conversation): boolean // 4.8, in projects.ts+export const clock: { next(): number } // 3.3+```++- Group 2 keeps `visibleState` (`model.ts:392`) correct for the reassembled state. Group 3 builds per-part views+ from the same rules and must not change them.+- Group 3 consumes the store's existing `read()` helpers for `derived` (`machineSlots`, `teamWorkRefusal`,+ `downSince`, `awaitingWorkers`, `otherProjectsWork`, `mentionsWaiting`). Group 2 exports `otherProjectsWork`,+ which is private today (`model.ts:323`).++**Group 3 → groups 4 and 5:** the HTTP contracts in section 4, exactly. Group 3 adds+`backend/src/superTabs/read/contract.ts` with the response types, as the single source of truth that groups 4 and 5+mirror by hand. Any change to it after acceptance is announced to the Lead before it merges.++**Group 2 → group 5:** the `project.report` schema (`through`, 3.6) and the wake-up text.++**Merge order:** 2, then 3 (spec), then 4 and 5. Groups 4 and 5 develop against a local backend running 2+3, or+against recorded fixtures of the section 4 examples.++## 8. Open questions and findings, ranked++Each item has a recommended answer.++**Lead's rulings (2026-10-26):**+- Q1, Q2, Q4, Q5, Q7: accepted as recommended.+- Q3: (b)–(g) accepted. (a): the owner (Ken) decided owners do **not** see private channels; the single constant in+ 4.8 is `false`.+- Q6: accepted as independent of N. The replica count and NTP are being confirmed with the owner; this does not+ block anything.+- R1–R10: no objection.++The items as raised:++**Q1. Auto-archive must not use `archived` (spec ruling 5 against the code).**+- Spec ruling 5 says archive uses the existing `Conversation.archived` field, and that a new message brings the+ group back. In the code, `archived` is a hard state:+ - posts and work in it are refused (`commands.ts:371-375` `ARCHIVED`);+ - its native terminal contexts are revoked and their deliveries cancelled (`native.ts:243`, `259-261`);+ - deliveries to it are withheld (`store.ts:1413`);+ - the host releases agents that are only in archived groups to automatic cleanup (`store.ts:1339-1340`).+- Setting it automatically after 24 h would close terminals, withhold deliveries and let hosts clean up idle+ finished workers. Making a post reopen it would break the "Reopen this conversation" rule and its tests.+- **Recommendation (designed in):** a separate `dormant` flag (Ruling R3). It is set by the 24 h sweep or by a+ manual archive, and cleared by any message or new work. Only the feed and first load read it. `archived` keeps+ today's meaning.++**Q2. Host roster delay after a share or billing change (Ruling R7).**+- `Machine` and `MachineShare` are outside the parts, so the incremental host form cannot see a revoked share.+- **Recommendation:** a full host read every 60 s (4.10). Commands, deliveries and claims recheck grants on every+ call (`store.ts:286-300`, `1427-1432`), so only the roster lags.+- **Alternative:** 15 s full reads, which cost 4× more.++**Q3. Private conversation rules not fixed by the addendum (4.8).**+- **Recommendations:**+ - (a) Only the listed people and the Lead see it; the project owner and Swarm owner do not.+ - (b) A person creates one only with themselves in it; the Lead may create one for any project reader.+ - (c) Only the Lead or a listed person changes the audience.+ - (d) Chat only, Lead the only agent.+ - (e) An audience is fixed once set: never removed, never added to an existing public group.+ - (f) Its posts do not feed project reports.+ - (g) Attachment URLs stay unguessable public URLs, as in private projects. Signed URLs are a separate change if+ wanted.+- The PM channel UI builds on (a)–(f).++**Q4. Swarm-wide limits serialize on the head.** Pending starts ≤ 32 (`commands.ts:1034`), machines ≤ 32, projects+≤ 100 and rules ≤ 50 are guarded by touching or writing `H`. So two `agent.start` calls in one Swarm conflict and+one retries. **Recommendation:** accept. Starts are rare, and the limit stays exact.++**Q5. `status` drops `revision`.** No tab revision exists after migration. **Recommendation:** replace it with+`lastChangedAt`. The CLI reads no `revision` from `status`, only from the list (`cards.ts:113-116`, `209`). The+skill texts reference `throughRevision` only through the wake-up text, which changes with 3.6.++**Q6. Backend processes and clock (spec ruling 3).**+- Several processes write: k8s pods with one process each, and pm2 `max` in Docker. The count is outside this repo.+- **Recommendation:** keep the design independent of N (section 3.3). The owner confirms the replica count, and that+ nodes run NTP, so drift stays far below the 15 s budget.++**Q7. Legacy `throughRevision`.**+- **Recommendation:** accept it only when it is ≤ `sequenceBase`, meaning a wake-up from before the migration that a+ Lead answers after it (3.6).+- After the migration a scalar cannot be safe, because groups number independently. A scalar would mark unread+ posts in a slower group as summarized.++**Findings where the spec's shape needed a change (Rulings, no decision needed unless you disagree):**++- **R1 Machine parts exist for every referenced machine, not only contributed ones.**+ - `reserveHarnessSlot` and `releaseHarness` write reservations and stop receipts for any machine an agent runs+ on, contributed or not (`commands.ts:315-324`, `1574-1584`; `store.ts:1297-1307`).+ - "One document per contributed machine" (spec table) would leave those without a home.+ - *Cost if wrong:* none; a machine part with `contribution: null` is never sent to clients.+- **R2 People live only in member parts.** Spec ruling 2 gives every person a part; keeping a second copy on the+ head would make every membership change write two places. *Cost if wrong:* none.+- **R3 `dormant` separate from `archived`:** Q1.+- **R4 Every message gets its own sequence, and pages use `(sequence, id)`** (4.6).+ - Today all messages of one command share the tab revision (`store.ts:1110`).+ - The page cursor `next = last row's sequence` with `sequence > after` (`store.ts:1135`, `1145`) can skip rows+ that share a sequence at a page edge.+ - New messages are numbered one by one; old ties are kept.+- **R5 `P(p)` is also the worker-decision fence** (3.6). Without it, `requireWorkerDecisions` acts on a stale read+ across groups.+- **R6 `lastChangedAt` is computed when read** (3.7).+- **R7 Host form full refresh:** Q2.+- **R8 `read()` never writes.** The migration does the `pullRequestUrls` backfill (`store.ts:451-456`).+- **R9 Part versions start at `R`.** Agent versions then keep `SuperTabConfiguration.revision` ordered after old+ rows.+- **R10 Group-level changes bump delivery rows** (D10). This is what makes ruling 9's claim touches enough. Without+ it, a claim could deliver into a group archived a moment earlier, which today's Swarm-wide bump prevents+ (`store.ts:1513-1514`).+- **R11 `project.report` takes a `through` map** (3.6, Q7).+- **R12 `reportSeq` is separate from `lastMessageSequence`.**+ - Hold and stop notices bump `lastMessageSequence` but never marked a project dirty (`store.ts:1538`, `1597`;+ neither calls `noteProjectReports`).+ - Computing dirtiness from `lastMessageSequence` would change that.+- **R13 Finished starts leave first load and command state, but stay loadable by key for 7 days** (spec archive,+ review round 1).+ - `work.assign` and an agent's own removal load the finished start they match (3.1).+ - After the 7-day expiry, a decision that still names that start falls back to the member-candidate match.+ - *Cost if wrong:* an assignment more than 7 days after a routed start needs an override reason.+- **R14 The old state moves to `legacyState`; `state` becomes `{ "version": 2 }`** (6.1.1, review round 1).+ - Old code refuses that state in `stateOf` before every write (`store.ts:39-45`), so a surviving old process+ cannot write.+ - The old state is kept unchanged and read-only until the owner says it can go, which is the spec's intent.+ - *Cost if wrong:* a reader of the raw `state` field outside the backend would see the stub. None exists in this+ repository.+- **R15 Host reads need what a write changed, not only its new data** (group 3 review round 1; Lead's ruling).+ - 4.10 woke a host for a group whose new `agentIds` include one of its agents. An agent removed from its last group+ then never woke its host, which kept it `active` (and out of automatic cleanup) until the 60 s full read.+ - Each group write therefore records the machines its agents and its work were on, before and after+ (`SwarmGroup.hostMachineIds`, set by `parts/commit.ts`), and the host form wakes on that.+ - That list is the last write's only, so a later write to the group (a rename, a post) would replace it before the+ host reads. An agent a group's write lets go (out of its members and its work) is therefore also written again, its+ data unchanged, and its host wakes on that agent's change, whatever the group's later writes say (review round 2).+- **R16 A machine's own reading wakes no host** (group 5's end-to-end run; Lead's ruling).+ - Machines report every 15 s. With the 30 s overlap every host tick resent its Swarm in full.+ - A host's rows carry only its own reading, which it sent. So the host form wakes on `SwarmMachine.hostChangedAt`,+ which `parts/commit.ts` moves only when a machine part's settings or ledger change, never when only its reading+ does. Desktop and web feeds still get readings by `changedAt`.\ No newline at end of filediff --git a/docs/performance/2026-10-26-swarm-state-baseline.md b/docs/performance/2026-10-26-swarm-state-baseline.mdnew file mode 100644index 000000000..eff276903--- /dev/null+++ b/docs/performance/2026-10-26-swarm-state-baseline.md@@ -0,0 +1,150 @@+# Swarm state baseline on main (#1726)++The "before" numbers for goals 1 and 3 of [Swarm state by parts](../plans/2026-10-26-swarm-state-parts.md): write+conflicts between agents in different work groups, and the cost of a poll. Group 6 reruns the same benchmark, with the+same seeds and lanes, on the finished branch for the "after" numbers.++## How it was run++- **Commands** (from `backend/`, after `npm ci`; see [the bench README](../../backend/integration/bench/README.md)):+ `npm run bench:swarm-state` twice (the mixed, busy Swarm), then `npm run bench:swarm-state -- --lane cross-group`+ once, one after the other.+- **Code measured:** main at `0d3485bad`. All three runs ran from `b71522ab6` on `bench/swarm-state-baseline`, with a+ clean tree. `backend/src` and `backend/prisma` there are identical to main (`git diff --quiet origin/main HEAD --+ backend/src backend/prisma`), and main has had no change under `backend/` through `c84d2bc2e`. The commits after+ `b71522ab6` on the branch add only this document, the result files and a docs-only merge of `feat/swarm-state-parts`+ (the design document). So the reviewed head, `1231be129`, has the same executable sources as `b71522ab6`: every+ file outside `docs/` and `backend/integration/bench/results/` is identical (`git diff --name-only b71522ab6 1231be129+ -- . ':!docs' ':!backend/integration/bench/results'` lists nothing).+- **Machine:** Apple M1 Max, 10 cores, 64 GB, macOS (Darwin 25.6.0, arm64), Node 24.18.0, MongoDB 7.0.24 as a local+ single-node replica set (mongodb-memory-server, the same set-up as `backend/integration/superTabs.test.ts`). The routes+ run in process through Fastify `inject`, so there is no network in the latencies.+- **Swarm:** seed 1726. 200 work groups: 180 done during setup, 20 active, 20 workers, each with one active group. One+ Lead on the owner's machine. 6 contributed machines, each owned by a different person. Briefs are 3,000 characters,+ so the state is about 1 MB, like the 1.16 MB Swarm with 195 groups in the issue. Plan fingerprints: mixed+ `8ba3412b11e82391…` (both runs), cross-group `575e841eb53ecf49…`.+- **Mixed load (120 s), the busy Swarm:** each worker posts about every 4 s in its own group (`message.send`,+ `work.status`, `work.check` in a 2:1:1 mix). Its terminal records a turn (a prompt and its answer) about every 10 s in+ the same group, at the same time. The Lead messages a worker in its group about every 5 s. Each machine reports every+ 15 s. Each host passes over its agents' deliveries every 3 s and claims and acknowledges what waits. 3 Desktop windows+ poll the full state every 3 s, and 2 CLI hosts read their roster every 1 s.+- **Cross-group lane (120 s), for goal 1:** the same workers, posts, terminal turns, machine reports and readers. Each+ worker's posts and turns run in one sequence, though, and there are no Lead messages and no delivery passes. So no+ two calls ever write one group at once, and every conflict between agents is between different groups.+- **Time:** 187–194 s per run end to end: 59–60 s setup (1,178 calls), 120–123 s load, the rest database start-up and+ shutdown.+- **Raw data:** [mixed, run 1](../../backend/integration/bench/results/baseline-main-0d3485bad-mixed-1.json),+ [mixed, run 2](../../backend/integration/bench/results/baseline-main-0d3485bad-mixed-2.json),+ [cross-group lane](../../backend/integration/bench/results/baseline-main-0d3485bad-cross-group.json).++## Headline++| Measure | Mixed, run 1 | Mixed, run 2 | Cross-group lane |+|---|---|---|---|+| Agent calls (worker posts and terminal turns) | 922 | 934 | 1,066 |+| … needed at least one retry | 779 (84%) | 785 (84%) | 453 (42%) |+| … failed transaction attempts | 4,576 | 4,338 | 1,038 |+| … gave up as `SWARM_BUSY` | 401 (43%) | 354 (38%) | 10 (1%) |+| Machine reports: calls / failed attempts / `SWARM_BUSY` | 48 / 163 / 9 | 48 / 201 / 15 | 48 / 37 / 0 |+| All writes: calls / failed attempts / `SWARM_BUSY` | 2,079 / 5,209 / 426 (20%) | 2,170 / 4,976 / 381 (18%) | 1,114 / 1,075 / 10 (1%) |+| Desktop poll, response (mean) | 1,020.0 KB | 1,021.6 KB | 1,023.2 KB |+| Host roster tick: response / read from MongoDB (isolated) | 4–5 KB / 1,041 KB | 4–5 KB / 1,041 KB | 4–5 KB / 1,042 KB |+| State after the load | 1 document, 1,036.5 KB | 1 document, 1,036.9 KB | 1 document, 1,037.4 KB |++**Goal 1, from the cross-group lane.** Agents writing only in their own groups, one writer per group, still conflict+with each other today:+- 42% of their calls needed a retry, and 10 ran out of retries.+- Machine reports, which write no group, conflicted with them too: 37 failed attempts in 48 reports.++Every one of these conflicts is across groups, and goal 1 says they must be zero. In the mixed Swarm, where same-group+writes add to them, 84% of agent calls retried and 38%–43% gave up.++**Goal 3.** A Desktop poll returns the whole Swarm, about 1 MB every 3 s per open window, even when nothing changed. A+host's roster reply is a few KB, but to build it the backend loads the whole Swarm document from MongoDB on every 1 s+tick. That load is only visible in the isolated measure.++## Cross-group lane, by kind of writer++A failed attempt is one database transaction the store retried: a P2034 write conflict, or a transient error, with+#1722's backoff. `SWARM_BUSY` means a call used all 8 attempts. Latencies include that backoff.++| Kind | Calls | OK | Failed attempts (conflicts) | Calls retried | SWARM_BUSY | Other errors | p50 ms | p95 ms | max ms |+|---|---|---|---|---|---|---|---|---|---|+| desktop | 120 | 120 | 0 | 0 | 0 | 0 | 26.1 | 39.7 | 70.8 |+| host | 240 | 240 | 0 | 0 | 0 | 0 | 32.8 | 54.6 | 81.0 |+| machine | 48 | 48 | 37 | 20 | 0 | 0 | 66.3 | 371.2 | 958.8 |+| terminal | 470 | 465 | 433 | 168 | 5 | 0 | 77.0 | 1174.3 | 3755.8 |+| worker | 596 | 591 | 605 | 285 | 5 | 0 | 91.3 | 825.5 | 3377.0 |++## Mixed Swarm, run 1++By kind of writer (`delivery` is each host's delivery passes):++| Kind | Calls | OK | Failed attempts (conflicts) | Calls retried | SWARM_BUSY | Other errors | p50 ms | p95 ms | max ms |+|---|---|---|---|---|---|---|---|---|---|+| delivery | 1923 | 1919 | 332 | 135 | 4 | 0 | 45.9 | 186.8 | 3512.3 |+| desktop | 120 | 120 | 0 | 0 | 0 | 0 | 38.1 | 95.9 | 229.1 |+| host | 240 | 240 | 0 | 0 | 0 | 0 | 59.5 | 208.3 | 477.1 |+| lead | 26 | 14 | 138 | 22 | 12 | 0 | 2065.9 | 3467.1 | 3587.9 |+| machine | 48 | 39 | 163 | 37 | 9 | 0 | 476.6 | 4274.5 | 4479.9 |+| terminal | 326 | 147 | 1770 | 268 | 179 | 0 | 2456.9 | 4346.4 | 5719.3 |+| worker | 596 | 374 | 2806 | 511 | 222 | 0 | 1401.5 | 4031.2 | 5485.7 |++By operation:++| Operation | Calls | OK | Failed attempts (conflicts) | Calls retried | SWARM_BUSY | Other errors | p50 ms | p95 ms | max ms |+|---|---|---|---|---|---|---|---|---|---|+| deliveries.list | 840 | 840 | 0 | 0 | 0 | 0 | 32.1 | 98.9 | 502.5 |+| delivery.ack | 540 | 539 | 129 | 55 | 1 | 0 | 54.6 | 223.1 | 3097.0 |+| delivery.claim | 543 | 540 | 203 | 80 | 3 | 0 | 57.6 | 400.0 | 3512.3 |+| message.send | 339 | 192 | 1769 | 304 | 147 | 0 | 1900.9 | 4059.3 | 5485.7 |+| native.append | 326 | 147 | 1770 | 268 | 179 | 0 | 2456.9 | 4346.4 | 5719.3 |+| observeMachine | 48 | 39 | 163 | 37 | 9 | 0 | 476.6 | 4274.5 | 4479.9 |+| read.desktop | 120 | 120 | 0 | 0 | 0 | 0 | 38.1 | 95.9 | 229.1 |+| read.host | 240 | 240 | 0 | 0 | 0 | 0 | 59.5 | 208.3 | 477.1 |+| work.check | 128 | 92 | 516 | 104 | 36 | 0 | 801.4 | 3778.6 | 4303.0 |+| work.status | 155 | 104 | 659 | 125 | 51 | 0 | 736.6 | 3975.9 | 4709.3 |++The latency is mostly waiting to retry. A Desktop poll takes under 40 ms (p50), but a write that has to retry takes+seconds. Terminal answers whose prompt had ended in `SWARM_BUSY` were not sent: 146 and 134 in the+two mixed runs, 2 in the lane. The bench counts them as skipped. The recorder refuses an answer whose prompt+was not recorded, and a real host records a gap at that point.++## Per reader (mixed, run 1)++Response bytes during the load, and one isolated poll after it with nothing else running. The isolated poll counts what+MongoDB sent the backend (its `serverStatus` bytes out, minus the status call's own reply).++| Reader | Polls | p50 ms | p95 ms | Mean KB | p95 KB | Isolated: response KB | Isolated: database KB |+|---|---|---|---|---|---|---|---|+| desktop:[email protected] | 40 | 37.8 | 69.4 | 1020.0 | 1026.8 | 1026.9 | 1037.4 |+| desktop:[email protected] | 40 | 38.0 | 86.9 | 1019.9 | 1026.8 | 1026.9 | 1037.4 |+| desktop:[email protected] | 40 | 39.4 | 95.9 | 1020.1 | 1026.8 | 1026.9 | 1037.4 |+| host:bench-machine-0 | 120 | 56.7 | 183.4 | 5.1 | 5.1 | 5.1 | 1040.9 |+| host:bench-machine-1 | 120 | 61.3 | 208.3 | 4.1 | 4.1 | 4.1 | 1040.4 |++## What group 6 compares++Rerun all three with the parts driver (`--driver <name>`, and `--lane cross-group` for the third) on the same kind of+machine, and check that the plan fingerprints match. These are suggestions, for the Lead and the owner to confirm:++- **Goal 1 (cross-group lane only):** the `worker`, `terminal` and `machine` kinds show 0 failed attempts and 0+ `SWARM_BUSY`. In the mixed Swarm, conflicts within one group (a worker's posts with its own terminal, or the Lead's+ messages into its group) may remain, which the goal allows. No threshold applies there.+- **Goal 3:** a Desktop reader's polls during the load cost about what changed in those 3 s, not 1 MB. An isolated+ poll of an up-to-date reader is near zero, both its response and what MongoDB sends for it. The same holds for the+ host tick.+- **Hot Swarm** (`--done-share 0`: all 200 groups active, the same 20 workers spread over them), for the variant the+ Lead asked for. No baseline is recorded here.++## Limits of this measure++- One local mongod on a laptop, without a network, so absolute latencies are not production's. Production's+ conflicts were worse: a 1.16 MB Swarm lost all five retries of a person's `agent.add`. Compare counts and rates+ between runs on the same machine.+- Which calls conflict depends on timing, so retry counts move by a few percent between runs (see the two mixed+ columns). The planned work is identical (same fingerprint).+- The bench models no `agent.start` dispatch, joins, sharing or Pro cards. It has 5 readers, as the brief names. In+ production every host also ticks every 1 s, and every open Desktop window polls.+- Setup is not measured. It builds the Swarm through 1,178 sequential commands before the load starts.+diff --git a/docs/performance/2026-10-26-swarm-state-results-e2e.test.mts b/docs/performance/2026-10-26-swarm-state-results-e2e.test.mtsnew file mode 100644index 000000000..d866b83bd--- /dev/null+++ b/docs/performance/2026-10-26-swarm-state-results-e2e.test.mts@@ -0,0 +1,206 @@+// Reference: the isolated end-to-end run behind docs/performance/2026-10-26-swarm-state-results.md ("Isolated end to+// end"), #1726 group 6. Not part of any suite; kept so its figures can be traced. It needs group 3's local backend+// recipe running first (MongoDB replica set on 127.0.0.1:27117, Redis on :16379, the fake sign-in on :18990, the backend+// on :18085). The fake sign-in must know the three tokens below: the recipe's owner and peer, plus an outsider+// (local-outsider-token, [email protected]). It uses port 18086 for its counting proxy. It starts one isolated daemon from+// the CLI's end-to-end harness (throwaway home and data, private tmux, a free port; never 18473, the everyday daemon's)+// and never reaches any host but 127.0.0.1. From cli/:+//+// E2E_OUT=<file.json> npx vitest run --root ../docs/performance --globals --testTimeout 900000 \+// 2026-10-26-swarm-state-results-e2e.test.mts+//+// Any failed check, or any failed post in the busy window, fails the run; the JSON file is written either way.+// The CLI's test isolation must load before anything else: it gives this run its own home and data folders.+import '../../cli/vitest.setup.ts'+import { createServer, request as httpRequest } from 'node:http'+import { connect } from 'node:net'+import { writeFileSync } from 'node:fs'+import { join } from 'node:path'+import { randomUUID } from 'node:crypto'+import { IsolatedDaemon, until } from '../../cli/e2e/harness/daemon.ts'+import { LocalClient } from '../../cli/e2e/harness/client.ts'++const B = 'http://127.0.0.1:18085', PROXY = 18086+const OWNER = 'local-owner-token', PEER = 'local-peer-token', OUTSIDER = 'local-outsider-token'+const out = process.env.E2E_OUT!+const results: Record<string, unknown> = {}+// Every failed check fails the run (after the results file is written), so a leak or an empty window never passes.+const failed: string[] = []+const ok = (name: string, pass: boolean, detail: unknown) => {+ results[name] = { pass, detail }+ if (!pass) failed.push(name)+ console.log(`${pass ? 'PASS' : 'FAIL'} ${name} ${JSON.stringify(detail).slice(0, 400)}`)+}++async function api(token: string, path: string, method = 'GET', body?: unknown) {+ // A call that hangs fails after 30 s (a post in the busy window then counts as failed) instead of stalling the run.+ const r = await fetch(`${B}${path}`, { method, headers: { authorization: `Bearer ${token}`, ...(body ? { 'content-type': 'application/json' } : {}) },+ body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(30_000) })+ const text = await r.text()+ let json: any = null+ try { json = JSON.parse(text) } catch {}+ return { status: r.status, bytes: Buffer.byteLength(text), body: json }+}+const command = async (token: string, tab: string, cmd: unknown, asAgentId?: string) => {+ const r = await api(token, `/api/super-tabs/${tab}/commands`, 'POST', { operationId: randomUUID(), command: cmd, ...(asAgentId ? { asAgentId } : {}) })+ if (!r.body?.success) throw new Error(`command failed ${JSON.stringify(cmd).slice(0, 120)}: ${r.status} ${JSON.stringify(r.body)}`)+ return r.body.data+}++// The proxy: counts each host-form reply (bytes, and whether it carried rows) the daemon reads.+interface HostRead { at: number; method: string; full: boolean; bytes: number; tabsWithRows: number; unchanged: number }+let hostReads: HostRead[] = []+const otherPaths: Record<string, { count: number; bytes: number }> = {}+const proxy = createServer((req, res) => {+ const chunks: Buffer[] = []+ req.on('data', c => chunks.push(c))+ req.on('end', () => {+ const upstream = httpRequest({ host: '127.0.0.1', port: 18085, path: req.url, method: req.method, headers: { ...req.headers, host: '127.0.0.1:18085' } }, up => {+ const body: Buffer[] = []+ up.on('data', c => body.push(c))+ up.on('end', () => {+ const buf = Buffer.concat(body), path = (req.url ?? '').split('?')[0]!+ if (/^\/api\/super-tabs\/hosts\/[^/]+\/changes$/.test(path)) {+ let tabs: any[] = []+ try { tabs = JSON.parse(buf.toString()).data?.tabs ?? [] } catch {}+ hostReads.push({ at: Date.now(), method: req.method!, full: /full=1/.test(req.url ?? '') || /"full":true/.test(Buffer.concat(chunks).toString()),+ bytes: buf.byteLength, tabsWithRows: tabs.filter(t => Array.isArray(t.roster)).length, unchanged: tabs.filter(t => t.unchanged).length })+ } else {+ const key = `${req.method} ${path.replace(/[0-9a-f]{24}/g, ':id')}`+ otherPaths[key] = { count: (otherPaths[key]?.count ?? 0) + 1, bytes: (otherPaths[key]?.bytes ?? 0) + buf.byteLength }+ }+ res.writeHead(up.statusCode!, up.headers)+ res.end(buf)+ })+ })+ upstream.on('error', e => { res.writeHead(502).end(String(e)) })+ upstream.end(Buffer.concat(chunks))+ })+})+proxy.on('upgrade', (req, socket, head) => {+ const up = connect(18085, '127.0.0.1', () => {+ up.write(`${req.method} ${req.url} HTTP/1.1\r\n${Object.entries(req.headers).map(([k, v]) => `${k}: ${k === 'host' ? '127.0.0.1:18085' : v}`).join('\r\n')}\r\n\r\n`)+ if (head.length) up.write(head)+ up.pipe(socket); socket.pipe(up)+ })+ up.on('error', () => socket.destroy()); socket.on('error', () => up.destroy())+})+declare const test: (name: string, body: () => Promise<void>, timeout: number) => void+test('isolated end to end', async () => {+await new Promise<void>(r => proxy.listen(PROXY, '127.0.0.1', r))++let daemon: IsolatedDaemon | null = null+try {+ // Seed: the owner's machine is the daemon's computer.+ const computerId = randomUUID().replaceAll('-', '')+ const machineId = (await api(OWNER, '/api/machines/resolve-computer', 'POST', { computerId, label: 'G6 isolated machine' })).body.data.machine.machineId as string+ const tab = (await api(OWNER, '/api/super-tabs', 'POST', { operationId: randomUUID(), name: 'G6 local Swarm' })).body.data.id as string+ const configuration = { engine: 'claude', model: 'opus', effort: 'high', contextWindow: null, engineVersion: null }+ const lead = (await command(OWNER, tab, { type: 'agent.add', conversationId: 'lead', machineId, harnessId: 'g6-lead-harness', name: 'Lead', lead: true, configuration })).result.agentId as string+ const invite = (await command(OWNER, tab, { type: 'invite.create', email: '[email protected]', role: 'collaborator', conversationId: 'lead' })).result.inviteId as string+ await command(PEER, tab, { type: 'invite.accept', inviteId: invite })+ const work = (await command(OWNER, tab, { type: 'conversation.create', title: 'Shared work', brief: 'A shared group.', checks: [] })).result.conversationId as string+ const builder = (await command(OWNER, tab, { type: 'agent.add', conversationId: work, machineId, harnessId: 'g6-builder-harness', name: 'Builder', lead: false, configuration })).result.agentId as string+ for (let i = 0; i < 30; i++) await command(OWNER, tab, { type: 'conversation.create', title: `Filler ${i}`, brief: 'x'.repeat(400), checks: [] })+ const ownerLoad = await api(OWNER, `/api/super-tabs/${tab}/parts`)+ const ownerId = ownerLoad.body.data.members.find((m: any) => m.data.email === '[email protected]').data.id as string+ const privateId = (await command(OWNER, tab, { type: 'conversation.create', title: 'Owner only', brief: 'Private note.', checks: [], audience: { personIds: [ownerId] } })).result.conversationId as string+ Object.assign(results, { tab, machineId, lead, builder, work, privateId })++ // 1. First load.+ const first = await api(OWNER, `/api/super-tabs/${tab}/parts`)+ const groupIds = (load: any) => load.body.data.groups.map((g: any) => g.key)+ ok('first load', first.status === 200 && first.body.data.format === 2 && groupIds(first).includes(work) && groupIds(first).includes(privateId),+ { bytes: first.bytes, groups: first.body.data.groups.length, agents: first.body.data.agents.length, members: first.body.data.members.length })++ // 2. Change reads: an idle read after the overlap is small; then a second client's post shows up.+ const peerFirst = await api(PEER, `/api/super-tabs/${tab}/parts`)+ ok('private conversation absent for a non-audience reader: first load', !groupIds(peerFirst).includes(privateId) && groupIds(peerFirst).includes(work),+ { peerGroups: peerFirst.body.data.groups.length, ownerGroups: first.body.data.groups.length })+ const privateOne = await api(PEER, `/api/super-tabs/${tab}/groups/${privateId}`)+ ok('private conversation absent for a non-audience reader: one group', privateOne.status === 404, { status: privateOne.status })+ const privateMessages = await api(PEER, `/api/super-tabs/${tab}/conversations/${privateId}/messages`)+ ok('private conversation absent for a non-audience reader: messages', privateMessages.status >= 400, { status: privateMessages.status })+ console.log('waiting 31 s for the change-read overlap to pass')+ await new Promise(r => setTimeout(r, 31_000))+ // The first change read resends what changed in the 30 s before the first load (the overlap); the next one is idle.+ const catchUp = await api(OWNER, `/api/super-tabs/${tab}/changes?cursor=${first.body.data.cursor}`)+ const idle = await api(OWNER, `/api/super-tabs/${tab}/changes?cursor=${catchUp.body.data.cursor}`)+ ok('change read, idle', idle.status === 200 && idle.body.data.reload === false && idle.body.data.groups.length === 0,+ { bytes: idle.bytes, catchUpBytes: catchUp.bytes, firstLoadBytes: first.bytes })+ const posted = await command(PEER, tab, { type: 'message.send', conversationId: work, text: 'Hello from the second client.', replyTo: null, recipientIds: [] })+ const changed = await api(OWNER, `/api/super-tabs/${tab}/changes?cursor=${idle.body.data.cursor}`)+ const messages = await api(OWNER, `/api/super-tabs/${tab}/conversations/${work}/messages`)+ ok('a post from a second client appears', groupIds(changed).includes(work) && JSON.stringify(messages.body).includes('Hello from the second client.'),+ { bytes: changed.bytes, groupsSent: changed.body.data.groups.length, parts: posted.parts })+ // A private post: the owner's change read carries it, the peer's does not.+ const peerCursor = (await api(PEER, `/api/super-tabs/${tab}/parts`)).body.data.cursor+ await new Promise(r => setTimeout(r, 31_000))+ const peerIdle = await api(PEER, `/api/super-tabs/${tab}/changes?cursor=${peerCursor}`)+ await command(OWNER, tab, { type: 'message.send', conversationId: privateId, text: 'Owner only note.', replyTo: null, recipientIds: [] })+ const peerChanged = await api(PEER, `/api/super-tabs/${tab}/changes?cursor=${peerIdle.body.data.cursor}`)+ ok('private conversation absent for a non-audience reader: changes after a private post', !groupIds(peerChanged).includes(privateId) && !JSON.stringify(peerChanged.body).includes(privateId),+ { groupsSent: peerChanged.body.data.groups.length })+ const outsider = await api(OUTSIDER, `/api/super-tabs/${tab}/parts`)+ ok('a non-member cannot read the Swarm', outsider.status === 403 || outsider.status === 404, { status: outsider.status })++ // 3. Old routes answer 426 UPDATE_REQUIRED.+ const old = await Promise.all([`/api/super-tabs`, `/api/super-tabs/${tab}`, `/api/super-tabs/hosts/${machineId}`, `/api/super-tabs/hosts/${machineId}/pools`,+ `/api/super-tabs/hosts/${machineId}/assignments`].map(async path => { const r = await api(OWNER, path); return { path, status: r.status, code: r.body?.error?.code } }))+ ok('old routes answer 426 UPDATE_REQUIRED', old.every(r => r.status === 426 && r.code === 'UPDATE_REQUIRED'), old)++ // 4. An isolated daemon signed in as the owner, through the counting proxy.+ daemon = await IsolatedDaemon.create({ env: { ADAPTER_COMPUTER_ID: computerId, BACKEND_WS_URL: `ws://127.0.0.1:${PROXY}`, WEB_URL: `http://127.0.0.1:${PROXY}`,+ HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200' } })+ if (daemon.port === 18473) throw new Error('refusing the everyday daemon port')+ writeFileSync(join(daemon.root, 'auth/session.json'), JSON.stringify({ version: 1, accessToken: OWNER, refreshToken: 'x', autonomousEnv: 'prod', computerId, machineId,+ expiresAt: Date.now() + 3_600_000, updatedAt: Date.now() }), { mode: 0o600 })+ await daemon.start()+ await until('daemon connected', async () => (await (await fetch(`http://127.0.0.1:${daemon!.port}/api/status`, { headers: daemon!.localHeaders() })).json()).connected === true, 60_000, 200)+ ok('isolated daemon connected', true, { port: daemon.port, root: daemon.root })+ // The agents were added before the daemon signed in, so nothing woke its Swarm host: wake it as the e2e suites do.+ const local = await LocalClient.connect(daemon, { machineId })+ ok('host woken', (await local.request('super_tabs', { action: 'wake' }) as { ok?: boolean }).ok === true, {})+ local.close()+ await until('first host form read', async () => hostReads.length > 0, 60_000, 200)+ const fullForm = hostReads.find(r => r.full && r.tabsWithRows > 0)+ // Let the minute's full read settle, then measure idle and active windows of 60 s each.+ await new Promise(r => setTimeout(r, 5_000))+ // Each window lasts this long; with work, a post every 5 s. Every post is counted, and one that fails fails the check.+ const WINDOW_MS = 60_000, POST_EVERY_MS = 5_000+ const window = async (label: string, during?: () => Promise<void>) => {+ hostReads = []+ const posts: Array<Promise<boolean>> = []+ const post = () => posts.push(during!().then(() => true, error => { console.log('post failed', error); return false }))+ const started = Date.now(), timer = during ? setInterval(post, POST_EVERY_MS) : null+ await new Promise(r => setTimeout(r, WINDOW_MS))+ if (timer) clearInterval(timer)+ const outcomes = await Promise.all(posts)+ const reads = hostReads.filter(r => r.at >= started)+ const total = reads.reduce((s, r) => s + r.bytes, 0)+ return { label, reads: reads.length, avgBytes: Math.round(total / Math.max(1, reads.length)), maxBytes: Math.max(...reads.map(r => r.bytes)),+ withRows: reads.filter(r => r.tabsWithRows > 0).length, full: reads.filter(r => r.full).length,+ postsOk: outcomes.filter(Boolean).length, postsFailed: outcomes.filter(o => !o).length,+ methods: [...new Set(reads.map(r => r.method))] }+ }+ const idleTick = await window('idle')+ let n = 0+ const activeTick = await window('active', async () => { await command(OWNER, tab, { type: 'message.send', conversationId: work, text: `Lead note ${n++}`, replyTo: null, recipientIds: [builder] }, lead) })+ // A host ticks every second: at least half the window's seconds must show a read, and every planned post must land.+ const enoughReads = (w: { reads: number }) => w.reads >= WINDOW_MS / 2_000+ const plannedPosts = Math.floor((WINDOW_MS - 1) / POST_EVERY_MS)+ ok('host tick bytes with etag', enoughReads(idleTick) && enoughReads(activeTick) && activeTick.methods.includes('POST')+ && activeTick.postsFailed === 0 && activeTick.postsOk >= plannedPosts,+ { fullFormBytes: fullForm?.bytes ?? null, idle: idleTick, active: activeTick })++ results.otherDaemonReads = otherPaths+ if (failed.length) throw new Error(`Failed checks: ${failed.join('; ')}`)+} catch (error) {+ console.log('ERROR', (error as Error).stack)+ throw error+} finally {+ await daemon?.close().catch(() => {})+ proxy.closeAllConnections(); proxy.close()+ writeFileSync(out, JSON.stringify(results, null, 2))+}+}, 900_000)diff --git a/docs/performance/2026-10-26-swarm-state-results.md b/docs/performance/2026-10-26-swarm-state-results.mdnew file mode 100644index 000000000..c63df3c36--- /dev/null+++ b/docs/performance/2026-10-26-swarm-state-results.md@@ -0,0 +1,342 @@+# Swarm state by parts: results on the integration branch (#1726)++The "after" numbers for [Swarm state by parts](../plans/2026-10-26-swarm-state-parts.md), measured on the combined+branch and compared with [the baseline on main](2026-10-26-swarm-state-baseline.md):+- **Goals 1 and 3:** the same benchmark, seeds and lanes as the baseline.+- **Goal 4:** the migration dry run.+- **Working together:** the suites and an isolated end-to-end run check that the parts work together.++**Status:** goals 1, 3 and 4 are met on `44d51aae8`. The migration dry run also ran on `63a497c0e`, the base that+ships: rollback there refuses, by design, the Swarms the previous release would misread.++A first run on `b4b28aec8` found that goal 3 held for what clients receive, but not for what the server reads from+MongoDB. That was fixed in its own group (#1745). Its before and after numbers are kept below.++## Code and machine++- **Integration head:** `feat/swarm-state-parts` at `44d51aae8`. It holds groups 0–5 (PRs #1731–#1735, #1737), the+ host-row clean-up (#1739), tonight's v1 work (liveness and takeover #1742 and #1744, routing readiness #1743) and the+ database-read fix (#1745).+- **What ran:** unless a section names another commit, the runs are from `4b8b5ea8a` on `validate/swarm-state-parts`,+ with a clean tree. That commit is the head plus this document. Other commits, where they apply:+ - the "before #1745" figures are from `b4b28aec8` (`03180d7a1` for the end-to-end run);+ - the Desktop suites, and the end-to-end reference file as checked in, ran on `1d79b4e57`. That commit adds #1746+ (Desktop's private chat with the PM), which changes only `desktop/` and `docs/`;+ - the first dry run in Goal 4 ran on `63a497c0e`, the base that ships, with the rollback guards of #1748–#1750.+- **Main, for comparison:**+ - the baseline runs at `b71522ab6` (main `0d3485bad`);+ - the hot variant, new here, at `f53d296d8`, whose `backend/src` and `backend/prisma` are identical to main.+- **Machine:** the baseline's: Apple M1 Max, 10 cores, 64 GB, macOS (Darwin 25.6.0, arm64), Node 24.18.0, MongoDB+ 7.0.24 as a local single-node replica set.+- **Units:** KB is 1,024 bytes, as in the baseline.++## The benchmark change, and what it changes in the numbers++On the integration branch the old full-state routes answer 426, so the benchmark stopped at setup ("Snapshot failed:+UPDATE_REQUIRED"). The Lead approved fixing it here. The change is in the head as `ae2348366`, and touches the bench+folder only:++- **The new-store driver** (`--driver parts`, now the default) reads the way the merged clients read:+ - setup facts come from a first load, and machine generations from the host form;+ - each Desktop window does one first load, then a change read since its cursor every 3 s; a `reload` answer is+ followed by a first load in the same poll;+ - each host reads its host form every 1 s: in full at start and at least every minute, by change in between, naming+ the etags of the rows it holds.+- **The main driver** (`--driver legacy`) is unchanged. Main's clients really do read the whole state, so main keeps+ those reads.+- **Same seeds, plans and lanes.** The plan fingerprints match the baseline: mixed `8ba3412b11e82391`, cross-group+ `575e841eb53ecf49`, hot `d078610a00b2c6bf`.++Numbers whose meaning changed:++| Measure | On main | On the new store |+|---|---|---|+| Desktop poll | the whole visible state | the first poll is a first load; later polls are change reads, which by design resend every part changed in the last 30 s |+| Host tick | today's roster route | the host form, with etags |+| State size | the one `SuperTab` document | the live parts: 7 collections, without tombstones or dormant groups |+| Isolated poll | one more poll after the load | the same, by a reader already up to date. The Desktop poll still falls inside the 30 s overlap, because the load just ended |++## Goal 1: agents in different groups never conflict++| Measure | Main: lane | New store: lane | Main: mixed 1 / 2 | New store: mixed 1 / 2 | Main: hot | New store: hot |+|---|---|---|---|---|---|---|+| Agent calls (worker posts, terminal turns) | 1,066 | 1,068 | 922 / 934 | 1,068 / 1,068 | 1,054 | 1,068 |+| … needed a retry | 453 (42%) | **0** | 779 / 785 (84%) | 8 / 9 (1%) | 581 (55%) | 5 (0%) |+| … failed transaction attempts | 1,038 | **0** | 4,576 / 4,338 | 10 / 10 | 1,990 | 6 |+| … `SWARM_BUSY` | 10 | **0** | 401 / 354 | 0 / 0 | 52 | 0 |+| Machine reports: failed attempts / `SWARM_BUSY` | 37 / 0 | **0 / 0** | 163 / 9, 201 / 15 | 0 / 0, 0 / 0 | 148 / 4 | 0 / 0 |+| Lead: failed attempts / `SWARM_BUSY` | — | — | 138 / 12, 122 / 9 | 0 / 0, 0 / 0 | 57 / 0 | 0 / 0 |+| All writes: calls / failed attempts / `SWARM_BUSY` | 1,114 / 1,075 / 10 | 1,116 / 0 / 0 | 2,079 / 5,209 / 426, 2,170 / 4,976 / 381 | 3,994 / 22 / 0, 3,994 / 20 / 0 | 2,998 / 2,308 / 56 | 3,078 / 20 / 0 |++- **Cross-group lane (the goal-1 test):** worker, terminal and machine writes have 0 failed attempts, 0 retries and+ 0 `SWARM_BUSY`, against 42% retried on main. Every conflict left on main there was across groups. This is the+ threshold the baseline set, and it is met.+- **Mixed Swarm:** the few conflicts left are within one group: a worker's post with its own terminal turn, or a+ delivery claim with the post that made it. The goal allows those. No call ran out of retries.+- **Hot Swarm:** all 200 groups are active, with the same 20 workers spread over them. 5 calls retried, against 55% on+ main.+- **Why the call counts differ:** more calls ran on the new store, but the planned work is identical. On main, a+ terminal answer whose prompt ran out of retries is never sent (146 and 134 skipped in the mixed runs). Each turn+ that does land also makes a delivery to claim and acknowledge (2,852 delivery calls here, against 1,923 and 2,002).+- **Latency:** write p50 is 30–57 ms on the new store. On main it was 0.7–2.5 s, mostly waiting to retry.++By kind of writer, cross-group lane on the new store:++| Kind | Calls | OK | Failed attempts (conflicts) | Calls retried | SWARM_BUSY | Other errors | p50 ms | p95 ms | max ms |+|---|---|---|---|---|---|---|---|---|---|+| desktop | 120 | 120 | 0 | 0 | 0 | 0 | 31.5 | 52.8 | 109.3 |+| host | 240 | 240 | 0 | 0 | 0 | 0 | 37.3 | 63.8 | 112.8 |+| machine | 48 | 48 | 0 | 0 | 0 | 0 | 36.2 | 48.7 | 84.9 |+| terminal | 472 | 472 | 0 | 0 | 0 | 0 | 46.1 | 68.3 | 88.1 |+| worker | 596 | 596 | 0 | 0 | 0 | 0 | 44.2 | 65.4 | 143.6 |++Mixed Swarm, run 1, on the new store:++| Kind | Calls | OK | Failed attempts (conflicts) | Calls retried | SWARM_BUSY | Other errors | p50 ms | p95 ms | max ms |+|---|---|---|---|---|---|---|---|---|---|+| delivery | 2852 | 2852 | 12 | 6 | 0 | 0 | 40.3 | 71.0 | 411.4 |+| desktop | 120 | 120 | 0 | 0 | 0 | 0 | 43.5 | 81.0 | 103.6 |+| host | 240 | 240 | 0 | 0 | 0 | 0 | 49.8 | 91.2 | 114.3 |+| lead | 26 | 26 | 0 | 0 | 0 | 0 | 49.0 | 80.6 | 119.6 |+| machine | 48 | 48 | 0 | 0 | 0 | 0 | 40.0 | 53.7 | 94.0 |+| terminal | 472 | 472 | 2 | 2 | 0 | 0 | 57.4 | 91.5 | 171.5 |+| worker | 596 | 596 | 8 | 6 | 0 | 0 | 49.9 | 85.5 | 237.5 |++## Goal 3: a poll costs what changed++### What clients receive++| Measure | Main (mixed) | New store (mixed 1 / 2) | Main (hot) | New store (hot) |+|---|---|---|---|---|+| Desktop poll during the load, p50 | 1,021.8 KB | 109.7 KB | 771.7 KB | 363.6 KB |+| Desktop poll during the load, mean (includes the first load) | 1,020.0 KB | 233.5 / 236.7 KB | 769.9 KB | 456.7 KB |+| Host tick during the load, p50 | 4.1 KB | 269 B | 4.1 KB | 269 B |+| Host tick, isolated (up to date) | 4–5 KB | 268–269 B | 4–5 KB | 268 B |+| State after the load | 1 document, 1,036.5 KB | 237 parts, 1,170.0 KB | 1 document, 777.0 KB | 237 parts, 902.8 KB |++- **Desktop:** in the busy Swarm, a change read carries every part changed in the last 30 s. All 20 active groups+ change in that time, so about 110 KB comes back, about a tenth of today's full read. In the hot Swarm more groups+ change, so it is about half. On an idle Swarm a change read is small: 2.8 KB on the 200-group Swarm (below), 518 B+ on the local stack.+- **Host:** a tick is about 269 B, against 4–5 KB, because the server answers "unchanged" to the etags the host holds.+- **Stored state:** not smaller in this benchmark, because no group goes dormant during a two-minute run (a finished+ group goes dormant after a day idle). Goal 2 is shown by the dry run instead: in the 1.16 MB Swarm, 126 of 196+ groups are dormant, and a first load is 316.6 KB.++### What the server reads from MongoDB++The isolated poll counts what MongoDB sends the backend for one poll (`serverStatus` bytes out). It runs right after+the load, by a reader already up to date. Mixed run 1:++| Reader | Polls | p50 ms | p95 ms | Mean KB | p95 KB | Isolated: response KB | Isolated: database KB |+|---|---|---|---|---|---|---|---|+| desktop:[email protected] | 40 | 39.0 | 80.0 | 234.4 | 843.7 | 110.8 | 181.2 |+| desktop:[email protected] | 40 | 54.4 | 81.9 | 237.6 | 858.8 | 110.8 | 181.2 |+| desktop:[email protected] | 40 | 38.4 | 60.0 | 228.6 | 820.1 | 110.8 | 181.2 |+| host:bench-machine-0 | 120 | 50.9 | 82.9 | 0.3 | 0.3 | 0.3 | 138.0 |+| host:bench-machine-1 | 120 | 49.2 | 98.6 | 0.3 | 0.3 | 0.3 | 83.7 |++| Isolated poll, database KB | Main | Before #1745 (`b4b28aec8`) | Now |+|---|---|---|---|+| Desktop, mixed | 1,037.4 | 1,284.2 | 181.2 |+| Host, mixed | 1,040.4–1,040.9 | 2,320.8–2,325.5 | 83.7–138.0 |+| Desktop, hot | 774.6–778.0 | 1,279.4–1,291.9 | 438.9–451.5 |+| Host, hot | 781.0–781.5 | 1,801.0–1,804.5 | 81.8–128.3 |++A diagnostic separates idle from active: `backend/integration/bench/pollDatabaseBytes.ts`. It used the default+200-group Swarm (1,147.1 KB of parts), one up-to-date reader of each kind (Desktop as the owner, the host of machine 1),+and no write for 35 s. Run it from `backend/` (about 1.5 minutes, on its own loopback replica set). It prints one JSON+line per poll:++```bash+NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= \+ DATABASE_URL=mongodb://127.0.0.1:1/bench-never-used npx tsx integration/bench/pollDatabaseBytes.ts+```++The "before #1745" column is the same measurement at `b4b28aec8`.++| Poll | Sent to the client | Read from MongoDB, before #1745 | Read from MongoDB, now |+|---|---|---|---|+| Desktop change read, idle | 2.8 KB | 1,140.7 KB | 44.4 KB |+| Desktop change read, after one post | 6.9 KB | 1,145.3 KB | 49.1 KB |+| Host form, idle (nothing on its machine changed) | 132 B | 5.4 KB | 5.4 KB |+| Host form, after one post in a group with its agent | 269 B | 2,277.2 KB | 15.5 KB |+| Host form, in full | 5.7 KB | 2,275.0 KB | 69.1 KB |++Before #1745, every Desktop change read loaded the whole Swarm. A host form woken by any change to its machine's work+loaded it twice, just to answer "unchanged": 2.3 MB per tick per host in the busy run, against 1.04 MB on main. Now a+change read loads the parts that changed plus what the reader's view needs. A woken host form loads only the+conversations its rows read.++In the busy run that means:+- a host tick reads 84–138 KB from the database, against 1,041 KB on main;+- a Desktop change read reads 181 KB, against 1,037 KB.++Idle, a Desktop change read costs 44 KB and a host tick 5 KB.++## Goal 4: the migration dry run++`scripts/swarm-parts/dry-run.ts` runs on its own loopback replica set.++### On the base that ships++This run is from a clean checkout of `63a497c0e`. That base adds the rollback guards of #1748–#1750: rollback refuses+a Swarm that the previous release would misread. The dry run now writes one such Swarm of each kind after the migration+(step 5b). It exited 0 in 21.0 s.++| Step | Result | Time |+|---|---|---|+| Seed 13 synthetic production-shaped Swarms | the big one: 1.16 MB, 196 groups, 40,000 messages; medium: 412.2 KB, 51 groups, 8,000 messages; ten small; one from before projects | 3,024 ms |+| Migrate | 13 ok, 0 failed, each read back and verified field by field, message count and order unchanged; big 920 ms, medium 193 ms, the small ones 19–25 ms | 3,482 ms |+| Migrate again | nothing to do | 38 ms |+| Read by parts | the big one: first load 316.6 KB, idle change read 2.6 KB, host form 10.8 KB in full, 108 B idle; old Desktop read 1,130.8 KB | 182 ms |+| Real commands through the store, then poll | 4 commands, 1 part written each; change read after two of them 6.3 KB (1 group); the host running that work 4.5 KB, another host 108 B | 296 ms |+| 5b. Unsafe for the previous release, written after the migration | a private conversation in one small Swarm, a lost task in another | 30 ms |+| Roll back | **11 of 13 rolled back**: the 2 written since are rebuilt from their parts, and the other 9 are identical to their old state. **2 refused on purpose** (below) | 195 ms |+| Old-shape read of every rolled-back Swarm | ok for all 11: format 1, revision above every message sequence. This checks the rolled-back state's shape with this branch's reader, not the previous release's binary or its access checks | 78 ms |++The 2 refusals change nothing. The parts stay authoritative, so nothing is lost or made public, and the remedy is to+roll forward with a fix:+- **The Swarm with a private conversation:** the previous release would make its private conversation readable by+ every project reader.+- **The Swarm with a lost task:** the previous release would read that task as active work.++### Earlier, at `4b8b5ea8a`++This run is from before the rollback guards. It exited 0 in 15.3 s, and rolled back **13 of 13**:++| Step | Result | Time |+|---|---|---|+| Seed | the same 13 Swarms | 2,863 ms |+| Migrate | 13 ok, 0 failed, verified; big 952 ms, medium 209 ms, the small ones 20–25 ms | 3,561 ms |+| Migrate again | nothing to do | 38 ms |+| Read by parts | the same sizes as above | 189 ms |+| Real commands through the store, then poll | the same as above | 289 ms |+| Roll back | 13 ok: the 2 written since are rebuilt from their parts, and the other 11 are identical to their old state | 190 ms |+| Old read of every Swarm | ok: format 1, revision above every message sequence | 79 ms |++`integration/superTabMigration.test.ts` passed as part of `npm run test:super-tabs` at `4b8b5ea8a`. A first dry run on+`b4b28aec8` gave the same results (3,513 ms to migrate).++## Isolated end to end++The stack ran on one Mac at `4b8b5ea8a`, all on loopback, with its own data:+- **Database and cache:** a MongoDB 7 replica set and Redis 7 in throwaway containers.+- **Sign-in and backend:** a fake sign-in service with fixed test tokens, and the backend from that commit (group 3's+ recipe).+- **CLI daemon:** an isolated daemon from the CLI's end-to-end harness (throwaway home and private tmux), signed in as+ the test owner through a byte-counting proxy. The everyday daemon on port 18473 was never touched.+- **The Swarm:** 34 groups (one of them private to the owner), 2 people, and a Lead and a Builder on the daemon's+ machine.++| Behaviour | Result |+|---|---|+| First load | 26.4 KB: 34 groups, 2 agents, 2 members |+| Change reads | idle 518 B. The first read after a load resends the 30 s before it (26.4 KB), by design |+| A post from a second client appears | in the owner's next change read (919 B, 1 group) and in the messages |+| Private conversation, non-audience member | absent from their first load (33 of 34 groups), change read after a private post (0 groups), one-group read (404) and messages (404) |+| Non-member | 403 |+| Old routes | all five answer 426 `UPDATE_REQUIRED` |+| Host tick, idle, 60 s | 60 reads, 300 B on average: one full read each minute (3.6 KB), every other read empty |+| Host tick, active, 60 s (a Lead post every 5 s to the Builder in its group) | 59 reads, 257 B on average, at most 269 B. None carried rows; every read named the etags it held. A full host form here is 1.9 KB |+| Desktop | `flutter test test/super_tab_local_backend_test.dart` against this backend passed: one first load (28.0 KB), change reads of 1,050 B and 1,334 B, the second person's post appears, old route 426. Today's full read of that Swarm is about 24.5 KB |++**Desktop was checked through the real Swarm controller over HTTP, not by running the app.** Desktop sends its calls+through the daemon on port 18473, and on this Mac that is the everyday one, which must not be touched. The controller+is the code Desktop and the web app run, and the widget tests cover the screens on top of it.++Not covered here: `harness super-tab status` from an agent. It needs a live agent session, so the placeholder agents in+this Swarm get `AGENT_UNAVAILABLE`, as designed. Group 5 ran it with live sessions at `3cb3e3350`. The same run on+`03180d7a1`, before #1745, gave the same results. Both times the stack was taken down at the end: processes stopped and+containers removed, with no port left open.++## Reproducing the numbers++All of these run from `backend/` after `npm ci`. Each starts its own MongoDB replica set on 127.0.0.1 and reads no+other database.++**Benchmark, new store** (at the integration head, about 3 minutes each, one after the other on a quiet machine):++```bash+npm run bench:swarm-state # mixed, run 1; run it again for run 2+npm run bench:swarm-state -- --lane cross-group # the goal-1 lane+npm run bench:swarm-state -- --done-share 0 # the hot Swarm+```++**Benchmark, main** (the same three commands, from a checkout of `f53d296d8`, where the default driver is main's).+The mixed and lane baselines are recorded in [the baseline](2026-10-26-swarm-state-baseline.md). Only the hot run is+new here.++**Where the output lives.** Each run prints its markdown report and writes `<driver>-<time>.json` and `.md` to+`integration/bench/results/` (or `--out DIR`). That folder keeps only committed reports in git. The runs this document+quotes are committed there:+- main: `baseline-main-0d3485bad-{mixed-1,mixed-2,cross-group,hot}.json`;+- new store: `results-44d51aae8-{mixed-1,mixed-2,cross-group,hot}.json`.++Each report names its commit, machine and plan fingerprint.++**Database bytes per poll:** `pollDatabaseBytes.ts`, with the command above.++**Migration dry run:**++```bash+NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= \+ node --import tsx scripts/swarm-parts/dry-run.ts --out <folder>+```++It prints the timings and writes `swarm-parts-migration-<date>.json` to the folder.++**Isolated end to end:**+- The stack is group 3's local backend recipe: containers, fake sign-in and the backend on port 18085.+- The Desktop part is the opt-in test in `desktop/`:+ `SWARM_LOCAL_BACKEND=http://127.0.0.1:18085 SWARM_LOCAL_TAB=<Swarm id> flutter test --no-pub test/super_tab_local_backend_test.dart`.+- The rest came from [2026-10-26-swarm-state-results-e2e.test.mts](2026-10-26-swarm-state-results-e2e.test.mts). It+ is kept here as a reference file, outside every test suite. It uses the CLI's end-to-end harness+ (`cli/e2e/harness/daemon.ts`, `client.ts`), after `cli/vitest.setup.ts` for test isolation:+ - it seeds the Swarm and checks each behaviour over HTTP;+ - it starts an `IsolatedDaemon` signed in through a counting proxy on port 18086, and wakes its Swarm host;+ - it counts the host-form replies for 60 s idle, then 60 s with a post every 5 s.+- Any failed check fails the run, and so does any post in the busy window that fails or takes over 30 s. The JSON+ file is written either way.+- The fake sign-in must also accept `local-outsider-token` ([email protected]), for the non-member check. Without it,+ the run fails on that check, as it should.+- The figures above ran at `4b8b5ea8a` (integration head `44d51aae8`).+- The file as checked in ran again on base `1d79b4e57`, whose backend and CLI are the same, and passed all 12 checks.+ The other figures were the same. The host-tick windows differed by a few bytes:+ - idle: 60 reads averaging 284 B (300 B before);+ - active: 59 reads averaging 257 B, with all 11 posts landed.+- Run it from `cli/`, with the stack up, in about 4.5 minutes. It writes every check and its figures to the JSON+ file:++ ```bash+ E2E_OUT=<file.json> npx vitest run --root ../docs/performance --globals --testTimeout 900000 \+ 2026-10-26-swarm-state-results-e2e.test.mts+ ```++## Suites++Backend and CLI at `4b8b5ea8a`. Desktop at `1d79b4e57`, the current head, which adds #1746 under `desktop/`.++| Suite | Command | Result |+|---|---|---|+| Backend typecheck | `npm run typecheck` | 0 errors |+| Backend unit | `npm test` | 2,185 passed, 11 skipped, 1 failed. The failure is `src/lib/teamSession.test.ts` › "cannot share another machine's harness…" (expected 404, got 500), which fails identically on main |+| Backend integration | `npm run test:super-tabs` | 7 files, 274 passed (read and migration suites included) |+| Bench self-tests | `npx vitest run --config integration/bench/vitest.config.ts`; `npx tsc -p integration/bench/tsconfig.json` | 7 files, 42 passed; 0 errors |+| CLI typecheck | `npm run typecheck` | 0 errors |+| CLI Super Tab specs | `npx vitest run src/superTabs` | 34 files, 896 passed |+| CLI `test:super-tabs` | `npm run test:super-tabs` | 188 passed, 100% coverage |+| CLI `test:harnessd` | `npm run test:harnessd` | 358 passed, 1 skipped |+| CLI `test:core` | `npm run test:core` | 3,116 passed. The coverage gate fails with the same 15 misses as on main (transcripts `ingest`, `history`, `attach`, `lastTurn`; services `machineAddonsProcess`, `process`), compared line by line |+| Super Tab end to end | `npx vitest run --config vitest.e2e.config.ts e2e/superTabs.e2e.ts e2e/superTabMachines.e2e.ts e2e/superTabsCollaboration.e2e.ts e2e/superTabRoute.e2e.ts e2e/swarmLegacySkills.e2e.ts e2e/agentClient.e2e.ts` | 12 passed, 9 failed: exactly the 9 group 5 recorded as failing on the base (5 in `agentClient`, 3 in `superTabs`, 1 in `superTabsCollaboration`), compared by name |+| Desktop analyzer | `flutter analyze --no-pub` (Flutter 3.47.2) | 47 issues, the identical list at `d9cf81002`, none in a file #1726 changed |+| Desktop affected suites (VM) | `flutter test --no-pub --timeout 60s --concurrency=6 test/super_tab_*_test.dart test/welcome_closed_super_tabs_test.dart test/devices_harness_test.dart test/swarm_launch_recovery_test.dart test/swarm_projects_test.dart test/swarm_sharing_test.dart test/shared_tab_invites_test.dart` | 784 passed, 3 skipped (one is the opt-in local backend test). At `4eab760ed`, before #1746: 770 passed, 2 skipped |+| Desktop affected suites (Chrome) | `flutter test --no-pub --platform chrome --dart-define=HARNESS_TEST=true test/super_tab_reading_test.dart test/super_tab_reading_client_test.dart test/super_tab_reading_workspace_test.dart test/super_tab_saved_view_test.dart test/super_tab_saved_view_widget_test.dart test/super_tab_parts_reading_test.dart test/super_tab_dormant_groups_test.dart test/super_tab_message_paging_test.dart test/super_tab_update_required_test.dart` | 91 passed |++## Limits++- One local mongod on a laptop, without a network. Compare counts, rates and bytes between runs on the same machine,+ not absolute latencies.+- Read latency is close to main's: Desktop p50 is 31–54 ms against 19–38 ms, and host 37–51 ms against 24–60 ms.+- The benchmark keeps every group active for the run (no 24 h dormancy), and models no `agent.start` dispatch, joins,+ sharing or Pro cards.diff --git a/docs/performance/2026-10-27-pm-confidential-isolated-run.test.mts b/docs/performance/2026-10-27-pm-confidential-isolated-run.test.mtsnew file mode 100644index 000000000..e7fe7a165--- /dev/null+++ b/docs/performance/2026-10-27-pm-confidential-isolated-run.test.mts@@ -0,0 +1,146 @@+// Reference: the isolated run behind #1751 (final review, Critical 1): a person's private chat delivered into a real PM+// terminal, then every way of watching that session refused. Not part of any suite; kept so its output can be traced.+// It needs the local backend recipe (groups 3 and 6) running first, on loopback: MongoDB replica set on 127.0.0.1:27117,+// Redis on :16379, the backend of this branch on :18085, and a fake sign-in on :18990 that knows these four tokens:+// local-owner-token ([email protected], id local-owner), local-alice-token, local-bob-token, local-carol-token (the same+// pattern). It starts one isolated daemon from the CLI's end-to-end harness (throwaway home and data, private tmux, fake+// Claude Code engine, a free port; never 18473, the everyday daemon's) and never reaches any host but 127.0.0.1. From cli/:+//+// npx vitest run --root ../docs/performance --globals --testTimeout 600000 2026-10-27-pm-confidential-isolated-run.test.mts+//+// Any failed check fails the run.+import '../../cli/vitest.setup.ts'+import { mkdirSync } from 'node:fs'+import { join } from 'node:path'+import { randomBytes, randomUUID } from 'node:crypto'+import { until } from '../../cli/e2e/harness/daemon.ts'+import { signIn, type Account, type RealBackend } from '../../cli/e2e/harness/realBackend.ts'+import { superTabCommand } from '../../cli/src/superTabs/command.ts'+import { observerSource } from '../../cli/src/superTabs/observers.ts'++const B = 'http://127.0.0.1:18085'+const person = (name: string): Account => ({ name, token: `local-${name}-token`, id: `local-${name}`, email: `${name}@local.test` })+const [owner, alice, bob, carol] = ['owner', 'alice', 'bob', 'carol'].map(person) as [Account, Account, Account, Account]+const CONFIG = { engine: 'claude', model: 'sonnet', effort: 'high', contextWindow: null, engineVersion: null }+const FIXTURE_KEYS = { ANTHROPIC_API_KEY: 'fixture-not-a-credential', OPENAI_API_KEY: 'fixture-not-a-credential' }+const SECRET = 'Only for the PM: the launch slips a week.'++async function api(a: Account, path: string, method = 'GET', body?: unknown) {+ const r = await fetch(`${B}${path}`, { method, headers: { authorization: `Bearer ${a.token}`, ...(body ? { 'content-type': 'application/json' } : {}) },+ body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(30_000) })+ const text = await r.text()+ let json: any = null+ try { json = JSON.parse(text) } catch { /* not JSON */ }+ return { status: r.status, body: json }+}+const backend: RealBackend = { url: B, wsUrl: 'ws://127.0.0.1:18085', logPath: '', api, stop: async () => {} }+const failed: string[] = []+// Straight to stdout: the CLI's test setup keeps console output of a passing test to itself.+const say = (line: string) => { process.stdout.write(`${line}\n`) }+const check = (name: string, pass: boolean, detail: unknown) => {+ if (!pass) failed.push(name)+ say(`${pass ? 'PASS' : 'FAIL'} ${name} ${JSON.stringify(detail).slice(0, 600)}`)+}++it('delivers a private chat into a real PM terminal, then refuses every way of watching that session', async () => {+ const side = await signIn(backend, owner, FIXTURE_KEYS)+ const created = async (folder: string) => {+ const cwd = join(side.daemon.projectsDir, folder)+ mkdirSync(cwd, { recursive: true })+ const made = await side.client.request('agent_create', { engine: 'claude', cwd, bypassPermission: false }, 90_000)+ if (made.error) throw new Error(`${folder}: ${JSON.stringify(made)}`)+ return until(`${folder} to bind its conversation`, async () => {+ const agents = (await side.client.request<{ agents: Array<Record<string, any>> }>('agents_list', {}, 30_000)).agents+ const agent = agents.find(a => a.id === made.agent.id)+ return agent?.sessionId && agent.status === 'active' ? agent : null+ }, 60_000, 500)+ }+ const pmSession = await created('pm'), builderSession = await created('builder')+ say(`isolated daemon on port ${side.daemon.port}, machine ${side.machineId}; PM session ${pmSession.id}, Builder session ${builderSession.id}`)++ // Swarm A: Alice and Bob read its public project; the PM runs on the owner's machine (neither Alice's nor Bob's).+ const tab = (await api(owner, '/api/super-tabs', 'POST', { operationId: randomUUID(), name: 'Isolated C1' })).body.data.id as string+ const run = async (a: Account, command: Record<string, unknown>, tabId = tab) => api(a, `/api/super-tabs/${tabId}/commands`, 'POST', { operationId: randomUUID(), command })+ for (const reader of [alice, bob]) {+ const invite = await run(owner, { type: 'invite.create', email: reader.email, role: 'collaborator', conversationId: 'lead' })+ await run(reader, { type: 'invite.accept', inviteId: invite.body.data.result.inviteId })+ }+ const pm = (await run(owner, { type: 'agent.add', conversationId: 'lead', machineId: side.machineId, harnessId: pmSession.id, name: 'PM', configuration: CONFIG, lead: true })).body.data.result.agentId as string+ await run(owner, { type: 'agent.add', conversationId: 'lead', machineId: side.machineId, harnessId: builderSession.id, name: 'Builder', configuration: CONFIG, lead: false })+ // The PM joins as a launched agent does, which starts its machine's Swarm host.+ let joined = ''+ const status = await superTabCommand(['--tab', tab, '--agent', pm, 'status'],+ { where: () => ({ port: side.daemon.port, dataDir: side.daemon.dataDir, machineId: side.machineId }), print: text => { joined = text } })+ check('the PM joins and its host starts', status === 0, { status, out: joined.slice(0, 120) })++ // Shares made before the chat, through the real share route: Bob's from this Swarm, Carol's the ordinary way.+ const share = async (recipient: Account, agentId: string, superTabId: string | null) => {+ const id = randomUUID()+ const r = await api(owner, `/api/harness-shares/${id}`, 'PUT', { superTabId, machineId: side.machineId, agentId, recipientEmail: recipient.email,+ name: 'PM', engine: 'claude', ownerPublicKey: randomBytes(32).toString('base64'), expiresAt: new Date(Date.now() + 86_400_000).toISOString() })+ return { id, status: r.status }+ }+ const bobsShare = await share(bob, pmSession.id, tab), carolsShare = await share(carol, pmSession.id, null), carolsBuilderShare = await share(carol, builderSession.id, null)+ check('shares made before the chat (Bob from the Swarm, Carol ordinary, and a Builder control)', [bobsShare, carolsShare, carolsBuilderShare].every(s => s.status === 200),+ [bobsShare.status, carolsShare.status, carolsBuilderShare.status])++ // Alice's private chat with the PM, and her secret.+ // The Swarm knows each person by the backend's own user id: read Alice's from the member list.+ const members = (await api(owner, `/api/super-tabs/${tab}/parts`)).body.data.members as Array<{ data: { id: string; email: string } }>+ const aliceId = members.find(m => m.data.email === alice.email)!.data.id+ const opened = await run(alice, { type: 'conversation.create', title: 'Chat with PM', brief: '', checks: [], audience: { personIds: [aliceId] } })+ check('Alice opens her private chat with the PM', opened.status === 200, { status: opened.status, error: opened.body?.error })+ const chat = opened.body.data.result.conversationId as string+ const sent = await run(alice, { type: 'message.send', conversationId: chat, text: SECRET, replyTo: null, recipientIds: [] })+ check('Alice posts her secret in her private chat with the PM', sent.status === 200, { status: sent.status })++ // It arrives in the PM's real terminal: its host claims the delivery and types it in. The machine's owner reads that screen.+ let screen = ''+ await until('the secret on the PM\'s screen', async () => {+ const asked = await run(owner, { type: 'agent.screen', agentId: pm, scrollback: 200 })+ if (asked.status !== 200) { screen = JSON.stringify(asked.body); return null }+ const read = await api(owner, `/api/super-tabs/${tab}/terminal/${asked.body.data.result.requestId}`)+ screen = String(read.body?.data?.text ?? JSON.stringify(read.body))+ return screen.includes(SECRET) ? screen : null+ }, 120_000, 2_000).catch(() => null)+ check('the secret arrived in the PM\'s terminal (read by its machine\'s owner)', screen.includes(SECRET),+ screen.split('\n').filter(line => line.includes('launch slips')).slice(0, 3))++ // 1. The machine's roster lists nobody to watch the PM, and marks its session confidential.+ const form = await api(owner, `/api/super-tabs/hosts/${side.machineId}/changes?full=1`)+ const rows = (form.body.data.tabs.find((t: any) => t.tabId === tab)?.roster ?? []) as Array<Record<string, any>>+ const pmRow = rows.find(r => r.agent?.id === pm), builderRow = rows.find(r => r.agent?.harnessId === builderSession.id)+ check('roster: the PM has no observers and is confidential', pmRow?.observers?.length === 0 && pmRow?.confidential === true,+ { observers: pmRow?.observers, confidential: pmRow?.confidential })+ check('roster: the Builder keeps its observers (control)', (builderRow?.observers ?? []).length >= 2, builderRow?.observers?.map((o: any) => o.email))++ // 2. The backend no longer lists the earlier shares to their recipients; the Builder's still opens.+ // What each recipient's share list holds, by session. Bob also holds the Builder share his roster entry gives him (the host's own).+ const listed = async (a: Account) => ((await api(a, '/api/harness-shares')).body.data.machines as Array<any>)+ .flatMap(m => m.shares.map((s: any) => ({ id: s.id, session: s.agentId === pmSession.id ? 'PM' : s.agentId === builderSession.id ? 'Builder' : s.agentId })))+ const bobs = await listed(bob), carols = await listed(carol)+ check('backend: Bob\'s earlier Swarm share is refused', !bobs.some(s => s.id === bobsShare.id), { refused: bobsShare.id, listed: bobs })+ check('backend: Carol\'s earlier ordinary share is refused', !carols.some(s => s.id === carolsShare.id), { refused: carolsShare.id, listed: carols })+ check('backend: Carol\'s ordinary share of the Builder still opens (control)', carols.some(s => s.id === carolsBuilderShare.id), { opens: carolsBuilderShare.id })++ // 3. The CLI host's cache refuses both shares of the PM's session.+ const cache = observerSource(side.daemon.dataDir, () => side.machineId)+ const cacheBob = cache.allows({ tab: `super:${tab}`, agentId: pmSession.id, recipientEmail: bob.email } as never)+ const cacheCarol = cache.allows({ tab: null, agentId: pmSession.id, recipientEmail: carol.email } as never)+ check('CLI cache: the PM\'s Swarm share and ordinary share are refused', !cacheBob && !cacheCarol, { swarm: cacheBob, ordinary: cacheCarol })++ // 4. Bob may not read or type into the PM's terminal.+ const peek = await run(bob, { type: 'agent.screen', agentId: pm, scrollback: 200 })+ const typed = await run(bob, { type: 'agent.input', agentId: pm, text: 'history' })+ check('terminal: Bob cannot read or type into the PM', peek.status === 403 && typed.status === 403,+ { screen: [peek.status, peek.body?.error?.code], input: [typed.status, typed.body?.error?.code] })++ // 5. No second Swarm may register the PM's session.+ const other = (await api(owner, '/api/super-tabs', 'POST', { operationId: randomUUID(), name: 'Another Swarm' })).body.data.id as string+ const again = await run(owner, { type: 'agent.add', conversationId: 'lead', machineId: side.machineId, harnessId: pmSession.id, name: 'PM again', configuration: CONFIG, lead: false }, other)+ check('another Swarm cannot register the PM\'s session', again.status === 409 && again.body?.error?.code === 'SESSION_CONFIDENTIAL',+ { status: again.status, code: again.body?.error?.code })++ await side.daemon.stop()+ if (failed.length) throw new Error(`Failed: ${failed.join('; ')}`)+})diff --git a/docs/plans/2026-10-26-swarm-state-parts.md b/docs/plans/2026-10-26-swarm-state-parts.mdnew file mode 100644index 000000000..ccc03314a--- /dev/null+++ b/docs/plans/2026-10-26-swarm-state-parts.md@@ -0,0 +1,309 @@+# Spec: Swarm state by parts (#1726)++Draft 1, 2026-10-26, Product Manager (River). Issue: https://github.com/autonomous-ai/openharness/issues/1726++## Intent and why++A Swarm must keep working with many people and agents at once and over months. Today each Swarm is one Mongo+document (`SuperTab.state`, one `revision`). Every write rewrites all of it and conflicts with every other+write; every reader downloads all of it; it only grows. One Swarm already returned 500s from write conflicts+(#1722 added retries and `SWARM_BUSY`, which eases the symptom only). The org launch waits for this work.++## Owner decisions (ken15, 2026-10-26, in project chat)++- Not tied to the 29 Oct date. Solve it properly, on its own branch, then merge and release once. Launch to+ the autonomous.ai org after this ships.+- Every client (backend, CLI, Desktop, web) moves to the new version at the same time. No compatibility period+ for older CLIs or Desktops.+- Highest priority, as fast as possible.++## Goals (from the issue's "Done when")++1. Agents working in different work groups of one Swarm never conflict with each other. Measured on a busy+ synthetic Swarm before and after.+2. A Swarm's active data stays small whatever its history. Finished work stays readable in Work details.+3. A poll costs what changed, not the whole Swarm.+4. Existing Swarms are migrated in place, with no lost history (messages, groups, decisions, runs).++## Non-goals++- No new Swarm features, no UI redesign. Screens look and behave as today, apart from archived groups+ loading on demand.+- No change to message, delivery, route-decision, run or attempt collections beyond what the new sequence+ source needs (they are already separate).+- No push transport (websocket or SSE) in this project. Polling for changes is enough; push can come later on+ the same cursor.++## Anti-goals (must not happen)++- A command acting on a stale read of something its rule depends on. Examples: two starts both taking a+ machine's last slot; an agent added after its member was removed.+- Any lost or reordered message, assignment result, check or route decision during or after migration.+- A client silently showing old data. An old client must get a clear "update Harness" error, not a broken+ screen.++## Facts the design starts from (code survey of main, 2026-10-26)++- Writers that bump the one revision: every command (`store.ts` execute), and outside commands:+ `observeMachine` (each contributed machine, at least every 15 s, per Swarm, probably the most frequent+ writer), native turn append (every terminal prompt and answer), delivery claim and ack (revision bump with+ no state change), hold notice, deliveries wake-up, stopped receipts, sharing, join.+- Every command also runs whole-state passes (`syncLeads`, `numberConversations`, `placeRules`,+ `expireRemovals`, `assignAgentDisplayNames`, `appendPullRequestUrls`, `noteProjectReports`). A worker's+ post in its own group also writes `projects[].progress`.+- Message `sequence` is the tab revision that carried it. Readers page messages by it.+- Readers: Desktop and web (the same Flutter code) poll the full state every 3 s per open Swarm. The CLI host+ ticks every 1 s and loads up to 100 full Swarms per tick. `harness super-tab` fetches the full state for+ every action, not just `status`. Pro cards load the full state every 5 s.+- Unbounded: `conversations` (removed only with their project), finished `starts`, `releasedHarnesses`,+ `overlapAlerts`, expired `invitations`.+- Tests: `backend/integration/superTabs.test.ts` (real MongoMemoryReplSet, about 10 concurrency cases),+ `commands.test.ts` (pure, no concurrency).++## Design++### Parts (storage)++| Part | One document per | Holds |+|---|---|---|+| Head | Swarm | scalars (name, owner, paused, environment, numbering), people, invitations, rules, routingPolicy, sharing, localModels, projects (settings and roles, not progress) |+| Group | work group / conversation | brief, task, checks, assignment, agentIds, leadId, pullRequestUrls, lastMessageSequence, archived, number, messageSeq counter |+| Agent | agent | the agent record, including volatile fields (downSince, alerting, limitedUntil, workDecision, configuration) |+| Machine | contributed machine | contribution settings, slots, harnessReservations, releasedHarnesses (capped), closingSessions, machineCleanups. The observation is stored here but written by its own path (below) |+| Start | agent start | one start record. Finished starts expire with a TTL (my call: 7 days) |+| Project progress | project | progress fields written by reports and posts |++Every part has its own `version` (incremented on each write) and a `changedAt` stamp (see Cursor).++### Concurrency rules++- A command writes only the parts it changes, each guarded by its version: compare-and-set inside one Mongo+ transaction, retried with #1722's backoff.+- Invariants are held by writes, not by reads. Mongo transactions catch write-write conflicts, not stale+ reads. So for every invariant one of these two must hold:+ (a) the command that depends on the invariant also writes (bumps) the part that holds it, or+ (b) the command that changes the invariant also writes every part that depends on it.+ - Example (a): `agent.start` and `agent.started` write the machine part (reservation), so two starts on one+ machine conflict, and starts on different machines don't.+ - Example (b): `member.remove` and `machine.remove` already write the affected agents and groups.+- The whole-state passes run only where their part changes. Example: display names when agents are added;+ numbering at group creation, using a head counter.+- Expected outcome: `message.send`, `work.status`, `work.check` and native turn appends in different groups+ touch only their own group and their own project-progress part.+- Machine observations write only the machine part. `recordAgentPresence` (`downSince`) writes an agent part+ only when the value actually changes.+- A delivery claim or ack must no longer bump a Swarm-wide revision. Its exactly-once and revocation+ guarantees move to the delivery row or the group part (left to the design group to choose; the existing+ integration tests must keep passing).+- The design group produces the full table: every command and every non-command writer, mapped to the parts+ it reads, the parts it writes, and the rule (a) or (b) that guards each invariant. The survey above seeds+ it.++### Change cursor and reads++- My call: no single global counter, because a counter written by every transaction is the same hotspot+ again. Each part write stamps `changedAt` from a monotonic per-process clock (server time, made strictly+ increasing).+- A client asks for parts with `changedAt > cursor − overlap` (overlap: my call, 10 s, so commits that land+ slightly out of order are not missed). It drops parts whose version it already has, and moves its cursor+ to the newest `changedAt` it received.+- Deletions are tombstones: a removed part keeps a document with `deleted: true` and a `changedAt`, and is+ purged after 7 days.+- Message `sequence` becomes per group, from the group part's `messageSeq` counter, written in the same+ transaction as the message. Clients page messages per group as they already do. Anything that needs a+ Swarm-wide order of messages uses `createdAt` plus `id`.+- Endpoints:+ - first load: the head plus active parts;+ - changes since a cursor;+ - archived groups on demand;+ - a host form for the CLI that returns, for all its Swarms, only the parts that changed. This replaces+ loading up to 100 full Swarms each second.+- `harness super-tab status` keeps its output (the Lead and agents depend on it) but builds it from the+ parts. Other actions stop fetching state they don't need.++### Archive++- A group whose assignment is done or cancelled and that has no message for 24 hours (my call), or that was+ archived by hand, leaves the active set.+- An archived group is not returned by first load or by changes. It is still readable in Work details, and a+ new message in it brings it back.+- `releasedHarnesses` is capped per machine (my call: 200, oldest dropped). Finished starts and expired+ invitations expire.++### Migration++- A one-shot, idempotent backend migration splits each `SuperTab` into parts, keeping every id.+- Messages get per-group sequences that preserve their current order.+- It runs during the release window, with backend, CLI and Desktop going out together. Verification for each+ Swarm: parts reassembled into the old shape equal the old state (field by field), and message counts and+ order match.+- A dry run on a copy of production data comes before the real run. The old `state` field is kept, read-only,+ until the owner says it can be dropped.+- Old clients: the backend answers the old full-state routes with an "update Harness" error that every client+ version shows as an error (my call: HTTP 426 with code `UPDATE_REQUIRED`).+- Rollback (`backend/src/superTabs/migration/rollback.ts`):+ - **Before any write in parts:** the kept old state goes back unchanged (`rollbackLegacy`).+ - **After writes:** the old state is rebuilt from the parts (`rollbackFromParts`).+ - **Refused when the previous release would misread the Swarm** (final review, Critical 2; Lead ruling for v1):+ - The previous release checks no audience. It filters conversations and messages by project alone, so a private+ conversation (Chat with PM) would become readable by every project reader.+ - It ends work only on done, stopped or cancelled, so a task whose status is lost would read as active. A lost+ task cancelled later is finished there too, but that release knows no lost marker. Its fenced worker would read+ as an ordinary finished worker awaiting a decision.+ - So `rollbackFromParts` refuses a Swarm with any private conversation or any lost task before it changes any+ row. The refusal names the Swarm and the reason.+ - The recovery path is to roll forward with a fix. The parts stay authoritative, so nothing is lost or made public.+ - A Swarm with neither rolls back as before.+- The dry run (`backend/scripts/swarm-parts/dry-run.ts`):+ - After the migration, it writes a private chat into one synthetic Swarm and a lost task into another, and shows+ that rollback refuses both and leaves their rows unchanged.+ - Its step 7 reads each rolled-back state with this branch's `visibleState`. That checks the state's shape still+ reads. It does not run the previous release's binary or its access checks, so it is not evidence that the+ previous release reads the state safely. The refusal above is what keeps the cases that release would misread+ out of its hands.++## Rulings from the builder check (draft 2, my calls)++An engineer read draft 1 as a builder. These rulings settle what a wrong guess would change, and they override+the sections above where the two differ.++1. **Things that use the Swarm revision as a clock.** These are project progress (`noteProjectReports`+ writes `dirtyRevision` on every post), the Lead's wake-up text, `project.report.throughRevision`, and native+ `recordingProgress` (which looks a message up by `sequence: revision`). Each needs a replacement:+ - Project progress keeps a watermark per group (the group's last reported `messageSeq`). "Dirty" is+ computed on read.+ - The progress part is written only on the change from clean to dirty, so posts in different groups of+ one project don't conflict.+ - `throughRevision` becomes a map from group to sequence.+ - `recordingProgress` uses the group's `messageSeq`.+2. **Insert races.** Example: a message sent while its sender's membership is being removed. Every actor+ (person or agent) gets a small part of its own: a membership part for a person, the agent part for an+ agent.+ - Every command touches its actor's part, with a version-guarded no-op bump.+ - Removing the actor deletes or bumps that part.+ - The design table lists each command's touches (parts read and guarded, though unchanged) as well as its+ writes.+3. **Cursor safety.**+ - The client's next cursor is the server's read start time minus the overlap, not the newest `changedAt`+ received.+ - The overlap is at least the longest a transaction can live (set the transaction timeout explicitly;+ #1722 uses 15 s), plus clock drift between backend processes. My call: 30 s, with transaction timeout ≤+ 15 s.+ - Group 1 confirms how many backend processes run and documents the clock source.+4. **Visibility.** Changes in role, project visibility, sharing and owner-only visibility, and derived views+ such as `otherProjectsWork`, can't be expressed as part changes. The head carries a visibility epoch; when+ it changes, the client reloads in full. Derived views are recomputed on the server for every response.+5. **Archive** uses the existing `Conversation.archived` field.+ - The change to archived is sent once (like a tombstone). After that the group drops out of the feed.+ - The CLI host and the delivery rules can still read archived groups by id.+ - A new message brings the group back, and that is sent as a change.+6. **Versions never reset.** A recreated part (for example an agent contributed again under the same+ `stableId`) continues from its tombstone's version. A cursor older than the tombstone retention (7 days)+ forces a full reload.+7. **Migration keeps every existing sequence value**; gaps are allowed.+ - Each group's `messageSeq` starts at the tab's final revision.+ - The head's group-number counter starts from the current highest number.+ - Every stored reference stays valid unchanged: `lastMessageSequence`, `recordingProgress`, the progress+ revisions, `checkpoint.sequence` in message sources, and `throughRevision`.+ - Writes to the old routes are frozen for the whole migration. This replaces "message sequence becomes+ per group, preserving order": that still holds for new messages, but old ones keep their numbers.+8. **Swarm "changed" token for clients.**+ - Lists and caches use a per-Swarm `lastChangedAt` (the newest `changedAt` of any part). It is kept on the+ head with a guarded max-update outside the hot path, or computed when read; group 1 picks one and shows+ it doesn't bring the hotspot back.+ - Command replies return the parts they wrote with their versions, in place of `revision`.+ - Operation receipts keep their stored `revision`.+9. **Delivery claim and ack.**+ - A claim touches the receiving agent's part and the sender's membership part (ruling 2) and keeps its+ `deliveryAllowed` and `senderAllowed` checks.+ - Revocation keeps cancelling delivery rows, so a claim and a cancel conflict on the same row.+ - The existing exactly-once and revocation integration tests stay as they are and must pass.+10. **Whole-state passes each serialize on one part.**+ - `syncLeads`: a change to `leadId` writes the Leads group.+ - Numbering (`numberConversations`, `retiredConversationNumber`) uses a head counter.+ - `assignAgentDisplayNames` touches the head, because display names must be unique across agents.+ - Group 1's table names the part for every remaining pass.++## Approval++Approved by the owner (ken15) on 2026-10-26, in project chat: "approve spec, hay plan, implement, e2e (isolate+app, backend, db, redis local tranh dung app live dang chay)". That is: approve the spec, plan, implement, and run+end-to-end tests on an isolated local stack (app, backend, database and Redis all local), never touching the+live app.++Ruling (PM): the migration dry run uses a local database seeded with synthetic Swarms shaped like production+(sizes from the issue: 1.16 MB with 195 groups, 422 KB with 50 groups, plus small ones), not a copy of+production. A production copy needs a separate ok from the owner.++## Constraints all groups share++- **Isolation.** Every end-to-end and integration run uses a local, isolated stack (backend, MongoDB replica+ set, Redis, CLI daemon and app, all on localhost) with its own data directories and ports. Never point at+ harness.autonomous.ai, the production backend or production data, and never use a person's real Harness+ session.++- One integration branch, `feat/swarm-state-parts`, cut from current main. Each group works on its own branch+ and opens a PR into it. One final PR from it to main, merged with `make merge-pr` after review and CI. No+ merge to main and no release without the owner's ok.+- Follow AGENTS.md, CONTRIBUTING.md, docs/validation-and-release.md and docs/naming-system.md (visible copy).+- Keep the existing behavior of every command: `commands.test.ts` and `backend/integration/superTabs*.test.ts`+ keep passing (adapted to the new store, never weakened). Behavior changes are only the ones this spec names.+- Mongo transactions through Prisma as today, with #1722's retry and backoff.+- Run the CLI and Desktop checks for the touched areas locally (AGENTS.md lists them) and record them in the+ PR.++## Left to builders++Internal module layout, names of new Prisma models and fields, exact endpoint paths and payload shapes (once+the design group fixes them), the test structure, and the benchmark tooling.++## Group plan++| # | Group | Depends on | Size | Produces |+|---|---|---|---|---|+| 0 | Measure: load benchmark | none | medium | Benchmark under `backend/integration/bench/`. A synthetic Swarm (about 200 groups, 20 agents posting in different groups, 6 machines observing every 15 s, 5 polling clients) on MongoMemoryReplSet. Reports conflicts and retries per command type, p50/p95 latency, bytes per poll. Baseline numbers on main. |+| 1 | Design doc | none | medium | `docs/design/2026-10-26-swarm-state-parts.md`: the full command and writer table, invariant rules, part schemas, cursor and endpoint contracts, migration plan. Strongest model. |+| 2 | Backend storage and commands | 1 | large | Part models, store, command layer, non-command writers, delivery claims, archive, TTLs. Existing tests adapted and passing. |+| 3 | Backend read API and migration | 1 (contracts); merges after 2 | large | First-load, changes, archived and host endpoints; `UPDATE_REQUIRED` on old routes; the migration with verification and dry-run tooling. |+| 4 | Desktop and web client | 1 (contracts) | large | Flutter `super_tabs` reads by cursor; archived groups on demand in Work details. |+| 5 | CLI | 1 (contracts) | large | Host tick, pools, assignments, Pro cards and `harness super-tab` on the new endpoints; `status` output unchanged. |+| 6 | Integrate, measure, migrate dry run | 2–5 | medium | Benchmark rerun against the branch (goal 1 and goal 3 numbers), full suites, dry run on a copy of production. |+| 7 | Whole-project review | 6 | medium | Independent review of the integrated branch. Strongest model. |++Groups 0 and 1 run now, in parallel. Groups 2–5 start when the design doc is accepted; 4 and 5 work against its+contracts in parallel with 2 and 3. Each group gets an independent Reviewer before its PR merges into the+integration branch.++Rough time (my estimate, not a commitment): groups 0–1 take a few hours; groups 2–5 take about 1–2 days in+parallel; group 6 plus review and the release take about half a day. Launch about 2–3 days from approval.++## My calls, for you to check while reading++1. Parts: head, group, agent, machine, start, project progress (machine observation inside the machine part).+2. No global counter. The cursor is `changedAt` with a 30 s overlap, taken from the server's read start time,+ plus per-part versions. Tombstones are kept 7 days; an older cursor forces a full reload.+3. New messages are numbered per group. Existing messages keep their current numbers.+3b. Every person and agent gets a small part of its own, so that removing someone and that person acting at+ the same time can't both succeed.+4. Archive after done or cancelled plus 24 hours without messages. `releasedHarnesses` capped at 200 per+ machine. Finished starts kept 7 days.+5. No push transport in this project.+6. Old clients get HTTP 426 `UPDATE_REQUIRED`. The old `state` field is kept read-only until you say drop it.+7. Synthetic benchmark as the before and after measure, plus a migration dry run on a copy of production. That+ copy needs your ok and access.++## Addendum, 2026-10-26: private conversations (owner decision)++The owner (ken15) chose in project chat to design private conversations into this project and build their UI+right after it ships ("chon 1 nha"). The product is a private channel for each person with the PM, under the+project: only that person and the project's Lead see it. It is in addition to the shared project chat, which+stays as it is ("mọi người vẫn có thể chat chung trao đổi như hiện tại").++For this project, that means:+- The storage, read API and visibility model support a conversation whose audience is an explicit set of+ people plus the Lead. Others do not see it: not in first load, not in changes, not in message reads, not in+ notifications or mentions, and not in `otherProjectsWork`.+- Changing a conversation's audience is a visibility change (ruling 4). Messages, deliveries and attachments+ in it follow its audience.+- No UI in this project. The channel UI (one channel per person, created on first use) is the next request,+ built on these contracts.diff --git a/docs/swarms.md b/docs/swarms.mdindex 714711934..c81e0ae12 100644--- a/docs/swarms.md+++ b/docs/swarms.md@@ -164,6 +164,25 @@ from being reused for private work after removal.Private projects control application access. Contributing machine owners aretrusted execution hosts and can access work running on their computers.+## Chat with PM++Each person has a private chat with each project's product manager, next to the+shared project chat, for their own questions and answers. In Desktop and the+web app it is **Chat with PM**, the first entry under an expanded project. The+first click opens a private conversation for that person alone, named after+them, with the project's product manager in it. Later clicks, other windows and+other devices open the same one: the request that creates it is the same for+each person and project, and the server answers a repeat with the conversation+it already made.++It behaves like the project chat: replies, attachments, the unread mark and the+product manager's tags in Notifications. Only that person and the product+manager read it. Other members, the project's owner and the Swarm's owner+included, never receive it, its messages or its notifications. The chat is+chat only: no work is assigned in it, and only the product manager joins it+among agents. As with any session, the owner of the machine running the+product manager can see what its terminal shows.+## Lead updatesThe default update cadence is five minutes; the project menu also offers one,