Skip to content

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

Merge batch 11-06 j0345: #3215 #3226 #3237 (#3251)

0xken15abf97f12c4b8
diff --git a/AGENTS.md b/AGENTS.md
index 561453e90..481c7060f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -49,7 +49,17 @@ For product names, terminology, and visible copy, follow the
Do 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 old
planner 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 the
reviewed 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 only
diff --git a/backend/integration/superTabActivity.test.ts b/backend/integration/superTabActivity.test.ts
index 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 #324
const s = await scene()
const state = (await store.read(owner, s.tabId)).state as unknown as SuperTabState
const 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 string
const row = async () => (await rosterRows(store, host, 'test-host')).find(t => t.tabId === tab && t.agent.id === worker)!
expect(await row()).toMatchObject({ tabName: 'Pilot', attention: null })
- await run(tab, { type: 'work.status', conversationId: group, assignmentId, status: 'blocked', result: 'No access to staging.' } as Command, host, worker)
+ 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 string
const 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 Command
await 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 string
const 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 string
const 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]!.recipients
expect(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 quo
const 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 string
const 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 string
const [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.ts
index 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 ProjectRule
import { 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 | undefined
if (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.personId
else 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.hold
recordStatus(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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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 = 2
diff --git a/backend/src/superTabs/mergeTrain/fakeTrainGitHub.ts b/backend/src/superTabs/mergeTrain/fakeTrainGitHub.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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').TaskPriority
diff --git a/backend/src/superTabs/parts/light.test.ts b/backend/src/superTabs/parts/light.test.ts
index 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.ts
index 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 const
const LIGHT_GROUP = {
diff --git a/backend/src/superTabs/parts/touches.test.ts b/backend/src/superTabs/parts/touches.test.ts
index 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.ts
index 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.ts
index 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)) continue
seen.add(i)
- const t = tokens[i]
+ const t = i >= 0 ? tokens[i] : undefined
if (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) continue
if (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 false
states = close(next)
diff --git a/backend/src/superTabs/postRecipients.test.ts b/backend/src/superTabs/postRecipients.test.ts
index 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)).messages
return { f, rows: rows.filter(m => m.conversationId === f.task) }
}
diff --git a/backend/src/superTabs/read/contract.ts b/backend/src/superTabs/read/contract.ts
index 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.ts
index 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.ts
index 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)).messages
const post = (on: string, by = rev) =>
f.run({ type: 'message.send', conversationId: on, text: 'Two findings.', replyTo: null, recipientIds: [] } as Command, f.as(by)).messages
return { f, id, rev, status, post }
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index 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: st
const newest = (list: SuperTabMessage[]) => list.length ? Math.max(...list.map(m => m.sequence)) : undefined
return { 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 = 300
const 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.InputJsonValue
type 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.ts
index 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 CommandEffect
import { 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.ts
index 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, machineTea
import { 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.ts
index 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.ts
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.