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
/**
* A crew member's folder on its host (task #3398). The server says when a member sleeps, moves or has its folder dropped
* (backend superTabs/crewKeep.ts, on the agent record of its row); this keeps the folder in step:
* - a dropped folder goes through the Swarm's own worktree removal (machines.ts removeStoppedWorktree), which refuses one
* with work not committed or pushed, and is remembered so a wake brings it back at the same path, where the engine's
* conversation is filed (claude --resume and codex resume find it by folder);
* - finished branch copies go: a local branch whose work merged into the default branch, or whose remote branch was
* deleted (a merged or closed pull request). Never the current branch or one never pushed; a deleted branch's tip is
* kept under refs/harness/dropped/ so no commit becomes unreachable. Only branches this member's own folder was on: the
* clone's other branches (a person's, other agents') are never touched (security reviews of #3229).
*/
import { execFile } from 'node:child_process'
import { ownProcessGroup } from '../lib/windows/noWindow.js'
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
import { dirname, isAbsolute, join } from 'node:path'
import { promisify } from 'node:util'
const run = promisify(execFile)
// No window on Windows (docs/windows-rules.md): a woken Member's folder comes back through here (task #4698).
const git = async (cwd: string, ...args: string[]) => (await run('git', args, { cwd, timeout: 60_000, maxBuffer: 4 * 1024 * 1024, ...ownProcessGroup() })).stdout.trim()
/** What a crew row asks of its host, from its agent record: close it to sleep (folder kept), close it and drop its folder, or
* close it because it moves elsewhere. Null for an awake member. */
export function crewRest(agent: { asleep?: { since?: unknown; folderDropped?: unknown } | null; movedTo?: unknown }): 'sleep' | 'drop' | 'moving' | null {
if (agent.movedTo) return 'moving'
if (agent.asleep) return agent.asleep.folderDropped === true ? 'drop' : 'sleep'
return null
}
type Remembered = { tabId: string; harnessId: string; path: string; source: string }
export interface CrewFoldersDeps {
dataDir: string
machineId: string
/** The Swarm's record of this member's worktree (machines.ts swarm-worktrees file): its folder and its project clone. */
worktree(tabId: string, harnessId: string): { path: string; source: string } | null
/** The Swarm's own removal, with its proofs and refusals (machines.ts removeStoppedWorktree). */
removeWorktree(tabId: string, harnessId: string): Promise<void>
log(line: string): void
}
export class CrewFolders {
/** This host's record, read once and kept in step with its writes: only this host writes the file. */
private cache?: Remembered[]
constructor(private readonly deps: CrewFoldersDeps) {}
/** Whether [harnessId]'s folder was dropped and waits to come back: read from disk, so a host restart forgets nothing. */
remembers(tabId: string, harnessId: string): boolean {
return this.read().some(r => r.tabId === tabId && r.harnessId === harnessId)
}
private get file() { return join(this.deps.dataDir, 'super-tabs', `crew-folders-${this.deps.machineId}.json`) }
private read(): Remembered[] {
return this.cache ??= this.readFile()
}
private readFile(): Remembered[] {
try {
const rows = (JSON.parse(readFileSync(this.file, 'utf8')) as { folders?: unknown }).folders
return Array.isArray(rows) ? rows.filter((r): r is Remembered => !!r && typeof r === 'object' && ['tabId', 'harnessId', 'path', 'source']
.every(k => typeof (r as Record<string, unknown>)[k] === 'string') && isAbsolute((r as Remembered).path) && isAbsolute((r as Remembered).source)) : []
} catch { return [] }
}
private write(rows: Remembered[]) {
this.cache = rows
mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 })
writeFileSync(`${this.file}.next`, JSON.stringify({ version: 1, folders: rows }), { mode: 0o600 })
renameSync(`${this.file}.next`, this.file)
}
private forget(tabId: string, harnessId: string) {
const rows = this.read(), kept = rows.filter(r => !(r.tabId === tabId && r.harnessId === harnessId))
if (kept.length !== rows.length) this.write(kept)
}
/** Drops [harnessId]'s folder ('dropped'), or keeps it when the removal refused it ('kept'), or finds no record ('none'). */
async drop(tabId: string, harnessId: string): Promise<'dropped' | 'kept' | 'none'> {
const worktree = this.deps.worktree(tabId, harnessId)
if (!worktree) return 'none'
this.write([...this.read().filter(r => !(r.tabId === tabId && r.harnessId === harnessId)), { tabId, harnessId, ...worktree }])
await this.deps.removeWorktree(tabId, harnessId)
if (!existsSync(worktree.path)) return 'dropped'
this.forget(tabId, harnessId)
this.deps.log('Kept an asleep crew folder: the Swarm\'s removal refused it')
return 'kept'
}
/** Brings back a dropped folder at its own path, on the default branch, before its session reopens there. */
async restore(tabId: string, harnessId: string): Promise<'restored' | 'none' | 'failed'> {
const remembered = this.read().find(r => r.tabId === tabId && r.harnessId === harnessId)
if (!remembered) return 'none'
if (existsSync(remembered.path)) { this.forget(tabId, harnessId); return 'none' }
try {
await git(remembered.source, 'worktree', 'prune')
const base = await git(remembered.source, 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD').catch(() => 'HEAD')
await git(remembered.source, 'worktree', 'add', '--detach', remembered.path, base)
this.forget(tabId, harnessId)
return 'restored'
} catch (error) {
this.deps.log(`Could not bring back a crew folder: ${error instanceof Error ? error.name : typeof error}`)
return 'failed'
}
}
}
/** Deletes [folder]'s finished branch copies and returns their names (see the file's comment for which). */
export async function pruneBranches(folder: string): Promise<string[]> {
const checkedOut = new Set((await git(folder, 'worktree', 'list', '--porcelain')).split('\n')
.filter(l => l.startsWith('branch refs/heads/')).map(l => l.slice('branch refs/heads/'.length)))
const base = await git(folder, 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD').catch(() => '')
const rows = (await git(folder, 'for-each-ref', 'refs/heads', '--format=%(refname:short)%09%(upstream)%09%(upstream:track)%09%(objectname)'))
.split('\n').filter(Boolean).map(line => { const [name, upstream, track, sha] = line.split('\t'); return { name: name!, upstream: upstream ?? '', track: track ?? '', sha: sha ?? '' } })
// Only branches this member's own folder was on (its HEAD's history): a worktree shares its clone's branches, which on an
// own account is a person's checkout with their branches and other agents' (security review 2 of #3229).
const own = new Set((await git(folder, 'reflog', 'show', '--format=%gs', 'HEAD').catch(() => '')).split('\n')
.flatMap(line => /^checkout: moving from (\S+) to (\S+)$/.exec(line)?.slice(1, 3) ?? []))
const dropped: string[] = []
for (const branch of rows) {
if (!own.has(branch.name)) continue
// A branch tracking the default branch itself (a start's own branch) is no pull request's copy.
if (checkedOut.has(branch.name) || !branch.upstream || (base && branch.upstream === `refs/remotes/${base}`)) continue
const gone = branch.track === '[gone]'
const merged = !gone && !!base && await git(folder, 'merge-base', '--is-ancestor', branch.name, base).then(() => true, () => false)
if (!gone && !merged) continue
// Its tip stays reachable, so a commit that was only here (a squash-merged branch, a closed one) is never lost.
if (gone) await git(folder, 'update-ref', `refs/harness/dropped/${branch.name}`, branch.sha)
await git(folder, 'branch', '-D', branch.name)
dropped.push(branch.name)
}
return dropped
}