chapterhouse 0.3.6 → 0.3.8

package/dist/copilot/hooks.test.js

@@ -0,0 +1,315 @@
+/**
+ * Unit tests for src/copilot/hooks.ts
+ *
+ * Tests per Mal's spec §6:
+ *  - One test per hook firing (block cases)
+ *  - One test per hook bypass attempt (allow cases)
+ *  - Integration: createSessionHooks adapter translates HookPipeline results to SDK format
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { HookPipeline } from "@bradygaster/squad-sdk/hooks";
+import { initHookPipeline, getHookPipeline, createSessionHooks, DEFAULT_ALLOWED_PATHS } from "./hooks.js";
+// ---------------------------------------------------------------------------
+// HookPipeline unit tests — directly exercising the squad-sdk class
+// ---------------------------------------------------------------------------
+describe("HookPipeline — file-write guard", () => {
+    it("blocks write to path outside allowlist", async () => {
+        const pipeline = new HookPipeline({ allowedWritePaths: ["src/**"] });
+        const result = await pipeline.runPreToolHooks({
+            toolName: "edit",
+            arguments: { path: "/etc/passwd" },
+            agentName: "test-agent",
+            sessionId: "test-1",
+        });
+        assert.equal(result.action, "block");
+        assert.ok(result.reason?.includes("/etc/passwd"), `reason should mention path, got: ${result.reason}`);
+    });
+    it("allows write to path inside allowlist", async () => {
+        const pipeline = new HookPipeline({ allowedWritePaths: ["src/**"] });
+        const result = await pipeline.runPreToolHooks({
+            toolName: "edit",
+            arguments: { path: "src/copilot/hooks.ts" },
+            agentName: "test-agent",
+            sessionId: "test-1",
+        });
+        assert.equal(result.action, "allow");
+    });
+    it("allows non-write tools regardless of path", async () => {
+        const pipeline = new HookPipeline({ allowedWritePaths: ["src/**"] });
+        const result = await pipeline.runPreToolHooks({
+            toolName: "bash",
+            arguments: { command: "echo hello", path: "/etc/passwd" },
+            agentName: "test-agent",
+            sessionId: "test-1",
+        });
+        // File-write guard only fires on edit/create/write_file/create_file
+        // This will hit the shell restriction instead (echo is safe)
+        assert.ok(result.action === "allow" || result.action === "block");
+        if (result.action === "block") {
+            // Should be shell restriction, not file-write
+            assert.ok(!result.reason?.includes("/etc/passwd"));
+        }
+    });
+});
+describe("HookPipeline — shell command restriction", () => {
+    it("blocks rm -rf", async () => {
+        const pipeline = new HookPipeline({});
+        const result = await pipeline.runPreToolHooks({
+            toolName: "bash",
+            arguments: { command: "rm -rf /important" },
+            agentName: "test-agent",
+            sessionId: "test-2",
+        });
+        assert.equal(result.action, "block");
+        assert.ok(result.reason?.toLowerCase().includes("rm -rf"), `reason should mention rm -rf, got: ${result.reason}`);
+    });
+    it("blocks git push --force", async () => {
+        const pipeline = new HookPipeline({});
+        const result = await pipeline.runPreToolHooks({
+            toolName: "bash",
+            arguments: { command: "git push --force origin main" },
+            agentName: "test-agent",
+            sessionId: "test-2",
+        });
+        assert.equal(result.action, "block");
+        assert.ok(result.reason?.toLowerCase().includes("git push --force"), `reason should mention force push, got: ${result.reason}`);
+    });
+    it("allows safe shell commands", async () => {
+        const pipeline = new HookPipeline({});
+        const result = await pipeline.runPreToolHooks({
+            toolName: "bash",
+            arguments: { command: "npm test" },
+            agentName: "test-agent",
+            sessionId: "test-2",
+        });
+        assert.equal(result.action, "allow");
+    });
+    it("allows non-shell tools regardless of args", async () => {
+        const pipeline = new HookPipeline({});
+        const result = await pipeline.runPreToolHooks({
+            toolName: "read_file",
+            arguments: { command: "rm -rf /" },
+            agentName: "test-agent",
+            sessionId: "test-2",
+        });
+        // Shell restriction only fires on bash/powershell/shell/exec
+        assert.equal(result.action, "allow");
+    });
+});
+describe("HookPipeline — PII scrubber", () => {
+    it("redacts email addresses in tool output", async () => {
+        const pipeline = new HookPipeline({ scrubPii: true });
+        const result = await pipeline.runPostToolHooks({
+            toolName: "bash",
+            arguments: {},
+            result: "User email is brian@example.com and also admin@test.org",
+            agentName: "test-agent",
+            sessionId: "test-3",
+        });
+        assert.ok(typeof result.result === "string" && !result.result.includes("brian@example.com"), `Email should be redacted, got: ${result.result}`);
+        assert.ok(typeof result.result === "string" && result.result.includes("[EMAIL_REDACTED]"), `Should contain redaction marker, got: ${result.result}`);
+    });
+    it("passes through clean output unchanged", async () => {
+        const pipeline = new HookPipeline({ scrubPii: true });
+        const original = "Build succeeded. 405 tests passed.";
+        const result = await pipeline.runPostToolHooks({
+            toolName: "bash",
+            arguments: {},
+            result: original,
+            agentName: "test-agent",
+            sessionId: "test-3",
+        });
+        assert.equal(result.result, original);
+    });
+    it("does not scrub when scrubPii is false", async () => {
+        const pipeline = new HookPipeline({ scrubPii: false });
+        const original = "Email: test@example.com";
+        const result = await pipeline.runPostToolHooks({
+            toolName: "bash",
+            arguments: {},
+            result: original,
+            agentName: "test-agent",
+            sessionId: "test-3",
+        });
+        assert.equal(result.result, original);
+    });
+});
+describe("HookPipeline — reviewer lockout", () => {
+    it("blocks locked-out agent from editing artifact", async () => {
+        const pipeline = new HookPipeline({ reviewerLockout: true });
+        pipeline.getReviewerLockout().lockout("src/auth.ts", "kaylee");
+        const result = await pipeline.runPreToolHooks({
+            toolName: "edit",
+            arguments: { path: "src/auth.ts" },
+            agentName: "kaylee",
+            sessionId: "test-4",
+        });
+        assert.equal(result.action, "block");
+        assert.ok(result.reason?.includes("kaylee"), `reason should name agent, got: ${result.reason}`);
+    });
+    it("allows non-locked-out agent to edit same artifact", async () => {
+        const pipeline = new HookPipeline({ reviewerLockout: true, allowedWritePaths: ["src/**"] });
+        pipeline.getReviewerLockout().lockout("src/auth.ts", "kaylee");
+        const result = await pipeline.runPreToolHooks({
+            toolName: "edit",
+            arguments: { path: "src/auth.ts" },
+            agentName: "zoe",
+            sessionId: "test-4",
+        });
+        assert.equal(result.action, "allow");
+    });
+    it("allows locked-out agent to edit different artifact", async () => {
+        const pipeline = new HookPipeline({ reviewerLockout: true, allowedWritePaths: ["src/**"] });
+        pipeline.getReviewerLockout().lockout("src/auth.ts", "kaylee");
+        const result = await pipeline.runPreToolHooks({
+            toolName: "edit",
+            arguments: { path: "src/copilot/hooks.ts" },
+            agentName: "kaylee",
+            sessionId: "test-4",
+        });
+        assert.equal(result.action, "allow");
+    });
+});
+// ---------------------------------------------------------------------------
+// initHookPipeline / getHookPipeline — singleton lifecycle
+// ---------------------------------------------------------------------------
+describe("initHookPipeline", () => {
+    it("initializes the singleton pipeline", () => {
+        const p = initHookPipeline();
+        assert.ok(p instanceof HookPipeline);
+        assert.equal(getHookPipeline(), p);
+    });
+    it("reinitializes on second call (returns new instance)", () => {
+        const first = initHookPipeline();
+        const second = initHookPipeline();
+        assert.ok(second instanceof HookPipeline);
+        // Both are valid instances; the singleton points to the latest
+        assert.equal(getHookPipeline(), second);
+    });
+    it("respects policy overrides", async () => {
+        // Override: disable PII scrubbing
+        initHookPipeline({ scrubPii: false });
+        const p = getHookPipeline();
+        const result = await p.runPostToolHooks({
+            toolName: "bash",
+            arguments: {},
+            result: "email: test@example.com",
+            agentName: "test-agent",
+            sessionId: "test-5",
+        });
+        // With scrubPii: false, email is NOT redacted
+        assert.equal(result.result, "email: test@example.com");
+    });
+});
+// ---------------------------------------------------------------------------
+// createSessionHooks — adapter tests (SDK interface bridging)
+// ---------------------------------------------------------------------------
+describe("createSessionHooks", () => {
+    before(() => {
+        // Fresh pipeline with defaults for adapter tests
+        initHookPipeline({
+            allowedWritePaths: DEFAULT_ALLOWED_PATHS,
+            scrubPii: true,
+            reviewerLockout: true,
+        });
+    });
+    const fakeInvocation = { sessionId: "adapter-test-session" };
+    it("returns deny for blocked write (SDK adapter output)", async () => {
+        const hooks = createSessionHooks("test-agent");
+        const result = await hooks.onPreToolUse({
+            toolName: "edit",
+            toolArgs: { path: "/etc/passwd" },
+            timestamp: Date.now(),
+            cwd: process.cwd(),
+        }, fakeInvocation);
+        assert.ok(result, "Should return a result object");
+        assert.equal(result.permissionDecision, "deny");
+        assert.ok(result.permissionDecisionReason?.includes("[BLOCKED]"), `reason should start with [BLOCKED], got: ${result.permissionDecisionReason}`);
+    });
+    it("returns undefined (allow) for safe write inside default paths", async () => {
+        const hooks = createSessionHooks("test-agent");
+        const result = await hooks.onPreToolUse({
+            toolName: "edit",
+            toolArgs: { path: "src/copilot/hooks.ts" },
+            timestamp: Date.now(),
+            cwd: process.cwd(),
+        }, fakeInvocation);
+        // Allowed — should return void/undefined
+        assert.ok(result == null || result.permissionDecision !== "deny");
+    });
+    it("returns deny for blocked shell command", async () => {
+        const hooks = createSessionHooks("test-agent");
+        const result = await hooks.onPreToolUse({
+            toolName: "bash",
+            toolArgs: { command: "rm -rf /" },
+            timestamp: Date.now(),
+            cwd: process.cwd(),
+        }, fakeInvocation);
+        assert.ok(result, "Should return a result object");
+        assert.equal(result.permissionDecision, "deny");
+    });
+    it("strips CWD prefix from absolute paths before hook check", async () => {
+        const hooks = createSessionHooks("test-agent");
+        const absPath = `${process.cwd()}/src/copilot/hooks.ts`;
+        const result = await hooks.onPreToolUse({
+            toolName: "edit",
+            toolArgs: { path: absPath },
+            timestamp: Date.now(),
+            cwd: process.cwd(),
+        }, fakeInvocation);
+        // After stripping CWD, "src/copilot/hooks.ts" matches "src/**" → allow
+        assert.ok(result == null || result.permissionDecision !== "deny", "Absolute path within project should be allowed");
+    });
+    it("scrubs PII from tool output via onPostToolUse adapter", async () => {
+        const hooks = createSessionHooks("test-agent");
+        const fakeToolResult = {
+            textResultForLlm: "Contact admin@example.com for support",
+            resultType: "success",
+        };
+        const result = await hooks.onPostToolUse({
+            toolName: "bash",
+            toolArgs: {},
+            toolResult: fakeToolResult,
+            timestamp: Date.now(),
+            cwd: process.cwd(),
+        }, fakeInvocation);
+        assert.ok(result, "Should return a modified result");
+        assert.ok(result.modifiedResult?.textResultForLlm.includes("[EMAIL_REDACTED]"), `Should redact email, got: ${result.modifiedResult?.textResultForLlm}`);
+    });
+    it("returns undefined from onPostToolUse when nothing to scrub", async () => {
+        const hooks = createSessionHooks("test-agent");
+        const fakeToolResult = {
+            textResultForLlm: "All 405 tests passed.",
+            resultType: "success",
+        };
+        const result = await hooks.onPostToolUse({
+            toolName: "bash",
+            toolArgs: {},
+            toolResult: fakeToolResult,
+            timestamp: Date.now(),
+            cwd: process.cwd(),
+        }, fakeInvocation);
+        // No PII → no modification → return undefined
+        assert.ok(result == null, "Should return undefined when no scrubbing needed");
+    });
+    it("uses per-agent allowedPaths when provided", async () => {
+        // Agent restricted to .squad/** only
+        const hooks = createSessionHooks("restricted-agent", [".squad/**"]);
+        const result = await hooks.onPreToolUse({
+            toolName: "edit",
+            toolArgs: { path: "src/copilot/hooks.ts" },
+            timestamp: Date.now(),
+            cwd: process.cwd(),
+        }, fakeInvocation);
+        // src/** is in DEFAULT_ALLOWED_PATHS (global) but NOT in restricted agent's paths
+        // The per-agent check runs first and should block it
+        assert.ok(result, "Should return a result object");
+        assert.equal(result.permissionDecision, "deny");
+    });
+    after(() => {
+        // Restore default pipeline for any tests that follow
+        initHookPipeline();
+    });
+});
+//# sourceMappingURL=hooks.test.js.map

package/dist/copilot/orchestrator.js

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { approveAll } from "@github/copilot-sdk";
+import { initHookPipeline, createSessionHooks } from "./hooks.js";
 import { createTools } from "./tools.js";
 import { getOrchestratorSystemMessage } from "./system-message.js";
 import { CHAPTERHOUSE_VERSION } from "../version.js";
@@ -17,9 +18,9 @@ import { loadAgents, ensureDefaultAgents, clearActiveTasks, getAgentRegistry, se
 import { normalizeProjectPath, setChannelProject } from "../squad/context.js";
 import { getSquadCoordinatorSystemMessage } from "../squad/charter.js";
 import { childLogger } from "../util/logger.js";
+import { squadEventBus } from "./squad-event-bus.js";
 import { SessionManager, SessionRegistry, SESSION_IDLE_TTL_MS, SESSION_MAX_ACTIVE, } from "./session-manager.js";
 const log = childLogger("orchestrator");
-const orchestratorPermissionHandler = approveAll;
 const MAX_RETRIES = 3;
 const RECONNECT_DELAYS_MS = [1_000, 3_000, 10_000];
 const HEALTH_CHECK_INTERVAL_MS = 30_000;
@@ -52,31 +53,36 @@ let lastRouteResult;
 export function getLastRouteResult() {
     return lastRouteResult;
 }
-const taskEventListeners = new Map();
 export function subscribeTaskEvents(taskId, listener) {
-    if (!taskEventListeners.has(taskId)) {
-        taskEventListeners.set(taskId, new Set());
-    }
-    taskEventListeners.get(taskId).add(listener);
-    return () => {
-        const set = taskEventListeners.get(taskId);
-        if (set) {
-            set.delete(listener);
-            if (set.size === 0)
-                taskEventListeners.delete(taskId);
-        }
-    };
+    return squadEventBus.subscribe("session:tool_call", (event) => {
+        if (event.sessionId !== taskId)
+            return;
+        const p = event.payload;
+        listener({
+            seq: p._seq ?? 0,
+            ts: p._ts ?? Date.now(),
+            kind: p._kind === "tool_complete" ? "tool_complete" : "tool_start",
+            toolName: p.toolName ?? null,
+            summary: p._summary ?? null,
+        });
+    });
 }
 function emitTaskEvent(taskId, event) {
-    const set = taskEventListeners.get(taskId);
-    if (set) {
-        for (const listener of set) {
-            try {
-                listener(event);
-            }
-            catch { /* non-fatal */ }
-        }
-    }
+    void squadEventBus.emit({
+        type: "session:tool_call",
+        sessionId: taskId,
+        payload: {
+            toolName: event.toolName ?? "",
+            toolArgs: {},
+            resultType: event.kind === "tool_complete" ? "success" : undefined,
+            // Internal fields threaded through payload so subscribeTaskEvents can reconstruct
+            _kind: event.kind,
+            _seq: event.seq,
+            _ts: event.ts,
+            _summary: event.summary,
+        },
+        timestamp: new Date(event.ts),
+    });
 }
 // ---------------------------------------------------------------------------
 // SessionRegistry — the single owner of all per-session orchestrators
