@spark-strategic/helix-core 0.2.4 → 0.2.5

package/dist/__tests__/connector-chat-durability.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * End-to-end smoke of the durable chat turn store wired into the helix-core Connector
+ * (the @spark-strategic/helix-chat store, vendored into src/chat).
+ *
+ * Drives a REAL Connector against a throwaway in-process WebSocket server: the server
+ * plays agents-api (sends chat_start → chat_message, collects the connector's outbound
+ * frames), the Connector runs the turn through a test adapter, and we then read the
+ * on-disk chat-turn record to prove the turn was persisted as its frames streamed.
+ *
+ * The point is crash-durability: the on-disk record outlives the process. The key case
+ * is a FAILED turn — even then the partial streamed content and the terminal verdict are
+ * on disk, which is exactly the state a boot reconcile would read after a crash.
+ *
+ * Self-running (mirrors helix-os's test style): `ts-node connector-chat-durability.test.ts`.
+ */
+export {};
+//# sourceMappingURL=connector-chat-durability.test.d.ts.map

package/dist/__tests__/connector-chat-durability.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-chat-durability.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/connector-chat-durability.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/__tests__/connector-chat-durability.test.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * End-to-end smoke of the durable chat turn store wired into the helix-core Connector
+ * (the @spark-strategic/helix-chat store, vendored into src/chat).
+ *
+ * Drives a REAL Connector against a throwaway in-process WebSocket server: the server
+ * plays agents-api (sends chat_start → chat_message, collects the connector's outbound
+ * frames), the Connector runs the turn through a test adapter, and we then read the
+ * on-disk chat-turn record to prove the turn was persisted as its frames streamed.
+ *
+ * The point is crash-durability: the on-disk record outlives the process. The key case
+ * is a FAILED turn — even then the partial streamed content and the terminal verdict are
+ * on disk, which is exactly the state a boot reconcile would read after a crash.
+ *
+ * Self-running (mirrors helix-os's test style): `ts-node connector-chat-durability.test.ts`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = __importDefault(require("node:assert"));
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const ws_1 = require("ws");
+const connector_1 = require("../connector");
+const adapter_1 = require("../adapter");
+const chat_store_1 = require("../chat/chat-store");
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'helix-core-chat-'));
+const silent = { debug() { }, info() { }, warn() { }, error() { } };
+/** Run one turn against a fresh local server + Connector, return the collected outbound
+ *  frames once the turn reaches a terminal (chat_done / chat_error). */
+function runTurn(adapter, sessionId, message) {
+    return new Promise((resolve, reject) => {
+        const frames = [];
+        const wss = new ws_1.WebSocketServer({ port: 0 }, () => {
+            const port = wss.address().port;
+            const connector = new connector_1.Connector({
+                config: { agentsApiUrl: `http://127.0.0.1:${port}`, slug: 'test', key: 'k' },
+                adapter,
+                client: { name: 'test', version: '0.0.0' },
+                logger: silent,
+                dataDir: TMP,
+            });
+            const done = (err) => {
+                try {
+                    connector.stop();
+                }
+                catch { /* ignore */ }
+                try {
+                    wss.close();
+                }
+                catch { /* ignore */ }
+                if (err)
+                    reject(err);
+                else
+                    resolve(frames);
+            };
+            const timeout = setTimeout(() => done(new Error('turn did not terminate in time')), 5000);
+            wss.on('connection', (ws) => {
+                ws.on('message', (data) => {
+                    let frame;
+                    try {
+                        frame = JSON.parse(data.toString());
+                    }
+                    catch {
+                        return;
+                    }
+                    if (frame.type === 'connector_hello') {
+                        // Kick the turn: enable the composer, then deliver the message.
+                        ws.send(JSON.stringify({ type: 'chat_start', payload: { sessionId } }));
+                        ws.send(JSON.stringify({ type: 'chat_message', payload: { sessionId, message, agentId: 'agent-x', model: 'test-model' } }));
+                        return;
+                    }
+                    frames.push(frame);
+                    if (frame.type === 'chat_done' || frame.type === 'chat_error') {
+                        clearTimeout(timeout);
+                        // Give the store's synchronous terminal flush a tick to settle, then finish.
+                        setTimeout(() => done(), 50);
+                    }
+                });
+            });
+            connector.start();
+        });
+        wss.on('error', reject);
+    });
+}
+/** Like runTurn, but after chat_done the server echoes a `chat_ack` carrying that frame's
+ *  turnId — the real agents-api §3.2 round-trip — so we can prove the connector evicts its
+ *  local record on ack. Resolves with the acked turnId once the ack has had a tick to land. */
+function runTurnThenAck(adapter, sessionId, message) {
+    return new Promise((resolve, reject) => {
+        const wss = new ws_1.WebSocketServer({ port: 0 }, () => {
+            const port = wss.address().port;
+            const connector = new connector_1.Connector({
+                config: { agentsApiUrl: `http://127.0.0.1:${port}`, slug: 'test', key: 'k' },
+                adapter,
+                client: { name: 'test', version: '0.0.0' },
+                logger: silent,
+                dataDir: TMP,
+            });
+            const done = (err, turnId) => {
+                try {
+                    connector.stop();
+                }
+                catch { /* ignore */ }
+                try {
+                    wss.close();
+                }
+                catch { /* ignore */ }
+                if (err)
+                    reject(err);
+                else
+                    resolve({ turnId });
+            };
+            const timeout = setTimeout(() => done(new Error('turn did not terminate in time')), 5000);
+            wss.on('connection', (ws) => {
+                ws.on('message', (data) => {
+                    let frame;
+                    try {
+                        frame = JSON.parse(data.toString());
+                    }
+                    catch {
+                        return;
+                    }
+                    if (frame.type === 'connector_hello') {
+                        ws.send(JSON.stringify({ type: 'chat_start', payload: { sessionId } }));
+                        ws.send(JSON.stringify({ type: 'chat_message', payload: { sessionId, message, agentId: 'agent-x', model: 'test-model' } }));
+                        return;
+                    }
+                    if (frame.type === 'chat_done') {
+                        clearTimeout(timeout);
+                        const turnId = typeof frame.turnId === 'string' ? frame.turnId : undefined;
+                        // Echo the §3.2 ack exactly as agents-api's ackFinalWriteToNode does, keyed by
+                        // the done frame's turnId, then give the connector's handler a tick to evict.
+                        ws.send(JSON.stringify({ type: 'chat_ack', payload: { sessionId, turnId } }));
+                        setTimeout(() => done(undefined, turnId), 100);
+                    }
+                });
+            });
+            connector.start();
+        });
+        wss.on('error', reject);
+    });
+}
+function recordFor(sessionId) {
+    const recs = (0, chat_store_1.recordsForSession)(sessionId);
+    node_assert_1.default.equal(recs.length, 1, `exactly one durable record for ${sessionId} (got ${recs.length})`);
+    return recs[0];
+}
+/** Adapter that streams one delta then throws — a failed turn with partial output. */
+class FailAfterDeltaAdapter {
+    name = 'fail';
+    version = '0.0.0';
+    async runTurn(_ctx, emit) {
+        emit.delta('partial answer before the crash');
+        await new Promise((r) => setTimeout(r, 10));
+        throw new Error('adapter blew up');
+    }
+}
+/** Adapter that runs one tool (call → result) then completes. */
+class ToolAdapter {
+    name = 'tool';
+    version = '0.0.0';
+    async runTurn(_ctx, emit) {
+        emit.tool('lookup', 'call');
+        await new Promise((r) => setTimeout(r, 10));
+        emit.tool('lookup', 'result', true);
+        emit.delta('done');
+    }
+}
+async function main() {
+    // 1. Healthy turn: full content buffered, marked complete + done.
+    const okFrames = await runTurn(new adapter_1.EchoAdapter(), 'sess-ok', 'hello');
+    node_assert_1.default.ok(okFrames.some((f) => f.type === 'chat_done'), 'healthy turn emits chat_done');
+    const ok = recordFor('sess-ok');
+    node_assert_1.default.equal(ok.content, 'You said: hello', 'full streamed content is durable on disk');
+    node_assert_1.default.equal(ok.stream.complete, true, 'stream marked complete');
+    node_assert_1.default.equal(ok.final.written, true, 'final write flagged');
+    node_assert_1.default.equal(ok.terminalReason, 'done', 'terminal reason is done');
+    node_assert_1.default.ok(ok.stream.lastStreamSeq > 0, 'at least one stream frame recorded');
+    node_assert_1.default.equal(ok.model, 'test-model', 'model recorded from the inbound frame');
+    node_assert_1.default.equal(ok.agentId, 'agent-x', 'agentId recorded from the inbound frame');
+    console.log('✓ healthy turn: full content + complete + done persisted');
+    // 2. FAILED turn: the key crash-durability case — partial content AND the error
+    //    verdict are on disk even though the turn never completed.
+    const failFrames = await runTurn(new FailAfterDeltaAdapter(), 'sess-fail', 'go');
+    node_assert_1.default.ok(failFrames.some((f) => f.type === 'chat_error'), 'failed turn emits chat_error');
+    const fail = recordFor('sess-fail');
+    node_assert_1.default.equal(fail.content, 'partial answer before the crash', 'partial streamed content survives a failure');
+    node_assert_1.default.equal(fail.stream.complete, false, 'stream NOT complete on failure');
+    node_assert_1.default.equal(fail.terminalReason, 'error', 'terminal reason is error');
+    node_assert_1.default.equal(fail.errorMessage, 'adapter blew up', 'error message persisted');
+    console.log('✓ failed turn: partial content + error verdict persisted (the crash-recovery coordinate)');
+    // 3. Tool turn: the ledger records the call and resolves it by name (no wire tool_use id).
+    const toolFrames = await runTurn(new ToolAdapter(), 'sess-tool', 'run tool');
+    node_assert_1.default.ok(toolFrames.some((f) => f.type === 'chat_done'), 'tool turn completes');
+    const tool = recordFor('sess-tool');
+    node_assert_1.default.equal(tool.tools.length, 1, 'one tool ledger entry');
+    node_assert_1.default.equal(tool.tools[0].name, 'lookup', 'tool name recorded');
+    node_assert_1.default.equal(tool.tools[0].state, 'executed', 'tool resolved to executed');
+    node_assert_1.default.equal(tool.tools[0].ok, true, 'tool result ok recorded');
+    console.log('✓ tool turn: ledger records call + result (name-resolved, fail-closed effect class)');
+    // 4. §3.2 ack round-trip: chat_done carries the turn's node-local store id; the server
+    //    echoes it as chat_ack; the connector's handler calls markAcked → the local record
+    //    flips acked/evicted and its heavy content is dropped (the server now owns the
+    //    durable copy). This is the authoritative close, faithful to helix-os.
+    const { turnId } = await runTurnThenAck(new adapter_1.EchoAdapter(), 'sess-ack', 'ack me');
+    node_assert_1.default.ok(turnId, 'chat_done carried a turnId for the server to ack');
+    const acked = recordFor('sess-ack');
+    node_assert_1.default.equal(acked.final.acked, true, 'record flipped acked on chat_ack');
+    node_assert_1.default.equal(acked.final.evicted, true, 'record evicted on ack');
+    node_assert_1.default.equal(acked.content, '', 'heavy content dropped once the server owns the durable copy');
+    console.log('✓ ack round-trip: chat_done→chat_ack evicts the node-local record (§3.2)');
+    fs.rmSync(TMP, { recursive: true, force: true });
+    console.log('\n✓ connector chat durability: healthy + failed + tool + ack turns all persisted node-side');
+}
+main().catch((err) => {
+    console.error('✗ connector-chat-durability test failed:', err);
+    try {
+        fs.rmSync(TMP, { recursive: true, force: true });
+    }
+    catch { /* ignore */ }
+    process.exit(1);
+});
+//# sourceMappingURL=connector-chat-durability.test.js.map

