chapterhouse 0.3.6 → 0.3.8

package/dist/api/ralph.js

@@ -0,0 +1,153 @@
+/**
+ * Ralph watch process manager.
+ *
+ * Wraps `squad loop` (the CLI's "Ralph mode" — continuous work loop) so the
+ * web UI can start, stop, and inspect the local watch process.
+ *
+ * Single-process assumption: only one Ralph loop runs per daemon instance.
+ * Cross-project Ralph (WS bridge) is out of scope — see #101 follow-ups.
+ *
+ * @module api/ralph
+ */
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("ralph");
+const execFileAsync = promisify(execFile);
+const state = {
+    process: null,
+    pid: null,
+    startedAt: null,
+    projectRoot: null,
+    interval: null,
+    lastPollAt: null,
+};
+// ---------------------------------------------------------------------------
+// Status
+// ---------------------------------------------------------------------------
+export function getRalphStatus() {
+    return {
+        running: state.process !== null && state.pid !== null,
+        pid: state.pid,
+        startedAt: state.startedAt?.toISOString() ?? null,
+        projectRoot: state.projectRoot,
+        interval: state.interval,
+        lastPollAt: state.lastPollAt?.toISOString() ?? null,
+    };
+}
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+export function startRalph(projectRoot, interval) {
+    if (state.process !== null) {
+        return { started: false, error: "Ralph watch is already running" };
+    }
+    const proc = spawn("squad", ["loop", "--interval", String(interval)], {
+        cwd: projectRoot,
+        detached: false,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (!proc.pid) {
+        return { started: false, error: "Failed to spawn squad process" };
+    }
+    state.process = proc;
+    state.pid = proc.pid;
+    state.startedAt = new Date();
+    state.projectRoot = projectRoot;
+    state.interval = interval;
+    proc.stdout?.on("data", (_data) => {
+        state.lastPollAt = new Date();
+    });
+    proc.stderr?.on("data", (data) => {
+        log.warn({ data: data.toString().trim() }, "ralph stderr");
+    });
+    proc.on("exit", (code, signal) => {
+        log.info({ code, signal }, "Ralph process exited");
+        state.process = null;
+        state.pid = null;
+        state.startedAt = null;
+        state.projectRoot = null;
+        state.interval = null;
+    });
+    log.info({ pid: proc.pid, projectRoot, interval }, "Ralph watch started");
+    return { started: true, pid: proc.pid };
+}
+// ---------------------------------------------------------------------------
+// Stop
+// ---------------------------------------------------------------------------
+export function stopRalph() {
+    if (!state.process || !state.pid) {
+        return { stopped: false, error: "Ralph watch is not running" };
+    }
+    try {
+        state.process.kill("SIGTERM");
+        // State cleanup happens in the exit handler; clear eagerly for immediate
+        // status visibility.
+        state.process = null;
+        state.pid = null;
+        state.startedAt = null;
+        state.projectRoot = null;
+        state.interval = null;
+        return { stopped: true };
+    }
+    catch (err) {
+        return { stopped: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Fetch open squad-related issues from the GitHub repo rooted at projectRoot.
+ * Combines squad-labeled issues and issues labeled squad:* (any agent assignment).
+ */
+export async function getRalphQueue(projectRoot) {
+    const run = async (label) => {
+        const { stdout } = await execFileAsync("gh", ["issue", "list", "--label", label, "--json", "number,title,url,state,createdAt,labels", "--limit", "50"], { cwd: projectRoot });
+        return JSON.parse(stdout);
+    };
+    // Fetch squad (triage inbox) and squad:* (agent-assigned) in parallel.
+    // Merge and deduplicate by issue number.
+    const [squadIssues, squadStarIssues] = await Promise.allSettled([
+        run("squad"),
+        // gh doesn't support wildcard label filters; use a common prefix label.
+        // Most squad-labeled issues carry both "squad" and "squad:<agent>" labels,
+        // so the first query already captures them. Keep the second as belt-and-suspenders
+        // using any known squad-prefixed label.
+        run("squad:*").catch(() => []),
+    ]);
+    const all = [
+        ...(squadIssues.status === "fulfilled" ? squadIssues.value : []),
+        ...(squadStarIssues.status === "fulfilled" ? squadStarIssues.value : []),
+    ];
+    const seen = new Set();
+    const deduped = all.filter((issue) => {
+        if (seen.has(issue.number))
+            return false;
+        seen.add(issue.number);
+        return true;
+    });
+    return deduped.map((issue) => ({
+        number: issue.number,
+        title: issue.title,
+        url: issue.url,
+        state: issue.state,
+        createdAt: issue.createdAt,
+        labels: issue.labels.map((l) => l.name),
+    }));
+}
+// ---------------------------------------------------------------------------
+// Daemon shutdown hook
+// ---------------------------------------------------------------------------
+/** Kill Ralph watch process on daemon shutdown — call from shutdown() in daemon.ts. */
+export function killRalphOnShutdown() {
+    if (state.process) {
+        log.info({ pid: state.pid }, "Stopping Ralph watch on daemon shutdown");
+        try {
+            state.process.kill("SIGTERM");
+        }
+        catch {
+            /* best effort */
+        }
+        state.process = null;
+        state.pid = null;
+    }
+}
+//# sourceMappingURL=ralph.js.map

package/dist/api/ralph.test.js

@@ -0,0 +1,101 @@
+/**
+ * Unit tests for Ralph watch process manager.
+ *
+ * We test the module's exported functions directly. For process-spawn paths
+ * we verify state-machine behavior (status transitions, error returns) rather
+ * than trying to mock child_process across the ESM module cache boundary —
+ * the existing test harness doesn't support that cleanly for singleton modules.
+ *
+ * The getRalphQueue integration is exercised at the HTTP endpoint level in
+ * server.test.ts via supertest.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { getRalphStatus, startRalph, stopRalph } from "./ralph.js";
+// ---------------------------------------------------------------------------
+// Ensure a clean slate before each test group.
+// ---------------------------------------------------------------------------
+function ensureStopped() {
+    stopRalph(); // idempotent — ignores "not running" error
+}
+test("getRalphStatus — returns not-running when idle", () => {
+    ensureStopped();
+    const status = getRalphStatus();
+    assert.equal(status.running, false);
+    assert.equal(status.pid, null);
+    assert.equal(status.startedAt, null);
+    assert.equal(status.projectRoot, null);
+});
+test("stopRalph — returns error when not running", () => {
+    ensureStopped();
+    const result = stopRalph();
+    assert.equal(result.stopped, false);
+    if (!result.stopped) {
+        assert.match(result.error, /not running/i);
+    }
+});
+test("startRalph — spawns process and updates status", () => {
+    ensureStopped();
+    // We spawn 'squad loop' against the project root. In test environment squad
+    // will likely exit immediately (no .squad dir), but the process is created
+    // and state is updated synchronously before the exit handler fires.
+    // Use the worktree path itself — it has a .squad dir via the main repo's
+    // git worktree setup, so squad can at least start.
+    const projectRoot = process.cwd();
+    const result = startRalph(projectRoot, 10);
+    // Either it started (pid assigned) or it failed to spawn — either way must be well-typed.
+    if (result.started) {
+        assert.ok(typeof result.pid === "number", "pid should be a number");
+        const status = getRalphStatus();
+        // Status may have already transitioned back to stopped if process exited instantly.
+        // The important thing is that the call succeeded and we got a pid.
+        assert.ok(result.pid > 0, "pid should be positive");
+    }
+    else {
+        // Spawn failed (e.g., squad not found in PATH during test) — that's acceptable.
+        assert.ok(typeof result.error === "string");
+    }
+    // Cleanup regardless.
+    ensureStopped();
+});
+test("startRalph — returns error if already running", () => {
+    ensureStopped();
+    const projectRoot = process.cwd();
+    const first = startRalph(projectRoot, 10);
+    if (!first.started) {
+        // Can't test double-start if first spawn fails — skip gracefully.
+        return;
+    }
+    const second = startRalph(projectRoot, 10);
+    assert.equal(second.started, false);
+    if (!second.started) {
+        assert.match(second.error, /already running/i);
+    }
+    ensureStopped();
+});
+test("stopRalph — transitions status back to stopped", () => {
+    ensureStopped();
+    const projectRoot = process.cwd();
+    const result = startRalph(projectRoot, 10);
+    if (!result.started) {
+        // spawn unavailable in test env — skip.
+        return;
+    }
+    const stopResult = stopRalph();
+    assert.ok(stopResult.stopped, "stop should succeed when running");
+    const status = getRalphStatus();
+    assert.equal(status.running, false);
+    assert.equal(status.pid, null);
+});
+test("getRalphStatus shape — all fields present", () => {
+    ensureStopped();
+    const status = getRalphStatus();
+    assert.ok(Object.prototype.hasOwnProperty.call(status, "running"));
+    assert.ok(Object.prototype.hasOwnProperty.call(status, "pid"));
+    assert.ok(Object.prototype.hasOwnProperty.call(status, "startedAt"));
+    assert.ok(Object.prototype.hasOwnProperty.call(status, "projectRoot"));
+    assert.ok(Object.prototype.hasOwnProperty.call(status, "interval"));
+    assert.ok(Object.prototype.hasOwnProperty.call(status, "lastPollAt"));
+    assert.equal(typeof status.running, "boolean");
+});
+//# sourceMappingURL=ralph.test.js.map

package/dist/api/server.js

@@ -6,6 +6,7 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { z } from "zod";
 import { sendToOrchestrator, getAgentInfo, cancelCurrentMessage, getLastRouteResult, getCurrentSessionKey, subscribeTaskEvents } from "../copilot/orchestrator.js";
+import { squadEventBus } from "../copilot/squad-event-bus.js";
 import { getAgentRegistry } from "../copilot/agents.js";
 import { config, persistModel } from "../config.js";
 import { getRouterConfig, updateRouterConfig } from "../copilot/router.js";
@@ -27,6 +28,7 @@ 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";
+import { getRalphStatus, startRalph, stopRalph, getRalphQueue } from "./ralph.js";
 const log = childLogger("server");
 void searchIndex; // re-exported by index-manager; reference here documents the dep
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -321,8 +323,72 @@ app.get("/api/workers/:taskId/events/stream", (req, res) => {
     });
 });
 // ---------------------------------------------------------------------------
-// SSE stream for real-time chat
+// Global squad EventBus SSE stream — thin pass-through of SDK SquadEvents.
+// Replaces the 4-second poll in the Workers frontend: clients subscribe once
+// and receive push notifications on session:created / session:destroyed /
+// session:error so the worker list updates in real time.
+// Chat-specific events (delta, message, queued) are NOT emitted here.
 // ---------------------------------------------------------------------------
+app.get("/api/squad/stream", (req, res) => {
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+    });
+    res.write(formatSseData({ type: "connected" }));
+    const heartbeat = setInterval(() => { res.write(`:ping\n\n`); }, 20_000);
+    const unsub = squadEventBus.subscribeAll((event) => {
+        res.write(formatSseData({ type: "squad_event", squadEvent: event }));
+    });
+    req.on("close", () => {
+        clearInterval(heartbeat);
+        unsub();
+    });
+});
+// ---------------------------------------------------------------------------
+// Ralph watch panel endpoints — /api/squad/ralph/*
+// ---------------------------------------------------------------------------
+const ralphStartSchema = z.object({
+    projectRoot: z.string().min(1, "projectRoot is required"),
+    interval: z.number().int().min(1).max(120).default(10),
+}).strict();
+app.get("/api/squad/ralph/status", (_req, res) => {
+    res.json(getRalphStatus());
+});
+app.post("/api/squad/ralph/start", (req, res) => {
+    const { projectRoot, interval } = parseRequest(ralphStartSchema, req.body);
+    const result = startRalph(projectRoot, interval);
+    if (!result.started) {
+        res.status(409).json({ error: result.error });
+        return;
+    }
+    res.status(201).json({ pid: result.pid, projectRoot, interval });
+});
+app.post("/api/squad/ralph/stop", (_req, res) => {
+    const result = stopRalph();
+    if (!result.stopped) {
+        res.status(409).json({ error: result.error });
+        return;
+    }
+    res.json({ stopped: true });
+});
+app.get("/api/squad/ralph/queue", async (req, res) => {
+    const projectRoot = Array.isArray(req.query.projectRoot)
+        ? req.query.projectRoot[0]
+        : req.query.projectRoot;
+    if (!projectRoot || typeof projectRoot !== "string") {
+        res.status(400).json({ error: "Missing required query param: projectRoot" });
+        return;
+    }
+    try {
+        const issues = await getRalphQueue(projectRoot);
+        res.json({ projectRoot, issues });
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : err }, "getRalphQueue failed");
+        res.status(502).json({ error: err instanceof Error ? err.message : "gh issue list failed" });
+    }
+});
 app.get("/stream", (req, res) => {
     const connectionId = `web-${++connectionCounter}`;
     res.writeHead(200, {
@@ -408,6 +474,15 @@ app.post("/api/message", (req, res) => {
                 ...(msgId ? { msgId } : {}),
             }));
         }
+    }, (remainingLength) => {
+        const sseRes = sseClients.get(connectionId);
+        if (sseRes) {
+            sseRes.write(formatSseData({
+                type: "queue-advance",
+                length: remainingLength,
+                sessionKey: effectiveSessionKey,
+            }));
+        }
     });
     res.json({ status: "queued" });
 });

package/dist/copilot/agents.js

@@ -8,6 +8,7 @@ import { AGENTS_DIR, SESSIONS_DIR } from "../paths.js";
 import { getState, setState } from "../store/db.js";
 import { loadMcpConfig } from "./mcp-config.js";
 import { getSkillDirectories } from "./skills.js";
+import { createSessionHooks } from "./hooks.js";
 import { findSquadAgent, renderProjectAgentRoster } from "../squad/registry.js";
 import { childLogger } from "../util/logger.js";
 const log = childLogger("agents");
@@ -19,6 +20,7 @@ const agentFrontmatterSchema = z.object({
     skills: z.array(z.string()).optional(),
     tools: z.array(z.string()).optional(),
     mcpServers: z.array(z.string()).optional(),
+    allowed_paths: z.array(z.string()).optional(),
 });
 // ---------------------------------------------------------------------------
 // Agent Registry
@@ -50,7 +52,7 @@ export function parseAgentMd(content, slug) {
         parsed[key] = value;
     }
     // Parse arrays from YAML inline syntax: [a, b, c]
-    for (const key of ["skills", "tools", "mcpServers"]) {
+    for (const key of ["skills", "tools", "mcpServers", "allowed_paths"]) {
         const raw = parsed[key];
         if (typeof raw === "string") {
             const arrMatch = raw.match(/^\[(.*)\]$/);
@@ -76,6 +78,7 @@ export function parseAgentMd(content, slug) {
         skills: fm.skills,
         tools: fm.tools,
         mcpServers: fm.mcpServers,
+        allowedPaths: fm.allowed_paths,
         systemMessage: body,
     };
 }
@@ -322,6 +325,7 @@ export async function createEphemeralAgentSession(slug, client, allTools, modelO
         mcpServers,
         skillDirectories,
         onPermissionRequest: approveAll,
+        hooks: createSessionHooks(slug, agent.allowedPaths),
         infiniteSessions: {
             enabled: true,
             backgroundCompactionThreshold: 0.80,
@@ -349,6 +353,7 @@ export async function createSquadAgentSession(slug, client, allTools, systemMess
         mcpServers,
         skillDirectories,
         onPermissionRequest: approveAll,
+        hooks: createSessionHooks(slug),
         infiniteSessions: {
             enabled: true,
             backgroundCompactionThreshold: 0.80,

package/dist/copilot/hooks.js

@@ -0,0 +1,157 @@
+/**
+ * Hook Pipeline — Governance enforcement for Chapterhouse sessions.
+ *
+ * Bridges the squad-sdk's HookPipeline to the Copilot SDK's SessionHooks interface.
+ * All session creation sites call createSessionHooks() to get a SessionHooks object
+ * that runs the four Phase 1 policy hooks:
+ *
+ *   1. File-write guard   — block writes outside allowed paths
+ *   2. Shell restriction  — block dangerous commands (rm -rf, force-push, etc.)
+ *   3. PII scrubber       — redact emails from tool output before agent sees it
+ *   4. Reviewer lockout   — block locked-out agents from re-authoring rejected artifacts
+ *
+ * SPIKE FINDING (2026-05-08): onPermissionRequest only receives a coarse `kind`
+ * ("shell"|"write"|...) with no tool name or arguments. The correct interception
+ * point is `hooks.onPreToolUse` / `hooks.onPostToolUse` in SessionConfig.
+ */
+import { HookPipeline } from "@bradygaster/squad-sdk/hooks";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("hooks");
+/**
+ * Paths agents are allowed to write into by default.
+ * This covers the full project tree. Per-agent restrictions come from
+ * charter frontmatter `allowed_paths` (Phase 2).
+ */
+export const DEFAULT_ALLOWED_PATHS = [
+    "src/**",
+    ".squad/**",
+    "docs/**",
+    "web/**",
+    ".github/**",
+    ".worktrees/**",
+    "agents/**",
+    "scripts/**",
+    "skills/**",
+];
+let pipeline;
+export function getHookPipeline() {
+    return pipeline;
+}
+/**
+ * Initialize the singleton HookPipeline. Called once from initOrchestrator()
+ * before any sessions are created. Safe to call multiple times (reinitializes).
+ */
+export function initHookPipeline(overrides) {
+    const config = {
+        allowedWritePaths: DEFAULT_ALLOWED_PATHS,
+        scrubPii: true,
+        reviewerLockout: true,
+        // blockedCommands: undefined → HookPipeline uses DEFAULT_BLOCKED_COMMANDS
+        ...overrides,
+    };
+    pipeline = new HookPipeline(config);
+    log.info({ scrubPii: config.scrubPii, reviewerLockout: config.reviewerLockout, paths: config.allowedWritePaths?.length }, "HookPipeline initialized");
+    return pipeline;
+}
+/**
+ * Normalize a file path: strip leading CWD so that absolute paths match
+ * relative glob patterns. HookPipeline.matchGlob anchors with ^...$, so
+ * "/home/user/repo/src/foo.ts" won't match "src/**" without this step.
+ */
+function normalizePath(filePath) {
+    const cwd = process.cwd().replace(/\\/g, "/");
+    const normalized = filePath.replace(/\\/g, "/");
+    if (normalized.startsWith(cwd + "/")) {
+        return normalized.slice(cwd.length + 1);
+    }
+    return normalized;
+}
+/**
+ * Normalize all path arguments in a tool args object before running hooks.
+ * The file-write guard reads `path` or `file_path` from arguments.
+ */
+function normalizeToolArgs(args) {
+    const out = { ...args };
+    if (typeof out.path === "string")
+        out.path = normalizePath(out.path);
+    if (typeof out.file_path === "string")
+        out.file_path = normalizePath(out.file_path);
+    return out;
+}
+/**
+ * Create a SessionHooks object for use in createSession / resumeSession calls.
+ *
+ * @param agentName - Used for reviewer-lockout and log context. Pass "orchestrator"
+ *                    for coordinator sessions.
+ * @param agentAllowedPaths - If provided, overrides the default allowed paths for the
+ *                            file-write guard. Derived from charter frontmatter in Phase 2.
+ *                            Currently unused (no charter has allowed_paths yet).
+ */
+export function createSessionHooks(agentName, agentAllowedPaths) {
+    // If agent has specific paths, create a temporary per-session pipeline for file-write
+    // checking. All other hooks (shell, PII, lockout) use the singleton.
+    const fileWritePipeline = agentAllowedPaths && agentAllowedPaths.length > 0
+        ? new HookPipeline({ allowedWritePaths: agentAllowedPaths })
+        : undefined;
+    return {
+        onPreToolUse: async (input, invocation) => {
+            const p = getHookPipeline();
+            if (!p)
+                return;
+            const args = normalizeToolArgs((input.toolArgs ?? {}));
+            const ctx = {
+                toolName: input.toolName,
+                arguments: args,
+                agentName,
+                sessionId: invocation.sessionId,
+            };
+            // If agent has specific allowed paths, check file-write guard with those first.
+            if (fileWritePipeline) {
+                const pathResult = await fileWritePipeline.runPreToolHooks(ctx);
+                if (pathResult.action === "block") {
+                    log.warn({ tool: input.toolName, agent: agentName, reason: pathResult.reason }, "Hook blocked (agent paths)");
+                    return {
+                        permissionDecision: "deny",
+                        permissionDecisionReason: `[BLOCKED] ${pathResult.reason}`,
+                    };
+                }
+            }
+            const result = await p.runPreToolHooks(ctx);
+            if (result.action === "block") {
+                log.warn({ tool: input.toolName, agent: agentName, reason: result.reason }, "Hook blocked tool call");
+                return {
+                    permissionDecision: "deny",
+                    permissionDecisionReason: `[BLOCKED] ${result.reason}`,
+                };
+            }
+            if (result.action === "modify" && result.modifiedArguments) {
+                return { modifiedArgs: result.modifiedArguments };
+            }
+        },
+        onPostToolUse: async (input, invocation) => {
+            const p = getHookPipeline();
+            if (!p)
+                return;
+            const args = normalizeToolArgs((input.toolArgs ?? {}));
+            const originalText = input.toolResult.textResultForLlm;
+            const postResult = await p.runPostToolHooks({
+                toolName: input.toolName,
+                arguments: args,
+                result: originalText,
+                agentName,
+                sessionId: invocation.sessionId,
+            });
+            const scrubbed = postResult.result;
+            if (typeof scrubbed === "string" && scrubbed !== originalText) {
+                log.info({ tool: input.toolName, agent: agentName }, "PII scrubbed from tool output");
+                return {
+                    modifiedResult: {
+                        ...input.toolResult,
+                        textResultForLlm: scrubbed,
+                    },
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=hooks.js.map