@switchyardhq/git-fleet 0.1.0

package/dist/commands/completion.js

@@ -0,0 +1,126 @@
+import { FleetError } from '../lib/errors.js';
+import { getMainRepoRoot } from '../lib/git.js';
+import { readState } from '../lib/state.js';
+const SHELLS = ['bash', 'zsh', 'fish'];
+/** command name -> short description (kept apostrophe-free for shell quoting). */
+const COMMANDS = [
+    ['spawn', 'create an isolated worktree + branch for an agent'],
+    ['list', 'show all active agents'],
+    ['status', 'detailed view of one agent'],
+    ['check', 'flag files touched by more than one agent'],
+    ['diff', 'diff an agent branch against its base'],
+    ['sync', 'catch an agent branch up with its base'],
+    ['exec', 'run a command inside an agent worktree'],
+    ['merge', 'merge an agent branch into the current branch and clean up'],
+    ['pr', 'push an agent branch and open a pull request via gh'],
+    ['remove', 'remove an agent worktree'],
+    ['clean', 'remove fully merged agents'],
+    ['watch', 'live-updating agent table'],
+    ['doctor', 'diagnose and repair state drift'],
+    ['completion', 'output a shell completion script'],
+];
+/** Commands whose first argument is an agent name. */
+const AGENT_COMMANDS = ['status', 'diff', 'sync', 'exec', 'merge', 'pr', 'remove'];
+const SNAPSHOT_NOTE = 'Agent names below are a snapshot of .fleet/state.json at generation time,\n' +
+    '# not dynamic — re-run `fleet completion <shell>` after spawning or removing\n' +
+    '# agents to refresh them.';
+/**
+ * Print a completion script for the given shell, covering command names and
+ * the agent names currently registered in `.fleet/state.json`.
+ */
+export async function completion(shell, options = {}) {
+    if (!SHELLS.includes(shell)) {
+        throw new FleetError(`Unsupported shell "${shell}". Supported: ${SHELLS.join(', ')}.`);
+    }
+    // Outside a repo (or with no agents) the script still works; the agent-name
+    // list is just empty.
+    let agents = [];
+    try {
+        const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+        agents = Object.keys(readState(repoRoot).agents).sort();
+    }
+    catch {
+        agents = [];
+    }
+    let script;
+    switch (shell) {
+        case 'bash':
+            script = bashScript(agents);
+            break;
+        case 'zsh':
+            script = zshScript(agents);
+            break;
+        case 'fish':
+            script = fishScript(agents);
+            break;
+    }
+    console.log(script);
+    return script;
+}
+function bashScript(agents) {
+    const commands = COMMANDS.map(([name]) => name).join(' ');
+    return `# fleet completion (bash) — source this file or add to ~/.bashrc:
+#   eval "$(fleet completion bash)"
+# ${SNAPSHOT_NOTE}
+_fleet_completions() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  local commands="${commands}"
+  local agents="${agents.join(' ')}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+    return
+  fi
+  case "$prev" in
+    ${AGENT_COMMANDS.join('|')})
+      COMPREPLY=( $(compgen -W "$agents" -- "$cur") )
+      ;;
+    completion)
+      COMPREPLY=( $(compgen -W "${SHELLS.join(' ')}" -- "$cur") )
+      ;;
+    *)
+      COMPREPLY=()
+      ;;
+  esac
+}
+complete -F _fleet_completions fleet`;
+}
+function zshScript(agents) {
+    const commandLines = COMMANDS.map(([name, desc]) => `    '${name}:${desc}'`).join('\n');
+    return `#compdef fleet
+# fleet completion (zsh) — write to a file on your $fpath, e.g.:
+#   fleet completion zsh > ~/.zsh/completions/_fleet
+# ${SNAPSHOT_NOTE}
+_fleet() {
+  local -a commands agents
+  commands=(
+${commandLines}
+  )
+  agents=(${agents.join(' ')})
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+  case "\${words[2]}" in
+    ${AGENT_COMMANDS.join('|')})
+      _describe 'agent' agents
+      ;;
+    completion)
+      _values 'shell' ${SHELLS.join(' ')}
+      ;;
+  esac
+}
+_fleet "$@"`;
+}
+function fishScript(agents) {
+    const commandLines = COMMANDS.map(([name, desc]) => `complete -c fleet -n '__fish_use_subcommand' -a ${name} -d '${desc}'`).join('\n');
+    const agentCondition = `__fish_seen_subcommand_from ${AGENT_COMMANDS.join(' ')}`;
+    return `# fleet completion (fish) — write to ~/.config/fish/completions/fleet.fish:
+#   fleet completion fish > ~/.config/fish/completions/fleet.fish
+# ${SNAPSHOT_NOTE}
+complete -c fleet -f
+${commandLines}
+complete -c fleet -n '${agentCondition}' -a '${agents.join(' ')}'
+complete -c fleet -n '__fish_seen_subcommand_from completion' -a '${SHELLS.join(' ')}'`;
+}

