chapterhouse 0.1.5 → 0.3.0

package/README.md

@@ -14,14 +14,16 @@ Chapterhouse is built on [Max](https://github.com/burkeholland/max) by [Burke Ho
 - **Learns any skill** — pulls from [skills.sh](https://skills.sh) or builds new skills on demand.
 - **Your Copilot subscription** — works with any model your subscription includes (Claude, GPT, Gemini, …). Auto-routing picks a tier per message.
 
+See [CHANGELOG.md](CHANGELOG.md) for recent changes and feature history.
+
 ## Installation
 
-**Requires Node.js 22.5 or later.**
+**Requires Node.js 24 or later** (npm ≥ 11.5.1 for Trusted Publishing support).
 
 Install globally via npm:
 
 ```bash
-npm install -g chapterhouse
+npm install -g chapterhouse@latest
 ```
 
 After installing, run first-time setup:
@@ -57,6 +59,12 @@ ENABLE_SQUAD=1                            # set to 1 to enable squad agent routi
 
 # Optional — periodic decisions→wiki sync (requires ENABLE_SQUAD=1)
 CHAPTERHOUSE_DECISIONS_SYNC_INTERVAL_MS=300000  # default 5 minutes (300 000 ms)
+
+# Optional — logging
+LOG_LEVEL=info   # trace | debug | info | warn | error | fatal | silent (default: info)
+                 # Set to "debug" to see chat message content and routing decisions.
+                 # Logs are structured JSON (Pino). For human-readable output:
+                 #   chapterhouse start 2>&1 | npx pino-pretty
 ```
 
 Then start the daemon:
@@ -91,13 +99,33 @@ npm install && npm run build && npm link
 
 ## Upgrading
 
-If you already have Chapterhouse installed:
-
 ```bash
 chapterhouse update
 ```
 
-Or manually: `cd ~/.chapterhouse/src && git pull && npm install && npm run build`. Your `~/.chapterhouse/` config carries forward automatically.
+`chapterhouse update` is npm-registry-aware. It detects how Chapterhouse was installed and routes accordingly:
+
+| Install source | Update action |
+| -------------- | ------------- |
+| **npm global** (`npm install -g chapterhouse`) | Runs `npm install -g chapterhouse@latest` |
+| **git/legacy** (`~/.chapterhouse/src`) | Git pull + rebuild (with deprecation notice) |
+| **dev** (source working tree) | No-op — use `git pull` manually |
+
+### Update flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--check-only` | Print current/latest version and exit without updating |
+| `--ref <version>` | Install a specific version, e.g. `--ref 0.1.5` |
+| `--force` | Bypass the Node 24 / npm 11.5.1 precondition check |
+
+**Legacy users:** if you previously installed via git clone, switch to the registry path once:
+
+```bash
+npm install -g chapterhouse@latest
+```
+
+Your `~/.chapterhouse/` config carries forward automatically.
 
 ## Quick Start
 
@@ -202,13 +230,39 @@ The deployment assets for the shared instance set Entra auth and `CHAPTERHOUSE_M
 
 ## CLI Commands
 
-| Command                     | Description                                       |
-| --------------------------- | ------------------------------------------------- |
-| `chapterhouse start`        | Start the Chapterhouse daemon (web UI + HTTP API) |
-| `chapterhouse start --open` | Same, plus open the browser                       |
-| `chapterhouse setup`        | Interactive first-run configuration               |
-| `chapterhouse update`       | Check for and install updates                     |
-| `chapterhouse help`         | Show available commands                           |
+| Command                        | Description                                       |
+| ------------------------------ | ------------------------------------------------- |
+| `chapterhouse start`           | Start the Chapterhouse daemon (web UI + HTTP API) |
+| `chapterhouse start --open`    | Same, plus open the browser                       |
+| `chapterhouse setup`           | Interactive first-run configuration               |
+| `chapterhouse update`              | Check for and install updates (npm registry for global installs) |
+| `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
 
@@ -217,6 +271,42 @@ The deployment assets for the shared instance set Entra auth and `CHAPTERHOUSE_M
 | `--self-edit` | Allow Chapterhouse to modify its own source code (use with `chapterhouse start`) |
 | `--open`      | Open the web UI in your default browser when the daemon is ready                 |
 
+### Daemon Management (macOS / Linux)
+
+Chapterhouse can run as a persistent user-level background service that starts on login and restarts automatically on crash — no root required.
+
+#### Install
+
+```sh
+chapterhouse daemon install
+```
+
+This writes and loads the appropriate unit file for your OS:
+
+| Platform | Unit file                                                               |
+| -------- | ----------------------------------------------------------------------- |
+| macOS    | `~/Library/LaunchAgents/com.bketelsen.chapterhouse.plist` (launchd)     |
+| Linux    | `~/.config/systemd/user/chapterhouse.service` (systemd `--user`)        |
+| Windows  | Not supported — run `chapterhouse start` manually or use Task Scheduler |
+
+#### Manage
+
+```sh
+chapterhouse daemon status    # is it running? what PID? where are the logs?
+chapterhouse daemon stop      # stop without uninstalling
+chapterhouse daemon start     # start without re-installing
+chapterhouse daemon restart   # restart in place
+chapterhouse daemon logs      # tail live logs (Ctrl+C to exit)
+chapterhouse daemon uninstall # stop, disable, and remove the unit file
+```
+
+#### Log locations
+
+| Platform | Location                                                    |
+| -------- | ----------------------------------------------------------- |
+| macOS    | `~/Library/Logs/chapterhouse.log`                           |
+| Linux    | `journalctl --user -u chapterhouse` (no extra config needed) |
+
 ## Web UI
 
 The browser app at `http://localhost:7788` is split into a few views:
@@ -361,3 +451,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/api/errors.js

@@ -1,4 +1,6 @@
 import { ZodError } from "zod";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("api:errors");
 export class HttpError extends Error {
     statusCode;
     expose;
@@ -80,15 +82,15 @@ export function createApiErrorHandler() {
         }
         if (error instanceof HttpError) {
             if (error.statusCode >= 500) {
-                console.error(`[api] ${req.method} ${req.originalUrl} failed:`, error);
+                log.error({ method: req.method, url: req.originalUrl, err: error instanceof Error ? error.message : error }, "API request failed");
             }
             else if (error.statusCode === 401 || error.statusCode === 403) {
-                console.warn(`[api] ${req.method} ${req.originalUrl} denied: ${error.message}`);
+                log.warn({ method: req.method, url: req.originalUrl, err: error.message }, "API request denied");
             }
             res.status(error.statusCode).json({ error: error.expose ? error.message : "Internal server error" });
             return;
         }
-        console.error(`[api] ${req.method} ${req.originalUrl} failed:`, error);
+        log.error({ method: req.method, url: req.originalUrl, err: error instanceof Error ? error.message : error }, "API request failed (unhandled)");
         res.status(500).json({ error: "Internal server error" });
     };
 }

package/dist/api/errors.test.js

@@ -64,26 +64,17 @@ test("api not-found handler returns JSON for unknown API routes", async () => {
 });
 test("centralized error handler hides internal error details", async () => {
     const app = express();
-    const originalConsoleError = console.error;
-    const logged = [];
-    console.error = (...args) => {
-        logged.push(args);
-    };
-    try {
-        app.get("/api/failure", () => {
-            throw new InternalServerError("do not leak", false);
-        });
-        app.use(createApiErrorHandler());
-        await withServer(app, async (baseUrl) => {
-            const response = await fetch(`${baseUrl}/api/failure`);
-            assert.equal(response.status, 500);
-            assert.deepEqual(await response.json(), { error: "Internal server error" });
-        });
-        assert.equal(logged.length, 1);
-        assert.equal(logged[0]?.[0], "[api] GET /api/failure failed:");
-    }
-    finally {
-        console.error = originalConsoleError;
-    }
+    app.get("/api/failure", () => {
+        throw new InternalServerError("do not leak", false);
+    });
+    app.use(createApiErrorHandler());
+    await withServer(app, async (baseUrl) => {
+        const response = await fetch(`${baseUrl}/api/failure`);
+        // Internal details must NOT reach the client
+        assert.equal(response.status, 500);
+        assert.deepEqual(await response.json(), { error: "Internal server error" });
+    });
+    // Logging now goes through pino (structured JSON), not console.error.
+    // The HTTP response contract above is the authoritative check.
 });
 //# sourceMappingURL=errors.test.js.map

package/dist/api/server.js

@@ -19,13 +19,15 @@ import { withWikiWrite } from "../wiki/lock.js";
 import { listSkills, removeSkill } from "../copilot/skills.js";
 import { restartDaemon } from "../daemon.js";
 import { API_TOKEN_PATH, resolveWikiRelativePath } from "../paths.js";
-import { getDb } from "../store/db.js";
+import { getDb, getSessionMessages } from "../store/db.js";
 import { getStatus, onStatusChange } from "../status.js";
 import { formatSseData, formatSseEvent } from "./sse.js";
 import { syncDecisionsFileToWiki } from "../squad/mirror.js";
 import { resolveProjectSquad } from "../squad/discovery.js";
 import { assertAuthenticationConfigured, createHealthPayload, createPublicConfigPayload, buildHistoryEntries, getDisplayHost, resolveApiToken, shouldServeSpaPath, } from "./server-runtime.js";
 import { BadRequestError, ForbiddenError, InternalServerError, NotFoundError, apiNotFoundHandler, asBadRequest, createApiErrorHandler, parseRequest, } from "./errors.js";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("server");
 void searchIndex; // re-exported by index-manager; reference here documents the dep
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Built SPA bundle (web/dist/), shipped alongside dist/
@@ -69,11 +71,11 @@ try {
     });
 }
 catch (err) {
-    console.error(err instanceof Error ? err.message : String(err));
+    log.error({ err: err instanceof Error ? err.message : String(err) }, "Auth token error");
     process.exit(1);
 }
 if (config.standaloneMode) {
-    console.log("[standalone] Running without authentication — team features disabled");
+    log.warn("Running without authentication — team features disabled");
 }
 function isLoopbackHostname(hostname) {
     return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
@@ -402,7 +404,7 @@ app.get("/api/models", async (_req, res) => {
         res.json({ models: models.map((m) => m.id), current: config.copilotModel });
     }
     catch (error) {
-        console.error("[api] Failed to list models:", error);
+        log.error({ err: error instanceof Error ? error.message : error }, "Failed to list models");
         throw new InternalServerError();
     }
 });