@@ -250,7 +256,8 @@ async function createOrResumeSession(sessionKey, projectRoot) {
                 tools,
                 mcpServers,
                 skillDirectories,
-                onPermissionRequest: orchestratorPermissionHandler,
+                onPermissionRequest: approveAll,
+                hooks: createSessionHooks("orchestrator"),
                 infiniteSessions,
             });
             log.info({ sessionKey }, "Session resumed successfully");
@@ -275,7 +282,8 @@ async function createOrResumeSession(sessionKey, projectRoot) {
         tools,
         mcpServers,
         skillDirectories,
-        onPermissionRequest: orchestratorPermissionHandler,
+        onPermissionRequest: approveAll,
+        hooks: createSessionHooks("orchestrator"),
         infiniteSessions,
     });
     log.info({ sessionKey, sessionId: session.sessionId.slice(0, 8) }, "Session created");
@@ -289,6 +297,8 @@ async function createOrResumeSession(sessionKey, projectRoot) {
 }
 export async function initOrchestrator(client) {
     copilotClient = client;
+    // Initialize governance hook pipeline before any session is created.
+    initHookPipeline();
     // (Re-)create the registry — supports multiple initOrchestrator calls in tests
     if (registry) {
         await registry.shutdown();
@@ -477,6 +487,13 @@ async function executeOnSession(manager, item) {
                     : data.agentDescription || data.agentDisplayName || `Squad dispatch: ${agentSlug}`).slice(0, 500);
                 db.prepare(`INSERT OR IGNORE INTO agent_tasks (task_id, agent_slug, description, status, origin_channel, session_key, source) VALUES (?, ?, ?, 'running', ?, ?, 'squad')`).run(data.toolCallId, agentSlug, description, item.sourceChannel || null, sessionKey);
                 activeSubagentTaskIds.add(data.toolCallId);
+                void squadEventBus.emit({
+                    type: "session:created",
+                    sessionId: data.toolCallId,
+                    agentName: agentSlug,
+                    payload: { agentName: agentSlug, priority: "normal" },
+                    timestamp: new Date(),
+                });
             }
             catch { /* non-fatal */ }
         });
