loopforge 3.0.0 → 3.2.1

package/dist/mcp/session.js

@@ -2,65 +2,70 @@
  *
  * Each McpSession = one complete multi-round loop.
  * SessionManager holds Map<sessionId, McpSession> and drives
- * the advance() cycle: validate report → commit round event → check stop → compile next.
+ * the advance() cycle: extract → feedback → check stop → compile next.
+ *
+ * Since v2.14 the round state machine lives in RoundLifecycle
+ * (round-lifecycle.ts). SessionManager owns "who may touch a session":
+ * the in-memory registry, per-session serialization queue, and cross-process
+ * lease fencing. RoundLifecycle owns "what happens to a session": crash
+ * recovery, transaction execution, disposition result building, and the
+ * advance pipeline. All round processing still goes through the
+ * SessionManager → RoundDriver → RoundCoordinator path.
  */
-import { createHash, randomUUID } from "node:crypto";
-import { RuntimeServices } from "../runtime-services.js";
+import { randomUUID } from "node:crypto";
+import { LoopForgeEngine } from "../engine.js";
+import { deriveGate } from "../cognitive-governance.js";
+import { makeGateDecision, Mode } from "../protocol.js";
+import { buildLoopProjection } from "../loop-projection.js";
+import { listVerifiedClaims } from "../evidence-claims.js";
+import { buildAudit } from "../audit.js";
 import { checkLoopHealth } from "../loop-compiler.js";
-import { getPolicy } from "../policy.js";
-import { Mode, makeLoopCompileRequest } from "../protocol.js";
+import { getPolicy, validateLoopId } from "../policy.js";
+import { makeLoopCompileRequest } from "../protocol.js";
 import { ReplayBackend } from "../replay.js";
-import { FileLoopStore } from "../loop-store.js";
-import { EvidenceCollector } from "../evidence-provider.js";
-import { parseRoundTransactionSnapshot, prepareRoundTransaction, } from "../round-transaction.js";
+import { FileLoopStore, queryLoopEntries } from "../loop-store.js";
+import { makeRoundId, prepareRoundTransaction } from "../round-transaction.js";
 import { RoundDriver } from "../round-driver.js";
 import { logEvent } from "../observability.js";
-import { derivePolicyMetrics, mergePolicyMetrics, policyMetrics, } from "../policy-metrics.js";
+import { policyMetrics, derivePolicyMetrics, mergePolicyMetrics, } from "../policy-metrics.js";
 import { SessionLeaseConflictError, VaultSessionStateStore, } from "../storage.js";
