loopforge 3.9.4 → 4.0.7

package/dist/mcp/session.js

@@ -16,27 +16,30 @@ import { randomUUID } from "node:crypto";
 import { LoopForgeEngine } from "../engine.js";
 import { canonicalizeGateAction, deriveGate, preflightStructuredGate, } from "../cognitive-governance.js";
 import { makeGateDecision, makeLoopObjective } from "../protocol.js";
-import { buildLoopProjection } from "../loop-projection.js";
-import { deriveCognitiveFacts } from "../cognitive-facts.js";
-import { NO_IN_FLIGHT_ROUND, deriveRoundFacts } from "../round-facts.js";
-import { listVerifiedClaims } from "../evidence-claims.js";
+import { loadCommittedHistory } from "../history.js";
 import { buildAudit } from "../audit.js";
 import { buildExplain } from "../explain.js";
 import { CHECK_CONTRACT_ITEMS_UNVERIFIED } from "../verification-gate.js";
-import { readOnlyRounds } from "../committed-round.js";
 import { deriveCommittedSubmissionView } from "../submission-receipt.js";
 import { getPolicy, validateLoopId } from "../policy.js";
 import { isRecord, unique } from "../token-utils.js";
 import { ReplayBackend } from "../replay.js";
-import { FileLoopStore, queryLoopEntries } from "../loop-store.js";
-import { makeRoundId, prepareRoundTransaction } from "../round-transaction.js";
+import { FileLoopStore } from "../loop-store.js";
+import { MAX_MID_CHECKPOINTS_PER_TRANSACTION, } from "../round-transaction.js";
+import { findCheckpointRef } from "../recovery.js";
+import { buildCheckpointRef, CheckpointError, FileWorkspaceCheckpointStore, } from "../workspace-checkpoint.js";
+import { resolveStateDirectory } from "../policy.js";
+import { resolve, sep } from "node:path";
 import { RoundDriver } from "../round-driver.js";
 import { logEvent } from "../observability.js";
+import { CompileFailureError, LegacyHistoryError, LoopExistsError, StartFailureError, } from "../errors.js";
 import { policyMetrics, derivePolicyMetrics, mergePolicyMetrics, } from "../policy-metrics.js";
 import { SessionLeaseConflictError, VaultSessionStateStore, } from "../storage.js";
 import { StorageCorruptionError } from "../loop-store.js";
