chapterhouse 0.3.9 → 0.3.11

package/dist/copilot/turn-event-log.js

@@ -0,0 +1,298 @@
+/**
+ * Per-turn in-memory event ring buffer with session-level fan-out — #130.
+ *
+ * Architecture decisions (from Mal #129):
+ *  - Events accumulate in a per-turn ring buffer (200 events) during the turn.
+ *  - A parallel per-session ring buffer (200 events) feeds the SSE reconnect path.
+ *  - On turn completion, events are persisted to the `turn_events` SQLite table.
+ *  - The per-turn buffer is cleared after a 30 s grace window so late reconnects
+ *    can still replay from memory before SQLite is needed.
+ *  - After the grace window, SSE replay falls back to SQLite.
+ *
+ * Public API surface:
+ *  - `emitTurnEvent(sessionKey, event)` — emit an event (called from orchestrator.ts)
+ *  - `subscribeTurn(turnId, listener)` — per-turn subscribe with immediate replay
+ *  - `subscribeSession(sessionKey, listener, afterSeq?)` — session SSE subscribe + replay
+ *  - `persistTurnEvents(turnId, sessionKey)` — write ring buffer to SQLite
+ *  - `scheduleClearTurnLog(turnId)` — schedule buffer clear after grace window
+ *  - `getSessionEventsFromDb(sessionKey, afterSeq)` — SQLite fallback for completed turns
+ *
+ * @module copilot/turn-event-log
+ */
+import { childLogger } from "../util/logger.js";
+import { getDb } from "../store/db.js";
+import { RingBuffer } from "./ring-buffer.js";
+const log = childLogger("turn-event-log");
+// ---------------------------------------------------------------------------
+// Capacity constants
+// ---------------------------------------------------------------------------
+/** Events retained per turn in memory (covers long turns with many tool calls). */
+export const TURN_BUFFER_CAPACITY = 200;
+/** Recent events retained per session for SSE reconnect replay. */
+export const SESSION_BUFFER_CAPACITY = 200;
+/** Grace window before per-turn buffer is cleared after turn completion (ms). */
+export const TURN_CLEAR_GRACE_MS = 30_000;
+// ---------------------------------------------------------------------------
+// Singleton state
+// ---------------------------------------------------------------------------
+/** Per-turn ring buffer + associated session key. */
+const turnBuffers = new Map();
+/** Per-turn live listeners (for subscribeTurn()). */
+const turnListeners = new Map();
+/** Per-session ring buffer for SSE reconnect replay (sliding window across turns). */
+const sessionBuffers = new Map();
+/** Per-session live listeners (SSE connections). */
+const sessionListeners = new Map();
+/** Pending clear-buffer timers keyed by turnId. */
+const clearTimers = new Map();
+/** Monotonic global sequence counter — used as SSE `id:` for Last-Event-ID replay. */
+let globalSeq = 0;
+// ---------------------------------------------------------------------------
+// Emit
+// ---------------------------------------------------------------------------
+/**
+ * Emit a turn event.  Updates both the per-turn ring buffer and the per-session
+ * sliding buffer, then notifies all live listeners.
+ *
+ * Called from orchestrator.ts alongside the existing callback path.
+ */
+export function emitTurnEvent(sessionKey, event) {
+    const indexed = { ...event, _seq: ++globalSeq, _ts: Date.now() };
+    // Per-turn buffer --------------------------------------------------------
+    const turnId = event.turnId;
+    let entry = turnBuffers.get(turnId);
+    if (!entry) {
+        entry = { buf: new RingBuffer(TURN_BUFFER_CAPACITY), sessionKey };
+        turnBuffers.set(turnId, entry);
+    }
+    entry.buf.push(indexed);
+    // Per-session buffer (sliding window across turns) -----------------------
+    let sessionBuf = sessionBuffers.get(sessionKey);
+    if (!sessionBuf) {
+        sessionBuf = new RingBuffer(SESSION_BUFFER_CAPACITY);
+        sessionBuffers.set(sessionKey, sessionBuf);
+    }
+    sessionBuf.push(indexed);
+    // Notify per-turn listeners ----------------------------------------------
+    const tListeners = turnListeners.get(turnId);
+    if (tListeners) {
+        for (const fn of tListeners) {
+            try {
+                fn(indexed);
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+    // Notify per-session listeners (SSE connections) -------------------------
+    const sListeners = sessionListeners.get(sessionKey);
+    if (sListeners) {
+        for (const fn of sListeners) {
+            try {
+                fn(indexed);
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Subscribe — per-turn
+// ---------------------------------------------------------------------------
+/**
+ * Subscribe to live events for a specific turn.
+ *
+ * Immediately delivers all buffered events for this turn to `listener`
+ * (replay-on-subscribe), then delivers live events until the returned
+ * unsubscribe function is called.
+ *
+ * Returns `undefined` rather than calling listener if the turn is unknown
+ * and there are no buffered events — the caller is responsible for falling
+ * back to SQLite if needed.
+ */
+export function subscribeTurn(turnId, listener) {
+    // Replay buffered events immediately
+    const entry = turnBuffers.get(turnId);
+    if (entry) {
+        for (const e of entry.buf.getAll()) {
+            try {
+                listener(e);
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+    // Register live listener
+    let ls = turnListeners.get(turnId);
+    if (!ls) {
+        ls = new Set();
+        turnListeners.set(turnId, ls);
+    }
+    ls.add(listener);
+    return () => {
+        const set = turnListeners.get(turnId);
+        if (set) {
+            set.delete(listener);
+            if (set.size === 0)
+                turnListeners.delete(turnId);
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Subscribe — per-session (SSE)
+// ---------------------------------------------------------------------------
+/**
+ * Subscribe to all turn events for a session (multi-tab SSE channel).
+ *
+ * If `afterSeq` is provided, replays only buffered events with `_seq > afterSeq`
+ * (supports `Last-Event-ID` reconnect).  Otherwise replays all buffered events.
+ *
+ * If the buffer doesn't cover the requested range (oldest buffered seq > afterSeq + 1),
+ * the caller should fall back to `getSessionEventsFromDb()` before calling this.
+ *
+ * Returns an unsubscribe function.
+ */
+export function subscribeSession(sessionKey, listener, afterSeq) {
+    // Replay from session buffer
+    const buf = sessionBuffers.get(sessionKey);
+    if (buf) {
+        const all = buf.getAll();
+        const toReplay = afterSeq !== undefined ? all.filter((e) => e._seq > afterSeq) : all;
+        for (const e of toReplay) {
+            try {
+                listener(e);
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+    // Register live listener
+    let ls = sessionListeners.get(sessionKey);
+    if (!ls) {
+        ls = new Set();
+        sessionListeners.set(sessionKey, ls);
+    }
+    ls.add(listener);
+    return () => {
+        const set = sessionListeners.get(sessionKey);
+        if (set) {
+            set.delete(listener);
+            if (set.size === 0)
+                sessionListeners.delete(sessionKey);
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+/**
+ * Persist the turn's buffered events to the `turn_events` SQLite table.
+ * Called on `turn:complete` and `turn:error` before scheduling the clear.
+ * No-ops silently if the turn has no buffered events.
+ */
+export function persistTurnEvents(turnId, sessionKey) {
+    const entry = turnBuffers.get(turnId);
+    if (!entry)
+        return;
+    const events = entry.buf.getAll();
+    if (events.length === 0)
+        return;
+    try {
+        const db = getDb();
+        const stmt = db.prepare(`INSERT OR IGNORE INTO turn_events (turn_id, session_key, seq, ts, event_type, payload)
+       VALUES (?, ?, ?, ?, ?, ?)`);
+        db.transaction(() => {
+            for (const e of events) {
+                stmt.run(turnId, sessionKey, e._seq, e._ts, e.type, JSON.stringify(e));
+            }
+        })();
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : err, turnId }, "turn-event-log: SQLite persist failed");
+    }
+}
+// ---------------------------------------------------------------------------
+// Lifecycle — clear
+// ---------------------------------------------------------------------------
+/**
+ * Schedule clearing of the per-turn ring buffer and listeners after `delayMs`.
+ * Any existing pending timer for this turnId is cancelled first.
+ *
+ * Defaults to TURN_CLEAR_GRACE_MS (30 s) to allow late reconnects to replay
+ * from memory rather than SQLite.
+ */
+export function scheduleClearTurnLog(turnId, delayMs = TURN_CLEAR_GRACE_MS) {
+    const existing = clearTimers.get(turnId);
+    if (existing)
+        clearTimeout(existing);
+    const timer = setTimeout(() => {
+        turnBuffers.delete(turnId);
+        turnListeners.delete(turnId);
+        clearTimers.delete(turnId);
+        log.debug({ turnId }, "turn-event-log: buffer cleared after grace window");
+    }, delayMs);
+    clearTimers.set(turnId, timer);
+}
+/**
+ * Immediately clear the per-turn buffer without waiting for the grace window.
+ * Used in tests and explicit eviction.
+ */
+export function clearTurnLog(turnId) {
+    const existing = clearTimers.get(turnId);
+    if (existing)
+        clearTimeout(existing);
+    clearTimers.delete(turnId);
+    turnBuffers.delete(turnId);
+    turnListeners.delete(turnId);
+}
+// ---------------------------------------------------------------------------
+// SQLite read-back (fallback for completed turns)
+// ---------------------------------------------------------------------------
+/**
+ * Return persisted events for a specific turn from SQLite.
+ * Used when the in-memory buffer has been cleared after the grace window.
+ */
+export function getTurnEventsFromDb(turnId, afterSeq = 0) {
+    try {
+        const db = getDb();
+        const rows = db
+            .prepare(`SELECT payload FROM turn_events WHERE turn_id = ? AND seq > ? ORDER BY seq ASC`)
+            .all(turnId, afterSeq);
+        return rows.map((r) => JSON.parse(r.payload));
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : err, turnId }, "turn-event-log: SQLite read failed");
+        return [];
+    }
+}
+/**
+ * Return persisted events for a session from SQLite, after a given sequence number.
+ * Used as SSE replay fallback when the session buffer doesn't cover the requested range.
+ */
+export function getSessionEventsFromDb(sessionKey, afterSeq = 0) {
+    try {
+        const db = getDb();
+        const rows = db
+            .prepare(`SELECT payload FROM turn_events
+          WHERE session_key = ? AND seq > ?
+          ORDER BY seq ASC
+          LIMIT 500`)
+            .all(sessionKey, afterSeq);
+        return rows.map((r) => JSON.parse(r.payload));
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : err, sessionKey }, "turn-event-log: SQLite session read failed");
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Diagnostics
+// ---------------------------------------------------------------------------
+/** Number of turns currently tracked in memory. Useful for tests. */
+export function turnLogSize() {
+    return turnBuffers.size;
+}
+/** Oldest _seq in the per-session buffer, or undefined if empty. */
+export function oldestSessionSeq(sessionKey) {
+    const buf = sessionBuffers.get(sessionKey);
+    if (!buf || buf.size === 0)
+        return undefined;
+    return buf.getAll()[0]._seq;
+}
+//# sourceMappingURL=turn-event-log.js.map

package/dist/copilot/turn-event-log.test.js

@@ -0,0 +1,326 @@
+/**
+ * Unit tests for src/copilot/turn-event-log.ts — #130
+ *
+ * Covers:
+ *  1. emitTurnEvent: pushes to per-turn buffer
+ *  2. emitTurnEvent: pushes to per-session buffer
+ *  3. emitTurnEvent: notifies per-turn listeners
+ *  4. emitTurnEvent: notifies per-session listeners
+ *  5. subscribeTurn: replays buffered events immediately
+ *  6. subscribeTurn: delivers live events after subscribe
+ *  7. subscribeTurn: unsub stops delivery
+ *  8. subscribeSession: replays all buffered events
+ *  9. subscribeSession: replays only afterSeq events on reconnect
+ * 10. subscribeSession: delivers live events after subscribe
+ * 11. subscribeSession: unsub stops delivery
+ * 12. scheduleClearTurnLog: clears buffer after delay
+ * 13. clearTurnLog: immediate clear
+ * 14. Multiple sessions tracked independently
+ * 15. turnLogSize: reflects active buffers
+ *
+ * Uses node:test (same pattern as existing *.test.ts files in this project).
+ * SQLite-dependent functions (persistTurnEvents, getSessionEventsFromDb) are
+ * tested in the integration suite to avoid needing a real DB here.
+ */
+import { describe, it, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { setTimeout as setTimeoutPromise } from "node:timers/promises";
+import { emitTurnEvent, subscribeTurn, subscribeSession, clearTurnLog, scheduleClearTurnLog, turnLogSize, oldestSessionSeq, TURN_BUFFER_CAPACITY, SESSION_BUFFER_CAPACITY, } from "./turn-event-log.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+let turnCounter = 0;
+let sessionCounter = 0;
+function freshTurnId() {
+    return `turn-test-${++turnCounter}-${Date.now()}`;
+}
+function freshSessionKey() {
+    return `session-test-${++sessionCounter}-${Date.now()}`;
+}
+function makeStarted(turnId, sessionKey) {
+    return { type: "turn:started", turnId, sessionKey, prompt: "hello" };
+}
+function makeDelta(turnId, sessionKey, text) {
+    return { type: "turn:delta", turnId, sessionKey, part: { type: "text", text } };
+}
+function makeComplete(turnId, sessionKey) {
+    return { type: "turn:complete", turnId, sessionKey, finalMessage: "done" };
+}
+// ---------------------------------------------------------------------------
+// Teardown: clear each turn/session used in a test to avoid cross-test pollution
+// ---------------------------------------------------------------------------
+const usedTurnIds = [];
+const registeredUnsubs = [];
+afterEach(() => {
+    // Clean up registered subscriptions
+    for (const fn of registeredUnsubs.splice(0)) {
+        try {
+            fn();
+        }
+        catch { /* already unsub'd */ }
+    }
+    // Clear turn buffers
+    for (const id of usedTurnIds.splice(0)) {
+        clearTurnLog(id);
+    }
+});
+function trackTurn(turnId) {
+    usedTurnIds.push(turnId);
+    return turnId;
+}
+function trackUnsub(fn) {
+    registeredUnsubs.push(fn);
+    return fn;
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe("turn-event-log", () => {
+    describe("emitTurnEvent", () => {
+        it("assigns a monotonically increasing _seq", () => {
+            const session = freshSessionKey();
+            const turn1 = trackTurn(freshTurnId());
+            const turn2 = trackTurn(freshTurnId());
+            const collected = [];
+            trackUnsub(subscribeSession(session, (e) => collected.push(e)));
+            emitTurnEvent(session, makeStarted(turn1, session));
+            emitTurnEvent(session, makeStarted(turn2, session));
+            assert.equal(collected.length, 2);
+            assert.ok(collected[0]._seq < collected[1]._seq, "_seq must be strictly increasing");
+        });
+        it("attaches a _ts timestamp (ms epoch)", () => {
+            const before = Date.now();
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            const collected = [];
+            trackUnsub(subscribeSession(session, (e) => collected.push(e)));
+            emitTurnEvent(session, makeStarted(turnId, session));
+            const after = Date.now();
+            assert.ok(collected[0]._ts >= before && collected[0]._ts <= after);
+        });
+    });
+    describe("subscribeTurn", () => {
+        it("replays existing buffered events immediately on subscribe", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            emitTurnEvent(session, makeStarted(turnId, session));
+            emitTurnEvent(session, makeDelta(turnId, session, "chunk1"));
+            const received = [];
+            trackUnsub(subscribeTurn(turnId, (e) => received.push(e)));
+            assert.equal(received.length, 2, "should replay 2 buffered events immediately");
+            assert.equal(received[0].type, "turn:started");
+            assert.equal(received[1].type, "turn:delta");
+        });
+        it("delivers live events after subscribe", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            const received = [];
+            trackUnsub(subscribeTurn(turnId, (e) => received.push(e)));
+            emitTurnEvent(session, makeStarted(turnId, session));
+            emitTurnEvent(session, makeDelta(turnId, session, "live"));
+            assert.equal(received.length, 2);
+        });
+        it("replay + live: receives buffered then subsequent events", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            emitTurnEvent(session, makeStarted(turnId, session));
+            const received = [];
+            trackUnsub(subscribeTurn(turnId, (e) => received.push(e)));
+            // 1 replayed
+            assert.equal(received.length, 1);
+            emitTurnEvent(session, makeDelta(turnId, session, "live-delta"));
+            // 1 replayed + 1 live
+            assert.equal(received.length, 2);
+            assert.equal(received[1].type, "turn:delta");
+        });
+        it("unsubscribe stops live delivery", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            const received = [];
+            const unsub = subscribeTurn(turnId, (e) => received.push(e));
+            emitTurnEvent(session, makeStarted(turnId, session));
+            assert.equal(received.length, 1);
+            unsub(); // stop listening
+            emitTurnEvent(session, makeDelta(turnId, session, "after-unsub"));
+            assert.equal(received.length, 1, "should not receive events after unsub");
+        });
+        it("multiple subscribers to the same turn all receive events", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            const a = [];
+            const b = [];
+            trackUnsub(subscribeTurn(turnId, (e) => a.push(e)));
+            trackUnsub(subscribeTurn(turnId, (e) => b.push(e)));
+            emitTurnEvent(session, makeStarted(turnId, session));
+            assert.equal(a.length, 1);
+            assert.equal(b.length, 1);
+        });
+    });
+    describe("subscribeSession", () => {
+        it("replays all buffered session events on subscribe (no afterSeq)", () => {
+            const session = freshSessionKey();
+            const turn1 = trackTurn(freshTurnId());
+            const turn2 = trackTurn(freshTurnId());
+            emitTurnEvent(session, makeStarted(turn1, session));
+            emitTurnEvent(session, makeComplete(turn2, session));
+            const received = [];
+            trackUnsub(subscribeSession(session, (e) => received.push(e)));
+            assert.equal(received.length, 2);
+        });
+        it("replays only events after afterSeq on reconnect", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            emitTurnEvent(session, makeStarted(turnId, session));
+            const seqAfterFirst = oldestSessionSeq(session) + 1; // seqAfterFirst > first event's seq
+            emitTurnEvent(session, makeDelta(turnId, session, "second"));
+            // Collect first subscribe (simulates initial connection)
+            const first = [];
+            const unsub1 = subscribeSession(session, (e) => first.push(e));
+            unsub1();
+            // Remember the seq of the last event we saw
+            const lastSeenSeq = first[first.length - 1]._seq;
+            emitTurnEvent(session, makeDelta(turnId, session, "third"));
+            // Reconnect with Last-Event-ID = lastSeenSeq
+            const reconnect = [];
+            trackUnsub(subscribeSession(session, (e) => reconnect.push(e), lastSeenSeq));
+            // Should only replay the "third" event (emitted after lastSeenSeq)
+            assert.ok(reconnect.every((e) => e._seq > lastSeenSeq), "replayed events must all have _seq > lastSeenSeq");
+            assert.equal(reconnect.length, 1);
+            assert.equal(reconnect[0].part.text, "third");
+            void seqAfterFirst; // suppress unused var warning
+        });
+        it("delivers live events after subscribe", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            const received = [];
+            trackUnsub(subscribeSession(session, (e) => received.push(e)));
+            emitTurnEvent(session, makeStarted(turnId, session));
+            assert.equal(received.length, 1);
+        });
+        it("unsubscribe stops delivery", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            const received = [];
+            const unsub = subscribeSession(session, (e) => received.push(e));
+            emitTurnEvent(session, makeStarted(turnId, session));
+            assert.equal(received.length, 1);
+            unsub();
+            emitTurnEvent(session, makeComplete(turnId, session));
+            assert.equal(received.length, 1);
+        });
+        it("two sessions are isolated from each other", () => {
+            const session1 = freshSessionKey();
+            const session2 = freshSessionKey();
+            const turn1 = trackTurn(freshTurnId());
+            const turn2 = trackTurn(freshTurnId());
+            const recv1 = [];
+            const recv2 = [];
+            trackUnsub(subscribeSession(session1, (e) => recv1.push(e)));
+            trackUnsub(subscribeSession(session2, (e) => recv2.push(e)));
+            emitTurnEvent(session1, makeStarted(turn1, session1));
+            emitTurnEvent(session2, makeStarted(turn2, session2));
+            assert.equal(recv1.length, 1);
+            assert.equal(recv2.length, 1);
+            assert.equal(recv1[0].turnId, turn1);
+            assert.equal(recv2[0].turnId, turn2);
+        });
+    });
+    describe("clearTurnLog", () => {
+        it("removes the per-turn buffer immediately", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            emitTurnEvent(session, makeStarted(turnId, session));
+            clearTurnLog(turnId);
+            // Subscribing after clear should receive no replayed events
+            const received = [];
+            trackUnsub(subscribeTurn(turnId, (e) => received.push(e)));
+            assert.equal(received.length, 0, "buffer should be empty after clearTurnLog");
+        });
+        it("does not affect other turns", () => {
+            const session = freshSessionKey();
+            const turn1 = trackTurn(freshTurnId());
+            const turn2 = trackTurn(freshTurnId());
+            emitTurnEvent(session, makeStarted(turn1, session));
+            emitTurnEvent(session, makeStarted(turn2, session));
+            clearTurnLog(turn1);
+            const received = [];
+            trackUnsub(subscribeTurn(turn2, (e) => received.push(e)));
+            assert.equal(received.length, 1, "turn2 buffer should be unaffected");
+        });
+    });
+    describe("scheduleClearTurnLog", () => {
+        it("clears the buffer after the specified delay", async () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            emitTurnEvent(session, makeStarted(turnId, session));
+            scheduleClearTurnLog(turnId, 50); // 50 ms delay for testing
+            // Before delay: buffer still populated
+            {
+                const received = [];
+                const unsub = subscribeTurn(turnId, (e) => received.push(e));
+                unsub();
+                assert.equal(received.length, 1, "buffer should exist before grace window");
+            }
+            await setTimeoutPromise(100); // wait for the grace window
+            // After delay: buffer cleared
+            {
+                const received = [];
+                trackUnsub(subscribeTurn(turnId, (e) => received.push(e)));
+                assert.equal(received.length, 0, "buffer should be cleared after grace window");
+            }
+        });
+        it("cancels a previous pending timer when called twice", async () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            emitTurnEvent(session, makeStarted(turnId, session));
+            scheduleClearTurnLog(turnId, 30);
+            scheduleClearTurnLog(turnId, 200); // reset to longer delay
+            await setTimeoutPromise(60); // first timer would have fired
+            // Buffer should still exist because we reset the timer
+            {
+                const received = [];
+                const unsub = subscribeTurn(turnId, (e) => received.push(e));
+                unsub();
+                assert.equal(received.length, 1, "buffer should not be cleared yet (timer was reset)");
+            }
+            // Clean up before test ends
+            clearTurnLog(turnId);
+        });
+    });
+    describe("turnLogSize", () => {
+        it("reflects the number of active turn buffers", () => {
+            const session = freshSessionKey();
+            const before = turnLogSize();
+            const turnId = trackTurn(freshTurnId());
+            emitTurnEvent(session, makeStarted(turnId, session));
+            assert.ok(turnLogSize() >= before + 1, "size should increase after emit");
+            clearTurnLog(turnId);
+            assert.ok(turnLogSize() <= before, "size should decrease after clear");
+        });
+    });
+    describe("capacity", () => {
+        it("session buffer evicts oldest when SESSION_BUFFER_CAPACITY is reached", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            // Overfill the session buffer
+            for (let i = 0; i < SESSION_BUFFER_CAPACITY + 10; i++) {
+                emitTurnEvent(session, makeDelta(turnId, session, `chunk-${i}`));
+            }
+            const received = [];
+            trackUnsub(subscribeSession(session, (e) => received.push(e)));
+            // Should only have SESSION_BUFFER_CAPACITY items (oldest evicted)
+            assert.equal(received.length, SESSION_BUFFER_CAPACITY);
+        });
+        it("turn buffer evicts oldest when TURN_BUFFER_CAPACITY is reached", () => {
+            const session = freshSessionKey();
+            const turnId = trackTurn(freshTurnId());
+            for (let i = 0; i < TURN_BUFFER_CAPACITY + 5; i++) {
+                emitTurnEvent(session, makeDelta(turnId, session, `chunk-${i}`));
+            }
+            const received = [];
+            trackUnsub(subscribeTurn(turnId, (e) => received.push(e)));
+            assert.equal(received.length, TURN_BUFFER_CAPACITY);
+        });
+    });
+});
+//# sourceMappingURL=turn-event-log.test.js.map

package/dist/copilot/turn-events.js

@@ -0,0 +1,11 @@
+/**
+ * Turn event types for the per-session SSE channel (#130).
+ *
+ * These mirror the `Part` discriminated union from `web/src/api-schemas.ts` for use
+ * on the daemon side without a cross-package import.  Keep in sync when the frontend
+ * type changes.
+ *
+ * @module copilot/turn-events
+ */
+export {};
+//# sourceMappingURL=turn-events.js.map

package/dist/store/db.js

@@ -175,6 +175,21 @@ export function getDb() {
             // Backfill from loaded_at so sidebar is not empty for existing projects
             db.exec(`UPDATE project_squads SET last_used_at = CAST((julianday(loaded_at) - 2440587.5) * 86400000 AS INTEGER) WHERE last_used_at IS NULL`);
         }
+        // turn_events: append-only per-turn event log for the SSE chat channel (#130).
+        // Events are written on turn completion; ring buffer serves live/recent replay.
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS turn_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        turn_id TEXT NOT NULL,
+        session_key TEXT NOT NULL DEFAULT 'default',
+        seq INTEGER NOT NULL,
+        ts INTEGER NOT NULL,
+        event_type TEXT NOT NULL,
+        payload TEXT NOT NULL
+      )
+    `);
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_turn_events_turn_id ON turn_events(turn_id, seq)`);
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_turn_events_session_key ON turn_events(session_key, seq)`);
         // Prune conversation log at startup — keep more history for better recovery
         db.prepare(`DELETE FROM conversation_log WHERE id NOT IN (SELECT id FROM conversation_log ORDER BY id DESC LIMIT 1000)`).run();
         // Set up FTS5 for memory search (graceful fallback if not available)

package/package.json

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