package/dist/commands/diff.js

@@ -0,0 +1,35 @@
+import { FleetError } from '../lib/errors.js';
+import { dim } from '../lib/format.js';
+import { branchExists, defaultBaseBranch, getMainRepoRoot, gitAt, verifyBranch } from '../lib/git.js';
+import { readState } from '../lib/state.js';
+export async function diff(name, options = {}) {
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const git = gitAt(repoRoot);
+    const state = readState(repoRoot);
+    // Also works for fleet/* branches that exist but aren't in state (e.g. the
+    // state file was deleted): fall back to main/master as the base.
+    const record = state.agents[name];
+    const branch = record?.branch ?? `fleet/${name}`;
+    if (!(await branchExists(git, branch))) {
+        if (record) {
+            throw new FleetError(`Agent "${name}" is tracked but its branch "${branch}" no longer exists.\n` +
+                `Run \`fleet remove ${name}\` to clean up the stale entry.`);
+        }
+        throw new FleetError(`No agent named "${name}" and no branch "${branch}" exists. ` +
+            'Run `fleet list` to see active agents.');
+    }
+    const base = options.base ?? record?.baseBranch ?? (await defaultBaseBranch(git));
+    await verifyBranch(git, base, 'Base');
+    const args = ['diff'];
+    if (process.stdout.isTTY)
+        args.push('--color=always');
+    args.push(`${base}...${branch}`);
+    const patch = await git.raw(args);
+    if (patch.trim().length === 0) {
+        console.log(dim(`No committed changes on ${branch} vs ${base}.`));
+    }
+    else {
+        console.log(patch.trimEnd());
+    }
+    return { branch, base, patch };
+}

package/dist/commands/doctor.js

