loopforge 2.11.0 → 3.2.1

package/dist/mcp/session.js

@@ -3,103 +3,64 @@
  * Each McpSession = one complete multi-round loop.
  * SessionManager holds Map<sessionId, McpSession> and drives
  * 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 { randomUUID } from "node:crypto";
-import { LoopForgeEngine, extractSelfEvaluation } from "../engine.js";
+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, makeLoopRoundResult } from "../protocol.js";
+import { getPolicy, validateLoopId } from "../policy.js";
+import { makeLoopCompileRequest } from "../protocol.js";
 import { ReplayBackend } from "../replay.js";
-import { FileLoopStore, LoopStoreBackend, VaultBackendLoopStore } 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 { policyMetrics } from "../policy-metrics.js";
+import { policyMetrics, derivePolicyMetrics, mergePolicyMetrics, } from "../policy-metrics.js";
 import { SessionLeaseConflictError, VaultSessionStateStore, } from "../storage.js";
-// ── Helpers ────────────────────────────────────────────────────────────────
-function buildLoopRequest(session, lastEval, verificationFlags) {
-    const req = {
-        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: verificationFlags ?? [],
-    };
-    if (lastEval) {
-        req.last_round_result = makeLoopRoundResult({
-            round: session.currentRound - 1,
-            success: lastEval.success,
-            output_summary: lastEval.output_summary,
-            constraint_violations: lastEval.constraint_violations,
-            manual_fixes_needed: "",
-            // P0–P2: Forward evolution fields to next compile
-            // Merge sub-agent discovered constraints into the active set
-            discovered_constraints: [
-                ...new Set([
-                    ...(lastEval.discovered_constraints ?? []),
-                    ...(lastEval.worker_results ?? []).flatMap((w) => w.discoveredConstraints ?? []).filter((c) => c.length > 0),
-                ]),
-            ],
-            objective_refinement: lastEval.objective_refinement ?? "",
-            emerged_subtasks: lastEval.emerged_subtasks ?? [],
-            // P4: Execution evidence
-            execution_evidence: lastEval.execution_evidence ?? undefined,
-            // P5: Self-correction
-            retracted_constraints: lastEval.retracted_constraints ?? [],
-            revised_success_criteria: lastEval.revised_success_criteria ?? [],
-            wrong_assumptions: lastEval.wrong_assumptions ?? [],
-            // Multi-agent: Forward delegation results to next compile
-            worker_results: lastEval.worker_results ?? [],
-            // v1.10: Checkpoint boundary
-            compression_checkpoint: lastEval.compression_checkpoint ?? false,
-            checkpoint_label: lastEval.checkpoint_label ?? "",
-            // v1.16: Agent's declared next action
-            next_action: lastEval.next_action,
-            // v2.2: Sub-goal lifecycle
-            completed_subtasks: lastEval.completed_subtasks ?? [],
-            blocked_subtasks: lastEval.blocked_subtasks ?? [],
-            canceled_subtasks: lastEval.canceled_subtasks ?? [],
-            // v2.8: Drift clarification
-            drift_clarification: lastEval.drift_clarification,
-            // v2.9: Model's information needs for the next prompt
-            prompt_requests: lastEval.prompt_requests,
-        });
-    }
-    return req;
-}
+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;
+    loopStore;
     sessionStore;
     ownerId = `${process.pid}:${randomUUID()}`;
     leaseMs;
     leaseRenewIntervalMs;
     leaseTimer = null;
+    lifecycle;
     /** Explicit context provider; never auto-discovered. */
     contextProvider;
     terminalSinks = new Set();
-    constructor(storeOrBackend, sessionStore) {
-        const isLoopStore = (v) => "readSession" in v && typeof v.readSession === "function";
-        const store = storeOrBackend
-            ? isLoopStore(storeOrBackend)
-                ? storeOrBackend
-                : new VaultBackendLoopStore(storeOrBackend)
-            : new FileLoopStore(getPolicy().backend.root_dir);
-        this.backend = storeOrBackend && !isLoopStore(storeOrBackend)
-            ? storeOrBackend
-            : new LoopStoreBackend(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?.();
@@ -122,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);
     }
@@ -176,10 +146,41 @@ export class SessionManager {
             }
         }
     }