@@ -485,6 +502,15 @@ async function executeOnSession(manager, item) {
                 spawnArgsMap.delete(event.data.toolCallId);
                 activeSubagentTaskIds.delete(event.data.toolCallId);
                 db.prepare(`UPDATE agent_tasks SET status = 'completed', completed_at = CURRENT_TIMESTAMP WHERE task_id = ?`).run(event.data.toolCallId);
+                const taskId = event.data.toolCallId;
+                const taskRow = db.prepare(`SELECT agent_slug FROM agent_tasks WHERE task_id = ?`).get(taskId);
+                void squadEventBus.emit({
+                    type: "session:destroyed",
+                    sessionId: taskId,
+                    agentName: taskRow?.agent_slug,
+                    payload: { agentName: taskRow?.agent_slug ?? "", reason: "complete" },
+                    timestamp: new Date(),
+                });
             }
             catch { /* non-fatal */ }
         });
@@ -494,6 +520,14 @@ async function executeOnSession(manager, item) {
                 spawnArgsMap.delete(data.toolCallId);
                 activeSubagentTaskIds.delete(data.toolCallId);
                 db.prepare(`UPDATE agent_tasks SET status = 'error', result = ?, completed_at = CURRENT_TIMESTAMP WHERE task_id = ?`).run(data.error || "Subagent failed", data.toolCallId);
+                const taskRow = db.prepare(`SELECT agent_slug FROM agent_tasks WHERE task_id = ?`).get(data.toolCallId);
+                void squadEventBus.emit({
+                    type: "session:error",
+                    sessionId: data.toolCallId,
+                    agentName: taskRow?.agent_slug,
+                    payload: { agentName: taskRow?.agent_slug ?? "", error: data.error ?? "Subagent failed" },
+                    timestamp: new Date(),
+                });
             }
             catch { /* non-fatal */ }
         });