@@ -418,7 +420,7 @@ app.get("/api/auto", (_req, res) => {
 app.post("/api/auto", (req, res) => {
     const body = parseRequest(autoRequestSchema, req.body ?? {});
     const updated = updateRouterConfig(body);
-    console.log(`[chapterhouse] Auto-routing ${updated.enabled ? "enabled" : "disabled"}`);
+    log.info({ enabled: updated.enabled }, "Auto-routing updated");
     res.json(updated);
 });
 // ---------------------------------------------------------------------------
@@ -519,7 +521,7 @@ app.post("/api/restart", (_req, res) => {
     res.json({ status: "restarting" });
     setTimeout(() => {
         restartDaemon().catch((err) => {
-            console.error("[chapterhouse] Restart failed:", err);
+            log.error({ err: err instanceof Error ? err.message : err }, "Restart failed");
         });
     }, 500);
 });
@@ -561,10 +563,10 @@ app.get("/api/projects", (_req, res) => {
     }
     const db = getDb();
     const rows = db.prepare(`
-    SELECT project_root, squad_dir, loaded_at
+    SELECT project_root, squad_dir, loaded_at, last_used_at
     FROM project_squads
     WHERE registered = 1
-    ORDER BY loaded_at DESC
+    ORDER BY COALESCE(last_used_at, 0) DESC
   `).all();
     res.json(rows.map((r) => ({
         projectRoot: r.project_root,
@@ -572,6 +574,7 @@ app.get("/api/projects", (_req, res) => {
         // Count from live filesystem — authoritative per Squad SDK rule: repo files win over cache.
         agentCount: countAgentsOnDisk(r.project_root),
         loadedAt: r.loaded_at,
+        lastUsedAt: r.last_used_at != null ? new Date(r.last_used_at).toISOString() : undefined,
     })));
 });
 app.post("/api/projects", async (req, res) => {
@@ -594,15 +597,15 @@ app.post("/api/projects", async (req, res) => {
     // Fire-and-forget: sync decisions.md to the wiki. Non-fatal if it fails.
     syncDecisionsFileToWiki(projectRoot).then(result => {
         if (result) {
-            console.log(`[squad] Synced ${result.entriesSynced} decision entries to wiki for ${projectRoot}`);
+            log.info({ entriesSynced: result.entriesSynced, projectRoot }, "Synced squad decisions to wiki");
         }
     }).catch(err => {
-        console.warn('[squad] syncDecisionsFileToWiki failed during registration (non-fatal):', err instanceof Error ? err.message : err);
+        log.warn({ err: err instanceof Error ? err.message : err }, "syncDecisionsFileToWiki failed during registration (non-fatal)");
     });
     // Fire-and-forget: populate squad_agents cache from disk so future queries have
     // something to work with (non-fatal — GET /api/projects counts live from disk anyway).
     resolveProjectSquad(projectRoot).catch(err => {
-        console.warn('[squad] resolveProjectSquad failed during registration (non-fatal):', err instanceof Error ? err.message : err);
+        log.warn({ err: err instanceof Error ? err.message : err }, "resolveProjectSquad failed during registration (non-fatal)");
     });
     res.status(201).json({ projectRoot, message: "Project registered successfully" });
 });
@@ -622,6 +625,24 @@ app.delete("/api/projects/:projectRoot", (req, res) => {
     db.prepare(`DELETE FROM squad_agents WHERE project_root = ?`).run(projectRoot);
     res.json({ message: "Project removed" });
 });
+// ---------------------------------------------------------------------------
+// Session messages — frontend rehydration on reload
+// ---------------------------------------------------------------------------
+app.get("/api/session/:sessionKey/messages", (req, res) => {
+    const sessionKey = Array.isArray(req.params.sessionKey)
+        ? req.params.sessionKey[0]
+        : req.params.sessionKey;
+    if (!sessionKey) {
+        throw new BadRequestError("Missing sessionKey");
+    }
+    const rawLimit = req.query.limit;
+    const limit = rawLimit !== undefined ? parseInt(String(rawLimit), 10) : undefined;
+    if (limit !== undefined && (!Number.isFinite(limit) || limit < 1)) {
+        throw new BadRequestError("'limit' must be a positive integer");
+    }
+    const messages = getSessionMessages(sessionKey, limit);
+    res.json({ sessionKey, messages });
+});
 app.use(apiNotFoundHandler);
 // ---------------------------------------------------------------------------
 // Static SPA + fallback. Mounted last so API routes win.
@@ -654,7 +675,7 @@ app.use(createApiErrorHandler());
 export function startApiServer() {
     return new Promise((resolve, reject) => {
         const server = app.listen(config.apiPort, config.apiHost, () => {
-            console.log(`[chapterhouse] HTTP API + web UI listening on http://${getDisplayHost(config.apiHost)}:${config.apiPort}`);
+            log.info({ host: getDisplayHost(config.apiHost), port: config.apiPort }, "HTTP API + web UI listening");
             resolve();
         });
         server.on("error", (err) => {

package/dist/cli.js

@@ -21,19 +21,31 @@ Usage:
   chapterhouse <command>
 
 Commands:
-  start       Start the Chapterhouse daemon (web UI at http://localhost:7788)
-  setup       Pick a default model and write ~/.chapterhouse/.env
-  update      Check for updates and install the latest version
-  help        Show this help message
+  start            Start the Chapterhouse daemon (web UI at http://localhost:7788)
+  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):
   --self-edit Allow Chapterhouse to modify his own source code (off by default)
   --open      Open the web UI in your default browser once the daemon is ready
 
+Flags (update):
+  --check-only      Print version info and install-source, then exit without updating
+  --ref <version>   Install a specific version (e.g. --ref 0.1.5)
+  --force           Bypass the Node/npm version precondition check
+
 Examples:
   chapterhouse start              Start the daemon, then open http://localhost:7788
   chapterhouse start --open       Same, but open the browser for you
   chapterhouse start --self-edit  Start with self-edit enabled
+  chapterhouse update             Update to latest (npm registry for global installs)
+  chapterhouse update --check-only  Show current/latest version without updating
+  chapterhouse update --ref 0.1.5   Install a specific version
+  chapterhouse daemon install     Install and enable the persistent background service
+  chapterhouse daemon status      Show whether the service is running
 `.trim());
 }
 const args = process.argv.slice(2);
@@ -54,30 +66,77 @@ switch (command) {
         await import("./setup.js");
         break;
     case "update": {
-        const { checkForUpdate, performUpdate } = await import("./update.js");
+        const updateFlags = args.slice(1);
+        const checkOnly = updateFlags.includes("--check-only");
+        const force = updateFlags.includes("--force");
+        const refIdx = updateFlags.indexOf("--ref");
+        const ref = refIdx !== -1 ? (updateFlags[refIdx + 1] ?? null) : null;
+        const { checkForUpdate, performUpdate, detectInstallSource, checkPreconditions, buildLegacyGitInstallCommand, } = await import("./update.js");
+        const source = detectInstallSource();
+        // Precondition check (bypass with --force)
+        if (!force) {
+            const pre = checkPreconditions();
+            if (!pre.ok) {
+                console.warn(`⚠  ${pre.message}`);
+                console.warn("   Run with --force to proceed anyway.");
+                process.exit(1);
+            }
+        }
         const check = await checkForUpdate();
         if (!check.checkSucceeded) {
-            console.error("⚠ Could not reach GitHub to check for updates. Check your network and try again.");
+            console.error("⚠ Could not reach npm registry or GitHub to check for updates. Check your network and try again.");
             process.exit(1);
         }
-        if (!check.updateAvailable) {
-            console.log(`chapterhouse v${check.current} is already the latest version.`);
-            console.log("Pulling latest from main...");
-            const result = await performUpdate();
-            if (result.ok) {
-                console.log("✅ Updated to latest main.");
+        console.log(`chapterhouse current: v${check.current}`);
+        console.log(`chapterhouse latest:  v${check.latest ?? "unknown"}`);
+        console.log(`Install source:       ${source}`);
+        if (checkOnly) {
+            if (check.updateAvailable) {
+                console.log(`\nUpdate available: v${check.current} → v${check.latest}`);
+                console.log(`Run \`chapterhouse update\` to install.`);
             }
             else {
-                console.error(`❌ Update failed: ${result.output}`);
-                process.exit(1);
+                console.log("\nYou are on the latest version.");
             }
             break;
         }
-        console.log(`Update available: v${check.current} → v${check.latest}`);
-        console.log("Installing...");
-        const result = await performUpdate(check.latest ? `v${check.latest}` : null);
+        if (source === "dev") {
+            console.log("ℹ Dev mode — use git pull manually.");
+            break;
+        }
+        if (source === "git") {
+            console.warn("⚠  Deprecation notice: your install uses the legacy git clone path.");
+            console.warn(`   Switch to the npm registry path for automatic updates:`);
+            console.warn(`     npm install -g chapterhouse@latest`);
+            console.warn("   Continuing with legacy git update...\n");
+        }
+        const targetRef = ref ?? (check.latest ? check.latest : null);
+        if (!check.updateAvailable && !ref) {
+            console.log(`chapterhouse v${check.current} is already the latest version.`);
+            if (source !== "git")
+                break;
+            // For git installs, still offer to pull latest main
+            console.log("Pulling latest from main...");
+        }
+        else if (check.updateAvailable) {
+            console.log(`\nUpdate available: v${check.current} → v${check.latest}`);
+            console.log("Installing...");
+        }
+        else {
+            console.log(`Installing specified ref: ${targetRef}`);
+        }
+        const result = await performUpdate(targetRef);
         if (result.ok) {
-            console.log(`✅ Updated to v${check.latest}`);
+            if (result.source === "dev") {
+                console.log("ℹ Dev mode — use git pull manually.");
+            }
+            else {
+                const label = ref ? `${ref}` : `v${check.latest ?? "latest"}`;
+                console.log(`✅ Updated to ${label}`);
+                if (result.source === "registry" || result.source === "unknown") {
+                    console.log("   To verify provenance: npm audit signatures (in any project that has chapterhouse as a dep)");
+                }
+            }
         }
         else {
             console.error(`❌ Update failed: ${result.output}`);
@@ -85,6 +144,64 @@ switch (command) {
         }
         break;
     }
+    case "daemon": {
+        const subcommand = args[1];
+        const { install, uninstall, start: daemonStart, stop: daemonStop, restart: daemonRestart, status: daemonStatus, logs: daemonLogs, printDaemonHelp, } = await import("./daemon-install.js");
+        switch (subcommand) {
+            case "install":
+                await install();
+                break;
+            case "uninstall":
+                await uninstall();
+                break;
+            case "start":
+                await daemonStart();
+                break;
+            case "stop":
+                await daemonStop();
+                break;
+            case "restart":
+                await daemonRestart();
+                break;
+            case "status":
+                await daemonStatus();
+                break;
+            case "logs":
+                await daemonLogs();
+                break;
+            default:
+                if (subcommand) {
+                    console.error(`Unknown daemon subcommand: ${subcommand}\n`);
+                }
+                printDaemonHelp();
+                if (subcommand)
+                    process.exit(1);
+        }
+        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/agents.js

@@ -9,6 +9,8 @@ import { getState, setState } from "../store/db.js";
 import { loadMcpConfig } from "./mcp-config.js";
 import { getSkillDirectories } from "./skills.js";
 import { findSquadAgent, renderProjectAgentRoster } from "../squad/registry.js";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("agents");
 // Frontmatter schema
 const agentFrontmatterSchema = z.object({
     name: z.string().min(1),
@@ -62,7 +64,7 @@ export function parseAgentMd(content, slug) {
     }
     const result = agentFrontmatterSchema.safeParse(parsed);
     if (!result.success) {
-        console.warn(`[agents] Invalid frontmatter in ${slug}.agent.md:`, result.error.format());
+        log.warn({ slug, errors: result.error.format() }, "Invalid frontmatter in agent file");
         return null;
     }
     const fm = result.data;
@@ -102,7 +104,7 @@ export function loadAgents() {
                 configs.push(config);
         }
         catch (err) {
-            console.warn(`[agents] Failed to read ${entry}:`, err instanceof Error ? err.message : err);
+            log.warn({ entry, err: err instanceof Error ? err.message : err }, "Failed to read agent entry");
         }
     }
     agentRegistry = configs;
@@ -138,7 +140,7 @@ export function ensureDefaultAgents() {
         if (!existsSync(dest)) {
             copyFileSync(src, dest);
             setState(stateKey, srcHash);
-            console.log(`[agents] Installed bundled agent: ${file}`);
+            log.info({ file }, "Installed bundled agent");
             continue;
         }
         // Check if the bundled version actually changed since our last sync
@@ -150,13 +152,13 @@ export function ensureDefaultAgents() {
         const destHash = createHash("sha256").update(readFileSync(dest)).digest("hex");
         if (lastSyncedHash && destHash !== lastSyncedHash) {
             // User modified the file after our last sync — don't clobber their changes
-            console.log(`[agents] Skipping ${file} — user has local customizations`);
+            log.debug({ file }, "Skipping bundled agent — user has local customizations");
             continue;
         }
         // Safe to update: either first sync (no record) or file is unmodified from our last deploy
         copyFileSync(src, dest);
         setState(stateKey, srcHash);
-        console.log(`[agents] Updated bundled agent: ${file}`);
+        log.info({ file }, "Updated bundled agent");
     }
 }
 /** Create a new agent .md file. Returns error string or null on success. */
@@ -326,7 +328,7 @@ export async function createEphemeralAgentSession(slug, client, allTools, modelO
             bufferExhaustionThreshold: 0.95,
         },
     });
-    console.log(`[agents] Created ephemeral session for @${agent.slug} (${model})`);
+    log.info({ agentSlug: agent.slug, model }, "Created ephemeral agent session");
     return session;
 }
 /** Create an ephemeral session for a squad virtual agent (not in CH registry). */
@@ -353,7 +355,7 @@ export async function createSquadAgentSession(slug, client, allTools, systemMess
             bufferExhaustionThreshold: 0.95,
         },
     });
-    console.log(`[agents] Created squad virtual agent session for @${slug} (${model})`);
+    log.info({ agentSlug: slug, model }, "Created squad virtual agent session");
     return session;
 }
 /** Clean up active task tracking (for shutdown/restart). */

package/dist/copilot/classifier.js

@@ -1,4 +1,6 @@
 import { approveAll } from "@github/copilot-sdk";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("classifier");
 // ---------------------------------------------------------------------------
 // Persistent GPT-4.1 classifier session
 // ---------------------------------------------------------------------------
@@ -52,7 +54,7 @@ export async function classifyWithLLM(client, message) {
         return TIER_MAP[raw] ?? "standard";
     }
     catch (err) {
-        console.log(`[chapterhouse] Classifier error (falling back to heuristics): ${err instanceof Error ? err.message : err}`);
+        log.warn({ err: err instanceof Error ? err.message : err }, "Classifier error, falling back to heuristics");
         // Destroy broken session so it's recreated next time
         if (classifierSession) {
             classifierSession.destroy().catch(() => { });