package/dist/__tests__/connector-chat-durability.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-chat-durability.test.js","sourceRoot":"","sources":["../../src/__tests__/connector-chat-durability.test.ts"],"names":[],"mappings":"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"}

package/dist/chat/chat-reconcile.d.ts

@@ -0,0 +1,44 @@
+import { type ChatTurnRecord, type ReconcileDisposition, type ToolReconcileOutcome } from './chat-store';
+/**
+ * The §5.1 policy table as a pure function: an effect class → its reconcile
+ * disposition. Unknown/undeclared classes fail closed to `needs-agent-review`.
+ * Pure w.r.t. IO — the deterministic heart the whole reconciler is built around.
+ */
+export declare function dispositionForEffectClass(effectClass: string | undefined): ReconcileDisposition;
+/** One turn's reconcile plan — the per-gap verdicts, computed purely from the record. */
+export interface TurnReconcilePlan {
+    turnId: string;
+    sessionId: string;
+    agentId?: string;
+    outcomes: ToolReconcileOutcome[];
+}
+/**
+ * Compute (but do not write) the reconcile plan for one sealed turn: apply the policy
+ * table to every ledger gap. Pure — no IO, no mutation — so the policy is unit-testable
+ * in isolation from the boot scan.
+ */
+export declare function planTurnReconcile(rec: ChatTurnRecord): TurnReconcilePlan;
+export interface ReconcileSummary {
+    /** Turns that needed a pass (had an unreconciled gap). */
+    scanned: number;
+    /** Turns whose verdict was written durably this pass. */
+    reconciled: number;
+    /** Gap entries by disposition across all reconciled turns. */
+    resolvedSafe: number;
+    needsVerify: number;
+    needsAgentReview: number;
+}
+/**
+ * Boot reconcile: walk every interrupted turn still owing a §5.1 pass, apply the policy
+ * table to its ledger gaps, and write the verdict back durably. Returns a summary.
+ *
+ * Runs ONCE per boot (every record on disk predates this process, so a gap is always a
+ * prior life's interrupted turn, never a live one). A turn is visited at most once —
+ * `reconcileTurnRecord` stamps `reconciledAt` and the selector excludes anything stamped
+ * — so a crash-loop never re-reconciles. Each `needs-agent-review` / `needs-verify` gap
+ * is logged (agent + session + tool + class) so the residual is visible in the node log
+ * even before the agent's next turn consumes it. Fail-soft: a per-turn error is logged
+ * and skipped; the pass always returns.
+ */
+export declare function reconcileInterruptedChatTurnsOnBoot(): ReconcileSummary;
+//# sourceMappingURL=chat-reconcile.d.ts.map