@@ -636,7 +670,7 @@ function isRecoverableError(err) {
         return false;
     return /disconnect|connection|EPIPE|ECONNRESET|ECONNREFUSED|socket|closed|ENOENT|spawn|not found|expired|stale/i.test(msg);
 }
-export async function sendToOrchestrator(prompt, source, callback, attachments, onActivity, onQueued) {
+export async function sendToOrchestrator(prompt, source, callback, attachments, onActivity, onQueued, onAdvance) {
     updateUserContext(source);
     updateRequestContext(source);
     // Generate a unique ID for this orchestrator turn.  Every SSE event emitted
@@ -686,6 +720,7 @@ export async function sendToOrchestrator(prompt, source, callback, attachments,
                         turnId,
                         // Background messages skip queue visibility — only web/user messages need it.
                         onQueued: source.type === "web" ? onQueued : undefined,
+                        onAdvance: source.type === "web" ? onAdvance : undefined,
                         sourceChannel,
                         targetAgent,
                         channelKey,

package/dist/copilot/session-manager.js

@@ -146,6 +146,9 @@ export class SessionManager {
         this._processing = true;
         while (this._queue.length > 0) {
             const item = this._queue.shift();
+            // Notify before the worker starts — closing the window where backend queue
+            // length has dropped but the frontend still shows stale "N ahead" counts.
+            item.onAdvance?.(this._queue.length);
             const start = Date.now();
             log.info({ sessionKey: this.sessionKey, sourceChannel: item.sourceChannel }, "session.turn.started");
             try {

package/dist/copilot/session-manager.test.js

@@ -426,4 +426,74 @@ test("SessionManager: onQueued does NOT fire when queue is empty (no active turn
     // Let the worker complete to avoid unresolved promises.
     await promise.catch(() => { });
 });
+// ---------------------------------------------------------------------------
+// onAdvance tests (#97 — queue-advance event timing)
+// ---------------------------------------------------------------------------
+test("SessionManager: onAdvance fires after each dequeue with remaining queue length", async () => {
+    const { session } = makeFakeSession();
+    const resolvers = [];
+    const worker = () => new Promise((r) => { resolvers.push(() => r("done")); });
+    const manager = new SessionManager("default", worker, factory(session));
+    // item1: no onAdvance — in real usage the first in-flight message is not a
+    // queued-behind message. onAdvance is set only on items that arrive while
+    // another turn is already in-flight.
+    let resolve1;
+    let reject1;
+    const p1 = new Promise((res, rej) => { resolve1 = res; reject1 = rej; });
+    const item1 = {
+        prompt: "first", callback: () => { }, sessionKey: "default",
+        turnId: "adv-turn-1", resolve: resolve1, reject: reject1,
+    };
+    manager.enqueue(item1);
+    // Wait one tick so drain() suspends at `await worker(item1)`.
+    await new Promise((r) => setTimeout(r, 0));
+    assert.equal(manager.isProcessing, true, "item1 should be processing");
+    // Enqueue items 2 and 3 WHILE item1 is in-flight.
+    const advanceLengths = [];
+    let resolve2;
+    let reject2;
+    const p2 = new Promise((res, rej) => { resolve2 = res; reject2 = rej; });
+    const item2 = {
+        prompt: "second", callback: () => { }, sessionKey: "default",
+        turnId: "adv-turn-2", resolve: resolve2, reject: reject2,
+        onAdvance: (len) => { advanceLengths.push(len); },
+    };
+    let resolve3;
+    let reject3;
+    const p3 = new Promise((res, rej) => { resolve3 = res; reject3 = rej; });
+    const item3 = {
+        prompt: "third", callback: () => { }, sessionKey: "default",
+        turnId: "adv-turn-3", resolve: resolve3, reject: reject3,
+        onAdvance: (len) => { advanceLengths.push(len); },
+    };
+    manager.enqueue(item2); // queue: [item2]
+    manager.enqueue(item3); // queue: [item2, item3]
+    // Unblock item1 → drain shifts item2 → item2.onAdvance(1) since item3 remains.
+    resolvers[0]();
+    await new Promise((r) => setTimeout(r, 0));
+    assert.equal(advanceLengths[0], 1, "item2 dequeue: 1 item remains (item3)");
+    // Unblock item2 → drain shifts item3 → item3.onAdvance(0) — queue empty.
+    resolvers[1]();
+    await new Promise((r) => setTimeout(r, 0));
+    assert.equal(advanceLengths[1], 0, "item3 dequeue: 0 items remain");
+    assert.equal(advanceLengths.length, 2, "onAdvance fires exactly once per dequeue");
+    // Clean up.
+    resolvers[2]();
+    await Promise.all([p1, p2, p3]);
+});
+test("SessionManager: onAdvance fires before worker starts (timing guarantee)", async () => {
+    const { session } = makeFakeSession();
+    const events = [];
+    const worker = () => {
+        events.push("worker-started");
+        return Promise.resolve("done");
+    };
+    const manager = new SessionManager("default", worker, factory(session));
+    const { item, promise } = makeDeferred();
+    item.onAdvance = () => { events.push("advance-fired"); };
+    manager.enqueue(item);
+    await promise.catch(() => { });
+    // advance must precede worker-started
+    assert.deepEqual(events, ["advance-fired", "worker-started"], "onAdvance must fire before the worker begins executing");
+});
 //# sourceMappingURL=session-manager.test.js.map

package/dist/copilot/squad-event-bus.js

@@ -0,0 +1,27 @@
+/**
+ * Process-scoped singleton EventBus for squad agent lifecycle events.
+ *
+ * The SDK `EventBus` is a plain class — no hidden global state. We own
+ * the singleton here so the entire daemon process shares one bus. All
+ * code that emits or subscribes to squad events imports from this module.
+ *
+ * Cross-project reach: NOT supported with a single bus instance. Requires
+ * the SDK's WS bridge (`startWSBridge`) or a shared IPC channel. Out of
+ * scope for #101 — see mal-101-architecture.md §Forward Implications.
+ *
+ * Exported event types mirror `SquadEventPayloadMap` from the SDK:
+ *   session:created      — sub-agent spawned
+ *   session:idle         — sub-agent waiting / between turns
+ *   session:error        — sub-agent failed
+ *   session:destroyed    — sub-agent finished (reason: complete | error | abort)
+ *   session:tool_call    — tool invoked (resultType undefined=start, defined=end)
+ *   agent:milestone      — model fallback / exhaustion
+ *   coordinator:routing  — coordinator routing decision phases
+ *   pool:health          — session pool stats
+ *
+ * @module copilot/squad-event-bus
+ */
+import { EventBus } from "@bradygaster/squad-sdk/runtime/event-bus";
+/** Process-level singleton. Import this everywhere instead of newing EventBus. */
+export const squadEventBus = new EventBus();
+//# sourceMappingURL=squad-event-bus.js.map

package/dist/copilot/tools.js

@@ -6,6 +6,7 @@ import { join } from "path";
 import { homedir } from "os";
 import { listSkills, createSkill, removeSkill } from "./skills.js";
 import { config, persistModel } from "../config.js";
+import { createSessionHooks } from "./hooks.js";
 import { getCurrentSourceChannel, getCurrentActivityCallback, getCurrentAuthenticatedUser, getLastAuthenticatedUser, getCurrentAuthorizationHeader, getCurrentChannelKey, getCurrentSessionKey, switchSessionModel, } from "./orchestrator.js";
 import { getRouterConfig, updateRouterConfig } from "./router.js";
 import { ensureWikiStructure, readPage, writePage, deletePage, listPages, writeRawSource, listSources, assertPagePath } from "../wiki/fs.js";
@@ -583,6 +584,7 @@ export function createTools(deps) {
                     const session = await deps.client.resumeSession(args.session_id, {
                         model: config.copilotModel,
                         onPermissionRequest: approveAll,
+                        hooks: createSessionHooks(args.name),
                     });
                     const db = getDb();
                     db.prepare(`INSERT OR REPLACE INTO agent_sessions (slug, copilot_session_id, model, status)

package/dist/daemon.js

@@ -2,6 +2,7 @@ import { getClient, stopClient } from "./copilot/client.js";
 import { initOrchestrator, setMessageLogger, setProactiveNotify, getAgentInfo, shutdownAgents } from "./copilot/orchestrator.js";
 import { stopEpisodeWriter } from "./copilot/episode-writer.js";
 import { startApiServer, broadcastToSSE } from "./api/server.js";
+import { killRalphOnShutdown } from "./api/ralph.js";
 import { getDb, closeDb, getState } from "./store/db.js";
 import { config } from "./config.js";
 import { spawn } from "child_process";
@@ -213,6 +214,10 @@ async function shutdown() {
         await stopClient();
     }
     catch { /* best effort */ }
+    try {
+        killRalphOnShutdown();
+    }
+    catch { /* best effort */ }
     closeDb();
     log.info("Goodbye");
     process.exit(0);
@@ -238,6 +243,10 @@ export async function restartDaemon() {
         await stopClient();
     }
     catch { /* best effort */ }
+    try {
+        killRalphOnShutdown();
+    }
+    catch { /* best effort */ }
     closeDb();
     // Spawn a detached replacement process with the same args (include execArgv for tsx/loaders)
     const child = spawn(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {