chapterhouse 0.2.0 → 0.3.1

package/README.md

@@ -239,8 +239,31 @@ The deployment assets for the shared instance set Entra auth and `CHAPTERHOUSE_M
 | `chapterhouse update --check-only` | Print current/latest version without updating                    |
 | `chapterhouse update --ref <ver>`  | Install a specific version                                       |
 | `chapterhouse daemon <sub>`    | Manage the persistent background service          |
+| `chapterhouse squad worktree <sub>` | Manage per-agent git worktrees for concurrent squad work |
 | `chapterhouse help`            | Show available commands                           |
 
+### Squad Worktree Commands
+
+Squad agents that work on GitHub issues each get a dedicated git worktree so they never step on each other. The `chapterhouse squad worktree` subcommands manage these worktrees:
+
+```sh
+chapterhouse squad worktree create <agent> <issue> [--base main] [--slug <slug>]
+    # Creates .worktrees/{agent}-{issue}/ and branch squad/{issue}-{slug}
+    # Prints the worktree path to stdout. Reuses existing worktree if present.
+
+chapterhouse squad worktree list
+    # Shows all active squad worktrees: agent, issue, branch, status, path
+
+chapterhouse squad worktree remove <agent> <issue> [--force] [--delete-branch]
+    # Removes a worktree. Refuses if dirty unless --force is passed.
+
+chapterhouse squad worktree prune [--base main] [--dry-run]
+    # Removes all worktrees whose branch has been merged into main.
+    # Skips dirty worktrees with a warning.
+```
+
+**How it works:** Worktrees live at `.worktrees/{agent}-{issue}/` inside the repo (gitignored). The Squad coordinator creates each worktree *before* spawning an agent and passes the path as `WORKTREE_PATH` in the spawn prompt. Agents do all their work—reads, edits, commits—inside that path. No agent ever runs `git checkout` in a working tree it doesn't own.
+
 ### Flags
 
 | Flag          | Description                                                                      |
@@ -284,6 +307,29 @@ chapterhouse daemon uninstall # stop, disable, and remove the unit file
 | macOS    | `~/Library/Logs/chapterhouse.log`                           |
 | Linux    | `journalctl --user -u chapterhouse` (no extra config needed) |
 
+#### Timing contract
+
+Chapterhouse enforces a **3-layer timing contract** so in-flight LLM streams can finish cleanly before the process is killed:
+
+| Layer | What it controls | Config | Default |
+|-------|-----------------|--------|---------|
+| 1 — Orchestrator turn | How long the orchestrator waits per LLM turn | `CHAPTERHOUSE_ORCHESTRATOR_TIMEOUT_MS` | `1800000` (30 min) |
+| 2 — Daemon shutdown grace | How long the daemon waits for in-flight work before force-exiting | `CHAPTERHOUSE_SHUTDOWN_TIMEOUT_MS` | `60000` (60 s) |
+| 3 — systemd kill window | How long systemd waits after SIGTERM before sending SIGKILL | `TimeoutStopSec` in generated unit | `90 s` (fixed) |
+
+**Rule:** each layer must exceed the one above it. Do not tighten `CHAPTERHOUSE_SHUTDOWN_TIMEOUT_MS` below `CHAPTERHOUSE_ORCHESTRATOR_TIMEOUT_MS`, and do not reduce `TimeoutStopSec` below `CHAPTERHOUSE_SHUTDOWN_TIMEOUT_MS`.
+
+#### Daemon PATH
+
+The generated systemd unit and launchd plist compose a rich `PATH` that includes:
+- The installing shell's `$PATH` (captured at install time)
+- The binary's own directory
+- Linuxbrew (`/home/linuxbrew/.linuxbrew/bin`), Homebrew (`/opt/homebrew/bin`, `/usr/local/bin`)
+- `~/.cargo/bin`, `~/.bun/bin`, `~/.volta/bin`, `~/.local/bin`
+- Standard system paths
+
+This ensures sub-agents and spawned tools can find CLI dependencies even in a headless service context.
+
 ## Web UI
 
 The browser app at `http://localhost:7788` is split into a few views:
@@ -428,3 +474,13 @@ git push origin main --follow-tags
 ```
 
 `npm version` handles the commit and tag automatically. `prepublishOnly` runs `npm run build` before publish so the tarball always contains a fresh build. If you don't have CI set up, publish manually with `npm publish` after the tag push.
+
+> **Pre-release gate:** `preversion` runs `npm run release:check` automatically before any `npm version` call. The script aborts with a clear error if the git working tree is dirty. Stash or commit all changes (including `.squad/` metadata edits) before bumping the version.
+
+### Commit message convention
+
+All commits on this repository follow **[Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)**. The format is `<type>(<scope>): <subject>` (e.g. `feat(api): add session export endpoint`). Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `build`, `ci`, `revert`, `release`.
+
+This is automatically enforced:
+- **Locally:** `husky` installs a `commit-msg` git hook on `npm install` that runs `commitlint` against every commit message. Bad messages are rejected before the commit lands.
+- **On PRs:** A GitHub Action (`lint-pr-title.yml`) validates the PR title on every open/edit. This matters because squash-merges use the PR title as the commit message on `main`.

package/dist/cli.js

@@ -25,6 +25,7 @@ Commands:
   setup            Pick a default model and write ~/.chapterhouse/.env
   update           Check for updates and install the latest version
   daemon <sub>     Manage the persistent background service (install/uninstall/start/stop/restart/status/logs)
+  squad <sub>      Squad agent tools (worktree management)
   help             Show this help message
 
 Flags (start):
@@ -178,6 +179,29 @@ switch (command) {
         }
         break;
     }
+    case "squad": {
+        const squadSub = args[1];
+        if (squadSub === 'worktree') {
+            const { runWorktreeCli, printWorktreeHelp } = await import("./squad/worktree.js");
+            await runWorktreeCli(args.slice(2));
+        }
+        else {
+            if (squadSub) {
+                console.error(`Unknown squad subcommand: ${squadSub}\n`);
+            }
+            console.log(`
+chapterhouse squad — Squad agent tools
+
+Subcommands:
+  worktree   Manage per-agent git worktrees (create / list / remove / prune)
+
+Run \`chapterhouse squad worktree\` for worktree subcommand help.
+`.trim());
+            if (squadSub)
+                process.exit(1);
+        }
+        break;
+    }
     case "help":
     case "--help":
     case "-h":

package/dist/copilot/orchestrator.js

@@ -315,8 +315,19 @@ export async function initOrchestrator(client) {
         log.error({ err: err instanceof Error ? err.message : err }, "Failed to create initial session (will retry on first message)");
     }
 }
-/** How long to wait for the orchestrator to finish a turn (10 min). */
-const ORCHESTRATOR_TIMEOUT_MS = 600_000;
+/** How long to wait for the orchestrator to finish a turn (30 min default).
+ *  Override with CHAPTERHOUSE_ORCHESTRATOR_TIMEOUT_MS env var (parsed as integer ms).
+ *  Part of the 3-layer timing contract — see systemd unit TimeoutStopSec comment. */
+const DEFAULT_ORCHESTRATOR_TIMEOUT_MS = 1_800_000;
+export const ORCHESTRATOR_TIMEOUT_MS = (() => {
+    const env = process.env.CHAPTERHOUSE_ORCHESTRATOR_TIMEOUT_MS;
+    if (env) {
+        const parsed = parseInt(env, 10);
+        if (!isNaN(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_ORCHESTRATOR_TIMEOUT_MS;
+})();
 /** Send a prompt on a session identified by sessionKey, return the response. */
 async function executeOnSession(sessionKey, prompt, callback, attachments, onActivity) {
     const projectRoot = sessionKey.startsWith("project:") ? sessionKey.slice("project:".length) : undefined;

package/dist/copilot/orchestrator.test.js

@@ -619,7 +619,7 @@ test("S5-01: subagent.failed event updates agent_tasks status to error", async (
         toolCallId: "subagent-call-003",
         agentName: "Zoe",
         agentDisplayName: "Zoe — QA",
-        error: "Timeout after 600s",
+        error: "Timeout after 1800s",
     });
     const errorWrite = state.dbWrites.find((w) => w.sql.includes("UPDATE") && w.sql.includes("agent_tasks") && w.sql.includes("error"));
     assert.ok(errorWrite, "subagent.failed must UPDATE agent_tasks to error status");

package/dist/daemon-install.js

@@ -53,9 +53,35 @@ export function resolveChapterhouseBin() {
         return argv1;
     return "chapterhouse";
 }
+/**
+ * Compose a rich PATH for launchd-spawned children (macOS).
+ * Prepends the installing shell's $PATH so any tool already on the user's PATH
+ * is available to sub-agents, then adds Homebrew and language-toolchain dirs.
+ */
+function composeMacOSPath(binDir, shellPath) {
+    const home = homedir();
+    return [
+        shellPath,
+        binDir,
+        "/opt/homebrew/bin",
+        "/usr/local/bin",
+        `${home}/.cargo/bin`,
+        `${home}/.bun/bin`,
+        `${home}/.volta/bin`,
+        `${home}/.local/bin`,
+        "/usr/bin",
+        "/bin",
+        "/usr/sbin",
+        "/sbin",
+    ]
+        .filter(Boolean)
+        .join(":");
+}
 /** Generate the launchd plist XML string. */
 export function generatePlist(options) {
     const label = options.label ?? DAEMON_LABEL;
+    const shellPath = options.shellPath ?? process.env.PATH ?? "";
+    const richPath = composeMacOSPath(dirname(options.binPath), shellPath);
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -78,16 +104,39 @@ export function generatePlist(options) {
     <key>EnvironmentVariables</key>
     <dict>
         <key>PATH</key>
-        <string>${dirname(options.binPath)}:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <string>${richPath}</string>
     </dict>
 </dict>
 </plist>
 `;
 }
+/**
+ * Compose a rich PATH for systemd-spawned children (Linux).
+ * Uses systemd's %h specifier for the home directory so the unit stays portable
+ * across uid changes. Prepends the installing shell's $PATH for robustness.
+ */
+function composeSystemdPath(binDir, shellPath) {
+    return [
+        shellPath,
+        binDir,
+        "/home/linuxbrew/.linuxbrew/bin",
+        "%h/.cargo/bin",
+        "%h/.bun/bin",
+        "%h/.volta/bin",
+        "%h/.local/bin",
+        "/opt/homebrew/bin",
+        "/usr/local/bin",
+        "/usr/bin",
+        "/bin",
+    ]
+        .filter(Boolean)
+        .join(":");
+}
 /** Generate the systemd user unit file string. */
 export function generateSystemdUnit(options) {
     const description = options.description ?? "Chapterhouse AI assistant daemon";
-    const pathDir = dirname(options.binPath);
+    const shellPath = options.shellPath ?? process.env.PATH ?? "";
+    const richPath = composeSystemdPath(dirname(options.binPath), shellPath);
     return `[Unit]
 Description=${description}
 After=network.target
@@ -97,7 +146,17 @@ Type=simple
 ExecStart=${options.binPath} start
 Restart=on-failure
 RestartSec=5s
-Environment="PATH=${pathDir}:/usr/local/bin:/usr/bin:/bin"
+# Rich PATH ensures spawned sub-agents and tools can find CLI dependencies
+# (Linuxbrew, Homebrew, Cargo, Bun, Volta). %h is expanded to $HOME by systemd.
+Environment="PATH=${richPath}"
+# ── Timing contract (three layers) ─────────────────────────────────────────────
+# Layer 1 │ Orchestrator turn timeout  │ CHAPTERHOUSE_ORCHESTRATOR_TIMEOUT_MS (default 1800 s)
+# Layer 2 │ Daemon graceful shutdown   │ CHAPTERHOUSE_SHUTDOWN_TIMEOUT_MS     (default 60 s)
+# Layer 3 │ systemd force-kill window  │ TimeoutStopSec = 90 s (must exceed layer 2)
+# Each layer must exceed the one above it. Do NOT tighten TimeoutStopSec without
+# first reducing CHAPTERHOUSE_SHUTDOWN_TIMEOUT_MS, or in-flight LLM streams will
+# be killed mid-response.
+TimeoutStopSec=90
 
 [Install]
 WantedBy=default.target

package/dist/daemon-install.test.js

@@ -41,6 +41,23 @@ test("generatePlist includes bin directory in PATH environment", () => {
     const plist = generatePlist({ binPath: MOCK_BIN_DARWIN, logPath: MOCK_LOG_DARWIN });
     assert.ok(plist.includes(dirname(MOCK_BIN_DARWIN)), "plist PATH should include bin directory");
 });
+test("generatePlist PATH includes Homebrew and toolchain directories", () => {
+    const plist = generatePlist({ binPath: MOCK_BIN_DARWIN, logPath: MOCK_LOG_DARWIN, shellPath: "" });
+    const home = homedir();
+    assert.ok(plist.includes("/opt/homebrew/bin"), "plist PATH should include /opt/homebrew/bin");
+    assert.ok(plist.includes(`${home}/.cargo/bin`), "plist PATH should include ~/.cargo/bin");
+    assert.ok(plist.includes(`${home}/.bun/bin`), "plist PATH should include ~/.bun/bin");
+    assert.ok(plist.includes(`${home}/.volta/bin`), "plist PATH should include ~/.volta/bin");
+    assert.ok(plist.includes(`${home}/.local/bin`), "plist PATH should include ~/.local/bin");
+});
+test("generatePlist PATH prepends installing shell PATH", () => {
+    const shellPath = "/custom/shell/bin:/another/dir";
+    const plist = generatePlist({ binPath: MOCK_BIN_DARWIN, logPath: MOCK_LOG_DARWIN, shellPath });
+    assert.ok(plist.includes(shellPath), "plist PATH should include the installing shell PATH");
+    const pathStart = plist.indexOf(shellPath);
+    const binDirStart = plist.indexOf(dirname(MOCK_BIN_DARWIN), plist.indexOf("<key>PATH</key>"));
+    assert.ok(pathStart < binDirStart, "shell PATH should appear before bin dir in composed PATH");
+});
 test("generatePlist respects a custom label override", () => {
     const customLabel = "com.example.test";
     const plist = generatePlist({ binPath: MOCK_BIN_DARWIN, logPath: MOCK_LOG_DARWIN, label: customLabel });
@@ -78,6 +95,24 @@ test("generateSystemdUnit includes bin directory in PATH", () => {
     const unit = generateSystemdUnit({ binPath: MOCK_BIN_LINUX });
     assert.ok(unit.includes(dirname(MOCK_BIN_LINUX)), "unit PATH should include bin directory");
 });
+test("generateSystemdUnit PATH includes Linuxbrew and toolchain directories", () => {
+    const unit = generateSystemdUnit({ binPath: MOCK_BIN_LINUX, shellPath: "" });
+    assert.ok(unit.includes("/home/linuxbrew/.linuxbrew/bin"), "unit PATH should include Linuxbrew");
+    assert.ok(unit.includes("%h/.cargo/bin"), "unit PATH should include %h/.cargo/bin");
+    assert.ok(unit.includes("%h/.bun/bin"), "unit PATH should include %h/.bun/bin");
+    assert.ok(unit.includes("%h/.volta/bin"), "unit PATH should include %h/.volta/bin");
+    assert.ok(unit.includes("%h/.local/bin"), "unit PATH should include %h/.local/bin");
+    assert.ok(unit.includes("/opt/homebrew/bin"), "unit PATH should include /opt/homebrew/bin");
+});
+test("generateSystemdUnit PATH prepends installing shell PATH", () => {
+    const shellPath = "/custom/shell/bin";
+    const unit = generateSystemdUnit({ binPath: MOCK_BIN_LINUX, shellPath });
+    assert.ok(unit.includes(shellPath), "unit PATH should include the installing shell PATH");
+});
+test("generateSystemdUnit includes TimeoutStopSec=90", () => {
+    const unit = generateSystemdUnit({ binPath: MOCK_BIN_LINUX });
+    assert.ok(unit.includes("TimeoutStopSec=90"), "unit should set TimeoutStopSec=90 for timing contract");
+});
 test("generateSystemdUnit has all three sections", () => {
     const unit = generateSystemdUnit({ binPath: MOCK_BIN_LINUX });
     assert.ok(unit.includes("[Unit]"), "unit should have [Unit] section");

package/dist/daemon.js

@@ -19,6 +19,23 @@ import { registerShutdownSignals } from "./shutdown-signals.js";
 import { logger } from "./util/logger.js";
 const log = logger.child({ module: "daemon" });
 const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * How long the daemon waits for in-flight work to finish before forcing an exit.
+ * Layer 2 of the 3-layer timing contract:
+ *   Layer 1 — orchestrator turn: CHAPTERHOUSE_ORCHESTRATOR_TIMEOUT_MS (default 1800 s)
+ *   Layer 2 — daemon shutdown:   CHAPTERHOUSE_SHUTDOWN_TIMEOUT_MS     (default 60 s) ← this
+ *   Layer 3 — systemd kill:      TimeoutStopSec=90 s (must exceed layer 2)
+ * Allows in-flight LLM streams to complete before the process is torn down.
+ */
+const SHUTDOWN_TIMEOUT_MS = (() => {
+    const env = process.env.CHAPTERHOUSE_SHUTDOWN_TIMEOUT_MS;
+    if (env) {
+        const parsed = parseInt(env, 10);
+        if (!isNaN(parsed) && parsed > 0)
+            return parsed;
+    }
+    return 60_000;
+})();
 /** Remove orphaned session folders older than 7 days, preserving the current session. */
 function pruneOldSessions() {
     try {
@@ -165,11 +182,11 @@ async function shutdown() {
     }
     shutdownState = "shutting_down";
     log.info("Shutting down (Ctrl+C again to force)");
-    // Force exit after 3 seconds no matter what
+    // Force exit after the configured grace period no matter what
     const forceTimer = setTimeout(() => {
         log.warn("Shutdown timed out — forcing exit");
         process.exit(1);
-    }, 3000);
+    }, SHUTDOWN_TIMEOUT_MS);
     forceTimer.unref();
     // Destroy all active agent sessions
     await shutdownAgents();

package/dist/squad/index.js

@@ -4,4 +4,5 @@ export * from './registry.js';
 export * from './context.js';
 export * from './charter.js';
 export * from './mirror.js';
+export * from './worktree.js';
 //# sourceMappingURL=index.js.map

package/dist/squad/worktree.js

@@ -0,0 +1,295 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+// ---------------------------------------------------------------------------
+// Path convention
+// ---------------------------------------------------------------------------
+/**
+ * Location: `.worktrees/{agent}-{issueNum}/` inside the repo root.
+ * This keeps worktrees discoverable (they're adjacent to the code) and
+ * `git worktree list` always surfaces them. The directory is gitignored.
+ *
+ * Tradeoff vs `~/.cache/chapterhouse-worktrees/<repo>/`:
+ *   + Visible without knowing a cache path
+ *   + `chapterhouse squad worktree list` doesn't need to guess the home
+ *   - Must be added to .gitignore (done once, documented here)
+ */
+export function getWorktreePath(repoRoot, agent, issueNum) {
+    return join(repoRoot, '.worktrees', `${agent}-${issueNum}`);
+}
+export function getBranchName(issueNum, slug) {
+    const safeslug = slug ? `-${slug.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')}` : '';
+    return `squad/${issueNum}${safeslug}`;
+}
+// ---------------------------------------------------------------------------
+// Git helpers
+// ---------------------------------------------------------------------------
+function git(args, cwd) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf-8' });
+    return {
+        ok: result.status === 0,
+        stdout: (result.stdout ?? '').trim(),
+        stderr: (result.stderr ?? '').trim(),
+    };
+}
+function hasUncommittedChanges(worktreePath) {
+    const r = git(['status', '--porcelain'], worktreePath);
+    return r.ok && r.stdout.length > 0;
+}
+function isBranchMerged(repoRoot, branch, base = 'main') {
+    // merged if branch tip is reachable from base
+    const r = git(['branch', '--merged', base, '--list', branch], repoRoot);
+    return r.ok && r.stdout.length > 0;
+}
+function getRepoRoot(cwd) {
+    const r = git(['rev-parse', '--show-toplevel'], cwd);
+    if (!r.ok)
+        throw new Error(`Not inside a git repo: ${r.stderr}`);
+    return r.stdout;
+}
+/**
+ * Create a dedicated worktree for an agent + issue pair.
+ * Branch: `squad/{issueNum}-{agent}` (off `main` by default).
+ * Returns the worktree path.
+ */
+export function createWorktree(repoRoot, agent, issueNum, opts = {}) {
+    const baseBranch = opts.baseBranch ?? 'main';
+    const branch = getBranchName(issueNum, opts.slug ?? agent);
+    const worktreePath = getWorktreePath(repoRoot, agent, issueNum);
+    if (existsSync(worktreePath)) {
+        // Reuse existing worktree
+        console.log(`↩  Reusing existing worktree: ${relative(repoRoot, worktreePath)}`);
+        return worktreePath;
+    }
+    // Check if branch already exists (another agent on same issue)
+    const branchExists = git(['show-ref', '--verify', `refs/heads/${branch}`], repoRoot);
+    let result;
+    if (branchExists.ok) {
+        result = git(['worktree', 'add', worktreePath, branch], repoRoot);
+    }
+    else {
+        result = git(['worktree', 'add', '-b', branch, worktreePath, baseBranch], repoRoot);
+    }
+    if (!result.ok) {
+        throw new Error(`Failed to create worktree: ${result.stderr}`);
+    }
+    console.log(`✅ Worktree created: ${relative(repoRoot, worktreePath)} (branch: ${branch})`);
+    return worktreePath;
+}
+/**
+ * List all squad worktrees (worktrees under `.worktrees/` with `squad/` branches).
+ */
+export function listWorktrees(repoRoot) {
+    const r = git(['worktree', 'list', '--porcelain'], repoRoot);
+    if (!r.ok)
+        throw new Error(`git worktree list failed: ${r.stderr}`);
+    const entries = parseWorktreePorcelain(r.stdout);
+    const squadEntries = entries.filter(e => e.path.includes('/.worktrees/'));
+    return squadEntries.map(e => {
+        const dirName = e.path.split('/.worktrees/')[1] ?? '';
+        const match = dirName.match(/^([^-]+)-(\d+)/);
+        const agent = match ? match[1] : dirName;
+        const issueNum = match ? match[2] : '?';
+        const dirty = existsSync(e.path) && hasUncommittedChanges(e.path);
+        return {
+            agent,
+            issueNum,
+            path: e.path,
+            branch: e.branch ?? '(detached)',
+            exists: existsSync(e.path),
+            dirty,
+            head: e.head ?? '',
+        };
+    });
+}
+/**
+ * Remove a specific worktree. Warns but refuses if the worktree has
+ * uncommitted changes (pass `force: true` to override).
+ */
+export function removeWorktree(repoRoot, agent, issueNum, opts = {}) {
+    const worktreePath = getWorktreePath(repoRoot, agent, issueNum);
+    if (!existsSync(worktreePath)) {
+        console.log(`ℹ  Worktree not found: ${worktreePath} (nothing to remove)`);
+        return;
+    }
+    if (!opts.force && hasUncommittedChanges(worktreePath)) {
+        console.error(`⚠  Worktree ${relative(repoRoot, worktreePath)} has uncommitted changes.\n` +
+            `   Commit or stash your work before removing, or pass --force to discard.`);
+        process.exitCode = 1;
+        return;
+    }
+    const removeArgs = ['worktree', 'remove', worktreePath];
+    if (opts.force)
+        removeArgs.push('--force');
+    const r = git(removeArgs, repoRoot);
+    if (!r.ok)
+        throw new Error(`Failed to remove worktree: ${r.stderr}`);
+    if (opts.deleteBranch) {
+        const branch = getBranchName(issueNum, agent);
+        const del = git(['branch', '-d', branch], repoRoot);
+        if (!del.ok) {
+            console.warn(`⚠  Could not delete branch ${branch}: ${del.stderr}`);
+        }
+    }
+    console.log(`🗑  Removed worktree: ${relative(repoRoot, worktreePath)}`);
+}
+/**
+ * Remove all squad worktrees whose branch has been merged into `main`.
+ * Warns and skips worktrees with uncommitted changes.
+ */
+export function pruneWorktrees(repoRoot, opts = {}) {
+    const base = opts.base ?? 'main';
+    const worktrees = listWorktrees(repoRoot);
+    if (worktrees.length === 0) {
+        console.log('ℹ  No squad worktrees found.');
+        return;
+    }
+    for (const wt of worktrees) {
+        const merged = isBranchMerged(repoRoot, wt.branch, base);
+        if (!merged) {
+            console.log(`↷  Skipping ${wt.agent}-${wt.issueNum} (branch not merged into ${base})`);
+            continue;
+        }
+        if (wt.dirty) {
+            console.warn(`⚠  Skipping ${wt.agent}-${wt.issueNum} (has uncommitted changes — clean up manually)`);
+            continue;
+        }
+        if (opts.dryRun) {
+            console.log(`[dry-run] Would remove: ${wt.agent}-${wt.issueNum} (branch: ${wt.branch})`);
+            continue;
+        }
+        removeWorktree(repoRoot, wt.agent, Number(wt.issueNum), { deleteBranch: true });
+    }
+}
+// ---------------------------------------------------------------------------
+// Print helpers
+// ---------------------------------------------------------------------------
+export function printWorktreeList(repoRoot) {
+    const worktrees = listWorktrees(repoRoot);
+    if (worktrees.length === 0) {
+        console.log('No squad worktrees found.');
+        return;
+    }
+    const header = ['AGENT', 'ISSUE', 'BRANCH', 'STATUS', 'PATH'];
+    const rows = worktrees.map(wt => [
+        wt.agent,
+        wt.issueNum,
+        wt.branch,
+        wt.dirty ? '⚠ dirty' : '✓ clean',
+        wt.path,
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map(r => r[i].length)));
+    const fmt = (cols) => cols.map((c, i) => c.padEnd(widths[i])).join('  ');
+    console.log(fmt(header));
+    console.log(widths.map(w => '-'.repeat(w)).join('  '));
+    for (const row of rows)
+        console.log(fmt(row));
+}
+export function printWorktreeHelp() {
+    console.log(`
+chapterhouse squad worktree — manage per-agent git worktrees
+
+Usage:
+  chapterhouse squad worktree <subcommand>
+
+Subcommands:
+  create <agent> <issue> [--base <branch>] [--slug <slug>]
+      Create a dedicated worktree for an agent + issue.
+      Path: .worktrees/{agent}-{issue}/   Branch: squad/{issue}-{agent}
+
+  list
+      List all squad worktrees with agent, branch, and status.
+
+  remove <agent> <issue> [--force] [--delete-branch]
+      Remove a worktree. Refuses if there are uncommitted changes
+      unless --force is passed (which discards the changes).
+
+  prune [--base <branch>] [--dry-run]
+      Remove all worktrees whose branch has been merged into main
+      (or the specified --base branch). Skips dirty worktrees.
+`.trim());
+}
+function parseWorktreePorcelain(output) {
+    const entries = [];
+    let current = null;
+    for (const line of output.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            if (current?.path)
+                entries.push(current);
+            current = { path: line.slice('worktree '.length) };
+        }
+        else if (line.startsWith('HEAD ') && current) {
+            current.head = line.slice('HEAD '.length);
+        }
+        else if (line.startsWith('branch ') && current) {
+            current.branch = line.slice('branch refs/heads/'.length);
+        }
+        else if (line === '' && current?.path) {
+            entries.push(current);
+            current = null;
+        }
+    }
+    if (current?.path)
+        entries.push(current);
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+export async function runWorktreeCli(args) {
+    let repoRoot;
+    try {
+        repoRoot = getRepoRoot(process.cwd());
+    }
+    catch {
+        console.error('❌ Not inside a git repository.');
+        process.exit(1);
+    }
+    const subcommand = args[0];
+    switch (subcommand) {
+        case 'create': {
+            const agent = args[1];
+            const issueNum = args[2];
+            if (!agent || !issueNum) {
+                console.error('Usage: chapterhouse squad worktree create <agent> <issue> [--base <branch>] [--slug <slug>]');
+                process.exit(1);
+            }
+            const baseIdx = args.indexOf('--base');
+            const baseBranch = baseIdx !== -1 ? args[baseIdx + 1] : undefined;
+            const slugIdx = args.indexOf('--slug');
+            const slug = slugIdx !== -1 ? args[slugIdx + 1] : undefined;
+            const path = createWorktree(repoRoot, agent, issueNum, { baseBranch, slug });
+            console.log(path);
+            break;
+        }
+        case 'list':
+            printWorktreeList(repoRoot);
+            break;
+        case 'remove': {
+            const agent = args[1];
+            const issueNum = args[2];
+            if (!agent || !issueNum) {
+                console.error('Usage: chapterhouse squad worktree remove <agent> <issue> [--force] [--delete-branch]');
+                process.exit(1);
+            }
+            removeWorktree(repoRoot, agent, issueNum, {
+                force: args.includes('--force'),
+                deleteBranch: args.includes('--delete-branch'),
+            });
+            break;
+        }
+        case 'prune': {
+            const baseIdx = args.indexOf('--base');
+            const base = baseIdx !== -1 ? args[baseIdx + 1] : undefined;
+            pruneWorktrees(repoRoot, { base, dryRun: args.includes('--dry-run') });
+            break;
+        }
+        default:
+            if (subcommand)
+                console.error(`Unknown worktree subcommand: ${subcommand}\n`);
+            printWorktreeHelp();
+            if (subcommand)
+                process.exit(1);
+    }
+}
+//# sourceMappingURL=worktree.js.map