loopforge 2.7.0 → 3.0.0

package/dist/mcp/session.js

@@ -2,78 +2,36 @@
  *
  * Each McpSession = one complete multi-round loop.
  * SessionManager holds Map<sessionId, McpSession> and drives
- * the advance() cycle: extract → feedback → check stop → compile next.
+ * the advance() cycle: validate report → commit round event → check stop → compile next.
  */
-import { randomUUID } from "node:crypto";
-import { LoopForgeEngine, extractSelfEvaluation } from "../engine.js";
+import { createHash, randomUUID } from "node:crypto";
+import { RuntimeServices } from "../runtime-services.js";
 import { checkLoopHealth } from "../loop-compiler.js";
 import { getPolicy } from "../policy.js";
-import { Mode, makeLoopCompileRequest, makeLoopRoundResult } from "../protocol.js";
+import { Mode, makeLoopCompileRequest } from "../protocol.js";
 import { ReplayBackend } from "../replay.js";
-import { FileLoopStore, LoopStoreBackend, VaultBackendLoopStore } from "../loop-store.js";
+import { FileLoopStore } from "../loop-store.js";
 import { EvidenceCollector } from "../evidence-provider.js";
 import { parseRoundTransactionSnapshot, prepareRoundTransaction, } from "../round-transaction.js";
 import { RoundDriver } from "../round-driver.js";
 import { logEvent } from "../observability.js";
