@switchyardhq/git-fleet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammed Alkindi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <img src="assets/logo.svg" alt="Switchyard logo" width="140">
+  </picture>
+</p>
+
+# Switchyard
+
+> One repo, many AI coding agents, zero collisions — Switchyard's `fleet` CLI gives every agent an isolated git worktree, with collision detection before you merge.
+
+[![npm version](https://img.shields.io/npm/v/@switchyardhq/git-fleet)](https://www.npmjs.com/package/@switchyardhq/git-fleet)
+[![npm downloads](https://img.shields.io/npm/dm/@switchyardhq/git-fleet)](https://www.npmjs.com/package/@switchyardhq/git-fleet)
+[![license](https://img.shields.io/github/license/MohammedAlkindi/Switchyard)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/MohammedAlkindi/Switchyard/ci.yml?branch=main&label=CI)](https://github.com/MohammedAlkindi/Switchyard/actions/workflows/ci.yml)
+![coverage](https://img.shields.io/badge/coverage-80%25-green)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](tsconfig.json)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/MohammedAlkindi/Switchyard/pulls)
+
+<!-- The coverage badge is a static number: re-run `npm run test:coverage` and update it
+     when it drifts. Replace with a Codecov (or similar) badge once coverage upload is
+     wired into CI. -->
+
+
+<p align="center">
+  <img src="assets/demo.gif" alt="30-second demo: fleet spawn isolates two agents, fleet list shows the whole fleet, fleet check catches the collision before anyone merges" width="830">
+</p>
+
+<p align="center">
+  <sub><code>fleet spawn</code> two agents · <code>fleet list</code> the whole fleet · <code>fleet check</code> catches the collision before anyone merges · <a href="assets/demo.mp4">full-quality mp4</a></sub>
+</p>
+
+<!-- The demo is rendered from demo.tape with vhs (see the comments at the top of that
+     file), producing assets/demo.mp4. The inline GIF is converted from it with:
+       ffmpeg -i assets/demo.mp4 -vf "fps=10,scale=960:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=128[p];[s1][p]paletteuse=dither=bayer:bayer_scale=5" -loop 0 assets/demo.gif
+     (GitHub only inline-plays mp4s uploaded via its web editor, not committed files —
+     a committed GIF is the reliable way to get a moving demo on the README.) -->
+
+Two AI coding agents on one checkout ends badly. This project exists because Codex silently ran a `git reset` on `main` mid-merge while Claude Code was mid-task on the same files — the merge state vanished and neither agent noticed. The failure mode isn't exotic: two agents, one working tree, no isolation. Switchyard (published as `@switchyardhq/git-fleet`; the installed command is `fleet`) gives each agent its own git worktree and branch, tracks them centrally, and flags collisions between agents before anyone merges.
+
+## What it looks like
+
+*(The same flow as the [demo video](assets/demo.mp4), in skimmable, copy-pasteable form.)*
+
+```console
+$ fleet spawn claude
+Spawned agent claude
+  branch:   fleet/claude (from main)
+  worktree: ~/project/.fleet/worktrees/claude
+
+Point your agent at it:
+  cd ~/project/.fleet/worktrees/claude
+
+$ fleet list
+┌────────┬──────────────┬──────┬───────┬───────────────┬───────────────┬──────────────────────────┐
+│ AGENT  │ BRANCH       │ BASE │ +/-   │ CHANGES       │ LAST ACTIVITY │ WORKTREE                 │
+├────────┼──────────────┼──────┼───────┼───────────────┼───────────────┼──────────────────────────┤
+│ claude │ fleet/claude │ main │ +3/-0 │ clean         │ 12m ago       │ .fleet/worktrees/claude  │
+│ codex  │ fleet/codex  │ main │ +1/-2 │ 4 uncommitted │ just now      │ .fleet/worktrees/codex   │
+└────────┴──────────────┴──────┴───────┴───────────────┴───────────────┴──────────────────────────┘
+
+$ fleet check
+1 collision risk detected:
+┌───────────────────┬───────────────┐
+│ FILE              │ AGENTS        │
+├───────────────────┼───────────────┤
+│ src/api/routes.ts │ claude, codex │
+└───────────────────┴───────────────┘
+These files are touched by more than one agent (committed or uncommitted). Coordinate before merging.
+```
+
+## Installation
+
+```sh
+npm install -g @switchyardhq/git-fleet
+```
+
+Requires Node.js >= 18.17 and git >= 2.31. The installed command is `fleet`.
+
+## Quickstart
+
+```sh
+cd your-repo
+fleet spawn claude              # isolated worktree on branch fleet/claude
+cd .fleet/worktrees/claude      # point your agent here and let it work
+fleet check                     # any files also touched by other agents?
+fleet sync claude               # base moved on? catch the branch up
+fleet exec claude -- npm test   # run commands in the worktree without cd'ing
+fleet diff claude               # review the branch before merging
+fleet merge claude              # merge into your current branch + clean up the agent
+fleet pr claude                 # …or push it and open a PR via gh instead
+```
+
+## Commands
+
+| Command | Description | Key flags |
+| --- | --- | --- |
+| `fleet spawn <agent>` | Create a worktree in `.fleet/worktrees/<agent>/` on a new branch `fleet/<agent>`, then provision it (`copyOnSpawn` / `postSpawn` below) | `--from <branch>` base branch (default: current branch) |
+| `fleet list` | All active agents: branch, base, ahead/behind, uncommitted count, last activity | `--json` machine-readable output |
+| `fleet status <agent>` | One agent in detail: uncommitted files, diff stat vs base, ahead/behind | `--json` machine-readable output |
+| `fleet check` | Table of files touched by more than one agent — collision risks before merging. Exits 1 if any are found (CI-friendly) | `--lines` only count overlapping line ranges, `--json` machine-readable output |
+| `fleet diff <agent>` | Full diff of the agent's branch against its base | `--base <branch>` diff against a different branch |
+| `fleet sync <agent>` | Merge the agent's base branch into its branch, catching it up. A conflicting merge is aborted — never left half-done | — |
+| `fleet exec <agent> -- <cmd>` | Run a shell command inside the agent's worktree (e.g. `fleet exec claude -- npm test`) | `--all` run in every worktree sequentially; exits 1 if any run fails |
+| `fleet merge <agent>` | Check for collisions, run the `preMerge` hook, merge the agent's branch into the current branch, then remove the worktree and branch. A conflicting merge is aborted — never left half-done | `--no-clean` keep the worktree and branch, `--delete-branch` explicit form of the default cleanup |
+| `fleet pr <agent>` | Push the agent's branch to `origin` and open a pull request with the [GitHub CLI](https://cli.github.com) — the review-based alternative to a local merge | `--title <t>`, `--base <branch>`, `--draft` |
+| `fleet remove <agent>` | Remove the worktree; refuses if there are uncommitted changes | `--force` discard changes, `--delete-branch` also delete the branch |
+| `fleet clean` | Remove agents whose branches are fully merged into their base | `--dry-run` list only, `--stale <days>` also remove long-idle agents (clean worktrees only; their branches are kept) |
+| `fleet watch` | `fleet list`, re-rendered live until Ctrl+C | `--interval <seconds>` refresh rate (default 3) |
+| `fleet doctor` | Diagnose git version, state file validity, orphaned worktrees, and stale entries. Exits 1 if problems remain | `--fix` repair: rebuild state from `git worktree list`, adopt/remove orphans, prune stale entries; `--json` machine-readable output |
+| `fleet completion <shell>` | Print a completion script for `bash`, `zsh`, or `fish` (agent names are a snapshot from generation time) | — |
+
+All commands work from the main checkout **or** from inside any agent worktree.
+
+### Scripting and CI
+
+`list`, `status`, `check`, and `doctor` all take `--json` for machine-readable output, so agents and CI can consume Switchyard state directly — e.g. a merge gate:
+
+```sh
+fleet check --json || exit 1                  # exit code alone is enough for CI
+fleet list --json | jq -r '.[].name'          # enumerate active agents
+```
+
+`fleet check --lines` refines collision detection from files to line ranges: two agents editing disjoint parts of one file are reported separately instead of blocking. Ranges are computed against each pair's merge base — exact when both agents share a base, a documented heuristic otherwise (see [docs/architecture.md](docs/architecture.md)).
+
+## Configuration
+
+An optional `.fleetrc.json` at the repo root sets per-repo defaults. Precedence everywhere: CLI flag > `.fleetrc.json` > built-in default.
+
+```json
+{
+  "$schema": "https://unpkg.com/@switchyardhq/git-fleet/schema/fleetrc.schema.json",
+  "defaultBase": "main",
+  "watchInterval": 3,
+  "autoClean": false,
+  "copyOnSpawn": [".env"],
+  "postSpawn": "npm ci",
+  "preMerge": "npm test"
+}
+```
+
+- `$schema` — optional; points editors at the config's JSON schema for autocomplete and validation. The schema ships with the package (`node_modules/@switchyardhq/git-fleet/schema/fleetrc.schema.json`).
+- `defaultBase` — base branch for `fleet spawn` when `--from` is not passed (built-in default: the current branch).
+- `watchInterval` — refresh interval for `fleet watch`, in seconds (built-in default: 3).
+- `autoClean` — when `true`, every successful `fleet merge` also runs a `fleet clean` sweep for other fully merged agents (built-in default: `false`).
+- `copyOnSpawn` — repo-root-relative files/directories copied into every new worktree by `fleet spawn`. Worktrees don't carry gitignored files, so a fresh one has no `.env` or local config — this fixes that. Missing entries are skipped with a note.
+- `postSpawn` — shell command run inside the new worktree after `fleet spawn` (e.g. `npm ci`), so the worktree is ready to work in. A failing hook is reported but the worktree is kept.
+- `preMerge` — shell command run inside the agent's worktree before `fleet merge` starts (e.g. `npm test`). A non-zero exit aborts the merge before anything is touched.
+
+A malformed config file is a hard error with the offending key named; a missing one is fine.
+
+> [!NOTE]
+> `postSpawn` and `preMerge` run shell commands straight from the repo's `.fleetrc.json` — the same trust you already extend to a repo's npm scripts or git hooks. Review that file before running `fleet spawn` or `fleet merge` in a repository you didn't author (details in [SECURITY.md](SECURITY.md)).
+
+## How it works
+
+`fleet spawn` runs `git worktree add` under the hood: each agent gets a real, separate directory with its own checkout of a dedicated `fleet/<agent>` branch, so one agent's `git reset` physically cannot touch another agent's files. A single gitignored `.fleet/state.json` in the main repo maps each agent to its branch, base, and worktree, and `fleet check` uses it to diff every agent branch against its base (`git diff base...branch`, plus uncommitted edits) and cross-reference the changed files. Switchyard also adds `.fleet/` to `.git/info/exclude` automatically, so it never dirties the repos it manages. Design rationale and limitations live in [docs/architecture.md](docs/architecture.md).
+
+## Contributing
+
+PRs are welcome. Clone, `npm install`, `npm test` — every command is tested against real throwaway git repositories, and any change to a command must come with such a test (no git mocks; see [CLAUDE.md](CLAUDE.md) and [AGENTS.md](AGENTS.md) for the ground rules). Commits follow [Conventional Commits](https://www.conventionalcommits.org/). Read [docs/architecture.md](docs/architecture.md) before structural changes, and [docs/deployment.md](docs/deployment.md) for the release process.
+
+## License
+
+MIT © Mohammed Alkindi — see [LICENSE](LICENSE).

package/dist/cli.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import chalk from 'chalk';
+import { Command } from 'commander';
+import { check } from './commands/check.js';
+import { clean } from './commands/clean.js';
+import { completion } from './commands/completion.js';
+import { diff } from './commands/diff.js';
+import { doctor } from './commands/doctor.js';
+import { exec } from './commands/exec.js';
+import { list } from './commands/list.js';
+import { merge } from './commands/merge.js';
+import { pr } from './commands/pr.js';
+import { remove } from './commands/remove.js';
+import { spawn } from './commands/spawn.js';
+import { status } from './commands/status.js';
+import { sync } from './commands/sync.js';
+import { watch } from './commands/watch.js';
+import { FleetError } from './lib/errors.js';
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+/** Run a command action, mapping expected failures to a clean exit-1 message. */
+async function run(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        process.exitCode = 1;
+        if (err instanceof FleetError) {
+            console.error(chalk.red(`error: ${err.message}`));
+            return;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`unexpected error: ${message}`));
+        if (process.env.FLEET_DEBUG && err instanceof Error && err.stack) {
+            console.error(err.stack);
+        }
+        else {
+            console.error(chalk.dim('Re-run with FLEET_DEBUG=1 for a stack trace.'));
+        }
+    }
+}
+const program = new Command();
+// Required for `fleet exec` passThroughOptions; only affects program-level
+// options (--version/--help), which must now precede the subcommand.
+program.enablePositionalOptions();
+program
+    .name('fleet')
+    .description('Manage multiple AI coding agents working on the same git repository.\n' +
+    'Each agent gets an isolated worktree + branch; Switchyard tracks them and\n' +
+    'flags file-level collisions before you merge.')
+    .version(pkg.version)
+    .showHelpAfterError('(run `fleet --help` for usage)');
+program
+    .command('spawn')
+    .description('create an isolated worktree + branch (fleet/<name>) for an agent')
+    .argument('<agent-name>', 'name for the agent, e.g. claude, codex, cursor')
+    .option('--from <branch>', 'base branch to spawn from (default: current branch)')
+    .action((name, opts) => run(() => spawn(name, opts)));
+program
+    .command('list')
+    .description('show all active agents: branch, ahead/behind, changes, last activity')
+    .option('--json', 'print machine-readable JSON instead of a table')
+    .action((opts) => run(() => list(opts)));
+program
+    .command('status')
+    .description("detailed view of one agent's worktree and branch vs its base")
+    .argument('<agent-name>', 'agent to inspect')
+    .option('--json', 'print machine-readable JSON instead of the summary')
+    .action((name, opts) => run(() => status(name, opts)));
+program
+    .command('check')
+    .description('flag files touched by more than one agent (exits 1 if any are found)')
+    .option('--lines', 'only count files whose edited line ranges actually overlap')
+    .option('--json', 'print machine-readable JSON instead of a table')
+    .action((opts) => run(async () => {
+    const result = await check(opts);
+    if (result.collisions.length > 0)
+        process.exitCode = 1;
+}));
+program
+    .command('diff')
+    .description("show an agent branch's full diff against its base branch")
+    .argument('<agent-name>', 'agent to diff')
+    .option('--base <branch>', 'diff against this branch instead of the recorded base')
+    .action((name, opts) => run(() => diff(name, opts)));
+program
+    .command('sync')
+    .description("merge an agent's base branch into its branch, catching it up")
+    .argument('<agent-name>', 'agent to sync')
+    .action((name) => run(() => sync(name)));
+program
+    .command('exec')
+    .description("run a shell command inside an agent's worktree (or all worktrees)")
+    .argument('[agent-name]', 'agent whose worktree to run in (omit with --all)')
+    .argument('[command...]', 'command to run, e.g. `fleet exec claude -- npm test`')
+    .option('--all', "run in every agent's worktree, sequentially")
+    .passThroughOptions()
+    .action((name, command, opts) => run(async () => {
+    // With --all the first positional is part of the command, not an agent.
+    let tokens = opts.all && name !== undefined ? [name, ...command] : command;
+    // commander keeps the literal `--` separator in pass-through args.
+    if (tokens[0] === '--')
+        tokens = tokens.slice(1);
+    const result = await exec(opts.all ? undefined : name, tokens, { all: opts.all });
+    if (!result.ok)
+        process.exitCode = 1;
+}));
+program
+    .command('pr')
+    .description("push an agent's branch to origin and open a pull request via gh")
+    .argument('<agent-name>', 'agent to open a PR for')
+    .option('--title <title>', 'PR title (default: gh --fill from the last commit)')
+    .option('--base <branch>', "PR base branch (default: the agent's recorded base)")
+    .option('--draft', 'open the PR as a draft')
+    .action((name, opts) => run(() => pr(name, opts)));
+program
+    .command('watch')
+    .description('live-updating `fleet list`, re-rendered on an interval until Ctrl+C')
+    .option('--interval <seconds>', 'refresh interval in seconds (default: 3)', parseFloat)
+    .action((opts) => run(() => watch(opts)));
+program
+    .command('merge')
+    .description("merge an agent's branch into the current branch, then clean up the agent")
+    .argument('<agent-name>', 'agent to merge')
+    .option('--delete-branch', 'delete the branch after merging (already the default cleanup)')
+    .option('--no-clean', 'keep the worktree and branch after merging')
+    .action((name, opts) => run(() => merge(name, opts)));
+program
+    .command('doctor')
+    .description('diagnose state/reality drift; exits 1 if problems remain unfixed')
+    .option('--fix', 'repair what can be repaired (rebuild state, adopt/remove orphans, prune stale entries)')
+    .option('--json', 'print machine-readable JSON instead of the report')
+    .action((opts) => run(async () => {
+    const result = await doctor(opts);
+    if (!result.healthy)
+        process.exitCode = 1;
+}));
+program
+    .command('completion')
+    .description('output a shell completion script (agent names are a snapshot)')
+    .argument('<shell>', 'bash, zsh, or fish')
+    .action((shell) => run(() => completion(shell)));
+program
+    .command('remove')
+    .description("remove an agent's worktree (branch is kept unless --delete-branch)")
+    .argument('<agent-name>', 'agent to remove')
+    .option('--force', 'discard uncommitted changes / delete an unmerged branch')
+    .option('--delete-branch', "also delete the agent's fleet/<name> branch")
+    .action((name, opts) => run(() => remove(name, opts)));
+program
+    .command('clean')
+    .description('remove agents whose branches are fully merged into their base')
+    .option('--dry-run', 'list what would be cleaned without removing anything')
+    .option('--stale <days>', 'also remove agents idle for this many days (clean worktree only; branch kept)', parseFloat)
+    .action((opts) => run(() => clean(opts)));
+program.addHelpText('after', '\nExamples:\n' +
+    '  fleet spawn claude              spawn an agent off the current branch\n' +
+    '  fleet spawn codex --from main   spawn a second agent off main\n' +
+    '  fleet check --lines             any files touched by both, line-precise?\n' +
+    '  fleet sync claude               catch fleet/claude up with its base\n' +
+    '  fleet exec claude -- npm test   run tests inside the claude worktree\n' +
+    '  fleet diff claude               review before merging fleet/claude\n' +
+    '  fleet merge claude              merge fleet/claude and clean it up\n' +
+    '  fleet pr claude                 push fleet/claude and open a PR via gh\n' +
+    '  fleet remove codex --force      drop a worktree, discarding its changes\n' +
+    '  fleet clean --stale 14          sweep merged agents + 2-week-idle ones\n' +
+    '  fleet doctor --fix              repair state drift after manual surgery\n' +
+    '  fleet list --json               agent table as JSON, for scripts and CI\n');
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/commands/check.js

@@ -0,0 +1,144 @@
+import { existsSync } from 'node:fs';
+import { dim, fail, ok, plural, table } from '../lib/format.js';
+import { branchExists, changedFilesVsBase, getMainRepoRoot, gitAt, uncommittedFiles, } from '../lib/git.js';
+import { formatRanges, parseUnifiedDiff, rangesOverlap } from '../lib/lines.js';
+import { readState, worktreeAbsPath } from '../lib/state.js';
+/**
+ * Cross-reference every agent branch's changed files (committed vs base, plus
+ * uncommitted edits in the worktree) and flag files touched by more than one
+ * agent — the collision risks to resolve before anyone merges.
+ */
+export async function check(options = {}) {
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const git = gitAt(repoRoot);
+    const state = readState(repoRoot);
+    const agents = Object.values(state.agents).sort((a, b) => a.name.localeCompare(b.name));
+    const json = options.json ?? false;
+    if (agents.length < 2) {
+        const result = { collisions: [], agentsChecked: agents.length };
+        if (options.lines)
+            result.disjoint = [];
+        if (json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(`Nothing to check: ${plural(agents.length, 'active agent')} ` +
+                '(collisions need at least 2).');
+        }
+        return result;
+    }
+    const agentsByFile = new Map();
+    // --lines only: file -> agent -> edited ranges (merge-base coordinates).
+    const rangesByFile = new Map();
+    for (const record of agents) {
+        const files = new Set();
+        if ((await branchExists(git, record.branch)) &&
+            (await branchExists(git, record.baseBranch))) {
+            for (const f of await changedFilesVsBase(git, record.baseBranch, record.branch)) {
+                files.add(f);
+            }
+        }
+        const abs = worktreeAbsPath(repoRoot, record);
+        if (existsSync(abs)) {
+            for (const f of await uncommittedFiles(abs))
+                files.add(f.path);
+        }
+        for (const file of files) {
+            const touchers = agentsByFile.get(file) ?? [];
+            touchers.push(record.name);
+            agentsByFile.set(file, touchers);
+        }
+        if (options.lines) {
+            const ranges = await collectAgentRanges(git, repoRoot, record, files);
+            for (const [file, fileRanges] of ranges) {
+                const perAgent = rangesByFile.get(file) ?? new Map();
+                perAgent.set(record.name, fileRanges);
+                rangesByFile.set(file, perAgent);
+            }
+        }
+    }
+    const multiAgent = [...agentsByFile.entries()]
+        .filter(([, names]) => names.length > 1)
+        .map(([file, names]) => ({ file, agents: [...names].sort() }))
+        .sort((a, b) => a.file.localeCompare(b.file));
+    let collisions;
+    let disjoint;
+    if (options.lines) {
+        collisions = [];
+        disjoint = [];
+        for (const { file, agents: names } of multiAgent) {
+            const perAgent = rangesByFile.get(file);
+            // An agent with no parsed ranges has no net change vs merge-base.
+            const entries = names.map((n) => perAgent?.get(n) ?? []);
+            const overlap = rangesOverlap(entries);
+            if (overlap === 'whole') {
+                collisions.push({ file, agents: names, overlap: 'whole-file' });
+            }
+            else if (overlap.length > 0) {
+                collisions.push({ file, agents: names, overlap: formatRanges(overlap) });
+            }
+            else {
+                disjoint.push({ file, agents: names });
+            }
+        }
+    }
+    else {
+        collisions = multiAgent;
+    }
+    const result = { collisions, agentsChecked: agents.length };
+    if (disjoint !== undefined)
+        result.disjoint = disjoint;
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    if (collisions.length === 0) {
+        console.log(ok(`No collisions across ${agents.length} agents.`));
+    }
+    else {
+        console.log(fail(`${plural(collisions.length, 'collision risk')} detected:`));
+        console.log(options.lines
+            ? table(['FILE', 'AGENTS', 'LINES'], collisions.map((c) => [c.file, c.agents.join(', '), c.overlap ?? '']))
+            : table(['FILE', 'AGENTS'], collisions.map((c) => [c.file, c.agents.join(', ')])));
+        console.log(dim(options.lines
+            ? 'Line ranges are relative to the merge base — exact when the agents share a base, a heuristic otherwise.'
+            : 'These files are touched by more than one agent (committed or uncommitted). ' +
+                'Coordinate before merging.'));
+    }
+    if (disjoint && disjoint.length > 0) {
+        console.log(dim(`${plural(disjoint.length, 'shared file')} with disjoint line edits (not counted as collisions):`));
+        for (const d of disjoint) {
+            console.log(dim(`  ${d.file} (${d.agents.join(', ')})`));
+        }
+    }
+    return result;
+}
+/**
+ * Edited line ranges for every file an agent touched, in merge-base
+ * coordinates: one `git diff -U0 <merge-base>` run inside the worktree covers
+ * committed and uncommitted work at once; untracked files (and anything else
+ * whose lines can't be resolved) are marked 'whole'.
+ */
+async function collectAgentRanges(git, repoRoot, record, files) {
+    const abs = worktreeAbsPath(repoRoot, record);
+    const worktreeExists = existsSync(abs);
+    const branchesExist = (await branchExists(git, record.branch)) && (await branchExists(git, record.baseBranch));
+    if (!branchesExist) {
+        // No merge base to anchor line numbers to — fall back to whole-file.
+        return new Map([...files].map((f) => [f, 'whole']));
+    }
+    const mergeBase = (await git.raw(['merge-base', record.baseBranch, record.branch])).trim();
+    const diffText = worktreeExists
+        ? await gitAt(abs).raw(['diff', '-U0', '--no-color', mergeBase])
+        : await git.raw(['diff', '-U0', '--no-color', mergeBase, record.branch]);
+    const ranges = parseUnifiedDiff(diffText);
+    if (worktreeExists) {
+        for (const f of await uncommittedFiles(abs)) {
+            // Untracked files never appear in `git diff`; both agents adding the
+            // same new file is a real collision, so mark them whole-file.
+            if (f.status === '??')
+                ranges.set(f.path, 'whole');
+        }
+    }
+    return ranges;
+}

package/dist/commands/clean.js

@@ -0,0 +1,133 @@
+import { existsSync } from 'node:fs';
+import { FleetError } from '../lib/errors.js';
+import { dim, ok, plural } from '../lib/format.js';
+import { branchExists, deleteBranch, getMainRepoRoot, gitAt, isMergedInto, lastCommitISO, pruneWorktrees, removeWorktree, uncommittedFiles, } from '../lib/git.js';
+import { readState, worktreeAbsPath, writeState } from '../lib/state.js';
+/**
+ * Remove agents whose branches are fully merged into their base — worktree,
+ * branch, and state entry. Never touches unmerged work or dirty worktrees.
+ */
+export async function clean(options = {}) {
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const git = gitAt(repoRoot);
+    const state = readState(repoRoot);
+    const agents = Object.values(state.agents).sort((a, b) => a.name.localeCompare(b.name));
+    const dryRun = options.dryRun ?? false;
+    if (options.stale !== undefined && (!Number.isFinite(options.stale) || options.stale <= 0)) {
+        throw new FleetError('Invalid --stale. Pass a positive number of days, e.g. --stale 14.');
+    }
+    if (agents.length === 0) {
+        console.log('Nothing to clean: no active agents.');
+        return { cleaned: [], kept: [] };
+    }
+    const cleaned = [];
+    const kept = [];
+    for (const record of agents) {
+        const abs = worktreeAbsPath(repoRoot, record);
+        if (!(await branchExists(git, record.branch))) {
+            // Branch was deleted outside Switchyard; only the stale state entry is left.
+            cleaned.push({
+                name: record.name,
+                branch: record.branch,
+                baseBranch: record.baseBranch,
+                reason: 'branch-missing',
+            });
+            if (!dryRun) {
+                await pruneWorktrees(git);
+                delete state.agents[record.name];
+            }
+            continue;
+        }
+        if (!(await branchExists(git, record.baseBranch))) {
+            kept.push({
+                name: record.name,
+                reason: `base branch "${record.baseBranch}" no longer exists`,
+            });
+            continue;
+        }
+        if (!(await isMergedInto(git, record.branch, record.baseBranch))) {
+            // Unmerged agents are never cleaned by default; --stale removes their
+            // worktree and state entry after long inactivity, but keeps the branch
+            // so the work stays recoverable.
+            if (options.stale !== undefined) {
+                const dirty = existsSync(abs) ? await uncommittedFiles(abs) : [];
+                if (dirty.length > 0) {
+                    kept.push({
+                        name: record.name,
+                        reason: `stale check skipped: ${plural(dirty.length, 'uncommitted change')}`,
+                    });
+                    continue;
+                }
+                const last = await lastCommitISO(git, record.branch);
+                const ageDays = last
+                    ? (Date.now() - new Date(last).getTime()) / (24 * 60 * 60 * 1000)
+                    : Number.POSITIVE_INFINITY;
+                if (ageDays > options.stale) {
+                    cleaned.push({
+                        name: record.name,
+                        branch: record.branch,
+                        baseBranch: record.baseBranch,
+                        reason: 'stale',
+                    });
+                    if (!dryRun) {
+                        if (existsSync(abs)) {
+                            await removeWorktree(git, abs, false);
+                        }
+                        else {
+                            await pruneWorktrees(git);
+                        }
+                        delete state.agents[record.name];
+                    }
+                    continue;
+                }
+            }
+            kept.push({ name: record.name, reason: `has unmerged commits vs ${record.baseBranch}` });
+            continue;
+        }
+        const dirty = existsSync(abs) ? await uncommittedFiles(abs) : [];
+        if (dirty.length > 0) {
+            kept.push({ name: record.name, reason: plural(dirty.length, 'uncommitted change') });
+            continue;
+        }
+        cleaned.push({
+            name: record.name,
+            branch: record.branch,
+            baseBranch: record.baseBranch,
+            reason: 'merged',
+        });
+        if (!dryRun) {
+            if (existsSync(abs)) {
+                await removeWorktree(git, abs, false);
+            }
+            else {
+                await pruneWorktrees(git);
+            }
+            // Merged into base was verified above; -D avoids `git branch -d`'s
+            // stricter merged-into-HEAD check, which depends on the current branch.
+            await deleteBranch(git, record.branch, true);
+            delete state.agents[record.name];
+        }
+    }
+    if (!dryRun) {
+        writeState(repoRoot, state);
+    }
+    const verb = dryRun ? 'Would clean' : 'Cleaned';
+    if (cleaned.length === 0) {
+        console.log(ok('Nothing to clean: no fully merged agents.'));
+    }
+    else {
+        console.log(ok(`${verb} ${plural(cleaned.length, 'agent')}:`));
+        for (const c of cleaned) {
+            const why = c.reason === 'merged'
+                ? `merged into ${c.baseBranch}`
+                : c.reason === 'stale'
+                    ? `stale ${options.stale}+ days — worktree removed, branch kept`
+                    : 'branch already deleted';
+            console.log(`  ${c.name} ${dim(`(${c.branch} — ${why})`)}`);
+        }
+    }
+    for (const k of kept) {
+        console.log(dim(`  kept ${k.name}: ${k.reason}`));
+    }
+    return { cleaned, kept };
+}