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.

Swarm cleans up after itself: idle builders stop, finished groups archive (#1807)

0xken15e82f5950976b
diff --git a/backend/integration/superTabTidy.test.ts b/backend/integration/superTabTidy.test.ts
new file mode 100644
index 000000000..924a0a998
--- /dev/null
+++ b/backend/integration/superTabTidy.test.ts
@@ -0,0 +1,266 @@
+import { randomUUID } from 'node:crypto'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'
+import { PrismaClient } from '@prisma/client'
+import type { AuthUser } from '../src/lib/ssoAuth.js'
+import { SuperTabStore } from '../src/superTabs/store.js'
+import type { Command } from '../src/superTabs/commands.js'
+import type { MachineObservation } from '../src/superTabs/machines.js'
+import { poolRows, rosterRows } from './hostRows.test-support.js'
+import { archiveFinishedGroups, markFinishedGroups, type PullRequestState } from '../src/superTabs/archive.js'
+
+// Nobody tidies a Swarm by hand: a worker idle for 15 minutes is stopped on its Lead's poll and its host is asked to close
+// it. A fresh loopback replica set, created here.
+let replica: MongoMemoryReplSet
+let db: PrismaClient
+const owner: AuthUser = { sub: '200000000000000000000001', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
+const host: AuthUser = { sub: '200000000000000000000003', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
+const config = { engine: 'codex', model: 'fixture-model', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }
+const MINUTE = 60_000
+
+beforeAll(async () => {
+ replica = await MongoMemoryReplSet.create({ binary: { version: '7.0.24', downloadDir: join(tmpdir(), 'harness-super-tab-mongodb-binaries') },
+ replSet: { count: 1, ip: '127.0.0.1', storageEngine: 'wiredTiger' } })
+ const uri = replica.getUri(`swarm_tidy_test_${randomUUID().replaceAll('-', '_')}`)
+ await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], {
+ env: { ...process.env, DATABASE_URL: uri }, timeout: 60000,
+ })
+ db = new PrismaClient({ datasources: { db: { url: uri } } })
+ for (const user of [owner, host]) await db.user.create({ data: { id: user.sub, externalId: `fixture-${user.sub}`, email: user.email, autonomousEnv: user.autonomousEnv } })
+ for (const machineId of ['lead-host', 'test-host']) {
+ await db.machine.create({ data: { machineId, userId: host.sub, apiKey: `fixture-${machineId}`, managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })
+ await db.machineShare.create({ data: { machineId, ownerId: host.sub, autonomousEnv: 'prod', emails: [owner.email] } })
+ }
+})
+afterAll(async () => {
+ await db?.$disconnect()
+ await replica?.stop()
+})
+
+/** A Swarm whose Lead runs on one of host's machines and whose Swarm-started worker, on another, finished "Ship the parser". */
+async function swarm() {
+ let now = Date.parse('2026-10-27T08:00:00.000Z')
+ const timed = new SuperTabStore(db, () => now)
+ const tab = (await timed.create(owner, randomUUID(), 'Tidy', 'public')).id
+ const execute = (command: Command, user = owner, asAgentId?: string) => timed.execute(user, tab, { operationId: randomUUID(), command }, asAgentId)
+ const invitation = await execute({ type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })
+ await execute({ type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)
+ for (const [machineId, name] of [['lead-host', 'Lead Mac'], ['test-host', 'Worker Mac']]) {
+ await execute({ type: 'machine.contribute', machineId: machineId!, name: name!, cwd: '/repo', engines: ['codex'], maxAgents: 4 }, host)
+ }
+ const generations = new Map<string, string>()
+ for (const machineId of ['lead-host', 'test-host']) generations.set(machineId, (await poolRows(timed, host, machineId)).find(p => p.tabId === tab)!.machine.generation)
+ const harness = { lead: randomUUID(), worker: randomUUID() }
+ const add = async (conversationId: string, machineId: string, harnessId: string, name: string, lead = false) => String((await execute({ type: 'agent.add',
+ conversationId, machineId, harnessId, name, configuration: config, lead })).result.agentId)
+ const lead = await add('lead', 'lead-host', harness.lead, 'Lead', true)
+ const group = String((await execute({ type: 'conversation.create', title: 'Ship the parser', brief: 'Implement it',
+ checks: [{ description: 'Verified', independent: false }] })).result.conversationId)
+ const worker = await add(group, 'test-host', harness.worker, 'Worker')
+ // As agent.started records it for a Swarm start (commands.ts); agent.add stands for a person's own session.
+ const row = await db.swarmAgent.findFirstOrThrow({ where: { tabId: tab, key: worker } })
+ await db.swarmAgent.update({ where: { id: row.id }, data: { data: { ...row.data as object,
+ startedSession: { creationId: 'creation-1', sessionId: 'session-1', createdAt: new Date(now).toISOString() } } } })
+ const assignmentId = String((await execute({ type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId)
+ await execute({ type: 'work.cancel', conversationId: group, assignmentId, reason: 'Done elsewhere' })
+ // Its host took the cancel notice, as a running host does.
+ await db.superTabDelivery.updateMany({ where: { tabId: tab, agentId: worker, status: 'queued' }, data: { status: 'delivered' } })
+ const observe = (machineId: string, running: string[], extra: Partial<MachineObservation> = {}) => timed.observeMachine(host, tab, machineId, {
+ generation: generations.get(machineId)!, resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9,
+ diskTotalBytes: 500e9, projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture', os: 'macOS', gpuPercent: null },
+ quotas: [], tools: {}, runningHarnessIds: running, stoppedHarnessIds: [], ...extra })
+ const member = async () => (await timed.read(owner, tab)).state.agents.find(a => a.id === worker)!
+ const lines = async () => (await db.superTabMessage.findMany({ where: { tabId: tab }, orderBy: { sequence: 'asc' } }))
+ .filter(m => (m.source as { kind?: string } | null)?.kind === 'idle-stop')
+ /** Marks an agent as the Swarm started it, with [patch] (a role), as agent.started and agent.start record them. */
+ const started = async (agentId: string, patch: Record<string, unknown> = {}) => {
+ const part = await db.swarmAgent.findFirstOrThrow({ where: { tabId: tab, key: agentId } })
+ await db.swarmAgent.update({ where: { id: part.id }, data: { data: { ...part.data as object, ...patch,
+ startedSession: { creationId: `creation-${agentId}`, sessionId: `session-${agentId}`, createdAt: new Date(now).toISOString() } } } })
+ }
+ /** Its host took every message queued so far, as a running host does. */
+ const delivered = () => db.superTabDelivery.updateMany({ where: { tabId: tab, status: 'queued' }, data: { status: 'delivered' } })
+ return { timed, tab, execute, lead, group, worker, harness, observe, member, lines, add, started, delivered,
+ clock: { get now() { return now }, set now(value: number) { now = value } } }
+}
+
+describe('a worker left idle', () => {
+ it('is stopped on its Lead\'s poll 15 minutes after its last activity, and its host is asked to close it', async () => {
+ const f = await swarm()
+ f.clock.now += 14 * MINUTE
+ await f.observe('test-host', [f.harness.worker], { harnessUncommitted: { [f.harness.worker]: false } })
+ await f.timed.deliveries(host, f.tab, f.lead)
+ expect((await f.member()).workDecision).toBe('awaiting')
+ f.clock.now += MINUTE + 1_000
+ await f.observe('test-host', [f.harness.worker], { harnessUncommitted: { [f.harness.worker]: false } })
+ await f.timed.deliveries(host, f.tab, f.lead)
+ const member = await f.member()
+ expect(member.workDecision).toBe('stop')
+ expect((await rosterRows(f.timed, host, 'test-host')).find(r => r.agent.id === f.worker)!.agent).toMatchObject({ releaseId: member.releaseId })
+ expect(await f.lines()).toEqual([expect.objectContaining({ conversationId: f.group, recipientIds: [], text: 'Worker stopped: no work for 15 minutes.' })])
+ // A second poll finds it already stopping and writes nothing more.
+ f.clock.now += MINUTE
+ await f.timed.deliveries(host, f.tab, f.lead)
+ expect(await f.lines()).toHaveLength(1)
+ })
+
+ it('is kept while its host reports uncommitted changes, or does not say', async () => {
+ const f = await swarm()
+ f.clock.now += 20 * MINUTE
+ await f.observe('test-host', [f.harness.worker], { harnessUncommitted: { [f.harness.worker]: true } })
+ await f.timed.deliveries(host, f.tab, f.lead)
+ expect((await f.member()).workDecision).toBe('awaiting')
+ f.clock.now += MINUTE
+ await f.observe('test-host', [f.harness.worker])
+ await f.timed.deliveries(host, f.tab, f.lead)
+ expect((await f.member()).workDecision).toBe('awaiting')
+ })
+
+ it('is kept while a message waits for it', async () => {
+ const f = await swarm()
+ f.clock.now += 20 * MINUTE
+ await f.observe('test-host', [f.harness.worker], { harnessUncommitted: { [f.harness.worker]: false } })
+ // Written straight into the queue, as a delivery from a moment ago that its host has not picked up yet.
+ await db.superTabDelivery.create({ data: { id: randomUUID(), tabId: f.tab, conversationId: f.group, messageId: randomUUID(), agentId: f.worker,
+ machineId: 'test-host', machineOwnerId: host.sub, assignmentId: null, membershipGeneration: 'g', authorKind: 'person', authorId: owner.sub, authorGeneration: 'g' } })
+ await f.timed.deliveries(host, f.tab, f.lead)
+ expect((await f.member()).workDecision).toBe('awaiting')
+ })
+
+ it('is kept, as a Reviewer, while the work it reviews is open, even once its review group was archived', async () => {
+ const f = await swarm()
+ const reviewed = String((await f.execute({ type: 'conversation.create', title: 'Parser v2', brief: 'More parsing',
+ checks: [{ description: 'Verified', independent: false }] })).result.conversationId)
+ const builder = await f.add(reviewed, 'test-host', randomUUID(), 'Builder')
+ const work = String((await f.execute({ type: 'work.assign', conversationId: reviewed, agentId: builder })).result.assignmentId)
+ const review = String((await f.execute({ type: 'conversation.create', title: 'Review: Parser v2', brief: 'Review it', reviewOf: reviewed,
+ checks: [{ description: 'Verdict', independent: false }] })).result.conversationId)
+ const reviewerHarness = randomUUID()
+ const reviewer = await f.add(review, 'test-host', reviewerHarness, 'Reviewer')
+ await f.started(reviewer, { role: 'reviewer' })
+ const verdict = String((await f.execute({ type: 'work.assign', conversationId: review, agentId: reviewer })).result.assignmentId)
+ await f.execute({ type: 'work.cancel', conversationId: review, assignmentId: verdict, reason: 'Verdict given' })
+ await f.execute({ type: 'conversation.archive', conversationId: review, archived: true })
+ // Asleep, as the hourly sweep leaves an archived group once its Lead read its reports: ordinary loads leave it out.
+ const part = await db.swarmGroup.findFirstOrThrow({ where: { tabId: f.tab, key: review } })
+ await db.swarmGroup.update({ where: { id: part.id }, data: { dormant: true, data: { ...part.data as object, dormant: true } } })
+ await f.delivered()
+ const reviewerOf = async () => (await f.timed.read(owner, f.tab)).state.agents.find(a => a.id === reviewer)!
+ const poll = async () => {
+ await f.observe('test-host', [f.harness.worker, reviewerHarness], { harnessUncommitted: { [f.harness.worker]: false, [reviewerHarness]: false } })
+ await f.timed.deliveries(host, f.tab, f.lead)
+ }
+ f.clock.now += 20 * MINUTE
+ await poll()
+ expect((await reviewerOf()).workDecision).not.toBe('stop')
+ // The reviewed work ends: no re-check can come, and the Reviewer has been idle long enough.
+ await f.execute({ type: 'work.cancel', conversationId: reviewed, assignmentId: work, reason: 'Dropped' })
+ await f.delivered()
+ f.clock.now += MINUTE
+ await poll()
+ expect((await reviewerOf()).workDecision).toBe('stop')
+ })
+
+ it('is kept once the owner turned tidying off', async () => {
+ const f = await swarm()
+ await f.execute({ type: 'tab.tidy', enabled: false })
+ f.clock.now += 20 * MINUTE
+ await f.observe('test-host', [f.harness.worker], { harnessUncommitted: { [f.harness.worker]: false } })
+ await f.timed.deliveries(host, f.tab, f.lead)
+ expect((await f.member()).workDecision).toBe('awaiting')
+ })
+})
+
+describe('a finished group', () => {
+ const PR = 'https://github.com/acme/app/pull/7'
+ /** GitHub as the sweep reads it: each pull request's state, null when it cannot say. */
+ const github = (states: Record<string, PullRequestState>) => ({ read: [] as string[], closed: false,
+ async state(url: string) { this.read.push(url); return states[url] ?? null }, async done() { this.closed = true } })
+ const archived = async (f: Awaited<ReturnType<typeof swarm>>) => (await db.swarmGroup.findFirstOrThrow({ where: { tabId: f.tab, key: f.group } })).archived
+ const archiveLines = async (f: Awaited<ReturnType<typeof swarm>>) => (await db.superTabMessage.findMany({ where: { tabId: f.tab, conversationId: f.group } }))
+ .filter(m => (m.source as { kind?: string } | null)?.kind === 'auto-archive')
+ const linkPr = (f: Awaited<ReturnType<typeof swarm>>) => f.execute({ type: 'message.send', conversationId: f.group, text: `Pull request: ${PR}`, replyTo: null, recipientIds: [] })
+
+ it('archives 30 minutes after its last message once every pull request is merged or closed, with one quiet line', async () => {
+ const f = await swarm()
+ await linkPr(f)
+ const prs = github({ [PR]: 'merged' })
+ f.clock.now += 29 * MINUTE
+ await archiveFinishedGroups(db, f.timed, prs, f.clock.now)
+ expect(await archived(f)).toBe(false)
+ f.clock.now += MINUTE
+ await archiveFinishedGroups(db, f.timed, prs, f.clock.now)
+ expect(await archived(f)).toBe(true)
+ expect(prs.read).toContain(PR)
+ expect(prs.closed).toBe(true)
+ expect(await archiveLines(f)).toEqual([expect.objectContaining({ recipientIds: [],
+ text: 'Archived: the work is cancelled and its pull requests are merged or closed.' })])
+ // It never archives twice.
+ f.clock.now += 40 * MINUTE
+ await archiveFinishedGroups(db, f.timed, prs, f.clock.now)
+ expect(await archiveLines(f)).toHaveLength(1)
+ })
+
+ it('stays open while a pull request is open or GitHub cannot say', async () => {
+ for (const state of ['open', null] as const) {
+ const f = await swarm()
+ await linkPr(f)
+ f.clock.now += 40 * MINUTE
+ await archiveFinishedGroups(db, f.timed, github({ [PR]: state }), f.clock.now)
+ expect(await archived(f)).toBe(false)
+ }
+ })
+
+ it('stays open while a person\'s decision asked there waits', async () => {
+ const f = await swarm()
+ await db.superTabDecision.create({ data: { id: randomUUID(), tabId: f.tab, batchId: 'b', conversationId: f.group, projectId: 'p', personId: owner.sub,
+ askerAgentId: f.lead, assignmentId: null, question: 'Ship it?', options: ['Yes', 'No'], recommended: 0, unblocks: 'Release', createdAt: new Date(f.clock.now) } })
+ f.clock.now += 40 * MINUTE
+ await archiveFinishedGroups(db, f.timed, github({}), f.clock.now)
+ expect(await archived(f)).toBe(false)
+ })
+
+ it('stays open once the owner turned tidying off, and never archives the Lead conversation', async () => {
+ const f = await swarm()
+ await f.execute({ type: 'tab.tidy', enabled: false })
+ f.clock.now += 40 * MINUTE
+ await archiveFinishedGroups(db, f.timed, github({}), f.clock.now)
+ expect(await archived(f)).toBe(false)
+ expect((await db.swarmGroup.findMany({ where: { tabId: f.tab, archived: true } }))).toEqual([])
+ })
+})
+
+describe('the archive pass', () => {
+ it('reads each pull request once however many groups link it', async () => {
+ const PR = 'https://github.com/acme/app/pull/9'
+ const f = await swarm()
+ const second = String((await f.execute({ type: 'conversation.create', title: 'Docs', brief: 'Docs too', checks: [{ description: 'Verified', independent: false }] })).result.conversationId)
+ const worker2 = await f.add(second, 'test-host', randomUUID(), 'Writer')
+ const work = String((await f.execute({ type: 'work.assign', conversationId: second, agentId: worker2 })).result.assignmentId)
+ await f.execute({ type: 'work.cancel', conversationId: second, assignmentId: work, reason: 'Done elsewhere' })
+ for (const group of [f.group, second]) await f.execute({ type: 'message.send', conversationId: group, text: `Pull request: ${PR}`, replyTo: null, recipientIds: [] })
+ const read: string[] = []
+ f.clock.now += 40 * MINUTE
+ await archiveFinishedGroups(db, f.timed, { state: async url => { read.push(url); return 'open' }, done: async () => {} }, f.clock.now)
+ // Other tests' Swarms share this database, with links of their own.
+ expect(read.filter(url => url === PR)).toEqual([PR])
+ })
+
+ it('finds a finished group written before the finished mark once the worker marks it at startup', async () => {
+ const f = await swarm()
+ const part = await db.swarmGroup.findFirstOrThrow({ where: { tabId: f.tab, key: f.group } })
+ // As an older backend left it: no mark at all.
+ await db.$runCommandRaw({ update: 'SwarmGroup', updates: [{ q: { _id: part.id }, u: { $unset: { workFinished: '' } } }] })
+ const prs = { state: async () => null, done: async () => {} }
+ f.clock.now += 40 * MINUTE
+ await archiveFinishedGroups(db, f.timed, prs, f.clock.now)
+ expect((await db.swarmGroup.findUniqueOrThrow({ where: { id: part.id } })).archived).toBe(false)
+ expect(await markFinishedGroups(db)).toBeGreaterThanOrEqual(1)
+ await archiveFinishedGroups(db, f.timed, prs, f.clock.now)
+ expect((await db.swarmGroup.findUniqueOrThrow({ where: { id: part.id } })).archived).toBe(true)
+ })
+})
diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prisma
index 03e4db518..d0c90f1fd 100644
--- a/backend/prisma/schema.prisma
+++ b/backend/prisma/schema.prisma
@@ -1368,6 +1368,9 @@ model SwarmGroup {
hostMachineIds String[] @default([])
/// A short hash of the fields host rows read (read/hostRows.ts); a post leaves it. Missing on a part written before it.
hostDigest String?
+ /// Its task is done or cancelled: all the archive pass reads (superTabs/archive.ts). Marked at worker startup on a part
+ /// written before it (markFinishedGroups).
+ workFinished Boolean @default(false)
@@unique([tabId, key])
@@index([tabId, changedAt])
@@ -1376,6 +1379,7 @@ model SwarmGroup {
@@index([tabId, projectId, dormant, lastActivityAt])
@@index([tabId, projectId, dormant, reportSeq])
@@index([dormant, lastActivityAt])
+ @@index([workFinished, archived, lastActivityAt])
@@index([executionMachineId])
}
diff --git a/backend/src/github/app.test.ts b/backend/src/github/app.test.ts
index 84de96ecb..3de612778 100644
--- a/backend/src/github/app.test.ts
+++ b/backend/src/github/app.test.ts
@@ -1,6 +1,6 @@
import { createPublicKey, generateKeyPairSync, verify } from 'node:crypto'
import { describe, expect, it } from 'vitest'
-import { cacheSecret, githubAppConfig, GitHubAppError, readPrivateKey, TOKEN_PERMISSIONS } from './app.js'
+import { cacheSecret, githubAppConfig, GitHubAppError, PULL_READ_PERMISSIONS, readPrivateKey, TOKEN_PERMISSIONS } from './app.js'
import { FAKE_API, fakeApp, fakeGitHub, throwawayKey } from './fakeGitHub.js'
import { githubRepository } from './repository.js'
@@ -196,6 +196,29 @@ describe('default branch protection', () => {
expect(await app.defaultBranch(repo, token)).toEqual({ branch: 'main', protection: 'none' })
})
+ it('reads whether a pull request is open, merged or closed, with a token for its repository alone', async () => {
+ const { app, github } = setup()
+ const { token } = await app.createToken(77, repo, PULL_READ_PERMISSIONS)
+ expect(github.calls.at(-1)!.body).toMatchObject({ repositories: ['app'], permissions: { pull_requests: 'read', metadata: 'read' } })
+ github.pulls.set('acme/app#1', { state: 'open', merged_at: null })
+ github.pulls.set('acme/app#2', { state: 'closed', merged_at: '2026-10-27T08:00:00Z' })
+ github.pulls.set('acme/app#3', { state: 'closed', merged_at: null })
+ expect(await app.pullRequestState(repo, 1, token)).toBe('open')
+ expect(await app.pullRequestState(repo, 2, token)).toBe('merged')
+ expect(await app.pullRequestState(repo, 3, token)).toBe('closed')
+ expect(github.calls.at(-1)).toMatchObject({ method: 'GET', path: '/repos/acme/app/pulls/3', auth: `Bearer ${token}` })
+ })
+
+ it('answers null, never a guess, when GitHub cannot say', async () => {
+ const { app, github } = setup()
+ const { token } = await app.createToken(77, repo, PULL_READ_PERMISSIONS)
+ expect(await app.pullRequestState(repo, 9, token)).toBeNull()
+ github.pulls.set('acme/app#9', { state: 'open', merged_at: null })
+ expect(await app.pullRequestState(repo, 9, 'ghs_not_issued')).toBeNull()
+ github.control.down = true
+ expect(await app.pullRequestState(repo, 9, token)).toBeNull()
+ })
+
it('never talks to the real GitHub in these tests', () => {
expect(FAKE_API).not.toContain('api.github.com')
})
diff --git a/backend/src/github/app.ts b/backend/src/github/app.ts
index 4a7ba02ed..87b0f8d34 100644
--- a/backend/src/github/app.ts
+++ b/backend/src/github/app.ts
@@ -14,6 +14,8 @@ import { githubRepository, type GitHubRepository } from './repository.js'
export const TOKEN_PERMISSIONS = { contents: 'write', pull_requests: 'write', checks: 'read', actions: 'read', metadata: 'read' } as const
/** What preparing an agent's folder may do before the agent has a task: clone and fetch the repository, nothing more. */
export const PREPARE_PERMISSIONS = { contents: 'read', metadata: 'read' } as const
+/** What the Swarm's tidying reads before it archives a finished group: whether its pull requests are merged or closed. */
+export const PULL_READ_PERMISSIONS = { pull_requests: 'read', metadata: 'read' } as const
export type TokenPermissions = Readonly<Record<string, 'read' | 'write'>>
/** A refusal with the code clients act on; `details` adds fields beside it, such as the install link. */
@@ -245,6 +247,20 @@ export class GitHubApp {
throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub did not revoke the token (HTTP ${answer.status}).`, 502)
}
+ /** Whether pull request [number] is open, merged or closed (GET /repos/{owner}/{repo}/pulls/{number}); null when GitHub
+ * cannot say, which a caller must read as possibly open. */
+ async pullRequestState(repository: GitHubRepository, number: number, token: string): Promise<'open' | 'merged' | 'closed' | null> {
+ try {
+ const answer = await this.call('GET', `/repos/${repository.owner}/${repository.name}/pulls/${number}`, `Bearer ${token}`)
+ const body = answer.body as Record<string, unknown>
+ if (answer.status !== 200 || !['open', 'closed'].includes(String(body.state))) return null
+ return body.state === 'open' ? 'open' : typeof body.merged_at === 'string' ? 'merged' : 'closed'
+ } catch (error) {
+ if (error instanceof GitHubAppError) return null
+ throw error
+ }
+ }
+
/** The default branch and whether pushing to it straight needs a pull request, read with the agent's own token
* (metadata and contents read): rulesets first (GET /repos/{owner}/{repo}/rules/branches/{branch}), then classic
* protection's flag on the branch. Remembered ten minutes; a failed read is `unknown`, never a refusal. */
diff --git a/backend/src/github/fakeGitHub.ts b/backend/src/github/fakeGitHub.ts
index 186a592ee..ec4dc4690 100644
--- a/backend/src/github/fakeGitHub.ts
+++ b/backend/src/github/fakeGitHub.ts
@@ -22,6 +22,8 @@ export function fakeGitHub(options: { publicKey: KeyObject; appId: string; now?:
const owners = new Map<string, number>()
const renamed = new Map<string, string>()
const protection = new Map<string, { rules?: unknown[]; protected?: boolean; branch?: string; fail?: boolean }>()
+ /** Pull requests by `owner/name#number`, lower case: GitHub's state and when it was merged. */
+ const pulls = new Map<string, { state: 'open' | 'closed'; merged_at: string | null }>()
const calls: FakeCall[] = []
const issued = new Set<string>()
const revoked: string[] = []
@@ -78,12 +80,17 @@ export function fakeGitHub(options: { publicKey: KeyObject; appId: string; now?:
const branch = known.branch ?? 'main'
// A renamed repository: GitHub redirects its old name to its id, and fetch follows, so the body names it as it is now.
if (!repoPath[3]) return json(200, { full_name: renamed.get(`${repoPath[1]}/${repoPath[2]}`.toLowerCase()) ?? `${repoPath[1]}/${repoPath[2]}`, default_branch: branch })
+ const pull = /^\/pulls\/(\d+)$/.exec(repoPath[3] ?? '')
+ if (pull) {
+ const known = pulls.get(`${repoPath[1]}/${repoPath[2]}#${pull[1]}`.toLowerCase())
+ return known ? json(200, { number: Number(pull[1]), ...known }) : json(404, { message: 'Not Found' })
+ }
if (repoPath[3] === `/rules/branches/${encodeURIComponent(branch)}`) return json(200, known.rules ?? [])
if (repoPath[3] === `/branches/${encodeURIComponent(branch)}`) return json(200, { name: branch, protected: known.protected ?? false })
}
return json(404, { message: 'Not Found' })
}) as typeof globalThis.fetch
- return { fetch, calls, installed, owners, renamed, protection, revoked, issued, control }
+ return { fetch, calls, installed, owners, renamed, protection, pulls, revoked, issued, control }
}
/** A configured app talking to [github]. */
diff --git a/backend/src/superTabs/archive.test.ts b/backend/src/superTabs/archive.test.ts
new file mode 100644
index 000000000..ef4140ea3
--- /dev/null
+++ b/backend/src/superTabs/archive.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from 'vitest'
+import { fakeApp, fakeGitHub, throwawayKey } from '../github/fakeGitHub.js'
+import { appPullRequests, startSwarmArchive, unknownPullRequests } from './archive.js'
+
+const key = throwawayKey()
+const setup = () => {
+ const github = fakeGitHub({ publicKey: key.publicKey, appId: '424242' })
+ github.installed.set('acme/app', 77)
+ github.pulls.set('acme/app#7', { state: 'closed', merged_at: '2026-10-27T08:00:00Z' })
+ github.pulls.set('acme/app#8', { state: 'open', merged_at: null })
+ return { github, prs: appPullRequests(fakeApp(key.privateKey, github)) }
+}
+
+describe('pull request states for archiving', () => {
+ it('reads each with one read-only token per repository, revoked once the sweep is done', async () => {
+ const { github, prs } = setup()
+ expect(await prs.state('https://github.com/acme/app/pull/7')).toBe('merged')
+ expect(await prs.state('https://github.com/acme/app/pull/8')).toBe('open')
+ const minted = github.calls.filter(c => c.path.endsWith('/access_tokens'))
+ expect(minted).toHaveLength(1)
+ expect(minted[0]!.body).toMatchObject({ permissions: { pull_requests: 'read', metadata: 'read' } })
+ await prs.done()
+ expect(github.revoked).toEqual(['ghs_fixture_1'])
+ })
+
+ it('cannot say for a repository without the app, a link that is no pull request, or a token GitHub refuses', async () => {
+ const { github, prs } = setup()
+ expect(await prs.state('https://github.com/other/repo/pull/1')).toBeNull()
+ expect(await prs.state('https://github.com/acme/app/issues/7')).toBeNull()
+ github.control.tokenStatus = 500
+ const refused = appPullRequests(fakeApp(key.privateKey, github))
+ expect(await refused.state('https://github.com/acme/app/pull/7')).toBeNull()
+ await refused.done()
+ expect(github.revoked).toEqual([])
+ })
+
+ it('cannot say anything without the Harness GitHub App', async () => {
+ expect(await unknownPullRequests.state('https://github.com/acme/app/pull/7')).toBeNull()
+ await unknownPullRequests.done()
+ })
+})
+
+describe('the archive pass in the worker', () => {
+ it('runs at once and then on its interval, never two passes at the same time', async () => {
+ vi.useFakeTimers()
+ try {
+ let release = () => {}
+ const passes: number[] = []
+ const db = { swarmGroup: { findMany: async () => { passes.push(passes.length); await new Promise<void>(r => { release = r }); return [] } } }
+ const stop = startSwarmArchive(db as never, { archiveFinished: async () => false }, () => unknownPullRequests, 1_000)
+ await vi.advanceTimersByTimeAsync(0)
+ expect(passes).toHaveLength(1)
+ await vi.advanceTimersByTimeAsync(1_000)
+ expect(passes).toHaveLength(1)
+ release()
+ await vi.advanceTimersByTimeAsync(1_000)
+ expect(passes).toHaveLength(2)
+ stop()
+ release()
+ await vi.advanceTimersByTimeAsync(5_000)
+ expect(passes).toHaveLength(2)
+ } finally { vi.useRealTimers() }
+ })
+})
diff --git a/backend/src/superTabs/archive.ts b/backend/src/superTabs/archive.ts
new file mode 100644
index 000000000..fcc823a8b
--- /dev/null
+++ b/backend/src/superTabs/archive.ts
@@ -0,0 +1,108 @@
+import type { Prisma, PrismaClient } from '@prisma/client'
+import { PULL_READ_PERMISSIONS, type GitHubApp } from '../github/app.js'
+import { githubRepository, type GitHubRepository } from '../github/repository.js'
+import type { Conversation } from './model.js'
+import type { HeadData } from './parts/index.js'
+import type { SuperTabStore } from './store.js'
+import { ARCHIVE_QUIET_MS } from './tidy.js'
+import { logger } from '../utils/logger.js'
+
+// A finished group archives by itself (roadmap, December: nobody tidies a Swarm by hand): its task done or cancelled, quiet
+// for 30 minutes, no person's decision waiting there, and every pull request it links merged or closed. Only GitHub says
+// that, over the network, so this runs in the singleton worker and never inside a Swarm's write; the write itself checks
+// everything the Swarm knows again (store.ts archiveFinished).
+
+export type PullRequestState = 'open' | 'merged' | 'closed' | null
+/** What a sweep asks GitHub: a pull request's state (null: it cannot say), and `done` once the sweep is over. */
+export interface PullRequests { state(url: string): Promise<PullRequestState>; done(): Promise<void> }
+
+/** Without the Harness GitHub App nothing can say a pull request is merged: a group that links one stays open. */
+export const unknownPullRequests: PullRequests = { state: async () => null, done: async () => {} }
+
+const PULL = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/([1-9][0-9]*)$/
+
+/** Reads with the Harness GitHub App: one read-only token per repository for the whole sweep, revoked when it is done. A
+ * repository the app is not installed on, or any GitHub failure, reads as null. */
+export function appPullRequests(app: GitHubApp): PullRequests {
+ 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, PULL_READ_PERMISSIONS)).token
+ })().catch(() => null))
+ return tokens.get(key)!
+ }
+ return {
+ async state(url) {
+ const match = PULL.exec(url), repository = match ? githubRepository(`https://github.com/${match[1]}`) : null
+ const granted = repository ? await token(repository) : null
+ return granted ? app.pullRequestState(repository!, Number(match![2]), granted) : null
+ },
+ async done() {
+ for (const granted of tokens.values()) {
+ const value = await granted
+ if (value) await app.revoke(value).catch(() => {})
+ }
+ tokens.clear()
+ },
+ }
+}
+
+const BATCH = 500
+
+/** Marks every part written before the finished mark whose task is done or cancelled, so the pass finds it: run once by the
+ * worker at startup, as its other index work is. Every later write of a part sets the mark itself (parts/write.ts). */
+export async function markFinishedGroups(db: PrismaClient): Promise<number> {
+ const answer = await db.$runCommandRaw({ update: 'SwarmGroup', updates: [{ q: { workFinished: { $exists: false }, deleted: false,
+ 'data.assignment.status': { $in: ['done', 'cancelled'] } }, u: { $set: { workFinished: true } }, multi: true }] })
+ return Number((answer as { nModified?: number }).nModified ?? 0)
+}
+
+/** One pass: every unarchived group quiet for ARCHIVE_QUIET_MS whose task is done or cancelled (its finished mark), in a Swarm that keeps
+ * tidying on, is archived once GitHub says each of its pull requests is merged or closed. Read oldest first by a cursor,
+ * so groups that stay open never hold later ones back. */
+export async function archiveFinishedGroups(db: PrismaClient, store: Pick<SuperTabStore, 'archiveFinished'>, prs: PullRequests, now: number): Promise<number> {
+ const tidy = new Map<string, boolean>()
+ const tidyOn = async (tabId: string) => {
+ if (!tidy.has(tabId)) tidy.set(tabId, ((await db.swarmHead.findUnique({ where: { id: `${tabId}:head` } }))?.data as unknown as HeadData | undefined)?.tidy !== false)
+ return tidy.get(tabId)!
+ }
+ // One read per pull request a pass, however many groups link it.
+ const states = new Map<string, Promise<PullRequestState>>()
+ const stateOf = (url: string) => { if (!states.has(url)) states.set(url, prs.state(url)); return states.get(url)! }
+ let archived = 0, after: { at: Date; id: string } | null = null
+ try {
+ for (;;) {
+ const cursor: Prisma.SwarmGroupWhereInput = after ? { OR: [{ lastActivityAt: { gt: after.at } }, { lastActivityAt: after.at, id: { gt: after.id } }] } : {}
+ const rows = await db.swarmGroup.findMany({ where: { workFinished: true, archived: false, deleted: false, kind: null, lastActivityAt: { lte: new Date(now - ARCHIVE_QUIET_MS) }, ...cursor },
+ orderBy: [{ lastActivityAt: 'asc' }, { id: 'asc' }], take: BATCH, select: { id: true, tabId: true, key: true, lastActivityAt: true, data: true } })
+ for (const row of rows) {
+ const group = row.data as unknown as Conversation
+ if (group.audience || !['done', 'cancelled'].includes(group.assignment?.status ?? '') || !await tidyOn(row.tabId)) continue
+ const urls = group.pullRequestUrls ?? []
+ let settled = true
+ for (const url of urls) if (!['merged', 'closed'].includes(await stateOf(url) ?? '')) { settled = false; break }
+ if (settled && await store.archiveFinished(row.tabId, row.key, urls)) archived++
+ }
+ if (rows.length < BATCH) return archived
+ after = { at: rows.at(-1)!.lastActivityAt, id: rows.at(-1)!.id }
+ }
+ } finally { await prs.done() }
+}
+
+/** Runs the archive pass every 10 minutes in the singleton worker. */
+export function startSwarmArchive(db: PrismaClient, store: Pick<SuperTabStore, 'archiveFinished'>, prs: () => PullRequests, everyMs = 10 * 60_000): () => void {
+ let running = false
+ const run = () => {
+ if (running) return
+ running = true
+ void archiveFinishedGroups(db, store, prs(), Date.now()).then(count => { if (count) logger.info('[swarm-archive] archived', { count }) })
+ .catch(error => logger.warn('[swarm-archive] 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/commands.test.ts b/backend/src/superTabs/commands.test.ts
index 23596ac59..88d30b9ad 100644
--- a/backend/src/superTabs/commands.test.ts
+++ b/backend/src/superTabs/commands.test.ts
@@ -559,6 +559,38 @@ describe('tab.routingPolicy', () => {
})
})
+describe('tab.tidy', () => {
+ it('is on until the Swarm owner turns it off, and back on', () => {
+ const f = fixture()
+ expect(f.state.tidy).toBeUndefined()
+ f.run({ type: 'tab.tidy', enabled: false })
+ expect(f.state.tidy).toBe(false)
+ f.run({ type: 'tab.tidy', enabled: true })
+ expect(f.state.tidy).toBeUndefined()
+ })
+ it('refuses a collaborator and a Lead that quotes no message of the owner', () => {
+ const f = fixture()
+ f.invite('collaborator')
+ expect(() => f.run({ type: 'tab.tidy', enabled: false }, peer)).toThrow('Only the Swarm owner')
+ const lead = f.add('lead-harness', 'owner', 'lead', true)
+ expect(() => f.run({ type: 'tab.tidy', enabled: false }, { kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' })).toThrow('Only the Swarm owner')
+ expect(f.state.tidy).toBeUndefined()
+ })
+ it('lets a Lead pass on a chat message the owner wrote in the last day, and no older one', () => {
+ const f = fixture()
+ const lead = f.add('lead-harness', 'owner', 'lead', true)
+ const asLead: Actor = { kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' }
+ const ownerAuthor = { kind: 'person' as const, id: 'owner', name: 'owner', membershipGeneration: f.state.people[0]!.generation }
+ const askedIn = { conversationId: 'lead', messageId: 'm1' }
+ expect(() => f.run({ type: 'tab.tidy', enabled: false, askedIn }, asLead,
+ { askedIn: { author: ownerAuthor, source: false, createdAt: 1000 - 25 * 3_600_000 } })).toThrow('Only the Swarm owner')
+ expect(() => f.run({ type: 'tab.tidy', enabled: false, askedIn }, asLead,
+ { askedIn: { author: { ...ownerAuthor, kind: 'agent', id: lead }, source: false, createdAt: 900 } })).toThrow('Only the Swarm owner')
+ f.run({ type: 'tab.tidy', enabled: false, askedIn }, asLead, { askedIn: { author: ownerAuthor, source: false, createdAt: 900 } })
+ expect(f.state.tidy).toBe(false)
+ })
+})
+
const candidate = (id: string, patch: Record<string, unknown> = {}) => ({ id, kind: 'new', machineId: 'machine', engine: 'claude',
model: 'opus', effort: 'high', quality: 3, cost: 3, title: `Title ${id}`, label: `Label ${id}`, ...patch })
const record = (patch: Record<string, unknown> = {}) => ({ assessment: { difficulty: 'high', risk: 'low', why: 'Schema change.' },
@@ -940,7 +972,9 @@ it('blocks routing and starts until a finished worker is kept or stopped', () =>
requirements: { memoryBytes: 0, diskBytes: 0, maxCpuPercent: 100, tools: [], devices: [], quotaRequired: false } }
expect(() => f.run(route, f.leadActor)).toThrow('reuse, keep or stop')
expect(() => f.run({ type: 'agent.start', request, ...via }, f.leadActor, { contribution: f.contribution, ...decisionIn(group) })).toThrow('reuse, keep or stop')
- f.run({ type: 'agent.release', agentId: f.worker, decision: 'keep' }, f.leadActor)
+ f.run({ type: 'agent.release', agentId: f.worker, decision: 'keep' }, f.leadActor, { now: 5000 })
+ // A kept worker is idle from the keep, not from its task's end (tidy.ts).
+ expect(f.state.agents.find(a => a.id === f.worker)!.keptAt).toBe(5000)
expect(f.run(route, f.leadActor).routeDecisions).toHaveLength(1)
expect(f.run({ type: 'agent.start', request, ...via }, f.leadActor, { contribution: f.contribution, ...decisionIn(group) }).result.startId).toBeTruthy()
})
@@ -2605,3 +2639,38 @@ describe('the morning digest setting (digest.ts)', () => {
expect(digest()).toBeUndefined()
})
})
+
+describe('agent.stopRefused', () => {
+ /** A worker the idle check marked for stopping (tidy.ts), as it was before: awaiting its Lead's decision. */
+ function idleStopped() {
+ const f = fixture(), lead = f.add('lead', 'owner', 'lead', true), worker = f.add('worker', 'owner', f.group())
+ const target = f.state.agents.find(a => a.id === worker)!
+ Object.assign(target, { workDecision: 'stop', releaseId: 'idle-release', idleStop: { previous: 'awaiting' } })
+ const asWorker: Actor = { kind: 'agent', agentId: worker, machineOwnerId: 'host-owner' }
+ return { f, lead, worker, asWorker, member: () => f.state.agents.find(a => a.id === worker)! }
+ }
+
+ it('lets the worker\'s own host withdraw an idle stop its folder\'s changes forbid, restarting its idle time', () => {
+ const t = idleStopped()
+ t.f.run({ type: 'agent.stopRefused', agentId: t.worker, releaseId: 'idle-release' }, t.asWorker, { now: 7000 })
+ expect(t.member()).toMatchObject({ workDecision: 'awaiting', keptAt: 7000 })
+ expect(t.member().releaseId).toBeUndefined()
+ expect(t.member().idleStop).toBeUndefined()
+ })
+
+ it('refuses another agent, a stale stop, and a stop its Lead asked for', () => {
+ const t = idleStopped()
+ expect(() => t.f.run({ type: 'agent.stopRefused', agentId: t.worker, releaseId: 'idle-release' }, { kind: 'agent', agentId: t.lead, machineOwnerId: 'host-owner' })).toThrow('Only the execution host')
+ expect(() => t.f.run({ type: 'agent.stopRefused', agentId: t.worker, releaseId: 'older' }, t.asWorker)).toThrow('Only the execution host')
+ delete t.member().idleStop
+ expect(() => t.f.run({ type: 'agent.stopRefused', agentId: t.worker, releaseId: 'idle-release' }, t.asWorker)).toThrow('Only the execution host')
+ expect(t.member().workDecision).toBe('stop')
+ })
+
+ it('keeps a stop its Lead asked for after the idle check made it', () => {
+ const t = idleStopped()
+ t.f.run({ type: 'agent.release', agentId: t.worker, decision: 'stop' }, { kind: 'agent', agentId: t.lead, machineOwnerId: 'host-owner' })
+ expect(() => t.f.run({ type: 'agent.stopRefused', agentId: t.worker, releaseId: 'idle-release' }, t.asWorker)).toThrow('Only the execution host')
+ expect(t.member().workDecision).toBe('stop')
+ })
+})
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index 8fd0d0f12..5f17aab94 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -78,6 +78,7 @@ export const commandSchema = z.discriminatedUnion('type', [
z.object({ type: z.literal('tab.project'), machineId: id, project }).strict(),
z.object({ type: z.literal('tab.pause'), paused: z.boolean() }).strict(),
z.object({ type: z.literal('tab.routingPolicy'), policy: routingOverrideSchema.nullable() }).strict(),
+ z.object({ type: z.literal('tab.tidy'), enabled: z.boolean(), askedIn: askedInSchema.optional() }).strict(),
z.object({ type: z.literal('rule.set'), projectId: id.optional(), rule: ruleSchema, text: ruleTextSchema, askedIn: askedInSchema.optional() }).strict(),
z.object({ type: z.literal('rule.remove'), projectId: id.optional(), ruleId: id, askedIn: askedInSchema.optional() }).strict(),
z.object({ type: z.literal('project.create'), name: title, visibility: z.enum(['public', 'private']), brief: z.string().trim().max(8000).default('') }).strict(),
@@ -118,6 +119,7 @@ export const commandSchema = z.discriminatedUnion('type', [
z.object({ type: z.literal('agent.startSettled'), startId: id, warning: z.string().max(2000).nullable() }).strict(),
z.object({ type: z.literal('agent.startFailed'), startId: id, error: text }).strict(),
z.object({ type: z.literal('agent.stopLease'), agentId: id, releaseId: id }).strict(),
+ z.object({ type: z.literal('agent.stopRefused'), agentId: id, releaseId: id }).strict(),
z.object({ type: z.literal('agent.remove'), agentId: id, releaseId: id.optional() }).strict(),
z.object({ type: z.literal('agent.release'), agentId: id, decision: z.enum(['keep', 'stop']) }).strict(),
z.object({ type: z.literal('agent.sessionClosed'), agentId: id, harnessId: id }).strict(),
@@ -375,7 +377,7 @@ export function authorizeCommandAccess(state: SuperTabState, actor: Actor, comma
if ('projectId' in command && command.projectId) readProject(state, actor, command.projectId)
if ('agentId' in command) readAgent(state, actor, command.agentId)
if (command.type === 'agent.start') readConversation(state, actor, command.request.conversationId)
- if ((command.type === 'rule.set' || command.type === 'rule.remove' || command.type === 'project.skills') && command.askedIn) {
+ if ((command.type === 'rule.set' || command.type === 'rule.remove' || command.type === 'project.skills' || command.type === 'tab.tidy') && command.askedIn) {
readConversation(state, actor, command.askedIn.conversationId)
}
if ('startId' in command && command.type !== 'route.modelResult') {
@@ -961,6 +963,18 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
if (actor.kind === 'agent') controls(state, actor)
state.paused = command.paused
break
+ case 'tab.tidy': {
+ // The Swarm owner's, or a Lead's passing on a chat message the Swarm owner wrote in the last day, as rules are.
+ if (!(actor.kind === 'person' && actor.userId === state.ownerId)) {
+ const asked = actor.kind === 'agent' && ledProject(state, actor.agentId) && command.askedIn && context.askedIn
+ if (!asked || asked.author.kind !== 'person' || asked.author.id !== state.ownerId || asked.source || context.now - asked.createdAt > RULE_MESSAGE_MS) {
+ fail('OWNER_REQUIRED', 'Only the Swarm owner, or a Lead passing on a chat message the owner wrote in the last day, turns tidying on or off.', 403)
+ }
+ }
+ if (command.enabled) delete state.tidy
+ else state.tidy = false
+ break
+ }
case 'tab.routingPolicy':
if (actor.kind !== 'person' || actor.userId !== state.ownerId) fail('OWNER_REQUIRED', 'Only the Super Tab owner can change its routing policy.', 403)
if (command.policy && Object.keys(command.policy).length) state.routingPolicy = command.policy
@@ -1320,7 +1334,24 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma
}
if (target.workDecision === 'stop' && command.decision !== 'stop') fail('STOP_REQUESTED', 'This worker is stopping. Wait for its execution host.')
if (command.decision === 'stop' && target.workDecision !== 'stop') target.releaseId = operationId
+ // A stop its Lead or a person asks for is theirs, even over the idle check's: its host no longer withdraws it.
+ if (command.decision === 'stop') delete target.idleStop
target.workDecision = command.decision
+ if (command.decision === 'keep') target.keptAt = context.now
+ break
+ }
+ case 'agent.stopRefused': {
+ // Only the idle check's stop, and only its host: the session's folder had changes by the time it would close it
+ // (review of #1807). The worker is as it was, idle again from now. A stop its Lead or a person asked for stays.
+ const target = agent(state, command.agentId)
+ if (actor.kind !== 'agent' || actor.agentId !== target.id || target.workDecision !== 'stop' || command.releaseId !== target.releaseId || !target.idleStop) {
+ fail('STALE_RELEASE', 'Only the execution host can withdraw the current idle stop.', 403)
+ }
+ if (target.idleStop.previous) target.workDecision = target.idleStop.previous
+ else delete target.workDecision
+ delete target.releaseId
+ delete target.idleStop
+ target.keptAt = context.now
break
}
case 'agent.stopLease': {
diff --git a/backend/src/superTabs/decisions.ts b/backend/src/superTabs/decisions.ts
index e7cfb0db6..07b87008a 100644
--- a/backend/src/superTabs/decisions.ts
+++ b/backend/src/superTabs/decisions.ts
@@ -77,6 +77,11 @@ export function answerDecision(state: SuperTabState, actor: Actor, decision: Dec
/** Mongo omits unset fields, so `answeredAt: null` alone would miss a row written without it. */
const waiting: Prisma.SuperTabDecisionWhereInput = { OR: [{ answeredAt: null }, { answeredAt: { isSet: false } }] }
+/** Whether a person's decision asked in this conversation still waits: a group that has one is never archived by itself. */
+export async function waitingIn(tx: Tx, tabId: string, conversationId: string): Promise<boolean> {
+ return !!await tx.superTabDecision.findFirst({ where: { tabId, conversationId, ...waiting }, select: { id: true } })
+}
+
/** What makes an ask a repeat: the same asker, task, person, conversation, question, options, recommendation and what it
* unblocks. Another asker, another task or other options with the same text is a decision of its own (review of #1753). */
const repeatKey = (d: Pick<DecisionDraft, 'askerAgentId' | 'assignmentId' | 'personId' | 'conversationId' | 'question' | 'options' | 'recommended' | 'unblocks'>) =>
diff --git a/backend/src/superTabs/machines.ts b/backend/src/superTabs/machines.ts
index 1503e7fa5..1399ca5cb 100644
--- a/backend/src/superTabs/machines.ts
+++ b/backend/src/superTabs/machines.ts
@@ -89,6 +89,9 @@ export const machineObservationSchema = z.object({ generation: z.string().max(16
/** When each running agent's screen or transcript last changed (epoch ms); its lease renews on recent progress
* (liveness.ts). Absent from hosts before it, whose agents renew by running alone. */
harnessProgress: z.record(z.string().max(160), z.number().int().nonnegative()).refine(v => Object.keys(v).length <= 1000).optional(),
+ /** Whether each running Swarm session's folder has uncommitted changes (git status), for those its host could read.
+ * Only a session reported clean is ever stopped for being idle (tidy.ts). Absent from hosts before it. */
+ harnessUncommitted: z.record(z.string().max(160), z.boolean()).refine(v => Object.keys(v).length <= 1000).optional(),
/** The Local models add-on (docs/plans/2026-10-23-swarm-local-models.md); absent from hosts before it. On the Swarm's
* grid: what this machine serves there (`local` an engine of its own, `api` a saved API it shares), usable by agents on
* any machine. On any other grid: a model its owner may use there (`shared`, shared with them), usable only by agents
diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.ts
index ec069d0ab..a7cd6e92a 100644
--- a/backend/src/superTabs/model.ts
+++ b/backend/src/superTabs/model.ts
@@ -31,6 +31,11 @@ export interface Agent {
roleId?: string | null
/** A finished worker stays undecided even when its group receives a new brief. */
workDecision?: 'awaiting' | 'keep' | 'stop'
+ /** When its Lead last decided keep: a kept worker is idle from then (tidy.ts). */
+ keptAt?: number
+ /** Set while its stop is the idle check's (tidy.ts), with the decision it had before: its host withdraws that stop when
+ * the session's folder has changes by the time it would close it (agent.stopRefused). */
+ idleStop?: { previous: 'awaiting' | 'keep' | null }
releaseId?: string
/** Captured from the original Swarm launch, never inferred from a later live session with the same id. */
startedSession?: { creationId: string; sessionId: string; createdAt: string }
@@ -208,6 +213,8 @@ export interface SuperTabState {
/** Owner-only sharing configuration; visibleState always removes it. */
sharing?: import('./sharing.js').SwarmSharing
paused: boolean
+ /** Idle workers stop and finished groups archive by themselves (tidy.ts); false once the owner turns it off. */
+ tidy?: false
people: Person[]
agents: Agent[]
conversations: Conversation[]
diff --git a/backend/src/superTabs/parts/write.test.ts b/backend/src/superTabs/parts/write.test.ts
index 4e98ee9fd..b4ddab1fa 100644
--- a/backend/src/superTabs/parts/write.test.ts
+++ b/backend/src/superTabs/parts/write.test.ts
@@ -26,3 +26,16 @@ describe('the host-fields digest a conversation write stores (group 3b)', () =>
}
})
})
+
+describe('the finished-work mark a conversation write stores', () => {
+ const group = (status: string | null): GroupData => ({ id: 'g', projectId: 'p', title: 'Work', leadId: 'lead', agentIds: ['lead'], archived: false,
+ brief: '', checks: [], lastMessageSequence: 0, assignment: status === null ? null : { id: 'w', agentId: 'worker', status: status as never,
+ configuration: { engine: 'codex', model: null, effort: null, contextWindow: null, engineVersion: null },
+ execution: { machineId: 'm', harnessId: 'h', machineOwnerId: 'o' }, result: null } })
+
+ it('is set only while its task is done or cancelled: the archive pass reads only those (archive.ts)', () => {
+ expect(extracted('group', group('done'), 1).workFinished).toBe(true)
+ expect(extracted('group', group('cancelled'), 1).workFinished).toBe(true)
+ for (const status of ['working', 'review', 'lost', 'stopped', null]) expect(extracted('group', group(status), 1).workFinished).toBe(false)
+ })
+})
diff --git a/backend/src/superTabs/parts/write.ts b/backend/src/superTabs/parts/write.ts
index 9af04604a..34df859b5 100644
--- a/backend/src/superTabs/parts/write.ts
+++ b/backend/src/superTabs/parts/write.ts
@@ -66,7 +66,8 @@ export function extracted(kind: PartKind, data: unknown, stamp: number): Record<
return { projectId: group.projectId ?? null, kind: group.kind ?? null, archived: group.archived, dormant: !!group.dormant,
agentIds: group.agentIds, executionMachineId: activeWork(group) ? group.assignment!.execution.machineId : null,
messageSeq: group.messageSeq ?? 0, reportSeq: group.reportSeq ?? 0,
- lastActivityAt: group.lastActivityAt ? new Date(group.lastActivityAt) : new Date(stamp), hostDigest: hostDigest(group) }
+ lastActivityAt: group.lastActivityAt ? new Date(group.lastActivityAt) : new Date(stamp), hostDigest: hostDigest(group),
+ workFinished: ['done', 'cancelled'].includes(group.assignment?.status ?? '') }
}
case 'agent': {
const agent = data as Agent
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index c0dd7b9a1..c7b043072 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -15,16 +15,17 @@ import { logger } from '../utils/logger.js'
import { canReadAgent, canReadGroup, canWatchAgent, groupProject, ledProject, projectOf, projectsOf, agentProjectId, readConversation, roleVersion, type ProjectVisibility } from './projects.js'
import { bindSession, makeProjectPrivate } from './sessionScope.js'
import { confidentialSessions, otherRegistrations, recordConfidential } from './confidential.js'
-import { answersRequest, noteProjectReports, projectUpdateRequest } from './projectUpdates.js'
+import { answersRequest, dirtyGroups, noteProjectReports, projectUpdateRequest } from './projectUpdates.js'
import { digestDue, digestRequest, digestSince } from './digest.js'
import { judgedMachines, loseTasks, sweepLiveness, SWEEP_EVERY_MS } from './liveness.js'
+import { archivable, archiveLine, stopIdleWorkers, stoppedMachines } from './tidy.js'
import { clock, insertParts, lastChangedAt, loadActive, reassemble, split, type HeadData, type SwarmParts } from './parts/index.js'
import { commitParts, indexesOf, numberMessages, type Touch, type Written } from './parts/commit.js'
import { touchesFor } from './parts/touches.js'
import { revokeNativeContexts, SuperTabNativeStore } from './native.js'
import {
- activeWork, actorKey, agent, agentOnly, appendPullRequestUrls, author, conversation, createSuperTab, fail, person, stableId, visibleState, finishWorker,
- SuperTabError, isLeads, parkLaterConversations, syncLeads, type Actor, type Agent, type Assignment, type Author, type MessageDraft, type SuperTabState,
+ activeWork, actorKey, agent, agentOnly, agentRole, appendPullRequestUrls, author, conversation, createSuperTab, fail, person, stableId, visibleState, finishWorker,
+ SuperTabError, isLeads, parkLaterConversations, syncLeads, type Actor, type Agent, type Assignment, type Author, type Conversation, type MessageDraft, type SuperTabState,
} from './model.js'
import type { HoldReason } from './holdReason.js'
import { agentDisplayName } from './agentNames.js'
@@ -33,7 +34,7 @@ import { accrueLent } from './leaderboard/lent.js'
import { mayDrive, TERMINAL_ANSWER_MS, TERMINAL_EXPIRY_MS, TERMINAL_PICKUP_MS, type TerminalEffect } from './terminal.js'
import { closeAssignment, closeUnassignedStart, readDecision, timedDecisionOf, writeRouteEffects } from './routeDecisions.js'
import { listMentions, markDone, mentionsWaiting, readMention, resolveByReply, writeMentions } from './mentions.js'
-import { answerable, listDecisions, readAskedDecision, recordAnswer, waitingInProject, writeDecisions } from './decisions.js'
+import { answerable, listDecisions, readAskedDecision, recordAnswer, waitingIn, waitingInProject, writeDecisions } from './decisions.js'
import { DEFAULT_ROUTING_POLICY, effectivePolicy, routingPolicySchema, type RoutingPolicy } from './routingPolicy.js'
import { authenticatedEmail, authorizeSwarmJoin, configureSharing, joinSwarmSchema, requireSharingOwner,
saveSharingSchema, sharingDetails, type JoinSwarm, type SaveSharing } from './sharing.js'
@@ -722,7 +723,7 @@ export class SuperTabStore {
const reply = await tx.superTabMessage.findFirst({ where: { id: command.replyTo, tabId, conversationId: command.conversationId } })
if (reply) context.reply = { id: reply.id, conversationId: reply.conversationId, author: reply.author as unknown as Author }
}
- if ((command.type === 'rule.set' || command.type === 'rule.remove' || command.type === 'project.skills') && command.askedIn) {
+ if ((command.type === 'rule.set' || command.type === 'rule.remove' || command.type === 'project.skills' || command.type === 'tab.tidy') && command.askedIn) {
const asked = await tx.superTabMessage.findFirst({ where: { id: command.askedIn.messageId, tabId, conversationId: command.askedIn.conversationId } })
if (asked) context.askedIn = { author: asked.author as unknown as Author, source: !!asked.source, createdAt: asked.createdAt.getTime() }
}
@@ -1593,6 +1594,13 @@ export class SuperTabStore {
const target = agent(state, agentId)
// A Lead's poll runs the time checks (liveness.ts): lost work wakes it in this same poll.
const written = ledProject(state, agentId) ? sweepLiveness(state, this.now()) : []
+ // The Lead's poll stops its project's idle workers too (tidy.ts): it is where what waits for each agent is known.
+ const reviewers = led ? state.agents.filter(a => agentRole(a) === 'reviewer' && a.workDecision !== 'stop' && agentProjectId(state, a) === led.id).map(a => a.id) : []
+ const asleep = reviewers.length ? (await tx.swarmGroup.findMany({ where: { tabId, deleted: false, dormant: true, agentIds: { hasSome: reviewers } },
+ select: { data: true } })).map(row => row.data as unknown as Conversation) : []
+ const idle = led ? stopIdleWorkers(state, led.id, this.now(), new Set((await tx.superTabDelivery.findMany({
+ where: { tabId, status: { in: [...OPEN_DELIVERY] } }, select: { agentId: true }, distinct: ['agentId'] })).map(d => d.agentId)), asleep) : []
+ written.push(...idle)
const update = projectUpdateRequest(state, target, this.now())
let woken = false
if (update) {
@@ -1624,7 +1632,9 @@ export class SuperTabStore {
}
// One write for all: the time checks' changes, the digest and the wake-ups'.
const sequences = numberMessages(state, written, this.now())
- await this.save(tx, loaded, state, clock.next(), [...judgedMachines(state, written), ...woken ? [{ kind: 'agent' as const, key: agentId }] : []])
+ // A stop was judged from its machine's report that the session is clean: a newer report makes this write retry.
+ await this.save(tx, loaded, state, clock.next(), [...judgedMachines(state, written), ...stoppedMachines(state, idle),
+ ...woken ? [{ kind: 'agent' as const, key: agentId }] : []])
await this.writeMessages(tx, tabId, state, written, sequences)
const rows = await tx.superTabDelivery.findMany({ where: { tabId, agentId, status: { in: [...OPEN_DELIVERY] } },
orderBy: { createdAt: 'asc' }, take: 100 })
@@ -1697,6 +1707,30 @@ export class SuperTabStore {
return { held: true }
}
+ /** Archives a finished group whose pull requests `checked` were all read merged or closed (archive.ts), only if it still
+ * qualifies inside this write: no message since, no decision waiting and no pull request linked since the read. Its
+ * queued deliveries are kept for when it reopens, as a person's archive keeps them. True when it archived. */
+ async archiveFinished(tabId: string, groupId: string, checked: readonly string[]): Promise<boolean> {
+ return transaction(this.db, async tx => {
+ const row = await tx.superTab.findUnique({ where: { id: tabId } })
+ if (!row) return false
+ const loaded = await loadRow(tx, requireParts(row), { groupIds: [groupId] }), state = structuredClone(loaded.state)
+ const group = state.conversations.find(c => c.id === groupId)
+ const now = this.now()
+ if (!group || !archivable(state, group, now) || (group.pullRequestUrls ?? []).some(url => !checked.includes(url))) return false
+ if (await waitingIn(tx, tabId, groupId)) return false
+ group.archived = true
+ const line = archiveLine(state, group, now), rows = line ? [line] : []
+ const sequences = numberMessages(state, rows, now)
+ if (!dirtyGroups(state, groupProject(state, group)).includes(group)) group.dormant = true
+ // As a person's archive does (execute): a claim of a delivery here conflicts with this write.
+ await tx.superTabDelivery.updateMany({ where: { tabId, conversationId: groupId, status: { in: [...OPEN_DELIVERY] } }, data: { updatedAt: new Date(now) } })
+ await this.save(tx, loaded, state, clock.next())
+ await this.writeMessages(tx, tabId, state, rows, sequences)
+ return true
+ })
+ }
+
/** Only the recorded execution host may attest that the actual session/attempt has stopped. */
async stopped(user: AuthUser, tabId: string, assignmentId: string, receipt: string) {
let ended: WorkHold[] = []
diff --git a/backend/src/superTabs/tidy.test.ts b/backend/src/superTabs/tidy.test.ts
new file mode 100644
index 000000000..58d5d249e
--- /dev/null
+++ b/backend/src/superTabs/tidy.test.ts
@@ -0,0 +1,151 @@
+import { describe, expect, it } from 'vitest'
+import type { Agent, Assignment, Conversation, SuperTabState } from './model.js'
+import { ARCHIVE_QUIET_MS, archivable, IDLE_STOP_MS, stopIdleWorkers } from './tidy.js'
+
+const MINUTE = 60_000
+const START = Date.parse('2026-10-27T08:00:00.000Z')
+const iso = (at: number) => new Date(at).toISOString()
+const config = { engine: 'claude', model: null, effort: null, contextWindow: null, engineVersion: null }
+const done = (patch: Partial<Assignment> = {}): Assignment => ({ id: 'a1', agentId: 'w', status: 'done', result: 'Merged', configuration: config,
+ execution: { machineId: 'm', harnessId: 'h', machineOwnerId: 'o' }, progressAt: START, ...patch })
+const worker = (patch: Partial<Agent> = {}): Agent => ({ id: 'w', machineId: 'm', harnessId: 'h', machineOwnerId: 'o', contributorId: 'p',
+ membershipGeneration: 'g', name: 'Builder', displayName: 'Rowan', configuration: config,
+ startedSession: { creationId: 'c1', sessionId: 's1', createdAt: iso(START - 60 * MINUTE) }, ...patch })
+const group = (patch: Partial<Conversation> = {}): Conversation => ({ id: 'g1', title: 'Task', leadId: 'L', agentIds: ['L', 'w'], archived: false,
+ brief: 'Do it', checks: [], assignment: done(), lastMessageSequence: 3, lastActivityAt: iso(START), ...patch })
+
+/** A Swarm whose Lead `L` runs on machine `m` with worker `w` (session `h`); the machine reported at `reportAt` that `h` runs
+ * with nothing uncommitted, unless `uncommitted` says otherwise. */
+function swarm(opts: { agents?: Agent[]; groups?: Conversation[]; reportAt?: number; uncommitted?: Record<string, boolean> | null; running?: string[] } = {}) {
+ const uncommitted = opts.uncommitted === undefined ? { h: false } : opts.uncommitted
+ return {
+ id: 't', ownerId: 'p', paused: false,
+ agents: [worker({ id: 'L', harnessId: 'hl', name: 'Lead', displayName: 'River' }), ...opts.agents ?? [worker()]],
+ people: [{ id: 'p', email: '[email protected]', role: 'owner', generation: 'g' }],
+ machines: [{ machineId: 'm', name: 'Studio', observation: { receivedAt: opts.reportAt ?? START + 15 * MINUTE, runningHarnessIds: opts.running ?? ['hl', 'h'],
+ stoppedHarnessIds: [], ...uncommitted ? { harnessUncommitted: uncommitted } : {} } }],
+ conversations: [{ id: 'lead', title: 'Lead', leadId: 'L', agentIds: ['L'], archived: false, brief: '', checks: [], assignment: null, lastMessageSequence: 0 },
+ ...opts.groups ?? [group()]],
+ } as unknown as SuperTabState
+}
+const at = START + IDLE_STOP_MS
+const target = (state: SuperTabState, id = 'w') => state.agents.find(a => a.id === id)!
+
+describe('stopping idle workers', () => {
+ it('stops a Swarm-started Builder 15 minutes after its last activity, with one quiet line in its last group', () => {
+ const state = swarm()
+ const rows = stopIdleWorkers(state, 'lead', at, new Set())
+ expect(target(state)).toMatchObject({ workDecision: 'stop' })
+ expect(target(state).releaseId).toEqual(expect.any(String))
+ // Marked as the idle check's, so its host may withdraw it if its folder changed since (agent.stopRefused).
+ expect(target(state).idleStop).toEqual({ previous: null })
+ expect(rows).toEqual([expect.objectContaining({ conversationId: 'g1', recipients: [], replyTo: null,
+ author: expect.objectContaining({ kind: 'agent', id: 'L' }), text: 'Rowan stopped: no work for 15 minutes.',
+ source: { kind: 'idle-stop', agentId: 'w' } })])
+ })
+
+ it('waits until a full 15 minutes have passed since its group last spoke', () => {
+ const state = swarm({ groups: [group({ lastActivityAt: iso(START + 5 * MINUTE) })] })
+ expect(stopIdleWorkers(state, 'lead', at, new Set())).toEqual([])
+ expect(target(state).workDecision).toBeUndefined()
+ state.machines![0]!.observation!.receivedAt = at + 5 * MINUTE
+ expect(stopIdleWorkers(state, 'lead', at + 5 * MINUTE, new Set())).toHaveLength(1)
+ })
+
+ it('counts its start, its last progress and a keep decision as activity', () => {
+ const fresh = swarm({ agents: [worker({ startedSession: { creationId: 'c', sessionId: 's', createdAt: iso(START + MINUTE) } })], groups: [] })
+ expect(stopIdleWorkers(fresh, 'lead', at, new Set())).toEqual([])
+ const progressed = swarm({ groups: [group({ assignment: done({ progressAt: START + MINUTE }) })] })
+ expect(stopIdleWorkers(progressed, 'lead', at, new Set())).toEqual([])
+ const kept = swarm({ agents: [worker({ workDecision: 'keep', keptAt: START + MINUTE })] })
+ expect(stopIdleWorkers(kept, 'lead', at, new Set())).toEqual([])
+ kept.machines![0]!.observation!.receivedAt = at + MINUTE
+ expect(stopIdleWorkers(kept, 'lead', at + MINUTE, new Set())).toHaveLength(1)
+ })
+
+ it('stops a worker that never got a task, saying so in the Lead conversation when it sits in no group', () => {
+ const state = swarm({ groups: [] })
+ expect(stopIdleWorkers(state, 'lead', at, new Set())).toEqual([expect.objectContaining({ conversationId: 'lead' })])
+ expect(target(state).workDecision).toBe('stop')
+ })
+
+ it('never stops a worker with active work, a queued delivery, or uncommitted changes', () => {
+ expect(stopIdleWorkers(swarm({ groups: [group({ assignment: done({ status: 'working' }) })] }), 'lead', at, new Set())).toEqual([])
+ expect(stopIdleWorkers(swarm(), 'lead', at, new Set(['w']))).toEqual([])
+ expect(stopIdleWorkers(swarm({ uncommitted: { h: true } }), 'lead', at, new Set())).toEqual([])
+ })
+
+ it('never stops a worker its host has not said is clean: an older host, a session not running, or a silent machine', () => {
+ expect(stopIdleWorkers(swarm({ uncommitted: null }), 'lead', at, new Set())).toEqual([])
+ expect(stopIdleWorkers(swarm({ uncommitted: { other: false } }), 'lead', at, new Set())).toEqual([])
+ expect(stopIdleWorkers(swarm({ running: ['hl'] }), 'lead', at, new Set())).toEqual([])
+ expect(stopIdleWorkers(swarm({ reportAt: at - 3 * MINUTE }), 'lead', at, new Set())).toEqual([])
+ })
+
+ it('leaves Leads, people\'s own sessions, stopping workers and workers waiting out a usage limit alone', () => {
+ const lead = swarm({ agents: [], uncommitted: { hl: false } })
+ expect(stopIdleWorkers(lead, 'lead', at, new Set())).toEqual([])
+ expect(stopIdleWorkers(swarm({ agents: [worker({ startedSession: undefined })] }), 'lead', at, new Set())).toEqual([])
+ const stopping = swarm({ agents: [worker({ workDecision: 'stop', releaseId: 'r1' })] })
+ expect(stopIdleWorkers(stopping, 'lead', at, new Set())).toEqual([])
+ expect(target(stopping).releaseId).toBe('r1')
+ const limited = swarm({ agents: [worker({ lostTask: { conversationId: 'g1', assignmentId: 'a1', reason: 'limit', at: START, resumeAt: iso(at + MINUTE) } })],
+ groups: [group({ assignment: done({ status: 'lost' }) })] })
+ expect(stopIdleWorkers(limited, 'lead', at, new Set())).toEqual([])
+ })
+
+ it('keeps a worker waiting out a usage limit past its reset time, until its task resumes or is handed on', () => {
+ const lostTask = { conversationId: 'g1', assignmentId: 'a1', reason: 'limit', at: START, resumeAt: iso(START + MINUTE) }
+ const lost = () => group({ assignment: done({ status: 'lost', lost: { reason: 'limit', at: START, resumeAt: iso(START + MINUTE) } }) })
+ // The reset passed long ago and the resume is late: its task still waits for it.
+ const late = swarm({ agents: [worker({ lostTask })], groups: [lost()], reportAt: at + 10 * MINUTE })
+ expect(stopIdleWorkers(late, 'lead', at + 10 * MINUTE, new Set())).toEqual([])
+ // Handed on to another attempt, or cancelled: nothing waits for it any more.
+ const handed = swarm({ agents: [worker({ lostTask })], groups: [group({ assignment: done({ id: 'a2', agentId: 'other', status: 'done' }) })] })
+ expect(stopIdleWorkers(handed, 'lead', at, new Set())).toHaveLength(1)
+ const cancelled = swarm({ agents: [worker({ lostTask })], groups: [group({ assignment: done({ status: 'cancelled' }) })] })
+ expect(stopIdleWorkers(cancelled, 'lead', at, new Set())).toHaveLength(1)
+ })
+
+ it('keeps a Reviewer while the work it reviews is still open, and stops it once that work is finished', () => {
+ const reviewer = worker({ role: 'reviewer' })
+ const review = group({ id: 'r1', reviewOf: 'g1', assignment: done({ id: 'a2' }) })
+ const open = swarm({ agents: [reviewer], groups: [group({ agentIds: ['L', 'b'], assignment: done({ agentId: 'b', status: 'review' }) }), review] })
+ expect(stopIdleWorkers(open, 'lead', at, new Set())).toEqual([])
+ const finished = swarm({ agents: [reviewer], groups: [group({ agentIds: ['L', 'b'], assignment: done({ agentId: 'b' }) }), review] })
+ expect(stopIdleWorkers(finished, 'lead', at, new Set())).toHaveLength(1)
+ })
+
+ it('does nothing once the owner turned tidying off, or for another project\'s workers', () => {
+ const off = swarm()
+ off.tidy = false
+ expect(stopIdleWorkers(off, 'lead', at, new Set())).toEqual([])
+ expect(stopIdleWorkers(swarm({ agents: [worker({ projectId: 'other' })] }), 'lead', at, new Set())).toEqual([])
+ })
+})
+
+describe('which finished groups archive', () => {
+ const quiet = START + ARCHIVE_QUIET_MS
+ it('is a group whose task is done or cancelled and that has been quiet for 30 minutes', () => {
+ const state = swarm()
+ expect(archivable(state, state.conversations[1]!, quiet)).toBe(true)
+ expect(archivable(state, state.conversations[1]!, quiet - 1)).toBe(false)
+ const cancelled = swarm({ groups: [group({ assignment: done({ status: 'cancelled' }) })] })
+ expect(archivable(cancelled, cancelled.conversations[1]!, quiet)).toBe(true)
+ })
+
+ it('is never a group with work still going, lost or stopped, or no task at all', () => {
+ for (const assignment of [done({ status: 'working' }), done({ status: 'review' }), done({ status: 'lost' }), done({ status: 'stopped' }), null]) {
+ const state = swarm({ groups: [group({ assignment })] })
+ expect(archivable(state, state.conversations[1]!, quiet)).toBe(false)
+ }
+ })
+
+ it('is never a Lead conversation, a private chat, the Leads conversation, an archived group, or any once tidying is off', () => {
+ const state = swarm({ groups: [group({ audience: { people: [] } as never }), group({ id: 'leads', kind: 'leads' }), group({ id: 'old', archived: true })] })
+ for (const g of state.conversations) expect(archivable(state, g, quiet)).toBe(false)
+ const off = swarm()
+ off.tidy = false
+ expect(archivable(off, off.conversations[1]!, quiet)).toBe(false)
+ })
+})
diff --git a/backend/src/superTabs/tidy.ts b/backend/src/superTabs/tidy.ts
new file mode 100644
index 000000000..2954e8955
--- /dev/null
+++ b/backend/src/superTabs/tidy.ts
@@ -0,0 +1,118 @@
+import { agentDisplayName } from './agentNames.js'
+import { activeWork, agentRole, stableId, type Agent, type Conversation, type MessageDraft, type SuperTabState } from './model.js'
+import { agentProjectId, groupProject, projectsOf } from './projects.js'
+
+// Nobody has to tidy a Swarm by hand (roadmap, December). A Builder left with nothing to do for 15 minutes is stopped, as
+// its Lead's agent.release stop would: its host closes the session and frees the machine slot (host.ts). Whatever the
+// owner turns off (tab.tidy), nothing here runs.
+
+/** How long a worker sits without work before it is stopped. */
+export const IDLE_STOP_MS = 15 * 60_000
+/** A machine report older than this does not vouch for a clean folder: the same 2 minutes after which work is lost. */
+const REPORT_FRESH_MS = 2 * 60_000
+
+const FINISHED = ['done', 'cancelled', 'stopped', 'lost']
+const time = (value: string | undefined) => value === undefined ? undefined : Date.parse(value)
+
+/** The groups a worker belongs to or worked in, with those asleep that the caller read for it (`asleep`). */
+const groupsOf = (state: SuperTabState, worker: Agent, asleep: readonly Conversation[]) =>
+ [...state.conversations, ...asleep.filter(g => !state.conversations.some(c => c.id === g.id))]
+ .filter(c => c.agentIds.includes(worker.id) || c.assignment?.agentId === worker.id)
+
+/** When the worker last had anything to do: its start, its Lead's keep, its own progress, or a message in one of its groups. */
+function idleSince(state: SuperTabState, worker: Agent, groups: Conversation[]): number {
+ const seen = [time(worker.startedSession?.createdAt), worker.keptAt, ...groups.flatMap(g => [time(g.lastActivityAt),
+ ...g.assignment?.agentId === worker.id ? [g.assignment.progressAt, g.assignment.lost?.at] : []])]
+ return Math.max(...seen.filter((t): t is number => t !== undefined && Number.isFinite(t)))
+}
+
+/** A Reviewer stays while work it reviews may come back to it for a re-check: the reviewed group's task is not finished. */
+function recheckPending(state: SuperTabState, reviewer: Agent, groups: Conversation[]): boolean {
+ if (agentRole(reviewer) !== 'reviewer') return false
+ return groups.some(g => {
+ const reviewed = g.reviewOf ? state.conversations.find(c => c.id === g.reviewOf) : undefined
+ return !!reviewed?.assignment && !FINISHED.includes(reviewed.assignment.status)
+ })
+}
+
+/** A worker whose task a usage limit took waits to take it back (work.resume) until that task is resumed, handed on or
+ * cancelled, however late the resume comes after the reset (review of #1807). A task not loaded is taken as waiting. */
+function waitingToResume(state: SuperTabState, worker: Agent): boolean {
+ const lost = worker.lostTask
+ if (!lost?.resumeAt) return false
+ const group = state.conversations.find(c => c.id === lost.conversationId)
+ return !group || (group.assignment?.id === lost.assignmentId && group.assignment.status === 'lost')
+}
+
+/** Only a host that said, in a fresh report, that the session runs with nothing uncommitted vouches for stopping it. */
+function reportedClean(state: SuperTabState, worker: Agent, now: number): boolean {
+ const report = state.machines?.find(m => m.machineId === worker.machineId)?.observation
+ return !!report && now - report.receivedAt <= REPORT_FRESH_MS && report.runningHarnessIds.includes(worker.harnessId)
+ && report.harnessUncommitted?.[worker.harnessId] === false
+}
+
+/**
+ * Marks for stopping every worker of the project idle for IDLE_STOP_MS: started by the Swarm (a person's own session is
+ * theirs to close), not a Lead, with no active task, no message waiting for it (`busy`), its host reporting nothing
+ * uncommitted, not waiting to resume after a usage limit, and, for a Reviewer, no re-check pending. Each gets one quiet
+ * line, to nobody, in its most recent group. Run on its Lead's poll, which knows what is waiting. `asleep` are the groups
+ * of its Reviewers that ordinary loads leave out: an archived review group still says whose re-check may come (review of
+ * #1807).
+ */
+export function stopIdleWorkers(state: SuperTabState, projectId: string, now: number, busy: ReadonlySet<string>,
+ asleep: readonly Conversation[] = []): MessageDraft[] {
+ if (state.tidy === false) return []
+ const project = projectsOf(state).find(p => p.id === projectId)
+ const leadId = project && state.conversations.find(c => c.id === project.leadConversationId)?.leadId
+ const lead = leadId ? state.agents.find(a => a.id === leadId) : undefined
+ if (!project || !lead) return []
+ const rows: MessageDraft[] = []
+ for (const worker of state.agents) {
+ if (!worker.startedSession || worker.workDecision === 'stop' || busy.has(worker.id) || agentProjectId(state, worker) !== projectId) continue
+ if (state.conversations.some(c => c.leadId === worker.id || (activeWork(c) && c.assignment!.agentId === worker.id))) continue
+ if (waitingToResume(state, worker)) continue
+ const groups = groupsOf(state, worker, asleep)
+ const since = idleSince(state, worker, groups)
+ if (!(now - since >= IDLE_STOP_MS) || recheckPending(state, worker, groups) || !reportedClean(state, worker, now)) continue
+ worker.idleStop = { previous: worker.workDecision ?? null }
+ worker.workDecision = 'stop'
+ worker.releaseId = stableId('idle-stop', worker.id, String(since))
+ const last = groups.filter(g => !g.archived).sort((a, b) => (time(b.lastActivityAt) ?? 0) - (time(a.lastActivityAt) ?? 0))[0]
+ rows.push({ id: stableId('idle-stop', worker.id, String(since), 'line'), conversationId: last?.id ?? project.leadConversationId, replyTo: null, recipients: [],
+ author: { kind: 'agent', id: lead.id, name: lead.name, displayName: agentDisplayName(state.agents, lead.id), membershipGeneration: lead.membershipGeneration },
+ text: `${worker.displayName ?? worker.name} stopped: no work for 15 minutes.`, source: { kind: 'idle-stop', agentId: worker.id } })
+ }
+ return rows
+}
+
+/** The machines whose reports the stops in `rows` were judged from, which their write touches (as liveness.ts judgedMachines). */
+export function stoppedMachines(state: SuperTabState, rows: MessageDraft[]): Array<{ kind: 'machine'; key: string }> {
+ const stopped = new Set(rows.map(r => r.source?.agentId))
+ return [...new Set(state.agents.filter(a => stopped.has(a.id)).map(a => a.machineId))].map(key => ({ kind: 'machine' as const, key }))
+}
+
+/** How long a finished group stays open after its last message: an archived group refuses posts, and the Lead still talks
+ * to its worker for a while after the task ends (ruling in the plan, 2026-10-27). */
+export const ARCHIVE_QUIET_MS = 30 * 60_000
+
+/** Whether a group may archive by itself, as far as the Swarm alone can tell: its task done or cancelled, quiet for
+ * ARCHIVE_QUIET_MS, and not a Lead conversation, a private chat with people or the Leads conversation. Its pull requests
+ * and decisions are checked by the caller (archive.ts). */
+export function archivable(state: SuperTabState, group: Conversation, now: number): boolean {
+ if (state.tidy === false || group.archived || group.kind || group.audience) return false
+ if (projectsOf(state).some(p => p.leadConversationId === group.id)) return false
+ if (!['done', 'cancelled'].includes(group.assignment?.status ?? '')) return false
+ const last = time(group.lastActivityAt)
+ return last !== undefined && now - last >= ARCHIVE_QUIET_MS
+}
+
+/** The one quiet line an archived group gets, to nobody, written as its project's Lead; none when the project has no Lead. */
+export function archiveLine(state: SuperTabState, group: Conversation, now: number): MessageDraft | null {
+ const leadId = state.conversations.find(c => c.id === groupProject(state, group).leadConversationId)?.leadId
+ const lead = leadId ? state.agents.find(a => a.id === leadId) : undefined
+ if (!lead) return null
+ const prs = group.pullRequestUrls?.length ? ' and its pull requests are merged or closed' : ''
+ return { id: stableId('auto-archive', group.id, String(now)), conversationId: group.id, replyTo: null, recipients: [],
+ author: { kind: 'agent', id: lead.id, name: lead.name, displayName: agentDisplayName(state.agents, lead.id), membershipGeneration: lead.membershipGeneration },
+ text: `Archived: the work is ${group.assignment!.status}${prs}.`, source: { kind: 'auto-archive' } }
+}
diff --git a/backend/src/worker.ts b/backend/src/worker.ts
index 7e5d5aab3..723aaef8b 100644
--- a/backend/src/worker.ts
+++ b/backend/src/worker.ts
@@ -18,6 +18,10 @@ import { ensureProductUsageExpiry } from './lib/productUsage.js'
import { ensureTerminalExpiry } from './superTabs/terminal.js'
import { ensureMentionExpiry } from './superTabs/mentions.js'
import { ensurePartExpiry, startSwarmSweeps } from './superTabs/sweeps.js'
+import { appPullRequests, markFinishedGroups, startSwarmArchive, unknownPullRequests } from './superTabs/archive.js'
+import { SuperTabStore } from './superTabs/store.js'
+import { GitHubApp, githubAppConfig } from './github/app.js'
+import { env } from './config/env.js'
import { machineBillingWorkerService } from './services/MachineBillingWorkerService.js'
import { productUsagePeopleRollupService } from './services/ProductUsagePeopleRollupService.js'
import { logger } from './utils/logger.js'
@@ -36,6 +40,8 @@ async function start(): Promise<void> {
await ensureTerminalExpiry(prisma)
await ensureMentionExpiry(prisma)
await ensurePartExpiry(prisma)
+ // After the push, which adds the finished mark: parts written before it are marked once, so the archive pass finds them.
+ await markFinishedGroups(prisma)
// AFTER the push: it creates the new collections + their unique indexes, and the copy uses $merge
// so those indexes survive. Copying first would leave the unique index build to fail silently.
await migrateMachineRename()
@@ -49,6 +55,7 @@ async function start(): Promise<void> {
await reconcileCommunityLikeCounts()
let stopSweeps = (): void => {}
+ let stopArchive = (): void => {}
const shutdown = (signal: string): void => {
logger.info(`Received ${signal}, stopping backend worker...`)
const hardExit = setTimeout(() => process.exit(0), 5000)
@@ -56,6 +63,7 @@ async function start(): Promise<void> {
machineBillingWorkerService.stop()
productUsagePeopleRollupService.stop()
stopSweeps()
+ stopArchive()
void Promise.allSettled([prisma.$disconnect(), closeBus()]).finally(() => process.exit(0))
}
process.on('SIGINT', () => shutdown('SIGINT'))
@@ -64,6 +72,10 @@ async function start(): Promise<void> {
machineBillingWorkerService.start()
productUsagePeopleRollupService.start()
stopSweeps = startSwarmSweeps(prisma)
+ // Finished groups archive once GitHub says their pull requests are merged or closed; without the app, only groups that
+ // link none do (superTabs/archive.ts).
+ const githubConfig = githubAppConfig(env), githubApp = githubConfig ? new GitHubApp(githubConfig) : null
+ stopArchive = startSwarmArchive(prisma, new SuperTabStore(prisma), () => githubApp ? appPullRequests(githubApp) : unknownPullRequests)
// PM2 wait_ready gates the singleton worker's "online" state on schema/catalog/backfill startup.
// Plain node/tsx runs do not provide process.send and simply continue.
process.send?.('ready')
diff --git a/backend/vitest.super-tabs.config.ts b/backend/vitest.super-tabs.config.ts
index ccf87c4f3..1cbcecf4e 100644
--- a/backend/vitest.super-tabs.config.ts
+++ b/backend/vitest.super-tabs.config.ts
@@ -1,5 +1,5 @@
import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { include: ['integration/superTabs.test.ts', 'integration/superTabSharing.test.ts', 'integration/superTabGithub.test.ts', 'integration/superTabTeam.test.ts',
- 'integration/superTabRead.test.ts', 'integration/superTabLeaderboard.test.ts', 'integration/superTabMigration.test.ts', 'integration/superTabLiveness.test.ts'], hookTimeout: 120000, testTimeout: 30000,
+ 'integration/superTabRead.test.ts', 'integration/superTabLeaderboard.test.ts', 'integration/superTabMigration.test.ts', 'integration/superTabLiveness.test.ts', 'integration/superTabTidy.test.ts'], hookTimeout: 120000, testTimeout: 30000,
fileParallelism: false, env: { NODE_ENV: 'test', HARNESS_CREDENTIAL_ENCRYPTION_KEY: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' } } })
diff --git a/cli/src/lib/worktreeSweep.ts b/cli/src/lib/worktreeSweep.ts
index 8f9270b4b..b0974d056 100644
--- a/cli/src/lib/worktreeSweep.ts
+++ b/cli/src/lib/worktreeSweep.ts
@@ -67,7 +67,9 @@ export async function sweepWorktrees(input: {
return removed
}
-async function sweepOne(path: string, now: number, idleMs: number): Promise<boolean> {
+/** Removes one worktree under the rule above: true when it went. The Swarm's host calls it with no idle wait for a worker
+ * it just stopped (superTabs/machines.ts `removeStoppedWorktree`). */
+export async function sweepOne(path: string, now: number, idleMs: number): Promise<boolean> {
const gitDir = resolve(path, await git(path, ['rev-parse', '--git-dir']))
const common = resolve(path, await git(path, ['rev-parse', '--git-common-dir']))
if (gitDir === common || basename(common) !== '.git') return false
diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.ts
index 9809b4dee..eff5b7b76 100644
--- a/cli/src/superTabs/host.spec.ts
+++ b/cli/src/superTabs/host.spec.ts
@@ -13,6 +13,7 @@ import { HostFeed } from './hostFeed.js'
import { SwarmReads } from './swarmReads.js'
import { retainedHarnesses, retentionFile } from './retention.js'
import { observerSource } from './observers.js'
+import { ContributedMachines } from './machines.js'
const roots: string[] = []
const hosts: SuperTabHost[] = []
@@ -997,6 +998,140 @@ it('stops a requested worker once, confirms removal, and releases retention on t
expect(acknowledgements).toBe(1)
})
+// Review of #1807: the clean report the idle check trusted can be a minute old. An edit since, or a folder git cannot read,
+// withdraws the idle stop instead of closing the session; a stop its Lead asked for closes as before.
+it.each([['changed', { ok: true, stdout: ' M src/a.ts\n', stderr: '' }], ['unreadable', { ok: false, stdout: '', stderr: 'fatal' }]] as const)(
+ 'withdraws an idle stop whose folder is %s when it would close it', async (_kind, status) => {
+ const git = vi.fn(async () => status)
+ const t = setup(), host = t.open({ machines: { git } })
+ vi.mocked(t.core.agents.byAgent).mockReturnValue({ agentId: 'harness', sessionId: 'native', registeredAt: 0, startedBy: 'agent', cwd: '/work/harness' } as never)
+ const target = { id: 'agent', harnessId: 'harness', machineId: 'machine-1', workDecision: 'stop', releaseId: 'idle-1', idleStop: { previous: 'awaiting' },
+ startedSession: { creationId: 'super-original-creation', sessionId: 'native', createdAt: new Date(0).toISOString() } }
+ const close = vi.fn(async () => ({ closed: true as const }))
+ t.core.agents.closeSwarm = close
+ const commands: unknown[] = []
+ let withdrawn = false
+ t.core.account.backend = async (method, path, body) => {
+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm(withdrawn ? [] : [{ tabId: 'tab', agent: target, stopRequested: true }], { tabs: ['tab'] }) } }
+ if (method === 'GET') return { status: 200, body: { data: swarmReply(path, { agents: [target], conversations: [] }) } }
+ commands.push((body as any)?.command)
+ if ((body as any)?.command?.type === 'agent.stopLease') return { status: 200, body: { data: { result: { expiresAt: Date.now() + 120_000, durationMs: 120_000 } } } }
+ if ((body as any)?.command?.type === 'agent.stopRefused') withdrawn = true
+ return { status: 200, body: { data: {} } }
+ }
+ await host.tick()
+ await vi.waitFor(() => expect(withdrawn).toBe(true))
+ expect(git).toHaveBeenCalledWith('/work/harness', ['status', '--porcelain'])
+ expect(commands).toEqual([{ type: 'agent.stopLease', agentId: 'agent', releaseId: 'idle-1' }, { type: 'agent.stopRefused', agentId: 'agent', releaseId: 'idle-1' }])
+ expect(close).not.toHaveBeenCalled()
+})
+
+it('retries a withdrawal the backend refused, reading the folder again after its backoff, and never closes meanwhile', async () => {
+ const git = vi.fn(async () => ({ ok: true, stdout: ' M src/a.ts\n', stderr: '' }))
+ const t = setup(), host = t.open({ machines: { git } })
+ vi.mocked(t.core.agents.byAgent).mockReturnValue({ agentId: 'harness', sessionId: 'native', registeredAt: 0, startedBy: 'agent', cwd: '/work/harness' } as never)
+ const target = { id: 'agent', harnessId: 'harness', machineId: 'machine-1', workDecision: 'stop', releaseId: 'idle-1', idleStop: { previous: 'awaiting' },
+ startedSession: { creationId: 'super-original-creation', sessionId: 'native', createdAt: new Date(0).toISOString() } }
+ const close = vi.fn(async () => ({ closed: true as const }))
+ t.core.agents.closeSwarm = close
+ let attempts = 0, withdrawn = false
+ t.core.account.backend = async (method, path, body) => {
+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm(withdrawn ? [] : [{ tabId: 'tab', agent: target, stopRequested: true }], { tabs: ['tab'] }) } }
+ if (method === 'GET') return { status: 200, body: { data: swarmReply(path, { agents: [target], conversations: [] }) } }
+ if ((body as any)?.command?.type === 'agent.stopLease') return { status: 200, body: { data: { result: { expiresAt: Date.now() + 120_000, durationMs: 120_000 } } } }
+ if ((body as any)?.command?.type === 'agent.stopRefused' && ++attempts === 1) return { status: 503, body: { error: 'SWARM_BUSY', message: 'Busy' } }
+ if ((body as any)?.command?.type === 'agent.stopRefused') withdrawn = true
+ return { status: 200, body: { data: {} } }
+ }
+ await host.tick()
+ await vi.waitFor(() => expect(attempts).toBe(1))
+ await vi.waitFor(() => expect(t.log.mock.calls.flat().join('\n')).toContain('Busy'))
+ // Within the first 5-second backoff nothing is tried again.
+ t.wait(4_000); await host.tick()
+ await new Promise(resolve => setTimeout(resolve, 20))
+ expect(attempts).toBe(1)
+ t.wait(2_000); await host.tick()
+ await vi.waitFor(() => expect(withdrawn).toBe(true))
+ expect(attempts).toBe(2)
+ expect(git).toHaveBeenCalledTimes(2)
+ expect(close).not.toHaveBeenCalled()
+})
+
+// Review of #1807: the lease answer can take up to its two minutes, so the folder is read after it, right before the close.
+it('withdraws an idle stop whose folder changed while the close lease was being granted', async () => {
+ let status = { ok: true, stdout: '', stderr: '' }
+ const git = vi.fn(async () => status)
+ const t = setup(), host = t.open({ machines: { git } })
+ vi.mocked(t.core.agents.byAgent).mockReturnValue({ agentId: 'harness', sessionId: 'native', registeredAt: 0, startedBy: 'agent', cwd: '/work/harness' } as never)
+ const target = { id: 'agent', harnessId: 'harness', machineId: 'machine-1', workDecision: 'stop', releaseId: 'idle-1', idleStop: { previous: 'awaiting' },
+ startedSession: { creationId: 'super-original-creation', sessionId: 'native', createdAt: new Date(0).toISOString() } }
+ const close = vi.fn(async () => ({ closed: true as const }))
+ t.core.agents.closeSwarm = close
+ let grant = () => {}, asked = false, withdrawn = false
+ t.core.account.backend = async (method, path, body) => {
+ if ((body as any)?.command?.type === 'agent.stopLease') {
+ asked = true
+ await new Promise<void>(resolve => { grant = resolve })
+ return { status: 200, body: { data: { result: { expiresAt: Date.now() + 120_000, durationMs: 120_000 } } } }
+ }
+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm(withdrawn ? [] : [{ tabId: 'tab', agent: target, stopRequested: true }], { tabs: ['tab'] }) } }
+ if (method === 'GET') return { status: 200, body: { data: swarmReply(path, { agents: [target], conversations: [] }) } }
+ if ((body as any)?.command?.type === 'agent.stopRefused') withdrawn = true
+ return { status: 200, body: { data: {} } }
+ }
+ await host.tick()
+ await vi.waitFor(() => expect(asked).toBe(true))
+ status = { ok: true, stdout: ' M src/a.ts\n', stderr: '' }
+ grant()
+ await vi.waitFor(() => expect(withdrawn).toBe(true))
+ expect(close).not.toHaveBeenCalled()
+})
+
+it('closes an idle stop whose folder is still clean', async () => {
+ const git = vi.fn(async () => ({ ok: true, stdout: '', stderr: '' }))
+ const t = setup(), host = t.open({ machines: { git } })
+ vi.mocked(t.core.agents.byAgent).mockReturnValue({ agentId: 'harness', sessionId: 'native', registeredAt: 0, startedBy: 'agent', cwd: '/work/harness' } as never)
+ const target = { id: 'agent', harnessId: 'harness', machineId: 'machine-1', workDecision: 'stop', releaseId: 'idle-1', idleStop: { previous: null },
+ startedSession: { creationId: 'super-original-creation', sessionId: 'native', createdAt: new Date(0).toISOString() } }
+ let removed = false
+ t.core.agents.closeSwarm = async () => ({ closed: true })
+ t.core.account.backend = async (method, path, body) => {
+ if ((body as any)?.command?.type === 'agent.stopLease') return { status: 200, body: { data: { result: { expiresAt: Date.now() + 3_600_000, durationMs: 120_000 } } } }
+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm(removed ? [] : [{ tabId: 'tab', agent: target, stopRequested: true }], { tabs: ['tab'] }) } }
+ if (method === 'GET') return { status: 200, body: { data: swarmReply(path, { agents: [target], conversations: [] }) } }
+ if ((body as any)?.command?.type === 'agent.remove') removed = true
+ return { status: 200, body: { data: {} } }
+ }
+ await host.tick()
+ await vi.waitFor(() => expect(removed).toBe(true))
+ expect(git).toHaveBeenCalledOnce()
+})
+
+it('removes a stopped worker\'s worktree only once its removal is acknowledged, and a failed removal stays in the log', async () => {
+ const t = setup(), host = t.open()
+ const removeWorktree = vi.spyOn(ContributedMachines.prototype, 'removeStoppedWorktree').mockRejectedValue(new Error('git refused'))
+ vi.mocked(t.core.agents.byAgent).mockReturnValue({ agentId: 'harness', sessionId: 'native', registeredAt: 0, startedBy: 'agent' } as never)
+ let removed = false
+ const target = { id: 'agent', harnessId: 'harness', machineId: 'machine-1', workDecision: 'stop', startedSession: { creationId: 'super-original-creation', sessionId: 'native', createdAt: new Date(0).toISOString() } }
+ t.core.agents.closeSwarm = async () => {
+ expect(removeWorktree).not.toHaveBeenCalled()
+ return { closed: true }
+ }
+ t.core.account.backend = async (method, path, body) => {
+ if ((body as any)?.command?.type === 'agent.stopLease') return { status: 200, body: { data: { result: { expiresAt: Date.now() + 3_600_000, durationMs: 120_000 } } } }
+ if (path.includes('/hosts/')) return { status: 200, body: { data: hostForm(removed ? [] : [{ tabId: 'tab', agent: target, stopRequested: true }], { tabs: ['tab'] }) } }
+ if (method === 'GET') return { status: 200, body: { data: swarmReply(path, { agents: [target], conversations: [] }) } }
+ expect(removeWorktree).not.toHaveBeenCalled()
+ removed = true
+ return { status: 200, body: { data: {} } }
+ }
+ try {
+ await host.tick()
+ await vi.waitFor(() => expect(removeWorktree).toHaveBeenCalledWith('tab', 'harness'))
+ await vi.waitFor(() => expect(t.log.mock.calls.flat().join('\n')).toContain('git refused'))
+ } finally { removeWorktree.mockRestore() }
+})
+
// A lost task (the backend's v1 liveness) has ended for its agent, as a cancelled one has: a stalled agent the Lead stops
// is closed, never kept for work it no longer holds.
it.each(['cancelled', 'lost'])('closes the session of a worker whose assignment is %s', async status => {
diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.ts
index 401e3df0a..e22ee3033 100644
--- a/cli/src/superTabs/host.ts
+++ b/cli/src/superTabs/host.ts
@@ -1,5 +1,5 @@
import { OBSERVER_VALID_MS, publishObservers } from './observers.js'
-import { ContributedMachines, type MachineDeps } from './machines.js'
+import { ContributedMachines, uncommittedIn, type MachineDeps } from './machines.js'
import { SwarmGrids } from './swarmGrids.js'
import { retainContributions } from './retention.js'
import { configurationObservation } from './configuration.js'
@@ -478,6 +478,16 @@ export class SuperTabHost {
command: { type: 'agent.stopLease', agentId: agent.id, releaseId: agent.releaseId },
})).result)
if (typeof leased.durationMs !== 'number' || !Number.isFinite(leased.durationMs) || leased.durationMs <= 0 || leased.durationMs > 120_000) throw new Error('The host could not reserve this native close. Remove a stuck contribution or update its backend.')
+ // The idle check's stop trusted a report up to a minute old (machines.ts): an edit since, or a folder git cannot
+ // read now, withdraws it instead (review of #1807). Read after the lease, whose answer can take minutes, so it
+ // is the last thing before the close. A stop its Lead asked for closes as before.
+ if (member.idleStop && (!native.cwd || await uncommittedIn(native.cwd, this.machineDeps.git) !== false)) {
+ // A failed withdrawal retries with backoff, reading the folder again; the unused lease simply expires.
+ await backend(this.core, 'POST', `/api/super-tabs/${tabId}/commands`, { operationId: `idle-stop-withdrawn-${agent.releaseId ?? agent.id}`,
+ asAgentId: agent.id, command: { type: 'agent.stopRefused', agentId: agent.id, releaseId: agent.releaseId } })
+ attempt.retryAt = Infinity
+ return
+ }
result = await this.core.agents.closeSwarm({ agentId: agent.harnessId, expiresAt: leaseRequestedAt + leased.durationMs,
creationId: identity.creationId, sessionId: identity.sessionId, createdAt: identity.createdAt })
}
@@ -492,6 +502,9 @@ export class SuperTabHost {
operationId: `release-${agent.releaseId ?? agent.id}`, asAgentId: agent.id, command: { type: 'agent.remove', agentId: agent.id, releaseId: agent.releaseId },
})
attempt.retryAt = Infinity
+ // Its worktree goes now that it is stopped for good, not after the weekly sweep's idle week (machines.ts).
+ await this.contributed().removeStoppedWorktree(tabId, agent.harnessId)
+ .catch(error => this.log(`Kept the worktree of a stopped worker: ${error instanceof Error ? error.message : String(error)}`))
} catch (error) {
attempt.failures++
// Five attempts total; permanent ownership/identity refusals never acquire another lease for this runtime.
diff --git a/cli/src/superTabs/machines.spec.ts b/cli/src/superTabs/machines.spec.ts
index 2cc95cd57..6deb58fba 100644
--- a/cli/src/superTabs/machines.spec.ts
+++ b/cli/src/superTabs/machines.spec.ts
@@ -459,6 +459,52 @@ describe('contributed machine executor', () => {
expect(f.backend.mock.calls.filter(c => c[1] === 'POST').at(-1)![3]).not.toHaveProperty('harnessProgress')
})
+ it('says whether each running session\'s folder has uncommitted changes, leaving out any git could not read', async () => {
+ const f = fixture()
+ const folders: Record<string, string> = { running: '/work/running', clean: '/work/clean', broken: '/work/broken' }
+ vi.mocked(f.core.agents.byAgent).mockImplementation(id => folders[id] ? { agentId: id, cwd: folders[id] } as never : undefined)
+ f.pool.harnessIds = ['running', 'clean', 'broken', 'stopped']
+ const git = vi.fn(async (cwd: string, args: string[]) => cwd === '/work/broken' ? { ok: false, stdout: '', stderr: 'fatal' }
+ : { ok: args.join(' ') === 'status --porcelain', stdout: cwd === '/work/running' ? ' M src/a.ts\n' : '', stderr: '' })
+ const machine = new ContributedMachines(f.core, 'host', { ...f.deps, git } as never)
+ await machine.tick()
+ const body = f.backend.mock.calls.find(c => c[1] === 'POST')![3] as Record<string, unknown>
+ expect(body.harnessUncommitted).toEqual({ running: true, clean: false })
+ expect(git.mock.calls.map(c => c[0]).sort()).toEqual(['/work/broken', '/work/clean', '/work/running'])
+ })
+
+ it('reads each session\'s folder at most once a minute', async () => {
+ const f = fixture()
+ vi.mocked(f.core.agents.byAgent).mockImplementation(id => id === 'running' ? { agentId: id, cwd: '/work/running' } as never : undefined)
+ const git = vi.fn(async () => ({ ok: true, stdout: '', stderr: '' }))
+ const machine = new ContributedMachines(f.core, 'host', { ...f.deps, git } as never)
+ await machine.tick()
+ f.advance(); await machine.tick()
+ expect(git).toHaveBeenCalledTimes(1)
+ f.step(60_000); await machine.tick()
+ expect(git).toHaveBeenCalledTimes(2)
+ })
+
+ it('drops uncommitted changes alone for a backend that refuses them, and offers them again ten minutes later', async () => {
+ const f = fixture()
+ vi.mocked(f.core.agents.byAgent).mockImplementation(id => id === 'running' ? { agentId: id, cwd: '/work/running' } as never : undefined)
+ const original = f.backend.getMockImplementation()!
+ f.backend.mockImplementation(async (core, method, path, body) => {
+ if (method === 'POST' && (body as Record<string, unknown>)?.harnessUncommitted) throw new SuperTabHostError('VALIDATION_ERROR', 'Unrecognized key: harnessUncommitted', 400)
+ return original(core, method, path, body)
+ })
+ const git = vi.fn(async () => ({ ok: true, stdout: '', stderr: '' }))
+ const machine = new ContributedMachines(f.core, 'host', { ...f.deps, git, progress: () => ({ running: 900 }) } as never)
+ const posts = () => f.backend.mock.calls.filter(c => c[1] === 'POST' && String(c[2]).includes('/machines/')).map(c => c[3] as Record<string, unknown>)
+ const fields = (post: Record<string, unknown>) => ['harnessUncommitted', 'harnessProgress'].filter(key => key in post)
+ await machine.tick()
+ expect(posts().map(fields)).toEqual([['harnessUncommitted', 'harnessProgress'], ['harnessProgress']])
+ f.advance(); await machine.tick()
+ expect(posts().map(fields).at(-1)).toEqual(['harnessProgress'])
+ f.step(600_000); await machine.tick()
+ expect(posts().map(fields).slice(-2)).toEqual([['harnessUncommitted', 'harnessProgress'], ['harnessProgress']])
+ })
+
it('drops progress for a backend that refuses it, and offers it again ten minutes later', async () => {
const f = fixture()
const original = f.backend.getMockImplementation()!
@@ -1088,6 +1134,43 @@ describe('removed machine cleanup', () => {
setLive: (sessions: RegisteredSession[]) => { live = sessions }, step: (ms: number) => { now += ms } }
}
+ it('removes a stopped worker\'s worktree once nothing runs there and nothing is uncommitted, and its branch once merged', async () => {
+ const m = machine()
+ const host = m.open()
+ const recorded = () => JSON.parse(readFileSync(swarmWorktreesFile(m.data, 'host'), 'utf8')).worktrees.map((w: { startId: string }) => w.startId)
+ // Its session still runs there: kept.
+ await host.removeStoppedWorktree('tab', 'h-recorded')
+ expect(existsSync(m.recorded)).toBe(true)
+ m.setLive([])
+ // A file not committed: kept, with its work.
+ await host.removeStoppedWorktree('tab', 'h-recorded')
+ expect(readFileSync(join(m.recorded, 'unpushed.txt'), 'utf8')).toBe('work')
+ rmSync(join(m.recorded, 'unpushed.txt'))
+ git(m.clone, 'config', 'branch.super-tab/recorded.harness', 'placeholder')
+ await host.removeStoppedWorktree('tab', 'h-recorded')
+ expect(existsSync(m.recorded)).toBe(false)
+ expect(git(m.clone, 'worktree', 'list', '--porcelain')).not.toContain('/recorded\n')
+ // Its branch had no commit of its own, so it went too.
+ expect(git(m.clone, 'branch', '--list', 'super-tab/recorded')).toBe('')
+ expect(recorded()).toEqual(['kept'])
+ })
+
+ it('keeps a stopped worker\'s branch with a commit only it has, and leaves alone a worktree it has no record of', async () => {
+ const m = machine()
+ m.setLive([])
+ rmSync(join(m.recorded, 'unpushed.txt'))
+ git(m.recorded, 'commit', '-q', '--allow-empty', '-m', 'only here')
+ git(m.clone, 'config', 'branch.super-tab/recorded.harness', 'placeholder')
+ const host = m.open()
+ await host.removeStoppedWorktree('tab', 'h-recorded')
+ expect(existsSync(m.recorded)).toBe(false)
+ expect(git(m.clone, 'log', '-1', '--format=%s', 'super-tab/recorded').trim()).toBe('only here')
+ rmSync(join(m.earlier, 'unpushed.txt'))
+ await host.removeStoppedWorktree('tab', 'h-earlier')
+ await host.removeStoppedWorktree('other-tab', 'h-recorded')
+ expect(existsSync(m.earlier)).toBe(true)
+ })
+
it('deletes only the tab\'s Swarm folders and Swarm-made worktrees, then acknowledges once', async () => {
const m = machine()
const host = m.open()
diff --git a/cli/src/superTabs/machines.ts b/cli/src/superTabs/machines.ts
index 6901aa729..84926d04e 100644
--- a/cli/src/superTabs/machines.ts
+++ b/cli/src/superTabs/machines.ts
@@ -14,7 +14,7 @@ import { startAgent, type ScopedRequest } from './start.js'
import { prepareSwarmStart } from './projectFolder.js'
import { readAuthSession } from '../lib/authSession.js'
import { createSwarmCloneTrustRepair, swarmCloneRoots } from './cloneTrust.js'
-import { git } from '../lib/worktreeSweep.js'
+import { git, sweepOne } from '../lib/worktreeSweep.js'
import { projectsRoot } from '../lib/projectFolder.js'
import { worktreeFolderName } from '../lib/agentNames.js'
import { teamPrivacyObserver } from '../team/observer.js'
@@ -33,6 +33,9 @@ const VERIFIED_TOOL_TTL_MS = 10 * 60_000
* is heard from within this long. */
const FIELD_REFUSED_MS = 10 * 60_000
const UNVERIFIED_TOOL_TTL_MS = 60_000
+/** How long a session's folder stands as clean or not before git is asked again: a minute bounds the work to one
+ * `git status` per running session a minute, and the backend stops an idle worker only on a report under 2 minutes old. */
+const UNCOMMITTED_TTL_MS = 60_000
/** How long this machine refuses a start before failing it with its reason, so the Lead starts it elsewhere: a minute of
* busy CPU or memory may pass, and routing saw this machine able a moment ago. A refusal no one reported left starts
* "Queued" for hours (DESKTOP-0TFH0OJ, 2026-10-23). */
@@ -141,6 +144,9 @@ export class ContributedMachines {
private privacyRefusedUntil = 0
/** Until when the reading leaves out its progress, which the backend refused. */
private progressRefusedUntil = 0
+ private uncommittedRefusedUntil = 0
+ /** Per running session, whether its folder had uncommitted changes when last read, and until when that stands. */
+ private readonly uncommittedCache = new Map<string, { cwd: string; dirty: boolean; until: number }>()
/** Until when the reading leaves out its readiness field, which the backend refused. */
private readinessRefusedUntil = 0
/** Whether each engine is installed and signed in, and until when that stands: one probe starts login shells and reads
@@ -325,7 +331,9 @@ export class ContributedMachines {
const readiness = { ...(readyEngines ? { engines: readyEngines } : {}), ...(checkouts ? { checkouts } : {}) }
const shown = began >= this.progressRefusedUntil ? this.deps.progress?.(running) ?? {} : {}
const progress = Object.fromEntries(running.flatMap(id => typeof shown[id] === 'number' ? [[id, shown[id]]] : []))
+ const uncommitted = began >= this.uncommittedRefusedUntil ? await this.uncommitted(running, began) : {}
const observation = { generation: pool.generation, tools: reportedTools,
+ ...(Object.keys(uncommitted).length ? { harnessUncommitted: uncommitted } : {}),
...(Object.keys(progress).length ? { harnessProgress: progress } : {}), ...(localModels ? { localModels } : {}),
...((readyEngines || checkouts) && began >= this.readinessRefusedUntil ? { readiness } : {}),
...(privacy && began >= this.privacyRefusedUntil ? { privacy } : {}),
@@ -349,14 +357,15 @@ export class ContributedMachines {
// Older backends reject the additive fields. The newest go alone first, readiness, progress, then privacy: a backend
// that takes everything else keeps the local models it reads. Their boolean-only view still safely refuses an
// unverified tool, and a reading without privacy is never one a Team machine passes on.
- const { readiness: _readiness, ...ready } = observation
+ const { harnessUncommitted: _uncommitted, ...known } = observation
+ const { readiness: _readiness, ...ready } = known
const { harnessProgress: _progress, ...withoutProgress } = ready
const { privacy: _privacy, ...withoutPrivacy } = withoutProgress
const { toolProbeErrors: _probeErrors, localModels: _served, refusedModels: _refused, ...legacy } = withoutPrivacy
// A backend before `starting` refuses it: it gets the models the grid lists, as before, not none at all.
const listedOnly = localModels?.some(m => m.starting)
? [{ ...withoutPrivacy, localModels: localModels.filter(m => !m.starting) }] : []
- const attempts = [...('readiness' in observation ? [observation] : []), ready, ...('harnessProgress' in ready ? [withoutProgress] : []),
+ const attempts = [...('harnessUncommitted' in observation ? [observation] : []), ...('readiness' in known ? [known] : []), ready, ...('harnessProgress' in ready ? [withoutProgress] : []),
...('privacy' in withoutProgress ? [withoutPrivacy] : []), ...listedOnly,
...('toolProbeErrors' in observation || 'localModels' in observation || 'refusedModels' in observation ? [legacy] : [])]
for (const [index, attempt] of attempts.entries()) {
@@ -365,7 +374,8 @@ export class ContributedMachines {
break
} catch (error) {
if (!refused(error) || index === attempts.length - 1) throw error
- if ('readiness' in attempt) this.readinessRefusedUntil = began + FIELD_REFUSED_MS
+ if ('harnessUncommitted' in attempt) this.uncommittedRefusedUntil = began + FIELD_REFUSED_MS
+ else if ('readiness' in attempt) this.readinessRefusedUntil = began + FIELD_REFUSED_MS
else if ('harnessProgress' in attempt) this.progressRefusedUntil = began + FIELD_REFUSED_MS
else if ('privacy' in attempt) this.privacyRefusedUntil = began + FIELD_REFUSED_MS
}
@@ -437,6 +447,41 @@ export class ContributedMachines {
}
} finally { local?.close() }
}
+ /** Whether each running session's folder has uncommitted changes (git status), for the sessions git could read: the
+ * backend stops a worker idle for 15 minutes only when its host says it is clean (backend superTabs/tidy.ts). */
+ private async uncommitted(running: readonly string[], now: number): Promise<Record<string, boolean>> {
+ const read: Record<string, boolean> = {}
+ for (const id of running) {
+ const cwd = this.core.agents.byAgent(id)?.cwd
+ if (!cwd) continue
+ let known = this.uncommittedCache.get(id)
+ if (!known || known.cwd !== cwd || known.until <= now) {
+ const dirty = await uncommittedIn(cwd, this.deps.git)
+ known = dirty === null ? undefined : { cwd, dirty, until: now + UNCOMMITTED_TTL_MS }
+ if (known) this.uncommittedCache.set(id, known)
+ else this.uncommittedCache.delete(id)
+ }
+ if (known) read[id] = known.dirty
+ }
+ // Sessions of every tab share it, so only what expired goes: a session that left is never read again.
+ for (const [id, entry] of this.uncommittedCache) if (entry.until <= now) this.uncommittedCache.delete(id)
+ return read
+ }
+
+ /** Once its host confirmed a worker stopped (host.ts releaseWorker), the worktree its start made goes at once instead of
+ * after the weekly sweep's idle week, by that sweep's own rule (lib/worktreeSweep.ts): only a worktree this machine's
+ * record proves the Swarm made, with no session in it and nothing uncommitted. Its branch keeps every commit and goes
+ * only when they are all on other branches or the remote, as once its pull request merged. Anything else stays. */
+ async removeStoppedWorktree(tabId: string, harnessId: string): Promise<void> {
+ const file = swarmWorktreesFile(this.core.dataDir, this.machineId)
+ const record = readWorktrees(file).find(w => w.tabId === tabId && w.harnessId === harnessId)
+ if (!record || !await swarmWorktree(record.path, record.source, record.startId)) return
+ if (this.core.agents.live().some(a => !!a.cwd && within(record.path, a.cwd))) return
+ // File times are wall-clock, so the sweep's idle check reads the real clock; no idle wait is asked.
+ if (!await sweepOne(record.path, Date.now(), 0).catch(() => false)) return
+ writeWorktrees(file, readWorktrees(file).filter(w => !(w.tabId === tabId && w.harnessId === harnessId)))
+ }
+
/** A removal deletes only what is provably the Swarm's: the record says which worktree each start made. */
private recordWorktree(tabId: string, startId: string, harnessId: string, request: Record<string, unknown>) {
const path = this.core.agents.byAgent(harnessId)?.cwd
@@ -558,6 +603,12 @@ export function createQuietGit(timeoutMs = 15_000): GitRun {
}
const quietGit = createQuietGit()
+/** Whether a session's folder has uncommitted changes (git status), or null when git could not say. */
+export async function uncommittedIn(cwd: string, run: GitRun = quietGit): Promise<boolean | null> {
+ const status = await run(cwd, ['status', '--porcelain'])
+ return status.ok ? status.stdout.trim() !== '' : null
+}
+
/** What git or the remote says when this login may not push: refused, signed out, or a credential it could not ask for.
* Anything else (a host it could not reach, a timeout) says nothing about access. */
const NO_PUSH = /permission|denied|returned error: 40[13]|could not read (username|password)|terminal prompts disabled|authentication failed|invalid username or password|repository not found/i
diff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.ts
index 7af78539f..1a2998b7c 100644
--- a/cli/src/superTabs/service.spec.ts
+++ b/cli/src/superTabs/service.spec.ts
@@ -203,6 +203,12 @@ it('tells the Lead how to switch a project\'s skills on its owner\'s own request
askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } })
expect(answer.help.command).toContain('project.skills switches a project between the Default, Harness orchestration and Custom skills (Custom once its owner has made the project\'s roles): only its project owner does, or its Lead passing on that owner\'s own chat message, with askedIn naming it.')
})
+it('tells the Lead how to turn the Swarm\'s tidying off or on at its owner\'s own request', async () => {
+ const t = setup()
+ const answer = await t.ask({ action: 'help' }, owner) as { help: { command: string; commands: Array<Record<string, unknown>> } }
+ expect(answer.help.commands).toContainEqual({ type: 'tab.tidy', enabled: false, askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } })
+ expect(answer.help.command).toContain('tab.tidy turns off, or back on, the Swarm\'s tidying: workers idle for 15 minutes stop and finished groups archive once their pull requests are merged or closed. Only the Swarm owner does, or a Lead passing on the owner\'s own chat message, with askedIn naming it.')
+})
it('tells the Lead that start works only on a machine in the Swarm\'s Machines list', async () => {
const t = setup()
const answer = await t.ask({ action: 'help' }, owner) as { help: { start: string } }
diff --git a/cli/src/superTabs/service.ts b/cli/src/superTabs/service.ts
index 237f8311a..e3db371a9 100644
--- a/cli/src/superTabs/service.ts
+++ b/cli/src/superTabs/service.ts
@@ -49,13 +49,14 @@ const HELP = {
capacity: 'capacity MACHINE_ID JSON: inspect machine, engine and quota headroom. JSON uses the start request fields below. Unknown allowances are not reported as free tokens.',
startRequest: { conversationId: 'GROUP', machineId: 'MACHINE', engine: 'codex', name: 'Builder', cwd: '/absolute/repo/on/that/machine', worktree: true, branchRef: 'refs/remotes/origin/BASE_BRANCH', requirements: START_REQUIREMENTS,
model: 'opus', effort: 'high', routeDecisionId: 'DECISION' },
- command: 'command OPERATION_ID JSON: send one of the commands below. Reuse exactly the same ID and JSON after an interrupted request. On Custom skills, work.assign takes "roleId" too, a role of the agent\'s kind. When your assignment needs a person to decide, set work.status needs_human; when you cannot go on, blocked. Set working again once it moves. rule.set and rule.remove change one project\'s routing rules: only the project owner does (naming projectId), or that project\'s Lead passing on the project owner\'s request, with askedIn naming the project owner\'s message in that project\'s chat. project.skills switches a project between the Default, Harness orchestration and Custom skills (Custom once its owner has made the project\'s roles): only its project owner does, or its Lead passing on that owner\'s own chat message, with askedIn naming it. A start, assignment or route that breaks a hard rule (forbidModel, machines, minEffort) is refused for agents; preferEngine and preferIdle only rank.',
+ command: 'command OPERATION_ID JSON: send one of the commands below. Reuse exactly the same ID and JSON after an interrupted request. On Custom skills, work.assign takes "roleId" too, a role of the agent\'s kind. When your assignment needs a person to decide, set work.status needs_human; when you cannot go on, blocked. Set working again once it moves. rule.set and rule.remove change one project\'s routing rules: only the project owner does (naming projectId), or that project\'s Lead passing on the project owner\'s request, with askedIn naming the project owner\'s message in that project\'s chat. project.skills switches a project between the Default, Harness orchestration and Custom skills (Custom once its owner has made the project\'s roles): only its project owner does, or its Lead passing on that owner\'s own chat message, with askedIn naming it. tab.tidy turns off, or back on, the Swarm\'s tidying: workers idle for 15 minutes stop and finished groups archive once their pull requests are merged or closed. Only the Swarm owner does, or a Lead passing on the owner\'s own chat message, with askedIn naming it. A start, assignment or route that breaks a hard rule (forbidModel, machines, minEffort) is refused for agents; preferEngine and preferIdle only rank.',
commands: [
{ type: 'project.report', projectId: 'PROJECT', through: { GROUP: 214031 }, text: 'What changed, what is blocked, and what comes next. Use null when nothing merits repeating.' },
{ type: 'project.repository', projectId: 'PROJECT', repositoryUrl: 'https://github.com/OWNER/REPOSITORY' },
{ type: 'project.skills', projectId: 'PROJECT', mode: 'default|orchestration|custom', askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },
// The morning digest, at a person's local time; time null turns it off.
{ type: 'project.digest', projectId: 'PROJECT', time: '08:00', timeZone: 'Asia/Ho_Chi_Minh' },
+ { type: 'tab.tidy', enabled: false, askedIn: { conversationId: 'GROUP', messageId: 'OWNER_MESSAGE' } },
{ type: 'message.send', conversationId: 'GROUP', text: 'A message addressed to an agent', replyTo: null, recipientIds: ['AGENT'] },
{ type: 'conversation.create', title: 'Outcome', task: { goal: 'An independently assignable result', changes: 'What changes', constraints: 'What must stay true', owns: ['Paths or code areas'] }, checks: [{ description: 'Observable acceptance evidence', independent: false }] },
{ type: 'conversation.create', title: 'Review: Outcome', reviewOf: 'GROUP', task: { goal: 'An independent verdict on the Builder\'s revision', changes: 'None: read only', constraints: 'The reviewed group\'s constraints', owns: ['The reviewed group\'s owned code, read only'] }, checks: [{ description: 'Verdict with the reviewed revision', independent: false }] },