The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Swarm 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.tsnew file mode 100644index 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.prismaindex 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.tsindex 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.tsindex 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 constexport 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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, commaif ('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: Commaif (actor.kind === 'agent') controls(state, actor)state.paused = command.pausedbreak+ 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.idleStoptarget.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.nowbreak}case 'agent.stopLease': {diff --git a/backend/src/superTabs/decisions.ts b/backend/src/superTabs/decisions.tsindex 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.tsindex 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 agentsdiff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.tsindex 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').SwarmSharingpaused: boolean+ /** Idle workers stop and finished groups archive by themselves (tidy.ts); false once the owner turns it off. */+ tidy?: falsepeople: Person[]agents: Agent[]conversations: Conversation[]diff --git a/backend/src/superTabs/parts/write.test.ts b/backend/src/superTabs/parts/write.test.tsindex 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.tsindex 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 Agentdiff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex 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 = falseif (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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 falsediff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.tsindex 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 texpect(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.tsindex 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.tsindex 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.tsindex 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_000const 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 } = knownconst { harnessProgress: _progress, ...withoutProgress } = readyconst { privacy: _privacy, ...withoutPrivacy } = withoutProgressconst { toolProbeErrors: _probeErrors, localModels: _served, refusedModels: _refused, ...legacy } = withoutPrivacy// A backend before `starting` refuses it: it gets the models the grid lists, as before, not none at all.const listedOnly = localModels?.some(m => m.starting)? [{ ...withoutPrivacy, localModels: localModels.filter(m => !m.starting) }] : []- const attempts = [...('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_MSelse if ('harnessProgress' in attempt) this.progressRefusedUntil = began + FIELD_REFUSED_MSelse 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/idiff --git a/cli/src/superTabs/service.spec.ts b/cli/src/superTabs/service.spec.tsindex 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 requestaskedIn: { 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.tsindex 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 }] },