-import { policyMetrics } from "../policy-metrics.js";
+import { derivePolicyMetrics, mergePolicyMetrics, policyMetrics, } 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 ────────────────────────────────────────────────────────────────
-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 ?? [],
-        });
-    }
-    return req;
-}
 // ── SessionManager ─────────────────────────────────────────────────────────
 export class SessionManager {
     sessions = new Map();
     /** Serializes state transitions for each session. */
     sessionQueues = new Map();
     backend;
+    eventWriter;
     sessionStore;
     ownerId = `${process.pid}:${randomUUID()}`;
     leaseMs;
@@ -82,16 +40,13 @@ export class SessionManager {
     /** 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 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);
+        const store = storeOrBackend ?? new FileLoopStore(getPolicy().backend.root_dir);
+        this.backend = store;
         this.sessionStore = sessionStore ?? new VaultSessionStateStore(store);
         const mcpPolicy = getPolicy().mcp;
         this.leaseMs = Math.max(1, mcpPolicy.session_lease_ms);
@@ -101,6 +56,11 @@ export class SessionManager {
             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;
@@ -153,41 +113,51 @@ 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);
-            }
-        }
-    }
     async create(input) {
+        const policyMaxRounds = getPolicy().engine.max_rounds;
+        if (input.maxRounds !== undefined &&
+            (!Number.isInteger(input.maxRounds) || input.maxRounds < 1 || input.maxRounds > policyMaxRounds)) {
+            return {
+                sessionId: "",
+                round: 0,
+                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}.` },
+            };
+        }
         const sessionId = randomUUID();
         const loopId = input.loopId ?? randomUUID();
-        const engine = new LoopForgeEngine(this.backend);
+        const engine = new RuntimeServices(this.backend);
         const maxRounds = input.maxRounds ?? getPolicy().engine.max_rounds;
         // Populate extra fields for the first round
         const request = buildLoopRequest({
-            sessionId, loopId, task: input.task, engine, currentRound: 1,
+            sessionId, loopId, task: input.task, runtime: engine, currentRound: 1,
             maxRounds, successTrajectory: [], status: "running", createdAt: Date.now(),
             consecutiveRejections: 0,
-            lastRejectionCheck: "",
+            escalatedRejectionChecks: [],
+            driftClarificationStreak: 0,
+            backtrackSkippedFiles: [],
             evidenceBaseline: [],
         });
         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 {
@@ -212,21 +182,36 @@ export class SessionManager {
             }
         }
         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 initialPrompt = prepared?.prompt ?? null;
         const initialLevel = prepared?.level ?? "l2";
         const evidenceBaseline = prepared?.evidenceBaseline ?? [];
         const session = {
-            sessionId, loopId, task: input.task, engine,
+            sessionId, loopId, task: input.task, runtime: engine,
             currentRound: 1, maxRounds, successTrajectory: [],
             status: "running", createdAt: Date.now(),
             // v1.13: Enforcement gate state
             consecutiveRejections: 0,
-            lastRejectionCheck: "",
+            escalatedRejectionChecks: [],
+            driftClarificationStreak: 0,
+            backtrackSkippedFiles: [],
             evidenceBaseline,
             roundSnapshot: prepared?.snapshot ?? prepareRoundTransaction(loopId, 1, evidenceBaseline),
             currentPrompt: initialPrompt,
             currentLevel: initialLevel,
             currentWarnings: prepared?.warnings ?? [],
+            currentCanonicalState: isRecord(prepared?.canonicalState)
+                ? prepared.canonicalState
+                : undefined,
         };
         this.sessions.set(sessionId, session);
         policyMetrics.recordStrategy(loopId, initialLevel);
@@ -271,14 +256,158 @@ 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.sessions.delete(sessionId);
+        this.sessionQueues.delete(sessionId);
         logEvent("session_end", {
             sessionId,
             loopId: session.loopId,
@@ -319,31 +448,22 @@ export class SessionManager {
             warnings: (session.currentWarnings ?? []),
         };
     }
-    /** Reconcile the crash window where feedback committed but session_state
+    /** 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. */
-    reconcileCommittedRound(session) {
+    async reconcileCommittedRound(session) {
         if (!session.roundSnapshot)
             return null;
-        const recovered = new RoundDriver(session.engine, this.backend).recover(session.roundSnapshot);
+        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 — 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;
+        // 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);
@@ -372,20 +492,36 @@ export class SessionManager {
                 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, pr.newLastSelfEval, pr.verificationFlags);
-        const prepared = new RoundDriver(session.engine, this.backend).prepareSync(request, session.loopId, 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) {
-            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.",
+                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;
@@ -394,6 +530,9 @@ export class SessionManager {
         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 {
@@ -443,7 +582,7 @@ export class SessionManager {
         catch {
             // Async evidence is best-effort; fall back to sync baseline.
         }
-        const reconciled = this.reconcileCommittedRound(session);
+        const reconciled = await this.reconcileCommittedRound(session);
         if (reconciled)
             return reconciled;
         const restored = this.restoredPromptResult(session);
@@ -465,7 +604,6 @@ export class SessionManager {
         const compileRequest = {
             task: session.task,
             mode: Mode.LOOP_COMPILE,
-            feedback: null,
             skill_name: null,
             task_id: null,
             loop_id: lcr.loop_id,
@@ -477,12 +615,16 @@ export class SessionManager {
             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);
+        const prepared = await new RoundDriver(session.runtime, 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." };
+            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;
@@ -491,6 +633,9 @@ export class SessionManager {
         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 {
@@ -525,12 +670,19 @@ export class SessionManager {
                 created_at: session.createdAt,
                 // v1.13: Enforcement gate state
                 consecutive_rejections: session.consecutiveRejections,
-                last_rejection_check: session.lastRejectionCheck,
+                // 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,
-                last_self_eval: session.lastSelfEval ?? 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,
@@ -551,47 +703,61 @@ export class SessionManager {
         }
         const loopId = entry.loop_id;
         const currentRound = lineage.current_round ?? 1;
-        const successTrajectory = lineage.success_trajectory ?? lineage.quality_trajectory ?? [];
+        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 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
+        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 LoopForgeEngine(this.backend);
+        const engine = new RuntimeServices(this.backend);
         return {
             sessionId: typeof lineage.session_id === "string" && lineage.session_id
                 ? lineage.session_id
                 : randomUUID(),
-            loopId, task, engine,
+            loopId, task, runtime: 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
-                : "",
-            evidenceBaseline: roundSnapshot?.beforeEvidence ?? fallbackEvidence,
-            roundSnapshot: roundSnapshot ?? prepareRoundTransaction(loopId, currentRound, fallbackEvidence),
-            lastSelfEval,
+            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,
         };
     }
     /** 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. */
-    resume(loopId) {
+    async resume(loopId) {
         const persistedEntry = this.findSessionEntry(loopId);
         if (!persistedEntry)
             return null;
@@ -617,21 +783,36 @@ export class SessionManager {
             };
         }
         this.sessions.set(session.sessionId, session);
-        const reconciled = this.reconcileCommittedRound(session);
+        const reconciled = await 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.
+        // 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 = 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, []);
+        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 {
@@ -714,6 +895,56 @@ 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;
+    }
+    /** 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",
+            loop_id: session.loopId,
+            task: session.task,
+            timestamp: new Date().toISOString(),
+            loop_lineage: {
+                round: session.currentRound,
+                session_id: session.sessionId,
+                stop_reason: stopReason,
+                success_trajectory: session.successTrajectory,
+                consecutive_rejections: session.consecutiveRejections,
+                ...extra,
+            },
+        });
+    }
     /** Get loop health for a loop (in-memory or vault).
      *  Computes goal alignment, constraint integrity, drift, strategy stability. */
     getHealth(loopId) {
@@ -723,8 +954,8 @@ export class SessionManager {
         for (const s of this.sessions.values()) {
             if (s.loopId === loopId) {
                 task = s.task;
-                if (s.engine.state?.task_id) {
-                    goalId = s.engine.state.task_id;
+                if (s.runtime.state?.task_id) {
+                    goalId = s.runtime.state.task_id;
                 }
                 break;
             }
@@ -739,7 +970,7 @@ export class SessionManager {
         if (!task)
             return null;
         // Hydrate vault context
-        const engine = new LoopForgeEngine(this.backend);
+        const engine = new RuntimeServices(this.backend);
         const vaultContext = engine.hydrateLoopContext(loopId);
         // Build a minimal request for health check
         const request = makeLoopCompileRequest({
@@ -756,22 +987,32 @@ 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.getLoopPolicyMetrics(loopId),
         };
     }
-    /** Core cycle: extract self-eval → record feedback → check stop → compile next.
-     *  @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) {
-        return this.withSessionQueue(sessionId, async () => {
+    /** 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 () => {
             const session = this.sessions.get(sessionId);
             if (session?.status === "running" &&
                 !this.renewSessionLease(session.loopId)) {
                 return this.leaseConflictResult(session.loopId, this.findSessionEntry(session.loopId));
             }
             try {
-                return await this.advanceUnlocked(sessionId, output, preExtractedEval);
+                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);
             }
             catch (error) {
                 if (error instanceof SessionLeaseConflictError) {
@@ -788,83 +1029,122 @@ export class SessionManager {
     //
     // 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.
+    /** Execute the round transaction and apply global rejection tracking.
      *  MUTATES: session.roundSnapshot, session.consecutiveRejections,
-     *           session.lastRejectionCheck, session.lastSelfEval,
-     *           session.successTrajectory */
-    async executeRoundTransaction(session, selfEval, extractionFailed) {
+     *           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.engine, this.backend).complete({
+        const completed = await new RoundDriver(session.runtime, this.backend).complete({
             snapshot,
             loopId: session.loopId,
             task: session.task,
             maxRounds: session.maxRounds,
-            selfEval,
-            extractionSucceeded: !extractionFailed,
-            lastSelfEval: session.lastSelfEval,
+            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);
-        // 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 = "";
+        // 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.newLastSelfEval)
-            session.lastSelfEval = pr.newLastSelfEval;
+        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.engine, this.backend).prepareRetry(retryRequest, session.roundSnapshot, pr.rejectionPrompt ?? "", session.consecutiveRejections);
+        const preparedRetry = await new RoundDriver(session.runtime, 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.",
+                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,
@@ -876,12 +1156,128 @@ export class SessionManager {
             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,
@@ -905,6 +1301,8 @@ export class SessionManager {
         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 {
@@ -912,7 +1310,7 @@ export class SessionManager {
             roundId: session.roundSnapshot?.roundId,
             prompt: null, stopReason: reason,
             stopDetail: pr.stopReason === "circuit_breaker"
-                ? `${pr.roundSuccess ? "No" : "All"} recent rounds failed, triggering the 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}.`,
@@ -923,26 +1321,25 @@ export class SessionManager {
      *  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) {
+    async advanceToNextRound(sessionId, session, pr, verificationFlags, actualEvidence) {
         const roundSuccess = pr.roundSuccess;
-        session.currentRound++;
-        session.currentPrompt = null;
+        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: session.currentRound,
+                    round: nextRound,
                     task: session.task,
                     domain: "",
-                    lastEvaluation: selfEval,
+                    lastRoundView: session.lastRoundProjection,
                 })).trim();
             }
             catch {
                 logEvent("context_provider_error", {
                     loopId: session.loopId,
-                    round: session.currentRound,
+                    round: nextRound,
                 });
             }
         }
@@ -958,19 +1355,39 @@ export class SessionManager {
                 roundSuccess,
             };
         }
-        const request = buildLoopRequest(session, selfEval, verificationFlags);
+        const request = buildLoopRequest({ ...session, currentRound: nextRound }, session.lastRoundProjection, 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;
+        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 {
@@ -983,7 +1400,7 @@ export class SessionManager {
             warnings: prepared?.warnings ?? [],
         };
     }
-    async advanceUnlocked(sessionId, output, preExtractedEval) {
+    async advanceUnlocked(sessionId, output, roundReport) {
         // ── 1. Validate session ──────────────────────────────────────────────
         const session = this.sessions.get(sessionId);
         if (!session)
@@ -991,22 +1408,33 @@ export class SessionManager {
         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 };
+        // ── 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,
+            };
         }
-        const { selfEval, extractionFailed } = extracted;
         // ── 3. Execute round transaction ─────────────────────────────────────
-        const tx = await this.executeRoundTransaction(session, selfEval, extractionFailed);
+        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;
@@ -1017,7 +1445,7 @@ export class SessionManager {
             return this.buildStopResult(sessionId, session, tx.pr);
         }
         // ── 5. Continue — compile next round ─────────────────────────────────
-        return this.advanceToNextRound(sessionId, session, selfEval, tx.pr, tx.verificationFlags, tx.actualEvidence);
+        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. */
@@ -1031,7 +1459,7 @@ export class SessionManager {
             stopReason: stopReason,
             roundsCompleted: session.currentRound,
             successTrajectory: [...session.successTrajectory],
-            lastEvaluation: session.lastSelfEval,
+            lastRoundView: session.lastRoundProjection,
         };
         await Promise.allSettled([...this.terminalSinks].map((sink) => Promise.resolve(sink(event))));
     }
@@ -1041,7 +1469,22 @@ export class SessionManager {
         if (!session)
             return null;
         const replay = new ReplayBackend(this.backend);
-        return replay.timeline(session.loopId);
+        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 };
     }
 }
 //# sourceMappingURL=session.js.map