@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/worker/console/chat/chat-event-store.js

@@ -0,0 +1,981 @@
+/**
+ * Operator Chat — persisted event ring + reconnect support (roadmap M1-T03/T04/T07).
+ *
+ * Each Chat session owns a bounded event ring persisted to app-data. Every
+ * event gets a monotonic `seq` and an `eventId = "<sessionId>:<seq>"`, so a
+ * browser that refreshes mid-stream (or reconnects after a network blip) can
+ * resume via the SSE `Last-Event-ID` header.
+ *
+ * Live turn streaming: while a turn is in flight, in-memory subscriber
+ * callbacks are notified so an open `GET /events` connection (re)plays the
+ * retained tail and then follows the live stream. When no turn is active the
+ * endpoint simply replays the ring and closes (idempotent snapshot).
+ *
+ * Stale-turn fence (T07): each persisted event records its `turnId`. A
+ * reconnecting client that lost its `turnId` mid-stream compares the ring's
+ * latest `turnId` against the one it last saw; a mismatch is surfaced as a
+ * `reconcile` signal so the UI does not render stale events under a new turn.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import path from "node:path";
+import { ensureSecureDir, writeSecureJsonSync, } from "../app-data.js";
+import { isTerminalOperationState, } from "../operation-store.js";
+import { scrubSecrets } from "./explore-tools.js";
+const OPERATION_PREVIEW_MAX_CHARS = 1200;
+function boundedRedactedText(value, maxChars = OPERATION_PREVIEW_MAX_CHARS) {
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    const { scrubbed } = scrubSecrets(value);
+    return scrubbed.length <= maxChars
+        ? scrubbed
+        : `${scrubbed.slice(0, maxChars)}…[truncated]`;
+}
+function safeIdentity(value) {
+    return boundedRedactedText(value, 240);
+}
+function controllerSummary(operation) {
+    const identity = operation.controllerIdentity;
+    if (!identity || typeof identity !== "object")
+        return undefined;
+    const record = identity;
+    const fingerprint = typeof record.fingerprint === "string"
+        ? record.fingerprint
+        : typeof record.packageFingerprint
+            ?.value === "string"
+            ? String(record.packageFingerprint.value)
+            : undefined;
+    const label = [record.packageName, record.packageVersion, fingerprint]
+        .filter((part) => typeof part === "string" && part.length > 0)
+        .join("@");
+    return safeIdentity(label);
+}
+/** Re-project an already-safe stored run summary through a bounded re-check. */
+function safeRunSummaryProjection(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = value;
+    const runId = safeIdentity(record.runId);
+    const status = safeIdentity(record.status);
+    if (!runId || !status)
+        return undefined;
+    const nodes = Array.isArray(record.nodes)
+        ? record.nodes
+            .filter((node) => Boolean(node && typeof node === "object"))
+            .map((node) => ({
+            id: safeIdentity(node.id) ?? "",
+            status: safeIdentity(node.status) ?? "",
+        }))
+            .filter((node) => node.id && node.status)
+            .slice(0, 20)
+        : [];
+    const verdict = typeof record.verdict === "string"
+        ? boundedRedactedText(record.verdict)
+        : undefined;
+    const failureCategory = typeof record.failureCategory === "string"
+        ? boundedRedactedText(record.failureCategory)
+        : undefined;
+    const outOfBounds = Array.isArray(record.outOfBounds)
+        ? record.outOfBounds
+            .filter((entry) => Boolean(entry && typeof entry === "object"))
+            .map((entry) => ({
+            nodeId: safeIdentity(entry.nodeId) ?? "",
+            failureCategory: safeIdentity(entry.failureCategory) ?? "",
+        }))
+            .filter((entry) => entry.nodeId && entry.failureCategory)
+            .slice(0, 20)
+        : undefined;
+    const nextRec = record.next && typeof record.next === "object"
+        ? record.next
+        : undefined;
+    const next = nextRec
+        ? {
+            kind: safeIdentity(nextRec.kind) ?? "",
+            description: typeof nextRec.description === "string"
+                ? boundedRedactedText(nextRec.description)
+                : undefined,
+        }
+        : undefined;
+    return {
+        runId,
+        status,
+        nodes,
+        ...(verdict ? { verdict } : {}),
+        ...(failureCategory ? { failureCategory } : {}),
+        ...(outOfBounds && outOfBounds.length > 0 ? { outOfBounds } : {}),
+        ...(next && next.kind ? { next } : {}),
+    };
+}
+/** Chat/browser-safe projection. Never includes actionParams, CLI args, paths or raw results. */
+export function projectOperationForChat(operation) {
+    const params = operation.actionParams ?? {};
+    const stdoutPreview = boundedRedactedText(operation.stdoutPreview);
+    const stderrPreview = boundedRedactedText(operation.stderrPreview);
+    const summaryPreview = boundedRedactedText(operation.errorMessage);
+    const taskId = safeIdentity(operation.taskId ?? params.taskId);
+    const dagRunId = safeIdentity(operation.dagRunId ?? params.dagRunId ?? params.runId);
+    const featureId = safeIdentity(params.featureId);
+    const workerRunId = safeIdentity(params.workerRunId);
+    const controller = controllerSummary(operation);
+    const runSummary = safeRunSummaryProjection(operation.runSummary);
+    const previewHash = createHash("sha256")
+        .update(JSON.stringify({
+        stdoutPreview,
+        stderrPreview,
+        summaryPreview,
+        state: operation.state,
+        // runSummary participates in the dedupe hash: terminal summary updates
+        // must not be swallowed by state+previewHash dedup (2026-08-14).
+        runSummary: runSummary ?? null,
+    }))
+        .digest("hex");
+    return {
+        schemaVersion: 1,
+        operationId: operation.operationId,
+        action: operation.action,
+        state: operation.state,
+        createdAt: operation.createdAt,
+        updatedAt: operation.finishedAt ?? operation.startedAt ?? operation.createdAt,
+        inspectHref: `/inspect/?operationId=${encodeURIComponent(operation.operationId)}#/`,
+        ...(taskId ? { taskId } : {}),
+        ...(dagRunId ? { dagRunId } : {}),
+        ...(featureId ? { featureId } : {}),
+        ...(workerRunId ? { workerRunId } : {}),
+        ...(controller ? { controller } : {}),
+        ...(stdoutPreview ? { stdoutPreview } : {}),
+        ...(stderrPreview ? { stderrPreview } : {}),
+        ...(summaryPreview ? { summaryPreview } : {}),
+        ...(operation.errorCode
+            ? { errorCode: safeIdentity(operation.errorCode) }
+            : {}),
+        ...(runSummary ? { runSummary } : {}),
+        previewHash,
+    };
+}
+/** Action families that leave a user-inspectable durable outcome. */
+const ARTIFACT_EMITTING_ACTIONS = new Set([
+    "taskAdvance",
+    "taskCreate",
+    "contractApply",
+    "dagReport",
+    "taskImportPrd",
+    "importPrd",
+]);
+/**
+ * Project a terminal operation into an「产物」rail card (2026-08-16).
+ * Mirrors `ArtifactCardState` (schemaVersion 1) so the existing frontend
+ * parser renders it without any change. Best-effort: operations without a
+ * durable outcome (pure status reads) return undefined.
+ */
+function artifactFromTerminalOperation(operation, projection) {
+    if (!ARTIFACT_EMITTING_ACTIONS.has(operation.action))
+        return undefined;
+    // Failed/interrupted actions leave nothing inspectable as a deliverable.
+    if (operation.state !== "succeeded")
+        return undefined;
+    const taskId = projection.taskId;
+    const kind = taskId
+        ? "contract"
+        : "operation";
+    const title = taskId ? `任务 ${taskId}` : `执行 ${operation.action}`;
+    const summary = projection.runSummary?.status
+        ? `运行 ${projection.runSummary.runId} · ${projection.runSummary.status}`
+        : projection.summaryPreview || undefined;
+    const reportLines = [];
+    if (projection.runSummary) {
+        const rs = projection.runSummary;
+        reportLines.push(`运行: ${rs.runId}`);
+        reportLines.push(`状态: ${rs.status}`);
+        if (rs.verdict)
+            reportLines.push(`结论: ${rs.verdict}`);
+        if (rs.failureCategory)
+            reportLines.push(`失败归类: ${rs.failureCategory}`);
+        if (Array.isArray(rs.nodes)) {
+            for (const node of rs.nodes.slice(0, 30)) {
+                reportLines.push(`- ${node.id}: ${node.status}`);
+            }
+        }
+    }
+    if (projection.stdoutPreview) {
+        reportLines.push("", "--- stdout 摘要 ---", projection.stdoutPreview);
+    }
+    const previewHash = createHash("sha256")
+        .update(JSON.stringify({
+        operationId: operation.operationId,
+        state: operation.state,
+        taskId: taskId ?? null,
+        runSummary: projection.runSummary ?? null,
+        stdoutPreview: projection.stdoutPreview ?? null,
+    }))
+        .digest("hex");
+    return {
+        schemaVersion: 1,
+        kind,
+        artifactId: `operation-${operation.operationId}`,
+        title,
+        ...(summary ? { summary } : {}),
+        ...(reportLines.length > 0
+            ? { reportText: reportLines.join("\n").slice(0, 8000) }
+            : {}),
+        inspectHref: projection.inspectHref,
+        previewHash,
+    };
+}
+export function projectCompactSnapshot(value) {
+    const record = value && typeof value === "object"
+        ? value
+        : {};
+    const summary = boundedRedactedText(record.summary, 12_000) ?? "Context compacted.";
+    const firstKeptEntryId = safeIdentity(record.firstKeptEntryId);
+    const tokensBefore = typeof record.tokensBefore === "number" &&
+        Number.isFinite(record.tokensBefore)
+        ? Math.max(0, Math.floor(record.tokensBefore))
+        : undefined;
+    const details = record.details === undefined
+        ? undefined
+        : boundedRedactedJson(record.details).preview;
+    return {
+        schemaVersion: 1,
+        summary,
+        ...(firstKeptEntryId ? { firstKeptEntryId } : {}),
+        ...(tokensBefore !== undefined ? { tokensBefore } : {}),
+        ...(details ? { details } : {}),
+        previewHash: createHash("sha256")
+            .update(JSON.stringify({ summary, firstKeptEntryId, tokensBefore, details }))
+            .digest("hex"),
+    };
+}
+function boundedRedactedJson(value) {
+    let raw;
+    try {
+        raw = JSON.stringify(value ?? {});
+    }
+    catch {
+        raw = String(value);
+    }
+    const preview = boundedRedactedText(raw) ?? "{}";
+    return {
+        preview,
+        previewHash: createHash("sha256").update(preview).digest("hex"),
+    };
+}
+/** Prefer readable Pi ToolResult text content; fall back to JSON shell. */
+function projectToolResultPreview(value) {
+    if (typeof value === "string") {
+        const preview = boundedRedactedText(value) ?? "";
+        return {
+            preview,
+            previewHash: createHash("sha256").update(preview).digest("hex"),
+        };
+    }
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const record = value;
+        const content = record.content;
+        if (Array.isArray(content)) {
+            const texts = [];
+            for (const block of content) {
+                if (!block || typeof block !== "object")
+                    continue;
+                const item = block;
+                if (typeof item.text === "string")
+                    texts.push(item.text);
+            }
+            if (texts.length > 0) {
+                const joined = texts.join("\n");
+                const preview = boundedRedactedText(joined) ?? "";
+                return {
+                    preview,
+                    previewHash: createHash("sha256").update(preview).digest("hex"),
+                };
+            }
+        }
+        if (typeof record.text === "string") {
+            const preview = boundedRedactedText(record.text) ?? "";
+            return {
+                preview,
+                previewHash: createHash("sha256").update(preview).digest("hex"),
+            };
+        }
+        if (typeof record.output === "string") {
+            const preview = boundedRedactedText(record.output) ?? "";
+            return {
+                preview,
+                previewHash: createHash("sha256").update(preview).digest("hex"),
+            };
+        }
+    }
+    return boundedRedactedJson(value);
+}
+export function projectChatToolEventPayload(input) {
+    if (input.kind === "tool_call") {
+        const { preview, previewHash } = boundedRedactedJson(input.value);
+        return {
+            toolCallId: input.toolCallId,
+            toolName: input.toolName,
+            argsPreview: preview,
+            previewHash,
+        };
+    }
+    const { preview, previewHash } = projectToolResultPreview(input.value);
+    return {
+        toolCallId: input.toolCallId,
+        toolName: input.toolName,
+        resultPreview: preview,
+        previewHash,
+        isError: Boolean(input.isError),
+        ...(input.operationId ? { operationId: input.operationId } : {}),
+    };
+}
+export function projectOperationEventSummary(event) {
+    const messagePreview = boundedRedactedText(event.message, 600);
+    const dataPreview = event.data === undefined
+        ? undefined
+        : boundedRedactedText(JSON.stringify(event.data), 600);
+    return {
+        seq: event.seq,
+        at: event.at,
+        kind: event.kind,
+        ...(event.state ? { state: event.state } : {}),
+        ...(messagePreview ? { messagePreview } : {}),
+        ...(dataPreview ? { dataPreview } : {}),
+        previewHash: createHash("sha256")
+            .update(JSON.stringify({
+            messagePreview,
+            dataPreview,
+            state: event.state,
+            kind: event.kind,
+        }))
+            .digest("hex"),
+    };
+}
+/** Conservative per-event byte contribution (compact JSON length × UTF-8/pretty scale). */
+function byteHint(value) {
+    return JSON.stringify(value).length * BYTE_GATE_SCALE;
+}
+function recomputeApproxBytes(ring) {
+    let total = BYTE_GATE_SLACK;
+    for (const event of ring.events)
+        total += byteHint(event);
+    for (const turn of ring.turns)
+        total += byteHint(turn);
+    ring.approxBytes = total;
+}
+/**
+ * D3 eviction priority: drop the single oldest candidate — text updates
+ * (`message_update`) first, structural events second, and `message_end` (the
+ * terminal full-text event) absolutely last. Falls back to the oldest event
+ * (legacy `shift()` order) when only `message_end` remain.
+ */
+function dropOneByPriority(ring) {
+    const events = ring.events;
+    if (events.length === 0)
+        return undefined;
+    const textIndex = events.findIndex((event) => event.kind === "message_update");
+    if (textIndex !== -1)
+        return events.splice(textIndex, 1)[0];
+    const structuralIndex = events.findIndex((event) => event.kind !== "message_end");
+    if (structuralIndex !== -1)
+        return events.splice(structuralIndex, 1)[0];
+    return events.shift();
+}
+/**
+ * D2 coalescing decision: merge an incoming `message_update` into the ring tail
+ * only when the tail is also a same-turn `message_update` and the update landed
+ * inside the coalescing window. Structural events close the window implicitly
+ * (their presence makes the tail check fail), so an
+ * update → tool_call → update sequence never merges across the tool boundary.
+ * `partial.at` (when present) drives the clock so tests can inject window
+ * boundaries deterministically without fake timers.
+ */
+function shouldCoalesce(ring, turnId, partial) {
+    if (partial.kind !== "message_update")
+        return false;
+    const tail = ring.events.at(-1);
+    if (!tail || tail.kind !== "message_update")
+        return false;
+    if (tail.turnId !== turnId)
+        return false;
+    const nowMs = partial.at ? Date.parse(partial.at) : Date.now();
+    if (Number.isNaN(nowMs))
+        return false;
+    return nowMs - Date.parse(tail.at) <= ring.coalesceWindowMs;
+}
+/** Stable hash of the normalized prompt payload for clientRequestId binding. */
+export function hashChatTurnPayload(input) {
+    const normalized = {
+        text: input.text,
+        images: (input.images ?? []).map((image) => ({
+            type: image.type ?? "image",
+            mimeType: image.mimeType ?? "",
+            data: image.data ?? "",
+        })),
+    };
+    return createHash("sha256")
+        .update(JSON.stringify(normalized))
+        .digest("hex");
+}
+const DEFAULT_MAX_EVENTS = 2000;
+/** Mirrors pi-web's bounded-ring orientation (2000 events / 10 MiB). */
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+/** Same-turn `message_update` events inside this window coalesce into one persisted event. */
+const DEFAULT_COALESCE_WINDOW_MS = 100;
+/** Conservative per-event scale for the byte pre-check gate (UTF-8 multibyte ≤ 4 bytes/char × pretty-print expansion). */
+const BYTE_GATE_SCALE = 12;
+/** Fixed envelope slack (schema keys, turnCount, nextSeq, minSeq, turns) for the byte pre-check gate. */
+const BYTE_GATE_SLACK = 8192;
+/** Legacy epoch for event files written before M5.1 (no epoch field). */
+const LEGACY_EPOCH = "legacy";
+/** Make a sessionId safe to use as a filename component. */
+function safeSessionId(sessionId) {
+    return sessionId.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 180);
+}
+/**
+ * Link durable Chat refs to the existing canonical operation store/event ring.
+ * This owns no operation state and schedules no work; it only projects facts.
+ */
+export function createChatOperationLinker(options) {
+    const followers = new Map();
+    const keyFor = (sessionId, operationId) => `${sessionId}\u0000${operationId}`;
+    function hasRef(input) {
+        return options.chatEvents.snapshot(input.sessionId).some((event) => {
+            if (event.kind !== "operation-ref")
+                return false;
+            const data = event.data;
+            return (event.turnId === input.turnId &&
+                data.operationId === input.operationId &&
+                data.toolCallId === input.toolCallId);
+        });
+    }
+    async function syncFact(input) {
+        const operation = await options.operations.get(input.operationId);
+        if (!operation)
+            return;
+        const focused = isTerminalOperationState(operation.state) ||
+            operation.state === "needs-reconcile";
+        if (!focused)
+            return;
+        const projection = projectOperationForChat(operation);
+        const closureKind = operation.state === "needs-reconcile"
+            ? "needs-reconcile"
+            : operation.state === "failed" || operation.state === "timed-out"
+                ? "failed"
+                : "terminal";
+        const duplicate = options.chatEvents
+            .snapshot(input.sessionId)
+            .some((event) => {
+            if (event.kind !== "operation-status")
+                return false;
+            const data = event.data;
+            return (data.operationId === input.operationId &&
+                data.closureKind === closureKind &&
+                data.operation?.state === projection.state &&
+                data.operation?.previewHash === projection.previewHash);
+        });
+        if (!duplicate) {
+            options.chatEvents.append(input.sessionId, input.turnId, {
+                kind: "operation-status",
+                data: {
+                    operationId: input.operationId,
+                    closureKind,
+                    operation: projection,
+                },
+            });
+        }
+        // Artifact projection (2026-08-16): the sidebar「产物」tab was permanently
+        // empty because nothing in the server ever emitted `artifact-ref`. On a
+        // terminal operation with a durable outcome (task created / advanced /
+        // contract applied / report produced) project one artifact card so the
+        // user can inspect the deliverable straight from the rail.
+        if (isTerminalOperationState(operation.state)) {
+            const artifact = artifactFromTerminalOperation(operation, projection);
+            if (artifact) {
+                const artifactDuplicate = options.chatEvents
+                    .snapshot(input.sessionId)
+                    .some((event) => event.kind === "artifact-ref" &&
+                    event.data
+                        .artifact?.previewHash === artifact.previewHash);
+                if (!artifactDuplicate) {
+                    options.chatEvents.append(input.sessionId, input.turnId, {
+                        kind: "artifact-ref",
+                        data: { artifact },
+                    });
+                }
+            }
+        }
+        if (isTerminalOperationState(operation.state)) {
+            const key = keyFor(input.sessionId, input.operationId);
+            followers.get(key)?.();
+            followers.delete(key);
+        }
+    }
+    async function link(input) {
+        const operation = await options.operations.get(input.operationId);
+        if (!operation)
+            throw new Error(`operation not found: ${input.operationId}`);
+        if (!hasRef(input)) {
+            options.chatEvents.append(input.sessionId, input.turnId, {
+                kind: "operation-ref",
+                data: {
+                    operationId: input.operationId,
+                    toolCallId: input.toolCallId,
+                    operation: projectOperationForChat(operation),
+                },
+            });
+        }
+        const key = keyFor(input.sessionId, input.operationId);
+        if (!followers.has(key) && !isTerminalOperationState(operation.state)) {
+            const unsubscribe = options.operationEvents.subscribe(input.operationId, () => {
+                void syncFact(input).catch(() => {
+                    // Recovery reads will retry from durable refs; never break operation append.
+                });
+            });
+            followers.set(key, unsubscribe);
+        }
+        await syncFact(input);
+    }
+    return {
+        link,
+        async recoverSession(sessionId) {
+            const refs = options.chatEvents
+                .snapshot(sessionId)
+                .filter((event) => event.kind === "operation-ref");
+            for (const event of refs) {
+                const data = event.data;
+                if (!data.operationId || !data.toolCallId)
+                    continue;
+                await link({
+                    sessionId,
+                    turnId: event.turnId,
+                    toolCallId: data.toolCallId,
+                    operationId: data.operationId,
+                }).catch(() => undefined);
+            }
+        },
+        clearSession(sessionId) {
+            for (const [key, unsubscribe] of followers) {
+                if (!key.startsWith(`${sessionId}\u0000`))
+                    continue;
+                unsubscribe();
+                followers.delete(key);
+            }
+        },
+        dispose() {
+            for (const unsubscribe of followers.values())
+                unsubscribe();
+            followers.clear();
+        },
+    };
+}
+export function createChatEventStore(options) {
+    const maxEvents = options?.maxEventsPerSession ?? DEFAULT_MAX_EVENTS;
+    const maxBytes = options?.maxBytesPerSession ?? DEFAULT_MAX_BYTES;
+    const coalesceWindowMs = options?.coalesceWindowMs ?? DEFAULT_COALESCE_WINDOW_MS;
+    const eventEpoch = options?.epoch?.trim() || LEGACY_EPOCH;
+    const persistenceDir = options?.appData?.chatEvents
+        ? path.resolve(options.appData.chatEvents)
+        : undefined;
+    if (persistenceDir)
+        ensureSecureDir(persistenceDir);
+    const rings = new Map();
+    /** Monotonic turn ordinal per session (persisted alongside the ring). */
+    const turnCounts = new Map();
+    /** Live subscribers per session. */
+    const subscribers = new Map();
+    function persistedPath(sessionId) {
+        return persistenceDir
+            ? path.join(persistenceDir, `${safeSessionId(sessionId)}.json`)
+            : undefined;
+    }
+    function eventIdFor(sessionId, seq) {
+        // Preserve the pre-M5.1 test/file surface for stores that did not opt in.
+        return eventEpoch === LEGACY_EPOCH
+            ? `${sessionId}:${seq}`
+            : `${eventEpoch}:${seq}`;
+    }
+    function loadRing(sessionId) {
+        const file = persistedPath(sessionId);
+        if (!file || !existsSync(file))
+            return undefined;
+        try {
+            const parsed = JSON.parse(readFileSync(file, "utf8"));
+            if (parsed.schemaVersion !== 1 ||
+                parsed.sessionId !== sessionId ||
+                !Array.isArray(parsed.events)) {
+                throw new Error("invalid persisted chat event ring");
+            }
+            // Persisted events are derived recovery facts. On a new Console boot we
+            // deliberately remap their ids into this store's generation namespace;
+            // clients with an old epoch then reconcile rather than cross generations.
+            const events = parsed.events
+                .slice(-maxEvents)
+                .map((event) => ({
+                ...event,
+                eventId: eventIdFor(sessionId, event.seq),
+            }));
+            const turns = Array.isArray(parsed.turns) ? parsed.turns : [];
+            // New Console epoch: orphan any queued/running turn whose ownerEpoch is
+            // missing or mismatched. Releases the active lease without pretending the
+            // user aborted (CHAT_TURN_OWNER_LOST fence).
+            let orphaned = false;
+            const now = new Date().toISOString();
+            for (const turn of turns) {
+                if (turn.state !== "queued" && turn.state !== "running")
+                    continue;
+                if (turn.ownerEpoch === eventEpoch)
+                    continue;
+                turn.state = "failed";
+                turn.finishedAt = now;
+                turn.error = {
+                    code: "CHAT_TURN_OWNER_LOST",
+                    message: "turn ownership lost after Console restart; previous execution is no longer owned",
+                };
+                orphaned = true;
+            }
+            turnCounts.set(sessionId, parsed.turnCount ?? 0);
+            const ring = {
+                events,
+                turns,
+                nextSeq: Math.max(parsed.nextSeq, (events[events.length - 1]?.seq ?? 0) + 1),
+                minSeq: events[0]?.seq ?? parsed.minSeq ?? 1,
+                maxEvents,
+                maxBytes,
+                coalesceWindowMs,
+                approxBytes: 0,
+                epoch: eventEpoch,
+            };
+            recomputeApproxBytes(ring);
+            // R6: re-check the bounds after a restart — a persisted file may exceed the
+            // current limits if it was written by an older config or hand-edited.
+            enforceBounds(sessionId, ring);
+            if (orphaned)
+                persist(sessionId, ring);
+            return ring;
+        }
+        catch (error) {
+            throw new Error(`invalid persisted chat events ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** The exact payload written to disk (single source of truth for D4 byte accounting). */
+    function ringPayload(sessionId, ring) {
+        return {
+            schemaVersion: 1,
+            sessionId,
+            turnCount: turnCounts.get(sessionId) ?? 0,
+            turns: ring.turns,
+            events: ring.events,
+            nextSeq: ring.nextSeq,
+            minSeq: ring.minSeq,
+            epoch: ring.epoch,
+        };
+    }
+    /** Serialized exactly as `writeSecureJsonSync` writes it, so byte accounting
+     *  (D4) and the on-disk bytes use the same formatting. */
+    function serializeRingForPersist(sessionId, ring) {
+        return `${JSON.stringify(ringPayload(sessionId, ring), null, 2)}\n`;
+    }
+    function bytesOfRing(sessionId, ring) {
+        return Buffer.byteLength(serializeRingForPersist(sessionId, ring), "utf8");
+    }
+    /**
+     * Enforce the `maxEvents + maxBytes` dual bound (D3/D4). maxEvents first
+     * (count), then bytes against the real serialized payload; every drop removes
+     * the oldest eviction candidate by priority. The byte loop is bounded because
+     * each iteration removes an event and stops on an empty ring. A conservative
+     * pre-check skips the exact serialization for small rings (keeps the frequent
+     * per-token append path O(1)-ish).
+     */
+    function enforceBounds(sessionId, ring) {
+        while (ring.events.length > ring.maxEvents) {
+            const dropped = dropOneByPriority(ring);
+            if (dropped)
+                ring.approxBytes -= byteHint(dropped);
+        }
+        if (ring.events.length > 0 && ring.approxBytes > ring.maxBytes) {
+            while (ring.events.length > 0 &&
+                bytesOfRing(sessionId, ring) > ring.maxBytes) {
+                const dropped = dropOneByPriority(ring);
+                if (dropped)
+                    ring.approxBytes -= byteHint(dropped);
+            }
+        }
+        if (ring.events.length > 0) {
+            ring.minSeq = ring.events[0].seq;
+        }
+    }
+    function persist(sessionId, ring) {
+        const file = persistedPath(sessionId);
+        if (!file)
+            return;
+        writeSecureJsonSync(file, ringPayload(sessionId, ring));
+    }
+    function ringFor(sessionId) {
+        let ring = rings.get(sessionId);
+        if (!ring) {
+            ring = loadRing(sessionId) ?? {
+                events: [],
+                turns: [],
+                nextSeq: 1,
+                minSeq: 1,
+                maxEvents,
+                maxBytes,
+                coalesceWindowMs,
+                approxBytes: BYTE_GATE_SLACK,
+                epoch: eventEpoch,
+            };
+            rings.set(sessionId, ring);
+        }
+        return ring;
+    }
+    return {
+        forkContextRefs(input) {
+            const allowed = new Set([
+                "operation-ref",
+                "operation-status",
+                "draft",
+                "assessment",
+                "taskKind-confirmed",
+                "human-gate-card",
+                "compact",
+                "artifact-ref",
+            ]);
+            let copiedCount = 0;
+            for (const event of this.snapshot(input.sourceSessionId)) {
+                if (!allowed.has(event.kind))
+                    continue;
+                const data = structuredClone(event.data);
+                if (event.kind === "human-gate-card") {
+                    delete data.humanGateToken;
+                    delete data.dagBytesPath;
+                }
+                this.append(input.targetSessionId, input.targetTurnId, {
+                    kind: event.kind,
+                    data: data,
+                });
+                copiedCount += 1;
+            }
+            return { copiedCount };
+        },
+        createTurn(sessionId, input) {
+            const ring = ringFor(sessionId);
+            const clientRequestId = input?.clientRequestId?.trim() || undefined;
+            const payloadHash = input?.payloadHash?.trim() || undefined;
+            if (clientRequestId) {
+                const existing = ring.turns.find((turn) => turn.clientRequestId === clientRequestId);
+                if (existing) {
+                    if (payloadHash &&
+                        existing.payloadHash &&
+                        existing.payloadHash !== payloadHash) {
+                        return {
+                            ok: false,
+                            code: "REQUEST_ID_REUSE_CONFLICT",
+                            message: `clientRequestId ${clientRequestId} was reused with a different payload`,
+                            existingTurn: { ...existing },
+                        };
+                    }
+                    // Same id + same (or missing) payload: idempotent return, no new lease.
+                    return {
+                        ok: true,
+                        turn: { ...existing },
+                        created: false,
+                        idempotent: true,
+                    };
+                }
+            }
+            const active = ring.turns.find((turn) => turn.state === "queued" || turn.state === "running");
+            if (active)
+                return { ok: false, code: "TURN_ACTIVE", activeTurn: { ...active } };
+            const ordinal = (turnCounts.get(sessionId) ?? 0) + 1;
+            turnCounts.set(sessionId, ordinal);
+            const now = new Date().toISOString();
+            const turn = {
+                schemaVersion: 1,
+                turnId: `${sessionId}:turn-${ordinal}`,
+                sessionId,
+                ordinal,
+                state: "queued",
+                createdAt: now,
+                ownerEpoch: eventEpoch,
+                ...(clientRequestId ? { clientRequestId } : {}),
+                ...(payloadHash ? { payloadHash } : {}),
+            };
+            ring.turns.push(turn);
+            ring.approxBytes += byteHint(turn);
+            persist(sessionId, ring);
+            return { ok: true, turn: { ...turn }, created: true, idempotent: false };
+        },
+        setTurnState(sessionId, turnId, state, error) {
+            const ring = ringFor(sessionId);
+            const turn = ring.turns.find((candidate) => candidate.turnId === turnId);
+            if (!turn)
+                return undefined;
+            turn.state = state;
+            const before = JSON.stringify(turn).length;
+            if (state === "running" && !turn.startedAt)
+                turn.startedAt = new Date().toISOString();
+            if (state === "settled" || state === "aborted" || state === "failed") {
+                turn.finishedAt = new Date().toISOString();
+            }
+            if (error)
+                turn.error = error;
+            ring.approxBytes +=
+                (JSON.stringify(turn).length - before) * BYTE_GATE_SCALE;
+            persist(sessionId, ring);
+            return { ...turn };
+        },
+        markAbortRequested(sessionId, turnId, at) {
+            const ring = ringFor(sessionId);
+            const turn = ring.turns.find((candidate) => candidate.turnId === turnId);
+            if (!turn)
+                return undefined;
+            const before = JSON.stringify(turn).length;
+            if (!turn.abortRequestedAt)
+                turn.abortRequestedAt = at ?? new Date().toISOString();
+            ring.approxBytes +=
+                (JSON.stringify(turn).length - before) * BYTE_GATE_SCALE;
+            persist(sessionId, ring);
+            return { ...turn };
+        },
+        findTurnByClientRequestId(sessionId, clientRequestId) {
+            const id = clientRequestId.trim();
+            if (!id)
+                return undefined;
+            const ring = ringFor(sessionId);
+            const turn = ring.turns.find((candidate) => candidate.clientRequestId === id);
+            return turn ? { ...turn } : undefined;
+        },
+        getTurn(sessionId, turnId) {
+            const ring = ringFor(sessionId);
+            const turn = ring.turns.find((candidate) => candidate.turnId === turnId);
+            return turn ? { ...turn } : undefined;
+        },
+        getActiveTurn(sessionId) {
+            const ring = ringFor(sessionId);
+            const turn = ring.turns.find((candidate) => candidate.state === "queued" || candidate.state === "running");
+            return turn ? { ...turn } : undefined;
+        },
+        latestTurn(sessionId) {
+            const ring = ringFor(sessionId);
+            const turn = ring.turns.at(-1);
+            return turn ? { ...turn } : undefined;
+        },
+        append(sessionId, turnId, partial) {
+            const ring = ringFor(sessionId);
+            // D1: every append (coalesced or not) consumes a fresh live seq so the
+            // live stream stays fully dense (AC-006); the persisted ring may collapse
+            // text updates, but nextSeq is always persisted alongside it so a restart
+            // never re-issues a seq a live client already saw.
+            const seq = ring.nextSeq++;
+            const at = partial.at ?? new Date().toISOString();
+            const live = {
+                schemaVersion: 1,
+                eventId: eventIdFor(sessionId, seq),
+                sessionId,
+                seq,
+                turnId,
+                at,
+                kind: partial.kind,
+                data: partial.data,
+            };
+            if (shouldCoalesce(ring, turnId, partial)) {
+                // AC-001: same-turn in-window text update replaces the persisted tail in
+                // place (keeping its original seq/eventId/turnId); only the text and `at`
+                // slide forward. The fresh live event is still returned/broadcast below.
+                const tail = ring.events.at(-1);
+                const before = JSON.stringify(tail).length;
+                tail.data = live.data;
+                tail.at = live.at;
+                ring.approxBytes +=
+                    (JSON.stringify(tail).length - before) * BYTE_GATE_SCALE;
+            }
+            else {
+                ring.events.push(live);
+                ring.approxBytes += byteHint(live);
+            }
+            enforceBounds(sessionId, ring);
+            persist(sessionId, ring);
+            const subs = subscribers.get(sessionId);
+            if (subs) {
+                for (const fn of subs) {
+                    try {
+                        fn(live);
+                    }
+                    catch {
+                        // a subscriber throwing must never break the append path
+                    }
+                }
+            }
+            return live;
+        },
+        listFrom(sessionId, cursor) {
+            const ring = rings.get(sessionId) ?? loadRing(sessionId);
+            if (!ring)
+                return { events: [], epoch: eventEpoch };
+            rings.set(sessionId, ring);
+            const normalized = typeof cursor === "number" ? { seq: cursor, epoch: null } : cursor;
+            if (normalized.epoch && normalized.epoch !== ring.epoch) {
+                return {
+                    error: "CURSOR_EPOCH_MISMATCH",
+                    minSeq: ring.minSeq,
+                    epoch: ring.epoch,
+                };
+            }
+            if (ring.events.length > 0 && normalized.seq + 1 < ring.minSeq) {
+                return {
+                    error: "CURSOR_EXPIRED",
+                    minSeq: ring.minSeq,
+                    epoch: ring.epoch,
+                };
+            }
+            return {
+                events: ring.events.filter((event) => event.seq > normalized.seq),
+                epoch: ring.epoch,
+            };
+        },
+        epoch(sessionId) {
+            return ringFor(sessionId).epoch;
+        },
+        snapshot(sessionId) {
+            const ring = rings.get(sessionId) ?? loadRing(sessionId);
+            if (ring)
+                rings.set(sessionId, ring);
+            return ring?.events.slice() ?? [];
+        },
+        nextTurnOrdinal(sessionId) {
+            // Load the ring FIRST so a fresh store instance hydrates turnCounts from
+            // the persisted file before we read it (otherwise a restart resets the
+            // ordinal to 1 and collides with prior turns).
+            const ring = ringFor(sessionId);
+            const next = (turnCounts.get(sessionId) ?? 0) + 1;
+            turnCounts.set(sessionId, next);
+            persist(sessionId, ring);
+            return next;
+        },
+        latestTurnId(sessionId) {
+            const ring = rings.get(sessionId) ?? loadRing(sessionId);
+            if (ring)
+                rings.set(sessionId, ring);
+            return ring?.events.at(-1)?.turnId;
+        },
+        subscribe(sessionId, listener) {
+            let subs = subscribers.get(sessionId);
+            if (!subs) {
+                subs = new Set();
+                subscribers.set(sessionId, subs);
+            }
+            subs.add(listener);
+            return () => {
+                subs?.delete(listener);
+                if (subs && subs.size === 0)
+                    subscribers.delete(sessionId);
+            };
+        },
+        clear(sessionId) {
+            rings.delete(sessionId);
+            turnCounts.delete(sessionId);
+            subscribers.delete(sessionId);
+            const file = persistedPath(sessionId);
+            if (file)
+                rmSync(file, { force: true });
+        },
+    };
+}