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 j0850: #3228 (#3265)

0xken15e1452676d3ee
diff --git a/backend/integration/superTabReleases.test.ts b/backend/integration/superTabReleases.test.ts
new file mode 100644
index 000000000..8bfffec1e
--- /dev/null
+++ b/backend/integration/superTabReleases.test.ts
@@ -0,0 +1,136 @@
+import { randomUUID } from 'node:crypto'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'
+import { PrismaClient } from '@prisma/client'
+import type { AuthUser } from '../src/lib/ssoAuth.js'
+import { SuperTabStore } from '../src/superTabs/store.js'
+import type { Command } from '../src/superTabs/commands.js'
+import type { Conversation } from '../src/superTabs/model.js'
+import { pendingKey } from '../src/superTabs/releases.js'
+import { SEED_RULES } from '../src/superTabs/policy.js'
+
+// Task #3405: a recorded merge joins its project's release list; the worker's settle marks the tasks a verified release carries
+// released, and opens one release step for the Integrator inside the window, through the store and a fresh replica set.
+let replica: MongoMemoryReplSet
+let db: PrismaClient
+const owner: AuthUser = { sub: '340500000000000000000001', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
+const host: AuthUser = { sub: '340500000000000000000003', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
+const config = { engine: 'codex', model: 'fixture-model', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }
+/** 11:00 in Vietnam on 6 November 2026, inside the release window. */
+const T = Date.UTC(2026, 10, 6, 4, 0)
+const MINUTE = 60_000
+
+beforeAll(async () => {
+ replica = await MongoMemoryReplSet.create({ binary: { version: '7.0.24', downloadDir: join(tmpdir(), 'harness-super-tab-mongodb-binaries') },
+ replSet: { count: 1, ip: '127.0.0.1', storageEngine: 'wiredTiger' } })
+ const uri = replica.getUri(`releases_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 } })
+ await db.machine.create({ data: { machineId: 'test-host', userId: host.sub, apiKey: 'fixture-only', managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })
+ await db.machineShare.create({ data: { machineId: 'test-host', ownerId: host.sub, autonomousEnv: 'prod', emails: [owner.email] } })
+})
+afterAll(async () => {
+ await db?.$disconnect()
+ await replica?.stop()
+})
+
+async function swarm() {
+ let now = T
+ const store = new SuperTabStore(db, () => now)
+ const tab = (await store.create(owner, randomUUID(), 'Releases')).id
+ const run = (command: Command, user = owner, asAgentId?: string) => store.execute(user, tab, { operationId: randomUUID(), command }, asAgentId)
+ const invitation = await run({ type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })
+ await run({ type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)
+ await run({ type: 'machine.contribute', machineId: 'test-host', name: 'Mac', cwd: '/repo', engines: ['codex'], maxAgents: 6 }, host)
+ const add = async (name: string, conversationId: string, extra: Record<string, unknown> = {}) => String((await run({ type: 'agent.add', conversationId,
+ machineId: 'test-host', harnessId: randomUUID(), name, configuration: config, lead: false, ...extra } as Command)).result.agentId)
+ const lead = await add('Coordinator', 'lead', { lead: true })
+ // The task contract (#3389): an agent's task says a check, its priority and who asked.
+ const task = async (title: string) => String((await run({ type: 'conversation.create', title, brief: 'Build it.', priority: 'P2', requesterId: owner.sub,
+ checks: [{ description: 'It works.', independent: false }] }, host, lead)).result.conversationId)
+ const group = async (id: string) => (await db.swarmGroup.findUnique({ where: { tabId_key: { tabId: tab, key: id } } }))!.data as unknown as Conversation
+ const ledger = async () => {
+ const head = (await db.swarmHead.findUnique({ where: { id: `${tab}:head` } }))!.data as { projects: Array<{ releases?: { pending: unknown[]; steps?: Record<string, { groupId: string }> } }> }
+ return head.projects[0]!.releases
+ }
+ return { store, tab, run, add, lead, task, group, ledger, clock: { set(at: number) { now = at } } }
+}
+
+describe('releases scheduled by the Swarm', () => {
+ it('a recorded merge waits on the list until a verified release carries it, then the task is released', async () => {
+ const s = await swarm()
+ const shipIt = await s.task('Offline drafts')
+ const url = 'https://github.com/example/app/pull/41'
+ await s.run({ type: 'conversation.merged', conversationId: shipIt, pullRequestUrl: url, mergedAt: new Date(T - 30 * MINUTE).toISOString() }, host, s.lead)
+ expect((await s.ledger())!.pending).toEqual([{ groupId: shipIt, url, mergedAt: T - 30 * MINUTE }])
+ // After 18:00: the release shipped it, and no step opens.
+ s.clock.set(T + 8 * 60 * MINUTE)
+ const outcome = await s.store.settleReleases(s.tab, 'lead', { resolved: [{ groupId: shipIt, url, components: ['desktop'], sha: 'm41' }],
+ releases: { desktop: { tag: 'v1.3.78_desktop', sha: 'd1', at: T - 5 * MINUTE, carries: [pendingKey({ groupId: shipIt, url })] } } })
+ expect(outcome).toMatchObject({ shipped: [shipIt], opened: null })
+ expect((await s.group(shipIt)).released).toEqual({ at: T - 5 * MINUTE, tags: ['v1.3.78_desktop'] })
+ expect((await s.ledger())!.pending).toEqual([])
+ })
+
+ it('opens one release step inside the window and tells the Integrator, and a second settle opens none', async () => {
+ const s = await swarm()
+ const integrator = await s.add('Shipper', 'lead', { roleName: 'Integrator' })
+ const shipIt = await s.task('Board strip')
+ const url = 'https://github.com/example/app/pull/42'
+ await s.run({ type: 'conversation.merged', conversationId: shipIt, pullRequestUrl: url, mergedAt: new Date(T - MINUTE).toISOString() }, host, s.lead)
+ const facts = { resolved: [{ groupId: shipIt, url, components: ['cli' as const] }], releases: {} }
+ const outcome = (await s.store.settleReleases(s.tab, 'lead', facts))!
+ expect(outcome.opened).toEqual(expect.any(String))
+ const step = await s.group(outcome.opened!)
+ expect(step).toMatchObject({ title: 'Release CLI', priority: 'P1', assignment: null })
+ expect(step.agentIds).toContain(integrator)
+ const rows = await db.superTabMessage.findMany({ where: { tabId: s.tab, conversationId: outcome.opened! } })
+ expect(rows.map(r => r.recipientIds)).toEqual([[integrator]])
+ expect(await db.superTabDelivery.count({ where: { tabId: s.tab, agentId: integrator, messageId: rows[0]!.id } })).toBe(1)
+ s.clock.set(T + 5 * MINUTE)
+ expect((await s.store.settleReleases(s.tab, 'lead', facts))!.opened).toBeNull()
+ const groups = await db.swarmGroup.findMany({ where: { tabId: s.tab }, select: { data: true } })
+ expect(groups.filter(g => (g.data as unknown as Conversation).title === 'Release CLI')).toHaveLength(1)
+ })
+
+ // River, 11-06: the window and pace come from the project rules record (#3393), which people edit without a release.
+ it('reads the window from the project\'s rules record: a window from 10:00 opens no step at 09:30', async () => {
+ const s = await swarm()
+ await s.add('Shipper', 'lead', { roleName: 'Integrator' })
+ const shipIt = await s.task('Later window')
+ const url = 'https://github.com/example/app/pull/43'
+ await s.run({ type: 'conversation.merged', conversationId: shipIt, pullRequestUrl: url, mergedAt: new Date(T - MINUTE).toISOString() }, host, s.lead)
+ await s.run({ type: 'rules.set', projectId: 'lead', baseRevision: 0, summary: 'Releases start at 10',
+ rules: { ...structuredClone(SEED_RULES), releaseWindow: { ...SEED_RULES.releaseWindow, start: '10:00' },
+ releasePace: { ...SEED_RULES.releasePace, backendPause: null } } } as Command)
+ const facts = { resolved: [{ groupId: shipIt, url, components: ['cli' as const] }], releases: {} }
+ // 09:30 in Vietnam: inside the seed's window, outside this project's.
+ s.clock.set(Date.UTC(2026, 10, 6, 2, 30))
+ expect((await s.store.settleReleases(s.tab, 'lead', facts))!.opened).toBeNull()
+ s.clock.set(Date.UTC(2026, 10, 6, 3, 0))
+ expect((await s.store.settleReleases(s.tab, 'lead', facts))!.opened).toEqual(expect.any(String))
+ })
+
+ it('reads the backend pause from the record, the seed\'s only while the project has none', async () => {
+ const s = await swarm()
+ await s.add('Shipper', 'lead', { roleName: 'Integrator' })
+ const shipIt = await s.task('Morning backend')
+ const url = 'https://github.com/example/app/pull/44'
+ await s.run({ type: 'conversation.merged', conversationId: shipIt, pullRequestUrl: url, mergedAt: new Date(T - 3 * 60 * MINUTE).toISOString() }, host, s.lead)
+ const facts = { resolved: [{ groupId: shipIt, url, components: ['backend' as const] }], releases: {} }
+ // 09:30 in Vietnam, in the seed's 09:00-10:00 backend pause: no record yet, so no step.
+ s.clock.set(Date.UTC(2026, 10, 6, 2, 30))
+ expect((await s.store.settleReleases(s.tab, 'lead', facts))!.opened).toBeNull()
+ await s.run({ type: 'rules.set', projectId: 'lead', baseRevision: 0, summary: 'No morning pause',
+ rules: { ...structuredClone(SEED_RULES), releasePace: { ...SEED_RULES.releasePace, backendPause: null } } } as Command)
+ s.clock.set(Date.UTC(2026, 10, 6, 2, 35))
+ expect((await s.store.settleReleases(s.tab, 'lead', facts))!.opened).toEqual(expect.any(String))
+ })
+})
diff --git a/backend/src/github/app.ts b/backend/src/github/app.ts
index aa60fcf85..adc761102 100644
--- a/backend/src/github/app.ts
+++ b/backend/src/github/app.ts
@@ -36,6 +36,9 @@ export const ACTIONS_READ_PERMISSIONS = { actions: 'read', metadata: 'read' } as
export const PUSH_ORIGIN_PERMISSIONS = { contents: 'read', pull_requests: 'read', metadata: 'read' } as const
/** What watching a task's pull request for its Engineer reads (superTabs/pullRequestEvents.ts): the pull request, its reviews
* and comments, and its head's checks. All already among the app's permissions ([TOKEN_PERMISSIONS]). */
+/** The release watch (superTabs/releaseWatch.ts): release workflow runs, where their tags sit on the default branch, and a
+ * pull request's files. */
+export const RELEASE_READ_PERMISSIONS = { contents: 'read', pull_requests: 'read', actions: 'read', metadata: 'read' } as const
export const PULL_WATCH_PERMISSIONS = { pull_requests: 'read', checks: 'read', metadata: 'read' } as const
/** The watch's answers kept for conditional reads: an unchanged one comes back 304, which GitHub's rate limit does not count. */
const WATCH_KEPT = 2000
@@ -457,6 +460,14 @@ export class GitHubApp {
/** Ends [token] at once (DELETE /installation/token, authorised by the token itself). One GitHub already ended reads as
* done. */
+ /** One GET of [path] with an installation [token], for readers that page and judge answers themselves (superTabs/releaseWatch.ts):
+ * its status, body, and the next page's path from the Link header. Throws [GitHubAppError] when GitHub does not answer. */
+ async get(path: string, token: string): Promise<{ status: number; body: unknown; next?: string }> {
+ const answer = await this.call('GET', path, `Bearer ${token}`)
+ const next = /<https:\/\/[^/>]+(\/[^>]+)>;\s*rel="next"/.exec(answer.link ?? '')?.[1]
+ return { status: answer.status, body: answer.body, ...(next ? { next } : {}) }
+ }
+
async revoke(token: string): Promise<void> {
const answer = await this.call('DELETE', '/installation/token', `Bearer ${token}`)
if (answer.status === 204 || answer.status === 401) return
diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.ts
index 877ef7ed6..f2c825641 100644
--- a/backend/src/superTabs/commands.test.ts
+++ b/backend/src/superTabs/commands.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, it } from 'vitest'
+import { groupProject } from './projects.js'
import { storeOldLeads } from './leads.test-support.js'
import { applyCommand, assertUniqueMessageIds, commandSchema, LOOP_NOTICE_AT, swarmGridName, withoutCredentials, type Command, type CommandContext } from './commands.js'
import { CREDENTIAL_MARKER, type CredentialKind } from './credentials.js'
@@ -5021,6 +5022,17 @@ describe('linked tasks', () => {
expect(task(R).ledger?.shippedAt).toEqual(expect.any(Number))
})
+ // Task #3405: the merge record puts the task on its project's release list, once, for the next verified release.
+ it('puts a recorded merge on the project\'s release list once', () => {
+ const { f, T, E, create } = linked()
+ const R = create('Fix the flaky test', T), url = 'https://github.com/example/app/pull/9'
+ const list = () => groupProject(f.state, f.state.conversations.find(c => c.id === R)!).releases?.pending
+ f.run({ type: 'conversation.merged', conversationId: R, pullRequestUrl: url, mergedAt: new Date(900).toISOString() }, E)
+ expect(list()).toEqual([{ groupId: R, url, mergedAt: 900 }])
+ f.run({ type: 'conversation.merged', conversationId: R, pullRequestUrl: url, mergedAt: new Date(900).toISOString() }, E)
+ expect(list()).toHaveLength(1)
+ })
+
it('archives a linked task without a verdict', () => {
const { f, T, E, create, task } = linked()
const R = create('Review', T)
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index c7b93f5c2..f772c17ae 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -52,6 +52,7 @@ import { react, reactionSchema, type ReactionTarget } from './reactions.js'
import { deleteMessage, editMessage, type MessageChangeTarget } from './messageEdits.js'
import { githubRepository } from '../github/repository.js'
import { shippedAt } from './ship.js'
+import { notePendingRelease } from './releases.js'
import { syncTaskLines } from './taskLine.js'
import { assignedNotice, tellBuddies } from './buddyNews.js'
import { bindPullRequestCards, bindTaskCard, pullRequestCard, recordCardMerged } from './cards.js'
@@ -2667,6 +2668,9 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
const shippedAt = group.ledger?.shippedAt, linked = group.pullRequestUrls?.includes(pullRequestUrl)
appendPullRequestUrls(group, [pullRequestUrl], repositoryUrl)
recordMerged(group, mergedAt)
+ // On its project's release list, for the next verified release to mark it shipped (releases.ts, task #3405). A Swarm from
+ // before projects keeps no list: its one project is not stored.
+ if (state.projects) notePendingRelease(groupProject(state, group), group, pullRequestUrl, mergedAt)
// Like a Slack app's update: the card shows the merge, and the line goes in the card's thread, once per pull request.
// Without a card yet, the group's first ship or a new link still says so, and the line becomes the card. A fix of an
// earlier merge says so once more.
diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.ts
index d896f22c8..52f57990b 100644
--- a/backend/src/superTabs/model.ts
+++ b/backend/src/superTabs/model.ts
@@ -429,6 +429,9 @@ export interface Conversation {
requesterId?: string
/** What the leaderboard counts here (leaderboard/record.ts); bookkeeping readers never get whole. */
ledger?: import('./leaderboard/record.js').GroupLedger
+ /** When a verified release carried its last recorded merge to people, and the release tags that did (releases.ts, task #3405):
+ * the board's Shipped. Absent while a release it needs has not gone out, and on work merged before the server recorded it. */
+ released?: { at: number; tags: string[] }
/** Whether its task is moving, waiting on purpose or stuck, as the time checks last found it (liveness.ts recordTaskStates). */
liveness?: TaskLiveness
/** Its last step up from a cheaper model: written when a grid attempt's first review fails (commands.ts reviewFailed, goals
@@ -726,6 +729,8 @@ export const NOTICE_READERS = {
// Their one Buddy cannot start in a person's older project chat, told to them there once per outage (commands.ts buddyDownLine).
'buddy-cannot-start': 'people',
'auto-archive': 'people', native: 'people',
+ // A release step the Swarm opened for the Integrator, and its verified release's line (releases.ts, task #3405).
+ release: 'people',
// The nightly routing reflection, for the project's people; never a Buddy's (buddies.ts routingRow).
'routing-reflection': 'people',
// No new agent can start, or soon none will, told to the coordinator; with none in the chat, people read it, tagging who can
diff --git a/backend/src/superTabs/parts/light.test.ts b/backend/src/superTabs/parts/light.test.ts
index 76f068f24..50c6c1e73 100644
--- a/backend/src/superTabs/parts/light.test.ts
+++ b/backend/src/superTabs/parts/light.test.ts
@@ -15,7 +15,7 @@ const conversation: Required<Conversation> = {
id: 'g', kind: 'leads', projectId: 'p', number: 1, title: 't', leadId: null, agentIds: [], archived: false, brief: '',
task: { goal: '', changes: '', constraints: '', owns: [] }, reviewOf: 'r', 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 },
+ requesterId: 'p', ledger: {}, released: { at: 1, tags: [] }, 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', hold: { kind: 'requester' }, priority: 'P0', lane: 'Desktop', handOutLane: 'Desktop', pin: { agentId: 'a', why: 'ci', at: 1 }, owed: [], pulse: {} as never,
}
diff --git a/backend/src/superTabs/parts/light.ts b/backend/src/superTabs/parts/light.ts
index d551d918c..1dce3b748 100644
--- a/backend/src/superTabs/parts/light.ts
+++ b/backend/src/superTabs/parts/light.ts
@@ -28,7 +28,7 @@ export const GROUP_FIELDS = {
always: ['id', 'kind', 'projectId', 'leadId', 'agentIds', 'archived', 'audience', 'dormant', 'assignment.id', 'assignment.agentId', 'assignment.status',
'assignment.lost', 'reviewOf', 'pulse'],
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', 'hold', 'priority', 'owed', 'lane', 'handOutLane', 'pin',
+ 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', 'released', 'owed', 'lane', 'handOutLane', 'pin',
'assignment.configuration', 'assignment.recordingProgress', 'assignment.leaseUntil', 'assignment.progressAt', 'assignment.nudgedAt', 'assignment.askedOf', 'assignment.hold', 'assignment.reviewFoundAt', 'assignment.changesRequestedAt', 'assignment.toldEngineerAt',
'assignment.reopened', 'assignment.handoffs', 'assignment.verdicts'],
} as const
diff --git a/backend/src/superTabs/projects.ts b/backend/src/superTabs/projects.ts
index df6bdce64..c6f928076 100644
--- a/backend/src/superTabs/projects.ts
+++ b/backend/src/superTabs/projects.ts
@@ -56,6 +56,9 @@ export interface SwarmProject {
* the daily tidy was last asked, and the instructions revision its last save made; `tidyPending`: asked, and no save has
* followed yet (pmSchedule.ts tidyRequest; tasks #3022, #3151). */
schedule?: { lastSlot: number; wakeId?: string; heardAt?: number; tidiedOn?: string; tidiedRevision?: number; tidyPending?: boolean }
+ /** Its release list (releases.ts, task #3405): merged tasks waiting for a release, each component's last verified release
+ * and its open release step. Written by the server alone; readers never get it. */
+ releases?: import('./releases.js').ReleaseLedger
/** The status card at the top of the project chat (Dee, 2026-10-31): the coordinator's last project.report text, which
* replaces the one before and posts nothing. Read exactly by those who read the project chat (model.ts visibleState). */
status?: ProjectStatus | null
diff --git a/backend/src/superTabs/read/views.test.ts b/backend/src/superTabs/read/views.test.ts
index deb54a755..87e54b9a9 100644
--- a/backend/src/superTabs/read/views.test.ts
+++ b/backend/src/superTabs/read/views.test.ts
@@ -210,6 +210,13 @@ describe('instructions in the reader\'s view (project instructions, phase 2)', (
expect(readerView(store.split(s.state, { tabId: 'tab', version: R, now: NOW }), owner, NOW, { teamMachines: [] }).parts.head.data.projects![0]!.coordinatorName)
.toBe('Lead engineer')
})
+ // Task #3405: the release list is the server's bookkeeping, like the schedule; no reader gets it.
+ it('sends projects without their release list', () => {
+ const { s } = scene()
+ s.edit(state => { state.projects![0]!.releases = { pending: [{ groupId: 'g', url: 'https://github.com/o/r/pull/1', mergedAt: NOW }] } })
+ const head = readerView(store.split(s.state, { tabId: 'tab', version: R, now: NOW }), owner, NOW, { teamMachines: [] }).parts.head
+ expect(head.data.projects!.every(p => !('releases' in p))).toBe(true)
+ })
})
// Task #3384: the board's pulse is cross-part and timed, so it goes in `derived`, for each project the reader sees; what it is
diff --git a/backend/src/superTabs/read/views.ts b/backend/src/superTabs/read/views.ts
index 120c34559..0d9106809 100644
--- a/backend/src/superTabs/read/views.ts
+++ b/backend/src/superTabs/read/views.ts
@@ -105,8 +105,9 @@ export function readerView(parts: SwarmParts, actor: Actor, now: number, extras:
const agentPart = part(parts.agents), groupPart = part(parts.groups), machinePart = part(parts.machines), startPart = part(parts.starts)
const head = Object.fromEntries(HEAD_FIELDS.filter(field => visible[field] !== undefined).map(field => [field, visible[field]])) as HeadView
// Every project names its coordinator; one from before the field reads as the Product Manager (instructions.ts). The built-in
- // schedule's slot is the coordinator poll's bookkeeping (pmSchedule.ts), like progress: no reader shows it.
- if (head.projects) head.projects = head.projects.map(({ progress: _progress, schedule: _schedule, ...project }) => ({ ...project, coordinatorName: coordinatorNameOf(project) }))
+ // schedule's slot is the coordinator poll's bookkeeping (pmSchedule.ts), like progress, and so is the release list (releases.ts):
+ // no reader shows them.
+ if (head.projects) head.projects = head.projects.map(({ progress: _progress, schedule: _schedule, releases: _releases, ...project }) => ({ ...project, coordinatorName: coordinatorNameOf(project) }))
head.invitations = visible.invitations.filter(i => readable.has(i.conversationId))
const projects = new Set((visible.projects ?? []).map(p => p.id)), seen = seenMachineIds(visible), names = swarmUsernames(state)
const buddy = isBuddyReader(state, actor)
diff --git a/backend/src/superTabs/releaseWatch.test.ts b/backend/src/superTabs/releaseWatch.test.ts
new file mode 100644
index 000000000..e2ab41525
--- /dev/null
+++ b/backend/src/superTabs/releaseWatch.test.ts
@@ -0,0 +1,216 @@
+import { describe, expect, it } from 'vitest'
+import type { PrismaClient } from '@prisma/client'
+import { batchLookupDue, readReleases, watchReleases, type GitHubGet, type ReleaseReader } from './releaseWatch.js'
+import type { ReleaseFacts, ReleaseLedger } from './releases.js'
+import { componentNamed, pendingKey } from './releases.js'
+
+const REPO = { owner: 'acme', name: 'app', fullName: 'acme/app' }
+const T = Date.UTC(2026, 10, 6, 4, 0)
+const run = (over: Record<string, unknown> = {}) => ({ head_branch: 'v1.3.78_desktop', head_sha: 'd1', event: 'push', conclusion: 'success',
+ run_started_at: new Date(T).toISOString(), created_at: new Date(T).toISOString(), ...over })
+
+/** A fake GitHub answering [routes] by path prefix; it records each path asked. */
+function github(routes: Record<string, { status: number; body: unknown; next?: string }>) {
+ const asked: string[] = []
+ const get: GitHubGet = async (_repository, path) => {
+ asked.push(path)
+ const hit = Object.keys(routes).find(key => path === key || path.startsWith(`${key}?`) || (key.endsWith('/') && path.startsWith(key)))
+ return hit ? routes[hit]! : { status: 404, body: {} }
+ }
+ return { get, asked }
+}
+const repo = { status: 200, body: { default_branch: 'main' } }
+const onMain = (committed: number, status = 'ahead') => ({ status: 200, body: { status, base_commit: { commit: { committer: { date: new Date(committed).toISOString() } } } } })
+
+describe('readReleases.latest', () => {
+ it('takes the highest successful tag push of the component\'s own workflow, on main', async () => {
+ const g = github({
+ '/repos/acme/app/actions/workflows/release-desktop.yml/runs': { status: 200, body: { workflow_runs: [
+ run({ head_branch: 'main', event: 'schedule' }), run({ head_branch: 'v1.3.78_desktop-candidate' }),
+ // A re-run of an older tag's workflow, listed first: the higher version still wins.
+ run({ head_branch: 'v1.3.77_desktop', head_sha: 'd0', run_started_at: new Date(T + 60_000).toISOString() }), run()] } },
+ '/repos/acme/app/compare/d1...main': onMain(T - 60_000),
+ '/repos/acme/app': repo,
+ })
+ expect(await readReleases(g.get).latest(REPO, componentNamed('desktop'))).toEqual({ tag: 'v1.3.78_desktop', sha: 'd1', at: T })
+ expect(g.asked[0]).toBe('/repos/acme/app/actions/workflows/release-desktop.yml/runs?event=push&status=success&per_page=30')
+ })
+
+ it('says none for a repository without that workflow or any release, and for a tag not on main', async () => {
+ expect(await readReleases(github({ '/repos/acme/app': repo }).get).latest(REPO, componentNamed('cli'))).toBeUndefined()
+ const empty = github({ '/repos/acme/app/actions/workflows/release.yml/runs': { status: 200, body: { workflow_runs: [] } }, '/repos/acme/app': repo })
+ expect(await readReleases(empty.get).latest(REPO, componentNamed('cli'))).toBeUndefined()
+ const off = github({ '/repos/acme/app/actions/workflows/release-desktop.yml/runs': { status: 200, body: { workflow_runs: [run()] } },
+ '/repos/acme/app/compare/d1...main': onMain(T, 'diverged'), '/repos/acme/app': repo })
+ expect(await readReleases(off.get).latest(REPO, componentNamed('desktop'))).toBeUndefined()
+ })
+
+ it('says it cannot tell (null) when GitHub fails, so nothing is marked on a guess', async () => {
+ const down = github({ '/repos/acme/app/actions/workflows/release-desktop.yml/runs': { status: 502, body: {} }, '/repos/acme/app': repo })
+ expect(await readReleases(down.get).latest(REPO, componentNamed('desktop'))).toBeNull()
+ const compare = github({ '/repos/acme/app/actions/workflows/release-desktop.yml/runs': { status: 200, body: { workflow_runs: [run()] } },
+ '/repos/acme/app/compare/': { status: 500, body: {} }, '/repos/acme/app': repo })
+ expect(await readReleases(compare.get).latest(REPO, componentNamed('desktop'))).toBeNull()
+ })
+})
+
+describe('readReleases.files', () => {
+ it('reads every page of a pull request\'s files, renames by both names', async () => {
+ const g = github({
+ '/repos/acme/app/pulls/7/files?per_page=100&page=2': { status: 200, body: [{ filename: 'cli/src/b.ts' }] },
+ '/repos/acme/app/pulls/7/files': { status: 200, body: [{ filename: 'desktop/lib/a.dart', previous_filename: 'desktop/lib/old.dart' }], next: '/repos/acme/app/pulls/7/files?per_page=100&page=2' },
+ })
+ expect(await readReleases(g.get).files(REPO, 7)).toEqual(['desktop/lib/a.dart', 'desktop/lib/old.dart', 'cli/src/b.ts'])
+ expect(await readReleases(github({}).get).files(REPO, 8)).toBeNull()
+ })
+})
+
+describe('readReleases.mergeCommit and contains', () => {
+ it('takes a merged pull request\'s own merge commit', async () => {
+ const g = github({ '/repos/acme/app/pulls/7': { status: 200, body: { merged_at: new Date(T).toISOString(), merge_commit_sha: 'm7' } } })
+ expect(await readReleases(g.get).mergeCommit(REPO, 7, T)).toBe('m7')
+ })
+
+ it('finds the batch commit on main that closed an original pull request, the oldest one naming it', async () => {
+ const g = github({
+ '/repos/acme/app/pulls/7': { status: 200, body: { merged_at: null, state: 'closed' } },
+ '/repos/acme/app/commits': { status: 200, body: [
+ { sha: 'later', commit: { message: 'Fix the follow-up of #7' } },
+ { sha: 'other', commit: { message: 'Merge batch i1: #70 #71 (#80)' } },
+ { sha: 'batch', commit: { message: 'Merge batch i0: #6 #7 (#79)' } }] },
+ '/repos/acme/app': repo,
+ })
+ expect(await readReleases(g.get).mergeCommit(REPO, 7, T)).toBe('batch')
+ expect(g.asked.at(-1)).toBe(`/repos/acme/app/commits?sha=main&since=${new Date(T - 6 * 3_600_000).toISOString()}&until=${new Date(T + 3_600_000).toISOString()}&per_page=100`)
+ expect(await readReleases(github({ '/repos/acme/app/pulls/7': { status: 502, body: {} } }).get).mergeCommit(REPO, 7, T)).toBeNull()
+ })
+
+ // Review 2 of #3228: on main, squash titles carry task numbers ("… (#3159)") and batch bodies name other pull requests.
+ it('takes only a batch title naming the original, never a task number in another title or a mention in a batch\'s body', async () => {
+ const g = github({
+ '/repos/acme/app/pulls/7': { status: 200, body: { merged_at: null, state: 'closed' } },
+ '/repos/acme/app/commits': { status: 200, body: [
+ { sha: 'real', commit: { message: 'Merge batch i2: #6 #7 (#80)' } },
+ { sha: 'mention', commit: { message: 'Merge batch i1: #5 (#79)\n\nIncludes the fix #7 needed.' } },
+ { sha: 'task', commit: { message: 'The board says so (#7)' } }] },
+ '/repos/acme/app': repo,
+ })
+ expect(await readReleases(g.get).mergeCommit(REPO, 7, T)).toBe('real')
+ const none = github({ '/repos/acme/app/pulls/7': { status: 200, body: { merged_at: null } }, '/repos/acme/app': repo,
+ '/repos/acme/app/commits': { status: 200, body: [{ sha: 'task', commit: { message: 'The board says so (#7)' } }, { sha: 'b', commit: { message: 'Merge batch i3: #70 (#81)' } }] } })
+ expect(await readReleases(none.get).mergeCommit(REPO, 7, T)).toBeNull()
+ })
+
+ it('looks for a batch every pass in the merge\'s first hour, then every 30 minutes, then every 2 hours after a day', () => {
+ const HOUR = 3_600_000, half = 30 * 60_000, at = 100 * 24 * HOUR
+ expect(batchLookupDue(at, at + 10 * 60_000 + 7)).toBe(true)
+ expect(batchLookupDue(at, at + 3 * HOUR)).toBe(true)
+ expect(batchLookupDue(at, at + 3 * HOUR + 5 * 60_000)).toBe(false)
+ expect(batchLookupDue(at, at + 2 * 24 * HOUR)).toBe(true)
+ expect(batchLookupDue(at, at + 2 * 24 * HOUR + half)).toBe(false)
+ })
+
+ it('says a tag contains a merge when main\'s history from the merge reaches the tag', async () => {
+ const answer = (status: string) => github({ '/repos/acme/app/compare/m7...t1': { status: 200, body: { status } } }).get
+ expect(await readReleases(answer('identical')).contains(REPO, 'm7', 't1')).toBe(true)
+ expect(await readReleases(answer('ahead')).contains(REPO, 'm7', 't1')).toBe(true)
+ expect(await readReleases(answer('behind')).contains(REPO, 'm7', 't1')).toBe(false)
+ expect(await readReleases(github({}).get).contains(REPO, 'm7', 't1')).toBeNull()
+ })
+})
+
+describe('watchReleases', () => {
+ const ledger = (over: Partial<ReleaseLedger> = {}): ReleaseLedger => ({ pending: [
+ { groupId: 'g1', url: 'https://github.com/acme/app/pull/7', mergedAt: T - 1 },
+ { groupId: 'g2', url: 'https://github.com/acme/app/pull/8', mergedAt: T - 1, components: ['backend'] },
+ { groupId: 'g3', url: 'https://github.com/acme/app/pull/9', mergedAt: T - 1 },
+ ], ...over })
+ function scene(releases: ReleaseLedger | undefined, reader: Partial<ReleaseReader> = {}) {
+ const head = { deleted: false, data: { projects: [
+ { id: 'p1', leadConversationId: 'lead', repository: { machineId: 'm', cwd: '/r', repositoryUrl: 'https://github.com/acme/app' }, ...releases ? { releases } : {} },
+ { id: 'p2', leadConversationId: 'lead2' }] } }
+ const db = {
+ superTabModelEvidence: { aggregateRaw: async () => [{ _id: { tabId: 'tab', projectId: 'p1' } }, { _id: { tabId: 'tab', projectId: 'p2' } }] },
+ swarmHead: { findUnique: async () => head },
+ } as unknown as PrismaClient
+ const settled: Array<{ tabId: string; projectId: string; facts: ReleaseFacts }> = []
+ const store = { settleReleases: async (tabId: string, projectId: string, facts: ReleaseFacts) => { settled.push({ tabId, projectId, facts }); return { messages: [], shipped: [], opened: null, dropped: [] } } }
+ const read: string[] = []
+ const fake: ReleaseReader = {
+ files: async (_repo, number) => { read.push(`files ${number}`); return number === 7 ? ['desktop/lib/a.dart'] : null },
+ latest: async (_repo, component) => { read.push(`latest ${component.id}`); return component.id === 'backend' ? { tag: 'v1.4.17_backend', sha: 'b', at: T } : null },
+ mergeCommit: async (_repo, number) => { read.push(`merge ${number}`); return `m${number}` },
+ contains: async (_repo, base, head) => { read.push(`contains ${base} ${head}`); return true },
+ done: async () => { read.push('done') },
+ ...reader,
+ }
+ return { db, store, settled, read, fake }
+ }
+
+ it('reads each new entry\'s files once, only the components something waits for, and settles with what it read', async () => {
+ const s = scene(ledger())
+ await watchReleases(s.db, s.store, s.fake, T, { warn: () => {}, info: () => {} })
+ expect(s.read).toEqual(['files 7', 'merge 7', 'merge 8', 'files 9', 'latest backend', 'contains m8 b', 'latest desktop', 'latest web', 'done'])
+ expect(s.settled).toEqual([{ tabId: 'tab', projectId: 'p1', facts: {
+ // g1's merge commit waits for Desktop and Web, which GitHub could not read: it is found again next pass.
+ resolved: [{ groupId: 'g1', url: 'https://github.com/acme/app/pull/7', components: ['desktop', 'web'] },
+ { groupId: 'g2', url: 'https://github.com/acme/app/pull/8', sha: 'm8' }],
+ releases: { backend: { tag: 'v1.4.17_backend', sha: 'b', at: T, carries: [pendingKey({ groupId: 'g2', url: 'https://github.com/acme/app/pull/8' })] } } } }])
+ })
+
+ it('reads an open step\'s component too, and nothing for a project with nothing to settle', async () => {
+ const s = scene({ pending: [], steps: { cli: { groupId: 's', at: T } } })
+ await watchReleases(s.db, s.store, s.fake, T, { warn: () => {}, info: () => {} })
+ expect(s.read).toEqual(['latest cli', 'done'])
+ const quiet = scene({ pending: [] })
+ await watchReleases(quiet.db, quiet.store, quiet.fake, T, { warn: () => {}, info: () => {} })
+ expect(quiet.settled).toEqual([])
+ })
+
+ it('says each project it could not read, and goes on', async () => {
+ const warned: string[] = []
+ const s = scene(ledger(), { files: async () => { throw new Error('boom') } })
+ await watchReleases(s.db, s.store, s.fake, T, { warn: message => { warned.push(message) }, info: () => {} })
+ expect(warned).toEqual(['[swarm-releases] project skipped'])
+ expect(s.read.at(-1)).toBe('done')
+ })
+
+ it('compares again only for a new tag or a newly resolved merge, and leaves out a release whose comparison GitHub could not answer', async () => {
+ const known = { pending: [{ groupId: 'g2', url: 'https://github.com/acme/app/pull/8', mergedAt: T - 1, components: ['backend' as const], sha: 'm8' }],
+ last: { backend: { tag: 'v1.4.17_backend', sha: 'b', at: T } } }
+ const same = scene(known)
+ await watchReleases(same.db, same.store, same.fake, T, { warn: () => {}, info: () => {} })
+ expect(same.read).toEqual(['latest backend', 'done'])
+ const unsure = scene({ ...known, last: {} }, { contains: async () => null })
+ await watchReleases(unsure.db, unsure.store, unsure.fake, T, { warn: () => {}, info: () => {} })
+ expect(unsure.settled[0]!.facts.releases).toEqual({})
+ })
+
+ // Review of #3228: the merge is recorded 20 s after its commit landed, and the CLI release is tagged on that very commit.
+ it('ships a merge recorded after its commit landed, in the release tagged on that commit', async () => {
+ const commitAt = T, recordedAt = T + 20_000
+ const g = github({
+ '/repos/acme/app/pulls/7': { status: 200, body: { merged_at: new Date(commitAt).toISOString(), merge_commit_sha: 'm7' } },
+ '/repos/acme/app/actions/workflows/release.yml/runs': { status: 200, body: { workflow_runs: [run({ head_branch: 'v0.5.55_cli', head_sha: 'm7',
+ run_started_at: new Date(T + 5 * 60_000).toISOString() })] } },
+ '/repos/acme/app/compare/m7...main': { status: 200, body: { status: 'identical' } },
+ '/repos/acme/app/compare/m7...m7': { status: 200, body: { status: 'identical' } },
+ '/repos/acme/app': repo,
+ })
+ const s = scene({ pending: [{ groupId: 'g1', url: 'https://github.com/acme/app/pull/7', mergedAt: recordedAt, components: ['cli'] }] },
+ { ...readReleases(g.get), done: async () => {} })
+ await watchReleases(s.db, s.store, s.fake, T + 6 * 60_000, { warn: () => {}, info: () => {} })
+ expect(s.settled[0]!.facts.releases.cli).toEqual({ tag: 'v0.5.55_cli', sha: 'm7', at: T + 5 * 60_000,
+ carries: [pendingKey({ groupId: 'g1', url: 'https://github.com/acme/app/pull/7' })] })
+ })
+
+ // Review 2 of #3228: a merge commit found in a pass whose comparison GitHub could not answer is found again, so the tag
+ // already settled is still compared with it.
+ it('keeps no merge commit found in a pass whose comparison was unsure', async () => {
+ const s = scene({ pending: [{ groupId: 'g2', url: 'https://github.com/acme/app/pull/8', mergedAt: T - 1, components: ['backend'] }],
+ last: { backend: { tag: 'v1.4.17_backend', sha: 'b', at: T } } }, { contains: async () => null })
+ await watchReleases(s.db, s.store, s.fake, T, { warn: () => {}, info: () => {} })
+ expect(s.read).toContain('merge 8')
+ expect(s.settled[0]!.facts).toEqual({ resolved: [], releases: {} })
+ })
+})
diff --git a/backend/src/superTabs/releaseWatch.ts b/backend/src/superTabs/releaseWatch.ts
new file mode 100644
index 000000000..6ecb761bc
--- /dev/null
+++ b/backend/src/superTabs/releaseWatch.ts
@@ -0,0 +1,281 @@
+/**
+ * The release watch (task #3405): every 5 minutes the singleton worker reads GitHub for each project with a release list to
+ * settle, and hands what it read to the store's one write (store.ts settleReleases, releases.ts). A component's verified
+ * release is its own release workflow's newest successful run on a pushed release tag (`v1.3.78_desktop`): that workflow
+ * builds and checks the release's artifacts, so its success is the tag plus its artifacts. Only a tag on the default branch
+ * counts. A release carries a task when GitHub says its tag contains the task's merge commit on main (its pull request's own
+ * merge commit, or the batch commit that closed it): by ancestry, never by when the merge was recorded, which comes after the
+ * merge (review of #3228). Every read fails closed: a read GitHub does not answer marks nothing and
+ * opens nothing, and the pass says which projects it could not read.
+ */
+import type { PrismaClient } from '@prisma/client'
+import { RELEASE_READ_PERMISSIONS, type GitHubApp } from '../github/app.js'
+import { githubRepository, type GitHubRepository } from '../github/repository.js'
+import { reflectionCandidates } from '../lib/routingReflection.js'
+import type { SuperTabState } from './model.js'
+import { projectsOf } from './projects.js'
+import { compareTags, componentsOf, isReleaseTag, PENDING_MAX, pendingKey, RELEASE_COMPONENTS, type PendingRelease, type ReleaseComponent,
+ type ReleaseComponentId, type ReleaseFacts, type VerifiedRelease } from './releases.js'
+import type { SuperTabStore } from './store.js'
+import { logger } from '../utils/logger.js'
+
+/** One GET in [repository]: its status (0 when it could not be asked), body, and the next page's path. */
+export type GitHubGet = (repository: GitHubRepository, path: string) => Promise<{ status: number; body: unknown; next?: string }>
+
+/** What the watch asks GitHub. `files`: a pull request's changed files, null when GitHub cannot say. `mergeCommit`: the
+ * commit on the default branch that merged pull request [number], recorded as merged at [mergedAt]; null when GitHub cannot
+ * say or it is not found yet. `latest`: a component's newest verified release on the default branch, undefined when there
+ * is none, null when GitHub cannot say. `contains`: whether commit [head] has commit [base] in its history; null when
+ * GitHub cannot say. */
+export interface ReleaseReader {
+ files(repository: GitHubRepository, number: number): Promise<string[] | null>
+ mergeCommit(repository: GitHubRepository, number: number, mergedAt: number): Promise<string | null>
+ latest(repository: GitHubRepository, component: ReleaseComponent): Promise<VerifiedRelease | null | undefined>
+ contains(repository: GitHubRepository, base: string, head: string): Promise<boolean | null>
+ done(): Promise<void>
+}
+
+/** A pull request's files are read 100 a page, at most this many pages (GitHub lists 3000 files at most). */
+const FILE_PAGES = 30
+/** An original pull request a batch closed: the batch commit naming it is looked for on main from this long before the merge
+ * was recorded (a merge recorded late) to an hour after it, at most COMMIT_PAGES pages of 100. */
+const BATCH_BEFORE_MS = 6 * 3_600_000, BATCH_AFTER_MS = 3_600_000, COMMIT_PAGES = 5
+/** A batch's squash title on main: "Merge batch 11-05 i2205: #3167 #3202 #3201 (#3206)", the originals before the batch's own
+ * number. Only that list names what a batch merged: other titles end in their task's number, which shares the pull requests'
+ * range, and a batch's body may name pull requests it did not merge (review 2 of #3228). */
+const BATCH_TITLE = /^Merge batch [^:\n]*:((?:\s+#\d+)+)\s+\(#\d+\)\s*$/
+
+/** Whether the pass looks for [mergedAt]'s merge commit at [now]: every pass for an hour, then every 30 minutes, and after a
+ * day every 2 hours, so a batch never found costs a few reads an hour rather than five pages every 5 minutes for 14 days. */
+export function batchLookupDue(mergedAt: number, now: number): boolean {
+ const age = now - mergedAt, PASS = 5 * 60_000
+ return age < 3_600_000 || now % (age < 86_400_000 ? 30 * 60_000 : 2 * 3_600_000) < PASS
+}
+type Run = { head_branch?: unknown; head_sha?: unknown; event?: unknown; conclusion?: unknown; run_started_at?: unknown; created_at?: unknown }
+
+/** The reads, over [get]. Each repository's default branch is read once per reader. */
+export function readReleases(get: GitHubGet): Omit<ReleaseReader, 'done'> {
+ const branches = new Map<string, Promise<string | null>>()
+ const branch = (repository: GitHubRepository) => {
+ const key = repository.fullName.toLowerCase()
+ if (!branches.has(key)) branches.set(key, get(repository, `/repos/${repository.fullName}`).then(answer => {
+ const name = (answer.body as { default_branch?: unknown } | null)?.default_branch
+ return answer.status === 200 && typeof name === 'string' && name ? name : null
+ }))
+ return branches.get(key)!
+ }
+ return {
+ async files(repository, number) {
+ const files: string[] = []
+ let path: string | undefined = `/repos/${repository.fullName}/pulls/${number}/files?per_page=100`
+ for (let page = 0; path && page < FILE_PAGES; page++) {
+ const answer = await get(repository, path)
+ if (answer.status !== 200 || !Array.isArray(answer.body)) return null
+ for (const file of answer.body as Array<{ filename?: unknown; previous_filename?: unknown }>) {
+ for (const name of [file.filename, file.previous_filename]) if (typeof name === 'string') files.push(name)
+ }
+ path = answer.next
+ }
+ return files
+ },
+ async mergeCommit(repository, number, mergedAt) {
+ const pull = await get(repository, `/repos/${repository.fullName}/pulls/${number}`)
+ const body = pull.body as { merged_at?: unknown; merge_commit_sha?: unknown } | null
+ if (pull.status !== 200 || !body) return null
+ if (typeof body.merged_at === 'string' && typeof body.merge_commit_sha === 'string') return body.merge_commit_sha
+ // Closed into a batch: the batch's squash title on main lists it ("Merge batch …: #6 #7 (#79)"). Newest first, so the
+ // last such batch is the oldest, the one that merged it.
+ const main = await branch(repository)
+ if (!main) return null
+ const names = (message: string) => BATCH_TITLE.exec(message.split('\n')[0]!)?.[1]!.trim().split(/\s+/).includes(`#${number}`) ?? false
+ let path: string | undefined = `/repos/${repository.fullName}/commits?sha=${encodeURIComponent(main)}&since=${new Date(mergedAt - BATCH_BEFORE_MS).toISOString()}`
+ + `&until=${new Date(mergedAt + BATCH_AFTER_MS).toISOString()}&per_page=100`
+ let found: string | null = null
+ for (let page = 0; path && page < COMMIT_PAGES; page++) {
+ const answer = await get(repository, path)
+ if (answer.status !== 200 || !Array.isArray(answer.body)) return null
+ for (const commit of answer.body as Array<{ sha?: unknown; commit?: { message?: unknown } }>) {
+ if (typeof commit.sha === 'string' && typeof commit.commit?.message === 'string' && names(commit.commit.message)) found = commit.sha
+ }
+ path = answer.next
+ }
+ return found
+ },
+ async contains(repository, base, head) {
+ const answer = await get(repository, `/repos/${repository.fullName}/compare/${base}...${head}`)
+ const status = (answer.body as { status?: unknown } | null)?.status
+ if (answer.status !== 200) return null
+ return status === 'ahead' || status === 'identical' ? true : status === 'behind' || status === 'diverged' ? false : null
+ },
+ async latest(repository, component) {
+ const runs = await get(repository, `/repos/${repository.fullName}/actions/workflows/${component.workflow}/runs?event=push&status=success&per_page=30`)
+ if (runs.status === 404) return undefined
+ const list = (runs.body as { workflow_runs?: unknown } | null)?.workflow_runs
+ if (runs.status !== 200 || !Array.isArray(list)) return null
+ // The highest version, not the newest run: a re-run of an older tag's workflow lists first (review of #3228).
+ const found = (list as Run[]).filter(run => run.event === 'push' && run.conclusion === 'success' && typeof run.head_sha === 'string'
+ && typeof run.head_branch === 'string' && isReleaseTag(component, run.head_branch))
+ .sort((a, b) => compareTags(b.head_branch as string, a.head_branch as string))[0]
+ if (!found) return undefined
+ const main = await branch(repository)
+ if (!main) return null
+ const compare = await get(repository, `/repos/${repository.fullName}/compare/${found.head_sha as string}...${encodeURIComponent(main)}`)
+ if (compare.status !== 200) return null
+ const status = (compare.body as { status?: unknown } | null)?.status
+ // Main at or ahead of the tag: the tag's commit is on main. A tag cut elsewhere is no release of main.
+ if (status !== 'ahead' && status !== 'identical') return undefined
+ const at = Date.parse(String(found.run_started_at ?? found.created_at ?? ''))
+ if (Number.isNaN(at)) return null
+ return { tag: found.head_branch as string, sha: found.head_sha as string, at }
+ },
+ }
+}
+
+/** Reads with the Harness GitHub App: one read-only token per repository for the whole pass, revoked when it is done. A
+ * repository the app is not installed on, or any GitHub failure, reads as unknown. */
+export function appReleaseReader(app: GitHubApp): ReleaseReader {
+ const tokens = new Map<string, Promise<string | null>>()
+ const token = (repository: GitHubRepository) => {
+ const key = repository.fullName.toLowerCase()
+ if (!tokens.has(key)) tokens.set(key, (async () => {
+ const installation = await app.installation(repository)
+ return installation === null ? null : (await app.createToken(installation, repository, RELEASE_READ_PERMISSIONS)).token
+ })().catch(() => null))
+ return tokens.get(key)!
+ }
+ const get: GitHubGet = async (repository, path) => {
+ const granted = await token(repository)
+ return granted ? app.get(path, granted).catch(() => ({ status: 0, body: null })) : { status: 0, body: null }
+ }
+ return {
+ ...readReleases(get),
+ async done() {
+ for (const granted of tokens.values()) {
+ const value = await granted
+ if (value) await app.revoke(value).catch(() => {})
+ }
+ tokens.clear()
+ },
+ }
+}
+
+/** Without the Harness GitHub App nothing can say a release is verified: every read is unknown, and each pass says so. */
+export const unknownReleases: ReleaseReader = { files: async () => null, mergeCommit: async () => null, latest: async () => null,
+ contains: async () => null, done: async () => {} }
+
+const PULL = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/([1-9][0-9]*)$/
+type Log = Pick<typeof logger, 'warn' | 'info'>
+
+/**
+ * One pass at [now]: each Swarm with work this week (the routing reflection's candidates), each of its projects whose release
+ * list has a task waiting or a step open and whose repository is on GitHub. It reads the files of each task not read yet,
+ * and the newest verified release of each component something waits for, then settles the project in one write. A project
+ * it could not read is logged and skipped; the others go on. The projects settled.
+ */
+export async function watchReleases(db: PrismaClient, store: Pick<SuperTabStore, 'settleReleases'>, reader: ReleaseReader, now: number,
+ log: Log = logger, candidates: () => Promise<Map<string, string[]>> = () => reflectionCandidates(db, now, log)): Promise<number> {
+ let settled = 0
+ try {
+ for (const [tabId, projectIds] of await candidates()) {
+ const head = await db.swarmHead.findUnique({ where: { id: `${tabId}:head` }, select: { deleted: true, data: true } })
+ if (!head || head.deleted) continue
+ for (const project of projectsOf(head.data as unknown as SuperTabState).filter(p => projectIds.includes(p.id))) {
+ const ledger = project.releases
+ const repository = githubRepository(project.repository?.repositoryUrl)
+ if (!ledger || !repository || (!ledger.pending.length && !Object.keys(ledger.steps ?? {}).length)) continue
+ try {
+ const facts: ReleaseFacts = { resolved: [], releases: {} }
+ let unread = 0
+ // Each entry as this pass knows it: its components, then its merge commit, each read once and kept on the list.
+ const entries: PendingRelease[] = [], fresh = new Set<string>()
+ for (const entry of ledger.pending) {
+ const known = { ...entry }
+ entries.push(known)
+ if (known.components && (!known.components.length || known.sha)) continue
+ const match = PULL.exec(entry.url)
+ const number = match && `${match[1]}/${match[2]}`.toLowerCase() === repository.fullName.toLowerCase() ? Number(match[3]) : null
+ const found: ReleaseFacts['resolved'][number] = { groupId: entry.groupId, url: entry.url }
+ if (!known.components) {
+ const files = number ? await reader.files(repository, number) : null
+ if (files) known.components = found.components = componentsOf(files)
+ }
+ if (known.components?.length && !known.sha && batchLookupDue(entry.mergedAt, now)) {
+ const sha = number ? await reader.mergeCommit(repository, number, entry.mergedAt) : null
+ if (sha) { known.sha = found.sha = sha; fresh.add(pendingKey(entry)) }
+ }
+ if (found.components || found.sha) facts.resolved.push(found)
+ if (!known.components || (known.components.length && !known.sha)) unread++
+ }
+ const needed = new Set<ReleaseComponentId>([...entries.flatMap(e => e.components ?? []), ...Object.keys(ledger.steps ?? {}) as ReleaseComponentId[]])
+ const unknown: string[] = []
+ for (const component of RELEASE_COMPONENTS.filter(c => needed.has(c.id))) {
+ const release = await reader.latest(repository, component)
+ const last = ledger.last?.[component.id]
+ if (release === null) { unknown.push(component.id); continue }
+ if (!release || (last && compareTags(release.tag, last.tag) < 0)) continue
+ // A new tag is compared with every merge waiting for it; the tag already settled only with merges resolved since.
+ const carries: string[] = []
+ let unsure = false
+ for (const entry of entries.filter(e => e.sha && e.components?.includes(component.id) && !e.shippedIn?.[component.id]
+ && (release.tag !== last?.tag || fresh.has(pendingKey(e))))) {
+ const inside = await reader.contains(repository, entry.sha!, release.sha)
+ if (inside === null) { unsure = true; break }
+ if (inside) carries.push(pendingKey(entry))
+ }
+ if (unsure) unknown.push(component.id)
+ else facts.releases[component.id] = { ...release, carries }
+ }
+ // A merge commit found this pass is kept only when every release it waits for was compared with it: one kept after an
+ // unsure comparison is no longer new next pass, so the tag already settled would never be compared with it.
+ facts.resolved = facts.resolved.flatMap(found => {
+ if (!found.sha || !entries.find(e => pendingKey(e) === pendingKey(found))!.components!.some(c => unknown.includes(c))) return [found]
+ const { sha: _again, ...rest } = found
+ return rest.components ? [rest] : []
+ })
+ if (unread || unknown.length) {
+ log.warn('[swarm-releases] GitHub could not say; those tasks stay waiting and no step opens on a guess', { tabId, projectId: project.id,
+ repository: repository.fullName, unreadPullRequests: unread, unreadReleases: unknown })
+ }
+ if (ledger.pending.length >= PENDING_MAX) log.warn('[swarm-releases] release list full: the oldest merges leave it unshipped', { tabId, projectId: project.id, max: PENDING_MAX })
+ const outcome = await store.settleReleases(tabId, project.id, facts)
+ settled++
+ if (outcome?.dropped.length) {
+ log.warn('[swarm-releases] merges no release carried in 14 days left the list unshipped', { tabId, projectId: project.id, groups: outcome.dropped.map(e => e.groupId) })
+ }
+ if (outcome && (outcome.shipped.length || outcome.opened)) {
+ log.info('[swarm-releases] settled', { tabId, projectId: project.id, shipped: outcome.shipped.length, opened: outcome.opened })
+ }
+ } catch (error) {
+ log.warn('[swarm-releases] project skipped', { tabId, projectId: project.id, error: error instanceof Error ? error.message : String(error) })
+ }
+ }
+ }
+ } finally { await reader.done() }
+ return settled
+}
+
+/** How long the pass keeps the Swarms with work this week: one aggregation an hour, not one a pass. A Swarm whose first routed
+ * attempt of the week came since is read within the hour, before any of its merges can wait on a release. */
+export const CANDIDATES_MS = 60 * 60_000
+
+/** Runs the release watch every 5 minutes in the singleton worker. */
+export function startReleaseWatch(db: PrismaClient, store: Pick<SuperTabStore, 'settleReleases'>, reader: () => ReleaseReader, everyMs = 5 * 60_000): () => void {
+ let running = false
+ let kept: { at: number; value: Map<string, string[]> } | null = null
+ const candidates = async (now: number) => {
+ if (!kept || now - kept.at >= CANDIDATES_MS) kept = { at: now, value: await reflectionCandidates(db, now) }
+ return kept.value
+ }
+ const run = () => {
+ if (running) return
+ running = true
+ const now = Date.now()
+ void watchReleases(db, store, reader(), now, logger, () => candidates(now))
+ .catch(error => logger.warn('[swarm-releases] pass failed', { error: error instanceof Error ? error.message : String(error) }))
+ .finally(() => { running = false })
+ }
+ run()
+ const timer = setInterval(run, everyMs)
+ timer.unref()
+ return () => clearInterval(timer)
+}
diff --git a/backend/src/superTabs/releases.test.ts b/backend/src/superTabs/releases.test.ts
new file mode 100644
index 000000000..9e47c8fe9
--- /dev/null
+++ b/backend/src/superTabs/releases.test.ts
@@ -0,0 +1,252 @@
+import { describe, expect, it } from 'vitest'
+import type { Agent, Conversation, SuperTabState } from './model.js'
+import type { SwarmProject } from './projects.js'
+import { missingContract } from './taskContract.js'
+import { backendPaused, compareTags, componentsOf, inReleaseWindow, isReleaseTag, notePendingRelease, PENDING_MAX, RELEASE_COMPONENTS, RELEASE_RULES,
+ pendingKey, releaseDue, settleReleases, PENDING_MS, shipped, waitingFor, type PendingRelease, type ReleaseLedger } from './releases.js'
+
+/** A time in Vietnam (UTC+7, no daylight saving) on 6 November 2026. */
+const vn = (hour: number, minute = 0) => Date.UTC(2026, 10, 6, hour - 7, minute)
+const MINUTE = 60_000
+
+const entry = (over: Partial<PendingRelease> = {}): PendingRelease =>
+ ({ groupId: 'g1', url: 'https://github.com/o/r/pull/1', mergedAt: vn(9), components: ['desktop'], ...over })
+const ledger = (over: Partial<ReleaseLedger> = {}): ReleaseLedger => ({ pending: [entry()], ...over })
+
+describe('release rules', () => {
+ it('seeds today\'s numbers in the project rules record\'s shape', () => {
+ expect(RELEASE_RULES.releaseWindow).toEqual({ start: '09:00', end: '18:00', timeZone: 'Asia/Ho_Chi_Minh' })
+ expect(RELEASE_RULES.releasePace).toEqual({ backendEveryMinutes: 120, appsAfterVisibleBatch: true, backendPause: { start: '09:00', end: '10:00' } })
+ })
+
+ it('is inside the window from 09:00 up to, not including, 18:00 Vietnam time', () => {
+ expect(inReleaseWindow(RELEASE_RULES, vn(8, 59))).toBe(false)
+ expect(inReleaseWindow(RELEASE_RULES, vn(9))).toBe(true)
+ expect(inReleaseWindow(RELEASE_RULES, vn(17, 59))).toBe(true)
+ expect(inReleaseWindow(RELEASE_RULES, vn(18))).toBe(false)
+ expect(inReleaseWindow(RELEASE_RULES, vn(23))).toBe(false)
+ })
+
+ it('pauses the backend from 09:00 up to 10:00, and nothing when the pause is off', () => {
+ expect(backendPaused(RELEASE_RULES, vn(9, 30))).toBe(true)
+ expect(backendPaused(RELEASE_RULES, vn(10))).toBe(false)
+ expect(backendPaused({ ...RELEASE_RULES, releasePace: { ...RELEASE_RULES.releasePace, backendPause: null } }, vn(9, 30))).toBe(false)
+ })
+})
+
+describe('componentsOf', () => {
+ it('maps visible files to the releases that carry them, web with Desktop', () => {
+ expect(componentsOf(['backend/src/worker.ts'])).toEqual(['backend'])
+ expect(componentsOf(['cli/src/index.ts', 'desktop/lib/main.dart'])).toEqual(['cli', 'desktop', 'web'])
+ })
+
+ it('maps tests, docs and other folders to none: they ship at their merge', () => {
+ expect(componentsOf(['backend/src/a.test.ts', 'backend/integration/x.test.ts', 'desktop/test/a_test.dart', 'cli/test/a.spec.ts',
+ 'backend/README.md', 'docs/plans/x.md', '.github/workflows/ci.yml', 'scripts/release-window.py'])).toEqual([])
+ })
+
+ it('knows each component\'s release tag and workflow', () => {
+ expect(RELEASE_COMPONENTS.map(c => [c.id, c.tagSuffix, c.workflow])).toEqual([
+ ['backend', '_backend', 'production-be-build.yaml'], ['cli', '_cli', 'release.yml'],
+ ['desktop', '_desktop', 'release-desktop.yml'], ['web', '_web', 'release-web.yml']])
+ const desktop = RELEASE_COMPONENTS.find(c => c.id === 'desktop')!
+ expect(isReleaseTag(desktop, 'v1.3.77_desktop')).toBe(true)
+ expect(isReleaseTag(desktop, 'v1.3.77_desktop-candidate')).toBe(false)
+ expect(isReleaseTag(desktop, 'main')).toBe(false)
+ expect(isReleaseTag(desktop, 'v1.4.16_backend')).toBe(false)
+ })
+})
+
+describe('releaseDue', () => {
+ it('opens Desktop right after a visible merge, inside the window only', () => {
+ expect(releaseDue(ledger(), 'desktop', vn(11), RELEASE_RULES)).toBe(true)
+ expect(releaseDue(ledger(), 'desktop', vn(8, 30), RELEASE_RULES)).toBe(false)
+ expect(releaseDue(ledger(), 'desktop', vn(18, 30), RELEASE_RULES)).toBe(false)
+ })
+
+ it('opens nothing without a waiting change, or while a step is open', () => {
+ expect(releaseDue(ledger(), 'cli', vn(11), RELEASE_RULES)).toBe(false)
+ expect(releaseDue(ledger({ pending: [entry({ shippedIn: { desktop: 'v1_desktop' } })] }), 'desktop', vn(11), RELEASE_RULES)).toBe(false)
+ expect(releaseDue(ledger({ pending: [entry({ components: undefined })] }), 'desktop', vn(11), RELEASE_RULES)).toBe(false)
+ expect(releaseDue(ledger({ steps: { desktop: { groupId: 's', at: vn(10) } } }), 'desktop', vn(11), RELEASE_RULES)).toBe(false)
+ })
+
+ it('opens the backend at most every 120 minutes after its last verified release, never in the pause', () => {
+ const backend = (lastAt?: number) => ledger({ pending: [entry({ components: ['backend'] })],
+ ...lastAt === undefined ? {} : { last: { backend: { tag: 'v1.4.16_backend', sha: 'abc', at: lastAt } } } })
+ expect(releaseDue(backend(), 'backend', vn(11), RELEASE_RULES)).toBe(true)
+ expect(releaseDue(backend(vn(11)), 'backend', vn(11) + 119 * MINUTE, RELEASE_RULES)).toBe(false)
+ expect(releaseDue(backend(vn(11)), 'backend', vn(11) + 120 * MINUTE, RELEASE_RULES)).toBe(true)
+ expect(releaseDue(backend(), 'backend', vn(9, 30), RELEASE_RULES)).toBe(false)
+ expect(releaseDue(backend(), 'backend', vn(10), RELEASE_RULES)).toBe(true)
+ })
+
+ it('leaves the apps to people when the pace says so', () => {
+ const rules = { ...RELEASE_RULES, releasePace: { ...RELEASE_RULES.releasePace, appsAfterVisibleBatch: false } }
+ expect(releaseDue(ledger(), 'desktop', vn(11), rules)).toBe(false)
+ })
+})
+
+describe('shipping', () => {
+ it('orders release tags by version, not by when they ran', () => {
+ expect(compareTags('v1.3.78_desktop', 'v1.3.77_desktop')).toBeGreaterThan(0)
+ expect(compareTags('v1.3.100_desktop', 'v1.3.99_desktop')).toBeGreaterThan(0)
+ expect(compareTags('v1.4.0_desktop', 'v1.3.99_desktop')).toBeGreaterThan(0)
+ expect(compareTags('v1.3.77_desktop', 'v1.3.77_desktop')).toBe(0)
+ expect(compareTags('v0.5.53_cli', 'v0.5.54_cli')).toBeLessThan(0)
+ })
+
+ it('ships a task only when every release it needs carries it', () => {
+ expect(shipped(entry({ components: ['backend', 'desktop'], shippedIn: { desktop: 'v1.3.78_desktop' } }))).toBe(false)
+ expect(shipped(entry({ components: ['backend', 'desktop'], shippedIn: { desktop: 'v1.3.78_desktop', backend: 'v1.4.17_backend' } }))).toBe(true)
+ expect(shipped(entry({ components: [] }))).toBe(true)
+ expect(shipped(entry({ components: undefined }))).toBe(false)
+ })
+
+ it('lists what waits for a component', () => {
+ const waiting = ledger({ pending: [entry({ groupId: 'a' }), entry({ groupId: 'b', components: ['cli'] }), entry({ groupId: 'c', shippedIn: { desktop: 't' } })] })
+ expect(waitingFor(waiting, 'desktop').map(e => e.groupId)).toEqual(['a'])
+ })
+})
+
+describe('notePendingRelease', () => {
+ const project = () => ({ id: 'p1' }) as SwarmProject
+
+ it('adds a merge once, oldest first', () => {
+ const p = project()
+ notePendingRelease(p, { id: 'b' }, 'https://github.com/o/r/pull/2', vn(11))
+ notePendingRelease(p, { id: 'a' }, 'https://github.com/o/r/pull/1', vn(10))
+ notePendingRelease(p, { id: 'a' }, 'https://github.com/o/r/pull/1', vn(10))
+ expect(p.releases!.pending.map(e => e.groupId)).toEqual(['a', 'b'])
+ })
+
+ it('keeps at most PENDING_MAX, pushing out the oldest', () => {
+ const p = project()
+ for (let i = 0; i < PENDING_MAX; i++) notePendingRelease(p, { id: `g${i}` }, `https://github.com/o/r/pull/${i + 1}`, vn(10) + i)
+ const dropped = notePendingRelease(p, { id: 'late' }, 'https://github.com/o/r/pull/999', vn(12))
+ expect(dropped.map(e => e.groupId)).toEqual(['g0'])
+ expect(p.releases!.pending).toHaveLength(PENDING_MAX)
+ })
+})
+
+describe('settleReleases', () => {
+ const T = vn(11)
+ const agent = (id: string, roleName?: string): Agent => ({ id, name: id, contributorId: 'owner', membershipGeneration: 'g', machineId: 'mac',
+ harnessId: `h-${id}`, machineOwnerId: 'owner', projectId: 'p1', ...roleName ? { roleName } : {},
+ configuration: { engine: 'claude', model: 'opus', effort: 'high', contextWindow: null, engineVersion: null } } as unknown as Agent)
+ const task = (number: number, over: Partial<Conversation> = {}): Conversation => ({ id: `g${number}`, projectId: 'p1', number,
+ title: `Task ${number}`, leadId: 'lead', agentIds: ['lead'], archived: false, brief: 'Do it.', checks: [], assignment: null,
+ lastMessageSequence: 1, ...over }) as Conversation
+ function swarm(pending: PendingRelease[], { integrator = true, ...over }: Partial<ReleaseLedger> & { integrator?: boolean } = {}): SuperTabState {
+ return {
+ version: 1, id: 'tab', name: 'Swarm', ownerId: 'owner', environment: 'prod', paused: false, invitations: [], groupCounter: 20,
+ people: [{ id: 'owner', email: '[email protected]', role: 'owner', generation: 'g' }] as SuperTabState['people'],
+ agents: [agent('lead'), ...integrator ? [agent('ship', 'Integrator')] : [], agent('eng', 'Engineer')],
+ projects: [{ id: 'p1', name: 'openharness', ownerId: 'owner', leadConversationId: 'lead-p1', visibility: 'public', members: [], updateMinutes: 5,
+ releases: { pending, ...over } }],
+ conversations: [{ ...task(0), id: 'lead-p1', number: undefined, title: 'Lead' } as Conversation, task(12), task(13)],
+ } as SuperTabState
+ }
+ const ledgerOf = (state: SuperTabState) => state.projects![0]!.releases!
+ const key12 = pendingKey({ groupId: 'g12', url: 'https://github.com/o/r/pull/1' })
+ /** A verified Desktop release whose tag GitHub says contains the merge commits of [carries]. */
+ const desktopRelease = (carries = [key12], tag = 'v1.3.78_desktop', at = T - 5 * MINUTE) => ({ tag, sha: 'd1', at, carries })
+ const webRelease = { tag: 'v1.3.98_web', sha: 'w1', at: T - 5 * MINUTE, carries: [key12] }
+ const noFacts = { resolved: [], releases: {} }
+
+ it('marks a task released once every release it needs carries it, and takes it off the list', () => {
+ const state = swarm([entry({ groupId: 'g12', mergedAt: T - 20 * MINUTE, components: ['desktop', 'web'] })])
+ const first = settleReleases(state, 'p1', { resolved: [], releases: { desktop: desktopRelease() } }, T)
+ expect(first.shipped).toEqual([])
+ expect(ledgerOf(state).pending[0]!.shippedIn).toEqual({ desktop: 'v1.3.78_desktop' })
+ const second = settleReleases(state, 'p1', { resolved: [], releases: { desktop: desktopRelease(), web: webRelease } }, T)
+ expect(second.shipped).toEqual(['g12'])
+ expect(state.conversations.find(c => c.id === 'g12')!.released).toEqual({ at: T - 5 * MINUTE, tags: ['v1.3.78_desktop', 'v1.3.98_web'] })
+ expect(ledgerOf(state).pending).toEqual([])
+ })
+
+ it('leaves a merge the tag does not contain waiting, and marks nothing without a verified release', () => {
+ const state = swarm([entry({ groupId: 'g12', mergedAt: T - 5 * MINUTE, components: ['desktop'] })])
+ settleReleases(state, 'p1', { resolved: [], releases: { desktop: desktopRelease([]) } }, vn(18, 30))
+ settleReleases(state, 'p1', noFacts, vn(18, 30))
+ expect(ledgerOf(state).pending[0]!.shippedIn).toBeUndefined()
+ expect(state.conversations.find(c => c.id === 'g12')!.released).toBeUndefined()
+ })
+
+ it('ships work that changed no released part at its merge', () => {
+ const state = swarm([entry({ groupId: 'g13', url: 'https://github.com/o/r/pull/13', mergedAt: T - MINUTE, components: undefined })])
+ const outcome = settleReleases(state, 'p1', { resolved: [{ groupId: 'g13', url: 'https://github.com/o/r/pull/13', components: [] }], releases: {} }, vn(20))
+ expect(outcome.shipped).toEqual(['g13'])
+ expect(state.conversations.find(c => c.id === 'g13')!.released).toEqual({ at: T - MINUTE, tags: [] })
+ })
+
+ it('opens one release step for the Integrator inside the window, and no second one while it is open', () => {
+ const state = swarm([entry({ groupId: 'g12', mergedAt: T - MINUTE, components: ['desktop', 'web'] })])
+ const outcome = settleReleases(state, 'p1', noFacts, T)
+ const step = state.conversations.find(c => c.id === outcome.opened)!
+ expect(step).toMatchObject({ projectId: 'p1', number: 21, title: 'Release Desktop and Web', priority: 'P1', assignment: null, archived: false })
+ expect(step.agentIds).toEqual(['lead', 'ship'])
+ expect(step.brief).toContain('#12 Task 12')
+ // River, 11-05: the task contract (#3389) holds for the step the Swarm opens: a check, a priority, and why nobody asked.
+ expect(step.checks).toEqual([expect.objectContaining({ description: expect.stringContaining('verified'), independent: false, evidence: null, passedBy: null })])
+ expect(step.ledger).toEqual({ askedAt: T, noRequesterReason: 'scheduled release' })
+ expect(outcome.messages[0]!.text).toContain('No requester: scheduled release')
+ // The guard's own test of an agent's create, on what the Swarm wrote: nothing missing.
+ expect(missingContract({ goal: step.brief, checks: step.checks.length, priority: !!step.priority,
+ requester: !!(step.requesterId || step.ledger?.noRequesterReason) })).toEqual([])
+ expect(ledgerOf(state).steps).toEqual({ desktop: { groupId: step.id, at: T }, web: { groupId: step.id, at: T } })
+ expect(outcome.messages).toEqual([expect.objectContaining({ conversationId: step.id, recipients: ['ship'], source: { kind: 'release' } })])
+ expect(settleReleases(state, 'p1', noFacts, T + 5 * MINUTE).opened).toBeNull()
+ })
+
+ it('opens no step outside the window, and the backend only at its pace', () => {
+ const late = swarm([entry({ components: ['desktop'] })])
+ expect(settleReleases(late, 'p1', noFacts, vn(18)).opened).toBeNull()
+ const backend = swarm([entry({ components: ['backend'], mergedAt: T - MINUTE })],
+ { last: { backend: { tag: 'v1.4.16_backend', sha: 'b', at: T - 60 * MINUTE } } })
+ expect(settleReleases(backend, 'p1', noFacts, T).opened).toBeNull()
+ expect(settleReleases(backend, 'p1', noFacts, T + 60 * MINUTE).opened).not.toBeNull()
+ })
+
+ it('says the PM assigns it when the project has no Integrator', () => {
+ const state = swarm([entry({ components: ['cli'] })], { integrator: false })
+ const outcome = settleReleases(state, 'p1', noFacts, T)
+ expect(outcome.messages[0]).toMatchObject({ recipients: [] })
+ expect(outcome.messages[0]!.text).toContain('No Integrator')
+ })
+
+ it('says in the step which verified release carried which tasks, and frees the component for the next step', () => {
+ const state = swarm([entry({ groupId: 'g12', mergedAt: T - 20 * MINUTE, components: ['desktop'] })],
+ { steps: { desktop: { groupId: 'g13', at: T - 15 * MINUTE } } })
+ const outcome = settleReleases(state, 'p1', { resolved: [], releases: { desktop: desktopRelease() } }, T)
+ expect(outcome.messages).toEqual([expect.objectContaining({ conversationId: 'g13', text: 'Verified v1.3.78_desktop: it carries #12 Task 12.' })])
+ expect(ledgerOf(state).steps).toEqual({})
+ })
+
+ it('frees a step that ended without a verified release an hour after it ended, so a failed release gets a new step', () => {
+ const state = swarm([entry({ groupId: 'g12', components: ['desktop'] })], { steps: { desktop: { groupId: 'g13', at: T - 30 * MINUTE } } })
+ state.conversations.find(c => c.id === 'g13')!.assignment = { id: 'a', agentId: 'ship', status: 'done' } as Conversation['assignment']
+ expect(settleReleases(state, 'p1', noFacts, T).opened).toBeNull()
+ expect(ledgerOf(state).steps!.desktop!.endedAt).toBe(T)
+ expect(settleReleases(state, 'p1', noFacts, T + 59 * MINUTE).opened).toBeNull()
+ expect(settleReleases(state, 'p1', noFacts, T + 60 * MINUTE).opened).not.toBeNull()
+ })
+
+ it('keeps a resolved merge commit, and marks a task the newest tag carries once it resolves, without moving back to an older tag', () => {
+ const state = swarm([entry({ groupId: 'g12', components: ['desktop'] })], { last: { desktop: { tag: 'v1.3.78_desktop', sha: 'd1', at: T - 5 * MINUTE } } })
+ settleReleases(state, 'p1', { resolved: [{ groupId: 'g12', url: 'https://github.com/o/r/pull/1', sha: 'm12' }], releases: {} }, vn(20))
+ expect(ledgerOf(state).pending[0]!.sha).toBe('m12')
+ // The same tag, read again now that the merge commit is known: it carries the task, and announces nothing new.
+ const again = settleReleases(state, 'p1', { resolved: [], releases: { desktop: desktopRelease() } }, vn(20))
+ expect(again.shipped).toEqual(['g12'])
+ // A re-run of an older tag's workflow is not newer: the last release stays.
+ settleReleases(state, 'p1', { resolved: [], releases: { desktop: desktopRelease([], 'v1.3.77_desktop', T) } }, vn(20))
+ expect(ledgerOf(state).last!.desktop!.tag).toBe('v1.3.78_desktop')
+ })
+
+ it('drops a merge no release carried in 14 days', () => {
+ const state = swarm([entry({ groupId: 'g12', mergedAt: T - PENDING_MS - 1, components: ['desktop'] })])
+ expect(settleReleases(state, 'p1', noFacts, vn(20)).dropped.map(e => e.groupId)).toEqual(['g12'])
+ expect(ledgerOf(state).pending).toEqual([])
+ })
+})
diff --git a/backend/src/superTabs/releases.ts b/backend/src/superTabs/releases.ts
new file mode 100644
index 000000000..e291e24ec
--- /dev/null
+++ b/backend/src/superTabs/releases.ts
@@ -0,0 +1,243 @@
+/**
+ * Releases scheduled by the Swarm (task #3405, anh Dee's Swarm redesign, 2026-11-05: the server does the routine). A merge
+ * recorded on a task puts it on its project's release list; the worker (releaseWatch.ts) reads GitHub for each component's
+ * newest verified release (a tag whose release workflow succeeded: its artifacts built and checked) and marks the tasks it
+ * carries released, and inside the release window it opens a release step for the project's Integrator: Desktop, CLI and web
+ * right after a visible merge, the backend at most every two hours and never in its morning pause. Everything here is pure.
+ */
+import { agentDisplayName } from './agentNames.js'
+import { localNow } from './digest.js'
+import { activeWork, nextConversationNumber, stableId, type Agent, type Conversation, type MessageDraft, type SuperTabState } from './model.js'
+import { agentProjectId, projectsOf, type SwarmProject } from './projects.js'
+import { SEED_RULES, type ProjectRules } from './policy.js'
+
+/** The release window, pace and backend pause: the project rules record's own (policy.ts, task #3393), which people edit
+ * without a release. The store reads each project's record when it settles (store.ts settleReleases). */
+export type ReleaseRules = Pick<ProjectRules, 'releaseWindow' | 'releasePace'>
+
+/** The record's seed (09:00-18:00 VN, the backend every 120 minutes and never 09:00-10:00, apps after each visible batch):
+ * what a project without a saved record runs on, and the pure functions' default. */
+export const RELEASE_RULES: ReleaseRules = { releaseWindow: SEED_RULES.releaseWindow, releasePace: SEED_RULES.releasePace }
+
+export type ReleaseComponentId = 'backend' | 'cli' | 'desktop' | 'web'
+/** What ships a part of the repository: its tag's suffix (`v1.4.16_backend`), the workflow a pushed tag runs, the folders
+ * whose visible changes it carries. Web is built from Desktop's folder. */
+export interface ReleaseComponent { id: ReleaseComponentId; name: string; tagSuffix: string; workflow: string; paths: readonly string[] }
+
+export const RELEASE_COMPONENTS: readonly ReleaseComponent[] = Object.freeze([
+ { id: 'backend', name: 'Backend', tagSuffix: '_backend', workflow: 'production-be-build.yaml', paths: ['backend/'] },
+ { id: 'cli', name: 'CLI', tagSuffix: '_cli', workflow: 'release.yml', paths: ['cli/'] },
+ { id: 'desktop', name: 'Desktop', tagSuffix: '_desktop', workflow: 'release-desktop.yml', paths: ['desktop/'] },
+ { id: 'web', name: 'Web', tagSuffix: '_web', workflow: 'release-web.yml', paths: ['desktop/'] },
+] as const)
+
+export const componentNamed = (id: ReleaseComponentId): ReleaseComponent => RELEASE_COMPONENTS.find(c => c.id === id)!
+
+/** Whether [tag] is a release of [component]: `v` and three numbers, then its suffix and nothing more. */
+export const isReleaseTag = (component: ReleaseComponent, tag: string): boolean =>
+ new RegExp(`^v\\d+\\.\\d+\\.\\d+${component.tagSuffix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`).test(tag)
+
+/** Tests, docs and fixtures reach nobody by a release: a change of only these ships at its merge. */
+const INVISIBLE = [/(^|\/)(test|tests|integration|integration_test|test_driver|__tests__|fixtures)\//, /\.(test|spec)\.[cm]?[jt]sx?$/,
+ /\.test-support\.[cm]?[jt]s$/, /_test\.dart$/, /\.md$/]
+
+/** The components whose releases carry [files], in RELEASE_COMPONENTS order. */
+export function componentsOf(files: readonly string[]): ReleaseComponentId[] {
+ const visible = files.filter(file => !INVISIBLE.some(pattern => pattern.test(file)))
+ return RELEASE_COMPONENTS.filter(c => visible.some(file => c.paths.some(path => file.startsWith(path)))).map(c => c.id)
+}
+
+const clock = (rules: ReleaseRules, now: number) => localNow(rules.releaseWindow.timeZone, now).time
+const within = (time: string, span: { start: string; end: string }) => span.start <= time && time < span.end
+
+/** From the window's start up to, not including, its end, in its own time zone. */
+export const inReleaseWindow = (rules: ReleaseRules, now: number): boolean => within(clock(rules, now), rules.releaseWindow)
+/** Inside the backend's pause, in the window's time zone. */
+export const backendPaused = (rules: ReleaseRules, now: number): boolean =>
+ !!rules.releasePace.backendPause && within(clock(rules, now), rules.releasePace.backendPause)
+
+/** A task merged and not yet carried by every release it needs. `components` is unknown until the worker read its pull
+ * request's files, and `sha` until it found the merge's commit on main (its own merge commit, or the batch's that closed
+ * it); `shippedIn` names, per component, the verified release that carries it. */
+export interface PendingRelease { groupId: string; url: string; mergedAt: number; components?: ReleaseComponentId[]; sha?: string
+ shippedIn?: Partial<Record<ReleaseComponentId, string>> }
+/** A component's newest verified release: its tag, the tag's commit, and when its release ran (the pace counts from it). */
+export interface VerifiedRelease { tag: string; sha: string; at: number }
+
+/** One entry's name on the list, by which a release says it carries it. */
+export const pendingKey = (entry: Pick<PendingRelease, 'groupId' | 'url'>): string => `${entry.groupId} ${entry.url}`
+
+/** Release tags by version (`v1.3.100_desktop` after `v1.3.99_desktop`): negative when [a] is older than [b]. */
+export function compareTags(a: string, b: string): number {
+ const version = (tag: string) => (/^v(\d+)\.(\d+)\.(\d+)/.exec(tag) ?? []).slice(1).map(Number)
+ const [x, y] = [version(a), version(b)]
+ for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0)
+ return 0
+}
+/** The release step open for a component, when the Swarm opened it, and when it first saw that step over without a verified
+ * release (done, cancelled or archived: the release may still be running). */
+export interface ReleaseStep { groupId: string; at: number; endedAt?: number }
+/** A project's release list (SwarmProject.releases). The server alone writes it; readers never get it. */
+export interface ReleaseLedger { pending: PendingRelease[]; last?: Partial<Record<ReleaseComponentId, VerifiedRelease>>; steps?: Partial<Record<ReleaseComponentId, ReleaseStep>> }
+
+/** At most this many tasks wait on a project's list; the oldest leaves first, with a warning. */
+export const PENDING_MAX = 100
+/** A merge no release carried in this long leaves the list, with a warning. */
+export const PENDING_MS = 14 * 24 * 3_600_000
+
+/** The tasks waiting for [component]: their components known, it among them, and no release of it carrying them yet. */
+export const waitingFor = (ledger: ReleaseLedger, component: ReleaseComponentId): PendingRelease[] =>
+ ledger.pending.filter(e => e.components?.includes(component) && !e.shippedIn?.[component])
+
+/** Whether the Swarm opens a release step for [component] at [now]: inside the window, with a change waiting and no step
+ * open; the backend also outside its pause and at least the pace after its last verified release; the apps when the pace
+ * says they go after each visible batch. */
+export function releaseDue(ledger: ReleaseLedger, component: ReleaseComponentId, now: number, rules: ReleaseRules): boolean {
+ if (!inReleaseWindow(rules, now) || ledger.steps?.[component] || !waitingFor(ledger, component).length) return false
+ if (component !== 'backend') return rules.releasePace.appsAfterVisibleBatch
+ if (backendPaused(rules, now)) return false
+ const last = ledger.last?.backend
+ return !last || now - last.at >= rules.releasePace.backendEveryMinutes * 60_000
+}
+
+/** Whether every release [entry] needs carries it: none for a change that only tests or documents. */
+export const shipped = (entry: PendingRelease): boolean => !!entry.components && entry.components.every(c => !!entry.shippedIn?.[c])
+
+/** Puts [group]'s merge of [url] at [mergedAt] on [project]'s release list, in the merge record's own write. The same merge
+ * recorded again adds nothing; a later merge of the same task waits on its own. Returns the entries the cap pushed out. */
+export function notePendingRelease(project: SwarmProject, group: Pick<Conversation, 'id'>, url: string, mergedAt: number): PendingRelease[] {
+ const ledger = project.releases ??= { pending: [] }
+ if (ledger.pending.some(e => e.groupId === group.id && e.url === url)) return []
+ ledger.pending.push({ groupId: group.id, url, mergedAt })
+ ledger.pending.sort((a, b) => a.mergedAt - b.mergedAt)
+ return ledger.pending.length > PENDING_MAX ? ledger.pending.splice(0, ledger.pending.length - PENDING_MAX) : []
+}
+
+/** How long a step that ended without a verified release still holds its component: a release workflow that is still
+ * running (Desktop's verifies nine downloads) lands within it. After it, the next pass opens a new step. */
+export const STEP_GRACE_MS = 60 * 60_000
+/** Why a release step names no requester: the Swarm opens it on its schedule (the task contract's recorded reason, #3389). */
+export const RELEASE_NO_REQUESTER = 'scheduled release'
+/** The one check of a release step: what tells the Integrator it is done. */
+export const RELEASE_CHECK = 'Each release here is verified (its tag\'s release workflow passed) and live, and the Swarm said so in this task'
+
+/** The project's Integrator: an agent of [projectId] whose crew role (task #3397) or role name is Integrator. */
+export function integratorOf(state: SuperTabState, projectId: string): Agent | undefined {
+ const role = (agent: Agent) => ((agent as Agent & { crew?: { role?: string } }).crew?.role ?? agent.roleName ?? '').trim().toLowerCase()
+ return state.agents.find(agent => role(agent) === 'integrator' && agentProjectId(state, agent) === projectId)
+}
+
+/** What the worker read from GitHub for one project's release list (releaseWatch.ts). */
+export interface ReleaseFacts {
+ /** What the worker found of pending entries: their components (their pull requests' files), their merge commits on main. */
+ resolved: Array<{ groupId: string; url: string; components?: ReleaseComponentId[]; sha?: string }>
+ /** Each component's newest verified release on main, with the entries whose merge commits GitHub says its tag contains
+ * (pendingKey). A component GitHub could not read or compare is absent, and nothing of it changes. */
+ releases: Partial<Record<ReleaseComponentId, VerifiedRelease & { carries: string[] }>>
+}
+/** What a settle did: rows to write, the tasks it marked released, the release step it opened, the entries it dropped. */
+export interface SettledReleases { messages: MessageDraft[]; shipped: string[]; opened: string | null; dropped: PendingRelease[] }
+
+const ended = (group: Conversation | undefined): boolean => !group || group.archived || (!!group.assignment && !activeWork(group))
+const named = (state: SuperTabState, groupId: string): string => {
+ const group = state.conversations.find(c => c.id === groupId)
+ return group ? `#${group.number} ${group.title}` : 'a task no longer here'
+}
+const joined = (words: string[]): string => words.length < 2 ? words.join('') : `${words.slice(0, -1).join(', ')} and ${words.at(-1)}`
+
+/**
+ * Settles [projectId]'s release list in [state] (a copy the caller writes) at [now]: [facts]' components fill their entries;
+ * each component's newer verified release is kept, marks the entries it carries, and says so in its open release step, which
+ * it frees; an entry every release it needs carries is marked released on its task and leaves the list; one past PENDING_MS
+ * leaves too. A step that ended without a verified release frees its components STEP_GRACE_MS later. Then, when components are
+ * due (releaseDue), one release step opens for them all, naming the Integrator. Deterministic in [now]: a retried write opens
+ * the same step id.
+ */
+export function settleReleases(state: SuperTabState, projectId: string, facts: ReleaseFacts, now: number, rules: ReleaseRules = RELEASE_RULES): SettledReleases {
+ const outcome: SettledReleases = { messages: [], shipped: [], opened: null, dropped: [] }
+ const project = projectsOf(state).find(p => p.id === projectId)
+ const ledger = project?.releases
+ if (!project || !ledger) return outcome
+ const chat = state.conversations.find(c => c.id === project.leadConversationId)
+ const lead = chat?.leadId ? state.agents.find(a => a.id === chat.leadId) : undefined
+ const row = (conversationId: string, text: string, recipients: string[], key: string): MessageDraft | null => lead ? {
+ id: stableId('release', state.id, projectId, key, String(now)), conversationId, replyTo: null, recipients, text, source: { kind: 'release' },
+ author: { kind: 'agent', id: lead.id, name: lead.name, displayName: agentDisplayName(state.agents, lead.id), membershipGeneration: lead.membershipGeneration },
+ } : null
+ const say = (draft: MessageDraft | null) => { if (draft) outcome.messages.push(draft) }
+
+ for (const read of facts.resolved) {
+ const entry = ledger.pending.find(e => pendingKey(e) === pendingKey(read))
+ if (!entry) continue
+ if (!entry.components && read.components) entry.components = [...read.components]
+ if (!entry.sha && read.sha) entry.sha = read.sha
+ }
+ const fresh = ledger.pending.filter(e => e.mergedAt > now - PENDING_MS)
+ outcome.dropped = ledger.pending.filter(e => !fresh.includes(e))
+ ledger.pending = fresh
+
+ for (const component of RELEASE_COMPONENTS) {
+ const read = facts.releases[component.id]
+ const known = ledger.last?.[component.id]
+ // A re-run of an older tag's workflow is no newer release; the same tag read again only carries merges resolved since.
+ const order = read && known ? compareTags(read.tag, known.tag) : 1
+ if (!read || order < 0) continue
+ const { carries: keys, ...release } = read
+ const carried = waitingFor(ledger, component.id).filter(e => keys.includes(pendingKey(e)))
+ for (const entry of carried) (entry.shippedIn ??= {})[component.id] = release.tag
+ if (order === 0) continue
+ ;(ledger.last ??= {})[component.id] = release
+ const step = ledger.steps?.[component.id]
+ if (step && release.at >= step.at) {
+ const tasks = carried.map(e => named(state, e.groupId))
+ if (state.conversations.some(c => c.id === step.groupId)) {
+ say(row(step.groupId, `Verified ${release.tag}: ${tasks.length ? `it carries ${joined(tasks)}` : 'no task waited for it'}.`, [], `verified-${release.tag}`))
+ }
+ delete ledger.steps![component.id]
+ }
+ }
+
+ ledger.pending = ledger.pending.filter(entry => {
+ if (!shipped(entry)) return true
+ const group = state.conversations.find(c => c.id === entry.groupId)
+ const tags = [...new Set(Object.values(entry.shippedIn ?? {}))].sort()
+ const at = Math.max(entry.mergedAt, ...entry.components!.map(c => ledger.last?.[c]?.at ?? entry.mergedAt))
+ if (group) {
+ group.released = { at, tags }
+ outcome.shipped.push(group.id)
+ }
+ return false
+ })
+
+ for (const component of RELEASE_COMPONENTS) {
+ const step = ledger.steps?.[component.id]
+ if (!step || !ended(state.conversations.find(c => c.id === step.groupId))) continue
+ step.endedAt ??= now
+ if (now - step.endedAt >= STEP_GRACE_MS) delete ledger.steps![component.id]
+ }
+
+ const due = RELEASE_COMPONENTS.filter(c => releaseDue(ledger, c.id, now, rules))
+ if (!due.length || state.paused) return outcome
+ const id = stableId('release-step', state.id, projectId, due.map(c => c.id).join(','), String(now))
+ if (state.conversations.some(c => c.id === id)) return outcome
+ const integrator = integratorOf(state, projectId)
+ const waiting = [...new Set(due.flatMap(c => waitingFor(ledger, c.id).map(e => e.groupId)))].map(groupId => named(state, groupId))
+ const names = joined(due.map(c => c.name)), window = rules.releaseWindow
+ const brief = [`Release ${names}: ${waiting.length} merged ${waiting.length === 1 ? 'task waits' : 'tasks wait'} for it (${waiting.join('; ')}).`,
+ `Release between ${window.start} and ${window.end} (${window.timeZone}), applying the merged pull requests' rollout notes first, and verify each release is live.`,
+ 'The Swarm marks those tasks shipped once each tag\'s release workflow succeeds, and says so here.'].join('\n')
+ const number = nextConversationNumber(state)
+ state.groupCounter = number
+ state.conversations.push({ id, projectId, number, title: `Release ${names}`, leadId: chat?.leadId ?? null,
+ agentIds: [...chat?.leadId ? [chat.leadId] : [], ...integrator ? [integrator.id] : []], archived: false, brief, priority: 'P1',
+ assignment: null, lastMessageSequence: 0,
+ // The task contract (#3389) holds for what the Swarm opens too: a check, a priority, and why nobody is named as its requester.
+ checks: [{ id: stableId(id, 'check', '0'), description: RELEASE_CHECK, independent: false, evidence: null, passedBy: null }],
+ ledger: { askedAt: now, noRequesterReason: RELEASE_NO_REQUESTER } } as unknown as Conversation)
+ for (const component of due) (ledger.steps ??= {})[component.id] = { groupId: id, at: now }
+ outcome.opened = id
+ say(row(id, integrator
+ ? `${integrator.displayName ?? integrator.name}, this release is yours: assign it to yourself and release ${names}.\n${brief}\n\nNo requester: ${RELEASE_NO_REQUESTER}`
+ : `${brief}\nNo Integrator in this project: the PM assigns it.\n\nNo requester: ${RELEASE_NO_REQUESTER}`, integrator ? [integrator.id] : [], 'opened'))
+ return outcome
+}
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index a79bd9328..39a90add6 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -54,7 +54,7 @@ import { isBuddy, isBuddyChat, isBuddyReader, refuseBuddyRouting, routingRow } f
import { lostReasonWithoutMachine } from './lostReason.js'
import { LEAD_NAME } from './leadStart.js'
import { deleteInstructions, instructionsId, readNotes, revisionId, writeInstructions, writeNotes } from './instructionsStore.js'
-import { deleteRules, readRules, readRulesHistory, writeRules } from './policyStore.js'
+import { currentRules, deleteRules, readRules, readRulesHistory, writeRules } from './policyStore.js'
import { SEED_RULES } from './policy.js'
import { coordinatorNameOf, FIRST_INSTRUCTIONS, FIRST_SUMMARY, liveNotes, MAX_REVISIONS } from './instructions.js'
import { INSTRUCTIONS_TEMPLATE } from './instructionsTemplate.js'
@@ -69,6 +69,7 @@ import { RefusalMemory } from './dispatchRefusals.js'
import { candidatesFor, DISPATCH_RULES, dispatchPlan, freeCrew, laneCapacity, openTasks, pinBuilder, pullRequestPin, roundOf, type Skip } from './dispatch.js'
import { failRefusedStarts, judgedMachines, loseTasks, nextLossAt, recordTaskState, sweepForLead, sweepLiveness, SWEEP_EVERY_MS, unpurgedNotice } from './liveness.js'
import { endedReply, taskLineChats } from './taskLine.js'
+import { settleReleases, type ReleaseFacts, type ReleaseRules, type SettledReleases } from './releases.js'
import { archivable, archiveLine, archiveWaitsFor, idleNotices, reviewClosable, reviewCloseLine, reviewPullRequests, type SettledPullRequest } from './tidy.js'
import { clock, insertParts, loadActive, loadGroups, loadLightGroups, loadMachineParts, loadObserved, reassemble, split, type GroupData, type HeadData, type MachineData, type Part, type SwarmParts } from './parts/index.js'
import { groupsBy, listingDrops, quietSince, readBy, withoutHints } from './parts/indexed.js'
@@ -4980,6 +4981,35 @@ export class SuperTabStore {
})
}
+ /** The release list of [projectId] settled with what the worker read from GitHub (releases.ts settleReleases, task #3405), in
+ * one write: the tasks a verified release carries are marked released, and a due release step opens for the Integrator.
+ * It loads the project's pending tasks and open steps only, and writes nothing when nothing changed. Null when the Swarm or
+ * its project's list is gone. */
+ async settleReleases(tabId: string, projectId: string, facts: ReleaseFacts, given?: ReleaseRules): Promise<SettledReleases | null> {
+ const now = this.now()
+ return transaction(this.db, async tx => {
+ const row = await tx.superTab.findUnique({ where: { id: tabId }, select: SWARM_ROW })
+ if (!row || row.deletedAt) return null
+ // The list names the groups to load: the head alone first, then one load with them.
+ const head = (await tx.swarmHead.findUnique({ where: { id: `${tabId}:head` }, select: { data: true } }))?.data as { projects?: SwarmProject[] } | undefined
+ const ledger = head?.projects?.find(p => p.id === projectId)?.releases
+ if (!ledger) return null
+ const groupIds = [...new Set([...ledger.pending.map(e => e.groupId), ...Object.values(ledger.steps ?? {}).map(s => s!.groupId)])]
+ const loaded = await loadRow(tx, requireParts(row), { groupIds })
+ const state = cloneData(loaded.state)
+ const before = JSON.stringify(projectsOf(loaded.state).find(p => p.id === projectId)?.releases)
+ // The project's rules record as it reads now: its saved window, pace and backend pause, or the seed until one is saved.
+ const rules = given ?? (await currentRules(tx, tabId, projectId)).rules
+ const outcome = settleReleases(state, projectId, facts, now, rules)
+ if (!outcome.opened && !outcome.shipped.length && !outcome.messages.length
+ && JSON.stringify(projectsOf(state).find(p => p.id === projectId)?.releases) === before) return outcome
+ const sequences = numberMessages(state, outcome.messages, now)
+ await this.save(tx, loaded, state, clock.next())
+ await this.writeMessages(tx, tabId, state, outcome.messages, sequences)
+ return outcome
+ })
+ }
+
/**
* 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
diff --git a/backend/src/worker.ts b/backend/src/worker.ts
index 0512a3259..eee7c5e3c 100644
--- a/backend/src/worker.ts
+++ b/backend/src/worker.ts
@@ -26,6 +26,7 @@ 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 { appReleaseReader, startReleaseWatch, unknownReleases } from './superTabs/releaseWatch.js'
import { recordTrainRules, startMergeTrain } from './superTabs/mergeTrain/run.js'
import { teamAccountRequired } from './superTabs/machines.js'
import { PrismaApprovals } from './github/approvals.js'
@@ -81,6 +82,7 @@ async function start(): Promise<void> {
let stopLegacyDrop = (): void => {}
let stopArchive = (): void => {}
let stopPullRequestWatch = (): void => {}
+ let stopReleaseWatch = (): void => {}
let stopMergeTrain = (): void => {}
let stopDeliveries = (): void => {}
let stopRepush = (): void => {}
@@ -103,6 +105,7 @@ async function start(): Promise<void> {
stopLegacyDrop()
stopArchive()
stopPullRequestWatch()
+ stopReleaseWatch()
stopMergeTrain()
stopDeliveries()
stopRepush()
@@ -162,6 +165,10 @@ 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 5 minutes, merged tasks a verified release carries are marked released, and inside the release window a due release
+ // step opens for the project's Integrator (superTabs/releaseWatch.ts, task #3405). Without the app nothing can be verified:
+ // each pass says so for every project still waiting.
+ stopReleaseWatch = startReleaseWatch(prisma, swarms, () => githubApp ? appReleaseReader(githubApp) : unknownReleases)
// Every minute, each project whose merge train is switched on (its rules record; off until saved on) 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) {
diff --git a/backend/vitest.super-tabs.config.ts b/backend/vitest.super-tabs.config.ts
index df766fe8f..5470aca57 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/superTabReviewSteps.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', 'integration/crewDispatch.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/superTabReleases.test.ts', 'integration/superTabReviewSteps.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', 'integration/crewDispatch.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-release-schedule-plan.md b/docs/plans/2026-11-05-release-schedule-plan.md
new file mode 100644
index 000000000..b575c1768
--- /dev/null
+++ b/docs/plans/2026-11-05-release-schedule-plan.md
@@ -0,0 +1,122 @@
+# Releases scheduled by the Swarm, tasks marked Shipped — Implementation Plan
+
+> **For agentic workers:** Follow the project's Engineer workflow: this plan is the pull request's first commit; implement
+> task by task, each failing test committed before the code that passes it; one review on the pull request. No Execution
+> Handoff.
+
+**Goal:** The server opens a release step for the project's Integrator inside the release window (Desktop, CLI and web after
+each visible batch; the backend at most every 2 hours), and a verified release (its tag's release workflow succeeded) marks
+the merged tasks it carries Shipped, so the board's Shipped column is true without anyone typing it (task #3405, anh Dee's
+Swarm redesign, 11-05). Strengthens "Tell the PM what you want, and your crew ships it": shipped means people have it.
+
+**Architecture:** Three pieces in `backend/src/superTabs/`.
+
+1. `releases.ts` (pure): the release rules (window and pace, the same shape as the project rules record's `releaseWindow`
+ and `releasePace`, #3393, with `backendPause` 09:00-10:00 per River 11-05; constants in this one file until that record
+ lands), the release components (backend, CLI,
+ Desktop, web: tag suffix, release workflow, visible paths), and the decisions: `inReleaseWindow`, `componentsOf(files)`,
+ `releaseDue`, `shippedNow`. A per-project ledger on the project (`SwarmProject.releases`): merged tasks not shipped yet
+ (`pending`), the last verified release per component (`last`), and the open release step per component (`steps`).
+2. A merge recorded on a task (`conversation.merged`, and any server merge through the same `notePendingRelease`) adds the
+ task to its project's `pending`.
+3. `releaseWatch.ts` (worker, every 5 minutes): for each Swarm with recent work, each project with a ledger to settle and a
+ GitHub repository the app reads: resolve new pending entries (the merged pull request's merge commit; the task's own
+ pull request's files → components), read each component's newest successful tag-push run of its release workflow (the
+ verified release: tag + its artifacts built and checked by that workflow; the highest version, not the newest run) and
+ check that its tag sits on main. Each pending task's merge commit on main is found once (its pull request's own merge
+ commit, or the batch commit that closed the original), and a release carries a task when GitHub says the tag contains
+ that commit: ancestry, never the recorded merge time, which comes after the merge (review of #3228). Then `SuperTabStore.settleReleases` writes in one transaction: tasks shipped (`Conversation.released`, a line
+ in the release step), and a new release step for each due component, the Integrator named in it.
+
+**Tech Stack:** TypeScript, vitest, Prisma on MongoDB (no schema change), the Harness GitHub App (read-only token:
+contents, pull requests, actions).
+
+**Spec:** task #3405 brief; project instructions rev 78 (Integrator role; release window; PM schedule "Releases go out
+through the day"); sibling #3393 (`policy.ts` `ProjectRules.releaseWindow/releasePace`), #3402 (merge train records merges),
+#3397 (crew roles).
+
+## Global Constraints
+
+- Swarm code stays out of `cli/src/core`. Backend only; no Prisma schema change, no new collection, no new index.
+- Numbers live in one place (`RELEASE_RULES` in `releases.ts`) until the project rules record lands; then it reads the record.
+- Identity: the server writes as the Swarm (system rows), never as a person's or the machine owner's login.
+- Fail closed: a GitHub read that fails marks nothing shipped and opens no step on a guess; it is logged and retried.
+- No release switches: the schedule ships on.
+
+## Design
+
+- Growth: `pending` holds merged, unshipped tasks only; an entry leaves when its task ships, or after 14 days with a warning
+ (a merge no release carried). At most 100 entries; the oldest leaves first with a warning. `last` is one row per
+ component; `steps` one pointer per component, cleared when its release is verified or its step ends.
+- Concurrency: `settleReleases` loads the head and the groups it writes in one transaction (the store's optimistic part
+ versions); a concurrent write retries. Steps are opened by a stable id per (project, component, release slot), so a
+ retry or a second worker pass never opens two.
+- Read cost: one head read per candidate Swarm a pass; GitHub only for projects with pending entries or open steps; each
+ pending entry's pull request read once (cached in the entry); per project a pass, one workflow-run read and one compare for
+ each component something waits for; the Swarm candidates' aggregation once an hour.
+- Scale: 10x merges = ~300 pending a day at peak, still cleared by each release; the warning "pending full" and the
+ GitHub rate (5 minutes × 4 reads × projects) warn first.
+- Compatibility: older clients ignore `released`; Desktop keeps its merged = Shipped until a follow-up reads `released`
+ (proposal to the PM). Reads strip `releases` from projects, as they strip `schedule`.
+- Migration + rollback: none. An absent ledger starts empty; tasks merged before the release are not backfilled.
+ Rollback leaves harmless fields.
+- Audience: only the server writes the ledger; no command sets it. The step is a task in the project, read as any task.
+- Identity: system rows; the GitHub App's own token.
+- Failure: every skipped project or unreadable pull request is logged with its reason; a step that ends without a verified
+ release lets the next pass open a new one, so a failed release is seen again.
+- Platforms: server only.
+
+## Review Focus
+
+- The window, pause and pace edges (08:59/09:00/09:59/10:00/17:59/18:00 VN, 119/120 minutes).
+- That only a successful tag-push run of the component's own release workflow counts as verified, only for a tag on main,
+ and only for merges whose commit on main its tag contains.
+- A task touching two components ships only when both are released; docs-only work ships at its merge.
+
+## Task 1: release rules and decisions (pure)
+
+**Files:** `backend/src/superTabs/releases.ts` (new), `backend/src/superTabs/releases.test.ts` (new).
+
+**Interfaces:** `RELEASE_RULES`, `RELEASE_COMPONENTS`, `inReleaseWindow(rules, now)`, `componentsOf(files)`,
+`releaseDue(ledger, component, now, rules)`, `shippedNow(entry, ledger)`, `ReleaseLedger`, `PendingRelease`.
+
+- [ ] Failing tests: window edges in Asia/Ho_Chi_Minh; backend due only 120 minutes after the last verified backend release;
+ Desktop/CLI/web due right after a visible merge; nothing due with an open step; test-only and docs-only files map to
+ no component; an entry ships only when every component carries it.
+- [ ] Implement.
+
+## Task 2: merges join the ledger
+
+**Files:** `backend/src/superTabs/releases.ts`, `backend/src/superTabs/commands.ts`, `backend/src/superTabs/projects.ts`,
+`backend/src/superTabs/read/views.ts`, tests in `releases.test.ts` and `commands.test.ts`.
+
+**Interfaces:** `notePendingRelease(project, group, mergedUrl, mergedAt)`; `SwarmProject.releases?: ReleaseLedger`;
+`Conversation.released?: { at: number; tags: string[] }`.
+
+- [ ] Failing tests: `conversation.merged` adds the task once (a second record of the same merge adds nothing); the cap
+ drops the oldest; a project read carries no `releases`.
+- [ ] Implement.
+
+## Task 3: the store write
+
+**Files:** `backend/src/superTabs/store.ts`, `backend/src/superTabs/releases.ts`, `backend/src/superTabs/releases.test.ts`.
+
+**Interfaces:** `SuperTabStore.settleReleases(tabId, projectId, facts: ReleaseFacts): Promise<SettledReleases>`.
+
+- [ ] Failing tests (memory store): a verified release marks its tasks `released` and posts the line in the step; a due
+ component inside the window opens one release step naming the Integrator (role "Integrator", crew or start role);
+ outside the window none; at the pace none; a second call opens no second step; with no Integrator the step says the
+ PM assigns it.
+- [ ] Implement.
+
+## Task 4: the worker pass
+
+**Files:** `backend/src/superTabs/releaseWatch.ts` (new), `backend/src/superTabs/releaseWatch.test.ts` (new),
+`backend/src/github/app.ts` (a read-only `reader(repository)`), `backend/src/worker.ts`.
+
+**Interfaces:** `ReleaseReader` (`pull(url)`, `latestRelease(repository, component)`, `contains(repository, base, head)`),
+`appReleaseReader(app)`, `watchReleases(db, store, reader, now)`, `startReleaseWatch(db, store, reader, everyMs)`.
+
+- [ ] Failing tests with a fake GitHub: only a successful `push` run whose branch is `v<x.y.z><suffix>` counts; a failed or
+ missing read marks nothing and opens nothing; entries resolve once; the pass calls `settleReleases` with the facts.
+- [ ] Implement; start it in the worker.