@@ -0,0 +1,248 @@
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { simpleGit } from 'simple-git';
+import { dim, fail, ok, warn } from '../lib/format.js';
+import { currentBranch, defaultBaseBranch, getMainRepoRoot, gitAt, pruneWorktrees, } from '../lib/git.js';
+import { readState, worktreeAbsPath, worktreesDir, writeState } from '../lib/state.js';
+/** Minimum git version Switchyard needs (`--path-format=absolute` support). */
+export const MIN_GIT = { major: 2, minor: 31 };
+/**
+ * Diagnose (and with --fix, repair) drift between `.fleet/state.json` and
+ * reality: corrupted state, orphaned worktrees, stale entries. Repairs are
+ * re-derived from actual `git worktree list` output, never guessed.
+ */
+export async function doctor(options = {}) {
+    const fix = options.fix ?? false;
+    const checks = [];
+    checks.push(await checkGitVersion());
+    let repoRoot;
+    try {
+        repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+        checks.push({ name: 'repository', ok: true, detail: `inside a git repository (${repoRoot})`, fixed: false });
+    }
+    catch {
+        checks.push({
+            name: 'repository',
+            ok: false,
+            detail: 'not inside a git repository — run fleet from within the repo it should manage',
+            fixed: false,
+        });
+        return finish(checks, options.json ?? false);
+    }
+    const git = gitAt(repoRoot);
+    const worktrees = await listGitWorktrees(git);
+    const fleetWorktrees = worktrees.filter((w) => isUnder(w.path, worktreesDir(repoRoot)) && w.branch !== null && w.branch.startsWith('fleet/'));
+    // --- state file -----------------------------------------------------------
+    let state = null;
+    let stateModified = false;
+    try {
+        state = readState(repoRoot);
+        checks.push({
+            name: 'state-file',
+            ok: true,
+            detail: `.fleet/state.json is valid (${Object.keys(state.agents).length} agents)`,
+            fixed: false,
+        });
+    }
+    catch {
+        if (fix) {
+            state = { version: 1, agents: {} };
+            for (const w of fleetWorktrees) {
+                const record = await adoptRecord(git, repoRoot, w.path, w.branch);
+                state.agents[record.name] = record;
+            }
+            stateModified = true;
+            checks.push({
+                name: 'state-file',
+                ok: false,
+                detail: `.fleet/state.json was corrupted — rebuilt from \`git worktree list\` (${Object.keys(state.agents).length} agents re-adopted; base branches and timestamps are re-derived, not original)`,
+                fixed: true,
+            });
+        }
+        else {
+            checks.push({
+                name: 'state-file',
+                ok: false,
+                detail: '.fleet/state.json is corrupted (not valid JSON / wrong shape) — run `fleet doctor --fix` to rebuild it from `git worktree list`',
+                fixed: false,
+            });
+        }
+    }
+    if (state === null) {
+        // Without a readable state the remaining cross-checks are meaningless.
+        checks.push({
+            name: 'orphaned-worktrees',
+            ok: false,
+            detail: 'skipped: state file unreadable',
+            fixed: false,
+        });
+        checks.push({
+            name: 'stale-entries',
+            ok: false,
+            detail: 'skipped: state file unreadable',
+            fixed: false,
+        });
+        return finish(checks, options.json ?? false);
+    }
+    // --- orphaned worktrees (on disk, not in state) ----------------------------
+    const trackedPaths = Object.values(state.agents).map((r) => worktreeAbsPath(repoRoot, r));
+    const orphanDetails = [];
+    let orphanCount = 0;
+    let orphansFixed = 0;
+    const wtDir = worktreesDir(repoRoot);
+    const entries = existsSync(wtDir) ? readdirSync(wtDir, { withFileTypes: true }) : [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const abs = path.join(wtDir, entry.name);
+        if (trackedPaths.some((p) => samePath(p, abs)))
+            continue;
+        orphanCount += 1;
+        const registered = worktrees.find((w) => samePath(w.path, abs));
+        if (registered && registered.branch !== null && registered.branch.startsWith('fleet/')) {
+            if (fix) {
+                const record = await adoptRecord(git, repoRoot, abs, registered.branch);
+                state.agents[record.name] = record;
+                stateModified = true;
+                orphansFixed += 1;
+                orphanDetails.push(`${entry.name}: adopted (branch ${registered.branch})`);
+            }
+            else {
+                orphanDetails.push(`${entry.name}: valid fleet worktree not in state — --fix will adopt it`);
+            }
+        }
+        else if (registered) {
+            // A real worktree, but not on a fleet/* branch — not Switchyard's to manage.
+            orphanDetails.push(`${entry.name}: worktree on branch ${registered.branch ?? '(detached)'} — not a fleet/* branch; remove it yourself with \`git worktree remove\``);
+        }
+        else {
+            if (fix) {
+                rmSync(abs, { recursive: true, force: true });
+                orphansFixed += 1;
+                orphanDetails.push(`${entry.name}: not a git worktree — directory removed`);
+            }
+            else {
+                orphanDetails.push(`${entry.name}: not a git worktree (leftover directory) — --fix will remove it`);
+            }
+        }
+    }
+    checks.push({
+        name: 'orphaned-worktrees',
+        ok: orphanCount === 0,
+        detail: orphanCount === 0
+            ? 'no untracked directories in .fleet/worktrees/'
+            : orphanDetails.join('; '),
+        fixed: orphanCount > 0 && orphansFixed === orphanCount,
+    });
+    // --- stale state entries (in state, gone on disk) --------------------------
+    const staleNames = Object.values(state.agents)
+        .filter((r) => !existsSync(worktreeAbsPath(repoRoot, r)))
+        .map((r) => r.name);
+    if (staleNames.length > 0 && fix) {
+        for (const name of staleNames) {
+            delete state.agents[name];
+        }
+        await pruneWorktrees(git);
+        stateModified = true;
+    }
+    checks.push({
+        name: 'stale-entries',
+        ok: staleNames.length === 0,
+        detail: staleNames.length === 0
+            ? 'every state entry has a worktree on disk'
+            : `worktree directory missing for: ${staleNames.join(', ')}` +
+                (fix ? ' — entries pruned (branches kept)' : ' — --fix will prune the entries (branches are kept)'),
+        fixed: staleNames.length > 0 && fix,
+    });
+    if (fix && stateModified) {
+        writeState(repoRoot, state);
+    }
+    return finish(checks, options.json ?? false);
+}
+function finish(checks, json) {
+    const healthy = checks.every((c) => c.ok || c.fixed);
+    if (json) {
+        console.log(JSON.stringify({ checks, healthy }, null, 2));
+        return { checks, healthy };
+    }
+    for (const c of checks) {
+        const mark = c.ok ? ok('ok    ') : c.fixed ? warn('fixed ') : fail('fail  ');
+        console.log(`${mark} ${c.name.padEnd(20)} ${c.detail}`);
+    }
+    console.log('');
+    if (healthy) {
+        console.log(ok('No problems found.') + (checks.some((c) => c.fixed) ? dim(' (after fixes)') : ''));
+    }
+    else {
+        console.log(fail('Problems found.') + dim(' Re-run with --fix to repair what can be repaired.'));
+    }
+    return { checks, healthy };
+}
+async function checkGitVersion() {
+    const version = await simpleGit().version();
+    if (!version.installed) {
+        return { name: 'git-version', ok: false, detail: 'git is not installed or not on PATH', fixed: false };
+    }
+    const okVersion = version.major > MIN_GIT.major ||
+        (version.major === MIN_GIT.major && version.minor >= MIN_GIT.minor);
+    return {
+        name: 'git-version',
+        ok: okVersion,
+        detail: okVersion
+            ? `git ${version.major}.${version.minor} (minimum ${MIN_GIT.major}.${MIN_GIT.minor})`
+            : `git ${version.major}.${version.minor} is older than the required ${MIN_GIT.major}.${MIN_GIT.minor} — upgrade git`,
+        fixed: false,
+    };
+}
+/** Parse `git worktree list --porcelain` into path/branch pairs. */
+async function listGitWorktrees(git) {
+    const out = await git.raw(['worktree', 'list', '--porcelain']);
+    const result = [];
+    let current = null;
+    for (const line of out.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('worktree ')) {
+            if (current)
+                result.push(current);
+            current = { path: path.resolve(trimmed.slice('worktree '.length)), branch: null };
+        }
+        else if (trimmed.startsWith('branch refs/heads/') && current) {
+            current.branch = trimmed.slice('branch refs/heads/'.length);
+        }
+        else if (trimmed === '' && current) {
+            result.push(current);
+            current = null;
+        }
+    }
+    if (current)
+        result.push(current);
+    return result;
+}
+/** Build a state record for an existing worktree found via `git worktree list`. */
+async function adoptRecord(git, repoRoot, worktreeAbs, branch) {
+    return {
+        name: path.basename(worktreeAbs),
+        branch,
+        baseBranch: await fallbackBase(git),
+        worktreePath: path.relative(repoRoot, worktreeAbs).split(path.sep).join('/'),
+        createdAt: new Date().toISOString(),
+    };
+}
+/** Best guess at a base branch when the original one is unknowable. */
+async function fallbackBase(git) {
+    try {
+        return await defaultBaseBranch(git);
+    }
+    catch {
+        return (await currentBranch(git)) ?? 'main';
+    }
+}
+function samePath(a, b) {
+    const ra = path.resolve(a);
+    const rb = path.resolve(b);
+    return process.platform === 'win32' ? ra.toLowerCase() === rb.toLowerCase() : ra === rb;
+}
+function isUnder(child, parent) {
+    const rel = path.relative(path.resolve(parent), path.resolve(child));
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}