-import { RoundLifecycle, buildLoopRequest, normalizeStartCriteria, } from "./round-lifecycle.js";
-import { activeContractOf, compileSessionContext, validateSubmission, } from "./submission-boundary.js";
+import { LOST_HANDLE_ROUTING } from "../recovery-guidance.js";
+import { MANUAL_STOP_REASON, RoundLifecycle, buildLoopRequest, normalizeInvocationInputs, normalizeStartCriteria, } from "./round-lifecycle.js";
+import { activeContractOf, validateSubmission, } from "./submission-boundary.js";
+import { makeSubmissionHandle, parseSubmissionHandle, staleHandleWarning, validateSubmissionHandle, } from "./submission-handle.js";
 // ── SessionManager ─────────────────────────────────────────────────────────
 export class SessionManager {
     sessions = new Map();
@@ -49,12 +52,23 @@ export class SessionManager {
     leaseRenewIntervalMs;
     leaseTimer = null;
     lifecycle;
-    /** Explicit context provider; never auto-discovered. */
-    contextProvider;
     terminalSinks = new Set();
-    constructor(store, sessionStore) {
+    checkpointStoreFor;
+    constructor(store, sessionStore, checkpointStoreFor) {
         this.loopStore = store ?? new FileLoopStore(getPolicy().backend.root_dir);
         this.sessionStore = sessionStore ?? new VaultSessionStateStore(this.loopStore);
+        const stores = new Map();
+        const fileStore = this.loopStore instanceof FileLoopStore ? this.loopStore : undefined;
+        this.checkpointStoreFor = checkpointStoreFor ?? (fileStore
+            ? (loopId) => {
+                let storeForLoop = stores.get(loopId);
+                if (!storeForLoop) {
+                    storeForLoop = new FileWorkspaceCheckpointStore(fileStore.loopDir(loopId), loopId);
+                    stores.set(loopId, storeForLoop);
+                }
+                return storeForLoop;
+            }
+            : undefined);
         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));
@@ -65,7 +79,9 @@ export class SessionManager {
             terminalSinks: this.terminalSinks,
             ownerId: this.ownerId,
             leaseMs: this.leaseMs,
-            getContext: () => this.contextProvider,
+            ...(this.checkpointStoreFor
+                ? { checkpointStoreFor: this.checkpointStoreFor }
+                : {}),
         });
         if (this.sessionStore?.renewLease) {
             this.leaseTimer = setInterval(() => this.renewOwnedLeases(), this.leaseRenewIntervalMs);
@@ -101,6 +117,15 @@ export class SessionManager {
     findSessionEntry(loopId) {
         return this.sessionStore?.load(loopId);
     }
+    /** Whether the loop already has durable round history. A lineage-only round
+     *  document from a failed start is NOT history and must remain retryable;
+     *  only a committed feedback envelope counts. */
+    hasCommittedRounds(loopId) {
+        const history = loadCommittedHistory(this.loopStore, loopId);
+        return history.rounds.length > 0 ||
+            history.directives.length > 0 ||
+            history.legacyRounds.length > 0;
+    }
     claimSessionEntry(loopId) {
         if (this.sessionStore?.acquireLease) {
             return this.sessionStore.acquireLease(loopId, this.ownerId, this.leaseMs);
@@ -125,12 +150,19 @@ export class SessionManager {
     }
     leaseConflictResult(loopId, entry) {
         const lineage = (entry?.loop_lineage ?? {});
+        const owner = entry?.loop_lineage
+            ? entry.loop_lineage.lease_owner ?? "unknown"
+            : "unknown";
         return {
             sessionId: "",
             round: typeof lineage.current_round === "number" ? lineage.current_round : 0,
             prompt: null,
-            stopReason: `session_owned_elsewhere:${loopId}`,
-            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.`,
+            stopDetail: `Another process (PID ${String(owner)}) holds the lease for loop ` +
+                `"${loopId}". Wait for the lease to expire or stop the other process.`,
+            submissionError: {
+                code: "lease_conflict",
+                details: { loopId, owner: String(owner) },
+            },
         };
     }
     async withSessionQueue(sessionId, work) {
@@ -163,21 +195,12 @@ export class SessionManager {
         // 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.`,
-            };
+            throw new LoopExistsError(loopId, "active");
         }
-        // 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.
+        // v3.2.1: pre-flight the cross-process lease BEFORE compiling. A compile
+        // no longer writes round history, but it still writes the derived state
+        // file and would waste evidence work against another process's loop.
+        // 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)
@@ -186,94 +209,93 @@ export class SessionManager {
         if (typeof persistedOwner === "string" && persistedOwner && persistedOwner !== this.ownerId) {
             throw new SessionLeaseConflictError(loopId);
         }
+        // A persisted session in ANY status, or any committed round document,
+        // means this loopId already names durable history. Starting a new round 1
+        // would overwrite it. The atomic `expectAbsent` save below is the final
+        // gate; this preflight avoids compiling and collecting evidence first.
+        if (persistedSession) {
+            const persistedStatus = isRecord(persistedLineage)
+                ? persistedLineage.status
+                : undefined;
+            throw new LoopExistsError(loopId, persistedStatus === "stopped" ? "stopped" : "session");
+        }
+        if (this.hasCommittedRounds(loopId)) {
+            throw new LoopExistsError(loopId, "rounds");
+        }
         // v3.9.4: normalize initial criteria before any runtime object is created.
         // A structural defect throws StartCriteriaError (mapped to
         // invalid_argument); empty/duplicate/over-cap entries produce warnings.
         const startCriteria = normalizeStartCriteria(input.criteria);
         const engine = new LoopForgeEngine(this.loopStore);
         const maxRounds = input.maxRounds ?? getPolicy().engine.max_rounds;
-        // Populate extra fields for the first round
+        const operatorAcceptance = {
+            task: input.task,
+            success_criteria: startCriteria.criteria.length > 0
+                ? [...startCriteria.criteria]
+                : ["Task goal achieved with verifiable evidence"],
+            hard_constraints: unique(input.constraints ?? []),
+        };
+        // Populate the typed request for the first round. The operator surface is
+        // the one acceptance object; the objective is derived from it.
         const request = buildLoopRequest({
             sessionId, loopId, task: input.task, engine, currentRound: 1,
-            maxRounds, successTrajectory: [], status: "running", createdAt: Date.now(),
+            maxRounds, status: "running", createdAt: Date.now(),
             consecutiveRejections: 0,
             lastRejectionCheck: "",
-            backtrackSkippedFiles: [],
-            backtrackSkippedFingerprints: {},
-            evidenceBaseline: [],
         });
-        request.domain = input.domain ?? "";
         request.plan_source = input.planSource ?? null;
         request.constraints_from_plan = input.constraints ?? [];
-        // The initial criteria are real objective criteria, not a second ledger.
-        // Supplying the objective here means the first compile persists these
-        // texts (and therefore their cr- ids) through the existing lineage.
-        if (startCriteria.criteria.length > 0) {
-            request.loop_objective = makeLoopObjective({
-                objective: input.task,
-                success_criteria: startCriteria.criteria,
-                hard_constraints: unique(input.constraints ?? []),
-                created_at_round: 1,
-                loop_id: loopId,
-                version: 1,
-                refinement_history: [],
-            });
+        // v4.0.5: the start task IS the initial invocation instruction. The
+        // prompt de-duplicates it against Current Task/Objective, but the round-1
+        // artifact records it. Later invocations only receive an instruction the
+        // host supplies explicitly.
+        if (input.task.trim()) {
+            request.current_user_instruction = input.task.trim();
         }
-        // Explicit context is requested by the MCP embedding; no auto-discovery.
-        if (this.contextProvider) {
-            try {
-                const ctx = {
-                    loopId,
-                    round: 1,
-                    task: input.task,
-                    domain: input.domain ?? "",
-                };
-                const rawContext = await this.contextProvider(ctx);
-                if (rawContext?.trim()) {
-                    request.external_context = rawContext.trim();
-                    logEvent("external_context_loaded", {
-                        loopId, round: 1,
-                        contextLength: request.external_context.length,
-                    });
-                }
-            }
-            catch {
-                // Provider failures are isolated from session creation.
-                logEvent("context_provider_error", { loopId, round: 1 });
+        request.loop_objective = makeLoopObjective({
+            objective: operatorAcceptance.task,
+            success_criteria: [...operatorAcceptance.success_criteria],
+            hard_constraints: [...operatorAcceptance.hard_constraints],
+            created_at_round: 1,
+            loop_id: loopId,
+        });
+        let prepared;
+        try {
+            prepared = await new RoundDriver(engine, this.loopStore, this.checkpointStoreFor?.(loopId)).prepare(request, loopId, 1, { operatorAcceptance });
+        }
+        catch (error) {
+            if (error instanceof CompileFailureError) {
+                throw new StartFailureError(error.message);
             }
+            throw error;
         }
-        const prepared = await new RoundDriver(engine, this.loopStore).prepare(request, loopId, 1);
-        const initialPrompt = prepared?.prompt ?? null;
-        const initialLevel = prepared?.level ?? "l2";
-        const evidenceBaseline = prepared?.evidenceBaseline ?? [];
+        const initialPrompt = prepared.prompt;
+        const initialLevel = prepared.level;
         const session = {
             sessionId, loopId, task: input.task, engine,
-            currentRound: 1, maxRounds, successTrajectory: [],
+            currentRound: 1, maxRounds,
             status: "running", createdAt: Date.now(),
             // v1.13: Enforcement gate state
             consecutiveRejections: 0,
             lastRejectionCheck: "",
-            backtrackSkippedFiles: [],
-            backtrackSkippedFingerprints: {},
-            evidenceBaseline,
-            roundSnapshot: prepared?.snapshot ?? prepareRoundTransaction(loopId, 1, evidenceBaseline),
-            currentPrompt: initialPrompt,
-            currentLevel: initialLevel,
-            currentWarnings: [...startCriteria.warnings, ...(prepared?.warnings ?? [])],
-            lastCompileResponse: prepared?.compileResponse ?? null,
+            operatorAcceptance,
+            roundSnapshot: prepared.snapshot,
         };
+        // v4.0.3: seed the round-1 trust baseline BEFORE the first prompt is
+        // delivered, so the first round already has the absolute entrypoint arm.
+        this.lifecycle.seedEntrypointTrust(session);
         this.sessions.set(sessionId, session);
         policyMetrics.recordStrategy(loopId, initialLevel);
         // 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.
+        // lease/existence gate — a TOCTOU window between the pre-flight checks
+        // above and this write can still lose the race to another process.
         try {
-            this.lifecycle.save(session);
+            this.lifecycle.save(session, { expectAbsent: true });
         }
         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.
+            // Roll back the in-memory registration: a registered-but-unsaved
+            // session would make every later create for this loopId fail until
+            // this process restarts.
             this.sessions.delete(sessionId);
             throw error;
         }
@@ -283,14 +305,37 @@ export class SessionManager {
             task: input.task.slice(0, 80),
             maxRounds,
         });
+        const snapshot = session.roundSnapshot;
+        const handle = makeSubmissionHandle(session);
         return {
             sessionId,
+            loopId,
             round: 1,
-            roundId: session.roundSnapshot?.roundId,
+            ...(handle ? { submissionHandle: handle } : {}),
+            // v4.0.2: start is a prompt-bearing result like next/resume; the
+            // boundary is projected from the same compiled artifact.
+            ...(snapshot?.promptArtifact
+                ? {
+                    contextMode: snapshot.promptArtifact.contextMode,
+                    contextReason: snapshot.promptArtifact.contextReason,
+                }
+                : {}),
+            ...(snapshot?.beforeCheckpoint
+                ? { checkpoints: [snapshot.beforeCheckpoint] }
+                : {}),
+            ...(snapshot?.beforeCheckpointError
+                ? {
+                    beforeCheckpointError: {
+                        code: snapshot.beforeCheckpointError.code,
+                        detail: snapshot.beforeCheckpointError.detail,
+                    },
+                }
+                : {}),
             prompt: initialPrompt,
             level: initialLevel,
-            roundSuccess: false,
-            warnings: [...startCriteria.warnings, ...(prepared?.warnings ?? [])],
+            agentSuccessClaim: false,
+            agentOutcome: null,
+            warnings: [...startCriteria.warnings, ...(prepared.warnings ?? [])],
             submission_guidance: this.lifecycle.guidanceFor(session),
         };
     }
@@ -300,28 +345,55 @@ export class SessionManager {
         const session = this.sessions.get(sessionId);
         return session ? this.lifecycle.guidanceFor(session) : null;
     }
-    /** v3.9.1: the most recent committed round's receipt, rebuilt from the
-     *  transaction + shared read model. Rejected/terminated attempts are not in
-     *  history; their receipt exists only on their own response. */
-    getLastSubmissionReceipt(sessionId) {
-        const session = this.sessions.get(sessionId);
-        if (!session)
+    /** v4.0.0: the current held handle, derived on demand. A read-only
+     *  projection; never persisted. */
+    getSubmissionHandle(sessionId) {
+        return makeSubmissionHandle(this.sessions.get(sessionId));
+    }
+    /** v3.9.1: the most recent committed round's receipt for a loop, rebuilt
+     *  from committed history. Rejected/terminated attempts are not history;
+     *  their receipt exists only on their own response. This intentionally takes
+     *  the durable loopId: it never reads live-session state. */
+    getLastSubmissionReceiptByLoopId(loopId) {
+        if (!loopId)
             return null;
-        const prefix = `loop:${session.loopId}:r`;
-        const entries = [
-            ...queryLoopEntries(this.loopStore, session.loopId, { prefix }),
-            ...queryLoopEntries(this.loopStore, session.loopId, {
-                prefix,
-                feedbackOnly: true,
-            }),
-        ];
-        const views = readOnlyRounds(entries);
-        const latest = views[views.length - 1];
-        return latest ? deriveCommittedSubmissionView(latest, views) : null;
+        const history = loadCommittedHistory(this.loopStore, loopId);
+        const views = history.rounds;
+        const rollbacks = history.directives;
+        const latestRound = views[views.length - 1];
+        const latestRollback = rollbacks[rollbacks.length - 1];
+        if (latestRollback &&
+            (!latestRound || latestRollback.round > latestRound.round)) {
+            return deriveCommittedSubmissionView(latestRollback, views, rollbacks);
+        }
+        return latestRound
+            ? deriveCommittedSubmissionView(latestRound, views, rollbacks)
+            : null;
+    }
+    /** v4.0.3: the machine-backed success trajectory is a projection of
+     *  committed branch rounds, not a session counter. Unbacked claims never
+     *  enter it. */
+    getMachineBackedSuccessTrajectory(loopId) {
+        return loadCommittedHistory(this.loopStore, loopId).rounds
+            .filter((view) => view.result?.shouldPushSuccessTrajectory === true &&
+            view.result?.evidencePosture?.machineBackedSuccess === true)
+            .map((view) => view.agentSuccessClaim);
     }
     get(sessionId) {
         return this.sessions.get(sessionId);
     }
+    /** Resolve a live session by its durable loop identity. `create` rejects a
+     *  second live session for the same loop, so the scan is unambiguous. A
+     *  persisted-only loop has no live session: call `resume` to rebuild it. */
+    getByLoopId(loopId) {
+        if (!loopId)
+            return undefined;
+        for (const session of this.sessions.values()) {
+            if (session.loopId === loopId)
+                return session;
+        }
+        return undefined;
+    }
     getLeaseStatus(loopId) {
         const entry = this.findSessionEntry(loopId);
         if (!entry)
@@ -348,13 +420,13 @@ export class SessionManager {
             return false;
         session.status = "stopped";
         this.lifecycle.save(session);
-        void this.lifecycle.notifyTerminal(session, "cancelled");
+        void this.lifecycle.notifyTerminal(session, MANUAL_STOP_REASON);
         this.sessions.delete(sessionId);
         this.sessionQueues.delete(sessionId);
         logEvent("session_end", {
             sessionId,
             loopId: session.loopId,
-            stopReason: "cancelled",
+            stopReason: MANUAL_STOP_REASON,
             roundsCompleted: session.currentRound,
         });
         return true;
@@ -387,38 +459,67 @@ export class SessionManager {
      *  Reconstructs the session and compiles the prompt for the next round
      *  (async — compilation collects evidence through RoundDriver.prepare).
      *  Returns null if no session_state entry exists for this loopId. */
-    async resume(loopId) {
+    async resume(loopId, inputs) {
+        // v4.0.5: validate invocation input before any state is read or saved.
+        const normalizedInputs = normalizeInvocationInputs(inputs);
         const persistedEntry = this.findSessionEntry(loopId);
         if (!persistedEntry)
             return null;
         const persistedLineage = (persistedEntry.loop_lineage ?? {});
         const persistedStatus = persistedLineage.status ?? "running";
-        const sessionEntry = persistedStatus === "running"
+        // v3.9.7: stalled is a RESUMABLE recovery state. It is how a committed
+        // directive with an unfinished restore survives a restart.
+        const sessionEntry = persistedStatus === "running" || persistedStatus === "stalled"
             ? this.claimSessionEntry(loopId)
             : persistedEntry;
         if (!sessionEntry)
             return this.leaseConflictResult(loopId, persistedEntry);
         const session = this.lifecycle.reconstructSession(sessionEntry);
         if (!session) {
-            // was not "running" — return stopped/stalled status
+            // was not "running"/"stalled" — report the SESSION status and, for a
+            // stopped loop, the committed loop terminal reason.
             const lineage = (sessionEntry.loop_lineage ?? {});
             const currentRound = lineage.current_round ?? 1;
             const status = lineage.status ?? "stopped";
-            return {
-                sessionId: "",
-                round: currentRound,
-                prompt: null,
-                stopReason: status,
-                stopDetail: `Loop is not running (status: ${status}). It may have already completed or been stopped.`,
-            };
+            if (status !== "stopped") {
+                return {
+                    sessionId: "",
+                    round: currentRound,
+                    prompt: null,
+                    sessionStatus: status,
+                    stopDetail: `Loop is not running (session status: ${status}).`,
+                };
+            }
+            // v4.0.4: resume of a stopped loop reports the committed `StopReason`
+            // (completed/failed/blocked/max_rounds/...) and the SAME three fact
+            // blocks as a live stop. Never a fake "stopped", never a legacy guess.
+            return this.lifecycle.stoppedLoopResult(loopId, currentRound);
         }
-        this.sessions.set(session.sessionId, session);
-        return this.lifecycle.resume(session);
+        // v4.0.5: the queue only serializes work if it runs against the ONE live
+        // object. If this process still holds a running/stalled session for the
+        // same identity, prefer it over a document reconstructed from a possibly
+        // pre-commit save; replacing it here would let an in-flight advance and
+        // this resume operate on two different snapshots.
+        const live = this.sessions.get(session.sessionId);
+        const target = live && live.loopId === loopId &&
+            (live.status === "running" || live.status === "stalled")
+            ? live
+            : session;
+        // Resume is a recovery attempt: set running so the lease is renewed while
+        // the (possibly long) restore executes. A failure saves stalled again.
+        if (target.status === "stalled")
+            target.status = "running";
+        if (target !== live)
+            this.sessions.set(target.sessionId, target);
+        // Serialize with any in-process advance holding this session's queue, so
+        // a recompile cannot race an in-flight held-handle submission.
+        return this.withSessionQueue(target.sessionId, () => this.lifecycle.resume(target, normalizedInputs));
     }
     /** 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) {
+    async unpause(loopId, inputs) {
+        const normalizedInputs = normalizeInvocationInputs(inputs);
         const persistedEntry = this.findSessionEntry(loopId);
         if (!persistedEntry)
             return null;
@@ -432,10 +533,17 @@ export class SessionManager {
         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);
+        // v4.0.5: keep the ONE live object when this process already holds it,
+        // for the same queue-visibility reason as resume().
+        const live = this.sessions.get(session.sessionId);
+        const target = live && live.loopId === loopId && live.status !== "stopped"
+            ? live
+            : session;
+        // Set to running so advance() works.
+        target.status = "running";
+        if (target !== live)
+            this.sessions.set(target.sessionId, target);
+        return this.withSessionQueue(target.sessionId, () => this.lifecycle.unpause(target, normalizedInputs));
     }
     /** Auto-resume all "running" sessions from vault on server startup.
      *  Scans vault for session_state entries, reconstructs each as an in-memory
@@ -459,7 +567,7 @@ export class SessionManager {
                 continue;
             const lineage = (entry.loop_lineage ?? {});
             const status = lineage.status ?? "running";
-            if (status !== "running" && status !== "paused")
+            if (status !== "running" && status !== "paused" && status !== "stalled")
                 continue;
             const claimedEntry = this.claimSessionEntry(lid);
             if (!claimedEntry)
@@ -472,6 +580,11 @@ export class SessionManager {
                 session = this.lifecycle.reconstructSession(claimedEntry, true);
             }
             catch (error) {
+                if (error instanceof LegacyHistoryError) {
+                    // A bulk startup scan must not rewrite history it cannot decode.
+                    logEvent("session_skip_legacy", { loopId: lid, error: error.message });
+                    continue;
+                }
                 if (error instanceof StorageCorruptionError && error.recoverable) {
                     logEvent("session_skip_gap", { loopId: lid, error: error.message });
                     continue;
@@ -542,6 +655,25 @@ export class SessionManager {
             },
         });
     }
+    gateInvalidResult(session) {
+        const handle = makeSubmissionHandle(session);
+        return {
+            error: "gate_invalid",
+            errorMessage: `Session is ${session.status}; a gate check requires a running held evaluation.`,
+            sessionId: session.sessionId,
+            ...(handle ? { submissionHandle: handle } : {}),
+            details: { reason_code: "session_not_running" },
+        };
+    }
+    gateLeaseConflictResult(session) {
+        const conflict = this.leaseConflictResult(session.loopId, this.findSessionEntry(session.loopId));
+        return {
+            error: "lease_conflict",
+            errorMessage: conflict.stopDetail ?? "Another process owns this loop.",
+            sessionId: session.sessionId,
+            details: { reason_code: "lease_conflict" },
+        };
+    }
     /** v3.7.1: structured gate preflight. The agent submits a
      *  GateActionDescriptor; the runtime classifies it (conservative:
      *  anything not provably safe is user_required with reason codes). A
@@ -549,49 +681,71 @@ export class SessionManager {
      *  loop + round + actionHash; agent_allowed records nothing and returns
      *  the evidence suggestion instead. No action is executed and no round
      *  advances from this call. */
-    checkGate(sessionId, roundId, action) {
-        const session = this.sessions.get(sessionId);
-        if (!session) {
+    async checkGate(handle, action) {
+        const parsed = parseSubmissionHandle(handle);
+        if (!parsed) {
+            const detail = "submissionHandle must be an object with exactly sessionId, roundId, " +
+                "and transactionId as non-empty strings.";
             return {
-                error: "session_not_found",
-                errorMessage: `session not found: ${sessionId}`,
-                sessionId,
+                error: "submission_handle_required",
+                errorMessage: `${detail} Copy it from the latest LoopForge response. ${LOST_HANDLE_ROUTING}`,
+                details: { reason_code: "shape", detail },
             };
         }
-        const expectedRoundId = session.roundSnapshot?.roundId
-            ?? makeRoundId(session.loopId, session.currentRound);
-        if (expectedRoundId !== roundId) {
+        const session = this.sessions.get(parsed.sessionId);
+        if (!session) {
             return {
-                error: "round_id_mismatch",
-                errorMessage: "roundId does not match the current round — re-run loopforge_gate_check " +
-                    "with the roundId from the latest response",
-                sessionId,
-                roundId,
+                error: "session_not_found",
+                errorMessage: `session not found: ${parsed.sessionId}`,
+                sessionId: parsed.sessionId,
             };
         }
-        const verdict = preflightStructuredGate(action);
-        if (verdict.kind === "user") {
-            this.recordOpenedGate(session.loopId, session.currentRound, verdict, canonicalizeGateAction(action));
+        if (session.status !== "running") {
+            return this.gateInvalidResult(session);
         }
-        return {
-            sessionId,
-            gateId: verdict.gateId,
-            risk: verdict.risk,
-            decision: verdict.decision,
-            reasonCodes: verdict.reasonCodes,
-            ...(verdict.kind === "user"
-                ? {
-                    blockedScope: verdict.blockedScope,
-                    allowedBeforeApproval: verdict.allowedBeforeApproval,
-                    requiredEvidence: [],
-                    approvalQuestion: verdict.approvalQuestion,
-                }
-                : {
-                    blockedScope: [],
-                    allowedBeforeApproval: [],
-                    requiredEvidence: verdict.requiredEvidence,
-                }),
-        };
+        const check = validateSubmissionHandle(parsed, session);
+        if (!check.ok)
+            return this.checkpointMismatchResult(check, session);
+        return this.withSessionQueue(session.sessionId, async () => {
+            const current = this.sessions.get(session.sessionId);
+            if (!current)
+                return { ...this.sessionNotFoundResult(session.sessionId) };
+            if (current.status !== "running") {
+                return this.gateInvalidResult(current);
+            }
+            // The authoritative re-check is inside the queue. A gate record must
+            // never be opened for a handle that lost the held attempt while this
+            // call was waiting behind another session mutation.
+            const inside = validateSubmissionHandle(parsed, current);
+            if (!inside.ok)
+                return this.checkpointMismatchResult(inside, current);
+            if (!this.renewSessionLease(current.loopId)) {
+                return this.gateLeaseConflictResult(current);
+            }
+            const verdict = preflightStructuredGate(action);
+            if (verdict.kind === "user") {
+                this.recordOpenedGate(current.loopId, current.currentRound, verdict, canonicalizeGateAction(action));
+            }
+            return {
+                submissionHandle: inside.handle,
+                gateId: verdict.gateId,
+                risk: verdict.risk,
+                decision: verdict.decision,
+                reasonCodes: verdict.reasonCodes,
+                ...(verdict.kind === "user"
+                    ? {
+                        blockedScope: verdict.blockedScope,
+                        allowedBeforeApproval: verdict.allowedBeforeApproval,
+                        requiredEvidence: [],
+                        approvalQuestion: verdict.approvalQuestion,
+                    }
+                    : {
+                        blockedScope: [],
+                        allowedBeforeApproval: [],
+                        requiredEvidence: verdict.requiredEvidence,
+                    }),
+            };
+        });
     }
     /** Record a user decision for a recorded gate. The gateId embeds the
      *  canonicalized action hash — if the action changed, the match fails and
@@ -639,8 +793,9 @@ export class SessionManager {
             };
         }
         try {
-            const prefix = `loop:${loopId}:gate:`;
-            const opened = queryLoopEntries(this.loopStore, loopId, { prefix })
+            const gatePrefix = `loop:${loopId}:gate:`;
+            const opened = loadCommittedHistory(this.loopStore, loopId).entries
+                .filter((entry) => String(entry.task_id ?? "").startsWith(gatePrefix))
                 .find((entry) => entry.task_type === "gate_opened" && entry.gate_id === gateId);
             if (!opened) {
                 return {
@@ -743,79 +898,51 @@ export class SessionManager {
      *  the runtime's submission boundary reads the same context (the sub-goal
      *  reference space is exactly the compiled set the prompt carried), and two
      *  copies would let the projection and the boundary disagree about it. */
-    compileContext(session) {
-        return compileSessionContext(session);
-    }
-    /** 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)
+    /** v4.0.4: read-only terminal summary of a persisted STOPPED loop.
+     *
+     *  Returns null unless the persisted session status is exactly "stopped":
+     *  a running/paused/stalled loop without a live session must still go
+     *  through `loopforge_resume`, so "no live session" is never mistaken for
+     *  "already stopped". It never claims a lease, saves a session or writes
+     *  history; the committed view supplies every field. */
+    getStoppedLoopSummary(loopId) {
+        validateLoopId(loopId);
+        const entry = this.findSessionEntry(loopId);
+        if (!entry)
             return null;
-        const prefix = `loop:${session.loopId}:`;
-        const entries = [
-            ...queryLoopEntries(this.loopStore, session.loopId, { prefix }),
-            ...queryLoopEntries(this.loopStore, session.loopId, { prefix, feedbackOnly: true }),
-        ];
-        const compileResponse = this.compileContext(session);
-        const openGates = this.lifecycle.listOpenGateDescriptions(session.loopId);
-        // v3.8: the projection reads the WHOLE committed history. The old
-        // `beforeRound: session.currentRound` bound is only correct while the loop
-        // is running, where currentRound is always one past the last committed
-        // round; a stop / terminate / max_rounds leaves currentRound ON the round
-        // it just committed, so the bound silently dropped the loop's final round
-        // and the projection disagreed with audit and explain about it.
-        // v3.8.1: one window, one decode, one derivation. The contract facts come
-        // from the same `deriveRoundFacts` the compile path calls, so the prompt
-        // and the projection cannot tell different stories about what the machine
-        // verified.
-        const rounds = readOnlyRounds(entries);
-        const projection = buildLoopProjection(deriveCognitiveFacts({
-            compileResponse,
-            rounds,
-            facts: deriveRoundFacts({
-                rounds,
-                currentRound: (rounds[rounds.length - 1]?.round ?? 0) + 1,
-                inFlight: NO_IN_FLIGHT_ROUND,
-                subGoals: compileResponse?.sub_goals ?? [],
-                commands: getPolicy().evidence.commands ?? [],
-            }),
-            verifiedClaims: listVerifiedClaims(entries, session.loopId),
-            openGates,
-        }));
-        return projection ? { ...projection } : null;
+        const lineage = (entry.loop_lineage ?? {});
+        if (lineage.status !== "stopped")
+            return null;
+        const currentRound = typeof lineage.current_round === "number"
+            ? lineage.current_round
+            : 1;
+        return this.lifecycle.stoppedLoopResult(loopId, currentRound);
     }
     /** v3.8: Read-only per-round "why" view over committed facts. Never
      *  rebuilds history and never writes. */
     getExplain(loopId, round) {
         validateLoopId(loopId);
-        const prefix = `loop:${loopId}:`;
-        const entries = [
-            ...queryLoopEntries(this.loopStore, loopId, { prefix }),
-            ...queryLoopEntries(this.loopStore, loopId, { prefix, feedbackOnly: true }),
-        ];
-        return buildExplain(loopId, entries, round);
+        // v4.0.4: the SAME loader reports the legacy count Explain prints; Explain
+        // never re-scans for it and never decodes a legacy round into a fake row.
+        const history = loadCommittedHistory(this.loopStore, loopId);
+        return buildExplain(loopId, history.entries, round, history.legacyRounds.length);
     }
     /** Read-only end-of-loop audit (verification view). Never writes. */
     getAudit(loopId) {
         validateLoopId(loopId);
-        // v3.3.1: audit judges COMMITTED decisions, which live on :feedback
-        // entries — but queryLoopEntries excludes feedback by default, so the
-        // audit view structurally never saw a committed round (it always
-        // reported "passed" on empty history). Merge both result sets like the
-        // round coordinator does.
-        const prefix = `loop:${loopId}:`;
-        const entries = [
-            ...queryLoopEntries(this.loopStore, loopId, { prefix }),
-            ...queryLoopEntries(this.loopStore, loopId, { prefix, feedbackOnly: true }),
-        ];
-        // Zero committed decisions → nothing to audit. Returning null lets the
-        // tools layer report "no audit data" instead of the external auditor
-        // solemnly passing a loop that never ran (or a mistyped loopId).
-        const hasCommittedDecision = readOnlyRounds(entries).length > 0;
-        if (!hasCommittedDecision)
+        // Audit judges COMMITTED decisions. The shared history loader returns the
+        // flat entry view and the decoded branch; there is no second query pair.
+        const history = loadCommittedHistory(this.loopStore, loopId);
+        // No committed decision and no legacy envelope → nothing to audit.
+        // Returning null lets the tools layer report "no audit data" instead of
+        // the external auditor solemnly passing a loop that never ran (or a
+        // mistyped loopId). Legacy-only loops still get a report so the gap is
+        // explicit, never silently empty.
+        if (history.rounds.length === 0 && history.directives.length === 0 &&
+            history.legacyRounds.length === 0) {
             return null;
-        const audit = buildAudit(loopId, entries, this.loopStore);
+        }
+        const audit = buildAudit(loopId, history.entries, this.loopStore);
         return { ...audit };
     }
     /** v3.5: The ACTIVE Round Contract governing the session's next round —
@@ -833,16 +960,10 @@ export class SessionManager {
      *  statistics (A4 port) folded with this process's live observations.
      *  Non-durable fields (evidence, vault errors) come from live only. */
     getPolicyMetrics(loopId) {
-        // v3.3.1: derived metrics judge committed decisions on :feedback entries,
-        // which queryLoopEntries excludes by default — merge both result sets so
-        // restart-surviving metrics actually see the committed rounds (before,
-        // derived.committedRounds was structurally 0 and the merge fell back to
-        // the live-only snapshot every time).
-        const prefix = `loop:${loopId}:`;
-        const entries = [
-            ...queryLoopEntries(this.loopStore, loopId, { prefix }),
-            ...queryLoopEntries(this.loopStore, loopId, { prefix, feedbackOnly: true }),
-        ];
+        // Derived metrics judge committed decisions through the same history
+        // loader as every other read path. Live-only counters are folded in
+        // afterwards; they never become the source of round facts.
+        const entries = loadCommittedHistory(this.loopStore, loopId).entries;
         const derived = derivePolicyMetrics(loopId, entries);
         const live = policyMetrics.snapshot(loopId);
         if (derived.committedRounds === 0)
@@ -860,20 +981,32 @@ export class SessionManager {
      *  `strategy_stability` was a literal `true`. What remains is counted
      *  directly from committed round flags. */
     getHealth(loopId) {
-        const engine = new LoopForgeEngine(this.loopStore);
-        const context = engine.hydrateLoopContext(loopId);
-        // No hydratable context at all → unknown loop. A started-but-uncommitted
-        // loop DOES have a context (the compile persists a lineage entry), so it
-        // still gets a view — with zeros — exactly as it did before.
-        if (!context)
+        const history = loadCommittedHistory(this.loopStore, loopId);
+        // No stored session or round at all → unknown loop. A started-but-
+        // uncommitted loop has a session entry, so it still gets a zeroed view.
+        if (history.entries.length === 0)
             return null;
-        const entries = Array.isArray(context.results) ? context.results : [];
-        const views = readOnlyRounds(entries);
+        const views = history.rounds;
         const roundsWithUnverifiedItems = views.filter((view) => view.verificationFlags.some((flag) => flag.check === CHECK_CONTRACT_ITEMS_UNVERIFIED)).length;
+        // v4.0.3: the ONE persisted posture is the source of this distribution.
+        const roundsByEvidenceStatus = {
+            verified: 0,
+            insufficient: 0,
+            contradicted: 0,
+            unknown: 0,
+            not_applicable: 0,
+        };
+        for (const view of views) {
+            if (view.evidencePosture) {
+                roundsByEvidenceStatus[view.evidencePosture.status]++;
+            }
+        }
         return {
             loopId,
             committed_rounds: views.length,
+            legacy_rounds: history.legacyRounds.length,
             rounds_with_unverified_items: roundsWithUnverifiedItems,
+            rounds_by_evidence_status: roundsByEvidenceStatus,
             // The policy value the enforcement gate escalates on. The streak itself
             // is derived in the gate — re-deriving it here would be a second
             // implementation of the same rule, which is what this release removes.
@@ -881,53 +1014,231 @@ export class SessionManager {
             policy_metrics: this.getPolicyMetrics(loopId),
         };
     }
+    /** v4.0.0: the stable result for a missing/malformed handle. */
+    handleRequiredResult() {
+        const detail = "submissionHandle must be an object with exactly sessionId, roundId, " +
+            "and transactionId as non-empty strings.";
+        return {
+            sessionId: "",
+            round: 0,
+            prompt: null,
+            stopDetail: `${detail} Copy it from the latest LoopForge response. ` +
+                LOST_HANDLE_ROUTING,
+            submissionError: {
+                code: "submission_handle_required",
+                details: { reason_code: "shape", detail },
+            },
+        };
+    }
+    sessionNotFoundResult(sessionId) {
+        return {
+            sessionId,
+            round: 0,
+            prompt: null,
+            stopDetail: "No session exists with this ID. It may have expired, been deleted, " +
+                "or never existed. Call loopforge_status with view=\"all\" to find the " +
+                "loopId; if the held prompt is still in context, call loopforge_status " +
+                "with that loopId to fetch the current handle; otherwise call " +
+                "loopforge_resume with it.",
+            submissionError: {
+                code: "session_not_found",
+                details: { sessionId },
+            },
+        };
+    }
+    sessionStateResult(session) {
+        const handle = makeSubmissionHandle(session);
+        return {
+            sessionId: session.sessionId,
+            round: session.currentRound,
+            ...(handle ? { submissionHandle: handle } : {}),
+            prompt: null,
+            sessionStatus: session.status,
+            stopDetail: `Session is ${session.status}. Use loopforge_resume to restart a ` +
+                "paused session, or loopforge_start for a new task.",
+        };
+    }
+    /** v4.0.0: one stored-prompt re-delivery for next/recover. A held prompt is
+     *  returned with the current handle and a warning; without one, the stable
+     *  mismatch error carries the current handle when it exists. */
+    handleMismatchResult(check, session) {
+        if (check.reason !== "no_held_prompt") {
+            const held = this.lifecycle.heldPromptResult(session, staleHandleWarning());
+            if (held)
+                return held;
+        }
+        return {
+            sessionId: session.sessionId,
+            round: session.currentRound,
+            ...(check.current ? { submissionHandle: check.current } : {}),
+            prompt: null,
+            stopDetail: check.detail,
+            submissionError: {
+                code: "submission_handle_mismatch",
+                details: {
+                    reason_code: check.reason,
+                    ...(check.mismatched.length > 0 ? { mismatched: [...check.mismatched] } : {}),
+                },
+            },
+        };
+    }
+    /** v4.0.0: the checkpoint variant: never re-deliver a prompt, never create a
+     *  checkpoint. The current handle rides the error for re-anchoring. */
+    checkpointMismatchResult(check, session) {
+        return {
+            error: "submission_handle_mismatch",
+            errorMessage: check.detail,
+            sessionId: session.sessionId,
+            ...(check.current ? { submissionHandle: check.current } : {}),
+            details: {
+                reason_code: check.reason,
+                ...(check.mismatched.length > 0 ? { mismatched: [...check.mismatched] } : {}),
+            },
+        };
+    }
+    /** v3.9.7: a pending rollback directive whose restore is not yet verified.
+     *  Read-only; used before the queue/lease so a stale handle cannot mask the
+     *  "call resume" recovery UX. */
+    restorePendingResult(session) {
+        const pending = loadCommittedHistory(this.loopStore, session.loopId)
+            .pendingDirective;
+        if (!pending?.recovery)
+            return null;
+        if (session.roundSnapshot?.restore?.directiveTransactionId ===
+            pending.recovery.transaction_id &&
+            session.roundSnapshot?.round === pending.recovery.target.redo_round) {
+            return null;
+        }
+        const handle = makeSubmissionHandle(session);
+        return {
+            sessionId: session.sessionId,
+            round: session.currentRound,
+            ...(handle ? { submissionHandle: handle } : {}),
+            prompt: null,
+            stopReason: "stalled",
+            submissionError: {
+                code: "restore_pending",
+                details: {
+                    loopId: session.loopId,
+                    directive_transaction_id: pending.recovery.transaction_id,
+                    redo_round: pending.recovery.target.redo_round,
+                    detail: "A pending restore must be completed by loopforge_resume before work can be submitted.",
+                },
+            },
+        };
+    }
     /** Core cycle: extract self-eval → record feedback → check stop → compile next.
-     *  The lease + per-session queue wrap the RoundLifecycle state machine.
-     *  @param preExtractedEval Structured SelfEvaluation supplied by the caller.
-     *    An absent value is returned as evaluation_invalid without mutating state.
-     *  @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. */
-    /** \`submission\` is the RAW evaluation payload, not a built one.
      *
-     *  v3.8.1: this method used to carry a partial copy of the submission
-     *  boundary (an object check plus core-field validation) while the MCP tool
-     *  handler carried the rest — one rule, three copies, across two layers.
-     *  The boundary now lives entirely in the runtime
-     *  (`RoundLifecycle.submissionBoundary`), so every caller — this manager, a
-     *  library user, a future CLI command — gets the same strictness. */
-    /** \`submission\` is the RAW evaluation payload, not a built one.
-     *
-     *  v3.8.1: this method used to carry a partial copy of the submission
-     *  boundary (an object check plus core-field validation) while the MCP tool
-     *  handler carried the rest — one rule, three copies, across two layers.
-     *  The whole boundary now runs HERE, before the queue and before the lease
-     *  heartbeat, so every caller of the public API gets it and a rejected
-     *  payload leaves nothing durable behind. */
-    async advance(sessionId, output, submission, roundId) {
-        // Judged before the session is even resolved: a malformed evaluation is a
-        // payload defect whatever the session's state. See submission-boundary.ts.
-        const boundary = validateSubmission(this.loopStore, this.sessions.get(sessionId), submission);
+     *  v4.0.0: the caller supplies the ONE `submissionHandle`; identity is
+     *  checked before the payload boundary and before the queue/lease heartbeat.
+     *  `submission` is the RAW evaluation payload. The whole payload boundary
+     *  still runs here, so every public caller gets the same strictness. */
+    async advance(handle, output, submission, inputs) {
+        const normalizedInputs = normalizeInvocationInputs(inputs);
+        const parsed = parseSubmissionHandle(handle);
+        if (!parsed)
+            return this.handleRequiredResult();
+        const session = this.sessions.get(parsed.sessionId);
+        if (!session)
+            return this.sessionNotFoundResult(parsed.sessionId);
+        if (session.status !== "running" && session.status !== "stalled") {
+            return this.sessionStateResult(session);
+        }
+        const pending = this.restorePendingResult(session);
+        if (pending)
+            return pending;
+        const check = validateSubmissionHandle(parsed, session);
+        if (!check.ok)
+            return this.handleMismatchResult(check, session);
+        // Identity is established for the attempt named by the handle. Only now
+        // does the payload boundary judge the submission against that attempt's
+        // reference space.
+        const boundary = validateSubmission(this.loopStore, session, submission);
         if (!boundary.ok) {
+            const current = makeSubmissionHandle(session);
             return {
-                sessionId,
-                round: this.sessions.get(sessionId)?.currentRound ?? 0,
-                ...(roundId !== undefined ? { roundId } : {}),
+                sessionId: session.sessionId,
+                round: session.currentRound,
+                ...(current ? { submissionHandle: current } : {}),
                 prompt: null,
-                stopReason: boundary.submissionError.code,
                 stopDetail: boundary.stopDetail,
                 submissionError: boundary.submissionError,
             };
         }
-        return this.withSessionQueue(sessionId, async () => {
-            const session = this.sessions.get(sessionId);
-            if (session?.status === "running" &&
-                !this.renewSessionLease(session.loopId)) {
-                return this.leaseConflictResult(session.loopId, this.findSessionEntry(session.loopId));
+        return this.withSessionQueue(session.sessionId, async () => {
+            const current = this.sessions.get(session.sessionId);
+            if (!current)
+                return this.sessionNotFoundResult(session.sessionId);
+            if (current.status !== "running" && current.status !== "stalled") {
+                return this.sessionStateResult(current);
+            }
+            const pendingInside = this.restorePendingResult(current);
+            if (pendingInside)
+                return pendingInside;
+            // The authoritative re-check. It runs AFTER the queue is acquired but
+            // BEFORE the lease heartbeat, so a concurrent commit cannot make this
+            // call renew a lease for a handle it is about to reject.
+            const inside = validateSubmissionHandle(parsed, current);
+            if (!inside.ok)
+                return this.handleMismatchResult(inside, current);
+            if (current.status === "running" &&
+                !this.renewSessionLease(current.loopId)) {
+                return this.leaseConflictResult(current.loopId, this.findSessionEntry(current.loopId));
+            }
+            try {
+                return await this.lifecycle.advance(current.sessionId, output, boundary.evaluation, boundary.diagnostics, boundary.submittedFields, normalizedInputs);
+            }
+            catch (error) {
+                if (error instanceof SessionLeaseConflictError) {
+                    return this.leaseConflictResult(error.loopId, this.findSessionEntry(error.loopId));
+                }
+                throw error;
+            }
+        });
+    }
+    /** v4.0.5: recompile the held prompt for a new host-provided instruction.
+     *  This does NOT submit an evaluation or advance the round: the exact held
+     *  handle is required, and the same round/attempt/context boundary is
+     *  preserved. The handle is re-checked inside the queue before the lease is
+     *  renewed, so a stale handle has zero side effects. */
+    async recompileHeld(handle, instruction) {
+        const normalizedInputs = normalizeInvocationInputs({
+            currentUserInstruction: instruction,
+        });
+        const parsed = parseSubmissionHandle(handle);
+        if (!parsed)
+            return this.handleRequiredResult();
+        const session = this.sessions.get(parsed.sessionId);
+        if (!session)
+            return this.sessionNotFoundResult(parsed.sessionId);
+        if (session.status !== "running" && session.status !== "stalled") {
+            return this.sessionStateResult(session);
+        }
+        const pending = this.restorePendingResult(session);
+        if (pending)
+            return pending;
+        const check = validateSubmissionHandle(parsed, session);
+        if (!check.ok)
+            return this.handleMismatchResult(check, session);
+        return this.withSessionQueue(session.sessionId, async () => {
+            const current = this.sessions.get(session.sessionId);
+            if (!current)
+                return this.sessionNotFoundResult(session.sessionId);
+            if (current.status !== "running" && current.status !== "stalled") {
+                return this.sessionStateResult(current);
+            }
+            const pendingInside = this.restorePendingResult(current);
+            if (pendingInside)
+                return pendingInside;
+            const inside = validateSubmissionHandle(parsed, current);
+            if (!inside.ok)
+                return this.handleMismatchResult(inside, current);
+            if (current.status === "running" &&
+                !this.renewSessionLease(current.loopId)) {
+                return this.leaseConflictResult(current.loopId, this.findSessionEntry(current.loopId));
             }
             try {
-                return await this.lifecycle.advance(sessionId, output, boundary.evaluation, roundId, boundary.diagnostics, boundary.submittedFields);
+                return await this.lifecycle.recompileHeldWithInstruction(current, normalizedInputs.currentUserInstruction);
             }
             catch (error) {
                 if (error instanceof SessionLeaseConflictError) {
@@ -937,6 +1248,330 @@ export class SessionManager {
             }
         });
     }
+    /** v3.9.7: submit an Agent-initiated recovery. v4.0.0: the handle is the
+     *  only anchor; shape and target visibility are checked before the
+     *  queue/lease, and the exact handle is re-checked before lease renewal. */
+    async recover(handle, recovery, inputs) {
+        const normalizedInputs = normalizeInvocationInputs(inputs);
+        const parsed = parseSubmissionHandle(handle);
+        if (!parsed)
+            return this.handleRequiredResult();
+        const session = this.sessions.get(parsed.sessionId);
+        if (!session)
+            return this.sessionNotFoundResult(parsed.sessionId);
+        if (session.status !== "running" && session.status !== "stalled") {
+            return this.sessionStateResult(session);
+        }
+        const pending = this.restorePendingResult(session);
+        if (pending)
+            return pending;
+        const check = validateSubmissionHandle(parsed, session);
+        if (!check.ok)
+            return this.handleMismatchResult(check, session);
+        if (!getPolicy().engine.agent_recovery_enabled) {
+            return this.recoveryDisabledResult(check.handle, session);
+        }
+        const invalid = (detail) => ({
+            sessionId: session.sessionId,
+            round: session.currentRound,
+            submissionHandle: check.handle,
+            prompt: null,
+            submissionError: {
+                code: "recovery_invalid",
+                details: { reason_code: "invalid_shape", detail },
+            },
+        });
+        if (!isRecord(recovery))
+            return invalid("recovery must be an object");
+        const keys = Object.keys(recovery);
+        if (keys.some((key) => key !== "target_checkpoint_id" && key !== "reason")) {
+            return invalid("recovery accepts only target_checkpoint_id and reason");
+        }
+        if (typeof recovery.target_checkpoint_id !== "string" ||
+            recovery.target_checkpoint_id.trim().length === 0) {
+            return invalid("target_checkpoint_id must be a non-empty string");
+        }
+        if (typeof recovery.reason !== "string" ||
+            recovery.reason.trim().length === 0 ||
+            recovery.reason.length > 500) {
+            return invalid("reason must be a non-empty string of at most 500 characters");
+        }
+        const targetCheckpointId = recovery.target_checkpoint_id;
+        const reason = recovery.reason;
+        // Read-only visibility check against the exact held snapshot. An invalid
+        // target must not cause a lease renewal or a directive.
+        const history = loadCommittedHistory(this.loopStore, session.loopId);
+        const entries = history.entries;
+        // A pending directive outranks target validation; the lifecycle retries
+        // the same restore and never commits a second directive.
+        if (!history.pendingDirective) {
+            const resolved = findCheckpointRef({
+                entries,
+                held: check.snapshot,
+                checkpointId: targetCheckpointId,
+            });
+            if (!resolved.ok) {
+                return {
+                    sessionId: session.sessionId,
+                    round: session.currentRound,
+                    submissionHandle: check.handle,
+                    prompt: null,
+                    submissionError: {
+                        code: resolved.code,
+                        details: {
+                            target_checkpoint_id: targetCheckpointId,
+                            reason_code: resolved.reason,
+                            detail: resolved.detail,
+                            current_round: session.currentRound,
+                        },
+                    },
+                };
+            }
+        }
+        const validatedRecovery = {
+            target_checkpoint_id: targetCheckpointId,
+            reason,
+        };
+        return this.withSessionQueue(session.sessionId, async () => {
+            const current = this.sessions.get(session.sessionId);
+            if (!current)
+                return this.sessionNotFoundResult(session.sessionId);
+            if (current.status !== "running" && current.status !== "stalled") {
+                return this.sessionStateResult(current);
+            }
+            const pendingInside = this.restorePendingResult(current);
+            if (pendingInside)
+                return pendingInside;
+            const inside = validateSubmissionHandle(parsed, current);
+            if (!inside.ok)
+                return this.handleMismatchResult(inside, current);
+            if (!getPolicy().engine.agent_recovery_enabled) {
+                return this.recoveryDisabledResult(inside.handle, current);
+            }
+            if (current.status === "running" &&
+                !this.renewSessionLease(current.loopId)) {
+                return this.leaseConflictResult(current.loopId, this.findSessionEntry(current.loopId));
+            }
+            try {
+                return await this.lifecycle.recover(current.sessionId, validatedRecovery, normalizedInputs);
+            }
+            catch (error) {
+                if (error instanceof SessionLeaseConflictError) {
+                    return this.leaseConflictResult(error.loopId, this.findSessionEntry(error.loopId));
+                }
+                throw error;
+            }
+        });
+    }
+    recoveryDisabledResult(handle, session) {
+        return {
+            sessionId: session.sessionId,
+            round: session.currentRound,
+            submissionHandle: handle,
+            prompt: null,
+            submissionError: {
+                code: "recovery_disabled",
+                details: { policy: "engine.agent_recovery_enabled" },
+            },
+        };
+    }
+    /** v3.9.7: Agent-created mid-round savepoint. v4.0.0: handle identity is
+     *  checked before the queue and again before lease renewal; capture/save
+     *  happen only after both. A checkpoint never changes the handle. */
+    async checkpoint(handle) {
+        const parsed = parseSubmissionHandle(handle);
+        if (!parsed) {
+            const detail = "submissionHandle must be an object with exactly sessionId, roundId, " +
+                "and transactionId as non-empty strings.";
+            return {
+                error: "submission_handle_required",
+                errorMessage: `${detail} Copy it from the latest LoopForge response. ${LOST_HANDLE_ROUTING}`,
+                details: { reason_code: "shape", detail },
+            };
+        }
+        const session = this.sessions.get(parsed.sessionId);
+        if (!session) {
+            return {
+                error: "session_not_found",
+                errorMessage: "No session exists with this ID.",
+                sessionId: parsed.sessionId,
+            };
+        }
+        if (session.status !== "running") {
+            const current = makeSubmissionHandle(session);
+            return {
+                error: "checkpoint_invalid",
+                errorMessage: `Session is ${session.status}; a checkpoint requires a running held evaluation.`,
+                sessionId: session.sessionId,
+                ...(current ? { submissionHandle: current } : {}),
+                details: { reason_code: "session_not_running" },
+            };
+        }
+        const check = validateSubmissionHandle(parsed, session);
+        if (!check.ok)
+            return this.checkpointMismatchResult(check, session);
+        return this.withSessionQueue(session.sessionId, async () => {
+            const current = this.sessions.get(session.sessionId);
+            if (!current) {
+                return {
+                    error: "session_not_found",
+                    errorMessage: "No session exists with this ID.",
+                    sessionId: session.sessionId,
+                };
+            }
+            if (current.status !== "running") {
+                const currentHandle = makeSubmissionHandle(current);
+                return {
+                    error: "checkpoint_invalid",
+                    errorMessage: `Session is ${current.status}; a checkpoint requires a running held evaluation.`,
+                    sessionId: current.sessionId,
+                    ...(currentHandle ? { submissionHandle: currentHandle } : {}),
+                    details: { reason_code: "session_not_running" },
+                };
+            }
+            // Authoritative re-check: after the queue is acquired, before the lease
+            // heartbeat. A checkpoint must never capture or save for a stale handle.
+            const inside = validateSubmissionHandle(parsed, current);
+            if (!inside.ok)
+                return this.checkpointMismatchResult(inside, current);
+            const pending = this.restorePendingResult(current);
+            if (pending) {
+                return {
+                    error: "restore_pending",
+                    errorMessage: "A pending restore must be completed by loopforge_resume before creating a checkpoint.",
+                    sessionId: current.sessionId,
+                    submissionHandle: inside.handle,
+                    details: { reason_code: "restore_pending" },
+                };
+            }
+            if (!this.renewSessionLease(current.loopId)) {
+                const conflict = this.leaseConflictResult(current.loopId, this.findSessionEntry(current.loopId));
+                return {
+                    error: "lease_conflict",
+                    errorMessage: conflict.stopDetail ?? "Another process owns this loop.",
+                    sessionId: current.sessionId,
+                    details: { reason_code: "lease_conflict" },
+                };
+            }
+            const held = inside.snapshot;
+            const store = this.checkpointStoreFor?.(current.loopId);
+            if (!store) {
+                return {
+                    error: "checkpoint_unavailable",
+                    errorMessage: "No workspace checkpoint store is configured for this loop.",
+                    sessionId: current.sessionId,
+                    submissionHandle: inside.handle,
+                    details: { reason_code: "store_unavailable" },
+                };
+            }
+            let stateDir;
+            try {
+                stateDir = resolveStateDirectory(process.cwd(), getPolicy().backend.root_dir);
+            }
+            catch (error) {
+                return {
+                    error: "checkpoint_unavailable",
+                    errorMessage: `The runtime state directory could not be resolved: ${String(error)}`,
+                    sessionId: current.sessionId,
+                    submissionHandle: inside.handle,
+                    details: { reason_code: "state_directory_invalid" },
+                };
+            }
+            const exclude = (path) => {
+                const abs = resolve(path);
+                const prefixAbs = stateDir.endsWith(sep) ? stateDir : `${stateDir}${sep}`;
+                return abs === stateDir || abs.startsWith(prefixAbs);
+            };
+            let manifest;
+            try {
+                manifest = await store.capture({
+                    round: held.round,
+                    role: "mid",
+                    cwd: process.cwd(),
+                    exclude,
+                    timeoutMs: Math.max(60_000, getPolicy().evidence.timeout_ms),
+                });
+            }
+            catch (error) {
+                if (error instanceof CheckpointError) {
+                    return {
+                        error: error.code,
+                        errorMessage: error.message,
+                        sessionId: current.sessionId,
+                        submissionHandle: inside.handle,
+                        details: { reason_code: error.reasonCode },
+                    };
+                }
+                return {
+                    error: "checkpoint_failed",
+                    errorMessage: String(error),
+                    sessionId: current.sessionId,
+                    submissionHandle: inside.handle,
+                    details: { reason_code: "capture_error" },
+                };
+            }
+            // The capture yielded to the event loop; a concurrent advance/pause may
+            // have invalidated the held transaction. Never attach an orphan
+            // checkpoint to a different attempt.
+            const after = validateSubmissionHandle(parsed, this.sessions.get(session.sessionId) ?? current);
+            if (!after.ok) {
+                return {
+                    error: "checkpoint_invalid",
+                    errorMessage: "The held attempt changed while the checkpoint was captured.",
+                    sessionId: current.sessionId,
+                    ...(after.current ? { submissionHandle: after.current } : {}),
+                    details: { reason_code: "identity_changed" },
+                };
+            }
+            const ref = buildCheckpointRef(manifest, {
+                transactionId: held.transactionId,
+                branchId: held.branchId,
+            });
+            const previous = held.checkpoints ?? [];
+            const duplicate = previous.find((item) => item.checkpointId === ref.checkpointId);
+            // The cap counts DISTINCT savepoints. Re-capturing an already visible
+            // state is idempotent and must still return the existing ref at the cap.
+            if (!duplicate &&
+                previous.length >= MAX_MID_CHECKPOINTS_PER_TRANSACTION) {
+                return {
+                    error: "checkpoint_limit",
+                    errorMessage: `This attempt already has ${MAX_MID_CHECKPOINTS_PER_TRANSACTION} mid-round checkpoints.`,
+                    sessionId: current.sessionId,
+                    submissionHandle: after.handle,
+                    details: { reason_code: "mid_checkpoint_cap" },
+                };
+            }
+            if (!duplicate) {
+                held.checkpoints = [...previous, ref];
+                try {
+                    this.lifecycle.save(current);
+                }
+                catch (error) {
+                    held.checkpoints = previous;
+                    return {
+                        error: "checkpoint_failed",
+                        errorMessage: `The checkpoint manifest was written but the session could not be saved: ${String(error)}. Retry returns the same id.`,
+                        sessionId: current.sessionId,
+                        submissionHandle: after.handle,
+                        details: { reason_code: "session_save_failed" },
+                    };
+                }
+            }
+            return {
+                sessionId: current.sessionId,
+                submissionHandle: after.handle,
+                checkpointId: manifest.checkpointId,
+                round: held.round,
+                role: "mid",
+                redoRound: manifest.round,
+                createdAt: (duplicate ?? ref).createdAt,
+                ...(manifest.head ? { head: manifest.head } : {}),
+                fileCount: Object.keys(manifest.fingerprints).length,
+                contentCount: manifest.contents.length,
+                contentHash: manifest.contentHash,
+            };
+        });
+    }
     /** Replay timeline for a session — creates ReplayBackend from the stored backend. */
     replayTimeline(sessionId) {
         const session = this.sessions.get(sessionId);
@@ -956,6 +1591,45 @@ export class SessionManager {
         const timeline = replay.timeline(loopId);
         return timeline.length > 0 ? timeline : null;
     }
+    /** v4.0.2: a bounded replay page with its window metadata. `null` only when
+     *  the session does not exist; an empty loop returns an empty page. */
+    replayPage(sessionId, opts) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return null;
+        return this.replayPageByLoop(session.loopId, opts);
+    }
+    replayPageByLoop(loopId, opts) {
+        validateLoopId(loopId);
+        return new ReplayBackend(this.loopStore).page(loopId, opts);
+    }
+    /** v3.9.6: committed rollback directives for the replay view. They are
+     *  events, not normal rounds; the timeline stays a normal-round projection. */
+    replayRollbacks(loopId) {
+        validateLoopId(loopId);
+        return loadCommittedHistory(this.loopStore, loopId).directives.map((view) => ({
+            round: view.round,
+            roundId: view.roundId,
+            transactionId: view.transactionId ?? view.roundId,
+            branchId: view.branchId ?? null,
+            origin: view.origin === "agent" ? "agent" : "machine",
+            redoRound: view.recovery?.target.redo_round ?? 0,
+            targetCheckpointId: view.recovery?.target.checkpoint_id ?? "",
+            reason: view.recovery?.reason ?? "",
+            observedSkippedFiles: [...(view.recovery?.observed_skipped_files ??
+                    view.recovery?.skipped_files ?? [])],
+            reportedSkippedFiles: [...(view.recovery?.reported_skipped_files ?? [])],
+            skippedFiles: [...(view.recovery?.skipped_files ?? [])],
+            abandonedRounds: [...(view.recovery?.abandoned_rounds ?? [])],
+            triggerFindings: [...(view.recovery?.trigger_findings ?? [])],
+            preservedDiscoveries: [...(view.recovery?.skipped_discoveries ?? [])],
+            // v4.0.2: the committed abandoned-path facts, same display caps as
+            // Working Memory / replay.
+            failedRounds: [...(view.recovery?.failed_rounds ?? [])],
+            approaches: [...(view.recovery?.approaches ?? [])].map((value) => value.slice(0, 200)),
+            wrongAssumptions: [...(view.recovery?.wrong_assumptions ?? [])].map((value) => value.slice(0, 500)),
+        }));
+    }
     /** v3.9.1: unsupported envelope versions for a loop, reported explicitly
      *  rather than silently dropped from replay/audit. */
     replayLegacyRounds(loopId) {