Skip to content

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

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.ts
index 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.ts
index 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 without
expect(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.ts
index 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 = first
else 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 = null
let 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.operationId
daemon = 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 : null
const 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) return
this.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 } })
+ }
}