The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Merge batch 11-06 j0345: #3215 #3226 #3237 (#3251)
0xken15abf97f12c4b8
diff --git a/AGENTS.md b/AGENTS.mdindex 561453e90..481c7060f 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -49,7 +49,17 @@ For product names, terminology, and visible copy, follow theDo the code review while CI runs, and keep review independent of implementation.- Base the branch on current `main`. A branch older than #991 runs the oldplanner and fails `ci/required`; use **Update branch** or rebase first.- - Merge with `make merge-pr ARGS="N --reviewed-head SHA --reviewed-base SHA --merge"`.+ - In a Swarm project whose rules switch the merge train on, the server merges routine+ work: every 10 minutes it batches PRs that are ready, have every review and test+ step passed at their current head (as many reads as the review table asks), a+ green `ci/required`, no conflict and no `hold` label. It builds a `harness-train/`+ branch from main, squash-merges it when its CI is green and the heads are+ unchanged, closes the originals with a link and records the merges. A red batch+ splits by component; a PR red on its own, or one that conflicts, gets a message+ in its task: fix and push, or merge main once. Docs merge on their own green CI;+ a CI workflow change is merged by hand. Never push to a `harness-train/` branch. Add the `hold` label to keep a+ PR out; the rules' `mergeTrain.enabled` is the kill switch. Hand merges still work.+ - Merge by hand with `make merge-pr ARGS="N --reviewed-head SHA --reviewed-base SHA --merge"`.It verifies automatic `ci/required` evidence and directly squash-merges thereviewed head. A merge queue is not a prerequisite for merging or releasing;do not add `--queue` or ask for queue setup. The helper respects a queue onlydiff --git a/backend/integration/superTabActivity.test.ts b/backend/integration/superTabActivity.test.tsindex 72e682d44..498b996e4 100644--- a/backend/integration/superTabActivity.test.ts+++ b/backend/integration/superTabActivity.test.ts@@ -454,7 +454,7 @@ describe('Phone push: who each push type reaches, and what it carries (task #324const s = await scene()const state = (await store.read(owner, s.tabId)).state as unknown as SuperTabStateconst assignmentId = state.conversations.find(c => c.id === s.web)!.assignment!.id- const notices = await pushed(() => run(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human',+ const notices = await pushed(() => run(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' },result: 'Ship it behind a flag?', ask: { personId: peer.sub, options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'The release' } } as Command,owner, s.worker))expect(notices.map(n => [n.personId, n.key.split(':')[0], n.title, n.link.includes('/decision/'), n.quiet === true]))diff --git a/backend/integration/superTabBuddies.test.ts b/backend/integration/superTabBuddies.test.tsindex 320bd597c..ff89241b4 100644--- a/backend/integration/superTabBuddies.test.ts+++ b/backend/integration/superTabBuddies.test.ts@@ -256,7 +256,7 @@ describe('a Buddy through the store', () => {configuration: config, lead: false })).result.agentId)const assignmentId = String((await f.execute({ type: 'work.assign', conversationId: group, agentId: builder })).result.assignmentId)await f.execute({ type: 'message.send', conversationId: group, text: 'Opened https://github.com/acme/app/pull/12', replyTo: null, recipientIds: [] }, owner, builder)- await f.execute({ type: 'work.status', conversationId: group, assignmentId, status: 'needs_human', result: 'Ship it behind a flag?' }, owner, builder)+ await f.execute({ type: 'work.status', conversationId: group, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Ship it behind a flag?' }, owner, builder)await f.execute({ type: 'decision.ask', conversationId: group, personId: peer.sub, questions: [{ question: 'Ship it behind a flag?',options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'The release' }] }, owner, f.lead)await f.execute({ type: 'decision.ask', conversationId: group, personId: owner.sub, questions: [{ question: 'Which week?',diff --git a/backend/integration/superTabLeaderboard.test.ts b/backend/integration/superTabLeaderboard.test.tsindex 7002afad2..7c87e8c90 100644--- a/backend/integration/superTabLeaderboard.test.ts+++ b/backend/integration/superTabLeaderboard.test.ts@@ -66,7 +66,7 @@ async function scene(before?: (state: SuperTabState) => void) {const worker = s.add('worker-harness', waiting)s.run({ type: 'work.assign', conversationId: waiting, agentId: worker })s.run({ type: 'work.status', conversationId: waiting, assignmentId: s.state.conversations.find(c => c.id === waiting)!.assignment!.id,- status: 'needs_human', result: 'Flag?' }, { kind: 'agent', agentId: worker, machineOwnerId: `${owner.sub}-machine` })+ status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Flag?' }, { kind: 'agent', agentId: worker, machineOwnerId: `${owner.sub}-machine` })s.edit(state => {const done = { id: 'done', agentId: worker, status: 'done' as const, result: PR, configuration: state.agents[0]!.configuration,execution: { machineId: 'host', harnessId: 'h', machineOwnerId: owner.sub } }diff --git a/backend/integration/superTabMergeTrain.test.ts b/backend/integration/superTabMergeTrain.test.tsnew file mode 100644index 000000000..60e3a0610--- /dev/null+++ b/backend/integration/superTabMergeTrain.test.ts@@ -0,0 +1,118 @@+import { randomUUID } from 'node:crypto'+import { execFile } from 'node:child_process'+import { promisify } from 'node:util'+import { join } from 'node:path'+import { tmpdir } from 'node:os'+import { afterAll, beforeAll, describe, expect, it } from 'vitest'+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'+import { PrismaClient } from '@prisma/client'+import type { AuthUser } from '../src/lib/ssoAuth.js'+import { SuperTabStore } from '../src/superTabs/store.js'+import type { Command } from '../src/superTabs/commands.js'+import { teamWrittenTask } from '../src/superTabs/teamWritten.js'+import { plan, profiled, reads } from './plans.test-support.js'++// Task #3402: the merge train reads its candidates from the Swarm, records each merge on its task with the original pull+// request's link (never the batch's), and tells a task's Engineer once per key. A fresh loopback replica set, created here.+let replica: MongoMemoryReplSet+let db: PrismaClient+const owner: AuthUser = { sub: '230000000000000000000001', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }+const host: AuthUser = { sub: '230000000000000000000003', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }+const config = { engine: 'codex', model: 'fixture-model', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }++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_merge_train_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()+})++let pullNumbers = 300++/** A Swarm on acme/app with a Lead, and a task with a review step, assigned to a worker that linked its pull request. */+async function swarm() {+ const number = ++pullNumbers, PR = `https://github.com/acme/app/pull/${number}`+ let now = Date.parse('2026-11-05T15:00:00.000Z')+ const store = new SuperTabStore(db, () => now)+ const tab = (await store.create(owner, randomUUID(), 'Train', 'public')).id+ const execute = (command: Command, user = owner, asAgentId?: string) => store.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 add = async (conversationId: string, machineId: string, name: string, lead = false) => String((await execute({ type: 'agent.add',+ conversationId, machineId, harnessId: randomUUID(), name, configuration: config, lead })).result.agentId)+ await add('lead', 'lead-host', 'Lead', true)+ await execute({ type: 'tab.project', machineId: 'lead-host', project: { cwd: '/repo', repositoryUrl: null } })+ await execute({ type: 'project.repository', projectId: 'lead', repositoryUrl: 'https://github.com/acme/app' })+ const task = String((await execute({ type: 'conversation.create', title: 'Ship the parser', brief: 'Implement it', checks: [] })).result.conversationId)+ const worker = await add(task, 'test-host', 'Worker')+ const assignment = String((await execute({ type: 'work.assign', conversationId: task, agentId: worker })).result.assignmentId)+ await execute({ type: 'work.status', conversationId: task, assignmentId: assignment, status: 'review', result: `Ready ${PR}` }, host, worker)+ const step = String((await execute({ type: 'conversation.create', title: 'Review', brief: 'Read it', reviewOf: task, step: 'Review',+ checks: [{ description: 'Read', independent: true }] })).result.conversationId)+ return { PR, number, store, tab, execute, task, worker, step, clock: { get now() { return now }, advance(ms: number) { now += ms } } }+}++describe('the merge train in the Swarm', () => {+ it('lists the project\'s tasks with their own pull requests and steps', async () => {+ const f = await swarm()+ const projects = (await f.store.trainProjects(f.clock.now)).filter(p => p.tabId === f.tab)+ expect(projects).toHaveLength(1)+ expect(projects[0]).toMatchObject({ projectId: 'lead', ownerId: owner.sub, repositoryUrl: 'https://github.com/acme/app' })+ expect(projects[0]!.pulls.map(p => [p.taskId, p.url, p.task.steps.map(s => s.step)])).toEqual([[f.task, f.PR, ['Review']]])+ })++ it('names the task\'s builders, its assignee and every earlier attempt\'s agent, so none counts as its review', async () => {+ const f = await swarm()+ await db.superTabAttempt.create({ data: { id: randomUUID(), tabId: f.tab, conversationId: f.task, snapshot: { assignment: { agentId: 'agent-before' } } } })+ // Other tasks' attempts, which the read's index bounds out.+ await db.superTabAttempt.createMany({ data: Array.from({ length: 20 }, (_, i) => ({ id: randomUUID(), tabId: f.tab, conversationId: `other-${i}`,+ snapshot: { assignment: { agentId: `other-${i}` } } })) })+ let projects: Awaited<ReturnType<typeof f.store.trainProjects>> = []+ const entries = await profiled(db, async () => { projects = await f.store.trainProjects(f.clock.now) })+ const [project] = projects.filter(p => p.tabId === f.tab)+ expect([...project!.pulls[0]!.task.builders!].sort()).toEqual([`agent:${f.worker}`, 'agent:agent-before'].sort())+ // One read of the attempts by their [tabId, conversationId, createdAt] index, examining only this Swarm's tasks' rows.+ const rows = reads(entries, 'SuperTabAttempt', ['tabId', 'conversationId']).filter(r => JSON.stringify(r.command).includes(f.tab))+ expect(rows, JSON.stringify(plan(rows))).toHaveLength(1)+ expect(rows[0]!.planSummary, JSON.stringify(plan(rows))).toMatch(/IXSCAN \{ tabId: 1, conversationId: 1, createdAt: 1/)+ expect(rows[0]!.docsExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(1)+ })++ it('records a merge with the original link, once, and marks nothing Team-written', async () => {+ const f = await swarm()+ const [project] = (await f.store.trainProjects(f.clock.now)).filter(p => p.tabId === f.tab)+ await f.store.trainMerged(project!, f.task, f.PR, f.clock.now - 1000)+ await f.store.trainMerged(project!, f.task, f.PR, f.clock.now - 1000)+ const state = (await f.store.read(owner, f.tab)).state+ const group = state.conversations.find(c => c.id === f.task)!+ expect(group.pullRequestUrls).toEqual([f.PR])+ expect(group.ledger?.shippedAt).toBeTypeOf('number')+ expect(group.teamWritten).toBeUndefined()+ expect(teamWrittenTask(state, group)).toBe(false)+ const merged = await db.superTabMessage.findMany({ where: { tabId: f.tab, conversationId: f.task, text: { startsWith: 'Merged ' } } })+ expect(merged.map(m => m.text)).toEqual([`Merged ${f.PR}`])+ })++ it('tells the task\'s Engineer once per key', async () => {+ const f = await swarm()+ expect(await f.store.trainTell(f.tab, f.task, `train-conflict:abc`, `Merge main once. ${f.PR}`)).toBe(true)+ expect(await f.store.trainTell(f.tab, f.task, `train-conflict:abc`, `Merge main once. ${f.PR}`)).toBe(false)+ const rows = await db.superTabMessage.findMany({ where: { tabId: f.tab, conversationId: f.task, text: { startsWith: 'Merge main once' } } })+ expect(rows.map(r => r.recipientIds)).toEqual([[f.worker]])+ })+})diff --git a/backend/integration/superTabNoticeDigest.test.ts b/backend/integration/superTabNoticeDigest.test.tsindex efd0b19e1..ca280ac58 100644--- a/backend/integration/superTabNoticeDigest.test.ts+++ b/backend/integration/superTabNoticeDigest.test.ts@@ -819,7 +819,7 @@ describe('a step\'s Stuck, skills notices and quiet alerts', () => {reviewOf: orphan })).result.conversationId)const reviewer = await f.add(step, 'test-host', 'Reviewer')const assignmentId = String((await f.execute({ type: 'work.assign', conversationId: step, agentId: reviewer })).result.assignmentId)- await f.execute({ type: 'work.status', conversationId: step, assignmentId, status: 'blocked', result: 'Needs the owner\'s account' }, host, reviewer)+ await f.execute({ type: 'work.status', conversationId: step, assignmentId, status: 'blocked', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Needs the owner\'s account' }, host, reviewer)const row = await statusRow(f.tab, step, 'Stuck')expect(row.recipientIds).toEqual([f.lead])expect((await deliveryOf(row.id, f.lead)).status).toBe('queued')diff --git a/backend/integration/superTabRead.test.ts b/backend/integration/superTabRead.test.tsindex 24991777d..cf4150b81 100644--- a/backend/integration/superTabRead.test.ts+++ b/backend/integration/superTabRead.test.ts@@ -819,7 +819,7 @@ describe('decisions asked of one person (v2)', () => {const s = await scene()clock = Date.now()const assignmentId = (await get(`/api/super-tabs/${s.tabId}/parts`, owner)).body.data.groups.find((g: { key: string }) => g.key === s.web).data.assignment.id- const needs = await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', result: 'Ship to everyone?',+ const needs = await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Ship to everyone?',ask: { personId: peer.sub, options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'Turning it on' } }, owner, s.worker)expect(needs.status, JSON.stringify(needs.body)).toBe(200)const [open] = await decisions(s.tabId, peer)@@ -917,7 +917,7 @@ describe('decisions asked of one person (v2)', () => {const s = await scene()clock = Date.now()const assignmentId = (await get(`/api/super-tabs/${s.tabId}/parts`, owner)).body.data.groups.find((g: { key: string }) => g.key === s.web).data.assignment.id- await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', result: 'Ship to everyone?',+ await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Ship to everyone?',ask: { personId: peer.sub, options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'Turning it on' } }, owner, s.worker)await writeGroup(s.tabId, s.web, Date.now(), group => { group.dormant = true })const first = (await get(`/api/super-tabs/${s.tabId}/parts`, peer)).body.data@@ -1257,7 +1257,7 @@ describe('decisions asked of one person (v2)', () => {projectId: 'lead', conversationId: s.web, assignmentId, personId: peer.sub, askerAgentId: s.worker, question: `Question ${i + 1}?`,options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'The release', createdAt: new Date() })) })const before = (await assignment()).leaseUntil as number- const needs = await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', result: 'Ship how?',+ const needs = await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Ship how?',ask: { personId: peer.sub, options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'The release' } }, owner, s.worker)expect(needs.status, JSON.stringify(needs.body)).toBe(200)const notAsked = `Not asked peer: 20 decisions you asked them are still open, and at most 20 can be. Wait for answers before asking more.`@@ -1269,7 +1269,7 @@ describe('decisions asked of one person (v2)', () => {expect(notice).toMatchObject({ text: `Needs a human\n\nShip how?\n\n${notAsked}`, recipientIds: [s.lead] })expect(await db.superTabDecision.count({ where: { tabId: s.tabId, askerAgentId: s.worker } })).toBe(20)// A repeat of one still open is that decision again, so it is asked as before.- const repeat = await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', result: 'Question 1?',+ const repeat = await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Question 1?',ask: { personId: peer.sub, options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'The release' } }, owner, s.worker)expect(repeat.body.data.result.notAsked).toBeUndefined()expect((await db.superTabMessage.findFirst({ where: { tabId: s.tabId, conversationId: s.web }, orderBy: { sequence: 'desc' } }))!.text)@@ -1300,7 +1300,7 @@ describe('decisions asked of one person (v2)', () => {const [other] = (await post(s.tabId, { type: 'decision.ask', conversationId: s.web, personId: peer.sub,questions: [{ ...question('Ship how?'), options: ['Today', 'Next week'] }] }, owner, s.lead)).body.data.result.decisionIds as string[]const assignmentId = (await get(`/api/super-tabs/${s.tabId}/parts`, owner)).body.data.groups.find((g: { key: string }) => g.key === s.web).data.assignment.id- expect((await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', result: 'Ship how?',+ expect((await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Ship how?',ask: { personId: peer.sub, options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'The release' } }, owner, s.worker)).status).toBe(200)const open = await decisions(s.tabId, peer)expect(open).toHaveLength(3)diff --git a/backend/integration/superTabTeam.test.ts b/backend/integration/superTabTeam.test.tsindex eaf4c02a8..58a890d89 100644--- a/backend/integration/superTabTeam.test.ts+++ b/backend/integration/superTabTeam.test.ts@@ -722,7 +722,7 @@ describe('a teammate\'s work and the machines that take it', () => {await store.observeMachine(person, f.tab, 'personal-mac', reading(generation))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: 'work.status', conversationId: f.teamGroup, assignmentId: 'assigned-before', status: 'blocked', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, 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)await run(f.tab, { type: 'work.cancel', conversationId: f.teamGroup, assignmentId: 'assigned-before', reason: 'Moving it to the Team machine.' })diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.tsindex 21a2a523d..6ef044664 100644--- a/backend/integration/superTabs.test.ts+++ b/backend/integration/superTabs.test.ts@@ -2453,9 +2453,9 @@ describe('Super Tabs on a real Mongo replica set', () => {const assignmentId = (await run(tab, { type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId as stringconst 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)+ await run(tab, { type: 'work.status', conversationId: group, assignmentId, status: 'blocked', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'No access to staging.' } as Command, host, worker)expect((await row()).attention).toEqual({ assignmentId, status: 'blocked', result: 'No access to staging.' })- await run(tab, { type: 'work.status', conversationId: group, assignmentId, status: 'needs_human', result: null } as Command, host, worker)+ await run(tab, { type: 'work.status', conversationId: group, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: null } as Command, host, worker)expect((await row()).attention).toEqual({ assignmentId, status: 'needs_human', result: null })await run(tab, { type: 'work.status', conversationId: group, assignmentId, status: 'working', result: null } as Command, host, worker)expect((await row()).attention).toBeNull()@@ -4714,7 +4714,7 @@ describe('leaderboard credits written by the store (leaderboard/record.ts)', ()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 ask = { type: 'work.status', conversationId: group, assignmentId, status: 'needs_human', result: 'Ship how?',+ const ask = { type: 'work.status', conversationId: group, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Ship how?',ask: { personId: peer.sub, options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'The release' } } as Commandawait run(tab, ask, host, worker)await run(tab, { type: 'work.status', conversationId: group, assignmentId, status: 'working', result: null } as Command, host, worker)diff --git a/backend/integration/workerIndexPlans.test.ts b/backend/integration/workerIndexPlans.test.tsindex 0a85d94c9..bea644a40 100644--- a/backend/integration/workerIndexPlans.test.ts+++ b/backend/integration/workerIndexPlans.test.ts@@ -289,6 +289,33 @@ describe('the pull request watch', () => {})})+// Task #3402: the merge train reads unarchived tasks that link a pull request, done ones included, through the same finished+// mark index: both marks of its first field, archived false, then the activity range, newest first and capped.+describe('the merge train\'s candidates', () => {+ it('reads the unarchived tasks active this week by the finished mark index, the newest first, capped', async () => {+ const { SuperTabStore } = await import('../src/superTabs/store.js')+ let n = 0+ const group = (activeAt: number, patch: { workFinished?: boolean; archived?: boolean; data?: Record<string, unknown> } = {}) => {+ const key = `m${++n}`+ return { id: `tab-m:${key}`, tabId: 'tab-m', key, version: 1, changedAt: new Date(NOW), ordinal: n, agentIds: [], lastActivityAt: new Date(activeAt),+ workFinished: patch.workFinished ?? false, archived: patch.archived ?? false, data: { pullRequestUrls: [`https://github.com/acme/app/pull/${n}`], ...patch.data } }+ }+ // Archived work and work quiet for a month, which a read the index does not bound examines too; a step, which it filters.+ await db.swarmGroup.createMany({ data: [+ ...Array.from({ length: 20 }, () => group(NOW - 60_000, { archived: true, workFinished: true })), ...Array.from({ length: 20 }, () => group(NOW - 30 * 24 * 3_600_000)),+ group(NOW - 3 * 3_600_000), group(NOW - 2 * 3_600_000, { workFinished: true }), group(NOW - 3_600_000, { data: { reviewOf: 'm1' } }),+ ] })+ const store = new SuperTabStore(db, () => NOW)+ const entries = await profiled(db, () => store.trainProjects(NOW, 2))+ const rows = reads(entries, 'SwarmGroup', ['workFinished', 'lastActivityAt'])+ expect(rows, JSON.stringify(plan(rows))).toHaveLength(1)+ expect(rows[0]!.planSummary, JSON.stringify(plan(rows))).toMatch(/IXSCAN \{ workFinished: 1, archived: 1, lastActivityAt: 1/)+ // One index range per mark, merged newest first: each reads up to the limit, and the step is filtered after. Never the+ // archived or month-old rows, whatever other tests in this database left.+ expect(rows[0]!.docsExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(2 * 2 + 1)+ })+})+describe('the hourly unused-upload sweep', () => {// Ken's prod scan of 11-04 (#2676): Performance Advisor suggested an index for it. The sweep's claim reads uploads by// `usedBy` and `proposedBy` (both null), `purpose` and age; its remove step reads the uploads it took by `usedBy` alone.diff --git a/backend/src/github/app.ts b/backend/src/github/app.tsindex 6d90ee117..a3b6ce2bd 100644--- a/backend/src/github/app.ts+++ b/backend/src/github/app.ts@@ -446,6 +446,13 @@ export class GitHubApp {throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub could not create a token for ${repository.fullName}.`, 502)}+ /** One call with an installation [token] this server minted (the merge train's, github/train.ts): its status and JSON body.+ * Throws [GitHubAppError] GITHUB_UNAVAILABLE when GitHub does not answer. */+ async installationCall(token: string, method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown> | unknown[] }> {+ const answer = await this.call(method, path, `Bearer ${token}`, body)+ return { status: answer.status, body: answer.body }+ }+/** Ends [token] at once (DELETE /installation/token, authorised by the token itself). One GitHub already ended reads as* done. */async revoke(token: string): Promise<void> {diff --git a/backend/src/github/train.test.ts b/backend/src/github/train.test.tsnew file mode 100644index 000000000..d486ace27--- /dev/null+++ b/backend/src/github/train.test.ts@@ -0,0 +1,147 @@+import { describe, expect, it } from 'vitest'+import { fakeApp, fakeGitHub, throwawayKey } from './fakeGitHub.js'+import { githubRepository } from './repository.js'+import { TRAIN_PERMISSIONS, TrainReadError, repositoryTrain, trainGitHub, type TrainCall } from './train.js'++const SHA = 'a'.repeat(40), MAIN = 'c'.repeat(40), MERGED = 'd'.repeat(40)+const pullBody = (n: number, over: Record<string, unknown> = {}) => ({ number: n, html_url: `https://github.com/acme/app/pull/${n}`, state: 'open',+ merged: false, draft: false, title: `PR ${n}`, body: 'text', mergeable: true, head: { sha: SHA, ref: `feature-${n}`, repo: { full_name: 'Acme/App' } }, base: { ref: 'main' },+ labels: [{ name: 'hold' }], ...over })++/** A stub of GitHub's answers by "METHOD path", recording each call. */+function stub(answers: Record<string, { status: number; body?: unknown }>) {+ const calls: Array<{ method: string; path: string; body?: unknown }> = []+ const call: TrainCall = async (method, path, body) => {+ calls.push({ method, path, ...(body === undefined ? {} : { body }) })+ const found = answers[`${method} ${path}`]+ return found ? { status: found.status, body: found.body ?? {} } : { status: 404, body: { message: 'Not Found' } }+ }+ return { calls, train: trainGitHub(call, 'acme/app') }+}++describe('the merge train on GitHub', () => {+ it('reads main, a pull request, its files and its ci/required', async () => {+ const { train } = stub({+ 'GET /repos/acme/app/git/ref/heads/main': { status: 200, body: { ref: 'refs/heads/main', object: { type: 'commit', sha: MAIN } } },+ 'GET /repos/acme/app/pulls/7': { status: 200, body: pullBody(7) },+ 'GET /repos/acme/app/pulls/7/files?per_page=100&page=1': { status: 200, body: [{ filename: 'backend/a.ts' }, { filename: 'docs/b.md' }] },+ [`GET /repos/acme/app/commits/${SHA}/check-runs?check_name=ci%2Frequired&filter=latest`]: { status: 200, body: { total_count: 1,+ check_runs: [{ name: 'ci/required', status: 'completed', conclusion: 'success' }] } },+ })+ expect(await train.mainHead()).toBe(MAIN)+ expect(await train.pull(7)).toEqual({ number: 7, url: 'https://github.com/acme/app/pull/7', state: 'open', merged: false, draft: false,+ title: 'PR 7', body: 'text', mergeable: true, head: SHA, headRef: 'feature-7', headRepository: 'acme/app', base: 'main', labels: ['hold'] })+ expect(await train.files(7)).toEqual(['backend/a.ts', 'docs/b.md'])+ expect(await train.ciRequired(SHA)).toBe('success')+ })++ it('reads ci/required as pending, failed or missing', async () => {+ const runs = (check_runs: unknown[]) => stub({ [`GET /repos/acme/app/commits/${SHA}/check-runs?check_name=ci%2Frequired&filter=latest`]: { status: 200, body: { total_count: check_runs.length, check_runs } } }).train+ expect(await runs([{ name: 'ci/required', status: 'in_progress', conclusion: null }]).ciRequired(SHA)).toBe('pending')+ expect(await runs([{ name: 'ci/required', status: 'completed', conclusion: 'failure' }]).ciRequired(SHA)).toBe('failure')+ expect(await runs([{ name: 'ci/required', status: 'completed', conclusion: 'skipped' }]).ciRequired(SHA)).toBe('failure')+ expect(await runs([]).ciRequired(SHA)).toBe(null)+ })++ it('fails closed on every read it cannot trust', async () => {+ const broken = stub({+ 'GET /repos/acme/app/git/ref/heads/main': { status: 500 },+ 'GET /repos/acme/app/pulls/7': { status: 200, body: { number: 8, state: 'open' } },+ 'GET /repos/acme/app/pulls/7/files?per_page=100&page=1': { status: 403 },+ [`GET /repos/acme/app/commits/${SHA}/check-runs?check_name=ci%2Frequired&filter=latest`]: { status: 200, body: { check_runs: 'x' } },+ }).train+ await expect(broken.mainHead()).rejects.toBeInstanceOf(TrainReadError)+ await expect(broken.pull(7)).rejects.toBeInstanceOf(TrainReadError)+ await expect(broken.files(7)).rejects.toBeInstanceOf(TrainReadError)+ await expect(broken.ciRequired(SHA)).rejects.toBeInstanceOf(TrainReadError)+ await expect(broken.ciRequired('main')).rejects.toBeInstanceOf(TrainReadError)+ })++ it('builds a batch: a branch at main, each head merged in, a pull request to main', async () => {+ const { train, calls } = stub({+ 'POST /repos/acme/app/git/refs': { status: 201, body: { ref: 'refs/heads/harness-train/1', object: { sha: MAIN } } },+ 'POST /repos/acme/app/merges': { status: 201, body: { sha: MERGED, parents: [{ sha: MAIN }, { sha: SHA }] } },+ 'POST /repos/acme/app/pulls': { status: 201, body: pullBody(9, { head: { sha: MERGED, ref: 'harness-train/1' }, labels: [] }) },+ })+ await train.createBranch('harness-train/1', MAIN)+ expect(await train.mergeInto('harness-train/1', SHA, 'Merge #7', MAIN)).toEqual({ sha: MERGED })+ expect((await train.openPull('harness-train/1', 'Batch', 'body')).number).toBe(9)+ expect(calls.map(c => [c.method, c.path, c.body])).toEqual([+ ['POST', '/repos/acme/app/git/refs', { ref: 'refs/heads/harness-train/1', sha: MAIN }],+ ['POST', '/repos/acme/app/merges', { base: 'harness-train/1', head: SHA, commit_message: 'Merge #7' }],+ ['POST', '/repos/acme/app/pulls', { head: 'harness-train/1', base: 'main', title: 'Batch', body: 'body', draft: false }],+ ])+ })++ it('reads a conflict as one, and never lets the branch point at a member\'s own commit', async () => {+ expect(await stub({ 'POST /repos/acme/app/merges': { status: 409 } }).train.mergeInto('harness-train/1', SHA, 'm', MAIN)).toBe('conflict')+ // Nothing merged: the head is in the branch already, which starts at main, so it is in main.+ expect(await stub({ 'POST /repos/acme/app/merges': { status: 204 } }).train.mergeInto('harness-train/1', SHA, 'm', MAIN)).toBe('already')+ // A fast-forward would leave the branch at the member's commit, which reads as the bot pushing it (pushOrigin.ts).+ await expect(stub({ 'POST /repos/acme/app/merges': { status: 201, body: { sha: SHA, parents: [{ sha: MAIN }] } } }).train+ .mergeInto('harness-train/1', SHA, 'm', MAIN)).rejects.toBeInstanceOf(TrainReadError)+ // Someone pushed onto the train branch before this merge: its commit, not the tip, is the first parent (review 1 of #3226).+ const FOREIGN = 'e'.repeat(40)+ await expect(stub({ 'POST /repos/acme/app/merges': { status: 201, body: { sha: MERGED, parents: [{ sha: FOREIGN }, { sha: SHA }] } } }).train+ .mergeInto('harness-train/1', SHA, 'm', MAIN)).rejects.toBeInstanceOf(TrainReadError)+ await expect(stub({ 'POST /repos/acme/app/merges': { status: 201, body: { sha: MERGED, parents: [{ sha: MAIN }, { sha: FOREIGN }] } } }).train+ .mergeInto('harness-train/1', SHA, 'm', MAIN)).rejects.toBeInstanceOf(TrainReadError)+ })++ it('squash-merges at the exact head, comments, closes and deletes', async () => {+ const { train, calls } = stub({+ 'PUT /repos/acme/app/pulls/9/merge': { status: 200, body: { merged: true, sha: MERGED } },+ 'POST /repos/acme/app/issues/7/comments': { status: 201, body: { id: 1 } },+ 'PATCH /repos/acme/app/pulls/7': { status: 200, body: pullBody(7, { state: 'closed' }) },+ 'DELETE /repos/acme/app/git/refs/heads/harness-train/1': { status: 204 },+ })+ expect(await train.squash(9, MERGED, 'Batch (#9)', 'msg')).toEqual({ sha: MERGED })+ await train.comment(7, 'Merged in the batch')+ await train.close(7)+ await train.deleteBranch('harness-train/1')+ expect(calls[0]).toEqual({ method: 'PUT', path: '/repos/acme/app/pulls/9/merge', body: { sha: MERGED, merge_method: 'squash', commit_title: 'Batch (#9)', commit_message: 'msg' } })+ expect(calls.map(c => c.method)).toEqual(['PUT', 'POST', 'PATCH', 'DELETE'])+ })++ it('reads a fork\'s pull request as from another repository', async () => {+ const { train } = stub({ 'GET /repos/acme/app/pulls/7': { status: 200, body: pullBody(7, { head: { sha: SHA, ref: 'harness-train/p1/1', repo: { full_name: 'outsider/app' } } }) } })+ expect(train.repository).toBe('acme/app')+ expect((await train.pull(7)).headRepository).toBe('outsider/app')+ })++ it('refuses a squash GitHub did not do, with its reason, and a branch name outside the train', async () => {+ const refused = await stub({ 'PUT /repos/acme/app/pulls/9/merge': { status: 405, body: { message: 'Required status check "x" is expected.' } } }).train+ .squash(9, MERGED, 't', 'm').catch(error => error)+ expect(refused).toBeInstanceOf(TrainReadError)+ expect(refused).toMatchObject({ status: 405, reason: 'Required status check "x" is expected.' })+ await expect(stub({ 'PUT /repos/acme/app/pulls/9/merge': { status: 200, body: { merged: false } } }).train.squash(9, MERGED, 't', 'm')).rejects.toBeInstanceOf(TrainReadError)+ const { train, calls } = stub({})+ await expect(train.createBranch('main', MAIN)).rejects.toBeInstanceOf(TrainReadError)+ await expect(train.deleteBranch('feature-7')).rejects.toBeInstanceOf(TrainReadError)+ expect(calls).toEqual([])+ })++ it('lists open pull requests into main, a page at a time', async () => {+ const { train } = stub({+ 'GET /repos/acme/app/pulls?state=open&base=main&per_page=100&page=1': { status: 200, body: [pullBody(7), pullBody(8, { draft: true })] },+ })+ expect((await train.openPulls()).map(p => [p.number, p.draft])).toEqual([[7, false], [8, true]])+ })+})++describe('the train\'s token', () => {+ it('asks only for what the train does, and is revoked when the pass is done', async () => {+ const key = throwawayKey(), github = fakeGitHub({ publicKey: key.publicKey, appId: '424242' })+ github.installed.set('acme/app', 77)+ const opened = await repositoryTrain(fakeApp(key.privateKey, github), githubRepository('https://github.com/acme/app')!)+ expect(opened).not.toBeNull()+ expect([...github.permissions.values()]).toEqual([TRAIN_PERMISSIONS])+ expect(TRAIN_PERMISSIONS).toEqual({ contents: 'write', pull_requests: 'write', checks: 'read', metadata: 'read' })+ await opened!.done()+ expect(github.revoked).toHaveLength(1)+ })+ it('is null where the app is not installed', async () => {+ const key = throwawayKey(), github = fakeGitHub({ publicKey: key.publicKey, appId: '424242' })+ expect(await repositoryTrain(fakeApp(key.privateKey, github), githubRepository('https://github.com/acme/app')!)).toBeNull()+ })+})diff --git a/backend/src/github/train.ts b/backend/src/github/train.tsnew file mode 100644index 000000000..c0a075088--- /dev/null+++ b/backend/src/github/train.ts@@ -0,0 +1,204 @@+/**+ * The merge train's calls to GitHub (task #3402, superTabs/mergeTrain/): read main and pull requests, build a batch branch+ * from main with the git data API (no checkout, so no code of any branch runs on the server), open its pull request,+ * squash-merge it at the exact head CI passed, and close the originals. Every write is the Harness GitHub App's installation+ * token, never a person's.+ *+ * Fail closed: any answer that is not exactly what the call expects throws [TrainReadError], and the pass then writes+ * nothing more for that batch. The branch the train writes never points at a member's own commit: GitHub's activity log+ * would then show the app's bot pushing it, which marks the member's task Team-written (pushOrigin.ts).+ */+import { GitHubAppError, type GitHubApp } from './app.js'+import type { GitHubRepository } from './repository.js'+import { TRAIN_BRANCH_PREFIX, TRAIN_CI_CHECK } from '../superTabs/mergeTrain/config.js'++/** What the train's token may do: build and delete its branches and merge (contents), open, merge, comment on and close pull+ * requests, and read checks. Among the app's own permissions ([TOKEN_PERMISSIONS]); no workflows, issues or actions. */+export const TRAIN_PERMISSIONS = { contents: 'write', pull_requests: 'write', checks: 'read', metadata: 'read' } as const++export class TrainReadError extends Error {+ /** [reason]: GitHub's own message when it gave one, on one line, cut short: what an Engineer is told of a refused merge. */+ constructor(readonly call: string, readonly status: number, readonly reason: string | null = null) {+ super(`GitHub answered ${call} with HTTP ${status}, not what the train expects`)+ }+}++/** A pull request as the train reads it. */+export interface TrainPull {+ number: number+ url: string+ state: 'open' | 'closed'+ merged: boolean+ draft: boolean+ title: string+ body: string+ mergeable: boolean | null+ head: string+ headRef: string+ /** The repository its branch is in, `owner/name` in lower case: another one for a fork's pull request. */+ headRepository: string+ base: string+ labels: string[]+}++export type TrainCall = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>++export interface TrainGitHub {+ /** `owner/name`, lower case. */+ readonly repository: string+ mainHead(): Promise<string>+ openPulls(): Promise<TrainPull[]>+ pull(number: number): Promise<TrainPull>+ files(number: number): Promise<string[]>+ ciRequired(sha: string): Promise<'success' | 'failure' | 'pending' | null>+ createBranch(name: string, sha: string): Promise<void>+ /** Merges [sha] into the train's [branch], whose head must be [tip]: the new merge commit, `conflict`, or `already` when the+ * branch (which starts at main) holds it already. A merge whose parents are not exactly [tip] then [sha] throws: someone+ * pushed onto the branch (review 1 of #3226). */+ mergeInto(branch: string, sha: string, message: string, tip: string): Promise<{ sha: string } | 'conflict' | 'already'>+ openPull(branch: string, title: string, body: string): Promise<TrainPull>+ /** Squash-merges pull request [number] only if its head is still [sha]: the commit on main. */+ squash(number: number, sha: string, title: string, message: string): Promise<{ sha: string }>+ comment(number: number, text: string): Promise<void>+ close(number: number): Promise<void>+ deleteBranch(name: string): Promise<void>+}++const SHA = /^[0-9a-f]{40}$/+/** Pages of a pull request's files read at most: GitHub lists 3,000 files at most, and the train reads no partial list. */+const FILE_PAGES = 30+const PULL_PAGES = 5+const PASSED = new Set(['success', 'neutral'])++type Json = Record<string, unknown>+const object = (value: unknown): Json => value && typeof value === 'object' && !Array.isArray(value) ? value as Json : {}+const text = (value: unknown): string | null => typeof value === 'string' ? value : null++/** The train's calls on `owner/name` [repository] through [call]. */+export function trainGitHub(call: TrainCall, repository: string): TrainGitHub {+ const base = `/repos/${repository}`+ const expect = async (method: string, path: string, statuses: number[], body?: unknown) => {+ const answer = await call(method, `${base}${path}`, body).catch(error => {+ if (error instanceof GitHubAppError) throw new TrainReadError(`${method} ${path}`, 0)+ throw error+ })+ if (!statuses.includes(answer.status)) {+ const said = text(object(answer.body).message)+ throw new TrainReadError(`${method} ${path}`, answer.status, said ? said.replace(/\s+/g, ' ').trim().slice(0, 300) : null)+ }+ return answer+ }+ const sha = (value: unknown, what: string): string => {+ if (typeof value !== 'string' || !SHA.test(value)) throw new TrainReadError(what, 200)+ return value+ }+ const own = (name: string, what: string) => {+ if (!name.startsWith(TRAIN_BRANCH_PREFIX) || name.length === TRAIN_BRANCH_PREFIX.length || /\.\.|[\s~^:?*[\\]/.test(name)) throw new TrainReadError(what, 0)+ }+ const pullOf = (value: unknown, what: string, number?: number): TrainPull => {+ const body = object(value), head = object(body.head), into = object(body.base)+ const state = body.state+ if (typeof body.number !== 'number' || (number !== undefined && body.number !== number) || (state !== 'open' && state !== 'closed')+ || typeof body.draft !== 'boolean' || !text(body.html_url) || !text(head.ref) || !text(into.ref)) throw new TrainReadError(what, 200)+ const mergeable = body.mergeable === true || body.mergeable === false ? body.mergeable : null+ return { number: body.number, url: text(body.html_url)!, state, merged: body.merged === true, draft: body.draft, title: text(body.title) ?? '',+ body: text(body.body) ?? '', mergeable, head: sha(head.sha, what), headRef: text(head.ref)!,+ headRepository: (text(object(head.repo).full_name) ?? '').toLowerCase(), base: text(into.ref)!,+ labels: Array.isArray(body.labels) ? body.labels.map(label => text(object(label).name)).filter((n): n is string => !!n) : [] }+ }+ return {+ repository: repository.toLowerCase(),+ async mainHead() {+ const answer = object((await expect('GET', '/git/ref/heads/main', [200])).body), target = object(answer.object)+ if (answer.ref !== 'refs/heads/main' || target.type !== 'commit') throw new TrainReadError('main', 200)+ return sha(target.sha, 'main')+ },+ async openPulls() {+ const all: TrainPull[] = []+ for (let page = 1; page <= PULL_PAGES; page++) {+ const answer = (await expect('GET', `/pulls?state=open&base=main&per_page=100&page=${page}`, [200])).body+ if (!Array.isArray(answer)) throw new TrainReadError('open pulls', 200)+ all.push(...answer.map(entry => pullOf(entry, 'open pulls')))+ if (answer.length < 100) return all+ }+ throw new TrainReadError('open pulls: too many', 200)+ },+ async pull(number) {+ return pullOf((await expect('GET', `/pulls/${number}`, [200])).body, `pull ${number}`, number)+ },+ async files(number) {+ const all: string[] = []+ for (let page = 1; page <= FILE_PAGES; page++) {+ const answer = (await expect('GET', `/pulls/${number}/files?per_page=100&page=${page}`, [200])).body+ if (!Array.isArray(answer)) throw new TrainReadError(`files ${number}`, 200)+ for (const entry of answer) {+ const name = text(object(entry).filename)+ if (!name) throw new TrainReadError(`files ${number}`, 200)+ all.push(name)+ // A rename changes its old path too.+ const before = text(object(entry).previous_filename)+ if (before) all.push(before)+ }+ if (answer.length < 100) return all+ }+ throw new TrainReadError(`files ${number}: too many`, 200)+ },+ async ciRequired(head) {+ sha(head, 'ci head')+ const answer = object((await expect('GET', `/commits/${head}/check-runs?check_name=${encodeURIComponent(TRAIN_CI_CHECK)}&filter=latest`, [200])).body)+ if (!Array.isArray(answer.check_runs)) throw new TrainReadError('ci', 200)+ const runs = answer.check_runs.map(object).filter(run => run.name === TRAIN_CI_CHECK)+ if (!runs.length) return null+ if (runs.some(run => run.status !== 'completed')) return 'pending'+ return runs.every(run => PASSED.has(String(run.conclusion))) ? 'success' : 'failure'+ },+ async createBranch(name, from) {+ own(name, 'create branch')+ await expect('POST', '/git/refs', [201], { ref: `refs/heads/${name}`, sha: sha(from, 'branch base') })+ },+ async mergeInto(branch, head, message, tip) {+ own(branch, 'merge')+ const answer = await expect('POST', '/merges', [201, 204, 409], { base: branch, head: sha(head, 'merge head'), commit_message: message })+ if (answer.status === 409) return 'conflict'+ if (answer.status === 204) return 'already'+ const body = object(answer.body), merged = sha(body.sha, 'merge')+ // Always a merge commit of its own, never the member's commit itself, with exactly the tip the train built as its first+ // parent and the member as its second: a commit anyone pushed onto the branch meanwhile never gets into a batch.+ const parents = Array.isArray(body.parents) ? body.parents.map(p => text(object(p).sha)) : []+ if (merged === head || parents.length !== 2 || parents[0] !== tip || parents[1] !== head) throw new TrainReadError('merge: unexpected parents', 201)+ return { sha: merged }+ },+ async openPull(branch, title, body) {+ own(branch, 'open pull')+ return pullOf((await expect('POST', '/pulls', [201], { head: branch, base: 'main', title, body, draft: false })).body, 'open pull')+ },+ async squash(number, head, title, message) {+ const answer = object((await expect('PUT', `/pulls/${number}/merge`, [200],+ { sha: sha(head, 'squash head'), merge_method: 'squash', commit_title: title, commit_message: message })).body)+ if (answer.merged !== true) throw new TrainReadError(`squash ${number}`, 200)+ return { sha: sha(answer.sha, `squash ${number}`) }+ },+ async comment(number, body) {+ await expect('POST', `/issues/${number}/comments`, [201], { body })+ },+ async close(number) {+ await expect('PATCH', `/pulls/${number}`, [200], { state: 'closed' })+ },+ async deleteBranch(name) {+ own(name, 'delete branch')+ // Gone already reads as done.+ await expect('DELETE', `/git/refs/heads/${name}`, [204, 422])+ },+ }+}++/** The train's calls on [repository] with one [TRAIN_PERMISSIONS] token for the pass, revoked by `done`; null where the app+ * is not installed. */+export async function repositoryTrain(app: Pick<GitHubApp, 'installation' | 'createToken' | 'installationCall' | 'revoke'>, repository: GitHubRepository):+ Promise<(TrainGitHub & { done(): Promise<void> }) | null> {+ const installation = await app.installation(repository)+ if (installation === null) return null+ const { token } = await app.createToken(installation, repository, TRAIN_PERMISSIONS)+ const train = trainGitHub((method, path, body) => app.installationCall(token, method, path, body), `${repository.owner}/${repository.name}`)+ return { ...train, done: () => app.revoke(token).catch(() => {}) }+}diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.tsindex 455d05be0..0446e7221 100644--- a/backend/src/superTabs/commands.test.ts+++ b/backend/src/superTabs/commands.test.ts@@ -20,6 +20,8 @@ import { groupView } from './read/views.js'import { weekStart } from './leaderboard/week.js'import { lentIn, weekSpan } from './leaderboard/rolling.js'+const HOLD = { kind: 'person', personId: 'owner', defaultAt: '2026-11-06T02:00:00.000Z' } as const+const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }/** What an older client's routing, policy, skill-set or role save answers (project instructions, phase 4). */const IGNORED_NOTE = 'Routing and roles live in each project\'s instructions now. Update Harness to edit them there.'@@ -331,7 +333,7 @@ describe('Super Tab collaboration policy', () => {expect(post(as(worker), [other])).toEqual([other])expect(post(as(worker), [lead])).toEqual([lead])expect(post(as(lead))).toEqual([worker])- f.run({ type: 'work.status', conversationId: group, assignmentId: f.state.conversations[1]!.assignment!.id, status: 'blocked', result: 'Stuck.' }, as(worker))+ f.run({ type: 'work.status', conversationId: group, assignmentId: f.state.conversations[1]!.assignment!.id, status: 'blocked', hold: HOLD, result: 'Stuck.' }, as(worker))expect(post(as(worker))).toEqual([])})@@ -795,12 +797,12 @@ describe('Super Tab collaboration policy', () => {const worker = f.add('worker', 'owner', group)const assignmentId = f.run({ type: 'work.assign', conversationId: group, agentId: worker }).result.assignmentId as stringconst as: Actor = { kind: 'agent', agentId: worker, machineOwnerId: 'host-owner' }- const stuck = f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'blocked', result: 'The staging database refuses my key.' }, as)+ const stuck = f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'blocked', hold: HOLD, result: 'The staging database refuses my key.' }, as)expect(stuck.messages[0]).toMatchObject({ conversationId: group, text: 'Stuck\n\nThe staging database refuses my key.', recipients: [lead] })expect(f.state.conversations[1]!.assignment!.status).toBe('blocked')expect(activeWork(f.state.conversations[1]!)).toBe(true)expect(() => f.run({ type: 'work.assign', conversationId: f.group(), agentId: worker })).toThrow('active assignment')- const decision = f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'needs_human', result: 'Ship to everyone, or behind a flag?' }, as)+ const decision = f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'needs_human', hold: HOLD, result: 'Ship to everyone, or behind a flag?' }, as)expect(decision.messages[0]).toMatchObject({ text: 'Needs a human\n\nShip to everyone, or behind a flag?', recipients: [lead] })f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'working', result: null }, as)expect(f.state.conversations[1]!.assignment!.status).toBe('working')@@ -1096,7 +1098,7 @@ describe('the last action of the project\'s agents on a task', () => {f.define(group)f.invite()const assignmentId = f.run({ type: 'work.assign', conversationId: group, agentId: f.worker, ...via }, f.leadActor, { ...decisionIn(group), now: 2000 }).result.assignmentId as string- f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'needs_human', result: 'Flag or not?',+ f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'needs_human', hold: HOLD, result: 'Flag or not?',ask: { personId: 'peer', options: ['Flag', 'Ship'], recommended: 0, unblocks: 'The release' } }, f.workerActor, { now: 3000 })expect(task().assignment!.askedOf).toBe('peer')expect(task().liveness).toMatchObject({ state: 'waiting', why: 'person', personId: 'peer' })@@ -1973,7 +1975,7 @@ describe('any agent of the project', () => {f.run({ type: 'conversation.rename', conversationId: group, title: 'Drafts offline' }, E)f.run({ type: 'conversation.requester', conversationId: group, personId: 'owner' }, E)expect(task()).toMatchObject({ title: 'Drafts offline', requesterId: 'owner' })- f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'blocked', result: 'Staging refuses the key.' }, E)+ f.run({ type: 'work.status', conversationId: group, assignmentId, status: 'blocked', hold: HOLD, result: 'Staging refuses the key.' }, E)expect(task().assignment!.status).toBe('blocked')f.run({ type: 'conversation.merged', conversationId: group, pullRequestUrl: 'https://github.com/example/app/pull/7' }, E)expect(task().ledger?.shippedAt).toBe(1000)@@ -1993,7 +1995,7 @@ describe('any agent of the project', () => {const { f, E } = project(), A = f.worker, group = f.group()const assignmentId = f.run({ type: 'work.assign', conversationId: group, agentId: A }).result.assignmentId as stringconst told = (status: 'working' | 'blocked' | 'review', actor: Actor, result = `Moved to ${status}.`) =>- f.run({ type: 'work.status', conversationId: group, assignmentId, status, result }, actor).messages[0]!.recipients+ f.run({ type: 'work.status', conversationId: group, assignmentId, status, result, ...(status === 'blocked' ? { hold: HOLD } : {}) }, actor).messages[0]!.recipientsexpect(told('blocked', E)).toEqual([A, f.lead])expect(told('working', owner)).toEqual([A, f.lead])// The coordinator's own change reaches its agent.@@ -3310,7 +3312,7 @@ it('marks every row the system writes in the owner\'s name, so a Lead cannot quoconst worker = f.add('worker', 'owner', group)run({ type: 'work.define', conversationId: group, brief: 'Save drafts offline.', checks: [{ description: 'Saved.', independent: false }] })const assignmentId = run({ type: 'work.assign', conversationId: group, agentId: worker }).result.assignmentId as string- run({ type: 'work.status', conversationId: group, assignmentId, status: 'blocked', result: 'Waiting.' })+ run({ type: 'work.status', conversationId: group, assignmentId, status: 'blocked', hold: HOLD, result: 'Waiting.' })run({ type: 'delivery.resolve', deliveryId: 'd1', resolution: 'received' },{ delivery: { id: 'd1', conversationId: group, agentId: worker, messageId: 'm1', text: 'Earlier.' } })run({ type: 'delivery.resolve', deliveryId: 'd2', resolution: 'resend' },@@ -4403,7 +4405,7 @@ describe('credentials in Swarm chat', () => {const worker = f.add('worker', 'owner', group.id)const assignmentId = f.run({ type: 'work.assign', conversationId: group.id, agentId: worker }).result.assignmentId as stringconst as: Actor = { kind: 'agent', agentId: worker, machineOwnerId: 'host-owner' }- const blocked = f.run({ type: 'work.status', conversationId: group.id, assignmentId, status: 'blocked', result: `Rejected ${github}` }, as)+ const blocked = f.run({ type: 'work.status', conversationId: group.id, assignmentId, status: 'blocked', hold: HOLD, result: `Rejected ${github}` }, as)expect(blocked.messages[0]!.text).toBe(`Stuck\n\nRejected ${CREDENTIAL_MARKER}`)f.run({ type: 'work.check', conversationId: group.id, assignmentId, checkId: group.checks[0]!.id, passed: true, evidence: `Signed in as ${jwt}` },{ kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' })@@ -5862,7 +5864,7 @@ describe('the Next-up queue (work.queue)', () => {.result.conversationId as stringconst [a, b, c] = [open('Drafts'), open('Sync'), open('Search')] as [string, string, string]const task = (id: string) => f.state.conversations.find(g => g.id === id)!- const queue = (conversationId: string, fields: { after?: string | null; notBefore?: string | null }) =>+ const queue = (conversationId: string, fields: { after?: string | null; notBefore?: string | null; hold?: unknown }) =>commandSchema.parse({ type: 'work.queue', conversationId, ...fields })return { f, a, b, c, open, task, queue }}@@ -5882,7 +5884,7 @@ describe('the Next-up queue (work.queue)', () => {it('takes the PM\'s not-before date, and clears it with null', () => {const { f, a, task, queue } = queued()- f.run(queue(a, { notBefore: '2026-12-04' }), f.leadActor)+ f.run(queue(a, { notBefore: '2026-12-04', hold: { kind: 'requester' } }), f.leadActor)expect(task(a).notBefore).toBe('2026-12-04')expect(task(a).queueRank).toBeUndefined()expect(groupView(task(a), new Set())).toMatchObject({ notBefore: '2026-12-04' })@@ -5933,10 +5935,10 @@ describe('the Next-up queue (work.queue)', () => {it('does the work once when the same operation comes again', () => {const { f, a, c, task, queue } = queued()- f.run(queue(c, { after: a, notBefore: '2026-12-04' }), owner, { operationId: 'move' })+ f.run(queue(c, { after: a, notBefore: '2026-12-04', hold: HOLD }), owner, { operationId: 'move' })const once = structuredClone(f.state)expect(task(c)).toMatchObject({ queueRank: expect.any(Number), notBefore: '2026-12-04' })- f.run(queue(c, { after: a, notBefore: '2026-12-04' }), owner, { operationId: 'move' })+ f.run(queue(c, { after: a, notBefore: '2026-12-04', hold: HOLD }), owner, { operationId: 'move' })expect(f.state).toEqual(once)})})@@ -6270,3 +6272,138 @@ describe('a start for a project with no repository', () => {expect(leadHost(f.state, project, 'other', { engine: 'claude' }, leadFor, { now: 1000 })).toMatchObject({ worktree: true })})})++describe('a held task carries one of four reasons (HOLD_REASON_MISSING)', () => {+ const REASONS = {+ task: (taskNumber: number) => ({ kind: 'task' as const, taskNumber }),+ person: { kind: 'person' as const, personId: 'owner', defaultAt: '2026-11-06T02:00:00.000Z' },+ reset: { kind: 'reset' as const, what: 'quota' as const, at: '2026-11-06T09:00:00.000Z' },+ requester: { kind: 'requester' as const },+ }+ const missing = expect.objectContaining({ code: 'HOLD_REASON_MISSING', status: 400,+ message: expect.stringMatching(/waits on task #N.*person already asked.*reset.*requester asked for later/s) })++ function queued() {+ const f = routed()+ const open = (title: string) => f.run({ type: 'conversation.create', title, brief: `${title}.`, checks: [], requesterId: 'owner' }).result.conversationId as string+ const [a, b] = [open('Drafts'), open('Sync')] as [string, string]+ const task = (id: string) => f.state.conversations.find(g => g.id === id)!+ const hold = (conversationId: string, fields: Record<string, unknown>) =>+ f.run(commandSchema.parse({ type: 'work.queue', conversationId, notBefore: '2026-12-04', ...fields }), f.leadActor)+ return { f, a, b, task, hold }+ }++ /** A task whose worker holds an assignment, as an agent reports it. */+ function working() {+ const f = routed()+ const group = f.group()+ const assignmentId = f.run({ type: 'work.assign', conversationId: group, agentId: f.worker }).result.assignmentId as string+ const task = () => f.state.conversations.find(g => g.id === group)!+ task().requesterId = 'owner'+ const status = (fields: Record<string, unknown>) => f.run(commandSchema.parse({ type: 'work.status', conversationId: group, assignmentId, result: 'Waiting.', ...fields }), f.workerActor)+ return { f, group, task, status }+ }++ it('accepts each of the four reasons on a not-before hold, and shows it', () => {+ const { f, a, b, task, hold } = queued()+ for (const [name, reason] of Object.entries({ ...REASONS, task: REASONS.task(task(b).number!) })) {+ hold(a, { hold: reason })+ expect(task(a).hold, name).toEqual(reason)+ expect(groupView(task(a), new Set()).held, name).toEqual(reason)+ }+ })++ it('refuses a not-before hold with no reason, and names the four kinds', () => {+ const { f, a, task, hold } = queued()+ const before = structuredClone(f.state)+ expect(() => hold(a, {})).toThrow(missing)+ expect(f.state).toEqual(before)+ expect(task(a).notBefore).toBeUndefined()+ })++ it('refuses a reason that is not true: another task that is not there, itself, a stranger, a requester nobody has', () => {+ const { f, a, task, hold, b } = queued()+ delete task(b).requesterId+ const before = structuredClone(f.state)+ expect(() => hold(a, { hold: REASONS.task(9999) })).toThrow(missing)+ expect(() => hold(a, { hold: REASONS.task(task(a).number!) })).toThrow(missing)+ expect(() => hold(a, { hold: { ...REASONS.person, personId: 'nobody' } })).toThrow(missing)+ expect(() => hold(b, { hold: REASONS.requester })).toThrow(missing)+ expect(f.state).toEqual(before)+ })++ it('takes the reason away with the date, and a place alone needs none', () => {+ const { f, a, b, task, hold } = queued()+ hold(a, { hold: REASONS.requester })+ f.run(commandSchema.parse({ type: 'work.queue', conversationId: a, notBefore: null }), f.leadActor)+ expect(task(a)).not.toHaveProperty('hold')+ expect(task(a)).not.toHaveProperty('notBefore')+ f.run(commandSchema.parse({ type: 'work.queue', conversationId: b, after: a }), f.leadActor)+ expect(task(b).queueRank).toBeDefined()+ })++ it('refuses a reason sent without a date, or with a kind that is not one of the four', () => {+ const parse = (fields: Record<string, unknown>) => commandSchema.safeParse({ type: 'work.queue', conversationId: 'task', ...fields }).success+ expect(parse({ after: null, hold: REASONS.requester })).toBe(false)+ expect(parse({ notBefore: '2026-12-04', hold: { kind: 'later' } })).toBe(false)+ expect(parse({ notBefore: '2026-12-04', hold: { kind: 'person', personId: 'owner' } })).toBe(false)+ expect(parse({ notBefore: '2026-12-04', hold: REASONS.reset })).toBe(true)+ })++ it('accepts each of the four reasons on blocked and on needs_human, and shows it', () => {+ const { f, group, task, status } = working()+ const other = f.group()+ const reasons = { ...REASONS, task: REASONS.task(f.state.conversations.find(g => g.id === other)!.number!) }+ for (const held of ['blocked', 'needs_human'] as const) {+ for (const [name, reason] of Object.entries(reasons)) {+ status({ status: held, hold: reason })+ expect(task().assignment!.hold, `${held} ${name}`).toEqual(reason)+ expect(groupView(task(), new Set()).held, `${held} ${name}`).toEqual(reason)+ }+ }+ expect(group).toBeDefined()+ })++ it('takes blocked and needs_human with no reason for now, shows no reason, and still refuses a reason that is not true', () => {+ const { f, task, status } = working()+ for (const held of ['blocked', 'needs_human'] as const) {+ status({ status: held })+ expect(task().assignment!.status, held).toBe(held)+ expect(groupView(task(), new Set()).held, held).toEqual({ kind: 'none' })+ }+ const before = structuredClone(f.state)+ expect(() => status({ status: 'needs_human', hold: REASONS.task(9999) })).toThrow(missing)+ expect(f.state).toEqual(before)+ })++ it('refuses a reason whose time has passed, and a task that is a step', () => {+ const { f, a, task } = queued()+ const now = Date.parse('2026-11-05T00:00:00.000Z')+ const hold = (reason: Record<string, unknown>) => f.run(commandSchema.parse({ type: 'work.queue', conversationId: a, notBefore: '2026-12-04', hold: reason }), f.leadActor, { now })+ expect(() => hold({ ...REASONS.person, defaultAt: '2026-11-04T00:00:00.000Z' })).toThrow(missing)+ expect(() => hold({ ...REASONS.reset, at: '2026-11-04T00:00:00.000Z' })).toThrow(missing)+ hold({ ...REASONS.reset, at: '2026-11-06T00:00:00.000Z' })+ const step = f.run({ type: 'conversation.create', title: 'Review', brief: 'Review it.', reviewOf: a, step: 'Review', checks: [] }).result.conversationId as string+ expect(() => hold(REASONS.task(task(step).number!))).toThrow(missing)+ })++ it('clears the reason with the next status, and takes none on any other status', () => {+ const { task, status } = working()+ status({ status: 'blocked', hold: REASONS.reset })+ status({ status: 'working', result: null })+ expect(task().assignment).not.toHaveProperty('hold')+ expect(groupView(task(), new Set())).not.toHaveProperty('held')+ expect(commandSchema.safeParse({ type: 'work.status', conversationId: 'g', assignmentId: 'a', status: 'working', result: null, hold: REASONS.reset }).success).toBe(false)+ })++ it('shows a hold from before reasons as no reason, and a task that is not held as nothing', () => {+ const { f, a, b, task } = queued()+ task(a).notBefore = '2026-12-04'+ expect(groupView(task(a), new Set()).held).toEqual({ kind: 'none' })+ expect(groupView(task(b), new Set())).not.toHaveProperty('held')+ const { task: blocked, f: g } = working()+ blocked().assignment!.status = 'blocked'+ expect(groupView(blocked(), new Set()).held).toEqual({ kind: 'none' })+ expect(f.state).toBeDefined(); expect(g.state).toBeDefined()+ })+})diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex caf432ecc..0f873456d 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -26,6 +26,7 @@ import { projectRulesSchema, rulesDiff, rulesEqual, SEED_RULES, type ProjectRuleimport { accessRefusal, changeAccess, expireAccess, taskAccess } from './machineAccess.js'import { MAX_ATTACHMENTS, type Attachment } from './attachments.js'import { agentsNamedIn, checkMentions, MAX_MENTIONS, namedIn, saysName, textTags, withTags, type MentionTarget } from './mentions.js'+import { checkReason, heldReason, missingReason } from './heldReason.js'import { answerDecision, askDecisions, checkAsker, decisionChoices, decisionQuestion, MAX_OPEN_DECISIONS, MAX_QUESTIONS, type DecisionTarget } from './decisions.js'import { leadOf, TERMINAL_KEYS, terminalAlert, terminalRequest, terminalResult, toLead, type TerminalRequest, workedAgain } from './terminal.js'import { BACK_WITH_YOU, pickUp, reopenHanded } from './handed.js'@@ -280,8 +281,11 @@ export const commandSchema = z.discriminatedUnion('type', [z.object({ type: z.literal('conversation.requester'), conversationId: id, personId: id.nullable() }).strict(),// A task's place in its project's Next up (taskQueue.ts): `after` the open task it goes right after, null for the top, absent// to stay; `notBefore` a day it should not start before, null to clear.- z.object({ type: z.literal('work.queue'), conversationId: id, after: id.nullable().optional(), notBefore: day.nullable().optional() }).strict()- .refine(c => c.after !== undefined || c.notBefore !== undefined, 'Give the task a place (after) or a not-before date.'),+ // A not-before date holds the task, so it carries its reason (heldReason.ts); a date without one is refused when it is applied.+ z.object({ type: z.literal('work.queue'), conversationId: id, after: id.nullable().optional(), notBefore: day.nullable().optional(),+ hold: heldReason.optional() }).strict()+ .refine(c => c.after !== undefined || c.notBefore !== undefined, 'Give the task a place (after) or a not-before date.')+ .refine(c => c.hold === undefined || typeof c.notBefore === 'string', 'A hold reason goes with a not-before date.'),// The Lead's record that a request's pull request merged (leaderboard/record.ts recordMerged); `mergedAt` for a backfill.// `fixes`: the merged PR this one fixes, for its model's fixes after merge (leaderboard/record.ts recordFix).z.object({ type: z.literal('conversation.merged'), conversationId: id, pullRequestUrl: z.string().max(400).regex(PULL_REQUEST_URL),@@ -405,7 +409,10 @@ export const commandSchema = z.discriminatedUnion('type', [// A worker's question for one named person, opened as a decision (decisions.ts); the result is the question.ask: decisionChoices.extend({ personId: id }).strict().optional(),// Its session's token totals by model, read by its host as it finishes (Done, Stopped): the attempt's end (costs/attempts.ts).- tokens: tokensByModelSchema.optional() }).strict(),+ tokens: tokensByModelSchema.optional(),+ // Why it waits, for blocked and needs_human (heldReason.ts); a status without one is refused when it is applied.+ hold: heldReason.optional() }).strict()+ .refine(c => c.hold === undefined || c.status === 'blocked' || c.status === 'needs_human', 'A hold reason goes with blocked or needs_human.'),z.object({ type: z.literal('work.cancel'), conversationId: id, assignmentId: id, reason }).strict(),// `lostAt` names the loss being resumed (Assignment.lost.at): one task can be lost to a limit, resumed and lost again.z.object({ type: z.literal('work.resume'), conversationId: id, assignmentId: id, lostAt: z.number().int().nonnegative().safe() }).strict(),@@ -2434,8 +2441,13 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,}for (const [groupId, rank] of placeAfter(siblings, task.id, command.after)) conversation(state, groupId).queueRank = rank}- if (command.notBefore === null) delete task.notBefore- else if (command.notBefore !== undefined) task.notBefore = command.notBefore+ if (command.notBefore === null) { delete task.notBefore; delete task.hold }+ else if (command.notBefore !== undefined) {+ if (!command.hold) missingReason()+ checkReason(state, task, command.hold, context.now)+ task.notBefore = command.notBefore+ task.hold = command.hold+ }break}case 'work.priority': {@@ -3814,6 +3826,10 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,if (!activeWork(group)) fail('ATTEMPT_CLOSED', 'Assign a new attempt to continue this work.')if (command.status === 'stopped' && !context.confirmedStopped) fail('STOP_UNCONFIRMED', 'Wait for the execution host to confirm the stop.')if (assignment.status === 'reconciling' && command.status !== 'stopped') fail('RECONCILING', 'Reconcile the previous assignment before continuing.')+ const holding = command.status === 'blocked' || command.status === 'needs_human'+ // Staged (review of #3215): a client from before reasons sends none, so blocked and needs_human take it for now and show+ // "no reason"; a reason that is sent is still checked. The refusal follows once the CLI sends one.+ if (holding && command.hold) checkReason(state, group, command.hold, context.now)let asked: string | undefinedif (command.ask) {if (command.status !== 'needs_human' || !command.result || actor.kind !== 'agent') {@@ -3841,6 +3857,9 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,pickUp(assignment)if (command.ask) assignment.askedOf = command.ask.personIdelse if (command.status !== 'needs_human') delete assignment.askedOf+ // Why it waits lasts as long as the wait: the next status clears it.+ if (holding) assignment.hold = command.hold+ else delete assignment.holdrecordStatus(group, assignment, previous, context.now, changed ? operationId : null, asked)if (['done', 'stopped'].includes(command.status)) finishWorker(state, assignment.agentId)// Finished work shows the worker recovered from a task it lost before.diff --git a/backend/src/superTabs/decisions.test.ts b/backend/src/superTabs/decisions.test.tsindex 9015fbbb0..2bde667ea 100644--- a/backend/src/superTabs/decisions.test.ts+++ b/backend/src/superTabs/decisions.test.ts@@ -6,6 +6,8 @@ import { createSuperTab, type Actor, type AgentConfiguration } from './model.js'import { ANSWERED_NOTICE, askDecisions, checkAsker, decisionsWaiting, listDecisions, overdueNotice, delegatedNotice, answerDecision, waitingInProject, withdrawIn, workEnded, workOver, type DecisionTarget } from './decisions.js'import { buddyChatId } from './buddies.js'+const HOLD = { kind: 'person', personId: 'owner', defaultAt: '2026-11-06T02:00:00.000Z' } as const+const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }const peer: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'peer', email: '[email protected]' }const config: AgentConfiguration = { engine: 'codex', model: 'test-model', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }@@ -68,15 +70,15 @@ describe('asking a person for decisions', () => {it('opens a decision for the named person when a worker needs one on its own task, and still tells the Lead', () => {const s = swarm()- const needs = s.run({ type: 'work.status', conversationId: s.group, assignmentId: s.assignmentId, status: 'needs_human', result: 'Ship to everyone, or behind a flag?',+ const needs = s.run({ type: 'work.status', conversationId: s.group, assignmentId: s.assignmentId, status: 'needs_human', hold: HOLD, result: 'Ship to everyone, or behind a flag?',ask: { personId: 'peer', options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'Turning the feature on' } }, asAgent(s.worker))expect(needs.decisions).toEqual([expect.objectContaining({ personId: 'peer', askerAgentId: s.worker, assignmentId: s.assignmentId,question: 'Ship to everyone, or behind a flag?', recommended: 0, unblocks: 'Turning the feature on' })])expect(needs.messages[0]).toMatchObject({ text: 'Needs a human\n\nShip to everyone, or behind a flag?\n\nAsked peer.', recipients: [s.lead] })// Without a person and options it reaches the Lead as before, who asks.- const plain = s.run({ type: 'work.status', conversationId: s.group, assignmentId: s.assignmentId, status: 'needs_human', result: 'Which database?' }, asAgent(s.worker))+ const plain = s.run({ type: 'work.status', conversationId: s.group, assignmentId: s.assignmentId, status: 'needs_human', hold: HOLD, result: 'Which database?' }, asAgent(s.worker))expect(plain.decisions ?? []).toEqual([])- expect(() => s.run({ type: 'work.status', conversationId: s.group, assignmentId: s.assignmentId, status: 'blocked', result: 'Stuck',+ expect(() => s.run({ type: 'work.status', conversationId: s.group, assignmentId: s.assignmentId, status: 'blocked', hold: HOLD, result: 'Stuck',ask: { personId: 'peer', options: ['A', 'B'], recommended: 0, unblocks: 'X' } }, asAgent(s.worker))).toThrow('needs a human')})diff --git a/backend/src/superTabs/heldReason.ts b/backend/src/superTabs/heldReason.tsnew file mode 100644index 000000000..29b3bce8d--- /dev/null+++ b/backend/src/superTabs/heldReason.ts@@ -0,0 +1,66 @@+import { z } from 'zod'+import { fail, type Conversation, type SuperTabState } from './model.js'+import { groupProject } from './projects.js'++/**+ * Why a task is held: a not-before date on the Next-up queue (work.queue), or an agent's blocked or needs_human status+ * (work.status). Exactly four reasons are real (anh Dee's Swarm redesign, 2026-11-05; #3390); the server refuses a hold that+ * names none (HOLD_REASON_MISSING), and the refusal lists the four. Not the delivery `holdReason` (holdReason.ts), which is a+ * host's reason for not typing a message yet.+ */+export const heldReason = z.discriminatedUnion('kind', [+ /** Waits on another task of the project. */+ z.object({ kind: z.literal('task'), taskNumber: z.number().int().positive().safe() }).strict(),+ /** Waits on a person who was asked, and what happens at `defaultAt` if they have not answered. */+ z.object({ kind: z.literal('person'), personId: z.string().min(1).max(200), defaultAt: z.iso.datetime() }).strict(),+ /** Waits for a quota or a machine to reset at `at`. */+ z.object({ kind: z.literal('reset'), what: z.enum(['quota', 'machine']), at: z.iso.datetime() }).strict(),+ /** The task's requester asked for it later. */+ z.object({ kind: z.literal('requester') }).strict(),+])+export type HeldReason = z.infer<typeof heldReason>++/** What a hold looks like where no reason was recorded: every hold from before reasons, shown as "no reason". */+export type HeldView = HeldReason | { kind: 'none' }++export const HELD_REASON_KINDS = ['task', 'person', 'reset', 'requester'] as const+/** The refusal's words: the four kinds, each with the fields it takes, so the next command can be right. */+export const HELD_REASON_HELP = 'Say why it is held, with "hold" set to one of: {"kind":"task","taskNumber":N} (waits on task #N); '+ + '{"kind":"person","personId":"PERSON","defaultAt":"ISO time"} (waits on a person already asked, and when the default applies); '+ + '{"kind":"reset","what":"quota"|"machine","at":"ISO time"} (waits for a reset); {"kind":"requester"} (the requester asked for later).'++/** A hold with no reason is refused, naming the four kinds. */+export function missingReason(): never {+ return fail('HOLD_REASON_MISSING', `A held task needs a reason. ${HELD_REASON_HELP}`, 400)+}++/**+ * The facts a reason claims, checked against the Swarm: the task it waits on is another task of this project, the person is a+ * member (not checked: that they were asked, which lives in their decisions), the requester exists, and a time is still ahead.+ * A reason that is not true is no reason.+ */+export function checkReason(state: SuperTabState, group: Conversation, reason: HeldReason, now: number): void {+ if (reason.kind === 'task') {+ const project = groupProject(state, group).id+ const other = state.conversations.find(c => c.number === reason.taskNumber && !c.archived && !c.reviewOf && !c.kind && groupProject(state, c).id === project)+ if (!other || other.id === group.id) fail('HOLD_REASON_MISSING', `Task #${reason.taskNumber} is not another open task of this project. ${HELD_REASON_HELP}`, 400)+ }+ else if (reason.kind === 'person') {+ if (Date.parse(reason.defaultAt) <= now) fail('HOLD_REASON_MISSING', `The default time ${reason.defaultAt} has passed. ${HELD_REASON_HELP}`, 400)+ if (!state.people.some(p => p.id === reason.personId)) fail('HOLD_REASON_MISSING', `${reason.personId} is not a member of this Swarm. ${HELD_REASON_HELP}`, 400)+ }+ else if (reason.kind === 'reset') {+ if (Date.parse(reason.at) <= now) fail('HOLD_REASON_MISSING', `The reset time ${reason.at} has passed. ${HELD_REASON_HELP}`, 400)+ }+ else if (reason.kind === 'requester' && !group.requesterId) {+ fail('HOLD_REASON_MISSING', `This task has no requester who could have asked for later. ${HELD_REASON_HELP}`, 400)+ }+}++/** What a reader shows for a held task: its reason, else "no reason" for a hold from before reasons. Absent when it is not held. */+export function heldView(group: Conversation): HeldView | undefined {+ const status = group.assignment?.status+ if (group.notBefore !== undefined) return group.hold ?? { kind: 'none' }+ if (status === 'blocked' || status === 'needs_human') return group.assignment!.hold ?? { kind: 'none' }+ return undefined+}diff --git a/backend/src/superTabs/leaderboard/record.test.ts b/backend/src/superTabs/leaderboard/record.test.tsindex be7aaf4c5..2379ca5c4 100644--- a/backend/src/superTabs/leaderboard/record.test.ts+++ b/backend/src/superTabs/leaderboard/record.test.ts@@ -6,6 +6,8 @@ import { MAX_UNBLOCKS } from './record.js'import { leaderboard } from './stats.js'import { DAY_MS, WEEK_MS, weekStart } from './week.js'+const HOLD = { kind: 'person', personId: 'owner', defaultAt: '2026-11-06T02:00:00.000Z' } as const+const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }const peer: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'peer', email: '[email protected]' }const config: AgentConfiguration = { engine: 'claude', model: 'opus', effort: 'high', contextWindow: null, engineVersion: null }@@ -41,7 +43,7 @@ function fixture() {return { worker, assignmentId: group(id).assignment!.id }}const status = (id: string, assignmentId: string, worker: string, next: 'working' | 'needs_human' | 'review' | 'done', result: string | null = null) =>- run({ type: 'work.status', conversationId: id, assignmentId, status: next, result }, asAgent(worker))+ run({ type: 'work.status', conversationId: id, assignmentId, status: next, result, ...(next === 'needs_human' ? { hold: HOLD } : {}) }, asAgent(worker))const passChecks = (id: string, assignmentId: string) => {for (const check of group(id).checks) run({ type: 'work.check', conversationId: id, assignmentId, checkId: check.id, passed: true, evidence: 'ok' })}diff --git a/backend/src/superTabs/mergeTrain/config.ts b/backend/src/superTabs/mergeTrain/config.tsnew file mode 100644index 000000000..92b626ed9--- /dev/null+++ b/backend/src/superTabs/mergeTrain/config.ts@@ -0,0 +1,42 @@+/**+ * The merge train's numbers (task #3402), in one place until the project rules record (task #3393) holds them: the train is+ * off until a project switches it on (River, 2026-11-05: merging someone's repository by itself would surprise them), and+ * runs every 10 minutes once on.+ */+export const TRAIN_DEFAULTS = Object.freeze({ enabled: false, everyMinutes: 10 })++/** Branches the train builds batches on. Nothing else in a repository may use this prefix. */+export const TRAIN_BRANCH_PREFIX = 'harness-train/'+/** The most pull requests one batch holds. */+export const TRAIN_MAX_BATCH = 8+/** The check whose green the train waits for, at a member's head and at the batch's. */+export const TRAIN_CI_CHECK = 'ci/required'+/** A pull request with one of these labels (any case) waits: people hold one by hand this way. */+export const TRAIN_HOLD_LABELS = ['hold']+/** A batch whose CI has not finished in this long is closed and built again. */+export const TRAIN_CI_TIMEOUT_MS = 90 * 60_000+/** The most projects one pass walks, the most recently active first (ENGINEERING.md 4: no read grows without a bound). */+export const TRAIN_PROJECTS = 50++/** Paths that change nothing a build or test runs: their pull requests merge on their own, with no batch. Not scripts/: it+ * holds the CI planner and release scripts, which run (review 2 of #3226). */+export const FAST_LANE: readonly RegExp[] = [/^docs\//, /\.md$/i]+/** Paths the train's token may not change (it has no `workflows` permission): GitHub would refuse the merge. */+export const NOT_MERGEABLE_BY_TOKEN = /^\.github\/workflows\//++/**+ * Where each area of the review table lives in the repository, by the table's own area names (task #3393's seed). Until the+ * table maps its areas to paths, these patterns do; they err wide, as a pull request that needs one more read than it got+ * only waits, and one merged with too few cannot be taken back (River, 2026-11-05: fail closed on the review table).+ */+export const REVIEW_AREAS: ReadonlyArray<{ area: string; paths: RegExp }> = [+ { area: 'Sign-in', paths: /(^|\/)(auth|login|sign_?in|signin|session)[^/]*$|^backend\/src\/middlewares\//i },+ { area: 'Tokens', paths: /token|^backend\/src\/github\//i },+ { area: 'Encryption', paths: /crypt|cipher|secret|credential|key(s|chain)?\b/i },+ { area: 'Access', paths: /access|permission|audience|membership/i },+ { area: 'Buddy guard', paths: /guard/i },+ { area: 'Device links', paths: /device|harness_?links|pairing|join_?link/i },+ { area: 'Deletion', paths: /purge|delet|cleanup|sweep|prune/i },+]+/** Reads an area above needs while the project has no review table. */+export const SECURITY_READS = 2diff --git a/backend/src/superTabs/mergeTrain/fakeTrainGitHub.ts b/backend/src/superTabs/mergeTrain/fakeTrainGitHub.tsnew file mode 100644index 000000000..7292d9f45--- /dev/null+++ b/backend/src/superTabs/mergeTrain/fakeTrainGitHub.ts@@ -0,0 +1,114 @@+/**+ * Tests only: one repository in memory, as the merge train's calls see it (github/train.ts TrainGitHub). Nothing here reaches+ * github.com. Commits are made-up SHAs; a squash moves main.+ */+import { createHash } from 'node:crypto'+import { TrainReadError, type TrainGitHub, type TrainPull } from '../../github/train.js'++export const sha = (seed: string): string => createHash('sha1').update(seed).digest('hex')++export interface FakePull extends TrainPull { files: string[] }++export function fakeTrainGitHub() {+ const state = {+ main: sha('main-0'),+ pulls: new Map<number, FakePull>(),+ /** ci/required by SHA; a SHA not listed reads as pending once it is a batch's tip, else null. */+ ci: new Map<string, 'success' | 'failure' | 'pending'>(),+ branches: new Map<string, string>(),+ /** Heads that conflict when merged into any batch. */+ conflicts: new Set<string>(),+ /** What each merge commit holds: the member heads merged into it. */+ contents: new Map<string, string[]>(),+ comments: [] as Array<{ number: number; text: string }>,+ squashes: [] as Array<{ number: number; sha: string; title: string; message: string }>,+ writes: [] as string[],+ reads: [] as string[],+ /** Calls (by name) that answer as GitHub failing. */+ failing: new Set<string>(),+ /** A squash GitHub refuses, with its reason (branch protection, a workflow change without that permission). */+ squashRefusal: null as string | null,+ /** Heads already in main: merging one into a batch merges nothing. */+ inMain: new Set<string>(),+ nextNumber: 900,+ /** Runs before each merge into a batch branch: a test pushes onto the branch here. */+ beforeMerge: null as ((branch: string) => void) | null,+ }+ const read = (name: string) => {+ state.reads.push(name)+ if (state.failing.has(name)) throw new TrainReadError(name, 500)+ }+ const write = (name: string) => {+ state.writes.push(name)+ if (state.failing.has(name)) throw new TrainReadError(name, 500)+ }+ const copy = (pull: FakePull): TrainPull => {+ const { files: _files, ...rest } = pull+ return { ...rest, labels: [...pull.labels] }+ }+ const github: TrainGitHub = {+ repository: 'acme/app',+ async mainHead() { read('mainHead'); return state.main },+ async openPulls() { read('openPulls'); return [...state.pulls.values()].filter(p => p.state === 'open').map(copy) },+ async pull(number) {+ read('pull')+ const found = state.pulls.get(number)+ if (!found) throw new TrainReadError('pull', 404)+ return copy(found)+ },+ async files(number) { read('files'); return [...state.pulls.get(number)?.files ?? []] },+ async ciRequired(head) { read('ciRequired'); return state.ci.get(head) ?? (state.contents.has(head) ? 'pending' : null) },+ async createBranch(name, from) { write('createBranch'); state.branches.set(name, from); state.contents.set(from, state.contents.get(from) ?? []) },+ async mergeInto(branch, head, message, expected) {+ write('mergeInto')+ state.beforeMerge?.(branch)+ // As github/train.ts checks GitHub's answer: the merge's first parent must be the tip the train expects.+ if (state.branches.get(branch) !== expected) throw new TrainReadError('merge: unexpected parents', 201)+ if (state.conflicts.has(head)) return 'conflict'+ if (state.inMain.has(head)) return 'already'+ const tip = state.branches.get(branch)!+ const merged = sha(`${tip}+${head}+${message}`)+ state.contents.set(merged, [...state.contents.get(tip) ?? [], head])+ state.branches.set(branch, merged)+ return { sha: merged }+ },+ async openPull(branch, title, body) {+ write('openPull')+ const number = state.nextNumber+++ const pull: FakePull = { number, url: `https://github.com/acme/app/pull/${number}`, state: 'open', merged: false, draft: false, title, body,+ mergeable: true, head: state.branches.get(branch)!, headRef: branch, headRepository: 'acme/app', base: 'main', labels: [], files: [] }+ state.pulls.set(number, pull)+ return copy(pull)+ },+ async squash(number, head, title, message) {+ write('squash')+ if (state.squashRefusal) throw new TrainReadError('squash', 405, state.squashRefusal)+ const pull = state.pulls.get(number)!+ if (pull.head !== head || pull.state !== 'open') throw new TrainReadError('squash', 409)+ state.main = sha(`${state.main}#${number}`)+ Object.assign(pull, { state: 'closed', merged: true })+ state.squashes.push({ number, sha: state.main, title, message })+ return { sha: state.main }+ },+ async comment(number, text) { write('comment'); state.comments.push({ number, text }) },+ async close(number) { write('close'); state.pulls.get(number)!.state = 'closed' },+ async deleteBranch(name) { write('deleteBranch'); state.branches.delete(name) },+ }+ /** A pull request into main with [files], ready, mergeable and green at its head. */+ const addPull = (number: number, files: string[], over: Partial<FakePull> = {}): FakePull => {+ const pull: FakePull = { number, url: `https://github.com/acme/app/pull/${number}`, state: 'open', merged: false, draft: false, title: `Change ${number}`,+ body: '', mergeable: true, head: sha(`head-${number}`), headRef: `feature-${number}`, headRepository: 'acme/app', base: 'main', labels: [], files, ...over }+ state.pulls.set(number, pull)+ state.ci.set(pull.head, 'success')+ return pull+ }+ /** A new commit pushed to pull request [number]. */+ const push = (number: number) => {+ const pull = state.pulls.get(number)!+ pull.head = sha(`${pull.head}-pushed`)+ state.ci.set(pull.head, 'success')+ return pull.head+ }+ const batches = () => [...state.pulls.values()].filter(p => p.headRef.startsWith('harness-train/') && p.state === 'open')+ return { github, state, addPull, push, batches }+}diff --git a/backend/src/superTabs/mergeTrain/plan.test.ts b/backend/src/superTabs/mergeTrain/plan.test.tsnew file mode 100644index 000000000..b770a762e--- /dev/null+++ b/backend/src/superTabs/mergeTrain/plan.test.ts@@ -0,0 +1,156 @@+import { describe, expect, it } from 'vitest'+import type { Check, Conversation } from '../model.js'+import { componentOf, eligible, headReads, laneOf, requiredReads, splitRed, type TrainCandidate, type TrainTask } from './plan.js'+import { TRAIN_DEFAULTS } from './config.js'++const URL = 'https://github.com/acme/app/pull/7'+const HEAD = 'a'.repeat(40), OLD = 'b'.repeat(40)++const check = (verdicts: Array<{ passed: boolean; head?: string; patch?: string | null; stale?: unknown; pullRequest?: string }>): Check => ({+ id: 'c1', description: 'Review', independent: true, evidence: null, passedBy: null,+ verdicts: verdicts.map((v, i) => ({ by: `agent:r${i}`, evidence: 'read', at: 1, pullRequest: URL, ...v })) as Check['verdicts'],+})+const step = (checks: Check[], over: Partial<Conversation> = {}): TrainTask['steps'][number] => ({+ step: 'Review', title: 'Review', checks, archived: false, assignment: { status: 'done' } as Conversation['assignment'], ...over,+})+const task = (over: Partial<TrainTask> = {}): TrainTask => ({+ checks: [check([{ passed: true, head: HEAD }])],+ pullRequestHeads: { [URL]: { head: HEAD, patch: 'p1', at: 1 } },+ steps: [step([check([{ passed: true, head: HEAD }])])],+ ...over,+})+const candidate = (over: Partial<TrainCandidate> = {}): TrainCandidate => ({+ url: URL, number: 7, head: HEAD, state: 'open', draft: false, base: 'main', mergeable: true, labels: [], files: ['backend/src/a.ts'],+ ciRequired: 'success', ...over,+})++describe('headReads', () => {+ it('counts passes recorded at the head GitHub shows now', () => {+ expect(headReads(task(), URL, HEAD)).toBe(1)+ })+ it('refuses a pass at an older head with another patch', () => {+ const t = task({ steps: [step([check([{ passed: true, head: OLD, patch: 'p0' }])])] })+ expect(headReads(t, URL, HEAD)).toBe(null)+ })+ it('keeps a pass at an older head whose patch is the same (a plain rebase)', () => {+ const t = task({ steps: [step([check([{ passed: true, head: OLD, patch: 'p1' }])])] })+ expect(headReads(t, URL, HEAD)).toBe(1)+ })+ it('never counts a pass with no head, though old clients still count it', () => {+ const t = task({ steps: [step([check([{ passed: true }])])] })+ expect(headReads(t, URL, HEAD)).toBe(null)+ })+ it('never counts a stale pass, or one on another pull request', () => {+ expect(headReads(task({ steps: [step([check([{ passed: true, head: HEAD, stale: { head: OLD } }])])] }), URL, HEAD)).toBe(null)+ expect(headReads(task({ steps: [step([check([{ passed: true, head: HEAD, pullRequest: 'https://github.com/acme/app/pull/8' }])])] }), URL, HEAD)).toBe(null)+ })+ it('refuses when the watch has not seen this head yet', () => {+ expect(headReads(task({ pullRequestHeads: { [URL]: { head: OLD, patch: 'p1', at: 1 } } }), URL, HEAD)).toBe(null)+ expect(headReads(task({ pullRequestHeads: undefined }), URL, HEAD)).toBe(null)+ })+ it('refuses a failure at the head next to a pass', () => {+ const t = task({ steps: [step([check([{ passed: true, head: HEAD }, { passed: false, head: HEAD }])])] })+ expect(headReads(t, URL, HEAD)).toBe(null)+ })+ it('needs a review step, every open step done, and the task checks too', () => {+ expect(headReads(task({ steps: [] }), URL, HEAD)).toBe(null)+ expect(headReads(task({ steps: [step([check([{ passed: true, head: HEAD }])], { step: 'Test', title: 'Test' })] }), URL, HEAD)).toBe(null)+ expect(headReads(task({ steps: [...task().steps, step([check([{ passed: true, head: HEAD }])], { step: 'Test', title: 'Test', assignment: { status: 'working' } as Conversation['assignment'] })] }), URL, HEAD)).toBe(null)+ expect(headReads(task({ steps: [...task().steps, step([], { step: 'Test', title: 'Test' })] }), URL, HEAD)).toBe(null)+ expect(headReads(task({ checks: [check([{ passed: true, head: OLD, patch: 'p0' }])] }), URL, HEAD)).toBe(null)+ })+ it('counts each reviewer once, over every review step passed at the head', () => {+ const two = step([check([{ passed: true, head: HEAD }])], { step: 'Security review 2', title: 'Security review 2' })+ two.checks[0]!.verdicts![0]!.by = 'agent:other'+ expect(headReads(task({ steps: [...task().steps, two] }), URL, HEAD)).toBe(2)+ const same = step([check([{ passed: true, head: HEAD }])], { step: 'Security review 2', title: 'Security review 2' })+ expect(headReads(task({ steps: [...task().steps, same] }), URL, HEAD)).toBe(1)+ })+ it('never counts the task\'s own builders as reads: its assignee or an earlier attempt\'s agent', () => {+ // The review step is passed by agent:r0 (the step helper's checker): as the builder, its pass counts for nothing, so the+ // step has no pass at all and the pull request may not merge, however many other steps passed.+ expect(headReads(task({ builders: ['agent:r0'] }), URL, HEAD)).toBe(null)+ const two = step([check([{ passed: true, head: HEAD }])], { step: 'Security review 2', title: 'Security review 2' })+ two.checks[0]!.verdicts![0]!.by = 'agent:other'+ expect(headReads(task({ steps: [...task().steps, two], builders: ['agent:r0'] }), URL, HEAD)).toBe(null)+ expect(headReads(task({ steps: [...task().steps, two], builders: ['agent:someone-else'] }), URL, HEAD)).toBe(2)+ })+ it('never counts a builder\'s pass of a test step, but keeps the builder\'s own task checks', () => {+ const tested = step([check([{ passed: true, head: HEAD }])], { step: 'Test', title: 'Test' })+ tested.checks[0]!.verdicts![0]!.by = 'agent:builder'+ expect(headReads(task({ steps: [...task().steps, tested], builders: ['agent:builder'] }), URL, HEAD)).toBe(null)+ const own = task({ builders: ['agent:r0'] })+ own.steps[0]!.checks[0]!.verdicts![0]!.by = 'agent:reviewer'+ expect(headReads(own, URL, HEAD)).toBe(1)+ })+ it('ignores a cancelled step', () => {+ const t = task({ steps: [...task().steps, step([], { step: 'Test', assignment: { status: 'cancelled' } as Conversation['assignment'] })] })+ expect(headReads(t, URL, HEAD)).toBe(1)+ })+})++describe('eligible', () => {+ it('takes a ready pull request with its Yes at its head, green ci/required, mergeable, no hold', () => {+ expect(eligible(candidate(), 1, 1)).toEqual({ ok: true })+ expect(eligible(candidate(), 2, 2)).toEqual({ ok: true })+ })+ it.each([+ ['closed', { state: 'closed' as const }],+ ['draft', { draft: true }],+ ['base', { base: 'release' }],+ ['ci', { ciRequired: 'pending' as const }],+ ['ci', { ciRequired: 'failure' as const }],+ ['ci', { ciRequired: null }],+ ['mergeable', { mergeable: null }],+ ['conflict', { mergeable: false }],+ ['hold', { labels: ['Hold'] }],+ ])('refuses %s', (why, over) => {+ expect(eligible(candidate(over), 1, 1)).toEqual({ ok: false, why })+ })+ it('refuses one whose verdicts are not at its head', () => {+ expect(eligible(candidate(), null, 1)).toEqual({ ok: false, why: 'verdict' })+ })+ it('refuses one with fewer passed reads at its head than the review table asks', () => {+ expect(eligible(candidate(), 1, 2)).toEqual({ ok: false, why: 'reads' })+ })+})++describe('lanes and components', () => {+ it('sends docs and Markdown alone down the fast lane; scripts run CI and release, so they batch', () => {+ expect(laneOf(['docs/a.md', 'AGENTS.md', 'cli/README.md'])).toBe('fast')+ expect(laneOf(['docs/a.md', 'scripts/ci-plan.py'])).toBe('code')+ expect(laneOf(['docs/a.md', 'backend/src/a.ts'])).toBe('code')+ expect(laneOf([])).toBe('code')+ })+ it('names a pull request by the top folders it touches', () => {+ expect(componentOf(['backend/src/a.ts', 'backend/b.ts'])).toBe('backend')+ expect(componentOf(['desktop/lib/a.dart', 'backend/src/a.ts', 'AGENTS.md'])).toBe('backend+desktop+root')+ })+ it('splits a red batch by component, then in halves, and stops at one', () => {+ const m = (n: number, files: string[]) => ({ number: n, files })+ expect(splitRed([m(1, ['backend/a']), m(2, ['desktop/a']), m(3, ['backend/b'])]).map(g => g.map(x => x.number))).toEqual([[1, 3], [2]])+ expect(splitRed([m(1, ['cli/a']), m(2, ['cli/b']), m(3, ['cli/c']), m(4, ['cli/d'])]).map(g => g.map(x => x.number))).toEqual([[1, 2], [3, 4]])+ expect(splitRed([m(1, ['cli/a'])])).toEqual([])+ })+})++describe('requiredReads', () => {+ it('asks the default for ordinary paths and two for the security areas, failing closed', () => {+ expect(requiredReads(['backend/src/superTabs/cards.ts'])).toBe(1)+ expect(requiredReads(['backend/src/github/tokens.ts'])).toBe(2)+ expect(requiredReads(['backend/src/routes/auth.ts', 'docs/a.md'])).toBe(2)+ expect(requiredReads(['backend/src/superTabs/purge.ts'])).toBe(2)+ expect(requiredReads(['desktop/lib/super_tabs/buddy_guard.dart'])).toBe(2)+ })+ it('takes the reads from the rules record when it names the area, never fewer than the default', () => {+ const reviews = { defaultReads: 1, rows: [{ area: 'Tokens', reads: 3 }] }+ expect(requiredReads(['backend/src/github/tokens.ts'], reviews)).toBe(3)+ expect(requiredReads(['backend/src/superTabs/cards.ts'], { defaultReads: 2, rows: [] })).toBe(2)+ })+})++describe('config', () => {+ it('is off until a project switches it on, every 10 minutes', () => {+ expect(TRAIN_DEFAULTS).toEqual({ enabled: false, everyMinutes: 10 })+ })+})diff --git a/backend/src/superTabs/mergeTrain/plan.ts b/backend/src/superTabs/mergeTrain/plan.tsnew file mode 100644index 000000000..ca985e03b--- /dev/null+++ b/backend/src/superTabs/mergeTrain/plan.ts@@ -0,0 +1,140 @@+/**+ * What the merge train may merge, and how it groups pull requests (task #3402). Pure: the pass (train.ts) reads GitHub and the+ * Swarm and hands the answers here. Every unknown reads as "not yet": a pull request merged with too little evidence cannot+ * be taken back, and one that waits a pass costs ten minutes.+ */+import type { Check, CheckVerdict, Conversation } from '../model.js'+import { FAST_LANE, REVIEW_AREAS, SECURITY_READS, TRAIN_HOLD_LABELS } from './config.js'++/** A pull request as the train reads it from GitHub this pass. */+export interface TrainCandidate {+ url: string+ number: number+ head: string+ state: 'open' | 'closed'+ draft: boolean+ base: string+ /** False on a conflict; null while GitHub is still working it out. */+ mergeable: boolean | null+ labels: string[]+ files: string[]+ /** The head's ci/required check: null when it has none yet. */+ ciRequired: 'success' | 'failure' | 'pending' | null+}++/** The verdict fields task #3394 adds (checkVerdicts.ts there): the pull request and head it was given at, the head's patch+ * id, and where it stopped counting. Optional here so this reads verdicts written before them, which never count. */+type HeadVerdict = CheckVerdict & { pullRequest?: string; head?: string; patch?: string | null; stale?: unknown }+interface PullRequestHead { head: string; patch: string | null; at: number }++/** The parts of a task, and of its steps, the train reads. */+export interface TrainTask {+ checks: Check[]+ /** Each linked pull request's head and patch id as the PR watch last read them (task #3394). */+ pullRequestHeads?: Record<string, PullRequestHead>+ steps: Array<Pick<Conversation, 'step' | 'title' | 'checks' | 'archived' | 'assignment'>>+ /** Who built the task, as verdicts name checkers (`agent:ID`): its assignee and every earlier attempt's agent. Their verdicts+ * on its steps count for nothing: a builder is never its own review or test (review 1 of #3226). */+ builders?: string[]+}++const REVIEW_STEP = /review/i+const MIN_PREFIX = 7++/** Whether [verdict] counts at [url]'s current head [now]: given at that head (a 7+ character prefix of it, as #3394 reads+ * one), or at a head whose patch is the same. A verdict with no head never counts here, though old clients still count it:+ * merging needs the head it read. */+function countsAt(verdict: HeadVerdict, url: string, now: PullRequestHead): boolean {+ if (!verdict.head || verdict.stale || verdict.pullRequest !== url) return false+ if (verdict.head.length >= MIN_PREFIX && now.head.startsWith(verdict.head)) return true+ return !!verdict.patch && verdict.patch === now.patch+}++/** The checkers whose passes count on [check], or null when it has no pass that counts or a failure that does. */+function passers(check: Check, url: string, now: PullRequestHead, ignored: ReadonlySet<string> = new Set()): string[] | null {+ const counting = ((check.verdicts ?? []) as HeadVerdict[]).filter(v => !ignored.has(v.by) && countsAt(v, url, now))+ if (!counting.length || counting.some(v => !v.passed)) return null+ return counting.map(v => v.by)+}++/**+ * How many independent reads [task]'s pull request [url] has at [head], the head GitHub shows now: the reviewers whose review+ * steps passed there, each once. Null when it may not merge whatever the count: the PR watch has not seen this head yet, no+ * review step passed, or the task's own checks or another step (a test) did not pass at this head. A cancelled step does not+ * count either way; any other step must be done.+ */+export function headReads(task: TrainTask, url: string, head: string): number | null {+ const now = task.pullRequestHeads?.[url]+ if (!now || now.head !== head) return null+ if (!task.checks.every(check => passers(check, url, now))) return null+ const readers = new Set<string>(), builders = new Set(task.builders ?? [])+ let reviewed = false+ for (const step of task.steps) {+ const status = step.assignment?.status+ if (status === 'cancelled') continue+ if (status !== 'done' || !step.checks.length) return null+ const found = step.checks.map(check => passers(check, url, now, builders))+ if (found.some(list => !list)) return null+ if (REVIEW_STEP.test(step.step ?? step.title)) {+ reviewed = true+ for (const list of found) for (const by of list!) readers.add(by)+ }+ }+ return reviewed ? readers.size : null+}++/** The review table's part the train reads (task #3393 rules.reviews). */+export interface ReviewTable { defaultReads: number; rows: Array<{ area: string; reads: number }> }++/** The reads [files] need: the most any area they touch asks, never fewer than the default. Without a table, each security+ * area needs [SECURITY_READS]. */+export function requiredReads(files: readonly string[], reviews?: ReviewTable): number {+ let reads = reviews?.defaultReads ?? 1+ for (const { area, paths } of REVIEW_AREAS) {+ if (!files.some(file => paths.test(file))) continue+ const row = reviews?.rows.find(r => r.area.toLowerCase() === area.toLowerCase())+ reads = Math.max(reads, reviews ? row?.reads ?? reviews.defaultReads : SECURITY_READS)+ }+ return reads+}++export type Ineligible = 'closed' | 'draft' | 'base' | 'hold' | 'ci' | 'mergeable' | 'conflict' | 'verdict' | 'reads'++/** Whether [candidate] may join a batch, given its [reads] at its head (headReads) and the reads its files need. */+export function eligible(candidate: TrainCandidate, reads: number | null, required: number): { ok: true } | { ok: false; why: Ineligible } {+ const no = (why: Ineligible) => ({ ok: false as const, why })+ if (candidate.state !== 'open') return no('closed')+ if (candidate.draft) return no('draft')+ if (candidate.base !== 'main') return no('base')+ if (candidate.labels.some(label => TRAIN_HOLD_LABELS.includes(label.toLowerCase()))) return no('hold')+ if (candidate.ciRequired !== 'success') return no('ci')+ if (candidate.mergeable === null) return no('mergeable')+ if (candidate.mergeable === false) return no('conflict')+ if (reads === null) return no('verdict')+ if (reads < required) return no('reads')+ return { ok: true }+}++/** `fast` when every file only documents or scripts (FAST_LANE): such a pull request merges on its own green CI. */+export function laneOf(files: readonly string[]): 'fast' | 'code' {+ return files.length && files.every(file => FAST_LANE.some(lane => lane.test(file))) ? 'fast' : 'code'+}++/** The top folders [files] touch, `root` for files at the top, as one name: CI runs per component. */+export function componentOf(files: readonly string[]): string {+ return [...new Set(files.map(file => file.includes('/') ? file.slice(0, file.indexOf('/')) : 'root'))].sort().join('+')+}++/** How a red batch of [members] runs again: one batch per component, or the two halves of one component; a single member+ * runs no more (it failed on its own). */+export function splitRed<T extends { files: readonly string[] }>(members: readonly T[]): T[][] {+ if (members.length <= 1) return []+ const groups = new Map<string, T[]>()+ for (const member of members) {+ const key = componentOf(member.files)+ groups.set(key, [...groups.get(key) ?? [], member])+ }+ if (groups.size > 1) return [...groups.values()]+ const half = Math.ceil(members.length / 2)+ return [members.slice(0, half), members.slice(half)]+}diff --git a/backend/src/superTabs/mergeTrain/run.test.ts b/backend/src/superTabs/mergeTrain/run.test.tsnew file mode 100644index 000000000..0d16e5249--- /dev/null+++ b/backend/src/superTabs/mergeTrain/run.test.ts@@ -0,0 +1,49 @@+import { describe, expect, it } from 'vitest'+import type { TrainProject } from '../store.js'+import { runMergeTrain, type MergeTrainDeps, type TrainMemories } from './run.js'++const project: TrainProject = { tabId: 't1', projectId: 'p1', ownerId: 'o1', autonomousEnv: 'prod', repositoryUrl: 'https://github.com/acme/app', pulls: [] }++function deps(over: Partial<MergeTrainDeps> = {}) {+ const calls: string[] = []+ const answer = (path: string) => {+ if (path.endsWith('/git/ref/heads/main')) return { status: 200, body: { ref: 'refs/heads/main', object: { type: 'commit', sha: 'c'.repeat(40) } } }+ if (path.includes('/pulls?')) return { status: 200, body: [] }+ return { status: 404, body: {} }+ }+ const value: MergeTrainDeps = {+ store: { trainProjects: async () => [project], trainMerged: async () => {}, trainTell: async () => true },+ app: {+ installation: async () => { calls.push('installation'); return 7 },+ createToken: async () => { calls.push('token'); return { token: 'ghs_x', expiresAt: '2030-01-01T00:00:00Z' } },+ installationCall: async (_token, method, path) => { calls.push(`${method} ${path}`); return answer(path) },+ revoke: async () => { calls.push('revoke') },+ },+ approved: async () => true,+ ...over,+ }+ return { value, calls }+}++describe('running the merge train', () => {+ it('is off unless the project switched it on: nothing read from GitHub', async () => {+ const { value, calls } = deps()+ expect(await runMergeTrain(value, new Map(), 1_000_000)).toBe(0)+ expect(calls).toEqual([])+ })++ it('runs a switched-on project once per interval, with one token revoked after', async () => {+ const { value, calls } = deps({ rules: async () => ({ enabled: true, everyMinutes: 10 }) })+ const memories: TrainMemories = new Map()+ expect(await runMergeTrain(value, memories, 1_000_000)).toBe(1)+ expect(calls.filter(c => c === 'token' || c === 'revoke')).toEqual(['token', 'revoke'])+ expect(await runMergeTrain(value, memories, 1_000_000 + 9 * 60_000)).toBe(0)+ expect(await runMergeTrain(value, memories, 1_000_000 + 10 * 60_000)).toBe(1)+ })++ it('skips a repository not approved for the project', async () => {+ const { value, calls } = deps({ rules: async () => ({ enabled: true, everyMinutes: 10 }), approved: async () => false })+ expect(await runMergeTrain(value, new Map(), 1_000_000)).toBe(0)+ expect(calls).toEqual([])+ })+})diff --git a/backend/src/superTabs/mergeTrain/run.ts b/backend/src/superTabs/mergeTrain/run.tsnew file mode 100644index 000000000..9c8eeb84f--- /dev/null+++ b/backend/src/superTabs/mergeTrain/run.ts@@ -0,0 +1,86 @@+/**+ * Runs the merge train (train.ts) in the singleton worker: every minute it looks at the projects with tasks that link pull+ * requests, and runs a pass for each whose train is switched on and whose interval has passed. The switch and the interval+ * are the project's rules (task #3393); until that record lands they are [TRAIN_DEFAULTS], off.+ *+ * A project runs only where its repository may get the app's tokens at all: the app installed there, and approved for the+ * project wherever approval is asked (github/approvals.ts), as an agent's token would be.+ */+import type { GitHubApp } from '../../github/app.js'+import { githubRepository } from '../../github/repository.js'+import { repositoryTrain } from '../../github/train.js'+import { logger } from '../../utils/logger.js'+import type { SuperTabStore, TrainProject } from '../store.js'+import { TRAIN_DEFAULTS } from './config.js'+import type { ReviewTable } from './plan.js'+import { newTrainMemory, trainPass, type TrainMemory } from './train.js'++export interface ProjectTrainRules { enabled: boolean; everyMinutes: number; reviews?: ReviewTable }+export type TrainRulesReader = (tabId: string, projectId: string) => Promise<ProjectTrainRules>+/** Until the project rules record lands (task #3393): the defaults, off for every project. */+export const defaultTrainRules: TrainRulesReader = async () => ({ ...TRAIN_DEFAULTS })++export interface MergeTrainDeps {+ store: Pick<SuperTabStore, 'trainProjects' | 'trainMerged' | 'trainTell'>+ app: Pick<GitHubApp, 'installation' | 'createToken' | 'installationCall' | 'revoke'>+ /** Whether [repository] may get the app's tokens for this project. */+ approved: (project: TrainProject, repository: string) => Promise<boolean>+ rules?: TrainRulesReader+}++/** What a worker keeps per project between runs: its train's memory and when it last ran. */+export type TrainMemories = Map<string, { memory: TrainMemory; ranAt: number }>++/** One run over every project. The passes that ran. */+export async function runMergeTrain(deps: MergeTrainDeps, memories: TrainMemories, now: number): Promise<number> {+ const rules = deps.rules ?? defaultTrainRules+ let ran = 0+ for (const project of await deps.store.trainProjects(now)) {+ const key = `${project.tabId}:${project.projectId}`+ try {+ const set = await rules(project.tabId, project.projectId)+ // The kill switch: off reads nothing from GitHub and writes nothing.+ if (!set.enabled) continue+ const kept = memories.get(key) ?? { memory: newTrainMemory(), ranAt: 0 }+ memories.set(key, kept)+ if (now - kept.ranAt < set.everyMinutes * 60_000) continue+ const repository = githubRepository(project.repositoryUrl)+ if (!repository || !await deps.approved(project, repository.fullName.toLowerCase())) continue+ const github = await repositoryTrain(deps.app, repository)+ if (!github) continue+ kept.ranAt = now+ try {+ const line = await trainPass({ projectId: project.projectId, github, memory: kept.memory, now, rules: set, swarm: {+ pulls: async () => project.pulls,+ merged: (taskId, url, mergedAt) => deps.store.trainMerged(project, taskId, url, mergedAt),+ tell: async (taskId, _url, tellKey, text) => { await deps.store.trainTell(project.tabId, taskId, tellKey, text) },+ } })+ ran+++ // One line a pass that did something or could not read (ENGINEERING.md 6): counts only, never a link or a title.+ if ('off' in line) continue+ if (line.unrecorded) logger.error('[merge-train] merges not recorded on their tasks: record them by hand with conversation.merged', { tabId: project.tabId, projectId: project.projectId, ...line })+ else if (line.unreadable || line.refused) logger.warn('[merge-train] pass', { tabId: project.tabId, projectId: project.projectId, ...line })+ else if (line.built || line.merged || line.closed || line.split) logger.info('[merge-train] pass', { tabId: project.tabId, projectId: project.projectId, ...line })+ } finally { await github.done() }+ } catch (error) {+ logger.warn('[merge-train] project skipped', { tabId: project.tabId, projectId: project.projectId, error: error instanceof Error ? error.message : String(error) })+ }+ }+ return ran+}++/** Runs [runMergeTrain] every minute in the singleton worker, one run at a time. */+export function startMergeTrain(deps: MergeTrainDeps, everyMs = 60_000): () => void {+ const memories: TrainMemories = new Map()+ let running = false+ const run = () => {+ if (running) return+ running = true+ void runMergeTrain(deps, memories, Date.now())+ .catch(error => logger.warn('[merge-train] failed', { error: error instanceof Error ? error.message : String(error) }))+ .finally(() => { running = false })+ }+ const timer = setInterval(run, everyMs)+ timer.unref()+ return () => clearInterval(timer)+}diff --git a/backend/src/superTabs/mergeTrain/train.test.ts b/backend/src/superTabs/mergeTrain/train.test.tsnew file mode 100644index 000000000..b430cc6c5--- /dev/null+++ b/backend/src/superTabs/mergeTrain/train.test.ts@@ -0,0 +1,412 @@+import { describe, expect, it } from 'vitest'+import type { Check, Conversation } from '../model.js'+import { fakeTrainGitHub, type FakePull } from './fakeTrainGitHub.js'+import type { TrainTask } from './plan.js'+import { newTrainMemory, trainPass, type TrainSwarm, type TrainTaskPull } from './train.js'++const MINUTE = 60_000+const ON = { enabled: true }++/** A task whose one review step passed at [head] of [url]. */+function approvedTask(url: string, head: string, reviewers = ['agent:reviewer']): TrainTask {+ const check = (by: string): Check => ({ id: `c-${by}`, description: 'Review', independent: true, evidence: 'ok', passedBy: by,+ verdicts: [{ by, passed: true, evidence: 'ok', at: 1, pullRequest: url, head, patch: `patch-${head}` }] as unknown as Check['verdicts'] })+ return {+ checks: [],+ pullRequestHeads: { [url]: { head, patch: `patch-${head}`, at: 1 } },+ steps: reviewers.map(by => ({ step: 'Review', title: 'Review', archived: false, checks: [check(by)], assignment: { status: 'done' } as Conversation['assignment'] })),+ }+}++function fakeSwarm() {+ const tasks = new Map<string, TrainTaskPull>()+ const merged: Array<{ taskId: string; url: string; mergedAt: number }> = []+ const told: Array<{ taskId: string; url: string; key: string; text: string }> = []+ const swarm: TrainSwarm = {+ async pulls() { return [...tasks.values()].map(t => ({ ...t })) },+ async merged(taskId, url, mergedAt) { merged.push({ taskId, url, mergedAt }) },+ async tell(taskId, url, key, text) { if (!told.some(t => t.taskId === taskId && t.key === key)) told.push({ taskId, url, key, text }) },+ }+ /** The task of [pull], approved at its current head. */+ const approve = (pull: FakePull, reviewers?: string[]) => {+ tasks.set(`task-${pull.number}`, { taskId: `task-${pull.number}`, url: pull.url, task: approvedTask(pull.url, pull.head, reviewers) })+ }+ return { swarm, tasks, merged, told, approve }+}++const setup = () => {+ const repo = fakeTrainGitHub(), swarm = fakeSwarm(), memory = newTrainMemory()+ let now = Date.UTC(2026, 10, 5, 15)+ const pass = (rules: { enabled: boolean } = ON) => trainPass({ projectId: 'p1', github: repo.github, swarm: swarm.swarm, memory, now: (now += 10 * MINUTE), rules })+ return { repo, swarm, memory, pass }+}++describe('the merge train builds batches', () => {+ it('batches eligible code pull requests on a branch from main, listing each member at its head', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts']), b = repo.addPull(8, ['desktop/lib/b.dart'])+ swarm.approve(a); swarm.approve(b)+ const main = repo.state.main+ await pass()+ const [batch] = repo.batches()+ expect(repo.batches()).toHaveLength(1)+ expect(batch!.headRef.startsWith('harness-train/p1/')).toBe(true)+ expect(repo.state.contents.get(batch!.head)).toEqual([a.head, b.head])+ expect(batch!.body).toContain(`#7 at ${a.head.slice(0, 12)}`)+ expect(batch!.body).toContain(`#8 at ${b.head.slice(0, 12)}`)+ expect(batch!.body).toContain(main.slice(0, 12))+ expect(swarm.merged).toEqual([])+ })++ it('keeps two pull requests that change the same file in separate batches, so no combination goes unread', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts']), b = repo.addPull(8, ['backend/src/a.ts', 'backend/src/b.ts']), c = repo.addPull(9, ['cli/src/c.ts'])+ swarm.approve(a); swarm.approve(b); swarm.approve(c)+ await pass()+ expect(repo.batches().map(p => repo.state.contents.get(p.head))).toEqual([[a.head, c.head]])+ repo.state.ci.set(repo.batches()[0]!.head, 'success')+ await pass()+ expect(repo.batches().map(p => repo.state.contents.get(p.head))).toEqual([[b.head]])+ })++ it('never batches a pull request whose verdict is not at its head', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts'])+ swarm.approve(a)+ repo.push(7)+ await pass()+ expect(repo.batches()).toEqual([])+ })++ it('waits for the reads the review table asks: two on a security path', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/github/tokens.ts'])+ swarm.approve(a)+ await pass()+ expect(repo.batches()).toEqual([])+ expect(swarm.told.map(t => t.key)).toEqual([`train-reads:${a.head}`])+ swarm.approve(a, ['agent:one', 'agent:two'])+ await pass()+ expect(repo.batches()).toHaveLength(1)+ })++ it('drops a conflicting pull request and tells its owner to merge main once, once per head', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts']), b = repo.addPull(8, ['backend/src/b.ts'])+ swarm.approve(a); swarm.approve(b)+ repo.state.conflicts.add(b.head)+ await pass()+ expect(repo.state.contents.get(repo.batches()[0]!.head)).toEqual([a.head])+ expect(swarm.told).toHaveLength(1)+ expect(swarm.told[0]).toMatchObject({ taskId: 'task-8', key: `train-conflict:${b.head}` })+ expect(swarm.told[0]!.text).toMatch(/merge main into its branch once/i)+ })++ it('tells the owner of a pull request GitHub already reads as conflicting', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts'], { mergeable: false })+ swarm.approve(a)+ await pass()+ await pass()+ expect(repo.batches()).toEqual([])+ expect(swarm.told.map(t => t.key)).toEqual([`train-conflict:${a.head}`])+ })++ it('merges a docs pull request on its own green CI, with no batch', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['docs/a.md', 'cli/README.md'])+ swarm.approve(a)+ await pass()+ expect(repo.batches()).toEqual([])+ expect(repo.state.squashes.map(s => s.number)).toEqual([7])+ expect(swarm.merged.map(m => [m.taskId, m.url])).toEqual([['task-7', a.url]])+ })++ it('holds a fast-lane pull request while a code batch is in CI, so main does not move under it', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts']))+ await pass()+ swarm.approve(repo.addPull(8, ['docs/a.md']))+ await pass()+ expect(repo.state.squashes).toEqual([])+ })+})++describe('the merge train finishes batches', () => {+ it('squash-merges a green batch at its tip, closes the originals with a link and records each merge', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts']), b = repo.addPull(8, ['desktop/lib/b.dart'])+ swarm.approve(a); swarm.approve(b)+ await pass()+ const batch = repo.batches()[0]!+ repo.state.ci.set(batch.head, 'success')+ await pass()+ expect(repo.state.squashes).toEqual([expect.objectContaining({ number: batch.number })])+ // The form main's batches use, which the release watch (#3405) reads: the originals before the batch's own number.+ expect(repo.state.squashes[0]!.title).toBe(`Merge batch 11-05 train-1510: #7 #8 (#${batch.number})`)+ const commit = repo.state.squashes[0]!.sha+ expect(repo.state.pulls.get(7)!.state).toBe('closed')+ expect(repo.state.pulls.get(8)!.state).toBe('closed')+ for (const n of [7, 8]) {+ const said = repo.state.comments.find(c => c.number === n)!.text+ expect(said).toContain(batch.url)+ expect(said).toContain(commit)+ }+ expect(swarm.merged.map(m => [m.taskId, m.url])).toEqual([['task-7', a.url], ['task-8', b.url]])+ expect(repo.state.branches.has(batch.headRef)).toBe(false)+ })++ it('titles a batch of one in the same form', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts']))+ await pass()+ const batch = repo.batches()[0]!+ repo.state.ci.set(batch.head, 'success')+ await pass()+ expect(repo.state.squashes[0]!.title).toBe(`Merge batch 11-05 train-1510: #7 (#${batch.number})`)+ })++ it('records every member\'s merge even when GitHub fails to take a comment after the squash', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts'])); swarm.approve(repo.addPull(8, ['backend/src/b.ts']))+ await pass()+ repo.state.ci.set(repo.batches()[0]!.head, 'success')+ repo.state.failing.add('comment')+ await pass()+ expect(swarm.merged.map(m => m.taskId)).toEqual(['task-7', 'task-8'])+ })++ it('never hands the batch pull request to the Swarm, so no task links it or reads it as Team-written', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts']))+ await pass()+ const batch = repo.batches()[0]!+ repo.state.ci.set(batch.head, 'success')+ await pass()+ const said = JSON.stringify([swarm.merged, swarm.told])+ expect(said).not.toContain(batch.url)+ expect(said).not.toContain(`#${batch.number}`)+ })++ it('splits a red batch by component and runs each part again', async () => {+ const { repo, swarm, pass } = setup()+ for (const [n, files] of [[7, ['backend/src/a.ts']], [8, ['desktop/lib/b.dart']], [9, ['backend/src/c.ts']]] as const) swarm.approve(repo.addPull(n, [...files]))+ await pass()+ const first = repo.batches()[0]!+ repo.state.ci.set(first.head, 'failure')+ await pass()+ expect(repo.state.pulls.get(first.number)!.state).toBe('closed')+ const parts = repo.batches().map(p => repo.state.contents.get(p.head)!.map(h => [...repo.state.pulls.values()].find(x => x.head === h)!.number))+ expect(parts).toEqual([[7, 9], [8]])+ expect(repo.state.squashes).toEqual([])+ })++ it('sends a pull request that fails alone back to its owner, and batches it again only at a new head', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts'])+ swarm.approve(a)+ await pass()+ repo.state.ci.set(repo.batches()[0]!.head, 'failure')+ await pass()+ expect(swarm.told).toEqual([expect.objectContaining({ taskId: 'task-7', key: `train-red:${a.head}` })])+ expect(swarm.told[0]!.text).toMatch(/CI failed/)+ await pass()+ expect(repo.batches()).toEqual([])+ const head = repo.push(7)+ swarm.approve(repo.state.pulls.get(7)!)+ await pass()+ expect(repo.state.contents.get(repo.batches()[0]!.head)).toEqual([head])+ })++ it('rebuilds from the new main when main moved, a person\'s hand merge included', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts'])+ swarm.approve(a)+ await pass()+ const first = repo.batches()[0]!+ repo.state.main = 'f'.repeat(40)+ repo.state.ci.set(first.head, 'success')+ await pass()+ expect(repo.state.squashes).toEqual([])+ expect(repo.state.pulls.get(first.number)!.state).toBe('closed')+ const [second] = repo.batches()+ expect(second!.body).toContain('f'.repeat(12))+ })++ it('never merges a member pushed after its batch went green: the heads are read again first', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts']), b = repo.addPull(8, ['backend/src/b.ts'])+ swarm.approve(a); swarm.approve(b)+ await pass()+ const first = repo.batches()[0]!+ repo.state.ci.set(first.head, 'success')+ repo.push(8)+ await pass()+ expect(repo.state.squashes).toEqual([])+ expect(repo.state.contents.get(repo.batches()[0]!.head)).toEqual([a.head])+ })++ it('never merges a member whose verdict stopped counting after the batch was built', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts'])+ swarm.approve(a)+ await pass()+ repo.state.ci.set(repo.batches()[0]!.head, 'success')+ swarm.tasks.get('task-7')!.task.steps[0]!.assignment = { status: 'working' } as Conversation['assignment']+ await pass()+ expect(repo.state.squashes).toEqual([])+ })++ it('closes a batch someone else pushed to, or one it did not build (a restart), without merging it', async () => {+ const { repo, swarm, pass, memory } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts']))+ await pass()+ const first = repo.batches()[0]!+ first.head = 'e'.repeat(40)+ repo.state.ci.set(first.head, 'success')+ await pass()+ expect(repo.state.squashes).toEqual([])+ expect(repo.state.pulls.get(first.number)!.state).toBe('closed')+ const second = repo.batches()[0]!+ memory.batches.clear()+ repo.state.ci.set(second.head, 'success')+ await pass()+ expect(repo.state.squashes).toEqual([])+ expect(repo.state.pulls.get(second.number)!.state).toBe('closed')+ })++ it('never touches a fork\'s pull request named like a live batch', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts']))+ await pass()+ const batch = repo.batches()[0]!+ repo.addPull(50, ['README.md'], { headRef: batch.headRef, headRepository: 'outsider/app' })+ const writes = repo.state.writes.length+ await pass()+ expect(repo.state.writes.length).toBe(writes)+ expect(repo.state.pulls.get(50)!.state).toBe('open')+ expect(repo.state.branches.has(batch.headRef)).toBe(true)+ })++ it('forgets a batch someone closed, and still builds the next one', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts']))+ await pass()+ const first = repo.batches()[0]!+ first.state = 'closed'+ swarm.approve(repo.addPull(8, ['backend/src/b.ts']))+ await pass()+ expect(repo.batches()).toHaveLength(1)+ expect(repo.batches()[0]!.number).not.toBe(first.number)+ })++ it('closes a batch GitHub refuses to merge, tells each Engineer why, and leaves those heads out', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts'])+ swarm.approve(a)+ await pass()+ const batch = repo.batches()[0]!+ repo.state.ci.set(batch.head, 'success')+ repo.state.squashRefusal = 'At least 1 approving review is required by reviewers with write access.'+ await pass()+ expect(repo.state.pulls.get(batch.number)!.state).toBe('closed')+ expect(swarm.told).toEqual([expect.objectContaining({ taskId: 'task-7', key: `train-refused:${a.head}` })])+ expect(swarm.told[0]!.text).toContain('At least 1 approving review is required')+ await pass()+ expect(repo.batches()).toEqual([])+ })++ it('leaves out a pull request that changes CI workflows, which its token cannot merge, with a line to its task', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['.github/workflows/ci.yml', 'scripts/ci-plan.py'])+ swarm.approve(a)+ await pass()+ expect(repo.batches()).toEqual([])+ expect(repo.state.squashes).toEqual([])+ expect(swarm.told.map(t => t.key)).toEqual([`train-workflows:${a.head}`])+ })++ it('records the other members and closes every original when one record fails after the squash', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts'])); swarm.approve(repo.addPull(8, ['backend/src/b.ts']))+ await pass()+ repo.state.ci.set(repo.batches()[0]!.head, 'success')+ const merged = swarm.swarm.merged+ swarm.swarm.merged = async (taskId, url, at) => { if (taskId === 'task-7') throw new Error('database down'); return merged(taskId, url, at) }+ await pass()+ expect(swarm.merged.map(m => m.taskId)).toEqual(['task-8'])+ expect(repo.state.pulls.get(7)!.state).toBe('closed')+ expect(repo.state.pulls.get(8)!.state).toBe('closed')+ })++ it('drops a member whose head is already in main', async () => {+ const { repo, swarm, pass } = setup()+ const a = repo.addPull(7, ['backend/src/a.ts']), b = repo.addPull(8, ['backend/src/b.ts'])+ swarm.approve(a); swarm.approve(b)+ repo.state.inMain.add(a.head)+ await pass()+ expect(repo.state.contents.get(repo.batches()[0]!.head)).toEqual([b.head])+ expect(swarm.told).toEqual([])+ })++ it('never builds on a train branch someone pushed to mid-build: no batch opened, the branch removed', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts'])); swarm.approve(repo.addPull(8, ['backend/src/b.ts']))+ let merges = 0+ repo.state.beforeMerge = branch => { if (++merges === 2) repo.state.branches.set(branch, 'e'.repeat(40)) }+ await pass()+ expect(repo.batches()).toEqual([])+ expect([...repo.state.branches.keys()].filter(b => b.startsWith('harness-train/'))).toEqual([])+ expect(repo.state.squashes).toEqual([])+ })++ it('closes a batch whose pull request opened at another head than the tip it built', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts']))+ const openPull = repo.github.openPull+ repo.github.openPull = async (branch, title, body) => { repo.state.branches.set(branch, 'e'.repeat(40)); return openPull(branch, title, body) }+ await pass()+ expect(repo.batches()).toEqual([])+ expect(repo.state.squashes).toEqual([])+ })++ it('stops with the kill switch: no read, no write, an open batch left as it is', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts']))+ await pass()+ const batch = repo.batches()[0]!+ repo.state.ci.set(batch.head, 'success')+ const before = { reads: repo.state.reads.length, writes: repo.state.writes.length }+ expect(await pass({ enabled: false })).toEqual({ off: true })+ expect({ reads: repo.state.reads.length, writes: repo.state.writes.length }).toEqual(before)+ expect(repo.batches()).toEqual([batch])+ })++ it('fails closed: a read GitHub fails writes nothing for that batch', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts']))+ await pass()+ repo.state.ci.set(repo.batches()[0]!.head, 'success')+ const writes = repo.state.writes.length+ repo.state.failing.add('ciRequired')+ const line = await pass()+ expect(repo.state.writes.length).toBe(writes)+ expect(line).toMatchObject({ unreadable: expect.any(Number) })+ repo.state.failing.clear()+ repo.state.failing.add('mainHead')+ await pass()+ expect(repo.state.writes.length).toBe(writes)+ })++ it('waits on a batch still in CI, and rebuilds one stuck past its time', async () => {+ const { repo, swarm, pass } = setup()+ swarm.approve(repo.addPull(7, ['backend/src/a.ts']))+ await pass()+ const first = repo.batches()[0]!+ await pass()+ expect(repo.batches()).toEqual([first])+ for (let i = 0; i < 9; i++) await pass()+ expect(repo.state.pulls.get(first.number)!.state).toBe('closed')+ expect(repo.batches()).toHaveLength(1)+ })+})diff --git a/backend/src/superTabs/mergeTrain/train.ts b/backend/src/superTabs/mergeTrain/train.tsnew file mode 100644index 000000000..eb03832cf--- /dev/null+++ b/backend/src/superTabs/mergeTrain/train.ts@@ -0,0 +1,263 @@+/**+ * The merge train (task #3402, anh Dee's Swarm redesign, 2026-11-05): one pass per project merges what passed, in batches,+ * through the Harness GitHub App. docs/plans/2026-11-05-merge-train-plan.md.+ *+ * A pass first finishes the batches it has open: one green at its tip, with main and every member's head read again and still+ * eligible, is squash-merged at that tip; its originals are closed with a link and their merges recorded on their tasks. A red+ * one splits by component (a member red on its own goes back to its owner); one built on an older main, changed by anyone+ * else, not built by this worker (a restart) or stuck in CI is closed and built again. Then, with no batch open, docs and+ * scripts merge on their own green CI and the rest go into a new batch.+ *+ * The batch pull request is never handed to the Swarm: no task links it, so no push-origin read of a task ever sees the+ * bot's branch (pushOrigin.ts). Its tip is the one this worker made, held in memory: a branch someone else pushed to is never+ * merged, as its tip no longer matches.+ */+import { TrainReadError, type TrainGitHub, type TrainPull } from '../../github/train.js'+import { NOT_MERGEABLE_BY_TOKEN, TRAIN_BRANCH_PREFIX, TRAIN_CI_TIMEOUT_MS, TRAIN_MAX_BATCH } from './config.js'+import { eligible, headReads, laneOf, requiredReads, splitRed, type Ineligible, type ReviewTable, type TrainTask } from './plan.js'++/** A task's linked pull request, as the Swarm holds it: what headReads reads. */+export interface TrainTaskPull { taskId: string; url: string; task: TrainTask }++/** What the train asks of the Swarm. */+export interface TrainSwarm {+ /** The project's open tasks and the pull requests each links. */+ pulls(): Promise<TrainTaskPull[]>+ /** Records [url]'s merge on task [taskId], as conversation.merged does. */+ merged(taskId: string, url: string, mergedAt: number): Promise<void>+ /** Tells task [taskId]'s Engineer [text], once per [key]. */+ tell(taskId: string, url: string, key: string, text: string): Promise<void>+}++interface Member { number: number; url: string; head: string; title: string; files: string[]; taskId: string }+interface Batch { number: number; url: string; branch: string; tip: string; base: string; startedAt: number; members: Member[] }++/** What a worker remembers between passes, per project: its open batches, the heads that failed alone, and the parts of red+ * batches still to run. Lost on a restart, which only closes and rebuilds what was open. */+export interface TrainMemory { batches: Map<number, Batch>; failed: Set<string>; splits: string[][] }+export const newTrainMemory = (): TrainMemory => ({ batches: new Map(), failed: new Set(), splits: [] })++export interface TrainRules { enabled: boolean; reviews?: ReviewTable }+export type TrainPassLine = { off: true } | { candidates: number; unreadable: number; built: number; merged: number; split: number; closed: number; refused: number; unrecorded: number }++const short = (sha: string) => sha.slice(0, 12)+/** A batch's label: the day and time it was built, in UTC ("11-05 train-1510"). */+const batchLabel = (at: number) => { const d = new Date(at), two = (n: number) => String(n).padStart(2, '0')+ return `${two(d.getUTCMonth() + 1)}-${two(d.getUTCDate())} train-${two(d.getUTCHours())}${two(d.getUTCMinutes())}` }+const PULL = /\/pull\/([1-9][0-9]*)$/++interface Read { member: Member; verdict: { ok: true } | { ok: false; why: Ineligible }; reads: number | null; required: number; lane: 'fast' | 'code' }++export async function trainPass(input: { projectId: string; github: TrainGitHub; swarm: TrainSwarm; memory: TrainMemory; now: number; rules: TrainRules }): Promise<TrainPassLine> {+ const { projectId, github, swarm, memory, now, rules } = input+ if (!rules.enabled) return { off: true }+ const line = { candidates: 0, unreadable: 0, built: 0, merged: 0, split: 0, closed: 0, refused: 0, unrecorded: 0 }+ const prefix = `${TRAIN_BRANCH_PREFIX}${projectId}/`+ let main: string, open: TrainPull[]+ try {+ main = await github.mainHead()+ open = await github.openPulls()+ } catch (error) {+ if (!(error instanceof TrainReadError)) throw error+ line.unreadable+++ return line+ }+ const tasks = await swarm.pulls()+ const taskOf = new Map<string, TrainTaskPull>()+ for (const linked of tasks) if (!taskOf.has(linked.url)) taskOf.set(linked.url, linked)++ /** [url] as it is now: GitHub's answer and the Swarm's verdicts. Null when it is not an open pull request of this repository. */+ const read = async (linked: TrainTaskPull): Promise<Read | null> => {+ const number = Number(PULL.exec(linked.url)?.[1])+ if (!number) return null+ const pull = await github.pull(number)+ if (pull.state !== 'open' || pull.url.toLowerCase() !== linked.url.toLowerCase() || pull.headRef.startsWith(TRAIN_BRANCH_PREFIX)) return null+ const files = await github.files(number), ciRequired = await github.ciRequired(pull.head)+ const reads = headReads(linked.task, linked.url, pull.head), required = requiredReads(files, rules.reviews)+ const verdict = eligible({ url: linked.url, number, head: pull.head, state: pull.state, draft: pull.draft, base: pull.base, mergeable: pull.mergeable,+ labels: pull.labels, files, ciRequired }, reads, required)+ return { member: { number, url: linked.url, head: pull.head, title: pull.title, files, taskId: linked.taskId }, verdict, reads, required, lane: laneOf(files) }+ }++ const closeBatch = async (number: number, branch: string, why: string) => {+ memory.batches.delete(number)+ await github.comment(number, `The merge train closed this batch: ${why}. Its pull requests go into the next batch.`)+ await github.close(number)+ await github.deleteBranch(branch)+ line.closed+++ }+ const tellRed = (member: Member) => swarm.tell(member.taskId, member.url, `train-red:${member.head}`,+ `CI failed for your pull request #${member.number} in the merge train, on its own with main (head ${member.head.slice(0, 7)}): fix it and push. The train takes it again at its new head. ${member.url}`)++ // Batches are pull requests from this repository's own train branches: a fork's pull request may take any branch name, and+ // closing it would delete the live batch's branch here (review 2 of #3226). A fork's is never touched.+ const ours = open.filter(p => p.headRef.startsWith(prefix) && p.headRepository === github.repository)+ // A batch no longer open (closed by a person, or its branch deleted) is forgotten, or the train would wait on it for good.+ for (const [number, batch] of memory.batches) {+ if (ours.some(p => p.number === number)) continue+ memory.batches.delete(number)+ line.closed+++ await github.deleteBranch(batch.branch).catch(error => { if (!(error instanceof TrainReadError)) throw error; line.unreadable++ })+ }++ // Finish the open batches.+ for (const pull of ours) {+ const batch = memory.batches.get(pull.number)+ try {+ if (!batch || batch.tip !== pull.head) {+ await closeBatch(pull.number, pull.headRef, batch ? 'its branch changed after the train built it' : 'the train did not build it on this server')+ continue+ }+ if (batch.base !== main) { await closeBatch(batch.number, batch.branch, 'main moved'); continue }+ const ci = await github.ciRequired(batch.tip)+ if (ci === 'pending' || ci === null) {+ if (now - batch.startedAt > TRAIN_CI_TIMEOUT_MS) await closeBatch(batch.number, batch.branch, 'its CI did not finish in time')+ continue+ }+ if (ci === 'failure') {+ await closeBatch(batch.number, batch.branch, 'ci/required failed')+ if (batch.members.length === 1) {+ memory.failed.add(`${batch.members[0]!.url}@${batch.members[0]!.head}`)+ await tellRed(batch.members[0]!)+ } else {+ memory.splits.push(...splitRed(batch.members).map(group => group.map(m => m.url)))+ line.split+++ }+ continue+ }+ // Green: read main and every member again, right before merging.+ if (await github.mainHead() !== batch.base) { await closeBatch(batch.number, batch.branch, 'main moved'); continue }+ let still = true+ for (const member of batch.members) {+ const linked = taskOf.get(member.url), current = linked ? await read(linked) : null+ if (!current || !current.verdict.ok || current.member.head !== member.head) { still = false; break }+ }+ if (!still) { await closeBatch(batch.number, batch.branch, 'a pull request in it changed or is no longer approved at its head'); continue }+ // The form main's batches use, which the release watch reads (task #3405): the originals before the batch's own number.+ const title = `Merge batch ${batchLabel(batch.startedAt)}: ${batch.members.map(m => `#${m.number}`).join(' ')} (#${batch.number})`+ let sha: string+ try {+ ({ sha } = await github.squash(batch.number, batch.tip, title, batch.members.map(m => `* ${m.title} (#${m.number})`).join('\n')))+ } catch (error) {+ // GitHub refused the merge itself (branch protection, a permission): trying again refuses again, so the batch closes and+ // its pull requests wait for a new head; each Engineer hears GitHub's reason (review 2 of #3226). No answer is retried.+ if (!(error instanceof TrainReadError) || ![403, 405, 409, 422].includes(error.status)) throw error+ await closeBatch(batch.number, batch.branch, 'GitHub refused to merge it')+ line.refused+++ for (const member of batch.members) {+ memory.failed.add(`${member.url}@${member.head}`)+ await swarm.tell(member.taskId, member.url, `train-refused:${member.head}`,+ `GitHub refused to merge your pull request #${member.number} in the merge train (head ${member.head.slice(0, 7)}): ${error.reason ?? `HTTP ${error.status}`}. Merge it by hand, or push a change that fixes this. ${member.url}`)+ }+ continue+ }+ memory.batches.delete(batch.number)+ main = sha+ // Merged now, whatever happens next: each member's merge is recorded on its own, then each original is closed.+ for (const member of batch.members) {+ try {+ await swarm.merged(member.taskId, member.url, now)+ line.merged+++ } catch { line.unrecorded++ }+ }+ for (const member of batch.members) {+ await github.comment(member.number, `Merged into main in ${sha} by the merge train, in batch ${batch.url}.`)+ .then(() => github.close(member.number))+ .catch(error => { if (!(error instanceof TrainReadError)) throw error; line.unreadable++ })+ }+ await github.deleteBranch(batch.branch).catch(error => { if (!(error instanceof TrainReadError)) throw error; line.unreadable++ })+ } catch (error) {+ if (!(error instanceof TrainReadError)) throw error+ line.unreadable+++ }+ }+ if (memory.batches.size) return line++ // Nothing open: read every candidate, merge the fast lane, and build the next batches.+ const reads: Read[] = []+ for (const linked of taskOf.values()) {+ try {+ const found = await read(linked)+ if (!found || memory.failed.has(`${found.member.url}@${found.member.head}`)) continue+ line.candidates+++ const { member, verdict } = found+ if (!verdict.ok && verdict.why === 'conflict') await tellConflict(swarm, member)+ else if (!verdict.ok && verdict.why === 'reads') {+ await swarm.tell(member.taskId, member.url, `train-reads:${member.head}`,+ `Your pull request #${member.number} needs ${found.required} passed reviews at its head (${member.head.slice(0, 7)}) before the merge train takes it; it has ${found.reads}. ${member.url}`)+ } else if (verdict.ok && member.files.some(file => NOT_MERGEABLE_BY_TOKEN.test(file))) {+ await swarm.tell(member.taskId, member.url, `train-workflows:${member.head}`,+ `Your pull request #${member.number} changes CI workflows, which the merge train cannot merge: merge it by hand. ${member.url}`)+ } else if (verdict.ok) reads.push(found)+ } catch (error) {+ if (!(error instanceof TrainReadError)) throw error+ line.unreadable+++ }+ }+ reads.sort((a, b) => a.member.number - b.member.number)+ try {+ for (const fast of reads.filter(r => r.lane === 'fast')) {+ const { member } = fast+ await github.squash(member.number, member.head, `${member.title} (#${member.number})`, `Merged by the merge train (fast lane).`)+ await swarm.merged(member.taskId, member.url, now)+ line.merged+++ }+ if (reads.some(r => r.lane === 'fast')) main = await github.mainHead()+ } catch (error) {+ if (!(error instanceof TrainReadError)) throw error+ line.unreadable+++ return line+ }+ const code = reads.filter(r => r.lane === 'code').map(r => r.member)+ const groups = (memory.splits.length ? memory.splits.map(urls => code.filter(m => urls.includes(m.url))) : [code])+ .map(disjoint).filter(group => group.length)+ memory.splits = []+ for (const [index, group] of groups.entries()) {+ const branch = `${prefix}${now}-${index}`+ try {+ await github.createBranch(branch, main)+ let tip = main+ const members: Member[] = []+ for (const member of group) {+ const merged = await github.mergeInto(branch, member.head, `Merge #${member.number} into the merge train's batch`, tip)+ if (merged === 'conflict') { await tellConflict(swarm, member); continue }+ // In main already (merged by hand meanwhile): nothing of it to batch.+ if (merged === 'already') continue+ tip = merged.sha+ members.push(member)+ }+ if (!members.length) { await github.deleteBranch(branch); continue }+ const body = [`The merge train's batch of ${members.length} pull request${members.length === 1 ? '' : 's'}, built from main at ${short(main)}.`, '',+ ...members.map(m => `- #${m.number} at ${short(m.head)}: ${m.title}`), '',+ 'It merges when ci/required is green here and every pull request is still at the head listed. Do not push to this branch.'].join('\n')+ const opened = await github.openPull(branch, `Merge train: ${members.map(m => `#${m.number}`).join(' ')}`, body)+ // Opened at another head than the tip built: someone pushed onto the branch. Never a batch (review 1 of #3226).+ if (opened.head !== tip) { await closeBatch(opened.number, branch, 'its branch changed while the train built it'); continue }+ memory.batches.set(opened.number, { number: opened.number, url: opened.url, branch, tip, base: main, startedAt: now, members })+ line.built+++ } catch (error) {+ if (!(error instanceof TrainReadError)) throw error+ line.unreadable+++ // Whatever it holds, a branch the train could not finish building is never left behind to be opened later.+ await github.deleteBranch(branch).catch(() => {})+ }+ }+ return line+}++/** The first members of [group], up to [TRAIN_MAX_BATCH], that share no file with an earlier one: two pull requests changing+ * one file would need a read of their combination, so the later one waits for the next batch and is tested on top of the+ * first once it merged (task #3401: a combination read only where files are shared). */+function disjoint(group: Member[]): Member[] {+ const taken = new Set<string>(), kept: Member[] = []+ for (const member of group) {+ if (kept.length === TRAIN_MAX_BATCH) break+ if (member.files.some(file => taken.has(file))) continue+ for (const file of member.files) taken.add(file)+ kept.push(member)+ }+ return kept+}++const tellConflict = (swarm: TrainSwarm, member: Member) => swarm.tell(member.taskId, member.url, `train-conflict:${member.head}`,+ `Your pull request #${member.number} conflicts with main or with another pull request in the merge train (head ${member.head.slice(0, 7)}): merge main into its branch once and push. The train takes it again at its new head. ${member.url}`)diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.tsindex 43c0ce5aa..cbd9302a3 100644--- a/backend/src/superTabs/model.ts+++ b/backend/src/superTabs/model.ts@@ -279,6 +279,8 @@ export interface Assignment {progressAt?: number/** While it needs a human: the person its agent asked (work.status with ask), whom its wait names (liveness.ts). */askedOf?: string+ /** While it is blocked or needs a human: why it waits (heldReason.ts). Absent on a hold from before reasons. */+ hold?: import('./heldReason.js').HeldReason/** When someone else's verdict found problems in a working hand-off of the older built-in skills, which then stops waiting* for its review (liveness.ts waitingForReview). Its next status clears it. */reviewFoundAt?: number@@ -437,6 +439,8 @@ export interface Conversation {queueRank?: number/** The day (YYYY-MM-DD) its work should not start before, a promise the PM marks with work.queue. */notBefore?: string+ /** Why its not-before date holds it (heldReason.ts), set with the date by work.queue. Absent on a hold from before reasons. */+ hold?: import('./heldReason.js').HeldReason/** How urgent its task is (taskPriority.ts), set by conversation.create and work.priority. Absent on a step, a chat and a task* from before priorities, which reads as P2. */priority?: import('./taskPriority.js').TaskPrioritydiff --git a/backend/src/superTabs/parts/light.test.ts b/backend/src/superTabs/parts/light.test.tsindex 4adcf1e40..99acb55e5 100644--- a/backend/src/superTabs/parts/light.test.ts+++ b/backend/src/superTabs/parts/light.test.ts@@ -8,7 +8,7 @@ import { FINISHED, GROUP_FIELDS } from './light.js'* 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, askedOf: 'p', reviewFoundAt: 1, changesRequestedAt: 1, toldEngineerAt: 1,+ execution: { machineId: 'm', harnessId: 'h', machineOwnerId: 'o' }, result: null, recordingProgress: { at: 1, revision: 1 }, leaseUntil: 1, progressAt: 1, askedOf: 'p', hold: { kind: 'requester' }, reviewFoundAt: 1, changesRequestedAt: 1, toldEngineerAt: 1,reopened: { at: 1, why: 'r' }, handoffs: 1, verdicts: [{ by: 'agent:r', passed: true, handoff: 1, review: 'g' }], lost: { reason: 'r', at: 1 },}const conversation: Required<Conversation> = {@@ -16,7 +16,7 @@ const conversation: Required<Conversation> = {task: { goal: '', changes: '', constraints: '', owns: [] }, reviewOf: 'r', teamWritten: true, teamWrittenBy: { kind: 'assigned' }, step: 'Review', reviewStamp: { assignmentId: 'w', handoff: 1 }, checks: [], assignment, lastMessageSequence: 0, lastMainSequence: 0, lastPersonSequence: 0, heardAt: 0, pullRequestUrls: [], pullRequestEvents: {}, cards: {},messageSeq: 0, reportSeq: 0, dormant: false, lastActivityAt: '', audience: { people: [] }, lostAttempt: { id: 'w', agentId: 'a' }, reactionSeq: 0,requesterId: 'p', ledger: {}, proposals: [], buddyName: 'Sparky', buddySessions: [], buddyDownTold: true, liveness: { state: 'quiet', why: 'silent', since: 1 }, leadAction: { kind: 'post', at: 1 },- stepUp: { attempt: 2, floor: 2, reason: 'r', at: 1, carry: '' }, queueRank: 1.5, notBefore: '2026-12-04', priority: 'P0',+ stepUp: { attempt: 2, floor: 2, reason: 'r', at: 1, carry: '' }, queueRank: 1.5, notBefore: '2026-12-04', hold: { kind: 'requester' }, priority: 'P0',}describe('the light conversation projection (parts/light.ts)', () => {diff --git a/backend/src/superTabs/parts/light.ts b/backend/src/superTabs/parts/light.tsindex 5b24b21a3..9ae56019d 100644--- a/backend/src/superTabs/parts/light.ts+++ b/backend/src/superTabs/parts/light.ts@@ -28,8 +28,8 @@ export const GROUP_FIELDS = {always: ['id', 'kind', 'projectId', 'leadId', 'agentIds', 'archived', 'audience', 'dormant', 'assignment.id', 'assignment.agentId', 'assignment.status','assignment.lost', 'reviewOf'],whenRunning: ['title', 'task.owns', 'assignment.execution', 'assignment.result'],- unread: ['number', 'brief', 'teamWritten', 'teamWrittenBy', 'step', 'reviewStamp', 'checks', 'lastMessageSequence', 'lastMainSequence', 'lastPersonSequence', 'heardAt', 'pullRequestUrls', 'pullRequestEvents', 'cards', 'messageSeq', 'reportSeq', 'lastActivityAt', 'lostAttempt', 'requesterId', 'ledger', 'reactionSeq', 'proposals', 'buddyName', 'buddySessions', 'buddyDownTold', 'liveness', 'leadAction', 'stepUp', 'queueRank', 'notBefore', 'priority',- 'assignment.configuration', 'assignment.recordingProgress', 'assignment.leaseUntil', 'assignment.progressAt', 'assignment.askedOf', 'assignment.reviewFoundAt', 'assignment.changesRequestedAt', 'assignment.toldEngineerAt',+ unread: ['number', 'brief', 'teamWritten', 'teamWrittenBy', 'step', 'reviewStamp', 'checks', 'lastMessageSequence', 'lastMainSequence', 'lastPersonSequence', 'heardAt', 'pullRequestUrls', 'pullRequestEvents', 'cards', 'messageSeq', 'reportSeq', 'lastActivityAt', 'lostAttempt', 'requesterId', 'ledger', 'reactionSeq', 'proposals', 'buddyName', 'buddySessions', 'buddyDownTold', 'liveness', 'leadAction', 'stepUp', 'queueRank', 'notBefore', 'hold', 'priority',+ 'assignment.configuration', 'assignment.recordingProgress', 'assignment.leaseUntil', 'assignment.progressAt', 'assignment.askedOf', 'assignment.hold', 'assignment.reviewFoundAt', 'assignment.changesRequestedAt', 'assignment.toldEngineerAt','assignment.reopened', 'assignment.handoffs', 'assignment.verdicts'],} as constconst LIGHT_GROUP = {diff --git a/backend/src/superTabs/parts/touches.test.ts b/backend/src/superTabs/parts/touches.test.tsindex b20edc906..05cfb4537 100644--- a/backend/src/superTabs/parts/touches.test.ts+++ b/backend/src/superTabs/parts/touches.test.ts@@ -3,6 +3,8 @@ import { applyCommand, type Command, type CommandContext } from '../commands.js'import { createSuperTab, type Actor } from '../model.js'import { touchesFor } from './touches.js'+const HOLD = { kind: 'person', personId: 'owner', defaultAt: '2026-11-06T02:00:00.000Z' } as const+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 }@@ -116,7 +118,7 @@ describe('the parts a command touches (design section 1.2, column T)', () => {it('makes an answer to waiting work meet a change to whom it waits on', () => {const f = swarm(), a = f.group('A')f.run({ type: 'conversation.requester', conversationId: a.id, personId: 'owner' })- f.run({ type: 'work.status', conversationId: a.id, assignmentId: a.assignmentId, status: 'needs_human', result: 'Flag?' }, f.agentActor(a.worker))+ f.run({ type: 'work.status', conversationId: a.id, assignmentId: a.assignmentId, status: 'needs_human', hold: HOLD, result: 'Flag?' }, f.agentActor(a.worker))const answer = f.run({ type: 'message.send', conversationId: a.id, text: 'Flag.', replyTo: null, recipientIds: [] }, f.agentActor(f.lead))expect(has(answer.touches, 'member', 'owner')).toBe(true)})diff --git a/backend/src/superTabs/policy.test.ts b/backend/src/superTabs/policy.test.tsindex 0ba3ace87..184efa276 100644--- a/backend/src/superTabs/policy.test.ts+++ b/backend/src/superTabs/policy.test.ts@@ -149,6 +149,48 @@ describe('reads and tests a change needs', () => {expect(globMatch('a/**/b.ts', 'a/x/y/c.ts')).toBe(false)})+ // Reviewers, after #3216: the linear matcher let `**/` end inside a name, so a folder pattern matched a name that only ends+ // with it. The regex it replaced, `(?:.*/)?`, ends only at a slash or matches nothing.+ it('ends a double star with a slash only at a folder boundary', () => {+ expect(globMatch('a/**/b', 'a/xb')).toBe(false)+ expect(globMatch('a/**/b', 'a/b')).toBe(true)+ expect(globMatch('a/**/b', 'a/x/b')).toBe(true)+ expect(globMatch('a/**/b', 'a/x/yb')).toBe(false)+ expect(globMatch('**/tests/**', 'latests/x.ts')).toBe(false)+ expect(globMatch('**/tests/**', 'pkg/latests/x.ts')).toBe(false)+ expect(globMatch('**/tests/**', 'tests/x.ts')).toBe(true)+ expect(globMatch('**/tests/**', 'pkg/tests/x.ts')).toBe(true)+ expect(globMatch('**/e2ee/**', 'mobile/lib/notee2ee/box.dart')).toBe(false)+ expect(globMatch('**/*auth*', 'backend/src/lib/ssoAuth.ts')).toBe(true)+ expect(testsFor(SEED_RULES, ['desktop/lib/latests/a.dart'])).toEqual(['Desktop on a Mac'])+ })++ // The regex the matcher replaced (#3216), for short inputs where it is fast: both must say the same thing.+ it('agrees with the regex it replaced on short random patterns and paths', () => {+ const regex = (glob: string) => {+ let source = ''+ for (let i = 0; i < glob.length; i++) {+ const c = glob[i]!+ if (c === '*' && glob[i + 1] === '*') {+ if (glob[i + 2] === '/') { source += '(?:.*/)?'; i += 2 } else { source += '.*'; i += 1 }+ } else if (c === '*') source += '[^/]*'+ else if (c === '?') source += '[^/]'+ else source += c.replace(/[.+^${}()|[\]\\]/g, '\\$&')+ }+ return new RegExp(`^${source}$`, 'i')+ }+ let seed = 7+ // A linear congruential generator's low bits repeat quickly: take the high ones.+ const random = (n: number) => { seed = (seed * 1_103_515_245 + 12_345) % 2_147_483_648; return Math.floor(seed / 65_536) % n }+ const pick = <T,>(items: readonly T[]) => items[random(items.length)]!+ const globParts = ['a', 'b', '/', '*', '?', '**', '**/', '.'], pathParts = ['a', 'b', '/', '.', 'x']+ for (let n = 0; n < 5_000; n++) {+ const glob = Array.from({ length: 1 + random(6) }, () => pick(globParts)).join('')+ const path = Array.from({ length: random(9) }, () => pick(pathParts)).join('')+ expect(globMatch(glob, path), `${glob} on ${path}`).toBe(regex(glob).test(path))+ }+ })+it('asks the most reads any touched row asks, at least the default, and fails closed on files it cannot read', () => {expect(requiredReads(SEED_RULES, ['desktop/lib/super_tabs/view.dart'])).toBe(1)expect(requiredReads(SEED_RULES, ['desktop/lib/super_tabs/view.dart', 'backend/src/lib/ssoAuth.ts'])).toBe(2)diff --git a/backend/src/superTabs/policy.ts b/backend/src/superTabs/policy.tsindex e634e87b3..13c4f8925 100644--- a/backend/src/superTabs/policy.ts+++ b/backend/src/superTabs/policy.ts@@ -181,6 +181,10 @@ function globTokens(glob: string): GlobToken[] {* whatever a project saves (security review of #3216: the regex it replaced took 19 s on `*a` ten times). */export function globMatch(glob: string, path: string): boolean {const tokens = globTokens(glob), end = tokens.length+ // A double star and a slash matches no folders, or any characters ending in a slash, as the regex `(?:.*/)?` did. So it+ // has two positions: at its token i (it may still match nothing and move on), and inside it, -(i + 1), having read+ // characters, which it leaves only by reading a slash. Without the inside position `a/**/b` matched `a/xb` (Reviewers).+ const inside = (i: number) => -(i + 1)// Every position reachable from [from] without reading a character: a wildcard may match nothing.const close = (from: Iterable<number>): Set<number> => {const seen = new Set<number>(), stack = [...from]@@ -188,7 +192,7 @@ export function globMatch(glob: string, path: string): boolean {const i = stack.pop()!if (seen.has(i)) continueseen.add(i)- const t = tokens[i]+ const t = i >= 0 ? tokens[i] : undefinedif (t && (t.kind === 'name' || t.kind === 'any' || t.kind === 'dirs')) stack.push(i + 1)}return seen@@ -197,14 +201,20 @@ export function globMatch(glob: string, path: string): boolean {for (const raw of path) {const c = raw.toLowerCase(), next: number[] = []for (const i of states) {+ if (i < 0) {+ // Inside a double star and a slash: any characters, leaving only after a slash.+ next.push(i)+ if (c === '/') next.push(-i)+ continue+ }const t = tokens[i]if (!t) continueif (t.kind === 'char') { if (t.c === c) next.push(i + 1) }else if (t.kind === 'one') { if (c !== '/') next.push(i + 1) }else if (t.kind === 'name') { if (c !== '/') next.push(i) }else if (t.kind === 'any') next.push(i)- // A double star and a slash: any characters, leaving after a slash.- else { next.push(i); if (c === '/') next.push(i + 1) }+ else if (c === '/') next.push(i + 1, inside(i))+ else next.push(inside(i))}if (!next.length) return falsestates = close(next)diff --git a/backend/src/superTabs/postRecipients.test.ts b/backend/src/superTabs/postRecipients.test.tsindex fd132e0da..7ab89aa59 100644--- a/backend/src/superTabs/postRecipients.test.ts+++ b/backend/src/superTabs/postRecipients.test.ts@@ -9,6 +9,8 @@ import { REACHED_NO_AGENT, type Command } from './commands.js'import { agent } from './model.js'import { owner, stepsFixture } from './steps.test-support.js'+const HOLD = { kind: 'person', personId: 'owner', defaultAt: '2026-11-06T02:00:00.000Z' } as const+function setup() {const f = stepsFixture()const post = (by: string, on: string, text: string, recipientIds: string[] = [], reply?: { id: string; author: never }) =>@@ -116,7 +118,7 @@ describe('an agent\'s thread reply', () => {describe('status still reaches the PM', () => {const status = (status: string, result: string | null) => {const f = stepsFixture()- const rows = f.run({ type: 'work.status', conversationId: f.task, assignmentId: f.group(f.task).assignment!.id, status, result } as Command, f.as(f.dev)).messages+ const rows = f.run({ type: 'work.status', conversationId: f.task, assignmentId: f.group(f.task).assignment!.id, status, result, ...(status === 'blocked' || status === 'needs_human' ? { hold: HOLD } : {}) } as Command, f.as(f.dev)).messagesreturn { f, rows: rows.filter(m => m.conversationId === f.task) }}diff --git a/backend/src/superTabs/read/contract.ts b/backend/src/superTabs/read/contract.tsindex 5ef68189b..a7adb8206 100644--- a/backend/src/superTabs/read/contract.ts+++ b/backend/src/superTabs/read/contract.ts@@ -39,6 +39,8 @@ export interface Audience { people: Array<{ id: string; generation: string }> }export type GroupView = Omit<Conversation, 'messageSeq' | 'reportSeq' | 'dormant' | 'lastActivityAt' | 'audience' | 'ledger' | 'proposals'> & {/** When it shipped (ms): its first Done; absent until it has. Nothing else of its ledger is sent. */shippedAt?: number+ /** Why a held task is held, or `none` for a hold from before reasons; absent when it is not held (heldReason.ts heldView). */+ held?: import('../heldReason.js').HeldView}& { messageSeq: number; dormant?: true; audience?: Audience/** A Buddy chat's owner, in place of its audience (read/views.ts groupView). */diff --git a/backend/src/superTabs/read/views.ts b/backend/src/superTabs/read/views.tsindex 2f72180af..76508041f 100644--- a/backend/src/superTabs/read/views.ts+++ b/backend/src/superTabs/read/views.ts@@ -5,6 +5,7 @@*/import { machineSuspensionReason, suspendedEngines } from '../engineHealth.js'import { leadChoices } from '../leadStart.js'+import { heldView } from '../heldReason.js'import { isBuddyChat, isBuddyReader } from '../buddies.js'import { agentForBuddy, agentWithoutMachine, groupForBuddy, machineHiddenFrom, seenMachineIds, visibleState, withSeenRequirement, type Actor, type Agent, type Conversation, type SuperTabState } from '../model.js'import { availableSlots, slotCounter, machineTeamWork, type ContributedMachine } from '../machines.js'@@ -70,7 +71,9 @@ export function groupView(group: Conversation, seenMachines: ReadonlySet<string>// alone for their Chat with PM, and would send what they write for the PM to their Buddy instead (buddies.ts).const readers = isBuddyChat(group) ? { buddyOwnerId: audience!.people[0]!.id } : audience ? { audience } : {}const shippedAt = ledger?.shippedAt- return { ...rest, messageSeq: messageSeq ?? 0, ...(dormant ? { dormant: true as const } : {}), ...(shippedAt === undefined ? {} : { shippedAt }), ...readers }+ const held = heldView(group)+ return { ...rest, messageSeq: messageSeq ?? 0, ...(dormant ? { dormant: true as const } : {}), ...(shippedAt === undefined ? {} : { shippedAt }),+ ...(held ? { held } : {}), ...readers }}/** A conversation's whole data as the reader may see it: a task's requirement lists only the machines they see. */diff --git a/backend/src/superTabs/steps.test.ts b/backend/src/superTabs/steps.test.tsindex 39e9a2113..37e2c7804 100644--- a/backend/src/superTabs/steps.test.ts+++ b/backend/src/superTabs/steps.test.ts@@ -13,6 +13,8 @@ import { reportedAs } from './projectUpdates.js'import { idleNotices } from './tidy.js'import { QUIET_RUNNING_MS, sweepForLead, sweepLiveness } from './liveness.js'+const HOLD = { kind: 'person', personId: 'owner', defaultAt: '2026-11-06T02:00:00.000Z' } as const+describe('opening a step', () => {it('opens on a task of its project, numbered, its opener in the task', () => {const f = stepsFixture()@@ -284,7 +286,7 @@ describe('who hears a step', () => {const rev = f.add('rev', id)f.run({ type: 'work.assign', conversationId: id, agentId: rev }, f.as(f.dev))const status = (status: string, result: string | null = 'note', on = id, by = rev) =>- f.run({ type: 'work.status', conversationId: on, assignmentId: f.group(on).assignment!.id, status, result } as Command, f.as(by)).messages+ f.run({ type: 'work.status', conversationId: on, assignmentId: f.group(on).assignment!.id, status, result, ...(status === 'blocked' || status === 'needs_human' ? { hold: HOLD } : {}) } as Command, f.as(by)).messagesconst post = (on: string, by = rev) =>f.run({ type: 'message.send', conversationId: on, text: 'Two findings.', replyTo: null, recipientIds: [] } as Command, f.as(by)).messagesreturn { f, id, rev, status, post }diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex 22ea126ba..6cbca43a3 100644--- a/backend/src/superTabs/store.ts+++ b/backend/src/superTabs/store.ts@@ -78,6 +78,8 @@ import { loadDeliveryParts, ms } from './parts/light.js'import { endSteps, ownerOf, stepEndedRows, stepsOf } from './steps.js'import { pullRequestEvents, type PullRequestWatch } from './pullRequestEvents.js'import { reopenOnEvents } from './handed.js'+import type { TrainTask } from './mergeTrain/plan.js'+import type { TrainTaskPull } from './mergeTrain/train.js'import { guardedWrite, partId } from './parts/write.js'import { retryable } from './retry.js'import { touchesFor } from './parts/touches.js'@@ -133,6 +135,12 @@ async function countersBefore(tx: Transaction, tabId: string, conversationId: stconst newest = (list: SuperTabMessage[]) => list.length ? Math.max(...list.map(m => m.sequence)) : undefinedreturn { message: newest(shown), main: newest(main), person: newest(person) }}+/** A project the merge train may run on, with its tasks' pull requests (trainProjects). */+export interface TrainProject { tabId: string; projectId: string; ownerId: string; autonomousEnv: string; repositoryUrl: string; pulls: TrainTaskPull[] }+/** A task quiet this long is not a merge train candidate. */+export const TRAIN_QUIET_MS = 7 * 24 * 3_600_000+/** The most tasks one train pass reads. */+export const TRAIN_TASKS = 300const reactionId = (tabId: string, actor: Actor, command: ReactCommand) => stableId(tabId, command.messageId, actorKey(actor), command.emoji)const json = (value: unknown): Prisma.InputJsonValue => JSON.parse(JSON.stringify(value)) as Prisma.InputJsonValuetype SendCommand = Extract<Command, { type: 'message.send' }>@@ -4744,6 +4752,97 @@ export class SuperTabStore {})}+ /**+ * The merge train's candidates (mergeTrain/run.ts): unarchived tasks (not steps), done ones included, active in the last+ * [TRAIN_QUIET_MS] that link a pull request, at most [limit], the most recently active first; grouped by project, each with+ * its steps and its own repository's pull requests. Read only: one indexed read, then each Swarm's state once.+ */+ async trainProjects(now: number, limit = TRAIN_TASKS): Promise<TrainProject[]> {+ // The finished mark's index, [workFinished, archived, lastActivityAt], as the PR watch reads it, both marks: a done task+ // still waits for its merge.+ const rows = await this.db.swarmGroup.aggregateRaw({ pipeline: [+ { $match: { workFinished: { $in: [false, true] }, archived: false, lastActivityAt: { $gte: { $date: new Date(now - TRAIN_QUIET_MS).toISOString() } },+ deleted: false, kind: null, 'data.reviewOf': null, 'data.pullRequestUrls.0': { $exists: true } } },+ { $sort: { lastActivityAt: -1 } },+ { $limit: limit },+ { $project: { _id: 0, tabId: 1, key: 1 } },+ ] }) as unknown as Array<{ tabId: string; key: string }>+ const byTab = new Map<string, string[]>()+ for (const row of rows) byTab.set(row.tabId, [...byTab.get(row.tabId) ?? [], row.key])+ const projects: TrainProject[] = []+ for (const [tabId, keys] of byTab) {+ const row = await this.db.superTab.findUnique({ where: { id: tabId }, select: SWARM_ROW })+ if (!row || row.deletedAt) continue+ // The awake groups come with every load, and a step sleeps only once its task is archived (steps.ts): every step of+ // these tasks is loaded.+ const { state } = await loadRow(this.db as unknown as Transaction, requireParts(row), { groupIds: keys })+ if (state.paused) continue+ // Every earlier attempt's agent, from the attempts record's [tabId, conversationId, createdAt] index: a builder is never+ // its own task's review (review 1 of #3226). A plain $in: Prisma would send `in` as one OR branch per task.+ const earlier = await this.db.superTabAttempt.aggregateRaw({ pipeline: [+ { $match: { tabId, conversationId: { $in: keys } } },+ { $project: { _id: 0, conversationId: 1, agentId: '$snapshot.assignment.agentId' } },+ ] }) as unknown as Array<{ conversationId: string; agentId?: unknown }>+ const found = new Map<string, TrainProject>()+ for (const key of keys) {+ const group = state.conversations.find(c => c.id === key)+ if (!group || group.archived || group.reviewOf || group.assignment?.status === 'cancelled') continue+ const project = groupProject(state, group), repositoryUrl = project.repository?.repositoryUrl ?? null+ if (!repositoryUrl) continue+ const entry = found.get(project.id) ?? { tabId, projectId: project.id, ownerId: project.ownerId ?? state.ownerId, autonomousEnv: state.environment,+ repositoryUrl, pulls: [] }+ found.set(project.id, entry)+ const steps = stepsOf(state, group.id).filter(step => !step.archived || step.assignment?.status !== 'cancelled')+ for (const url of group.pullRequestUrls ?? []) {+ const own = projectPullRequestUrl(url, repositoryUrl)+ if (!own) continue+ const builders = [...new Set([group.assignment?.agentId, group.lostAttempt?.agentId,+ ...earlier.filter(a => a.conversationId === group.id).map(a => a.agentId)].filter((id): id is string => typeof id === 'string' && !!id))]+ .map(id => `agent:${id}`)+ entry.pulls.push({ taskId: group.id, url: own, task: { checks: group.checks,+ pullRequestHeads: (group as { pullRequestHeads?: TrainTask['pullRequestHeads'] }).pullRequestHeads, steps, builders } })+ }+ }+ projects.push(...found.values())+ }+ return projects+ }++ /** Records that the merge train merged [url], a pull request of task [groupId]: conversation.merged, as the project's+ * owner, who switched the train on for it (mergeTrain/config.ts). Once per pull request: a retry is the same operation. */+ async trainMerged(project: Pick<TrainProject, 'tabId' | 'ownerId' | 'autonomousEnv'>, groupId: string, url: string, mergedAt: number): Promise<void> {+ const person = await this.db.user.findUnique({ where: { id: project.ownerId }, select: { email: true } })+ if (!person) throw new Error('The project owner is gone: the merge train cannot record its merge.')+ const user: AuthUser = { sub: project.ownerId, email: person.email, autonomousEnv: project.autonomousEnv as AuthUser['autonomousEnv'], role: 'user' }+ await this.executeOnce(user, project.tabId, { operationId: `merge-train-${stableId(groupId, url)}`,+ command: { type: 'conversation.merged', conversationId: groupId, pullRequestUrl: url, mergedAt: new Date(mergedAt).toISOString() } })+ }++ /** Tells task [groupId]'s Engineer [text] from the merge train, once per [key], as its project's Lead writes the Swarm's own+ * lines (pullRequestSeen). A task with no Engineer in the Swarm hears nothing. Whether it was told now. */+ async trainTell(tabId: string, groupId: string, key: string, text: string): Promise<boolean> {+ const id = stableId('merge-train', groupId, key)+ if (await this.db.superTabMessage.findUnique({ where: { id }, select: { id: true } })) return false+ return transaction(this.db, async tx => {+ if (await tx.superTabMessage.findUnique({ where: { id }, select: { id: true } })) return false+ const row = await tx.superTab.findUnique({ where: { id: tabId }, select: SWARM_ROW })+ if (!row || row.deletedAt) return false+ const loaded = await loadRow(tx, requireParts(row), { groupIds: [groupId] }), state = cloneData(loaded.state)+ const group = state.conversations.find(c => c.id === groupId)+ if (!group || group.archived || group.reviewOf) return false+ const ownerId = ownerOf(state, group), owner = ownerId ? state.agents.find(a => a.id === ownerId) : undefined+ const leadId = state.conversations.find(c => c.id === groupProject(state, group).leadConversationId)?.leadId+ const by = state.agents.find(a => a.id === leadId) ?? owner+ if (!owner || !by) return false+ const rows: MessageDraft[] = [{ id, conversationId: group.id, text, replyTo: null, recipients: [owner.id], source: { kind: 'system' },+ author: { kind: 'agent', id: by.id, name: by.name, displayName: agentDisplayName(state.agents, by.id), membershipGeneration: by.membershipGeneration } }]+ const sequences = numberMessages(state, rows, this.now())+ await this.save(tx, loaded, state, clock.next())+ await this.writeMessages(tx, tabId, state, rows, sequences)+ return true+ })+ }+async archiveFinished(tabId: string, groupId: string, checked: Readonly<Record<string, SettledPullRequest>>, reviewOf?: string): Promise<boolean> {return transaction(this.db, async tx => {const row = await tx.superTab.findUnique({ where: { id: tabId }, select: SWARM_ROW })diff --git a/backend/src/superTabs/taskLine.test.ts b/backend/src/superTabs/taskLine.test.tsindex 123720ac3..753b97146 100644--- a/backend/src/superTabs/taskLine.test.ts+++ b/backend/src/superTabs/taskLine.test.ts@@ -4,6 +4,8 @@ import { createSuperTab, type Actor, type AgentConfiguration, type CommandEffectimport { SHIP_KIND } from './ship.js'import { TASK_LINE_KIND } from './taskLine.js'+const HOLD = { kind: 'person', personId: 'owner', defaultAt: '2026-11-06T02:00:00.000Z' } as const+const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }const config: AgentConfiguration = { engine: 'claude', model: 'opus', effort: 'high', contextWindow: null, engineVersion: null }const PR = 'https://github.com/example/app/pull/7'@@ -30,7 +32,7 @@ function fixture() {const task = (id: string) => state.conversations.find(c => c.id === id)!const status = (id: string, worker: string, value: 'working' | 'needs_human' | 'blocked' | 'review' | 'done' | 'stopped', result: string | null = null,extra: Record<string, unknown> = {}) =>- run({ type: 'work.status', conversationId: id, assignmentId: task(id).assignment!.id, status: value, result, ...extra } as Command, as(worker))+ run({ type: 'work.status', conversationId: id, assignmentId: task(id).assignment!.id, status: value, result, ...(value === 'blocked' || value === 'needs_human' ? { hold: HOLD } : {}), ...extra } as Command, as(worker))const lines = (effects: CommandEffects) => effects.messages.filter(m => m.source?.kind === TASK_LINE_KIND)return { run, add, as, group, request, task, status, lines, pm, get state() { return state } }}diff --git a/backend/src/superTabs/teamRouting.test.ts b/backend/src/superTabs/teamRouting.test.tsindex 295cf696d..7a4ccfa5a 100644--- a/backend/src/superTabs/teamRouting.test.ts+++ b/backend/src/superTabs/teamRouting.test.ts@@ -4,6 +4,8 @@ import { admitMachineStart, availableSlots, machineObservationSchema, machineTeaimport { createSuperTab, SuperTabError, visibleState, type Actor, type AgentConfiguration, type AgentStart, type SuperTabState } from './model.js'import type { RouteDecision } from './routeRecord.js'+const HOLD = { kind: 'person', personId: 'owner', defaultAt: '2026-11-06T02:00:00.000Z' } as const+// Teammates' work runs only on Team machines (docs/plans/2026-10-24-swarm-team-account.md, Task 3): a start or an// assignment for a project whose owner did not contribute the machine needs a Harness Team account whose privacy check// passed, or a machine used only for agents. A person's own projects on their own machine are unchanged.@@ -349,7 +351,7 @@ describe('agents already working on a personal machine', () => {work.assignment = { id: 'before-release', agentId: old, status: 'working', configuration: config,execution: { machineId: 'mate-mac', harnessId: 'harness-old', machineOwnerId: 'mate' }, result: null }const oldActor: Actor = { kind: 'agent', agentId: old, machineOwnerId: 'mate' }- f.run({ type: 'work.status', conversationId: group, assignmentId: 'before-release', status: 'blocked', result: 'Needs a token.' }, oldActor)+ f.run({ type: 'work.status', conversationId: group, assignmentId: 'before-release', status: 'blocked', hold: HOLD, result: 'Needs a token.' }, oldActor)expect(f.run({ type: 'message.send', conversationId: group, text: 'Here it is.', replyTo: null, recipientIds: [old] }).messages[0]!.recipients).toEqual([old])expect(f.state.agents.find(a => a.id === old)).not.toHaveProperty('workDecision')expect(f.state.conversations.find(c => c.id === group)!.assignment).toMatchObject({ id: 'before-release', status: 'blocked' })diff --git a/backend/src/worker.ts b/backend/src/worker.tsindex ebc526b1c..7165c6e53 100644--- a/backend/src/worker.ts+++ b/backend/src/worker.ts@@ -26,6 +26,9 @@ import { startDeliveryCompaction } from './superTabs/deliveryCompaction.js'import { startThreadBackfill } from './superTabs/threadBackfill.js'import { appPullRequests, markFinishedGroups, startSwarmArchive, unknownPullRequests } from './superTabs/archive.js'import { appPullRequestWatch, startPullRequestWatch } from './superTabs/pullRequestEvents.js'+import { startMergeTrain } from './superTabs/mergeTrain/run.js'+import { teamAccountRequired } from './superTabs/machines.js'+import { PrismaApprovals } from './github/approvals.js'import { SuperTabStore } from './superTabs/store.js'import { announceSwarmDeliveries, announceSwarmTerminal } from './lib/swarmDeliveryPushes.js'import { announceSwarmHostChanges } from './lib/swarmHostPushes.js'@@ -78,6 +81,7 @@ async function start(): Promise<void> {let stopLegacyDrop = (): void => {}let stopArchive = (): void => {}let stopPullRequestWatch = (): void => {}+ let stopMergeTrain = (): void => {}let stopDeliveries = (): void => {}let stopRepush = (): void => {}let stopCompaction = (): void => {}@@ -99,6 +103,7 @@ async function start(): Promise<void> {stopLegacyDrop()stopArchive()stopPullRequestWatch()+ stopMergeTrain()stopDeliveries()stopRepush()stopCompaction()@@ -157,6 +162,13 @@ async function start(): Promise<void> {// GitHub events on an open task's pull request reach its Engineer within a minute (superTabs/pullRequestEvents.ts): only// with the app, which reads them.if (githubApp) stopPullRequestWatch = startPullRequestWatch(prisma, swarms, () => appPullRequestWatch(githubApp))+ // Every minute, each project whose merge train is switched on (its rules; off until then) merges what passed at its head, in+ // batches through the app (superTabs/mergeTrain/, task #3402). Only where an agent's token could be had for the repository.+ if (githubApp) {+ const approvals = new PrismaApprovals(prisma)+ stopMergeTrain = startMergeTrain({ store: swarms, app: githubApp,+ approved: async (project, repository) => !teamAccountRequired() || approvals.approved(project.autonomousEnv, project.tabId, project.projectId, repository) })+ }// A delivery that can no longer move ends as Not sent, instead of waiting for good (superTabs/deliverySettle.ts).stopDeliveries = startDeliverySettle(prisma, swarms)// Every 15 s, the machine of each agent with a delivery still queued after 10 s is told again, in case its push was lost:diff --git a/backend/vitest.super-tabs.config.ts b/backend/vitest.super-tabs.config.tsindex f46608352..1e18a19ba 100644--- a/backend/vitest.super-tabs.config.ts+++ b/backend/vitest.super-tabs.config.ts@@ -8,5 +8,5 @@ export default defineConfig({ test: { include: ['integration/superTabs.test.ts','integration/superTabBuddyProbes.test.ts', 'integration/superTabBuddySessions.test.ts', 'integration/superTabSwarmBuddy.test.ts', 'integration/superTabPersonalLead.test.ts', 'integration/superTabCosts.test.ts', 'integration/harnessSharesList.test.ts', 'integration/harnessSharesIndexPlan.test.ts', 'integration/atlasSnapshot.test.ts', 'integration/queryStats.test.ts','integration/superTabEvidence.test.ts', 'integration/superTabAttemptModels.test.ts', 'integration/superTabNamedReads.test.ts', 'integration/swarmSweepPlans.test.ts', 'integration/overdueDecisions.test.ts', 'integration/workerIndexPlans.test.ts', 'integration/superTabReflection.test.ts', 'integration/superTabScorecard.test.ts','integration/superTabMessagePages.test.ts', 'integration/superTabDeliveryCompaction.test.ts', 'integration/superTabNoticeDigest.test.ts', 'integration/superTabPmSchedule.test.ts', 'integration/superTabDigestHour.test.ts', 'integration/superTabCommandLoads.test.ts', 'integration/superTabThreads.test.ts', 'integration/superTabMachineRemovals.test.ts',- 'integration/superTabInstructions.test.ts', 'integration/superTabProjectRules.test.ts', 'integration/superTabWorkflow.test.ts', 'integration/superTabTaskLines.test.ts', 'integration/superTabDeletion.test.ts', 'integration/communityReports.test.ts', 'integration/superTabMachineNames.test.ts', 'integration/superTabComputerMoves.test.ts', 'integration/superTabTagsClear.test.ts', 'integration/swarmAgentTombstones.test.ts', 'integration/superTabPullRequestEvents.test.ts', 'integration/superTabProposals.test.ts', 'integration/superTabRequestReads.test.ts', 'integration/superTabVoiceMessages.test.ts', 'integration/superTabThumbnails.test.ts', 'integration/superTabProjectChatWorkers.test.ts', 'integration/prismaQueryTiming.test.ts', 'integration/secondaryReads.test.ts', 'integration/pushDevices.test.ts'], hookTimeout: 120000, testTimeout: 30000, setupFiles: ['integration/noDefaultDigest.test-support.ts', 'integration/cacheOn.test-support.ts', 'src/lib/noRedis.test-support.ts'],+ 'integration/superTabInstructions.test.ts', 'integration/superTabProjectRules.test.ts', 'integration/superTabWorkflow.test.ts', 'integration/superTabTaskLines.test.ts', 'integration/superTabDeletion.test.ts', 'integration/communityReports.test.ts', 'integration/superTabMachineNames.test.ts', 'integration/superTabComputerMoves.test.ts', 'integration/superTabTagsClear.test.ts', 'integration/swarmAgentTombstones.test.ts', 'integration/superTabPullRequestEvents.test.ts', 'integration/superTabMergeTrain.test.ts', 'integration/superTabProposals.test.ts', 'integration/superTabRequestReads.test.ts', 'integration/superTabVoiceMessages.test.ts', 'integration/superTabThumbnails.test.ts', 'integration/superTabProjectChatWorkers.test.ts', 'integration/prismaQueryTiming.test.ts', 'integration/secondaryReads.test.ts', 'integration/pushDevices.test.ts'], hookTimeout: 120000, testTimeout: 30000, setupFiles: ['integration/noDefaultDigest.test-support.ts', 'integration/cacheOn.test-support.ts', 'src/lib/noRedis.test-support.ts'],fileParallelism: false, env: { NODE_ENV: 'test', HARNESS_CREDENTIAL_ENCRYPTION_KEY: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' } } })diff --git a/docs/plans/2026-11-05-hold-reason-plan.md b/docs/plans/2026-11-05-hold-reason-plan.mdnew file mode 100644index 000000000..fb0504f1d--- /dev/null+++ b/docs/plans/2026-11-05-hold-reason-plan.md@@ -0,0 +1,36 @@+# Holding a task needs a reason (#3390) Implementation Plan++> Built the project's way (Engineer, test first, one pull request), not subagent-driven-development. No handoff step.++**Goal:** A task held for later, blocked or waiting on a person carries one of four reasons, shown on the task, and a hold+with none is refused with `HOLD_REASON_MISSING`, which lists the four kinds.++**Architecture:** One new module, `backend/src/superTabs/heldReason.ts`: the reason's schema (a discriminated union of four+kinds), a fact check against the Swarm, the refusal, and `heldView`. `work.queue` (with `notBefore`) and `work.status`+(`blocked`, `needs_human`) take an optional `hold` in their schema and require it when applied; it is stored on the task+(`Conversation.hold`) or the assignment (`Assignment.hold`) and shown as `held` in the group view, `{kind:'none'}` for a+hold from before reasons.++**Tech Stack:** TypeScript, zod, vitest (`npm test -- <path>`).++**Spec:** the task brief of #3390 (Dee's Swarm redesign, 2026-11-05).++## Global Constraints+- New guard, new name: `HOLD_REASON_MISSING`. `removedRefusals.test.ts` stays green.+- No numbers in constants: the reasons carry their own times (`defaultAt`, `at`); the server adds none.+- The release window never holds building or merging: nothing here reads it.+- `model.ts` gains fields: `parts/light.ts` and its test place them (light.test.ts fails otherwise).+- Staged (review of #3215, ENGINEERING.md §5): `blocked` and `needs_human` from today's CLI carry no `hold`, so they are accepted without one and shown as `none`; a `hold` that is sent is checked. `work.queue` (the PM's own call) already refuses a not-before date without one. The refusal for statuses follows once the CLI's examples, rules text and skill send `hold`.+- "Waits on a person already asked" checks that the person is a member, not that a decision to them is open (decisions live outside the Swarm state). A reason's time must still be ahead; a task reason must name a task, not a step.+- No new collection, index or stored shape outside the existing Swarm parts.++## Review Focus+- Every `blocked` / `needs_human` caller (agents, tests) now sends a `hold`; old agents get a refusal that says what to send.+- A reason that is not true (unknown task, stranger, a requester nobody has) is no reason.+- Clearing: `notBefore: null` and any later status remove the reason.++### Task 1: The reason and its refusal+**Files:** Create `backend/src/superTabs/heldReason.ts`; modify `commands.ts`, `model.ts`, `parts/light.ts`, `read/contract.ts`, `read/views.ts`.+**Interfaces:** `heldReason` (zod), `HeldReason`, `checkReason(state, group, reason)`, `missingReason()`, `heldView(group)`.+- [ ] Failing tests in `commands.test.ts` "a held task carries one of four reasons": each reason accepted and shown on `work.queue`, `blocked`, `needs_human`; no reason refused with the four kinds; untrue reasons refused; cleared by `notBefore: null` and the next status; legacy holds show `none`.+- [ ] Implement until they pass; update existing callers of `blocked` / `needs_human` to send a reason.diff --git a/docs/plans/2026-11-05-merge-train-plan.md b/docs/plans/2026-11-05-merge-train-plan.mdnew file mode 100644index 000000000..8a0889448--- /dev/null+++ b/docs/plans/2026-11-05-merge-train-plan.md@@ -0,0 +1,154 @@+# Merge train Implementation Plan++> Written by the project's Engineer way of working (project instructions, Engineer): plan first, then each task test first,+> the failing test committed before its code. No per-task review: the pull request's review steps are the independent+> reviews. No Execution Handoff.++**Goal:** Every 10 minutes the server merges approved pull requests in batches through the Harness GitHub App, so nobody+merges routine work by hand (task #3402, requested by Dee through Harness).++**Architecture:** A new module `backend/src/superTabs/mergeTrain/` runs one pass per project in the singleton worker+(worker.ts), like the pull request watch. The pass is a pure planner (`plan.ts`: who is eligible, which lane, how a red batch+splits) driven by `train.ts` against two narrow interfaces: `TrainGitHub` (the repository, through the App, `github/train.ts`)+and `TrainSwarm` (the Swarm store: candidates, recording a merge, telling an owner). The train keeps no stored record: an+open batch is an open pull request on a `harness-train/<project>/` branch whose body lists its members and their heads. The+worker remembers the tip it built for each batch; a batch whose tip differs (someone pushed to it) or that it does not know (a+restart) is closed and rebuilt, never merged, so a hand merge, a restart or a push to the branch never leaves a stale record.++**Tech Stack:** TypeScript backend, vitest, GitHub REST (git data, merges, pulls, check runs) through the existing App.++**Spec:** task #3402's brief (conversation a8d3e85bda1c45e0e8fe9f33): anh Dee's Swarm redesign, approved 2026-11-05.++## Global Constraints++- PR body first line: "Requested by Dee through Harness."+- Owns `backend/src/superTabs/`, `backend/src/worker.ts`, `backend/src/github/`, `AGENTS.md`.+- Fail closed on every read: a GitHub answer that is not exactly what the train expects means no write for that batch or+ pull request this pass (no merge, no close, no tell); the pass logs one line.+- Re-fetch every member's head and main's head immediately before the squash merge; any difference aborts and rebuilds.+- Train branches never mark tasks Team-written: the batch pull request is never linked to a task (never in a Swarm+ message, result or `pullRequestUrls`), and no ref the train writes ever points at a member's own commit.+- Kill switch and interval live in the project rules record (task #3393, `rules.mergeTrain.enabled/everyMinutes`). Opt-in+ (River, 11-05): until a project switches it on it is off. Until the record lands, `TRAIN_DEFAULTS = { enabled: false,+ everyMinutes: 10 }` in `mergeTrain/config.ts` is the one place they live.+- Reads (River, 11-05): a PR needs as many distinct passed review reads at its head as the review table asks for its+ changed paths; until the table lands, the security areas (sign-in, tokens, encryption, access, Buddy guard, device links,+ deletion) need two (`REVIEW_AREAS`, erring wide). Every other open step (a test) must have passed at the head too.+- Two PRs that change the same file never share a batch (task #3401's rule: a combination read only where files are+ shared): the later one waits and runs on top of the first once it merged.+- The fast lane merges docs-only PRs (docs/, *.md) on their own green CI only while no code batch is open, so it never+ moves main under a batch in CI. scripts/ batches: it holds the CI planner and release scripts (review 2).+- Review 2 of #3226: only pull requests from this repository's own `harness-train/` branches are batches (a fork's is never+ touched); a batch no longer open is forgotten; a squash GitHub refuses closes the batch and tells each Engineer GitHub's+ reason; a PR changing `.github/workflows/` stays out (the token has no `workflows`); each merge is recorded on its own.+- Known window: between the last read of main and the squash, a hand merge of seconds could let a batch merge on a main its+ CI did not see. GitHub's "require branches to be up to date before merging" closes it on GitHub's side; the train's+ squash then fails and the batch rebuilds.+- People can still merge by hand; the train sees it as main moving or a member closing, and rebuilds.+- Two security reviews before merge: this is the first server write to main.+- Swarm code stays out of cli/src/core. Temp files only in mktemp -d folders.++## Design++- growth: no stored train record. Batch branches are deleted when their batch merges or closes; a branch the train finds+ with no open pull request is deleted on the next pass. Train keys on a task (`train-*:<head>` in `pullRequestEvents`)+ are bounded by the existing `SEEN_KEPT`.+- concurrency: one pass at a time per worker (`running` guard, as the PR watch); the singleton worker is the only writer.+ Two passes racing anyway meet GitHub's own guards: creating an existing ref is 422, a squash with a stale `sha` is 409;+ both read as "skip this pass".+- read cost: per pass and project, one main ref read, one open-PR list, then per candidate the PR, its check runs and its+ files, each with the ETag cache the watch uses; per open batch its PR and its check runs.+- scale: 10x PRs is 10x candidate reads per pass, still under the App's 5,000/h at 10-minute passes; the pass's log line+ (`candidates`, `unreadable`, `merged`, `split`) warns first. Batches hold at most `TRAIN_MAX_BATCH = 8` members.+- compatibility: old clients see the merges as before (task cards, "Merged <url>" lines); nothing new on the wire.+- migration + rollback: none. Rolling back stops the worker pass; open batch PRs stay open and can be closed by hand.+- audience: only tasks of a project whose repository is approved for the App (github/projectAccess.ts); the train never+ quotes PR text from outside the repository's people into the Swarm.+- identity: every write is the App's installation token, never a person's login or the machine owner's.+- failure: a failed pass logs why; a red batch tells each failing PR's owner in its task; a conflict tells its owner+ "merge main once"; GitHub refusing a merge leaves the batch open and logs it.+- platforms: backend only.++## Review Focus++- A member whose head moved after its verdicts (a push after review): never merged; the batch rebuilds without it until+ its verdicts are at the new head (Task 3 test "verdict not at head").+- A member pushed between the batch's green CI and the merge: the re-fetch catches it (Task 4 test "moved before merge").+- A batch PR link reaching a task: never, so push-origin reads of tasks never see the bot's branch (Task 4 test).+- GitHub answering 5xx/403/malformed on any read: nothing written (Task 4 test "fail closed").+- Kill switch off mid-batch: no merge and no new batch; an open batch is left as it is (Task 4 test).++---++### Task 1: Eligibility and lanes (pure)++**Files:** Create `backend/src/superTabs/mergeTrain/plan.ts`, `mergeTrain/config.ts`; Test `mergeTrain/plan.test.ts`++**Interfaces:**+- Produces: `TrainCandidate { url; number; taskId; ownerId|null; head; draft; base; mergeable; labels; files; ciRequired: 'success'|'failure'|'pending'|null }`,+ `verdictAtHead(state, task, url, head): boolean`, `eligible(candidate, verdictOk): { ok: true } | { ok: false; why }`,+ `laneOf(files): 'fast' | 'code'`, `componentOf(files): string`, `splitRed(members): Member[][]`.+- `verdictAtHead` reads #3394's verdict fields (`CheckVerdict.head`, `.patch`, `.stale`, `Conversation.pullRequestHeads`):+ every check of the task and of each step not cancelled has a passing verdict that counts at [head]; a verdict with no+ head never counts here (fail closed). At least one review step.++- [ ] Test: open, ready, base main, verdicts at head, ci/required success, mergeable true, no `hold` label → eligible.+- [ ] Test: each failing condition alone (draft, verdict at an older head, verdict without head, a step not passed, ci+ pending/failed, mergeable null/false, `hold` label, base not main) → not eligible with its reason.+- [ ] Test: files all in `docs/`, `*.md`, `scripts/` → lane `fast`; any other → `code`.+- [ ] Test: `splitRed` of members over two components → one group per component; one component of 4 → halves; 1 → [].+- [ ] Code; commit.++### Task 2: The App's train calls++**Files:** Create `backend/src/github/train.ts`, `github/train.test.ts`; Modify `github/app.ts` (one `installationCall`)++**Interfaces:**+- Produces: `TrainGitHub` with `mainHead()`, `openPulls()`, `pull(n)`, `files(n)`, `checkRuns(sha)`, `createBranch(name, sha)`,+ `mergeInto(branch, sha, message)` → `{ sha } | 'conflict'`, `openBatch(branch, title, body)`, `squash(n, sha, title, message)`+ → `{ sha }`, `close(n, comment)`, `deleteBranch(name)`. Every unexpected status throws `TrainReadError`.+- `mergeInto` refuses (throws) when GitHub answers 204 (nothing merged) or a result equal to a member's head: the train's+ ref never points at a member's commit.++- [ ] Test (fake fetch): each call's path, method, token permissions (`contents: write, pull_requests: write, checks: read`).+- [ ] Test: 500, 403, malformed bodies throw `TrainReadError`; `mergeInto` 409 → `'conflict'`; 204 throws.+- [ ] Code; commit.++### Task 3: One pass builds batches++**Files:** Create `mergeTrain/train.ts`, `mergeTrain/fakeTrainGitHub.ts` (tests only), `mergeTrain/train.test.ts`++**Interfaces:**+- Consumes: Task 1, Task 2's `TrainGitHub`.+- Produces: `trainPass(project, github, swarm, now, rules): Promise<TrainPassLine>`; `TrainSwarm { candidates(): TaskPull[];+ merged(taskId, url, mergedAt, commit): Promise<void>; tell(taskId, key, text): Promise<void> }`.++- [ ] Test: two eligible code PRs, no open batch → one `harness-train/` branch from main with both merged in, one batch PR+ whose body lists `#N@head` per member.+- [ ] Test: a conflicting PR drops out, the rest batch, and its owner is told "merge main once" once per head.+- [ ] Test: verdict not at head → not in any batch.+- [ ] Test: a fast-lane PR merges on its own green ci/required, no batch.+- [ ] Code; commit.++### Task 4: One pass finishes batches++**Files:** `mergeTrain/train.ts`, `mergeTrain/train.test.ts`++- [ ] Test: green batch → re-fetch heads, squash with `sha`, originals closed with a comment naming the batch and merge+ commit, `merged` recorded on each task with the original's URL, batch branch deleted, no task links the batch PR.+- [ ] Test: red batch of two components → closed, two split batches open; red batch of one → its owner told, PR not+ batched again at that head.+- [ ] Test: main moved (by anything but docs) → batch closed and rebuilt from the new main.+- [ ] Test: a member pushed after green → no merge, rebuilt without it.+- [ ] Test: kill switch off → no write at all; any read failure → no write for that batch.+- [ ] Code; commit.++### Task 5: Wiring and docs++**Files:** `backend/src/superTabs/store.ts` (`trainCandidates`, `trainMerged`, `trainTell`), `backend/src/worker.ts`+(`startMergeTrain`), `AGENTS.md` (merge section), `superTabs/pullRequestEvents.ts` (keep `train-*` keys)++- [ ] Test (store): `trainMerged` records the merge like `conversation.merged` with the original URL and marks no task+ Team-written; `trainTell` posts once per key to the task's Engineer.+- [ ] Code; AGENTS.md says the train merges routine work, how to hold a PR (`hold` label), the kill switch, and that hand+ merges still work. Commit.