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
feat(cli): clean a removed machine's Swarm folders and worktrees (#1653)
0xken15dfead979694d
diff --git a/cli/src/lib/worktreeSweep.ts b/cli/src/lib/worktreeSweep.tsindex bd34483d5..8f9270b4b 100644--- a/cli/src/lib/worktreeSweep.ts+++ b/cli/src/lib/worktreeSweep.ts@@ -8,7 +8,8 @@ const exec = promisify(execFile)/** A week without a commit, a checkout or an index write. */export const WORKTREE_IDLE_MS = 7 * 24 * 3600_000-async function git(cwd: string, args: string[]): Promise<string> {+/** git as itself: none of the repository settings a parent process left in the environment. */+export async function git(cwd: string, args: string[]): Promise<string> {const env = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' }for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE']) delete (env as NodeJS.ProcessEnv)[key]return (await exec('git', ['-C', cwd, ...args], { timeout: 30_000, killSignal: 'SIGKILL', maxBuffer: 1024 * 1024, env }))diff --git a/cli/src/superTabs/command.spec.ts b/cli/src/superTabs/command.spec.tsindex 978b9c7a4..cf7353a62 100644--- a/cli/src/superTabs/command.spec.ts+++ b/cli/src/superTabs/command.spec.ts@@ -176,3 +176,39 @@ it('gives up after three pending reads, and passes on a refused request withoutexpect(request).toHaveBeenCalledOnce()expect(JSON.parse(print.mock.calls.at(-1)![0])).toMatchObject({ error: 'LEAD_REQUIRED' })})+it('lets a machine owner preview and then remove their machine, as the person, without a participating harness', async () => {+ const print = vi.fn(), close = vi.fn()+ const request = vi.fn(async (_type: string, payload?: Record<string, unknown>) => payload?.method === 'GET'+ ? { ok: true, value: { blockedBy: null, agents: [{ id: 'a1', name: 'Builder', projectName: 'App' }], soleSourceProjects: [] } }+ : { ok: true, value: { revision: 2 } })+ const deps = { where: () => where, open: async () => ({ request, close, machineId: 'machine' }), print, pane: '%99', env: {} }+ expect(await superTabCommand(['--tab', 'tab', 'remove-machine', 'box'], deps)).toBe(0)+ expect(request.mock.calls.filter(c => c[0] === 'super_tabs')).toHaveLength(1)+ expect(request).toHaveBeenLastCalledWith('super_tabs', expect.objectContaining({ action: 'backend', method: 'GET', path: '/api/super-tabs/tab/machines/box/removal' }), 30_000)+ expect(print.mock.calls.at(-1)![0]).toContain('Builder')+ expect(await superTabCommand(['--tab', 'tab', 'remove-machine', 'box', '--yes'], deps)).toBe(0)+ const sent = request.mock.calls.at(-1)![1]!+ expect(sent).toMatchObject({ action: 'backend', method: 'POST', path: '/api/super-tabs/tab/commands', body: { command: { type: 'machine.remove', machineId: 'box' } } })+ expect(String((sent.body as Record<string, unknown>).operationId)).toMatch(/^machine-remove-/)+ request.mockImplementation(async (type: string) => (type === 'super_tabs'+ ? { error: 'LEAD_PROTECTED', detail: 'This machine runs the Product Manager of App.' } : { agents: [] }) as never)+ expect(await superTabCommand(['--tab', 'tab', 'remove-machine', 'box', '--yes'], deps)).toBe(1)+ expect(print.mock.calls.at(-1)![0]).toContain('Product Manager of App')+ for (const argv of [['--tab', 'tab', 'remove-machine'], ['--tab', 'tab', 'remove-machine', '../x'], ['--tab', 'tab', 'remove-machine', 'box', '--force']]) {+ expect(() => parseSuperTabArgs(argv, where)).toThrow('harness super-tab')+ }+})+it('refuses to remove a machine for an agent: a Swarm agent\'s pane, an outside agent\'s shell, or --agent', async () => {+ const print = vi.fn(), close = vi.fn()+ const request = vi.fn(async (type: string) => type === 'agents_list' ? { agents: [{ id: 'worker', engine: 'claude', tmuxPane: '%7', status: 'active' }] } : { ok: true })+ const deps = { where: () => where, open: async () => ({ request, close, machineId: 'machine' }), print }+ for (const [argv, extra] of [+ [['--tab', 'tab', 'remove-machine', 'box', '--yes'], { pane: '%7', env: {} }],+ [['--tab', 'tab', 'remove-machine', 'box', '--yes'], { pane: '%99', env: { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 'session' } }],+ [['--tab', 'tab', '--agent', 'agent', 'remove-machine', 'box', '--yes'], { pane: '%99', env: {} }],+ ] as const) {+ expect(await superTabCommand(argv, { ...deps, ...extra })).toBe(1)+ expect(print.mock.calls.at(-1)![0]).toContain('your own terminal')+ }+ expect(request.mock.calls.some(c => c[0] === 'super_tabs')).toBe(false)+})diff --git a/cli/src/superTabs/command.ts b/cli/src/superTabs/command.tsindex 0a8a0b3ce..412f5c029 100644--- a/cli/src/superTabs/command.ts+++ b/cli/src/superTabs/command.ts@@ -2,14 +2,14 @@ import { inspectCapacity, startAgent } from './start.js'import { object } from './host.js'import { routeTask } from './routeCommand.js'import { openDaemon, whereFor, type Daemon, type Where } from '../agentClient/daemon.js'-import { callerOf, type Frame } from '../agentClient/model.js'+import { callerOf, outsideCaller, type Frame } from '../agentClient/model.js'import { identifier } from './host.js'import { resolve } from 'node:path'import { uploadAttachments } from './attach.js'import { keyName } from './terminal.js'import { randomUUID } from 'node:crypto'-const USAGE = 'harness super-tab --tab ID [--agent ID] [--port N --machine ID] status | messages GROUP | message GROUP MESSAGE_ID | post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... | command OPERATION_ID JSON | start OPERATION_ID JSON | resume START_ID | capacity MACHINE_ID JSON | route GROUP JSON | screen AGENT [--scrollback N] | type AGENT [TEXT] [--key K]... | help'+const USAGE = 'harness super-tab --tab ID [--agent ID] [--port N --machine ID] status | messages GROUP | message GROUP MESSAGE_ID | post GROUP TEXT OPERATION_ID [--reply-to MESSAGE_ID] [--attach PATH]... | command OPERATION_ID JSON | start OPERATION_ID JSON | resume START_ID | capacity MACHINE_ID JSON | route GROUP JSON | remove-machine MACHINE_ID [--yes] | screen AGENT [--scrollback N] | type AGENT [TEXT] [--key K]... | help'export function parseSuperTabArgs(argv: readonly string[], where: Where) {const positional: string[] = []let tabId = '', agentId = ''@@ -50,6 +50,13 @@ export function parseSuperTabArgs(argv: readonly string[], where: Where) {} else if (action === 'resume' && identifier(first) && positional.length === 2) payload.startId = firstelse if (action === 'capacity' && identifier(first) && second && positional.length === 3) {Object.assign(payload, { targetMachineId: first, request: JSON.parse(second) })+ } else if (action === 'remove-machine' && identifier(first) && (positional.length === 2 || positional.length === 3 && second === '--yes')) {+ // The machine's owner, as the person: without --yes, what removal would do (the agents it stops, a refusal); with it,+ // the removal. The daemon's owner-only backend request carries both.+ Object.assign(payload, second === '--yes'+ ? { action: 'backend', method: 'POST', path: `/api/super-tabs/${tabId}/commands`,+ body: { operationId: `machine-remove-${randomUUID()}`, command: { type: 'machine.remove', machineId: first } } }+ : { action: 'backend', method: 'GET', path: `/api/super-tabs/${tabId}/machines/${first}/removal` })} else if (action === 'route' && identifier(first) && second && positional.length === 3) {Object.assign(payload, { conversationId: first, assessment: JSON.parse(second) })} else if (action === 'screen' && identifier(first) && (positional.length === 2@@ -76,7 +83,7 @@ export function parseSuperTabArgs(argv: readonly string[], where: Where) {}export async function superTabCommand(argv: readonly string[], deps: {- where?: () => Where; open?: typeof openDaemon; print?: (text: string) => void; pane?: string; fetch?: typeof fetch+ where?: () => Where; open?: typeof openDaemon; print?: (text: string) => void; pane?: string; fetch?: typeof fetch; env?: NodeJS.ProcessEnv} = {}): Promise<number> {let daemon: Daemon | null = nulllet operationId: unknown@@ -85,7 +92,15 @@ export async function superTabCommand(argv: readonly string[], deps: {const request = parseSuperTabArgs(argv, (deps.where ?? (() => whereFor(process.env.TMUX_PANE)))())operationId = request.payload.operationIddaemon = await (deps.open ?? openDaemon)(request.where)- if (request.payload.action !== 'help' && !request.payload.agentId) {+ if (request.payload.action === 'backend') {+ // The owner's own act: it deletes this machine's Swarm folders, so neither a Swarm agent on it (its pane, or --agent)+ // nor an outside agent's shell may run it with the owner's authority.+ const listed = request.payload.agentId || outsideCaller(deps.env ?? process.env, request.where.machineId) ? null : await daemon.request('agents_list')+ if (!listed || callerOf(Array.isArray(listed.agents) ? listed.agents as Frame[] : [], deps.pane ?? process.env.TMUX_PANE, request.where.machineId)) {+ throw new Error('Remove a machine from your own terminal or from Desktop, not from an agent.')+ }+ }+ if (!['help', 'backend'].includes(String(request.payload.action)) && !request.payload.agentId) {const listed = await daemon.request('agents_list')const frames = Array.isArray(listed.agents) ? listed.agents as Frame[] : []const caller = callerOf(frames, deps.pane ?? process.env.TMUX_PANE, request.where.machineId)diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.tsindex 8fb7e0426..293f72565 100644--- a/cli/src/superTabs/host.spec.ts+++ b/cli/src/superTabs/host.spec.ts@@ -1,4 +1,4 @@-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { dirname, join } from 'node:path'import { prepareSwarmSkill } from '../lib/swarmSkills.js'@@ -1424,3 +1424,29 @@ describe('closing the sessions the backend ends', () => {expect(t.commands).toHaveLength(0)})})++describe('a machine its owner removed from a Swarm', () => {+ afterEach(() => { vi.unstubAllEnvs() })+ it('cleans up for its own machine\'s cleanup row and acknowledges, ignoring another machine\'s', async () => {+ const t = setup()+ const home = join(t.dir, 'home'); vi.stubEnv('HOME', home); vi.stubEnv('USERPROFILE', home)+ const folder = join(t.dir, 'swarm-projects', 'tab', 'project'), other = join(t.dir, 'swarm-projects', 'other-tab')+ mkdirSync(folder, { recursive: true }); mkdirSync(other, { recursive: true })+ const sent: unknown[] = []+ vi.mocked(t.call).mockImplementation(async (method, path, body) => {+ if (path.includes('/hosts/')) return { status: 200, body: { success: true, data: [+ { tabId: 'tab', cleanup: { machineId: 'machine-1', removalId: 'removal' } },+ { tabId: 'other-tab', cleanup: { machineId: 'machine-2', removalId: 'theirs' } }] } }+ if (method === 'POST') sent.push(body)+ return { status: 200, body: { success: true, data: method === 'GET' ? { state: { starts: [] } } : { revision: 1 } } }+ })+ const host = t.open()+ await host.tick()+ await vi.waitFor(() => expect(sent).toEqual([{ operationId: 'machine-cleaned-removal', command: { type: 'machine.cleaned', machineId: 'machine-1', removalId: 'removal' } }]))+ expect(existsSync(join(t.dir, 'swarm-projects', 'tab'))).toBe(false)+ expect(existsSync(other)).toBe(true)+ await host.tick()+ await new Promise(resolve => setTimeout(resolve, 50))+ expect(sent).toHaveLength(1)+ })+})diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.tsindex 8d53d65b9..6a8e69323 100644--- a/cli/src/superTabs/host.ts+++ b/cli/src/superTabs/host.ts@@ -486,6 +486,7 @@ export class SuperTabHost {this.wakeShare(data)this.publishAttention(data)this.joinSwarms(data)+ this.cleanRemoved(data)// Off the poll: a screen read waits on the core, and never delays the input leases below.if (this.core.superTabs) void this.terminal.tick(data)// Recovery can wait on a native receipt. Run it beside leases, so another worker's input@@ -710,6 +711,17 @@ export class SuperTabHost {}}+ /** Its owner removed this machine from a Swarm: the roster names the cleanup until this host acknowledges it, so a host+ * that restarted part-way cleans again. Off the poll: deleting folders never delays deliveries. */+ private cleanRemoved(rows: unknown[]): void {+ for (const row of rows.map(object)) {+ const cleanup = object(row.cleanup)+ if (!identifier(row.tabId) || cleanup.machineId !== this.machineId || !identifier(cleanup.removalId)) continue+ this.machines ??= new ContributedMachines(this.core, this.machineId)+ void this.machines.clean(row.tabId, cleanup.removalId).catch(error => this.log(error instanceof Error ? error.message : String(error)))+ }+ }+/** Hands the core this roster's waits when they changed (or on the first roster). A failed roster read changes* nothing: a network blip does not close an alert. */private wakeShare(rows: unknown[]): void {diff --git a/cli/src/superTabs/machines.spec.ts b/cli/src/superTabs/machines.spec.tsindex aaf8a23d7..a63db31bd 100644--- a/cli/src/superTabs/machines.spec.ts+++ b/cli/src/superTabs/machines.spec.ts@@ -1,6 +1,11 @@-import { describe, expect, it, vi } from 'vitest'+import { execFileSync } from 'node:child_process'+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import { afterEach, describe, expect, it, vi } from 'vitest'+import type { RegisteredSession } from '../lib/registry.js'import { fakeCore } from '../testing/fakeCore.js'-import { ContributedMachines } from './machines.js'+import { ContributedMachines, swarmWorktreesFile } from './machines.js'import { SuperTabHostError } from './host.js'import { startAgent } from './start.js'@@ -350,3 +355,163 @@ describe('contributed machine executor', () => {})})})++describe('removed machine cleanup', () => {+ const roots: string[] = []+ afterEach(() => { vi.unstubAllEnvs(); for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) })+ const git = (cwd: string, ...args: string[]) => execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t', '-c', 'init.defaultBranch=main', ...args], { cwd, stdio: 'pipe' }).toString()+ const repo = (path: string) => { mkdirSync(path, { recursive: true }); git(path, 'init', '-q'); git(path, 'commit', '-q', '--allow-empty', '-m', 'init'); return path }+ const worktree = (source: string, path: string, branch: string) => { git(source, 'worktree', 'add', '-q', '-b', branch, path); writeFileSync(join(path, 'unpushed.txt'), 'work'); return path }+ const session = (agentId: string, cwd: string, startedBy?: 'agent') => ({ agentId, cwd, ...(startedBy ? { startedBy } : {}) }) as unknown as RegisteredSession++ /** A temporary home and Harness data folder: the tab's two Swarm folders, a Swarm clone, a person's own clone with+ * their own worktree, and Swarm worktrees made from each, one known from this host's record, one from the tab's+ * start receipts, and one whose receipt names another agent. */+ function machine() {+ const root = mkdtempSync(join(tmpdir(), 'swarm-cleanup-')); roots.push(root)+ const home = join(root, 'home'), data = join(root, 'data')+ vi.stubEnv('HOME', home); vi.stubEnv('USERPROFILE', home)+ const clone = repo(join(data, 'swarm-projects', 'tab', 'project'))+ const newRoot = join(home, 'harnesses', 'swarms', 'tab')+ mkdirSync(newRoot, { recursive: true }); writeFileSync(join(newRoot, 'notes.txt'), 'swarm')+ const otherTab = join(data, 'swarm-projects', 'other-tab'); mkdirSync(otherTab, { recursive: true })+ const own = repo(join(home, 'code', 'app'))+ const ownWorktree = worktree(own, join(home, 'harnesses', 'worktrees', 'app', 'mine'), 'mine')+ const recorded = worktree(clone, join(home, 'harnesses', 'worktrees', 'project', 'recorded'), 'super-tab/recorded')+ const earlier = worktree(own, join(home, 'harnesses', 'worktrees', 'app', 'earlier'), 'super-tab/earlier')+ const unproven = worktree(own, join(home, 'harnesses', 'worktrees', 'app', 'unproven'), 'super-tab/unproven')+ mkdirSync(join(data, 'super-tabs'), { recursive: true })+ writeFileSync(swarmWorktreesFile(data, 'host'), JSON.stringify({ version: 1, worktrees: [+ { tabId: 'tab', startId: 'recorded', harnessId: 'h-recorded', source: clone, path: recorded },+ { tabId: 'other-tab', startId: 'kept', harnessId: 'h-kept', source: own, path: ownWorktree },+ ] }))+ const starts = [+ { id: 'earlier', creationId: 'super-earlier', harnessId: 'h-earlier', request: { machineId: 'host', worktree: true, cwd: own } },+ { id: 'unproven', creationId: 'super-unproven', harnessId: 'h-unproven', request: { machineId: 'host', worktree: true, cwd: own } },+ { id: 'elsewhere', creationId: 'super-elsewhere', harnessId: 'h-elsewhere', request: { machineId: 'another', worktree: true, cwd: own } },+ ]+ let live = [session('h-recorded', recorded, 'agent')]+ const all = () => [...live, session('h-earlier', earlier, 'agent'), session('h-unproven', unproven, 'agent'), session('h-elsewhere', ownWorktree, 'agent')]+ const core = fakeCore({ dataDir: data, agents: {+ live: vi.fn(() => live), all: vi.fn(all),+ creationStatus: vi.fn(async (creationId: string) => ({ creationId, state: 'created' as const,+ agentId: creationId === 'super-unproven' ? 'someone-else' : `h-${creationId.slice('super-'.length)}` })),+ closeStarted: vi.fn(async (agentId: string) => { live = live.filter(s => s.agentId !== agentId); return { closed: true } as never }),+ } })+ const backend = vi.fn(async (_core: unknown, method: string, path: string, _body?: unknown): Promise<unknown> =>+ method === 'GET' && path === '/api/super-tabs/tab' ? { state: { starts } } : { revision: 1 })+ const log = vi.fn()+ let now = 0+ const open = () => new ContributedMachines(core, 'host', { backend, log, now: () => now } as never)+ const acks = () => backend.mock.calls.filter(c => c[1] === 'POST')+ return { core, backend, log, open, acks, home, data, clone, newRoot, otherTab, own, ownWorktree, recorded, earlier, unproven, starts,+ setLive: (sessions: RegisteredSession[]) => { live = sessions }, step: (ms: number) => { now += ms } }+ }++ it('deletes only the tab\'s Swarm folders and Swarm-made worktrees, then acknowledges once', async () => {+ const m = machine()+ const host = m.open()+ await host.clean('tab', 'removal')+ for (const gone of [join(m.data, 'swarm-projects', 'tab'), m.newRoot, m.recorded, m.earlier]) expect(existsSync(gone), gone).toBe(false)+ for (const kept of [m.own, m.ownWorktree, m.unproven, m.otherTab]) expect(existsSync(kept), kept).toBe(true)+ expect(readFileSync(join(m.ownWorktree, 'unpushed.txt'), 'utf8')).toBe('work')+ // The person's repository forgets only the Swarm worktree it held.+ const listed = git(m.own, 'worktree', 'list', '--porcelain')+ expect(listed).toContain('/mine\n'); expect(listed).not.toContain('/earlier\n')+ expect(m.core.agents.closeStarted).toHaveBeenCalledWith('h-recorded', 'now')+ expect(m.acks()).toEqual([[m.core, 'POST', '/api/super-tabs/tab/commands',+ { operationId: 'machine-cleaned-removal', command: { type: 'machine.cleaned', machineId: 'host', removalId: 'removal' } }]])+ expect(JSON.parse(readFileSync(swarmWorktreesFile(m.data, 'host'), 'utf8')).worktrees.map((w: { tabId: string }) => w.tabId)).toEqual(['other-tab'])+ expect(m.log.mock.calls.flat().join('\n')).toContain(m.unproven.split('/').pop())+ await host.clean('tab', 'removal')+ expect(m.acks()).toHaveLength(1)+ await expect(host.clean('../escape', 'other')).rejects.toThrow('Invalid machine removal.')+ })++ it('keeps a person\'s own worktree of the same repository even when the registry now lists it as the agent\'s folder', async () => {+ const m = machine()+ const outside = worktree(m.own, join(m.home, 'code', 'app-feature'), 'feature')+ vi.mocked(m.core.agents.all).mockReturnValue([session('h-earlier', m.ownWorktree, 'agent'), session('h-unproven', outside, 'agent')])+ vi.mocked(m.core.agents.creationStatus!).mockImplementation(async creationId => ({ creationId, state: 'created' as const, agentId: `h-${creationId.slice('super-'.length)}` }))+ await m.open().clean('tab', 'removal')+ for (const kept of [m.ownWorktree, outside, m.own]) expect(existsSync(kept), kept).toBe(true)+ expect(git(m.own, 'worktree', 'list', '--porcelain')).toContain('/mine\n')+ expect(m.acks()).toHaveLength(1)+ })++ it('reads git as itself, not through git settings the daemon inherited', async () => {+ const m = machine()+ vi.stubEnv('GIT_DIR', join(m.home, 'nowhere')); vi.stubEnv('GIT_WORK_TREE', join(m.home, 'nowhere'))+ await m.open().clean('tab', 'removal')+ expect(existsSync(m.recorded)).toBe(false)+ expect(existsSync(m.earlier)).toBe(false)+ })++ it('waits longer after each failed acknowledgement instead of cleaning again every pass', async () => {+ const m = machine()+ const host = m.open()+ m.backend.mockImplementationOnce(async () => ({ state: { starts: [] } })).mockRejectedValueOnce(new Error('Backend offline'))+ await expect(host.clean('tab', 'removal')).rejects.toThrow('Backend offline')+ const calls = m.backend.mock.calls.length+ await host.clean('tab', 'removal')+ m.step(59_000); await host.clean('tab', 'removal')+ expect(m.backend.mock.calls).toHaveLength(calls)+ m.step(1_000); await host.clean('tab', 'removal')+ expect(m.acks()).toHaveLength(2)+ })++ it('keeps a recorded folder that is no longer the worktree it recorded', async () => {+ const m = machine()+ rmSync(m.recorded, { recursive: true, force: true }); mkdirSync(m.recorded, { recursive: true })+ writeFileSync(join(m.recorded, 'mine.txt'), 'person')+ await m.open().clean('tab', 'removal')+ expect(readFileSync(join(m.recorded, 'mine.txt'), 'utf8')).toBe('person')+ expect(m.acks()).toHaveLength(1)+ })++ it('keeps a folder whose session will not close, cleans the rest and acknowledges', async () => {+ const m = machine()+ const person = session('person', join(m.newRoot), undefined)+ m.setLive([person])+ await m.open().clean('tab', 'removal')+ expect(m.core.agents.closeStarted).not.toHaveBeenCalledWith('person', 'now')+ expect(existsSync(m.newRoot)).toBe(true)+ expect(existsSync(join(m.data, 'swarm-projects', 'tab'))).toBe(false)+ expect(m.log.mock.calls.flat().join('\n')).toContain(m.newRoot)+ expect(m.acks()).toHaveLength(1)+ })++ it('finishes a cleanup after a restart that interrupted its acknowledgement', async () => {+ const m = machine()+ m.backend.mockImplementationOnce(async () => ({ state: { starts: [] } })).mockRejectedValueOnce(new Error('Backend offline'))+ await expect(m.open().clean('tab', 'removal')).rejects.toThrow('Backend offline')+ expect(existsSync(m.recorded)).toBe(false)+ await m.open().clean('tab', 'removal')+ expect(m.acks()).toHaveLength(2)+ expect(m.acks()[1]![3]).toEqual({ operationId: 'machine-cleaned-removal', command: { type: 'machine.cleaned', machineId: 'host', removalId: 'removal' } })+ })++ it('waits for the tab\'s start receipts before deleting anything', async () => {+ const m = machine()+ m.backend.mockRejectedValueOnce(new Error('Backend offline'))+ await expect(m.open().clean('tab', 'removal')).rejects.toThrow('Backend offline')+ expect(existsSync(m.recorded)).toBe(true)+ expect(existsSync(m.newRoot)).toBe(true)+ expect(m.acks()).toHaveLength(0)+ })++ it('records the worktree a Swarm start made', async () => {+ const root = mkdtempSync(join(tmpdir(), 'swarm-record-')); roots.push(root)+ const core = fakeCore({ dataDir: root, agents: { byAgent: vi.fn(id => id === 'h-new' ? session('h-new', '/worktrees/project/new', 'agent') : undefined) } })+ const pool = { tabId: 'tab', machine: { machineId: 'host', generation: 'grant', cwd: '/repo', engines: ['codex'], paused: false },+ harnessIds: [], starts: [{ id: 'new', dispatched: true, request: { worktree: true, cwd: '/clone' } }], paused: false }+ const backend = vi.fn(async (_core: unknown, _method: string, path: string, _body?: unknown): Promise<unknown> => path.endsWith('/pools') ? [pool] : { revision: 1 })+ const open = vi.fn(async () => ({ machineId: 'host', request: vi.fn(async () => ({})), close: vi.fn() }))+ const start = vi.fn(async () => ({ ok: true, harnessId: 'h-new' }))+ await new ContributedMachines(core, 'host', { backend, open, start, now: () => 0,+ capabilities: vi.fn(async () => ({ ok: true, resources: {}, tools: {} })) } as never).tick()+ expect(JSON.parse(readFileSync(swarmWorktreesFile(root, 'host'), 'utf8'))).toEqual({ version: 1, worktrees: [+ { tabId: 'tab', startId: 'new', harnessId: 'h-new', source: '/clone', path: '/worktrees/project/new' }] })+ expect(backend.mock.calls.some(c => JSON.stringify(c[3] ?? '').includes('agent.startSettled'))).toBe(true)+ })+})diff --git a/cli/src/superTabs/machines.ts b/cli/src/superTabs/machines.tsindex 2f6885f20..a186033b8 100644--- a/cli/src/superTabs/machines.ts+++ b/cli/src/superTabs/machines.ts@@ -1,3 +1,6 @@+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'+import { lstat, readFile, realpath, rm } from 'node:fs/promises'+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'import type { CoreApi } from '../core/api.js'import { openDaemon } from '../agentClient/daemon.js'import { backend, SuperTabHostError } from './host.js'@@ -5,7 +8,10 @@ import { identifier, object } from './wire.js'import { readCapabilities, quotaOf, meteredEngine } from './capacity.js'import { startAgent, type ScopedRequest } from './start.js'import { prepareSwarmProject } from './projectFolder.js'-import { createSwarmCloneTrustRepair } from './cloneTrust.js'+import { createSwarmCloneTrustRepair, swarmCloneRoots } from './cloneTrust.js'+import { git } from '../lib/worktreeSweep.js'+import { projectsRoot } from '../lib/projectFolder.js'+import { worktreeFolderName } from '../lib/agentNames.js'const finite = (v: unknown) => typeof v === 'number' && Number.isFinite(v) ? v : nullconst list = (v: unknown) => Array.isArray(v) ? v.map(object) : []@@ -23,6 +29,42 @@ export const MACHINE_POLL_MS = 5_000* silent from one that has nothing new (its offline threshold is counted in these beats). */export const MACHINE_HEARTBEAT_MS = 15_000+/** The worktrees this machine's Swarm starts made, by tab: what a removal may delete besides the tab's Swarm folders. */+export const swarmWorktreesFile = (dataDir: string, machineId: string) => join(dataDir, 'super-tabs', `swarm-worktrees-${machineId}.json`)+type SwarmWorktree = { tabId: string; startId: string; harnessId: string; source: string; path: string }+function readWorktrees(file: string): SwarmWorktree[] {+ let saved: unknown+ try { saved = JSON.parse(readFileSync(file, 'utf8')) } catch { return [] }+ const rows = object(saved).worktrees+ return (Array.isArray(rows) ? rows.map(object) : []).filter(w => [w.tabId, w.startId, w.harnessId].every(identifier)+ && typeof w.source === 'string' && isAbsolute(w.source) && typeof w.path === 'string' && isAbsolute(w.path)) as unknown as SwarmWorktree[]+}+function writeWorktrees(file: string, worktrees: SwarmWorktree[]) {+ mkdirSync(dirname(file), { recursive: true, mode: 0o700 })+ writeFileSync(`${file}.next`, JSON.stringify({ version: 1, worktrees }), { mode: 0o600, flush: true })+ renameSync(`${file}.next`, file)+}+const within = (parent: string, path: string) => {+ const rel = relative(resolve(parent), resolve(path))+ return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))+}+/** Whether `path` is the worktree a Swarm start made from `source`: in Harness's worktrees folder, named for that start+ * (start.ts names its branch super-tab/<start>; a taken name gets -2, -3), and still a linked worktree of `source`'s+ * repository. A person's own worktree, of the same repository or in the same folder, or one at the path now, is not.+ * The agent's registry folder alone is not proof: it can change after the launch. */+async function swarmWorktree(path: string, source: string, startId: string): Promise<boolean> {+ try {+ const real = await realpath(path), home = await realpath(join(projectsRoot(), 'worktrees'))+ const leaf = worktreeFolderName(`super-tab/${startId}`), name = basename(real)+ if (!within(home, real) || real === home || (name !== leaf && !/^\d+$/.test(name.startsWith(`${leaf}-`) ? name.slice(leaf.length + 1) : ''))) return false+ if (within(path, source) || !(await lstat(join(path, '.git'))).isFile()) return false+ const gitdir = /^gitdir: (.+)$/m.exec(await readFile(join(path, '.git'), 'utf8'))?.[1]?.trim()+ if (!gitdir) return false+ const common = (await git(source, ['rev-parse', '--git-common-dir'])).trim()+ return dirname(await realpath(resolve(path, gitdir))) === join(await realpath(resolve(source, common)), 'worktrees')+ } catch { return false }+}+/** Separate from chat delivery: slow resource readers and agent launches never* hold up a delivery lease. Only a tab's explicit owner grant wakes this queue. */export class ContributedMachines {@@ -41,6 +83,11 @@ export class ContributedMachines {private readonly toolCache = new Map<string, { value: boolean | null; detail?: string; until: number }>()/** Per waiting start, why it was last not started, so the log says it once per reason, not every pass. */private readonly waiting = new Map<string, string>()+ /** Removals cleaned and acknowledged by this host, and the one in progress per removal. */+ private readonly cleaned = new Set<string>()+ private readonly cleaning = new Map<string, Promise<void>>()+ /** Per removal whose cleanup or acknowledgement failed, how often and when it may run again. */+ private readonly cleanupRetries = new Map<string, { failures: number; at: number }>()constructor(private readonly core: CoreApi, private readonly machineId: string,private readonly deps: { backend: typeof backend; open: typeof openDaemon; capabilities: typeof readCapabilities;start: typeof startAgent; now: () => number; prepare?: typeof prepareSwarmProject; log?: (message: string) => void; env?: NodeJS.ProcessEnv } =@@ -51,7 +98,7 @@ export class ContributedMachines {private noteWaiting(startId: string, reason: string) {if (this.waiting.get(startId) === reason) returnthis.waiting.set(startId, reason)- ;(this.deps.log ?? (message => console.warn(`[super-tabs] ${message}`)))(`Swarm start ${startId} is waiting: ${reason}`)+ this.log(`Swarm start ${startId} is waiting: ${reason}`)}/** One pass at a time, one [MACHINE_POLL_MS] after the last began (or a beat after one that failed). */tick(): Promise<void> {@@ -178,6 +225,8 @@ export class ContributedMachines {const result = await this.deps.start({ tabId: row.tabId, startId: start.id, hostDispatch: true }, scoped, where, this.deps.open)if (result.ok === true && identifier(result.harnessId)) {this.waiting.delete(start.id)+ // Before the start settles: a settled start is no longer listed, so a missed record would never be made.+ this.recordWorktree(String(row.tabId), start.id, result.harnessId, object(start.request))await scoped({ action: 'command', operationId: `settled-${start.id}`,command: { type: 'agent.startSettled', startId: start.id, warning: result.modelWarning ?? null } })} else if (result.ok !== true) {@@ -191,4 +240,79 @@ export class ContributedMachines {}} finally { local?.close() }}+ /** 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+ if (request.worktree !== true || typeof request.cwd !== 'string' || !path) return+ try {+ const file = swarmWorktreesFile(this.core.dataDir, this.machineId), worktrees = readWorktrees(file)+ if (!worktrees.some(w => w.tabId === tabId && w.startId === startId)) writeWorktrees(file, [...worktrees, { tabId, startId, harnessId, source: request.cwd, path }])+ } catch (error) { this.log(`Could not record the worktree of Swarm start ${startId}: ${error instanceof Error ? error.message : String(error)}`) }+ }+ private log(message: string) { (this.deps.log ?? (line => console.warn(`[super-tabs] ${line}`)))(message) }++ /** Its owner removed this machine from the tab's Swarm (docs: 2026-10-23-remove-machine): close the Swarm's sessions+ * here, delete the tab's Swarm folders and the worktrees its starts made, and acknowledge. Each step is safe to repeat,+ * so a host that stopped part-way does it again from the roster's cleanup row, which stays until acknowledged. */+ clean(tabId: string, removalId: string): Promise<void> {+ // Both name folders and an operation: nothing else may reach a path.+ if (!identifier(tabId) || !identifier(removalId)) return Promise.reject(new Error('Invalid machine removal.'))+ if (this.cleaned.has(removalId) || this.deps.now() < (this.cleanupRetries.get(removalId)?.at ?? 0)) return Promise.resolve()+ const running = this.cleaning.get(removalId) ?? this.runCleanup(tabId, removalId)+ .then(() => { this.cleaned.add(removalId); this.cleanupRetries.delete(removalId) }, error => {+ // The row asks again every poll; a backend that keeps failing is asked a minute later, doubling up to half an hour.+ const retry = this.cleanupRetries.get(removalId) ?? { failures: 0, at: 0 }+ retry.at = this.deps.now() + Math.min(30 * 60_000, 60_000 * 2 ** retry.failures++)+ this.cleanupRetries.set(removalId, retry)+ throw error+ }).finally(() => this.cleaning.delete(removalId))+ this.cleaning.set(removalId, running)+ return running+ }+ private async runCleanup(tabId: string, removalId: string) {+ const file = swarmWorktreesFile(this.core.dataDir, this.machineId)+ const recorded = readWorktrees(file).filter(w => w.tabId === tabId)+ // Starts from before the record: a worktree counts only when this machine's receipt for that start created the+ // very agent the registry lists as agent-started in it. A start receipt read is required; a tab gone or no longer+ // readable by this owner leaves only the record.+ let starts: Record<string, unknown>[] = []+ try { starts = list(object(object(await this.deps.backend(this.core, 'GET', `/api/super-tabs/${tabId}`)).state).starts) }+ catch (error) { if (!(error instanceof SuperTabHostError) || ![403, 404].includes(error.status)) throw error }+ const swarm = new Set(recorded.map(w => w.harnessId))+ const candidates = recorded.map(w => ({ source: w.source, path: w.path, startId: w.startId, proven: true }))+ for (const start of starts) {+ const request = object(start.request)+ if (request.machineId !== this.machineId || !identifier(start.id) || !identifier(start.harnessId) || !identifier(start.creationId)) continue+ const creation = await this.core.agents.creationStatus?.(start.creationId)+ const proven = creation?.state === 'created' && creation.agentId === start.harnessId+ if (proven) swarm.add(start.harnessId)+ const agent = this.core.agents.all().find(a => a.agentId === start.harnessId)+ if (request.worktree === true && typeof request.cwd === 'string' && agent?.cwd && !candidates.some(c => c.path === agent.cwd)) {+ candidates.push({ source: request.cwd, path: agent.cwd, startId: start.id, proven: proven && agent.startedBy === 'agent' })+ }+ }+ const worktrees: string[] = []+ for (const c of candidates) {+ if (c.proven && await swarmWorktree(c.path, c.source, c.startId)) worktrees.push(c.path)+ else if (existsSync(c.path)) this.log(`Kept ${c.path}: it is not provably a worktree a Swarm start made.`)+ }+ const targets = [...worktrees, ...swarmCloneRoots(this.core.dataDir, tabId)]+ const inside = (cwd: string | null) => !!cwd && targets.some(t => within(t, cwd))+ for (const agent of this.core.agents.live()) {+ if (agent.startedBy === 'agent' && (swarm.has(agent.agentId) || inside(agent.cwd))) {+ await this.core.agents.closeStarted?.(agent.agentId, 'now').catch(() => null)+ }+ }+ const open = this.core.agents.live().map(a => a.cwd).filter((cwd): cwd is string => !!cwd)+ for (const target of targets) {+ if (open.some(cwd => within(target, cwd))) { this.log(`Kept ${target}: a session still runs in it.`); continue }+ const source = candidates.find(c => c.path === target)?.source+ // git forgets the worktree in its repository too; a folder it refuses (a submodule, a lock) is deleted as a folder.+ if (source) await git(source, ['worktree', 'remove', '--force', target]).catch(() => null)+ await rm(target, { recursive: true, force: true })+ }+ writeWorktrees(file, readWorktrees(file).filter(w => w.tabId !== tabId))+ await this.deps.backend(this.core, 'POST', `/api/super-tabs/${tabId}/commands`, { operationId: `machine-cleaned-${removalId}`,+ command: { type: 'machine.cleaned', machineId: this.machineId, removalId } })+ }}