chapterhouse 0.3.0 → 0.3.1

package/README.md

@@ -307,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:

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterhouse",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Chapterhouse — a team-level AI assistant for engineering teams, built on the GitHub Copilot SDK. Web UI only.",
   "bin": {
     "chapterhouse": "dist/cli.js"