package/dist/chat/chat-reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-reconcile.d.ts","sourceRoot":"","sources":["../../src/chat/chat-reconcile.ts"],"names":[],"mappings":"AAmDA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAMtB;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,oBAAoB,CAY/F;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,iBAAiB,CAaxE;AAED,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mCAAmC,IAAI,gBAAgB,CA0DtE"}

package/dist/chat/chat-reconcile.js

@@ -0,0 +1,175 @@
+"use strict";
+// ============================================================================
+// GENERATED — DO NOT EDIT.
+// Vendored from @spark-strategic/helix-chat (auxiliary/helix-chat/src/chat-reconcile.ts) by
+// helix-core/scripts/vendor-helix-chat.js at build time. Edit the canonical file
+// in @spark-strategic/helix-chat and rebuild; changes made directly here will be overwritten.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispositionForEffectClass = dispositionForEffectClass;
+exports.planTurnReconcile = planTurnReconcile;
+exports.reconcileInterruptedChatTurnsOnBoot = reconcileInterruptedChatTurnsOnBoot;
+/**
+ * §5.1 tool-call reconciler — the resume-path actor.
+ *
+ * The chat store (`chat-store.ts`) RECORDS the coordinates of an interrupted turn:
+ * each tool invocation writes `started` before `executed` (side-effect ordering), and
+ * a turn sealed without a terminal frame leaves its in-flight calls as a `started &&
+ * !executed` gap (`indeterminate` once sealed, or raw `started` after a hard crash
+ * that killed the stream loop before `seal` ran). This module is what READS that
+ * sealed ledger on node boot and applies the §5.1 policy table — the half the store
+ * deliberately left to "the resume path."
+ *
+ * The policy is DETERMINISTIC by the tool's declared effect class, never by asking the
+ * user (spec §5.1):
+ *
+ *   | class                      | policy                                    | disposition         |
+ *   |----------------------------|-------------------------------------------|---------------------|
+ *   | pure / read                | re-run freely (no side effect)            | resolved-safe       |
+ *   | idempotent-keyed           | re-run; tool collapses the dup by its key | resolved-safe       |
+ *   | verifiable                 | verify reality by key, re-run if absent   | needs-verify        |
+ *   | irreversible-unverifiable  | fail CLOSED — never auto-replay           | needs-agent-review  |
+ *
+ * DEFAULT IS FAIL-CLOSED. An undeclared/undeterminable class is read as
+ * `irreversible-unverifiable` → `needs-agent-review`: re-running is an opt-in a tool
+ * EARNS by declaring a safe class. This biases every ambiguous gap toward NOT repeating
+ * a side effect — a missed re-run is recoverable by the user, a duplicated irreversible
+ * side effect often is not.
+ *
+ * What this reconciler does NOT do, by design (spec §5.2 "node loss → close"): it does
+ * not resurrect or re-execute the interrupted turn. The turn is already sealed/closed;
+ * there is no handoff and no migration. The reconciler's job is to resolve the ledger
+ * into its correct final state and SURFACE the residual — the actual re-run / verify /
+ * resend happens when the AGENT next runs (§5.1 residual handling: it reads the
+ * agent-facing reconcile task and resolves it itself via a sibling verify tool, or the
+ * user's next action answers it, re-entering the normal consent gate — never a
+ * privileged rerun fast-path). A `needs-agent-review`/`needs-verify` disposition is the
+ * durable breadcrumb that reconcile task is built from; the §5.3 inspect command reads
+ * it per entry.
+ *
+ * Idempotent: a turn is stamped `reconciledAt` once visited, so a reboot loop never
+ * re-reconciles. Fail-soft throughout — reconcile is recovery instrumentation and must
+ * never break boot (the standing §0 principle the whole store honors).
+ */
+const chat_store_context_1 = require("./chat-store-context");
+const chat_store_1 = require("./chat-store");
+/** The fail-closed default an undeclared/unknown effect class collapses to. Mirrors
+ *  `local-tools.ts` DEFAULT_EFFECT_CLASS / the store's FAIL_CLOSED_EFFECT_CLASS. */
+const FAIL_CLOSED_EFFECT_CLASS = 'irreversible-unverifiable';
+/**
+ * The §5.1 policy table as a pure function: an effect class → its reconcile
+ * disposition. Unknown/undeclared classes fail closed to `needs-agent-review`.
+ * Pure w.r.t. IO — the deterministic heart the whole reconciler is built around.
+ */
+function dispositionForEffectClass(effectClass) {
+    switch (effectClass) {
+        case 'pure':
+        case 'read':
+        case 'idempotent-keyed':
+            return 'resolved-safe';
+        case 'verifiable':
+            return 'needs-verify';
+        case 'irreversible-unverifiable':
+        default:
+            return 'needs-agent-review'; // fail closed: undeclared ⇒ assume irreversible
+    }
+}
+/**
+ * Compute (but do not write) the reconcile plan for one sealed turn: apply the policy
+ * table to every ledger gap. Pure — no IO, no mutation — so the policy is unit-testable
+ * in isolation from the boot scan.
+ */
+function planTurnReconcile(rec) {
+    const outcomes = [];
+    for (const entry of rec.tools) {
+        if (!(0, chat_store_1.isReconcileGap)(entry))
+            continue; // executed ⇒ no gap to reconcile
+        const effectClass = entry.effectClass || FAIL_CLOSED_EFFECT_CLASS;
+        outcomes.push({
+            ordinal: entry.ordinal,
+            ...(entry.toolCallId ? { toolCallId: entry.toolCallId } : {}),
+            disposition: dispositionForEffectClass(effectClass),
+            effectClass,
+        });
+    }
+    return { turnId: rec.turnId, sessionId: rec.sessionId, agentId: rec.agentId, outcomes };
+}
+/**
+ * Boot reconcile: walk every interrupted turn still owing a §5.1 pass, apply the policy
+ * table to its ledger gaps, and write the verdict back durably. Returns a summary.
+ *
+ * Runs ONCE per boot (every record on disk predates this process, so a gap is always a
+ * prior life's interrupted turn, never a live one). A turn is visited at most once —
+ * `reconcileTurnRecord` stamps `reconciledAt` and the selector excludes anything stamped
+ * — so a crash-loop never re-reconciles. Each `needs-agent-review` / `needs-verify` gap
+ * is logged (agent + session + tool + class) so the residual is visible in the node log
+ * even before the agent's next turn consumes it. Fail-soft: a per-turn error is logged
+ * and skipped; the pass always returns.
+ */
+function reconcileInterruptedChatTurnsOnBoot() {
+    const logger = (0, chat_store_context_1.getChatStoreContext)().logger;
+    const summary = {
+        scanned: 0, reconciled: 0, resolvedSafe: 0, needsVerify: 0, needsAgentReview: 0,
+    };
+    let turns;
+    try {
+        turns = (0, chat_store_1.listTurnsNeedingReconcile)();
+    }
+    catch (err) {
+        logger.warn('Chat reconcile: failed to list interrupted turns; skipping', { error: String(err) });
+        return summary;
+    }
+    for (const rec of turns) {
+        summary.scanned++;
+        try {
+            const plan = planTurnReconcile(rec);
+            if (plan.outcomes.length === 0)
+                continue; // gap vanished between list and read
+            const wrote = (0, chat_store_1.reconcileTurnRecord)(rec.turnId, plan.outcomes);
+            if (!wrote)
+                continue; // already reconciled by a racing pass / unknown — idempotent
+            summary.reconciled++;
+            for (const o of plan.outcomes) {
+                if (o.disposition === 'resolved-safe')
+                    summary.resolvedSafe++;
+                else if (o.disposition === 'needs-verify')
+                    summary.needsVerify++;
+                else
+                    summary.needsAgentReview++;
+            }
+            // Surface the residual. `resolved-safe` gaps need no attention (a re-run would be
+            // free); the others are the agent-facing reconcile tasks the next turn resolves.
+            const residual = plan.outcomes.filter((o) => o.disposition !== 'resolved-safe');
+            if (residual.length > 0) {
+                const byOrdinal = new Map(rec.tools.map((t) => [t.ordinal, t.name]));
+                logger.warn('Chat reconcile: interrupted turn has unresolved tool side effects', {
+                    turnId: rec.turnId,
+                    sessionId: rec.sessionId,
+                    agentId: rec.agentId,
+                    residual: residual.map((o) => ({
+                        tool: byOrdinal.get(o.ordinal) ?? `#${o.ordinal}`,
+                        toolCallId: o.toolCallId,
+                        effectClass: o.effectClass,
+                        disposition: o.disposition,
+                    })),
+                });
+            }
+        }
+        catch (err) {
+            logger.warn('Chat reconcile: failed to reconcile a turn; leaving for next boot', {
+                turnId: rec.turnId, error: String(err),
+            });
+        }
+    }
+    if (summary.reconciled > 0) {
+        logger.info('Chat reconcile: applied §5.1 policy to interrupted turns', {
+            scanned: summary.scanned,
+            reconciled: summary.reconciled,
+            resolvedSafe: summary.resolvedSafe,
+            needsVerify: summary.needsVerify,
+            needsAgentReview: summary.needsAgentReview,
+        });
+    }
+    return summary;
+}
+//# sourceMappingURL=chat-reconcile.js.map

package/dist/chat/chat-reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-reconcile.js","sourceRoot":"","sources":["../../src/chat/chat-reconcile.ts"],"names":[],"mappings":"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"}

package/dist/chat/chat-store-context.d.ts

@@ -0,0 +1,25 @@
+/** The minimal logger the store/reconciler use. Structurally satisfied by winston's
+ *  `Logger` and by a plain console wrapper — the two hosts' loggers both fit. */
+export interface ChatLogger {
+    debug(msg: string, meta?: unknown): void;
+    info(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+    error(msg: string, meta?: unknown): void;
+}
+/** What the host injects. Both members are consulted lazily (see module header). */
+export interface ChatStoreContext {
+    /** Resolve the base data dir; the store writes under `<dataDir>/chat-turns`. Called
+     *  per operation so a host that mutates its config (or a test that points it at a
+     *  throwaway dir) is always honored at the moment of the write. */
+    resolveDataDir(): string;
+    /** Where the store's fail-soft diagnostics go. */
+    logger: ChatLogger;
+}
+/**
+ * Inject the host's data dir resolver + logger. Call once at boot. Idempotent — a later
+ * call simply replaces the context (useful for tests). Never throws.
+ */
+export declare function configureChatStore(ctx: ChatStoreContext): void;
+/** The active context, or the safe default if the host never configured. Never throws. */
+export declare function getChatStoreContext(): ChatStoreContext;
+//# sourceMappingURL=chat-store-context.d.ts.map

package/dist/chat/chat-store-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-store-context.d.ts","sourceRoot":"","sources":["../../src/chat/chat-store-context.ts"],"names":[],"mappings":"AAoCA;iFACiF;AACjF,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B;;uEAEmE;IACnE,cAAc,IAAI,MAAM,CAAC;IACzB,kDAAkD;IAClD,MAAM,EAAE,UAAU,CAAC;CACpB;AAgBD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAE9D;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,IAAI,gBAAgB,CAEtD"}