-import { auditEntries, deriveStructuredGate } from "../cognitive-governance.js";
-import { isRecord } from "../token-utils.js";
-import { parseRoundReport, deriveCompilerProjection } from "../round-report.js";
-import { collectSkippedRoundFiles, findSafeRestorePoint, findBacktrackTargetGitHead, } from "../round-recovery.js";
-import { CanonicalEventWriter } from "../canonical-event-writer.js";
-import { buildLoopRequest } from "./session-projection.js";
-import { withSessionQueue } from "./session-queue.js";
-// ── Helpers ────────────────────────────────────────────────────────────────
+import { StorageCorruptionError } from "../loop-store.js";
+import { RoundLifecycle, buildLoopRequest } from "./round-lifecycle.js";
 // ── SessionManager ─────────────────────────────────────────────────────────
 export class SessionManager {
     sessions = new Map();
     /** Serializes state transitions for each session. */
     sessionQueues = new Map();
-    backend;
-    eventWriter;
+    loopStore;
     sessionStore;
     ownerId = `${process.pid}:${randomUUID()}`;
     leaseMs;
     leaseRenewIntervalMs;
     leaseTimer = null;
+    lifecycle;
     /** Explicit context provider; never auto-discovered. */
     contextProvider;
     terminalSinks = new Set();
-    /** Vault-replayed policy metrics, keyed by loop. The signature covers every
-     *  entry's task_id/timestamp/sequence so both appends and idempotent
-     *  replacements (same task_id) invalidate the cache. */
-    derivedMetricsCache = new Map();
-    constructor(storeOrBackend, sessionStore) {
-        const store = storeOrBackend ?? new FileLoopStore(getPolicy().backend.root_dir);
-        this.backend = store;
-        this.sessionStore = sessionStore ?? new VaultSessionStateStore(store);
+    constructor(store, sessionStore) {
+        this.loopStore = store ?? new FileLoopStore(getPolicy().backend.root_dir);
+        this.sessionStore = sessionStore ?? new VaultSessionStateStore(this.loopStore);
         const mcpPolicy = getPolicy().mcp;
         this.leaseMs = Math.max(1, mcpPolicy.session_lease_ms);
         this.leaseRenewIntervalMs = Math.max(1, Math.min(mcpPolicy.session_lease_renew_interval_ms, this.leaseMs));
+        this.lifecycle = new RoundLifecycle({
+            store: this.loopStore,
+            sessionStore: this.sessionStore,
+            registry: this,
+            terminalSinks: this.terminalSinks,
+            ownerId: this.ownerId,
+            leaseMs: this.leaseMs,
+            getContext: () => this.contextProvider,
+        });
         if (this.sessionStore?.renewLease) {
             this.leaseTimer = setInterval(() => this.renewOwnedLeases(), this.leaseRenewIntervalMs);
             this.leaseTimer.unref?.();
         }
     }
-    appendCanonicalEvent(entry) {
-        if (!this.backend)
-            throw new Error("Vault backend is not initialized");
-        (this.eventWriter ??= new CanonicalEventWriter(this.backend)).append(entry);
-    }
     /** Stable process-local owner token used for cross-process session leases. */
     getOwnerId() {
         return this.ownerId;
@@ -78,6 +83,15 @@ export class SessionManager {
             this.sessionStore?.releaseLease?.(session.loopId, this.ownerId);
         }
     }
+    // ── SessionRegistry (view for RoundLifecycle) ────────────────────────────
+    values() {
+        return this.sessions.values();
+    }
+    /** Register (or replace) a session in the in-memory registry. */
+    upsert(session) {
+        this.sessions.set(session.sessionId, session);
+    }
+    // ── Lease helpers ────────────────────────────────────────────────────────
     findSessionEntry(loopId) {
         return this.sessionStore?.load(loopId);
     }
@@ -113,29 +127,67 @@ export class SessionManager {
             stopDetail: `Another process (PID ${entry?.loop_lineage ? entry.loop_lineage.lease_owner ?? "unknown" : "unknown"}) holds the lease for loop "${loopId}". Wait for the lease to expire or stop the other process.`,
         };
     }
+    async withSessionQueue(sessionId, work) {
+        const previous = this.sessionQueues.get(sessionId) ?? Promise.resolve();
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const tail = previous.then(() => gate);
+        this.sessionQueues.set(sessionId, tail);
+        await previous;
+        try {
+            return await work();
+        }
+        finally {
+            release();
+            if (this.sessionQueues.get(sessionId) === tail) {
+                this.sessionQueues.delete(sessionId);
+            }
+        }
+    }
+    // ── Lifecycle entry points ───────────────────────────────────────────────
     async create(input) {
-        const policyMaxRounds = getPolicy().engine.max_rounds;
-        if (input.maxRounds !== undefined &&
-            (!Number.isInteger(input.maxRounds) || input.maxRounds < 1 || input.maxRounds > policyMaxRounds)) {
+        const sessionId = randomUUID();
+        const loopId = input.loopId ?? randomUUID();
+        // v2.14: same-process duplicate guard. Cross-process duplicates are
+        // fenced by the lease (SessionLeaseConflictError on save); within one
+        // process the lease owner is identical, so a second create for the
+        // same loopId would silently overwrite the first session's persisted
+        // state and leave two in-memory sessions pointing at one loop.
+        const existing = [...this.sessions.values()].find((s) => s.loopId === loopId);
+        if (existing) {
             return {
                 sessionId: "",
-                round: 0,
+                round: existing.currentRound,
                 prompt: null,
-                stopReason: "invalid_input",
-                stopDetail: `maxRounds must be an integer between 1 and ${policyMaxRounds}.`,
-                error: { code: "invalid_max_rounds", message: `maxRounds must be an integer between 1 and ${policyMaxRounds}.` },
+                stopReason: `loop_already_running:${loopId}`,
+                stopDetail: `A session for loop "${loopId}" already exists in this process (session ${existing.sessionId}). Inspect or resume it instead of starting a duplicate.`,
             };
         }
-        const sessionId = randomUUID();
-        const loopId = input.loopId ?? randomUUID();
-        const engine = new RuntimeServices(this.backend);
+        // v3.2.1: pre-flight the cross-process lease BEFORE compiling — the
+        // compile persists round-1 lineage and the state file into the loop's
+        // vault, which would corrupt another process's live loop (round-1
+        // lineage replaced, metadata overwritten). Mirrors the save-time check
+        // (VaultSessionStateStore.save: a non-empty lease_owner that is not ours
+        // conflicts), so observable behavior is unchanged — only the side
+        // effects are avoided. The save below remains the atomic final gate.
+        const persistedSession = this.sessionStore?.load(loopId);
+        const persistedLineage = persistedSession?.loop_lineage;
+        const persistedOwner = persistedLineage && typeof persistedLineage === "object" && !Array.isArray(persistedLineage)
+            ? persistedLineage.lease_owner
+            : "";
+        if (typeof persistedOwner === "string" && persistedOwner && persistedOwner !== this.ownerId) {
+            throw new SessionLeaseConflictError(loopId);
+        }
+        const engine = new LoopForgeEngine(this.loopStore);
         const maxRounds = input.maxRounds ?? getPolicy().engine.max_rounds;
         // Populate extra fields for the first round
         const request = buildLoopRequest({
-            sessionId, loopId, task: input.task, runtime: engine, currentRound: 1,
+            sessionId, loopId, task: input.task, engine, currentRound: 1,
             maxRounds, successTrajectory: [], status: "running", createdAt: Date.now(),
             consecutiveRejections: 0,
-            escalatedRejectionChecks: [],
+            lastRejectionCheck: "",
             driftClarificationStreak: 0,
             backtrackSkippedFiles: [],
             evidenceBaseline: [],
@@ -143,21 +195,6 @@ export class SessionManager {
         request.domain = input.domain ?? "";
         request.plan_source = input.planSource ?? null;
         request.constraints_from_plan = input.constraints ?? [];
-        const successCriteria = (input.successCriteria ?? [])
-            .filter((criterion) => typeof criterion === "string")
-            .map((criterion) => criterion.trim())
-            .filter(Boolean);
-        if (successCriteria.length > 0) {
-            request.loop_objective = {
-                objective: input.task,
-                success_criteria: successCriteria,
-                hard_constraints: input.constraints ?? [],
-                created_at_round: 1,
-                loop_id: loopId,
-                version: 1,
-                refinement_history: [],
-            };
-        }
         // Explicit context is requested by the MCP embedding; no auto-discovery.
         if (this.contextProvider) {
             try {
@@ -181,27 +218,17 @@ export class SessionManager {
                 logEvent("context_provider_error", { loopId, round: 1 });
             }
         }
-        const prepared = await new RoundDriver(engine, this.backend).prepare(request, loopId, 1);
-        if (!prepared) {
-            return {
-                sessionId,
-                round: 1,
-                prompt: null,
-                stopReason: "prompt_compile_failed",
-                stopDetail: "Prompt compilation failed; no session state was persisted.",
-                error: { code: "prompt_compile_failed", message: "Prompt compilation failed while starting.", retryable: true },
-            };
-        }
+        const prepared = await new RoundDriver(engine, this.loopStore).prepare(request, loopId, 1);
         const initialPrompt = prepared?.prompt ?? null;
         const initialLevel = prepared?.level ?? "l2";
         const evidenceBaseline = prepared?.evidenceBaseline ?? [];
         const session = {
-            sessionId, loopId, task: input.task, runtime: engine,
+            sessionId, loopId, task: input.task, engine,
             currentRound: 1, maxRounds, successTrajectory: [],
             status: "running", createdAt: Date.now(),
             // v1.13: Enforcement gate state
             consecutiveRejections: 0,
-            escalatedRejectionChecks: [],
+            lastRejectionCheck: "",
             driftClarificationStreak: 0,
             backtrackSkippedFiles: [],
             evidenceBaseline,
@@ -209,14 +236,23 @@ export class SessionManager {
             currentPrompt: initialPrompt,
             currentLevel: initialLevel,
             currentWarnings: prepared?.warnings ?? [],
-            currentCanonicalState: isRecord(prepared?.canonicalState)
-                ? prepared.canonicalState
-                : undefined,
+            lastCompileResponse: prepared?.compileResponse ?? null,
         };
         this.sessions.set(sessionId, session);
         policyMetrics.recordStrategy(loopId, initialLevel);
-        // Persist to vault for cross-process recovery
-        this.save(session);
+        // Persist to vault for cross-process recovery. The save is the atomic
+        // lease gate — a TOCTOU window between the pre-flight check above and
+        // this write can still lose the lease race to another process.
+        try {
+            this.lifecycle.save(session);
+        }
+        catch (error) {
+            // v3.2.1: roll back the in-memory registration — a registered-but-
+            // unsaved session would make every later create for this loopId
+            // return loop_already_running until this process restarts.
+            this.sessions.delete(sessionId);
+            throw error;
+        }
         logEvent("session_start", {
             sessionId,
             loopId,
@@ -256,156 +292,13 @@ export class SessionManager {
                 : 0,
         };
     }
-    audit(loopId) {
-        return { ...auditEntries(loopId, this.backend.queryLoopEvents(loopId)) };
-    }
-    inspect(loopId, round) {
-        const taskId = `loop:${loopId}:r${round}`;
-        const loopEntries = this.backend.queryLoopEvents(loopId);
-        const lineage = loopEntries
-            .find((entry) => entry.task_id === taskId);
-        const roundEvent = loopEntries.find((entry) => entry.task_id === `${taskId}:event`);
-        if (!lineage && !roundEvent)
-            return null;
-        const report = parseRoundReport(roundEvent?.round_report);
-        return {
-            format: "loopforge.inspect",
-            loopId,
-            round,
-            lineage: lineage ?? null,
-            roundEvent: roundEvent ? {
-                taskId: roundEvent.task_id,
-                timestamp: roundEvent.timestamp,
-                success: roundEvent.success === true,
-                report,
-                evidence: report?.evidence ?? null,
-                transaction: roundEvent.loop_lineage?.round_transaction ?? null,
-            } : null,
-        };
-    }
-    async retry(sessionId, report) {
-        const session = this.sessions.get(sessionId);
-        if (!session)
-            return { sessionId, round: 0, prompt: null, stopReason: "session_not_found" };
-        if ((session.roundSnapshot?.attempt ?? 1) <= 1) {
-            return {
-                sessionId,
-                round: session.currentRound,
-                prompt: session.currentPrompt ?? null,
-                stopReason: "retry_not_pending",
-                stopDetail: "The current round has not been rejected; submit it with loopforge_next.",
-            };
-        }
-        return this.advance(sessionId, report);
-    }
-    async backtrack(sessionId) {
-        return withSessionQueue(this.sessionQueues, sessionId, async () => {
-            const session = this.sessions.get(sessionId);
-            if (!session)
-                return { sessionId, round: 0, prompt: null, stopReason: "session_not_found" };
-            if (session.status !== "running") {
-                return { sessionId, round: session.currentRound, prompt: null, stopReason: session.status };
-            }
-            const entries = this.backend
-                ? this.backend.queryLoopEvents(session.loopId)
-                    .filter((entry) => String(entry.task_id ?? "").startsWith(`loop:${session.loopId}:r`))
-                : [];
-            const restore = findSafeRestorePoint(session.currentRound, entries, getPolicy().engine.backtrack_max_depth);
-            if (!restore) {
-                return {
-                    sessionId,
-                    round: session.currentRound,
-                    prompt: session.currentPrompt ?? null,
-                    stopReason: "no_clean_restore_point",
-                    stopDetail: "No clean round exists within the configured backtrack depth.",
-                };
-            }
-            const skippedFiles = collectSkippedRoundFiles(restore.round, session.currentRound, entries);
-            return this.buildBacktrackResult(sessionId, session, {
-                action: "backtrack",
-                roundSuccess: false,
-                shouldPushSuccessTrajectory: false,
-                newConsecutiveRejections: 0,
-                verificationFlags: [],
-                gateContradicted: false,
-                backtrackTarget: restore.round,
-                backtrackTargetGitHead: findBacktrackTargetGitHead(restore.round, entries),
-                backtrackSkippedDiscoveries: restore.skippedDiscoveries,
-                backtrackSkippedFiles: skippedFiles,
-                backtrackTriggerRule: "manual",
-                backtrackPrompt: `# Manual Backtrack\n\nRestore the workspace to the state after Round ${restore.round}, ` +
-                    "then verify the affected files before continuing. LoopForge does not execute restore commands.",
-                enforcementReason: `Manual backtrack to clean Round ${restore.round}`,
-            });
-        });
-    }
-    cognitiveProjection(sessionId) {
-        const session = this.sessions.get(sessionId);
-        if (!session)
-            return null;
-        if (session.currentCanonicalState)
-            return session.currentCanonicalState;
-        const request = buildLoopRequest(session, session.lastRoundProjection);
-        const context = session.runtime.hydrateLoopContext(session.loopId);
-        const result = session.runtime.invokeLoopCompile(request, context, {
-            persistLineage: false,
-        });
-        return isRecord(result.response?.canonical_state)
-            ? result.response.canonical_state
-            : null;
-    }
-    checkGate(action) {
-        return deriveStructuredGate(action);
-    }
-    resolveGate(sessionId, gateId, action, approved, note) {
-        const session = this.sessions.get(sessionId);
-        if (!session)
-            return { error: `session not found: ${sessionId}` };
-        const descriptor = action;
-        const classified = deriveStructuredGate(descriptor);
-        if (classified.id !== gateId) {
-            return { error: "gateId does not match the supplied action and scope" };
-        }
-        if (classified.gate.kind !== "user") {
-            return { error: "agent gates are resolved by submitting the required evidence" };
-        }
-        const decidedAt = new Date().toISOString();
-        const decision = {
-            gateId,
-            kind: classified.gate.kind,
-            approved,
-            scope: descriptor.scope,
-            note,
-            decidedAt,
-            actionHash: classified.actionHash,
-        };
-        this.appendCanonicalEvent({
-            task_id: `loop:${session.loopId}:gate:${gateId}`,
-            task_type: "gate_decision",
-            loop_id: session.loopId,
-            gate_id: gateId,
-            approved,
-            decision_note: note,
-            gate_decision: decision,
-            timestamp: decidedAt,
-            loop_lineage: { round: session.currentRound, gate_id: gateId, action_hash: classified.actionHash },
-        });
-        // Gate decisions change the derived state immediately. Do not let the
-        // status view serve a pre-decision canonical-state cache.
-        session.currentCanonicalState = undefined;
-        return { sessionId, loopId: session.loopId, gateId, approved };
-    }
     delete(sessionId) {
         const session = this.sessions.get(sessionId);
         if (!session)
             return false;
         session.status = "stopped";
-        session.stopReason = "cancelled";
-        this.save(session);
-        // Durable terminal event after the session_state write, before the
-        // in-memory session is dropped (A4).
-        this.persistTerminalEvent(session, "cancelled");
-        void this.notifyTerminal(session, "cancelled");
+        this.lifecycle.save(session);
+        void this.lifecycle.notifyTerminal(session, "cancelled");
         this.sessions.delete(sessionId);
         this.sessionQueues.delete(sessionId);
         logEvent("session_end", {
@@ -427,7 +320,7 @@ export class SessionManager {
             return { sessionId, round: session.currentRound, status: session.status };
         }
         session.status = "paused";
-        this.save(session);
+        this.lifecycle.save(session);
         logEvent("session_paused", {
             sessionId,
             loopId: session.loopId,
@@ -435,329 +328,15 @@ export class SessionManager {
         });
         return { sessionId, round: session.currentRound, status: "paused" };
     }
-    restoredPromptResult(session) {
-        if (!session.currentPrompt)
-            return null;
-        return {
-            sessionId: session.sessionId,
-            round: session.currentRound,
-            roundId: session.roundSnapshot?.roundId,
-            prompt: session.currentPrompt,
-            level: session.currentLevel ?? "l2",
-            roundSuccess: undefined,
-            warnings: (session.currentWarnings ?? []),
-        };
-    }
-    /** Reconcile the crash window where a round event committed but session_state
-     *  still points at the old prompt. Returns null when no commit is pending. */
-    async reconcileCommittedRound(session) {
-        if (!session.roundSnapshot)
-            return null;
-        const recovered = new RoundDriver(session.runtime, this.backend).recover(session.roundSnapshot);
-        if (!recovered)
-            return null;
-        const pr = recovered.result;
-        session.roundSnapshot = recovered.snapshot;
-        // Replay the committed counter. Rejections accumulate globally across
-        // all checks (v2.14) so alternating rejection reasons cannot dodge R6.
-        session.consecutiveRejections = pr.newConsecutiveRejections;
-        this.updateEscalationChecks(session, pr);
-        if (pr.newRoundProjection)
-            session.lastRoundProjection = pr.newRoundProjection;
-        if (pr.shouldPushSuccessTrajectory &&
-            session.successTrajectory.length < session.currentRound) {
-            session.successTrajectory.push(pr.roundSuccess);
-        }
-        session.currentPrompt = null;
-        if (pr.action === "stop" || pr.action === "terminate") {
-            const reason = pr.action === "terminate"
-                ? "enforcement_terminated"
-                : pr.stopReason ?? "stalled";
-            session.status = reason === "stalled" ? "stalled" : "stopped";
-            this.save(session);
-            void this.notifyTerminal(session, reason);
-            return {
-                sessionId: session.sessionId,
-                round: session.currentRound,
-                roundId: recovered.snapshot.roundId,
-                prompt: null,
-                stopReason: reason,
-                stopDetail: reason === "completed"
-                    ? "Task completed successfully — the agent declared should_continue=false with success=true."
-                    : reason === "blocked"
-                        ? "Agent cannot proceed under current constraints. The task may need revised constraints or human intervention."
-                        : reason === "failed"
-                            ? "Agent declared should_continue=false with success=false — the task was not achieved."
-                            : `Loop stopped: ${reason}.`,
-                roundSuccess: pr.roundSuccess,
-            };
-        }
-        if (pr.action === "backtrack") {
-            // Backtrack committed but prompt not delivered (crash window).
-            // Reset round counter to the restore target + 1 so the next
-            // resume / unpause compiles from the correct restored state.
-            const restoreTarget = pr.backtrackTarget ?? (session.currentRound - 1);
-            session.currentRound = restoreTarget + 1;
-            session.consecutiveRejections = 0;
-            session.escalatedRejectionChecks = [];
-            session.driftClarificationStreak = 0;
-            session.backtrackSkippedFiles = pr.backtrackSkippedFiles ?? [];
-            session.backtrackTargetGitHead = pr.backtrackTargetGitHead;
-            session.lastRoundProjection = undefined;
-            session.currentPrompt = null;
-            this.save(session);
-            // Return null — caller (resume/unpause) will recompile normally
-            return null;
-        }
-        if (pr.action !== "continue")
-            return null;
-        session.currentRound++;
-        const request = buildLoopRequest(session, session.lastRoundProjection, pr.verificationFlags);
-        const prepared = await new RoundDriver(session.runtime, this.backend).prepare(request, session.loopId, session.currentRound);
-        if (!prepared) {
-            return {
-                sessionId: session.sessionId,
-                round: session.currentRound,
-                prompt: null,
-                stopReason: "prompt_compile_failed",
-                stopDetail: "Prompt compilation failed during crash recovery; the persisted round remains unchanged and can be retried.",
-                error: { code: "prompt_compile_failed", message: "Prompt compilation failed during crash recovery.", retryable: true },
-            };
-        }
-        const prompt = prepared.prompt;
-        session.evidenceBaseline = prepared.evidenceBaseline;
-        session.roundSnapshot = prepared.snapshot;
-        session.currentPrompt = prompt;
-        session.currentLevel = prepared.level;
-        session.currentWarnings = prepared?.warnings ?? [];
-        session.currentCanonicalState = isRecord(prepared.canonicalState)
-            ? prepared.canonicalState
-            : undefined;
-        policyMetrics.recordStrategy(session.loopId, session.currentLevel);
-        this.save(session);
-        return {
-            sessionId: session.sessionId,
-            round: session.currentRound,
-            roundId: session.roundSnapshot.roundId,
-            prompt,
-            level: session.currentLevel,
-            roundSuccess: pr.roundSuccess,
-            warnings: (session.currentWarnings ?? []),
-        };
-    }
-    /** v1.18: Resume a paused session. Reconstructs from vault state and
-     *  compiles the next prompt. Returns null if no paused session exists
-     *  for this loopId. */
-    async unpause(loopId) {
-        const persistedEntry = this.findSessionEntry(loopId);
-        if (!persistedEntry)
-            return null;
-        const lineage = (persistedEntry.loop_lineage ?? {});
-        const status = lineage.status ?? "running";
-        if (status !== "paused")
-            return null;
-        const sessionEntry = this.claimSessionEntry(loopId);
-        if (!sessionEntry)
-            return this.leaseConflictResult(loopId, persistedEntry);
-        const session = this.reconstructSession(sessionEntry, true);
-        if (!session)
-            return null;
-        // Set to running so advance() works
-        session.status = "running";
-        this.sessions.set(session.sessionId, session);
-        // Replace the sync-fallback evidence baseline with async evidence
-        // so resumed sessions don't silently drop async provider data.
-        try {
-            const asyncEvidence = await EvidenceCollector.fromPolicy().collectAsync({
-                loopId: session.loopId,
-                phase: "before",
-            });
-            if (asyncEvidence.length > 0) {
-                session.evidenceBaseline = asyncEvidence;
-                if (!session.roundSnapshot?.beforeEvidence?.length) {
-                    session.roundSnapshot = prepareRoundTransaction(session.loopId, session.currentRound, asyncEvidence);
-                }
-            }
-        }
-        catch {
-            // Async evidence is best-effort; fall back to sync baseline.
-        }
-        const reconciled = await this.reconcileCommittedRound(session);
-        if (reconciled)
-            return reconciled;
-        const restored = this.restoredPromptResult(session);
-        if (restored) {
-            this.save(session);
-            return restored;
-        }
-        // Compile the next prompt from the current round state
-        const lcr = makeLoopCompileRequest({
-            loop_id: session.loopId,
-            round: session.currentRound,
-            goal_id: "",
-            task: session.task,
-            domain: undefined,
-            plan_source: null,
-            constraints_from_plan: [],
-            health_check_interval: 1,
-        });
-        const compileRequest = {
-            task: session.task,
-            mode: Mode.LOOP_COMPILE,
-            skill_name: null,
-            task_id: null,
-            loop_id: lcr.loop_id,
-            round: lcr.round,
-            goal_id: lcr.goal_id,
-            domain: lcr.domain ?? "",
-            plan_source: lcr.plan_source ?? null,
-            constraints_from_plan: lcr.constraints_from_plan ?? [],
-            health_check_interval: lcr.health_check_interval,
-            max_rounds: session.maxRounds,
-        };
-        const prepared = await new RoundDriver(session.runtime, this.backend).prepare(compileRequest, session.loopId, session.currentRound);
-        if (!prepared) {
-            return {
-                sessionId: session.sessionId,
-                round: session.currentRound,
-                prompt: null,
-                stopReason: "prompt_compile_failed",
-                stopDetail: "Prompt compilation failed while resuming; the paused session remains recoverable.",
-                error: { code: "prompt_compile_failed", message: "Prompt compilation failed during resume.", retryable: true },
-            };
-        }
-        const prompt = prepared.prompt;
-        const level = prepared.level;
-        session.evidenceBaseline = prepared.evidenceBaseline;
-        session.roundSnapshot = prepared.snapshot;
-        session.currentPrompt = prompt;
-        session.currentLevel = level;
-        session.currentWarnings = prepared?.warnings ?? [];
-        session.currentCanonicalState = isRecord(prepared.canonicalState)
-            ? prepared.canonicalState
-            : undefined;
-        policyMetrics.recordStrategy(session.loopId, level);
-        this.save(session);
-        return {
-            sessionId: session.sessionId,
-            round: session.currentRound,
-            roundId: session.roundSnapshot.roundId,
-            prompt,
-            level,
-            roundSuccess: undefined,
-            warnings: [],
-        };
-    }
-    /** Persist session state to vault for cross-process recovery.
-     *  The filtered vault and replacement entry are written once under the
-     *  backend lock, so recovery never observes the old two-write gap. */
+    /** Persist session state to vault for cross-process recovery. Delegates to
+     *  the round lifecycle, which owns the durable session document shape. */
     save(session) {
-        if (!this.sessionStore)
-            return;
-        const leaseActive = session.status === "running";
-        const sessionEntry = {
-            task_id: `loop:${session.loopId}:session`,
-            task_type: "session_state",
-            timestamp: new Date().toISOString(),
-            loop_id: session.loopId,
-            task: session.task,
-            loop_lineage: {
-                session_id: session.sessionId,
-                current_round: session.currentRound,
-                max_rounds: session.maxRounds,
-                success_trajectory: session.successTrajectory,
-                status: session.status,
-                created_at: session.createdAt,
-                // v1.13: Enforcement gate state
-                consecutive_rejections: session.consecutiveRejections,
-                // Enforcement escalation is tracked per terminal rule.
-                escalated_rejection_checks: session.escalatedRejectionChecks,
-                // v2.12: Clarification streak
-                drift_clarification_streak: session.driftClarificationStreak,
-                // v2.13: Backtrack skipped files for workspace restore check
-                backtrack_skipped_files: session.backtrackSkippedFiles,
-                // v2.13: Git HEAD of the active backtrack restore point
-                backtrack_target_git_head: session.backtrackTargetGitHead ?? "",
-                // v1.19: durable round transaction state
-                round_snapshot: session.roundSnapshot ?? null,
-                current_prompt: session.currentPrompt ?? null,
-                current_level: session.currentLevel ?? "",
-                stop_reason: session.stopReason ?? "",
-                // v1.20: cross-process single-owner lease
-                lease_owner: leaseActive ? this.ownerId : "",
-                lease_expires_at: leaseActive ? Date.now() + this.leaseMs : 0,
-            },
-        };
-        this.sessionStore.save(sessionEntry, {
-            expectedLeaseOwner: this.ownerId,
-        });
-    }
-    /** Reconstruct a McpSession from a vault session_state entry.
-     *  Returns null if the entry is not "running" status.
-     *  Shared by resume() and autoResumeAll(). */
-    reconstructSession(entry, allowPaused = false) {
-        const lineage = (entry.loop_lineage ?? {});
-        const status = lineage.status ?? "running";
-        if (status !== "running" && !(allowPaused && status === "paused")) {
-            return null;
-        }
-        const loopId = entry.loop_id;
-        const currentRound = lineage.current_round ?? 1;
-        const successTrajectory = Array.isArray(lineage.success_trajectory)
-            ? lineage.success_trajectory.filter((value) => typeof value === "boolean")
-            : [];
-        const task = entry.task ?? "";
-        const maxRounds = lineage.max_rounds ?? getPolicy().engine.max_rounds;
-        const roundSnapshot = parseRoundTransactionSnapshot(lineage.round_snapshot);
-        const latestReport = this.backend.queryLoopEvents(loopId)
-            .filter((entry) => String(entry.task_id ?? "").startsWith(`loop:${loopId}:r`) && String(entry.task_id ?? "").endsWith(":event"))
-            .map((roundEvent) => ({
-            round: typeof roundEvent.loop_lineage?.round === "number"
-                ? roundEvent.loop_lineage.round
-                : 0,
-            report: parseRoundReport(roundEvent.round_report),
-        })).filter((candidate) => candidate.report !== null)
-            .sort((a, b) => b.round - a.round)[0]?.report;
-        const lastRoundProjection = latestReport
-            ? deriveCompilerProjection(latestReport, currentRound - 1)
-            : undefined;
-        const engine = new RuntimeServices(this.backend);
-        return {
-            sessionId: typeof lineage.session_id === "string" && lineage.session_id
-                ? lineage.session_id
-                : randomUUID(),
-            loopId, task, runtime: engine,
-            currentRound, maxRounds, successTrajectory,
-            status: status,
-            createdAt: lineage.created_at ?? Date.now(),
-            consecutiveRejections: lineage.consecutive_rejections ?? 0,
-            escalatedRejectionChecks: Array.isArray(lineage.escalated_rejection_checks)
-                ? lineage.escalated_rejection_checks.filter((value) => typeof value === "string")
-                : [],
-            driftClarificationStreak: lineage.drift_clarification_streak ?? 0,
-            backtrackSkippedFiles: lineage.backtrack_skipped_files ?? [],
-            backtrackTargetGitHead: typeof lineage.backtrack_target_git_head === "string" &&
-                lineage.backtrack_target_git_head
-                ? lineage.backtrack_target_git_head
-                : undefined,
-            evidenceBaseline: roundSnapshot?.beforeEvidence ?? [],
-            roundSnapshot: roundSnapshot ?? prepareRoundTransaction(loopId, currentRound, []),
-            lastRoundProjection,
-            currentPrompt: typeof lineage.current_prompt === "string"
-                ? lineage.current_prompt
-                : null,
-            currentLevel: typeof lineage.current_level === "string"
-                ? lineage.current_level
-                : undefined,
-            stopReason: typeof lineage.stop_reason === "string" && lineage.stop_reason
-                ? lineage.stop_reason
-                : undefined,
-        };
+        this.lifecycle.save(session);
     }
     /** Resume a loop from vault state.
      *  Reconstructs the session and compiles the prompt for the next round.
      *  Returns null if no session_state entry exists for this loopId. */
-    async resume(loopId) {
+    resume(loopId) {
         const persistedEntry = this.findSessionEntry(loopId);
         if (!persistedEntry)
             return null;
@@ -768,7 +347,7 @@ export class SessionManager {
             : persistedEntry;
         if (!sessionEntry)
             return this.leaseConflictResult(loopId, persistedEntry);
-        const session = this.reconstructSession(sessionEntry);
+        const session = this.lifecycle.reconstructSession(sessionEntry);
         if (!session) {
             // was not "running" — return stopped/stalled status
             const lineage = (sessionEntry.loop_lineage ?? {});
@@ -783,47 +362,29 @@ export class SessionManager {
             };
         }
         this.sessions.set(session.sessionId, session);
-        const reconciled = await this.reconcileCommittedRound(session);
-        if (reconciled)
-            return reconciled;
-        const restored = this.restoredPromptResult(session);
-        if (restored)
-            return restored;
-        // A persisted session may lack a prompt after an interrupted handoff;
-        // compile the current canonical state once and persist the replacement.
-        const request = buildLoopRequest(session);
-        const prepared = await new RoundDriver(session.runtime, this.backend).prepare(request, session.loopId, session.currentRound);
-        if (!prepared) {
-            return {
-                sessionId: session.sessionId,
-                round: session.currentRound,
-                roundId: session.roundSnapshot?.roundId,
-                prompt: null,
-                stopReason: "prompt_compile_failed",
-                stopDetail: "Prompt compilation failed; the persisted session remains unchanged and can be retried.",
-                error: { code: "prompt_compile_failed", message: "Prompt compilation failed while resuming.", retryable: true },
-            };
-        }
-        const prompt = prepared.prompt;
-        session.evidenceBaseline = prepared.evidenceBaseline;
-        session.roundSnapshot = prepared.snapshot;
-        session.currentPrompt = prompt;
-        session.currentLevel = prepared?.level ?? "l2";
-        session.currentWarnings = prepared?.warnings ?? [];
-        session.currentCanonicalState = isRecord(prepared?.canonicalState)
-            ? prepared.canonicalState
-            : undefined;
-        policyMetrics.recordStrategy(session.loopId, session.currentLevel);
-        this.save(session);
-        return {
-            sessionId: session.sessionId,
-            round: session.currentRound,
-            roundId: session.roundSnapshot.roundId,
-            prompt,
-            level: session.currentLevel,
-            roundSuccess: false,
-            warnings: (session.currentWarnings ?? []),
-        };
+        return this.lifecycle.resume(session);
+    }
+    /** v1.18: Resume a paused session. Reconstructs from vault state and
+     *  compiles the next prompt. Returns null if no paused session exists
+     *  for this loopId. */
+    async unpause(loopId) {
+        const persistedEntry = this.findSessionEntry(loopId);
+        if (!persistedEntry)
+            return null;
+        const lineage = (persistedEntry.loop_lineage ?? {});
+        const status = lineage.status ?? "running";
+        if (status !== "paused")
+            return null;
+        const sessionEntry = this.claimSessionEntry(loopId);
+        if (!sessionEntry)
+            return this.leaseConflictResult(loopId, persistedEntry);
+        const session = this.lifecycle.reconstructSession(sessionEntry, true);
+        if (!session)
+            return null;
+        // Set to running so advance() works
+        session.status = "running";
+        this.sessions.set(session.sessionId, session);
+        return this.lifecycle.unpause(session);
     }
     /** Auto-resume all "running" sessions from vault on server startup.
      *  Scans vault for session_state entries, reconstructs each as an in-memory
@@ -852,7 +413,20 @@ export class SessionManager {
             const claimedEntry = this.claimSessionEntry(lid);
             if (!claimedEntry)
                 continue;
-            const session = this.reconstructSession(claimedEntry, true);
+            // v2.14: a bulk startup scan must not die on one corrupt loop —
+            // recoverable gaps are recorded and skipped; corrupted storage
+            // (invalid JSON/format/sequence) still surfaces to the caller.
+            let session = null;
+            try {
+                session = this.lifecycle.reconstructSession(claimedEntry, true);
+            }
+            catch (error) {
+                if (error instanceof StorageCorruptionError && error.recoverable) {
+                    logEvent("session_skip_gap", { loopId: lid, error: error.message });
+                    continue;
+                }
+                throw error;
+            }
             if (session) {
                 this.sessions.set(session.sessionId, session);
                 activeLoopIds.add(lid);
@@ -895,55 +469,143 @@ export class SessionManager {
         }
         return result;
     }
-    /** Stable signature over the vault event list. A changed signature means the
-     *  vault has grown or an idempotent replacement landed, so the cached
-     *  snapshot must be recomputed. Physical order is stable: writeEntry appends,
-     *  and replacements update in place. */
-    metricsSignature(entries) {
-        const hash = createHash("sha256");
-        for (const entry of entries) {
-            hash.update(entry.task_id ?? "");
-            hash.update("\\u0000");
-            hash.update(entry.timestamp ?? "");
-            hash.update("\\u0000");
-            hash.update(String(entry.event_sequence ?? ""));
-            hash.update("\\u0000");
-            hash.update(entry.task_type ?? "");
-        }
-        return hash.digest("hex");
-    }
-    /** Policy metrics that survive process restarts: durable events are
-     *  replayed through derivePolicyMetrics and merged with live in-process
-     *  observations (rejections never reach the vault). */
-    getLoopPolicyMetrics(loopId) {
-        const entries = this.backend.queryLoopEvents(loopId);
-        const signature = this.metricsSignature(entries);
-        const cached = this.derivedMetricsCache.get(loopId);
-        if (cached && cached.signature === signature)
-            return cached.snapshot;
-        const snapshot = mergePolicyMetrics(derivePolicyMetrics(loopId, entries), policyMetrics.snapshot(loopId));
-        this.derivedMetricsCache.set(loopId, { signature, snapshot });
-        return snapshot;
+    // ── v2.12: User/Agent gates ────────────────────────────────────────────
+    /** Classify a flat gate text. Read-only — no vault writes. */
+    checkGate(gateText) {
+        const { id, gate } = deriveGate(gateText);
+        return {
+            id,
+            kind: gate.kind,
+            ...(gate.kind === "user"
+                ? {
+                    question: gate.question,
+                    blockedScope: gate.blockedScope,
+                    allowedWork: gate.allowedWork,
+                }
+                : {
+                    problem: gate.problem,
+                    requiredEvidence: gate.requiredEvidence,
+                    suggestedResolution: gate.suggestedResolution,
+                }),
+        };
     }
-    /** Append a durable session_end event for a terminal transition. Call after
-     *  the session_state write so a failure here only loses a metric, never the
-     *  stopped status. The fixed task_id makes repeated terminals idempotent. */
-    persistTerminalEvent(session, stopReason, extra) {
-        this.appendCanonicalEvent({
-            task_id: `loop:${session.loopId}:end`,
-            task_type: "session_end",
+    /** Record a user decision for a recorded gate. The gateId embeds the
+     *  canonicalized action hash — if the action changed, the match fails and
+     *  the old approval expires automatically. */
+    resolveGate(sessionId, gateId, approved, note) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return { error: `session not found: ${sessionId}` };
+        const prefix = `loop:${session.loopId}:gate:`;
+        const opened = queryLoopEntries(this.loopStore, session.loopId, { prefix })
+            .find((entry) => entry.task_type === "gate_opened" && entry.gate_id === gateId);
+        if (!opened) {
+            return { error: `no gate_opened record for gate ${gateId} — the gate may have expired or was never recorded` };
+        }
+        const actionText = typeof opened.gate_action === "string" ? opened.gate_action : "";
+        const { id, gate, actionHash } = deriveGate(actionText);
+        if (id !== gateId) {
+            return { error: "gateId does not match the recorded action — the action changed, old approvals expire" };
+        }
+        if (gate.kind !== "user") {
+            return { error: "agent gates are resolved by submitting the required evidence, not by user approval" };
+        }
+        const decision = makeGateDecision({
+            gateId,
+            kind: "user",
+            approved: approved === true,
+            scope: gate.blockedScope ?? [],
+            note: typeof note === "string" ? note : "",
+            decidedAt: new Date().toISOString(),
+            actionHash: actionHash ?? "",
+        });
+        const entry = {
+            id: randomUUID(),
+            task_id: `loop:${session.loopId}:gate:${gateId}:decision`,
+            task_type: "gate_decision",
             loop_id: session.loopId,
-            task: session.task,
             timestamp: new Date().toISOString(),
+            gate_id: gateId,
+            approved: decision.approved,
+            decision_note: decision.note,
+            gate_decision: decision,
             loop_lineage: {
                 round: session.currentRound,
-                session_id: session.sessionId,
-                stop_reason: stopReason,
-                success_trajectory: session.successTrajectory,
-                consecutive_rejections: session.consecutiveRejections,
-                ...extra,
+                gate_id: gateId,
+                action_hash: actionHash,
             },
+        };
+        this.loopStore.appendEntry(entry);
+        return { sessionId, loopId: session.loopId, gateId, approved: decision.approved };
+    }
+    // ── v2.12: Typed projection + audit ────────────────────────────────────
+    /** Typed cognitive state projection for an active session. Derived on
+     *  demand — zero persistence. Null when nothing meaningful exists yet. */
+    getProjection(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return null;
+        const entries = queryLoopEntries(this.loopStore, session.loopId, { prefix: `loop:${session.loopId}:` });
+        let compileResponse = null;
+        // v3.0.1: the round boundary already compiled this round — derive the
+        // projection from that response instead of recompiling the whole vault.
+        // The cache is invalidated by every compile path (it is rebuilt with the
+        // new round's response); the artifact's deterministic roundId guards
+        // against stale reuse.
+        const cached = session.lastCompileResponse;
+        const expectedRoundId = session.roundSnapshot?.roundId
+            ?? makeRoundId(session.loopId, session.currentRound);
+        if (cached?.prompt_artifact && cached.prompt_artifact.roundId === expectedRoundId) {
+            compileResponse = cached;
+        }
+        else {
+            try {
+                const request = {
+                    task: session.task,
+                    mode: Mode.LOOP_COMPILE,
+                    feedback: null,
+                    skill_name: null,
+                    task_id: null,
+                    loop_id: session.loopId,
+                    round: session.currentRound,
+                    max_rounds: session.maxRounds,
+                    verification_flags: [],
+                };
+                const compiled = session.engine.invokeLoopCompile(request, undefined, { persistLineage: false });
+                compileResponse = compiled.response ?? null;
+            }
+            catch {
+                compileResponse = null; // projection degrades gracefully
+            }
+        }
+        const openGates = this.lifecycle.listOpenGateDescriptions(session.loopId);
+        const projection = buildLoopProjection({
+            loopId: session.loopId,
+            currentRound: session.currentRound,
+            compileResponse,
+            vaultEntries: entries,
+            verifiedClaims: listVerifiedClaims(entries, session.loopId),
+            openGates,
         });
+        return projection ? { ...projection } : null;
+    }
+    /** Read-only end-of-loop audit (verification view). Never writes. */
+    getAudit(loopId) {
+        validateLoopId(loopId);
+        const entries = queryLoopEntries(this.loopStore, loopId, { prefix: `loop:${loopId}:` });
+        const audit = buildAudit(loopId, entries, this.loopStore);
+        return { ...audit };
+    }
+    /** v2.12: Policy metrics that survive restarts — vault-derived round
+     *  statistics (A4 port) folded with this process's live observations.
+     *  Non-durable fields (evidence, vault errors) come from live only. */
+    getPolicyMetrics(loopId) {
+        const entries = queryLoopEntries(this.loopStore, loopId, { prefix: `loop:${loopId}:` });
+        const derived = derivePolicyMetrics(loopId, entries);
+        const live = policyMetrics.snapshot(loopId);
+        if (derived.committedRounds === 0)
+            return live;
+        return mergePolicyMetrics(derived, live);
     }
     /** Get loop health for a loop (in-memory or vault).
      *  Computes goal alignment, constraint integrity, drift, strategy stability. */
@@ -954,8 +616,8 @@ export class SessionManager {
         for (const s of this.sessions.values()) {
             if (s.loopId === loopId) {
                 task = s.task;
-                if (s.runtime.state?.task_id) {
-                    goalId = s.runtime.state.task_id;
+                if (s.engine.state?.task_id) {
+                    goalId = s.engine.state.task_id;
                 }
                 break;
             }
@@ -970,7 +632,7 @@ export class SessionManager {
         if (!task)
             return null;
         // Hydrate vault context
-        const engine = new RuntimeServices(this.backend);
+        const engine = new LoopForgeEngine(this.loopStore);
         const vaultContext = engine.hydrateLoopContext(loopId);
         // Build a minimal request for health check
         const request = makeLoopCompileRequest({
@@ -987,32 +649,27 @@ export class SessionManager {
             drift_detected: health.drift_detected,
             strategy_stability: health.strategy_stability,
             task_continuity: health.task_continuity,
-            policy_metrics: this.getLoopPolicyMetrics(loopId),
+            policy_metrics: this.getPolicyMetrics(loopId),
         };
     }
-    /** Core cycle for a canonical structured round report. Free-form output is
-     *  intentionally ignored; the runtime never guesses state from text. */
-    async advance(sessionId, report) {
-        return withSessionQueue(this.sessionQueues, sessionId, async () => {
+    /** Core cycle: extract self-eval → record feedback → check stop → compile next.
+     *  The lease + per-session queue wrap the RoundLifecycle state machine.
+     *  @param preExtractedEval Optional pre-built SelfEvaluation from MCP tool parameter.
+     *    When provided (MCP path with evaluation parameter), skips regex extraction.
+     *    When undefined (runtime/CLI path), falls back to regex extraction from output.
+     *  @param roundId v3.0.1: The roundId of the round this submission reports on
+     *    (from the last start/next/resume response). Anchors the submission so a
+     *    stale or duplicate submission is not processed against a later round.
+     *    Optional for library callers — when absent the anchor check is skipped. */
+    async advance(sessionId, output, preExtractedEval, roundId) {
+        return this.withSessionQueue(sessionId, async () => {
             const session = this.sessions.get(sessionId);
             if (session?.status === "running" &&
                 !this.renewSessionLease(session.loopId)) {
                 return this.leaseConflictResult(session.loopId, this.findSessionEntry(session.loopId));
             }
             try {
-                const normalized = parseRoundReport(report);
-                if (!normalized) {
-                    return {
-                        sessionId,
-                        round: session?.currentRound ?? 0,
-                        roundId: session?.roundSnapshot?.roundId,
-                        prompt: session?.currentPrompt ?? null,
-                        stopReason: "invalid_round_report",
-                        stopDetail: "The submitted report is not a valid canonical RoundReport. The current round remains unchanged and can be retried.",
-                        roundSuccess: false,
-                    };
-                }
-                return await this.advanceUnlocked(sessionId, normalized.summary, normalized);
+                return await this.lifecycle.advance(sessionId, output, preExtractedEval, roundId);
             }
             catch (error) {
                 if (error instanceof SessionLeaseConflictError) {
@@ -1022,469 +679,13 @@ export class SessionManager {
             }
         });
     }
-    // ── advanceUnlocked pipeline ───────────────────────────────────────────
-    //
-    // The method is split into focused private helpers so each phase of the
-    // round-boundary decision loop is independently readable and testable.
-    //
-    // Pipeline: validate → extract → execute transaction → route disposition
-    //           → advance to next round (continue) or return terminal result.
-    /** Execute the round transaction and apply global rejection tracking.
-     *  MUTATES: session.roundSnapshot, session.consecutiveRejections,
-     *           session.escalatedRejectionChecks, session.lastRoundProjection,
-     *           session.successTrajectory, session.driftClarificationStreak */
-    async executeRoundTransaction(session, roundReport) {
-        const snapshot = session.roundSnapshot ?? prepareRoundTransaction(session.loopId, session.currentRound, session.evidenceBaseline ?? []);
-        const completed = await new RoundDriver(session.runtime, this.backend).complete({
-            snapshot,
-            loopId: session.loopId,
-            task: session.task,
-            maxRounds: session.maxRounds,
-            roundReport,
-            previousProjection: session.lastRoundProjection,
-            consecutiveRejections: session.consecutiveRejections,
-            successTrajectory: session.successTrajectory,
-            driftClarificationStreak: session.driftClarificationStreak,
-            escalatedRejectionChecks: session.escalatedRejectionChecks,
-            backtrackSkippedFiles: session.backtrackSkippedFiles,
-            backtrackTargetGitHead: session.backtrackTargetGitHead,
-            expectedAction: isRecord(session.currentCanonicalState?.todoProjection) &&
-                session.currentCanonicalState.todoProjection.sourceId !== "objective" &&
-                typeof session.currentCanonicalState.suggestedNextAction === "string"
-                ? session.currentCanonicalState.suggestedNextAction
-                : undefined,
-            remainingCriteria: Array.isArray(session.currentCanonicalState?.remainingCriteria)
-                ? session.currentCanonicalState.remainingCriteria.filter((value) => typeof value === "string")
-                : [],
-        });
-        const outcome = completed.outcome;
-        const actualEvidence = completed.actualEvidence;
-        session.roundSnapshot = outcome.snapshot;
-        const pr = outcome.result;
-        policyMetrics.recordStrategyOutcome(session.loopId, session.currentLevel, pr, outcome.replayed);
-        // v2.12: Clarification streak tracking — independent of rejection tracking.
-        // Reset on rounds without intent_drift; track substantive vs weak clarifications.
-        this.updateClarificationStreak(session, pr);
-        // v2.14: Global rejection tracking — rejections accumulate across ALL
-        // checks. The coordinator increments unconditionally; alternating
-        // rejection reasons can no longer reset the R6 counter.
-        session.consecutiveRejections = pr.newConsecutiveRejections;
-        this.updateEscalationChecks(session, pr);
-        // v2.13: A new backtrack decision supersedes the previous restore point.
-        if (pr.action === "backtrack") {
-            session.backtrackTargetGitHead = pr.backtrackTargetGitHead;
-        }
-        if (pr.newRoundProjection)
-            session.lastRoundProjection = pr.newRoundProjection;
-        if (pr.shouldPushSuccessTrajectory) {
-            session.successTrajectory.push(pr.roundSuccess);
-        }
-        if (pr.action === "continue" || pr.action === "stop") {
-            session.currentCanonicalState = undefined;
-        }
-        return { pr, verificationFlags: pr.verificationFlags, actualEvidence };
-    }
-    /** v2.12: Update the clarification streak based on the round result.
-     *  - Substantive clarification (anchors present): keep streak — genuine pivot.
-     *  - No intent_drift this round: reset streak to 0.
-     *  - Weak clarification rejected by R7: streak was already consumed by
-     *    enforceIntentDrift to decide reject vs terminate; staleness is handled
-     *    on the enforcement side. We sync the persisted counter for crash recovery.
-     *  MUTATES: session.driftClarificationStreak */
-    updateClarificationStreak(session, pr) {
-        const hasIntentDrift = pr.verificationFlags.some((f) => f.check === "intent_drift");
-        if (!hasIntentDrift) {
-            // No drift this round — reset streak
-            session.driftClarificationStreak = 0;
-            return;
-        }
-        // A runtime-verified clarification closes the drift episode.
-        if (pr.clarificationAccepted) {
-            session.driftClarificationStreak = 0;
-            return;
-        }
-        // R7 rejected (weak or no clarification). The enforcement gate
-        // already used the streak to decide reject vs terminate.
-        // Increment the persisted counter so crash recovery sees it.
-        session.driftClarificationStreak += 1;
-    }
-    /** Persist terminal-rule escalation independently for each enforcement
-     * check. A non-rejection ends the current rejection episode and clears the
-     * set; rejected rules retain their marker until the episode resolves. */
-    updateEscalationChecks(session, pr) {
-        if (pr.action !== "reject") {
-            session.escalatedRejectionChecks = [];
-            return;
-        }
-        if (pr.escalationIssued && pr.rejectionCheck) {
-            const checks = new Set(session.escalatedRejectionChecks);
-            checks.add(pr.rejectionCheck);
-            session.escalatedRejectionChecks = [...checks].sort();
-        }
-    }
-    /** Build a rejection result: compile a retry prompt, persist, return.
-     *  MUTATES: session.roundSnapshot, session.currentPrompt, session.currentLevel */
-    async buildRejectionResult(sessionId, session, pr, verificationFlags) {
-        const retryRequest = buildLoopRequest(session, undefined, verificationFlags);
-        const preparedRetry = await new RoundDriver(session.runtime, this.backend).prepareRetry(retryRequest, session.roundSnapshot, pr.rejectionPrompt ?? "", session.consecutiveRejections);
-        if (!preparedRetry) {
-            return {
-                sessionId,
-                round: session.currentRound,
-                roundId: session.roundSnapshot?.roundId,
-                prompt: null,
-                stopReason: "prompt_compile_failed",
-                stopDetail: "Retry prompt compilation failed; the rejected attempt remains retryable.",
-                error: { code: "prompt_compile_failed", message: "Retry prompt compilation failed.", retryable: true },
-            };
-        }
-        session.roundSnapshot = preparedRetry.snapshot;
-        session.currentPrompt = preparedRetry.prompt;
-        session.currentLevel = preparedRetry.level;
-        session.currentWarnings = preparedRetry.warnings ?? [];
-        session.currentCanonicalState = isRecord(preparedRetry.canonicalState)
-            ? preparedRetry.canonicalState
-            : undefined;
-        this.save(session);
-        return {
-            sessionId,
-            round: session.currentRound,
-            roundId: session.roundSnapshot.roundId,
-            prompt: preparedRetry.prompt,
-            level: preparedRetry.level,
-            enforcementAction: "reject",
-            enforcementReason: pr.enforcementReason,
-        };
-    }
-    /** v2.10: Build a backtrack result — roll back to last clean round.
-     *  Resets the round counter to the restore target + 1, merges preserved
-     *  discoveries, compiles from the restored state, and injects the
-     *  backtrack prompt at the top.
-     *  MUTATES: session.currentRound, session.roundSnapshot,
-     *           session.currentPrompt, session.currentLevel,
-     *           session.consecutiveRejections, session.lastRoundProjection */
-    async buildBacktrackResult(sessionId, session, pr) {
-        const skippedUntilRound = session.currentRound;
-        const restoreTarget = pr.backtrackTarget ?? (skippedUntilRound - 1);
-        const newRound = restoreTarget + 1;
-        logEvent("session_backtrack", {
-            sessionId,
-            loopId: session.loopId,
-            fromRound: skippedUntilRound,
-            toRound: newRound,
-            triggerRule: pr.backtrackTriggerRule ?? "",
-            skippedDiscoveries: (pr.backtrackSkippedDiscoveries ?? []).length,
-        });
-        // Reset session to the restored round
-        session.currentRound = newRound;
-        session.consecutiveRejections = 0;
-        session.escalatedRejectionChecks = [];
-        session.driftClarificationStreak = 0;
-        session.backtrackSkippedFiles = pr.backtrackSkippedFiles ?? [];
-        session.backtrackTargetGitHead = pr.backtrackTargetGitHead;
-        session.lastRoundProjection = undefined; // force L2 recompile from vault state
-        session.currentPrompt = null;
-        const skippedRounds = Array.from({ length: Math.max(0, skippedUntilRound - restoreTarget - 1) }, (_, index) => restoreTarget + 1 + index);
-        this.appendCanonicalEvent({
-            task_id: `loop:${session.loopId}:backtrack:${randomUUID()}`,
-            task_type: "backtrack",
-            loop_id: session.loopId,
-            format: "loopforge.event",
-            timestamp: new Date().toISOString(),
-            loop_lineage: {
-                round: newRound,
-                restore_round: restoreTarget,
-                skipped_rounds: skippedRounds,
-                skipped_files: session.backtrackSkippedFiles,
-                trigger_rule: pr.backtrackTriggerRule ?? "",
-                reason: pr.enforcementReason ?? "",
-            },
-        });
-        // Preserve discoveries from skipped rounds as constraints_from_plan
-        // so they survive the compilation and re-enter active constraints.
-        const preservedDiscoveries = pr.backtrackSkippedDiscoveries ?? [];
-        // Compile the restored prompt — use a fresh request with the restored round
-        const request = {
-            task: session.task,
-            mode: Mode.LOOP_COMPILE,
-            skill_name: null,
-            task_id: null,
-            loop_id: session.loopId,
-            round: newRound,
-            max_rounds: session.maxRounds,
-            verification_flags: pr.verificationFlags,
-            constraints_from_plan: preservedDiscoveries,
-        };
-        const prepared = await new RoundDriver(session.runtime, this.backend).prepare(request, session.loopId, newRound);
-        if (!prepared || !prepared.prompt) {
-            return {
-                sessionId,
-                round: newRound,
-                prompt: null,
-                stopReason: "prompt_compile_failed",
-                stopDetail: "Backtrack prompt compilation failed; the restore decision remains persisted and retryable.",
-                error: { code: "prompt_compile_failed", message: "Backtrack prompt compilation failed.", retryable: true },
-                enforcementAction: "backtrack",
-                enforcementReason: pr.enforcementReason,
-                restoreRound: restoreTarget,
-                skippedRounds,
-                skippedFiles: session.backtrackSkippedFiles,
-                recoveryRequirements: [
-                    "Restore the workspace to the selected clean round.",
-                    "Verify every skipped file before continuing.",
-                ],
-            };
-        }
-        // Inject backtrack prompt at the top of the compiled prompt
-        const backtrackHeader = pr.backtrackPrompt ?? "";
-        const fullPrompt = backtrackHeader
-            ? backtrackHeader + "\n" + (prepared.prompt ?? "")
-            : prepared.prompt ?? "";
-        session.evidenceBaseline = prepared.evidenceBaseline;
-        session.roundSnapshot = prepared.snapshot;
-        session.currentPrompt = fullPrompt;
-        session.currentLevel = prepared.level;
-        session.currentWarnings = prepared?.warnings ?? [];
-        session.currentCanonicalState = isRecord(prepared.canonicalState)
-            ? prepared.canonicalState
-            : undefined;
-        this.save(session);
-        return {
-            sessionId,
-            round: newRound,
-            roundId: session.roundSnapshot?.roundId,
-            prompt: fullPrompt,
-            level: prepared.level,
-            enforcementAction: "backtrack",
-            enforcementReason: pr.enforcementReason,
-            warnings: prepared?.warnings ?? [],
-            restoreRound: restoreTarget,
-            skippedRounds,
-            skippedFiles: session.backtrackSkippedFiles,
-            recoveryRequirements: [
-                "Restore the workspace to the selected clean round.",
-                "Verify every skipped file before continuing.",
-            ],
-        };
-    }
-    /** Build a termination result: persist stopped status, notify sinks.
-     *  MUTATES: session.status, session.currentPrompt */
-    buildTerminationResult(sessionId, session, pr) {
-        session.status = "stopped";
-        session.currentPrompt = null;
-        this.save(session);
-        // Durable terminal event after the session_state write (A4): a failure
-        // here only loses a metric, never the stopped status.
-        this.persistTerminalEvent(session, "enforcement_terminated", {
-            enforcement_reason: pr.enforcementReason,
-        });
-        void this.notifyTerminal(session, "enforcement_terminated");
-        logEvent("session_end", {
-            sessionId, loopId: session.loopId,
-            stopReason: "enforcement_terminated", round: session.currentRound,
-        });
-        return {
-            sessionId,
-            round: session.currentRound,
-            roundId: session.roundSnapshot?.roundId,
-            prompt: null,
-            stopReason: "enforcement_terminated",
-            stopDetail: pr.enforcementReason ?? "The enforcement gate terminated the loop.",
-            enforcementAction: "terminate",
-            enforcementReason: pr.enforcementReason,
-        };
-    }
-    /** Build a stop result: persist stopped/stalled status, notify sinks.
-     *  MUTATES: session.status, session.currentPrompt */
-    buildStopResult(sessionId, session, pr) {
-        const reason = pr.stopReason ?? "stalled";
-        session.status = reason === "stalled" ? "stalled" : "stopped";
-        session.currentPrompt = null;
-        this.save(session);
-        // Durable terminal event after the session_state write (A4).
-        this.persistTerminalEvent(session, reason);
-        void this.notifyTerminal(session, reason);
-        logEvent("session_end", { sessionId, loopId: session.loopId, stopReason: reason, round: session.currentRound });
-        return {
-            sessionId, round: session.currentRound,
-            roundId: session.roundSnapshot?.roundId,
-            prompt: null, stopReason: reason,
-            stopDetail: pr.stopReason === "circuit_breaker"
-                ? "The last consecutive accepted rounds all failed without recovery, triggering the circuit breaker."
-                : pr.stopReason === "max_rounds"
-                    ? "The configured maximum number of rounds has been reached."
-                    : `Loop stopped: ${reason}.`,
-            roundSuccess: pr.roundSuccess,
-        };
-    }
-    /** Compile the next round's prompt and advance the session.
-     *  Includes the commit fence (pause/delete race guard) and context provider.
-     *  MUTATES: session.currentRound, session.currentPrompt, session.currentLevel,
-     *           session.evidenceBaseline, session.roundSnapshot */
-    async advanceToNextRound(sessionId, session, pr, verificationFlags, actualEvidence) {
-        const roundSuccess = pr.roundSuccess;
-        const nextRound = session.currentRound + 1;
-        // v1.8: Memory injection — tier-aware external context.
-        let externalCtx = "";
-        if (this.contextProvider) {
-            try {
-                externalCtx = (await this.contextProvider({
-                    loopId: session.loopId,
-                    round: nextRound,
-                    task: session.task,
-                    domain: "",
-                    lastRoundView: session.lastRoundProjection,
-                })).trim();
-            }
-            catch {
-                logEvent("context_provider_error", {
-                    loopId: session.loopId,
-                    round: nextRound,
-                });
-            }
-        }
-        // Commit fence: pause()/delete() may have run while the context provider
-        // was awaited. Do not compile if the session is no longer running.
-        if (this.sessions.get(sessionId) !== session || session.status !== "running") {
-            return {
-                sessionId,
-                round: session.currentRound,
-                prompt: null,
-                stopReason: session.status,
-                stopDetail: `Session is no longer running (status: ${session.status}). It was paused or deleted while the context provider was running.`,
-                roundSuccess,
-            };
-        }
-        const request = buildLoopRequest({ ...session, currentRound: nextRound }, session.lastRoundProjection, verificationFlags);
-        if (externalCtx) {
-            request.external_context = externalCtx;
-        }
-        const prepared = await new RoundDriver(session.runtime, this.backend).prepare(request, session.loopId, nextRound);
-        if (!prepared) {
-            return {
-                sessionId,
-                round: session.currentRound,
-                roundId: session.roundSnapshot?.roundId,
-                prompt: null,
-                stopReason: "prompt_compile_failed",
-                stopDetail: "Prompt compilation failed; the current round remains unchanged and can be retried.",
-                roundSuccess,
-                error: { code: "prompt_compile_failed", message: "Prompt compilation failed while advancing.", retryable: true },
-            };
-        }
-        const nextPrompt = prepared.prompt;
-        const nextLevel = prepared.level;
-        const nextBaseline = prepared.evidenceBaseline ?? actualEvidence;
-        // Clear backtrack restore state only after the next prompt is ready.
-        session.backtrackSkippedFiles = [];
-        session.backtrackTargetGitHead = undefined;
-        session.currentRound = nextRound;
-        session.currentPrompt = null;
-        session.evidenceBaseline = nextBaseline;
-        session.roundSnapshot = prepared?.snapshot ?? prepareRoundTransaction(session.loopId, session.currentRound, nextBaseline);
-        session.currentPrompt = nextPrompt;
-        session.currentLevel = nextLevel;
-        session.currentWarnings = prepared?.warnings ?? [];
-        session.currentCanonicalState = isRecord(prepared?.canonicalState)
-            ? prepared.canonicalState
-            : undefined;
-        policyMetrics.recordStrategy(session.loopId, nextLevel);
-        this.save(session);
-        return {
-            sessionId,
-            round: session.currentRound,
-            roundId: session.roundSnapshot.roundId,
-            prompt: nextPrompt,
-            level: nextLevel,
-            roundSuccess,
-            warnings: prepared?.warnings ?? [],
-        };
-    }
-    async advanceUnlocked(sessionId, output, roundReport) {
-        // ── 1. Validate session ──────────────────────────────────────────────
-        const session = this.sessions.get(sessionId);
-        if (!session)
-            return { sessionId, round: 0, prompt: null, stopReason: "session_not_found", stopDetail: "No session exists with this ID. It may have expired, been deleted, or never existed." };
-        if (session.status !== "running") {
-            return { sessionId, round: session.currentRound, prompt: null, stopReason: session.status, stopDetail: `Session is ${session.status}. Use loopforge_resume to restart a paused session, or loopforge_start for a new task.` };
-        }
-        // ── 2. Require canonical report ───────────────────────────────────────
-        if (!roundReport) {
-            logEvent("invalid_round_report", {
-                sessionId,
-                loopId: session.loopId,
-                round: session.currentRound,
-            });
-            return {
-                sessionId,
-                round: session.currentRound,
-                roundId: session.roundSnapshot?.roundId,
-                prompt: session.currentPrompt ?? null,
-                stopReason: "invalid_round_report",
-                stopDetail: "A canonical RoundReport is required; the current round remains unchanged and can be retried.",
-                roundSuccess: false,
-            };
-        }
-        // ── 3. Execute round transaction ─────────────────────────────────────
-        const tx = await this.executeRoundTransaction(session, roundReport);
-        // ── 4. Route disposition ─────────────────────────────────────────────
-        if (tx.pr.action === "reject") {
-            return this.buildRejectionResult(sessionId, session, tx.pr, tx.verificationFlags);
-        }
-        // ── v2.10: Backtrack — roll back to last clean round ──────────────────
-        if (tx.pr.action === "backtrack") {
-            return this.buildBacktrackResult(sessionId, session, tx.pr);
-        }
-        // Accepted rounds advance the before-snapshot baseline. Rejected rounds
-        // retain the original baseline so their retry remains zero-commit.
-        session.evidenceBaseline = tx.actualEvidence;
-        if (tx.pr.action === "terminate") {
-            return this.buildTerminationResult(sessionId, session, tx.pr);
-        }
-        if (tx.pr.action === "stop") {
-            return this.buildStopResult(sessionId, session, tx.pr);
-        }
-        // ── 5. Continue — compile next round ─────────────────────────────────
-        return this.advanceToNextRound(sessionId, session, tx.pr, tx.verificationFlags, tx.actualEvidence);
-    }
-    /** Write back loop knowledge to long-term memory.
-     *  Uses shared base builder from policy.ts. Called when a loop terminates. */
-    async notifyTerminal(session, stopReason) {
-        if (this.terminalSinks.size === 0)
-            return;
-        const event = {
-            loopId: session.loopId,
-            task: session.task,
-            success: stopReason === "completed",
-            stopReason: stopReason,
-            roundsCompleted: session.currentRound,
-            successTrajectory: [...session.successTrajectory],
-            lastRoundView: session.lastRoundProjection,
-        };
-        await Promise.allSettled([...this.terminalSinks].map((sink) => Promise.resolve(sink(event))));
-    }
     /** Replay timeline for a session — creates ReplayBackend from the stored backend. */
     replayTimeline(sessionId) {
         const session = this.sessions.get(sessionId);
         if (!session)
             return null;
-        const replay = new ReplayBackend(this.backend);
-        return replay.eventTimeline(session.loopId);
-    }
-    replayTimelineByLoop(loopId, fromSequence, toSequence, limit = 50) {
-        const replay = new ReplayBackend(this.backend);
-        const timeline = replay.eventTimeline(loopId)
-            .filter((entry) => {
-            const sequence = typeof entry.event_sequence === "number" ? entry.event_sequence : null;
-            if (sequence === null)
-                return fromSequence === undefined && toSequence === undefined;
-            return (fromSequence === undefined || sequence >= fromSequence) &&
-                (toSequence === undefined || sequence <= toSequence);
-        })
-            .slice(0, Math.max(1, Math.min(200, limit)));
-        const last = timeline.at(-1);
-        const lastSequence = last && typeof last.event_sequence === "number" ? last.event_sequence : null;
-        return { timeline, nextSequence: lastSequence === null ? null : lastSequence + 1 };
+        const replay = new ReplayBackend(this.loopStore);
+        return replay.timeline(session.loopId);
     }
 }
 //# sourceMappingURL=session.js.map