+    // ── Lifecycle entry points ───────────────────────────────────────────────
     async create(input) {
         const sessionId = randomUUID();
         const loopId = input.loopId ?? randomUUID();
-        const engine = new LoopForgeEngine(this.backend);
+        // 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: existing.currentRound,
+                prompt: null,
+                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.`,
+            };
+        }
+        // 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({
@@ -217,7 +218,7 @@ export class SessionManager {
                 logEvent("context_provider_error", { loopId, round: 1 });
             }
         }
-        const prepared = await new RoundDriver(engine, this.backend).prepare(request, loopId, 1);
+        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 ?? [];
@@ -235,11 +236,23 @@ export class SessionManager {
             currentPrompt: initialPrompt,
             currentLevel: initialLevel,
             currentWarnings: prepared?.warnings ?? [],
+            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,
@@ -284,8 +297,8 @@ export class SessionManager {
         if (!session)
             return false;
         session.status = "stopped";
-        this.save(session);
-        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", {
@@ -307,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,
@@ -315,308 +328,10 @@ 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 feedback committed but session_state
-     *  still points at the old prompt. Returns null when no commit is pending. */
-    reconcileCommittedRound(session) {
-        if (!session.roundSnapshot)
-            return null;
-        const recovered = new RoundDriver(session.engine, this.backend).recover(session.roundSnapshot);
-        if (!recovered)
-            return null;
-        const pr = recovered.result;
-        session.roundSnapshot = recovered.snapshot;
-        // Replay the committed counter — but with per-rule tracking.
-        if (pr.action === "reject" && pr.rejectionCheck) {
-            session.consecutiveRejections =
-                pr.rejectionCheck === session.lastRejectionCheck
-                    ? pr.newConsecutiveRejections
-                    : 1;
-            session.lastRejectionCheck = pr.rejectionCheck;
-        }
-        else {
-            session.consecutiveRejections = pr.newConsecutiveRejections;
-            if (pr.action !== "reject")
-                session.lastRejectionCheck = "";
-        }
-        if (pr.newLastSelfEval)
-            session.lastSelfEval = pr.newLastSelfEval;
-        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.lastRejectionCheck = "";
-            session.driftClarificationStreak = 0;
-            session.lastSelfEval = 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, pr.newLastSelfEval, pr.verificationFlags);
-        const prepared = new RoundDriver(session.engine, this.backend).prepareSync(request, session.loopId, session.currentRound);
-        if (!prepared) {
-            session.status = "stalled";
-            this.save(session);
-            return {
-                sessionId: session.sessionId,
-                round: session.currentRound,
-                prompt: null,
-                stopReason: "stalled",
-                stopDetail: "RoundDriver.prepareSync returned null — prompt compilation failed during crash recovery. The session state may be inconsistent.",
-            };
-        }
-        const prompt = prepared.prompt;
-        session.evidenceBaseline = prepared.evidenceBaseline;
-        session.roundSnapshot = prepared.snapshot;
-        session.currentPrompt = prompt;
-        session.currentLevel = prepared.level;
-        session.currentWarnings = prepared?.warnings ?? [];
-        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 = 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,
-            feedback: null,
-            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.engine, this.backend).prepare(compileRequest, session.loopId, session.currentRound);
-        if (!prepared) {
-            session.status = "stopped";
-            this.save(session);
-            void this.notifyTerminal(session, "stalled");
-            return { sessionId: session.sessionId, round: session.currentRound, prompt: null, stopReason: "stalled", stopDetail: "RoundDriver.prepare returned null during unpause — the compiler could not produce a prompt." };
-        }
-        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 ?? [];
-        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,
-                last_rejection_check: session.lastRejectionCheck,
-                // v2.12: Clarification streak
-                drift_clarification_streak: session.driftClarificationStreak,
-                // v2.13: Backtrack skipped files for workspace restore check
-                backtrack_skipped_files: session.backtrackSkippedFiles,
-                // v1.19: durable round transaction state
-                round_snapshot: session.roundSnapshot ?? null,
-                last_self_eval: session.lastSelfEval ?? null,
-                current_prompt: session.currentPrompt ?? null,
-                current_level: session.currentLevel ?? "",
-                // 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 = lineage.success_trajectory ?? lineage.quality_trajectory ?? [];
-        const task = entry.task ?? "";
-        const maxRounds = lineage.max_rounds ?? getPolicy().engine.max_rounds;
-        const roundSnapshot = parseRoundTransactionSnapshot(lineage.round_snapshot);
-        const fallbackEvidence = EvidenceCollector.fromProviderNames(getPolicy().evidence.providers).collect();
-        const persistedEval = lineage.last_self_eval;
-        const lastSelfEval = persistedEval !== null &&
-            typeof persistedEval === "object" &&
-            !Array.isArray(persistedEval) &&
-            typeof persistedEval.success === "boolean" &&
-            typeof persistedEval.output_summary === "string"
-            ? persistedEval
-            : undefined;
-        const engine = new LoopForgeEngine(this.backend);
-        return {
-            sessionId: typeof lineage.session_id === "string" && lineage.session_id
-                ? lineage.session_id
-                : randomUUID(),
-            loopId, task, engine,
-            currentRound, maxRounds, successTrajectory,
-            status: status,
-            createdAt: lineage.created_at ?? Date.now(),
-            consecutiveRejections: lineage.consecutive_rejections ?? 0,
-            lastRejectionCheck: typeof lineage.last_rejection_check === "string"
-                ? lineage.last_rejection_check
-                : "",
-            driftClarificationStreak: lineage.drift_clarification_streak ?? 0,
-            backtrackSkippedFiles: lineage.backtrack_skipped_files ?? [],
-            evidenceBaseline: roundSnapshot?.beforeEvidence ?? fallbackEvidence,
-            roundSnapshot: roundSnapshot ?? prepareRoundTransaction(loopId, currentRound, fallbackEvidence),
-            lastSelfEval,
-            currentPrompt: typeof lineage.current_prompt === "string"
-                ? lineage.current_prompt
-                : null,
-            currentLevel: typeof lineage.current_level === "string"
-                ? lineage.current_level
-                : undefined,
-        };
+        this.lifecycle.save(session);
     }
     /** Resume a loop from vault state.
      *  Reconstructs the session and compiles the prompt for the next round.
@@ -632,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 ?? {});
@@ -647,32 +362,29 @@ export class SessionManager {
             };
         }
         this.sessions.set(session.sessionId, session);
-        const reconciled = this.reconcileCommittedRound(session);
-        if (reconciled)
-            return reconciled;
-        const restored = this.restoredPromptResult(session);
-        if (restored)
-            return restored;
-        // Legacy session without a stored prompt: compile once, then persist it.
-        const request = buildLoopRequest(session);
-        const prepared = new RoundDriver(session.engine, this.backend).prepareSync(request, session.loopId, session.currentRound);
-        const prompt = prepared?.prompt ?? null;
-        session.evidenceBaseline = prepared?.evidenceBaseline ?? [];
-        session.roundSnapshot = prepared?.snapshot ?? prepareRoundTransaction(session.loopId, session.currentRound, []);
-        session.currentPrompt = prompt;
-        session.currentLevel = prepared?.level ?? "l2";
-        session.currentWarnings = prepared?.warnings ?? [];
-        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
@@ -701,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);
@@ -744,6 +469,144 @@ export class SessionManager {
         }
         return result;
     }
+    // ── 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,
+                }),
+        };
+    }
+    /** 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,
+            timestamp: new Date().toISOString(),
+            gate_id: gateId,
+            approved: decision.approved,
+            decision_note: decision.note,
+            gate_decision: decision,
+            loop_lineage: {
+                round: session.currentRound,
+                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. */
     getHealth(loopId) {
@@ -769,7 +632,7 @@ export class SessionManager {
         if (!task)
             return null;
         // Hydrate vault context
-        const engine = new LoopForgeEngine(this.backend);
+        const engine = new LoopForgeEngine(this.loopStore);
         const vaultContext = engine.hydrateLoopContext(loopId);
         // Build a minimal request for health check
         const request = makeLoopCompileRequest({
@@ -786,14 +649,19 @@ export class SessionManager {
             drift_detected: health.drift_detected,
             strategy_stability: health.strategy_stability,
             task_continuity: health.task_continuity,
-            policy_metrics: policyMetrics.snapshot(loopId),
+            policy_metrics: this.getPolicyMetrics(loopId),
         };
     }
     /** 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. */
-    async advance(sessionId, output, preExtractedEval) {
+     *    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" &&
@@ -801,7 +669,7 @@ export class SessionManager {
                 return this.leaseConflictResult(session.loopId, this.findSessionEntry(session.loopId));
             }
             try {
-                return await this.advanceUnlocked(sessionId, output, preExtractedEval);
+                return await this.lifecycle.advance(sessionId, output, preExtractedEval, roundId);
             }
             catch (error) {
                 if (error instanceof SessionLeaseConflictError) {
@@ -811,380 +679,12 @@ 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.
-    /** Extract a SelfEvaluation from agent output.
-     *  Structured param preferred → regex extraction → heuristic fallback.
-     *  Returns null only when both regex and heuristic returned null. */
-    extractEvaluation(output, preExtractedEval) {
-        if (preExtractedEval) {
-            return { selfEval: preExtractedEval, extractionFailed: false };
-        }
-        const structured = extractSelfEvaluation(output);
-        if (!structured)
-            return null;
-        return { selfEval: structured, extractionFailed: false };
-    }
-    /** Execute the round transaction and apply per-rule rejection tracking.
-     *  MUTATES: session.roundSnapshot, session.consecutiveRejections,
-     *           session.lastRejectionCheck, session.lastSelfEval,
-     *           session.successTrajectory, session.driftClarificationStreak */
-    async executeRoundTransaction(session, selfEval, extractionFailed) {
-        const snapshot = session.roundSnapshot ?? prepareRoundTransaction(session.loopId, session.currentRound, session.evidenceBaseline ?? []);
-        const completed = await new RoundDriver(session.engine, this.backend).complete({
-            snapshot,
-            loopId: session.loopId,
-            task: session.task,
-            maxRounds: session.maxRounds,
-            selfEval,
-            extractionSucceeded: !extractionFailed,
-            lastSelfEval: session.lastSelfEval,
-            consecutiveRejections: session.consecutiveRejections,
-            successTrajectory: session.successTrajectory,
-            driftClarificationStreak: session.driftClarificationStreak,
-            backtrackSkippedFiles: session.backtrackSkippedFiles,
-        });
-        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);
-        // Per-rule rejection tracking: same-check rejections accumulate;
-        // a different rejection reason resets the counter.
-        if (pr.action === "reject" && pr.rejectionCheck) {
-            session.consecutiveRejections =
-                pr.rejectionCheck === session.lastRejectionCheck
-                    ? pr.newConsecutiveRejections
-                    : 1;
-            session.lastRejectionCheck = pr.rejectionCheck;
-        }
-        else {
-            session.consecutiveRejections = pr.newConsecutiveRejections;
-            if (pr.action !== "reject")
-                session.lastRejectionCheck = "";
-        }
-        if (pr.newLastSelfEval)
-            session.lastSelfEval = pr.newLastSelfEval;
-        if (pr.shouldPushSuccessTrajectory) {
-            session.successTrajectory.push(pr.roundSuccess);
-        }
-        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;
-        }
-        // v2.12: Clarification accepted with anchors → substantive pivot.
-        // Keep streak as-is (don't increment for genuine explanations).
-        if (pr.clarificationAccepted) {
-            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;
-    }
-    /** 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.engine, this.backend).prepareRetry(retryRequest, session.roundSnapshot, pr.rejectionPrompt ?? "", session.consecutiveRejections);
-        if (!preparedRetry) {
-            session.status = "stalled";
-            session.currentPrompt = null;
-            this.save(session);
-            return {
-                sessionId,
-                round: session.currentRound,
-                roundId: session.roundSnapshot?.roundId,
-                prompt: null,
-                stopReason: "stalled",
-                stopDetail: "RoundDriver.prepareRetry returned null — the retry prompt could not be compiled.",
-            };
-        }
-        session.roundSnapshot = preparedRetry.snapshot;
-        session.currentPrompt = preparedRetry.prompt;
-        session.currentLevel = preparedRetry.level;
-        session.currentWarnings = preparedRetry.warnings ?? [];
-        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.lastSelfEval */
-    async buildBacktrackResult(sessionId, session, pr) {
-        const restoreTarget = pr.backtrackTarget ?? (session.currentRound - 1);
-        const newRound = restoreTarget + 1;
-        logEvent("session_backtrack", {
-            sessionId,
-            loopId: session.loopId,
-            fromRound: session.currentRound,
-            toRound: newRound,
-            triggerRule: pr.backtrackTriggerRule ?? "",
-            skippedDiscoveries: (pr.backtrackSkippedDiscoveries ?? []).length,
-        });
-        // Reset session to the restored round
-        session.currentRound = newRound;
-        session.consecutiveRejections = 0;
-        session.lastRejectionCheck = "";
-        session.driftClarificationStreak = 0;
-        session.backtrackSkippedFiles = pr.backtrackSkippedFiles ?? [];
-        session.lastSelfEval = undefined; // force L2 recompile from vault state
-        session.currentPrompt = null;
-        // 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,
-            feedback: null,
-            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.engine, this.backend).prepare(request, session.loopId, newRound);
-        if (!prepared || !prepared.prompt) {
-            session.status = "stalled";
-            session.currentPrompt = null;
-            this.save(session);
-            return {
-                sessionId,
-                round: newRound,
-                prompt: null,
-                stopReason: "stalled",
-                stopDetail: "Backtrack failed: RoundDriver.prepare returned null — could not compile from restore point.",
-                enforcementAction: "backtrack",
-                enforcementReason: pr.enforcementReason,
-            };
-        }
-        // 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 ?? [];
-        this.save(session);
-        return {
-            sessionId,
-            round: newRound,
-            roundId: session.roundSnapshot?.roundId,
-            prompt: fullPrompt,
-            level: prepared.level,
-            enforcementAction: "backtrack",
-            enforcementReason: pr.enforcementReason,
-            warnings: prepared?.warnings ?? [],
-        };
-    }
-    /** 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);
-        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);
-        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"
-                ? `${pr.roundSuccess ? "No" : "All"} recent rounds failed, 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, selfEval, pr, verificationFlags, actualEvidence) {
-        const roundSuccess = pr.roundSuccess;
-        session.currentRound++;
-        session.currentPrompt = null;
-        // v2.13: Clear backtrack skipped files after advancing past the restore round
-        session.backtrackSkippedFiles = [];
-        // v1.8: Memory injection — tier-aware external context.
-        let externalCtx = "";
-        if (this.contextProvider) {
-            try {
-                externalCtx = (await this.contextProvider({
-                    loopId: session.loopId,
-                    round: session.currentRound,
-                    task: session.task,
-                    domain: "",
-                    lastEvaluation: selfEval,
-                })).trim();
-            }
-            catch {
-                logEvent("context_provider_error", {
-                    loopId: session.loopId,
-                    round: session.currentRound,
-                });
-            }
-        }
-        // 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, selfEval, verificationFlags);
-        if (externalCtx) {
-            request.external_context = externalCtx;
-        }
-        const prepared = await new RoundDriver(session.engine, this.backend).prepare(request, session.loopId, session.currentRound);
-        const nextPrompt = prepared?.prompt ?? null;
-        const nextLevel = prepared?.level ?? "l2";
-        const nextBaseline = prepared?.evidenceBaseline ?? actualEvidence;
-        session.evidenceBaseline = nextBaseline;
-        session.roundSnapshot = prepared?.snapshot ?? prepareRoundTransaction(session.loopId, session.currentRound, nextBaseline);
-        session.currentPrompt = nextPrompt;
-        session.currentLevel = nextLevel;
-        session.currentWarnings = prepared?.warnings ?? [];
-        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, preExtractedEval) {
-        // ── 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. Extract self-evaluation ───────────────────────────────────────
-        const extracted = this.extractEvaluation(output, preExtractedEval);
-        if (!extracted) {
-            session.status = "stalled";
-            this.save(session);
-            void this.notifyTerminal(session, "stalled");
-            logEvent("session_end", { sessionId, loopId: session.loopId, stopReason: "stalled", round: session.currentRound });
-            return { sessionId, round: session.currentRound, prompt: null, stopReason: "stalled", stopDetail: "Self-evaluation could not be extracted from agent output. Both structured regex and heuristic fallback returned null.", roundSuccess: false };
-        }
-        const { selfEval, extractionFailed } = extracted;
-        // ── 3. Execute round transaction ─────────────────────────────────────
-        const tx = await this.executeRoundTransaction(session, selfEval, extractionFailed);
-        // ── 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, selfEval, 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],
-            lastEvaluation: session.lastSelfEval,
-        };
-        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);
+        const replay = new ReplayBackend(this.loopStore);
         return replay.timeline(session.loopId);
     }
 }