package/dist/commands/exec.js

@@ -0,0 +1,53 @@
+import { existsSync } from 'node:fs';
+import { FleetError } from '../lib/errors.js';
+import { dim, fail, warn } from '../lib/format.js';
+import { getMainRepoRoot } from '../lib/git.js';
+import { runShell, shellJoin } from '../lib/proc.js';
+import { getAgent, readState, worktreeAbsPath } from '../lib/state.js';
+/**
+ * Run a shell command inside an agent's worktree (or every worktree with
+ * --all) without cd'ing there — `fleet exec claude -- npm test`. Under --all
+ * the runs are sequential so their output doesn't interleave.
+ */
+export async function exec(agentName, cmdTokens, options = {}) {
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const state = readState(repoRoot);
+    if (cmdTokens.length === 0) {
+        throw new FleetError('No command given. Usage: fleet exec <agent> -- <command...>');
+    }
+    let targets;
+    if (options.all) {
+        targets = Object.values(state.agents).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    else {
+        if (!agentName) {
+            throw new FleetError('Pass an agent name (or --all to run in every worktree).');
+        }
+        targets = [getAgent(state, agentName)];
+    }
+    const command = shellJoin(cmdTokens);
+    if (targets.length === 0) {
+        console.log('No active agents. Run `fleet spawn <name>` to create one.');
+        return { command, outcomes: [], ok: true };
+    }
+    const outcomes = [];
+    for (const record of targets) {
+        const abs = worktreeAbsPath(repoRoot, record);
+        if (!existsSync(abs)) {
+            if (!options.all) {
+                throw new FleetError(`Agent "${record.name}" has no worktree on disk (${abs}).\n` +
+                    'Run `fleet doctor --fix` to reconcile state, or `fleet remove` the agent.');
+            }
+            console.log(warn(`[${record.name}] skipped: worktree missing`));
+            outcomes.push({ name: record.name, exitCode: null, skipped: 'worktree-missing' });
+            continue;
+        }
+        console.log(dim(`[${record.name}] $ ${command}`));
+        const exitCode = await runShell(command, abs);
+        outcomes.push({ name: record.name, exitCode });
+        if (exitCode !== 0) {
+            console.log(fail(`[${record.name}] exited ${exitCode}`));
+        }
+    }
+    return { command, outcomes, ok: outcomes.every((o) => o.exitCode === 0) };
+}

package/dist/commands/list.js

@@ -0,0 +1,86 @@
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { dim, relativeTime, table, warn } from '../lib/format.js';
+import { aheadBehind, branchExists, getMainRepoRoot, gitAt, lastCommitISO, uncommittedFiles, } from '../lib/git.js';
+import { readState, worktreeAbsPath } from '../lib/state.js';
+/** Gather the per-agent data `fleet list` displays, without printing anything. */
+export async function collectListings(options = {}) {
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const state = readState(repoRoot);
+    const agents = Object.values(state.agents).sort((a, b) => a.name.localeCompare(b.name));
+    // Each agent needs several independent, read-only git calls; running the
+    // agents concurrently keeps `fleet list` (and every `fleet watch` frame)
+    // fast as the fleet grows. Output order mirrors the sorted agents.
+    return Promise.all(agents.map((record) => describeAgent(repoRoot, record)));
+}
+/** Render listings as the `fleet list` table. Shared with `fleet watch`. */
+export function buildListTable(listings) {
+    const rows = listings.map((l) => [
+        l.name,
+        l.branch,
+        l.baseBranch,
+        l.ahead === null ? '?' : `+${l.ahead}/-${l.behind}`,
+        l.worktreeMissing
+            ? warn('worktree missing')
+            : l.uncommitted === 0
+                ? dim('clean')
+                : warn(`${l.uncommitted} uncommitted`),
+        relativeTime(l.lastActivity),
+        l.worktreePath,
+    ]);
+    return table(['AGENT', 'BRANCH', 'BASE', '+/-', 'CHANGES', 'LAST ACTIVITY', 'WORKTREE'], rows);
+}
+export async function list(options = {}) {
+    const listings = await collectListings(options);
+    if (options.json) {
+        console.log(JSON.stringify(listings, null, 2));
+        return listings;
+    }
+    if (listings.length === 0) {
+        console.log('No active agents. Run `fleet spawn <name>` to create one.');
+        return [];
+    }
+    console.log(buildListTable(listings));
+    return listings;
+}
+async function describeAgent(repoRoot, record) {
+    const git = gitAt(repoRoot);
+    const abs = worktreeAbsPath(repoRoot, record);
+    const worktreeMissing = !existsSync(abs);
+    let ahead = null;
+    let behind = null;
+    if ((await branchExists(git, record.branch)) && (await branchExists(git, record.baseBranch))) {
+        ({ ahead, behind } = await aheadBehind(git, record.baseBranch, record.branch));
+    }
+    let uncommitted = 0;
+    let lastActivity = await lastCommitISO(git, record.branch);
+    if (!worktreeMissing) {
+        const files = await uncommittedFiles(abs);
+        uncommitted = files.length;
+        // Uncommitted edits postdate the last commit; use the newest file mtime.
+        let newest = lastActivity ? new Date(lastActivity).getTime() : 0;
+        for (const f of files) {
+            try {
+                const mtime = statSync(path.join(abs, f.path)).mtimeMs;
+                if (mtime > newest)
+                    newest = mtime;
+            }
+            catch {
+                // Deleted or renamed while we looked — skip it.
+            }
+        }
+        if (newest > 0)
+            lastActivity = new Date(newest).toISOString();
+    }
+    return {
+        name: record.name,
+        branch: record.branch,
+        baseBranch: record.baseBranch,
+        worktreePath: record.worktreePath,
+        worktreeMissing,
+        ahead,
+        behind,
+        uncommitted,
+        lastActivity,
+    };
+}

package/dist/commands/merge.js

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import { readConfig } from '../lib/config.js';
+import { FleetError } from '../lib/errors.js';
+import { dim, ok, plural, warn } from '../lib/format.js';
+import { currentBranch, deleteBranch, getMainRepoRoot, gitAt, pruneWorktrees, removeWorktree, uncommittedFiles, verifyBranch, } from '../lib/git.js';
+import { runShell } from '../lib/proc.js';
+import { getAgent, readState, worktreeAbsPath, writeState } from '../lib/state.js';
+import { check } from './check.js';
+import { clean } from './clean.js';
+/**
+ * Merge an agent's branch into the main worktree's current branch, guarded by
+ * a collision check, and clean up the agent on success. Never leaves the repo
+ * mid-merge: a conflicted merge is aborted before the error is reported.
+ */
+export async function merge(name, options = {}) {
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const git = gitAt(repoRoot);
+    const state = readState(repoRoot);
+    const config = readConfig(repoRoot);
+    const record = getAgent(state, name);
+    await verifyBranch(git, record.branch, 'Agent');
+    const doClean = options.clean ?? true;
+    if (options.deleteBranch && !doClean) {
+        throw new FleetError('--delete-branch and --no-clean contradict each other; pick one.');
+    }
+    const into = await currentBranch(git);
+    if (!into) {
+        throw new FleetError('HEAD is detached in the main worktree. Check out the branch you want to merge into first.');
+    }
+    const mainStatus = await git.status();
+    if (mainStatus.conflicted.length > 0) {
+        throw new FleetError(`The main worktree already has an unresolved merge (${plural(mainStatus.conflicted.length, 'conflicted file')}). Resolve or abort it first.`);
+    }
+    // Collision gate: refuse while another still-active agent touches the same
+    // files. Reuses `fleet check` (which prints its table) rather than a second
+    // implementation of the cross-reference.
+    if (Object.keys(state.agents).length >= 2) {
+        const { collisions } = await check({ cwd: repoRoot });
+        const blocking = collisions.filter((c) => c.agents.includes(name));
+        if (blocking.length > 0) {
+            const lines = blocking
+                .map((c) => `  ${c.file} (${c.agents.filter((a) => a !== name).join(', ')})`)
+                .join('\n');
+            throw new FleetError(`Refusing to merge "${name}": ${plural(blocking.length, 'file is', 'files are')} also touched by other active agents:\n` +
+                `${lines}\n` +
+                'Merge or remove those agents first (or resolve the overlap), then re-run.');
+        }
+    }
+    // preMerge hook: e.g. "npm test" in the agent's worktree. Runs after the
+    // collision gate and before the merge starts, so a failure aborts cleanly.
+    if (config.preMerge) {
+        const hookDir = worktreeAbsPath(repoRoot, record);
+        if (existsSync(hookDir)) {
+            console.log(dim(`preMerge: ${config.preMerge}`));
+            const exitCode = await runShell(config.preMerge, hookDir);
+            if (exitCode !== 0) {
+                throw new FleetError(`preMerge hook failed (exit ${exitCode}): ${config.preMerge}\n` +
+                    `The merge was not started — ${into} is unchanged.`);
+            }
+        }
+        else {
+            console.log(warn(`preMerge hook skipped: worktree missing (${hookDir})`));
+        }
+    }
+    try {
+        await git.merge([record.branch]);
+    }
+    catch (err) {
+        const status = await git.status();
+        if (status.conflicted.length > 0) {
+            // Never leave the repo mid-merge: abort before reporting.
+            await git.raw(['merge', '--abort']);
+            throw new FleetError(`Merging ${record.branch} into ${into} conflicts in ${plural(status.conflicted.length, 'file')}:\n` +
+                status.conflicted.map((f) => `  ${f}`).join('\n') +
+                `\nThe merge was aborted — ${into} is unchanged. Resolve manually with \`git merge ${record.branch}\` when ready.`);
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new FleetError(`git merge failed before starting: ${message}`);
+    }
+    console.log(ok(`Merged ${record.branch} into ${into}.`));
+    let cleaned = false;
+    let branchDeleted = false;
+    if (!doClean) {
+        console.log(dim(`  --no-clean: worktree and ${record.branch} kept. Run \`fleet remove ${name} --delete-branch\` later.`));
+    }
+    else {
+        const abs = worktreeAbsPath(repoRoot, record);
+        const dirty = existsSync(abs) ? await uncommittedFiles(abs) : [];
+        if (dirty.length > 0) {
+            // The merge itself succeeded; don't fail it, and never discard work.
+            console.log(warn(`  worktree kept: ${plural(dirty.length, 'uncommitted change')} in ${abs}`));
+            console.log(dim(`  commit them, or run \`fleet remove ${name} --force\` to discard; ${record.branch} kept.`));
+        }
+        else {
+            if (existsSync(abs)) {
+                await removeWorktree(git, abs, false);
+            }
+            else {
+                await pruneWorktrees(git);
+            }
+            // Safe force-delete: the branch was just merged into `into`.
+            await deleteBranch(git, record.branch, true);
+            delete state.agents[name];
+            writeState(repoRoot, state);
+            cleaned = true;
+            branchDeleted = true;
+            console.log(`  removed worktree and deleted ${record.branch}`);
+        }
+    }
+    let autoCleaned = [];
+    if (config.autoClean && doClean) {
+        const swept = await clean({ cwd: repoRoot });
+        autoCleaned = swept.cleaned.map((c) => c.name);
+    }
+    return { branch: record.branch, into, cleaned, branchDeleted, autoCleaned };
+}