loopforge 3.9.4 → 4.0.7

package/dist/mcp/tools.js

@@ -1,24 +1,76 @@
 /** LoopForge MCP — Tool definitions and handlers.
  *
- * 9 tools: start, next, status, stop, pause, resume, replay,
- *          gate_check, gate_resolve.
- * status is the unified inspection tool (view=session|loop|all|audit).
+ * 10 tools: start, next, status, stop, pause, resume, replay,
+ *           checkpoint, gate_check, gate_resolve.
+ * status is the unified inspection tool (view=session|loop|all|audit|explain).
  * Each handler receives SessionManager + parsed input, returns the output object.
  */
-import { StartCriteriaError } from "./round-lifecycle.js";
+import { InvocationInputError, MANUAL_STOP_REASON, StartCriteriaError, } from "./round-lifecycle.js";
+import { PROMPT_CONTEXT_REASONS } from "../protocol.js";
 import { ProjectionCoverageError } from "../prompt-coverage.js";
+import { LegacyHistoryError, LoopExistsError, OperatorAcceptanceConflictError, StartFailureError, } from "../errors.js";
 import { validateCoreSelfEvaluation } from "../self-eval.js";
 import { isRecord } from "../token-utils.js";
 import { getPolicy, validateLoopId } from "../policy.js";
 import { deriveEvidenceCapability } from "../evidence-provider.js";
-import { fieldGuideDescription } from "../submission-guidance.js";
+import { CORE_SELF_EVALUATION_FIELDS, fieldGuideDescription, } from "../submission-guidance.js";
+import { LOST_HANDLE_ROUTING } from "../recovery-guidance.js";
+import { CONTEXT_MODE_DESCRIPTION } from "../round-guidance.js";
+import { SessionLeaseConflictError } from "../storage.js";
+import { ReplayWindowError } from "../replay.js";
 // ═══════════════════════════════════════════════════════════════════════════
 // Tool schemas (MCP JSON Schema format)
 // ═══════════════════════════════════════════════════════════════════════════
+/** v4.0.0: the ONE held-round anchor. The object is closed so a client cannot
+ *  smuggle separate anchor fields alongside it. */
+const SUBMISSION_HANDLE_SCHEMA = {
+    type: "object",
+    description: "The submissionHandle object returned with the held prompt. Copy it " +
+        "verbatim; never edit, reconstruct, or derive it. A stale handle never " +
+        "submits work. " + LOST_HANDLE_ROUTING,
+    properties: {
+        sessionId: {
+            type: "string",
+            description: "The owning session identity.",
+        },
+        roundId: {
+            type: "string",
+            description: "The stable logical round identity.",
+        },
+        transactionId: {
+            type: "string",
+            description: "The exact held transaction attempt.",
+        },
+    },
+    required: ["sessionId", "roundId", "transactionId"],
+    additionalProperties: false,
+};
+/** Output form: absent/null on terminal or non-held results, exact shape when
+ *  present. */
+const SUBMISSION_HANDLE_OUTPUT_SCHEMA = {
+    ...SUBMISSION_HANDLE_SCHEMA,
+    type: ["object", "null"],
+};
+/** The closed argument set for `loopforge_start`.
+ *
+ *  The handler's unknown-argument guard reads this list; `schema-sync.test`
+ *  asserts that the advertised tool schema exposes exactly the same keys. A
+ *  field removed from the protocol (for example `domain` in 4.0.1) must not
+ *  survive in only one of them: the schema says what clients may send, and
+ *  the guard makes a stale caller fail loudly instead of silently dropping
+ *  the field. */
+export const START_INPUT_KEYS = [
+    "task",
+    "loopId",
+    "maxRounds",
+    "planSource",
+    "constraints",
+    "criteria",
+];
 const TOOL_BASE_SCHEMAS = [
     {
         name: "loopforge_start",
-        description: "Start a new LoopForge loop session. Compiles the first-round prompt from the task description and returns it. Use this at the beginning of an autonomous multi-round coding loop.",
+        description: "Start a new LoopForge loop for a NEW objective. Compiles the first-round prompt from the task description and returns it. Use loopforge_status/loopforge_resume instead for an objective that already has a loopId.",
         inputSchema: {
             type: "object",
             properties: {
@@ -28,17 +80,16 @@ const TOOL_BASE_SCHEMAS = [
                 },
                 loopId: {
                     type: "string",
-                    description: "Optional loop ID. Generated automatically if not provided.",
+                    description: "Optional durable loop ID. Generated when omitted and returned " +
+                        "with the first prompt. Keep it: loopforge_resume and every " +
+                        "loopforge_status view use loopId after a restart, and a live " +
+                        "session can re-anchor a lost handle with loopId.",
                 },
                 maxRounds: {
                     type: "integer",
                     minimum: 1,
                     description: "Maximum rounds before auto-stop. Default: 200 from policy.",
                 },
-                domain: {
-                    type: "string",
-                    description: "Domain hint (e.g. 'solidity', 'react', 'rust') for state context.",
-                },
                 planSource: {
                     type: "string",
                     description: "Plan reference for constraint extraction (e.g. 'docs/plan.md').",
@@ -51,7 +102,9 @@ const TOOL_BASE_SCHEMAS = [
                 criteria: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Initial success criteria. Each becomes a stable cr-XXXXXXXX anchor " +
+                    description: "Initial success criteria — the operator's acceptance surface. Phrase " +
+                        "each as an observable outcome; implementation detail belongs in " +
+                        "sub-goals or task text. Each becomes a stable cr-XXXXXXXX anchor " +
                         "rendered in every prompt and usable by contract items. Omit to keep " +
                         "the default criterion.",
                 },
@@ -61,30 +114,58 @@ const TOOL_BASE_SCHEMAS = [
     },
     {
         name: "loopforge_next",
-        description: "Submit the output from the current round and advance to the next. Returns the next-round prompt, or null with a stopReason when the loop ends. A structured evaluation is required; output is optional supporting context.",
+        description: "Submit one evaluation for the held attempt. Returns the next prompt (with its derived contextMode/contextReason and a strategy label), or null with stopReason/stopDetail when the loop ends. The submission may be accepted, rejected (same logical round, attempt+1, new handle), replayed, or answered with a rollback directive. A structured evaluation is required unless currentUserInstruction is the only argument: then the held prompt is recompiled for that instruction without submitting or advancing. If the held prompt is same_round_retry and the original invocation is gone, do NOT use next — call loopforge_resume(loopId, invocationLost: true) so LoopForge recompiles the same round/attempt as a cold-context prompt.",
         inputSchema: {
             type: "object",
             properties: {
-                sessionId: {
+                submissionHandle: SUBMISSION_HANDLE_SCHEMA,
+                output: {
                     type: "string",
-                    description: "Session ID returned by loopforge_start.",
+                    description: "Optional. The agent's full output from executing the current round's prompt. The structured evaluation is the authoritative report.",
                 },
-                roundId: {
+                currentUserInstruction: {
                     type: "string",
-                    description: "The roundId from the most recent loopforge_start / loopforge_next / loopforge_resume / loopforge_status response. Anchors this submission to the exact round it reports on: a submission whose roundId no longer matches the current round (the round already committed) is not processed — the current held prompt is returned instead, so lost responses can be recovered without skipping or double-committing a round.",
+                    description: "v4.0.5: the host's current user instruction for this invocation, " +
+                        "trimmed and non-empty. It is invocation input, not a task update: " +
+                        "it never rewrites session.task, the Objective, Success Criteria, " +
+                        "hard constraints or the Round Contract. With evaluation/recovery " +
+                        "it is carried into the retry/redo/next prompt compiled after the " +
+                        "submission; with only the handle it recompiles the held prompt " +
+                        "without submitting or advancing the round.",
                 },
-                output: {
-                    type: "string",
-                    description: "Optional. The agent's full output from executing the current round's prompt. The structured evaluation is the authoritative report.",
+                recovery: {
+                    type: "object",
+                    description: "v3.9.7: Agent-initiated recovery. Abandon the current branch and " +
+                        "restore a visible workspace checkpoint (the held before-image, a " +
+                        "mid-round savepoint, or a committed round's before-image). " +
+                        "Mutually exclusive with evaluation. LoopForge records the directive, " +
+                        "executes the restore, verifies the full Git boundary, then issues " +
+                        "the redo prompt. It never chooses a target or judges the reason.",
+                    properties: {
+                        target_checkpoint_id: {
+                            type: "string",
+                            pattern: "^ck-[a-f0-9]{24}$",
+                            description: "Checkpoint id (ck-<24 hex>) from the held prompt, a loopforge_checkpoint result, or a committed round's before-image.",
+                        },
+                        reason: {
+                            type: "string",
+                            minLength: 1,
+                            maxLength: 500,
+                            description: "The Agent's reason for abandoning the branch. Recorded verbatim; never judged.",
+                        },
+                    },
+                    required: ["target_checkpoint_id", "reason"],
+                    additionalProperties: false,
                 },
                 evaluation: {
                     type: "object",
-                    description: "Required structured self-evaluation for this round. Free-text or embedded evaluation blocks are not accepted.",
-                    required: ["success", "output_summary", "should_continue", "constraint_violations"],
+                    description: "Structured self-evaluation for this round. Required when recovery is absent. Free-text or embedded evaluation blocks are not accepted.",
+                    required: ["outcome", "output_summary", "should_continue", "constraint_violations"],
                     properties: {
-                        success: {
-                            type: "boolean",
-                            description: fieldGuideDescription("success"),
+                        outcome: {
+                            type: "string",
+                            enum: ["success", "partial", "failed", "blocked"],
+                            description: fieldGuideDescription("outcome"),
                         },
                         output_summary: {
                             type: "string",
@@ -104,10 +185,6 @@ const TOOL_BASE_SCHEMAS = [
                             items: { type: "string" },
                             description: fieldGuideDescription("discovered_constraints"),
                         },
-                        objective_refinement: {
-                            type: "string",
-                            description: fieldGuideDescription("objective_refinement"),
-                        },
                         emerged_subtasks: {
                             type: "array",
                             items: { type: "string" },
@@ -122,38 +199,21 @@ const TOOL_BASE_SCHEMAS = [
                                     items: { type: "string" },
                                     description: fieldGuideDescription("execution_report.files_changed"),
                                 },
-                                tests_reported: {
-                                    type: "object",
-                                    description: fieldGuideDescription("execution_report.tests_reported"),
-                                    properties: {
-                                        passed: { type: "integer", minimum: 0, description: "Number of passing tests." },
-                                        failed: { type: "integer", minimum: 0, description: "Number of failing tests." },
-                                        skipped: { type: "integer", minimum: 0, description: "Number of skipped tests." },
-                                    },
-                                },
-                                criterion_claims: {
+                                claims: {
                                     type: "array",
-                                    description: fieldGuideDescription("execution_report.criterion_claims"),
+                                    maxItems: 100,
+                                    description: fieldGuideDescription("execution_report.claims"),
                                     items: {
                                         type: "object",
                                         properties: {
-                                            criterion_id: { type: "string", description: "cr-XXXXXXXX criterion id (free text allowed)." },
+                                            id: {
+                                                type: "string",
+                                                description: "cr-XXXXXXXX objective criterion id or rci-XXXXXXXX " +
+                                                    "id of an item of the ACTIVE contract.",
+                                            },
                                             outcome: { type: "string", enum: ["met", "remaining"] },
                                         },
-                                        required: ["criterion_id", "outcome"],
-                                        additionalProperties: false,
-                                    },
-                                },
-                                contract_item_claims: {
-                                    type: "array",
-                                    description: fieldGuideDescription("execution_report.contract_item_claims"),
-                                    items: {
-                                        type: "object",
-                                        properties: {
-                                            item_id: { type: "string", description: "rci-XXXXXXXX id of an item of the ACTIVE contract." },
-                                            outcome: { type: "string", enum: ["met", "remaining"], description: "Your claim for that item this round." },
-                                        },
-                                        required: ["item_id", "outcome"],
+                                        required: ["id", "outcome"],
                                         additionalProperties: false,
                                     },
                                 },
@@ -164,22 +224,26 @@ const TOOL_BASE_SCHEMAS = [
                             items: { type: "string" },
                             description: fieldGuideDescription("retracted_constraints"),
                         },
-                        revised_success_criteria: {
-                            type: "array",
-                            description: fieldGuideDescription("revised_success_criteria"),
-                            items: {
-                                type: "object",
-                                properties: {
-                                    old: { type: "string", description: "Original criterion." },
-                                    new: { type: "string", description: "Revised criterion." },
-                                },
-                            },
-                        },
                         wrong_assumptions: {
                             type: "array",
                             items: { type: "string" },
                             description: fieldGuideDescription("wrong_assumptions"),
                         },
+                        open_questions: {
+                            type: "array",
+                            maxItems: 3,
+                            items: { type: "string", maxLength: 300 },
+                            description: fieldGuideDescription("open_questions"),
+                        },
+                        resolved_open_question_ids: {
+                            type: "array",
+                            maxItems: 20,
+                            items: {
+                                type: "string",
+                                pattern: "^oq-[a-f0-9]{12}$",
+                            },
+                            description: fieldGuideDescription("resolved_open_question_ids"),
+                        },
                         worker_results: {
                             type: "array",
                             description: fieldGuideDescription("worker_results"),
@@ -187,28 +251,23 @@ const TOOL_BASE_SCHEMAS = [
                                 type: "object",
                                 properties: {
                                     agentId: { type: "string" },
-                                    subAgentType: { type: "string" },
                                     subTask: { type: "string" },
                                     resultSummary: { type: "string" },
                                     outcome: {
                                         type: "string",
                                         enum: ["success", "partial", "failed"],
                                     },
-                                    discoveredConstraints: {
-                                        type: "array",
-                                        items: { type: "string" },
-                                    },
                                 },
                                 required: ["agentId", "subTask", "resultSummary", "outcome"],
                             },
                         },
-                        compression_checkpoint: {
+                        subtask_boundary: {
                             type: "boolean",
-                            description: fieldGuideDescription("compression_checkpoint"),
+                            description: fieldGuideDescription("subtask_boundary"),
                         },
-                        checkpoint_label: {
+                        subtask_boundary_label: {
                             type: "string",
-                            description: fieldGuideDescription("checkpoint_label"),
+                            description: fieldGuideDescription("subtask_boundary_label"),
                         },
                         subgoal_updates: {
                             type: "array",
@@ -233,22 +292,18 @@ const TOOL_BASE_SCHEMAS = [
                                 required: ["id", "status"],
                             },
                         },
-                        stop_reason: {
-                            type: "string",
-                            enum: ["gave_up", "blocked", "needs_human_input"],
-                            description: fieldGuideDescription("stop_reason"),
-                        },
                         no_change_reason: {
                             type: "string",
                             description: fieldGuideDescription("no_change_reason"),
                         },
-                        outcome: {
+                        objective_refinement: {
                             type: "string",
-                            enum: ["success", "partial", "failed", "blocked"],
-                            description: fieldGuideDescription("outcome"),
+                            maxLength: 1000,
+                            description: fieldGuideDescription("objective_refinement"),
                         },
                         blocker: {
                             type: "string",
+                            maxLength: 500,
                             description: fieldGuideDescription("blocker"),
                         },
                         gate_ids: {
@@ -270,54 +325,53 @@ const TOOL_BASE_SCHEMAS = [
                             },
                             description: fieldGuideDescription("retroactiveClaims"),
                         },
-                        prompt_requests: {
-                            type: "object",
-                            description: fieldGuideDescription("prompt_requests"),
-                            properties: {
-                                emphasize: {
-                                    type: "array",
-                                    items: { type: "string" },
-                                    description: "Constraints, discoveries, or decisions that need emphasis in the next prompt. Each entry is matched against active state items by STABLE ID (c-/cr-/sg-XXXXXXXX) or by exact text after normalization — a paraphrase matches nothing and renders nothing. Matched items appear in a 'Critical Context' section. Max 5 entries. Pure reordering — no token overhead.",
-                                },
-                                confusion_points: {
-                                    type: "array",
-                                    items: { type: "string" },
-                                    description: "Things you're confused about. Rendered at the TOP of the next prompt before the objective. Max 3 entries, each ≤ 200 chars recommended. Be specific — 'I don't understand why milestone 3 is marked complete when phase 2 appears unfinished.'",
-                                },
-                            },
-                        },
                         round_contract: {
                             type: "object",
                             description: fieldGuideDescription("round_contract"),
                             properties: {
                                 work_item: {
                                     type: "string",
-                                    description: "Optional. Round focus, one line. Rendered as the active contract's Current Task first line. Max 200 chars.",
+                                    minLength: 1,
+                                    maxLength: 200,
+                                    description: "Required. The bounded deliverable this contract slice " +
+                                        "produces — an outcome, not an activity. Rendered as the " +
+                                        "Current Task heading. 1–200 chars.",
                                 },
                                 items: {
                                     type: "array",
-                                    description: "Required, at least one (max 20). Each item is a verification unit bound to evidence commands. The runtime derives a stable rci-XXXXXXXX id per item and renders it in the prompt — cite that id in execution_report.contract_item_claims.",
+                                    minItems: 1,
+                                    maxItems: 20,
+                                    description: "Required, at least one (max 20). Each item is an " +
+                                        "acceptance condition for the deliverable, bound to its own " +
+                                        "evidence commands. The runtime derives a stable " +
+                                        "rci-XXXXXXXX id per item and renders it in the prompt — " +
+                                        "cite that id in execution_report.claims.",
                                     items: {
                                         type: "object",
                                         properties: {
                                             description: {
                                                 type: "string",
-                                                description: "What must be true for this item. Max 200 chars.",
+                                                minLength: 1,
+                                                maxLength: 200,
+                                                description: "What must be true for this acceptance condition. " +
+                                                    "1–200 chars.",
                                             },
                                             criterion_refs: {
                                                 type: "array",
+                                                maxItems: 20,
                                                 items: { type: "string" },
                                                 description: "Optional. Real cr-XXXXXXXX ids of ACTIVE criteria rendered in this prompt. Free text and unknown ids are rejected. Max 20.",
                                             },
-                                            subgoal_refs: {
-                                                type: "array",
-                                                items: { type: "string" },
-                                                description: "Optional. sg-XXXXXXXX ids of ACTIVE sub-goals displayed in this prompt. A sub-goal created by this same submission's emerged_subtasks becomes referenceable next round. Max 20 ids. A machine-verified item produces the derived verified-subgoal fact for exactly the ids it names here.",
-                                            },
                                             verify_with: {
                                                 type: "array",
+                                                minItems: 1,
+                                                maxItems: 20,
                                                 items: { type: "string" },
-                                                description: "Required, at least one. Names of configured, enabled, after-capable evidence.commands (loop_policy.json) that verify this item. Unknown or disabled names are rejected.",
+                                                description: "Required, at least one. Names of configured, " +
+                                                    "enabled, after-capable evidence.commands " +
+                                                    "(loop_policy.json) that check this acceptance " +
+                                                    "condition. Unknown or disabled names are rejected. A " +
+                                                    "command may be shared by multiple conditions.",
                                             },
                                         },
                                         required: ["description", "verify_with"],
@@ -326,31 +380,87 @@ const TOOL_BASE_SCHEMAS = [
                                 },
                                 scope: {
                                     type: "array",
+                                    maxItems: 50,
                                     items: { type: "string" },
-                                    description: "Files/directories this round may touch (workspace-relative; './' and trailing slashes accepted; must stay inside the workspace). Out-of-scope git changes trigger round_scope_drift, which is a machine fact and is not waivable by explanation. Max 50 items.",
+                                    description: "Optional, report-only. The files/directories you intend " +
+                                        "this slice to touch. Omission and [] both mean no declared " +
+                                        "intent. It is NOT enforced and is not part of the rc- id: " +
+                                        "out-of-scope changes are reported as an info fact and " +
+                                        "never reject the round. Max 50 items.",
+                                },
+                                supersedes: {
+                                    type: "object",
+                                    description: "Optional redirect modifier. Replaces the named ACTIVE " +
+                                        "contract with this proposal's slice; its acceptance items " +
+                                        "must differ. The old contract closes as superseded. Not " +
+                                        "allowed with should_continue=false or outcome=blocked.",
+                                    properties: {
+                                        contract_id: {
+                                            type: "string",
+                                            pattern: "^rc-[a-f0-9]{8}$",
+                                            description: "The rc-XXXXXXXX id of the ACTIVE contract rendered in " +
+                                                "this prompt. A stale/other id is rejected.",
+                                        },
+                                        reason: {
+                                            type: "string",
+                                            maxLength: 500,
+                                            description: "Optional Agent report, recorded verbatim for audit only.",
+                                        },
+                                    },
+                                    required: ["contract_id"],
+                                    additionalProperties: false,
                                 },
                             },
-                            required: ["items", "scope"],
+                            required: ["work_item", "items"],
+                            additionalProperties: false,
                         },
                     },
                 },
             },
-            required: ["sessionId", "roundId", "evaluation"],
+            required: ["submissionHandle"],
+        },
+    },
+    {
+        name: "loopforge_checkpoint",
+        description: "v3.9.7: Create an explicit mid-round workspace checkpoint (savepoint). " +
+            "The call itself is the Agent's decision that this state is worth " +
+            "restoring to. It creates no round, no commit and no progress; the " +
+            "checkpoint becomes a visible recovery target only through the held " +
+            "transaction's ref list. Requires the same submissionHandle as " +
+            "loopforge_next; the handle is unchanged after a successful checkpoint.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                submissionHandle: SUBMISSION_HANDLE_SCHEMA,
+            },
+            required: ["submissionHandle"],
+            additionalProperties: false,
         },
     },
     {
         name: "loopforge_status",
-        description: "Inspect loop state. view=session (default): session status, round identity, success trajectory and typed projection. view=loop: loop health (goal alignment, constraints, drift). view=all: summary of every persisted loop. view=audit: read-only end-of-loop verification audit (claims, gates, verdict, sequence integrity).",
+        description: "Read-only inspection. view=session (default): live session status, " +
+            "round identity, the current held submissionHandle when one exists, " +
+            "success trajectory, active contract, current guidance and the latest " +
+            "committed receipt. It never returns the held prompt; a paused or " +
+            "stalled session must resume before submitting. view=loop: committed " +
+            "round counts, unverified-item rounds and policy metrics. view=all: " +
+            "summary of every persisted loop. view=audit: end-of-loop verification " +
+            "audit. view=explain: per-round \"why\" view over committed facts.",
         inputSchema: {
             type: "object",
             properties: {
                 sessionId: {
                     type: "string",
-                    description: "Session ID returned by loopforge_start (views session/audit).",
+                    description: "Live session ID returned by loopforge_start or loopforge_resume. " +
+                        "Resolvable only in the current process; after a restart use loopId. " +
+                        "view=session returns the current held submissionHandle.",
                 },
                 loopId: {
                     type: "string",
-                    description: "Loop ID (views loop/audit).",
+                    description: "Durable loop ID. Required for views loop/audit/explain; also " +
+                        "accepted for view=session, which resolves it to the live session " +
+                        "and returns its current held submissionHandle.",
                 },
                 view: {
                     type: "string",
@@ -367,7 +477,8 @@ const TOOL_BASE_SCHEMAS = [
     },
     {
         name: "loopforge_stop",
-        description: "Manually stop a loop session and return its final trajectory.",
+        description: "Manually stop a loop session and return its final trajectory. The " +
+            "returned `success` is tool-call success, not a task-success verdict.",
         inputSchema: {
             type: "object",
             properties: {
@@ -381,7 +492,7 @@ const TOOL_BASE_SCHEMAS = [
     },
     {
         name: "loopforge_pause",
-        description: "Pause a running loop session. The loop suspends at the next round boundary and its state is persisted to vault. Paused loops can be resumed with loopforge_resume. Use this to interrupt a long-running loop without losing progress.",
+        description: "Pause a running loop session: it immediately stops accepting submissions (an in-flight advance may still finish) and its state is persisted to vault. Paused loops can be resumed with loopforge_resume. Use this to interrupt a long-running loop without losing progress.",
         inputSchema: {
             type: "object",
             properties: {
@@ -395,10 +506,12 @@ const TOOL_BASE_SCHEMAS = [
     },
     {
         name: "loopforge_replay",
-        description: "Replay a completed or running loop as an auditable round timeline. " +
-            "Pass sessionId for a live session, or loopId to replay straight from " +
-            "the vault (works after a process restart, when no session is in " +
-            "memory) — the timeline is derived from committed round documents.",
+        description: "Replay committed rounds as an auditable timeline. Pass sessionId for a " +
+            "live session, or loopId to replay straight from the vault (works after " +
+            "a process restart). Returns the last 10 committed rounds by default; " +
+            "pass start/end for an explicit window (at most 50 rounds). Each round " +
+            "carries its context boundary, committed report, assumptions, open " +
+            "questions, blocker and contract redirect. Read-only projection.",
         inputSchema: {
             type: "object",
             properties: {
@@ -411,6 +524,16 @@ const TOOL_BASE_SCHEMAS = [
                     description: "Loop ID to replay from the vault — works without a " +
                         "live session, e.g. after a restart.",
                 },
+                start: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "First round of the explicit window (inclusive).",
+                },
+                end: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "Last round of the explicit window (inclusive).",
+                },
             },
             // v3.3.1: either identifier resolves the timeline; sessionId wins when
             // both are given (it also disambiguates re-used loopIds).
@@ -419,7 +542,20 @@ const TOOL_BASE_SCHEMAS = [
     },
     {
         name: "loopforge_resume",
-        description: "Resume a loop from vault state. Works for both: (a) running sessions that were interrupted by a process restart, and (b) paused sessions (via loopforge_pause). Returns the compiled prompt for the next round, or null with a stopReason if the loop is already complete.",
+        description: "Resume a loop from vault state. Requires the durable loopId returned by " +
+            "loopforge_start (not sessionId). Use this when the held prompt was lost, " +
+            "no live session exists, or the session is paused/stalled; if only the " +
+            "submissionHandle was lost while the prompt is still in context, prefer " +
+            "loopforge_status. Returns the held prompt and its current " +
+            "submissionHandle, or a newly compiled prompt when none is held. A " +
+            "terminal loop returns no prompt, the committed stopReason when one was " +
+            "committed, and/or sessionStatus (paused/stopped/stalled); a stopped " +
+            "loop without a committed stop round reports sessionStatus only. " +
+            "v4.0.5: pass invocationLost=true when the original in-context retry " +
+            "invocation no longer exists; LoopForge recompiles the SAME logical " +
+            "round and attempt as a cold-context invocation_recovery prompt. " +
+            "currentUserInstruction carries the host's current instruction into " +
+            "that recompile or redelivery.",
         inputSchema: {
             type: "object",
             properties: {
@@ -427,6 +563,24 @@ const TOOL_BASE_SCHEMAS = [
                     type: "string",
                     description: "Loop ID to resume. Must have a saved session_state entry from a previous start/run.",
                 },
+                invocationLost: {
+                    type: "boolean",
+                    description: "v4.0.5: set true when the invocation that received the held " +
+                        "same_round_retry prompt is gone. A held retry is then recompiled " +
+                        "as fresh_invocation / invocation_recovery for the SAME round and " +
+                        "attempt (L2, with Machine Evidence, Working Memory and rejection " +
+                        "lessons). On an already clean-context prompt this is an " +
+                        "idempotent no-op.",
+                },
+                currentUserInstruction: {
+                    type: "string",
+                    description: "v4.0.5: the host's current user instruction, trimmed and " +
+                        "non-empty. It is invocation input only; it never rewrites " +
+                        "session.task, the Objective, criteria, constraints or the Round " +
+                        "Contract. An instruction identical (trimmed, case-sensitive) to " +
+                        "the held prompt's is idempotent; a different one recompiles the " +
+                        "same round/attempt with a new handle.",
+                },
             },
             required: ["loopId"],
         },
@@ -442,8 +596,7 @@ const TOOL_BASE_SCHEMAS = [
         inputSchema: {
             type: "object",
             properties: {
-                sessionId: { type: "string", description: "Session ID." },
-                roundId: { type: "string", description: "RoundId from the latest response." },
+                submissionHandle: SUBMISSION_HANDLE_SCHEMA,
                 action: {
                     type: "object",
                     description: "The action the agent plans to perform.",
@@ -480,7 +633,7 @@ const TOOL_BASE_SCHEMAS = [
                     required: ["description", "scope", "effects", "reversibility", "authorization"],
                 },
             },
-            required: ["sessionId", "roundId", "action"],
+            required: ["submissionHandle", "action"],
         },
     },
     {
@@ -519,19 +672,79 @@ const ADVANCE_OUTPUT_SCHEMA = {
     type: "object",
     properties: {
         ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
-        error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
+        error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, submissionHandle?, details? }" },
         details: { type: "object", additionalProperties: true },
         sessionId: { type: "string" },
+        loopId: {
+            type: "string",
+            description: "Durable loop identity. Returned with every held prompt so a restarted " +
+                "agent can call loopforge_resume without reconstructing IDs.",
+        },
         round: { type: "number" },
-        roundId: { type: ["string", "null"] },
+        submissionHandle: SUBMISSION_HANDLE_OUTPUT_SCHEMA,
         prompt: { type: ["string", "null"] },
-        stopReason: { type: ["string", "null"] },
-        stopDetail: { type: ["string", "null"], description: "Human-readable context for why the loop stopped. Provides facts without prescribing a specific agent action." },
+        stopReason: {
+            type: ["string", "null"],
+            enum: [
+                "completed", "failed", "blocked", "cancelled", "max_rounds",
+                "stalled", "enforcement_terminated", "paused", "incomplete", null,
+            ],
+            description: "v4.0.4: LoopForge's terminal reason. Never a session status, a tool " +
+                "error or the Agent's round outcome.",
+        },
+        sessionStatus: {
+            enum: ["running", "stopped", "paused", "stalled"],
+            description: "v4.0.4: the live session status when the result is not a committed " +
+                "loop terminal reason.",
+        },
+        stopDetail: { type: ["string", "null"], description: "Human-readable context for why the loop stopped. Three fact blocks: Agent report, LoopForge decision, Machine evidence. Provides facts without prescribing a specific agent action." },
         level: { type: ["string", "null"] },
-        roundSuccess: { type: ["boolean", "null"] },
-        enforcementAction: { enum: ["accept", "reject", "terminate", "backtrack"] },
+        contextMode: {
+            enum: ["fresh_invocation", "same_round_retry"],
+            description: CONTEXT_MODE_DESCRIPTION,
+        },
+        contextReason: {
+            // v4.0.5: the ONE runtime whitelist; a new reason cannot drift between
+            // the protocol, the decoder and this output schema.
+            enum: [...PROMPT_CONTEXT_REASONS],
+            description: "v4.0.2: why the context boundary was selected.",
+        },
+        agentSuccessClaim: { type: ["boolean", "null"] },
+        agentOutcome: {
+            type: ["string", "null"],
+            enum: ["success", "partial", "failed", "blocked", null],
+            description: "v4.0.6: the Agent-declared round outcome.",
+        },
+        agentShouldContinue: {
+            type: ["boolean", "null"],
+            description: "v4.0.4: the Agent's declared should_continue for that same round.",
+        },
+        checkpoints: {
+            type: ["array", "null"],
+            items: { type: "object", additionalProperties: true },
+            description: "v3.9.7: the held transaction's checkpoint refs (before-image + explicit mid savepoints).",
+        },
+        beforeCheckpointError: {
+            type: ["object", "null"],
+            additionalProperties: true,
+            description: "v3.9.7: explicit machine fact when the automatic before-image could not be captured.",
+        },
+        enforcementAction: { enum: ["accept", "reject", "terminate", "backtrack", "recovery"] },
         enforcementReason: { type: ["string", "null"] },
-        verificationStatus: { enum: ["trusted", "insufficient", "contradicted"] },
+        recovery: {
+            type: ["object", "null"],
+            additionalProperties: true,
+            description: "v3.9.7: committed rollback directive facts and the verified restore that produced the redo prompt.",
+        },
+        evidencePosture: {
+            type: ["object", "null"],
+            additionalProperties: true,
+            description: "v4.0.3: the ONE evidence posture of the round this result is about " +
+                "(status, machineBackedSuccess, verificationConfigured, workspace, " +
+                "files reconciliation, providers, commands, contract snapshot, " +
+                "findings and omitted counts). Accepted rounds carry the persisted " +
+                "posture; a rejection carries its transient copy.",
+        },
         submission_guidance: {
             type: ["object", "null"],
             additionalProperties: true,
@@ -547,11 +760,6 @@ const ADVANCE_OUTPUT_SCHEMA = {
                 "Returned by loopforge_next only.",
         },
         warnings: { type: "array", items: { type: "string" } },
-        projection: {
-            type: "object",
-            additionalProperties: true,
-            description: "v2.12: Typed cognitive state projection (focus/todo/phase/delegation/handoff).",
-        },
     },
     additionalProperties: true,
 };
@@ -559,22 +767,59 @@ const ADVANCE_OUTPUT_SCHEMA = {
  *  validates each handler's output against these before returning it —
  *  a mismatch is a contract bug, surfaced as a JSON-RPC error instead of
  *  silently shipping an output that violates the declared schema. */
+const CHECKPOINT_OUTPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        ok: { type: "boolean" },
+        error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, submissionHandle?, details? }" },
+        sessionId: { type: "string" },
+        submissionHandle: SUBMISSION_HANDLE_SCHEMA,
+        checkpointId: { type: "string" },
+        round: { type: "number" },
+        role: { const: "mid" },
+        redoRound: { type: "number" },
+        createdAt: { type: "number" },
+        head: { type: ["string", "null"] },
+        fileCount: { type: "number" },
+        contentCount: { type: "number" },
+        contentHash: { type: "string" },
+    },
+    additionalProperties: true,
+};
 export const TOOL_OUTPUT_SCHEMAS = {
     loopforge_start: ADVANCE_OUTPUT_SCHEMA,
     loopforge_next: ADVANCE_OUTPUT_SCHEMA,
     loopforge_resume: ADVANCE_OUTPUT_SCHEMA,
+    loopforge_checkpoint: CHECKPOINT_OUTPUT_SCHEMA,
     loopforge_status: {
         type: "object",
         properties: {
             ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
-            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, submissionHandle?, details? }" },
             sessionId: { type: "string" },
             loopId: { type: "string" },
             round: { type: "number" },
-            roundId: { type: ["string", "null"] },
+            submissionHandle: SUBMISSION_HANDLE_OUTPUT_SCHEMA,
+            checkpoints: { type: ["array", "null"], items: { type: "object", additionalProperties: true } },
+            beforeCheckpointError: { type: ["object", "null"], additionalProperties: true },
             maxRounds: { type: "number" },
             status: { enum: ["running", "stopped", "stalled", "paused"] },
-            successTrajectory: { type: "array", items: { type: "boolean" } },
+            // v4.0.4: a stopped loop's committed terminal facts are readable from
+            // view=session without calling resume.
+            loopStopReason: {
+                type: ["string", "null"],
+                enum: [
+                    "completed", "failed", "blocked", "cancelled", "max_rounds",
+                    "stalled", "enforcement_terminated", "paused", "incomplete", null,
+                ],
+            },
+            agentShouldContinue: { type: ["boolean", "null"] },
+            stopDetail: { type: ["string", "null"] },
+            machineBackedSuccessTrajectory: { type: "array", items: { type: "boolean" } },
+            evidencePosture: { type: ["object", "null"], additionalProperties: true },
+            machineBackedSuccess: { type: ["boolean", "null"] },
+            agentSuccessClaim: { type: ["boolean", "null"] },
+            agentOutcome: { type: ["string", "null"] },
             lease: { type: ["object", "null"], additionalProperties: true },
             metrics: { type: "object", additionalProperties: true },
             // v3.5: the ACTIVE Round Contract governing the next round (derived
@@ -592,10 +837,16 @@ export const TOOL_OUTPUT_SCHEMAS = {
         type: "object",
         properties: {
             ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
-            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
-            success: { type: "boolean" },
-            roundsCompleted: { type: "number" },
-            successTrajectory: { type: "array", items: { type: "boolean" } },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, submissionHandle?, details? }" },
+            success: { type: "boolean", description: "Tool-call success, not a task-success verdict." },
+            sessionId: { type: "string" },
+            loopId: { type: "string" },
+            roundsCompleted: { type: "number", description: "Deprecated alias of roundCursor (the session round cursor, not a committed count)." },
+            roundCursor: { type: "number", description: "The session's current round cursor." },
+            sessionStatus: { const: "stopped" },
+            loopStopReason: { const: MANUAL_STOP_REASON, description: "The manual-cancel terminal reason sent to the terminal sink; not a committed round fact." },
+            machineBackedSuccessRounds: { type: "number", description: "Machine-backed successful rounds (same committed-view source as the trajectory)." },
+            machineBackedSuccessTrajectory: { type: "array", items: { type: "boolean" } },
         },
         additionalProperties: true,
     },
@@ -603,7 +854,7 @@ export const TOOL_OUTPUT_SCHEMAS = {
         type: "object",
         properties: {
             ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
-            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, submissionHandle?, details? }" },
             sessionId: { type: "string" },
             round: { type: "number" },
             status: { type: "string" },
@@ -614,10 +865,16 @@ export const TOOL_OUTPUT_SCHEMAS = {
         type: "object",
         properties: {
             ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
-            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, submissionHandle?, details? }" },
             sessionId: { type: "string" },
             loopId: { type: "string" },
             timeline: { type: "array", items: { type: "object", additionalProperties: true } },
+            window: {
+                type: "object",
+                additionalProperties: true,
+                description: "v4.0.2: the returned round window: { start, end, totalRounds, " +
+                    "hasBefore, hasAfter }.",
+            },
             legacyRounds: {
                 type: "array",
                 items: { type: "object", additionalProperties: true },
@@ -631,8 +888,8 @@ export const TOOL_OUTPUT_SCHEMAS = {
         type: "object",
         properties: {
             ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
-            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
-            sessionId: { type: "string" },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, submissionHandle?, details? }" },
+            submissionHandle: SUBMISSION_HANDLE_SCHEMA,
             gateId: { type: "string" },
             risk: { type: "string", enum: ["low", "high", "unknown"] },
             decision: { type: "string", enum: ["agent_allowed", "user_required"] },
@@ -648,7 +905,7 @@ export const TOOL_OUTPUT_SCHEMAS = {
         type: "object",
         properties: {
             ok: { type: "boolean", description: "v3.8: uniform result envelope — false means the error object describes a rejected call." },
-            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, roundId?, details? }" },
+            error: { type: "object", additionalProperties: true, description: "v3.8 ToolError: { code, message, retryable, sessionId?, submissionHandle?, details? }" },
             sessionId: { type: "string" },
             loopId: { type: "string" },
             gateId: { type: "string" },
@@ -673,12 +930,6 @@ function closeObjectSchemas(schema) {
     }
     return result;
 }
-const CORE_EVALUATION_FIELDS = new Set([
-    "success",
-    "output_summary",
-    "constraint_violations",
-    "should_continue",
-]);
 /** Keep the four authoritative fields schema-strict while leaving optional
  * reporting fields available for buildSelfEvaluation's lossy normalization.
  * Their descriptions remain in tools/list, but malformed optional values do
@@ -691,7 +942,7 @@ function prepareInputSchema(name, schema) {
     if (!isRecord(evaluation) || !isRecord(evaluation.properties))
         return result;
     evaluation.properties = Object.fromEntries(Object.entries(evaluation.properties).map(([field, value]) => {
-        if (CORE_EVALUATION_FIELDS.has(field) || !isRecord(value))
+        if (CORE_SELF_EVALUATION_FIELDS.has(field) || !isRecord(value))
             return [field, value];
         return [field, typeof value.description === "string"
                 ? { description: value.description }
@@ -814,7 +1065,7 @@ export function validateToolDispatchInput(name, input) {
         : {};
     validateSchema(input, {
         ...contract.inputSchema,
-        required: ["sessionId", "roundId"],
+        required: ["submissionHandle"],
         properties: { ...properties, evaluation: {} },
     }, "arguments");
     if (!isRecord(input.evaluation))
@@ -855,13 +1106,51 @@ function projectionErrorResult(error) {
     }
     return null;
 }
+/** Stable state-integrity errors. They are never retryable with the same
+ *  payload: the loop data or the operator surface must be repaired first. */
+function stateErrorResult(error) {
+    if (error instanceof LegacyHistoryError) {
+        return {
+            error: error.code,
+            errorMessage: error.message,
+            details: { loopId: error.loopId, rounds: error.rounds },
+        };
+    }
+    if (error instanceof OperatorAcceptanceConflictError) {
+        return {
+            error: error.code,
+            errorMessage: error.message,
+            details: { loopId: error.loopId },
+        };
+    }
+    return null;
+}
 export const TOOL_HANDLERS = {
     async loopforge_start(mgr, input) {
+        // A removed or misspelled start argument must not disappear silently: the
+        // schema is permissive about extra top-level keys, and the handler used to
+        // rebuild StartInput from a whitelist. Without this guard a stale manual
+        // (for example one still naming `domain`) produces a successful start with
+        // part of the caller's intent ignored.
+        const unknownStartArgs = Object.keys(input).filter((key) => !START_INPUT_KEYS.includes(key));
+        if (unknownStartArgs.length > 0) {
+            const retired = unknownStartArgs.includes("domain")
+                ? " `domain` was removed in 4.0.1."
+                : "";
+            return {
+                error: "invalid_argument",
+                errorMessage: `unknown loopforge_start argument(s): ${unknownStartArgs.join(", ")}.` +
+                    `${retired} Accepted: ${START_INPUT_KEYS.join(", ")}.`,
+                details: {
+                    unknown: unknownStartArgs,
+                    accepted: [...START_INPUT_KEYS],
+                },
+            };
+        }
         const startInput = {
             task: String(input.task ?? ""),
             loopId: input.loopId,
             maxRounds: typeof input.maxRounds === "number" ? input.maxRounds : undefined,
-            domain: input.domain,
             planSource: input.planSource,
             constraints: Array.isArray(input.constraints)
                 ? input.constraints
@@ -920,20 +1209,34 @@ export const TOOL_HANDLERS = {
             const projectionFailure = projectionErrorResult(error);
             if (projectionFailure)
                 return projectionFailure;
+            const stateFailure = stateErrorResult(error);
+            if (stateFailure)
+                return stateFailure;
+            if (error instanceof LoopExistsError) {
+                return {
+                    error: error.code,
+                    errorMessage: error.message,
+                    details: { loopId: error.loopId, reason: error.reason },
+                };
+            }
+            if (error instanceof StartFailureError) {
+                return {
+                    error: error.code,
+                    errorMessage: error.message,
+                    details: { retry: "call loopforge_start again" },
+                };
+            }
+            if (error instanceof SessionLeaseConflictError) {
+                return {
+                    error: "lease_conflict",
+                    errorMessage: `loop "${error.loopId}" is owned by another running LoopForge process`,
+                };
+            }
             return {
                 error: "policy_invalid",
                 errorMessage: `the runtime policy could not be loaded: ${error.message}`,
             };
         }
-        // v2.14: a same-process duplicate loopId surfaces as a clean argument
-        // error instead of a prompt-less "success" the client cannot act on.
-        if (typeof result.stopReason === "string" &&
-            result.stopReason.startsWith("loop_already_running:")) {
-            return {
-                error: "loop_already_running",
-                errorMessage: result.stopDetail ?? "loop already running",
-            };
-        }
         // v3.8: the static capability warning — a loop with no provider or no
         // enabled command can still run; its success claims are recorded as
         // insufficient instead of verified, and the agent is told so up front.
@@ -943,57 +1246,86 @@ export const TOOL_HANDLERS = {
             : { ...result };
     },
     async loopforge_next(mgr, input) {
-        const sessionId = String(input.sessionId ?? "");
         const output = String(input.output ?? "");
         const rawEval = input.evaluation;
-        const roundId = input.roundId === undefined ? undefined : String(input.roundId);
-        if (!sessionId) {
-            return { error: "invalid_argument", errorMessage: "sessionId is required" };
-        }
-        // v3.0.1: every submission is anchored to the round it reports on. A
-        // missing roundId would silently re-process a stale submission against a
-        // later round — reject it here so the contract is enforced even when the
-        // handler is invoked directly (bypassing schema validation).
-        if (!roundId || !roundId.trim()) {
+        const rawRecovery = input.recovery;
+        const handle = input.submissionHandle;
+        const rawInstruction = input.currentUserInstruction;
+        if (rawRecovery !== undefined && rawEval !== undefined) {
             return {
-                error: "round_id_required",
-                errorMessage: "roundId is required — pass the roundId from the most recent " +
-                    "loopforge_start / loopforge_next / loopforge_resume / loopforge_status response",
+                error: "recovery_invalid",
+                errorMessage: "evaluation and recovery are mutually exclusive",
             };
         }
-        // v3.8.1: the submission boundary belongs to the RUNTIME, not to this
-        // transport. `mgr.advance` applies all of it — object shape, core fields,
-        // subgoal_updates structure and references, and the strict Round Contract
-        // declaration/claims boundary — before touching any state, and reports a
-        // refusal through `submissionError`. This handler only maps that onto the
-        // tool envelope, so a non-MCP caller gets exactly the same strictness.
+        // v4.0.0: the handle is the only identity. The runtime validates its
+        // shape, resolves the session, checks the exact held attempt, then runs
+        // the payload boundary — all before its queue/lease heartbeat. This
+        // handler only maps the refusal onto the tool envelope.
+        // v4.0.5: handle + instruction alone is the instruction-recompile mode:
+        // no submission and no round/attempt advance.
         let result;
         try {
-            result = await mgr.advance(sessionId, output, rawEval, roundId);
+            if (rawRecovery !== undefined) {
+                result = await mgr.recover(handle, rawRecovery, rawInstruction !== undefined
+                    ? { currentUserInstruction: String(rawInstruction) }
+                    : undefined);
+            }
+            else if (rawEval !== undefined) {
+                result = await mgr.advance(handle, output, rawEval, rawInstruction !== undefined
+                    ? { currentUserInstruction: String(rawInstruction) }
+                    : undefined);
+            }
+            else if (rawInstruction !== undefined) {
+                result = await mgr.recompileHeld(handle, String(rawInstruction));
+            }
+            else {
+                result = await mgr.advance(handle, output, rawEval);
+            }
         }
         catch (error) {
+            if (error instanceof InvocationInputError) {
+                return { error: "invalid_argument", errorMessage: error.message };
+            }
             const projectionFailure = projectionErrorResult(error);
             if (projectionFailure)
                 return projectionFailure;
+            const stateFailure = stateErrorResult(error);
+            if (stateFailure)
+                return stateFailure;
             throw error;
         }
+        const loopId = result.sessionId
+            ? mgr.get(result.sessionId)?.loopId
+            : undefined;
         if (result.submissionError) {
             return {
                 error: result.submissionError.code,
-                errorMessage: result.stopDetail ?? "the submission was rejected",
+                errorMessage: result.stopDetail ??
+                    (rawRecovery !== undefined
+                        ? "the recovery request was rejected"
+                        : "the submission was rejected"),
                 details: result.submissionError.details,
-                sessionId,
-                roundId,
+                ...(result.sessionId ? { sessionId: result.sessionId } : {}),
+                ...(loopId ? { loopId } : {}),
+                ...(result.submissionHandle ? { submissionHandle: result.submissionHandle } : {}),
             };
         }
-        // v2.12: Typed projection — runtime facts for the main agent, attached
-        // on every accepted/continued round (not on errors).
-        let projection = null;
-        if (result.enforcementAction !== "reject" && result.enforcementAction !== "terminate" &&
-            result.stopReason !== "session_not_found" && result.stopReason !== "stalled") {
-            projection = mgr.getProjection(sessionId);
+        return { ...result, ...(loopId ? { loopId } : {}) };
+    },
+    async loopforge_checkpoint(mgr, input) {
+        const result = await mgr.checkpoint(input.submissionHandle);
+        if (result.error) {
+            return {
+                error: String(result.error),
+                errorMessage: String(result.errorMessage ?? "the checkpoint was rejected"),
+                details: result.details,
+                ...(typeof result.sessionId === "string" ? { sessionId: result.sessionId } : {}),
+                ...(isRecord(result.submissionHandle)
+                    ? { submissionHandle: result.submissionHandle }
+                    : {}),
+            };
         }
-        return projection ? { ...result, projection } : { ...result };
+        return { ok: true, ...result };
     },
     async loopforge_status(mgr, input) {
         const view = input.view === "loop" || input.view === "all" ||
@@ -1043,52 +1375,125 @@ export const TOOL_HANDLERS = {
                 errorMessage: `no health data for loop "${loopId}"`,
             };
         }
-        if (!sessionId) {
+        if (!sessionId && !loopId) {
             return {
                 error: "invalid_argument",
-                errorMessage: "sessionId is required for view=session",
+                errorMessage: "sessionId or loopId is required for view=session",
             };
         }
-        const session = mgr.get(sessionId);
+        // sessionId is a live-process key; loopId is the durable identity. Prefer
+        // a live sessionId, then fall back to loopId so a model that kept only the
+        // durable key can still read session state in the same process. A stale
+        // sessionId after a restart resolves through loopId when both are present.
+        const session = (sessionId ? mgr.get(sessionId) : undefined) ??
+            (loopId ? mgr.getByLoopId(loopId) : undefined);
         if (!session) {
+            // v4.0.4: a persisted STOPPED loop has no live session, but its
+            // committed terminal facts are still readable. This is a projection of
+            // committed history — no lease, no session save, no resume side effect.
+            // A running/paused/stalled loop with no live session still goes through
+            // resume; "no live session" is never treated as "stopped".
+            if (loopId) {
+                let stopped = null;
+                try {
+                    stopped = mgr.getStoppedLoopSummary(loopId);
+                }
+                catch (error) {
+                    const stateFailure = stateErrorResult(error);
+                    if (stateFailure)
+                        return stateFailure;
+                    throw error;
+                }
+                if (stopped) {
+                    return {
+                        ok: true,
+                        loopId,
+                        round: stopped.round,
+                        status: stopped.sessionStatus ?? "stopped",
+                        loopStopReason: stopped.stopReason ?? null,
+                        agentSuccessClaim: stopped.agentSuccessClaim ?? null,
+                        agentOutcome: stopped.agentOutcome ?? null,
+                        agentShouldContinue: stopped.agentShouldContinue ?? null,
+                        stopDetail: stopped.stopDetail ?? null,
+                        last_submission: stopped.submission_receipt ?? null,
+                    };
+                }
+            }
             return {
                 error: "session_not_found",
-                errorMessage: `session not found: ${sessionId} (process restarted?) — pass loopId for view=audit/loop, or loopforge_resume`,
-                sessionId,
+                errorMessage: sessionId
+                    ? `session not found: ${sessionId} (process restarted?) — 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`
+                    : `no live session for loop "${loopId}" — call loopforge_resume with this loopId`,
+                ...(sessionId ? { sessionId } : {}),
+                ...(loopId ? { loopId } : {}),
+                details: {
+                    next: "loopforge_resume",
+                    ...(loopId ? { loopId } : {}),
+                },
             };
         }
-        const metrics = session.engine.getMetrics();
+        // Every live-session-derived projection must use the resolved session's
+        // identity. The caller's raw sessionId is empty on a loopId-only query and
+        // may be stale when the loopId fallback resolved the session; using it here
+        // silently nulled the handle/contract/guidance and forced a full resume.
+        const liveSessionId = session.sessionId;
+        const policyMetricsView = mgr.getPolicyMetrics(session.loopId);
+        // v4.0.3: a live held prompt has no result yet; the last committed
+        // receipt is the correct current machine posture then.
+        const lastReceipt = mgr.getLastSubmissionReceiptByLoopId(session.loopId);
+        const posture = session.roundSnapshot?.result?.evidencePosture ??
+            lastReceipt?.verification.evidence_posture ??
+            null;
         return {
-            sessionId: session.sessionId,
+            sessionId: liveSessionId,
             loopId: session.loopId,
             round: session.currentRound,
-            roundId: session.roundSnapshot?.roundId ?? null,
+            submissionHandle: mgr.getSubmissionHandle(liveSessionId),
+            checkpoints: session.roundSnapshot
+                ? [
+                    ...(session.roundSnapshot.beforeCheckpoint
+                        ? [session.roundSnapshot.beforeCheckpoint]
+                        : []),
+                    ...(session.roundSnapshot.checkpoints ?? []),
+                ]
+                : [],
+            beforeCheckpointError: session.roundSnapshot?.beforeCheckpointError ?? null,
             maxRounds: session.maxRounds,
             status: session.status,
-            successTrajectory: session.successTrajectory,
+            evidencePosture: posture,
+            // v4.0.4: no committed/held posture is null (unknown), not false.
+            machineBackedSuccess: posture?.machineBackedSuccess ?? null,
+            agentSuccessClaim: session.roundSnapshot?.result?.agentSuccessClaim ??
+                lastReceipt?.agent_success_claim ?? null,
+            agentOutcome: session.roundSnapshot?.result?.agentOutcome ??
+                lastReceipt?.agent_outcome ?? null,
+            machineBackedSuccessTrajectory: mgr.getMachineBackedSuccessTrajectory(session.loopId),
             lease: mgr.getLeaseStatus(session.loopId),
             // v3.5: derived ACTIVE Round Contract (display-only — the compile and
             // verification gates derive the same value from the same committed
             // evals via the shared round-contract walker).
-            activeContract: mgr.getActiveContract(sessionId),
+            activeContract: mgr.getActiveContract(liveSessionId),
             // v3.9.1: current-fact submission guidance for the held round. Same
             // derivation as start/next/resume; read-only and never persisted.
-            submission_guidance: mgr.getSubmissionGuidance(sessionId),
-            last_submission: mgr.getLastSubmissionReceipt(sessionId),
+            submission_guidance: mgr.getSubmissionGuidance(liveSessionId),
+            last_submission: lastReceipt,
+            last_rollback: mgr.replayRollbacks(session.loopId).at(-1) ?? null,
             // v3.8: the ONE capability fact — the static half the compile hashes
             // (what verification is possible) plus the live half rendered from the
             // last baseline. `available` is provider-registry state: reported here
             // and by `doctor`, never hashed.
-            capability: deriveEvidenceCapability(getPolicy(), session.evidenceBaseline ?? []),
-            projection: mgr.getProjection(sessionId),
+            capability: deriveEvidenceCapability(getPolicy(), session.roundSnapshot?.beforeEvidence ?? []),
             metrics: {
-                vaultWriteErrors: metrics.vaultWriteErrors,
-                // v3.3.1: engine sessionStart was written but never read — surface it
-                // so a status view shows how long this engine session has been alive
-                // (observability design: the runtime is the loop's watchdog).
-                startedAt: metrics.sessionStart,
-                sessionAgeSeconds: Math.max(0, Math.floor((Date.now() - metrics.sessionStart) / 1000)),
-                policy: mgr.getPolicyMetrics(session.loopId),
+                // The vault write counters live in the shared policy metrics now;
+                // the engine no longer owns a second copy.
+                vaultWriteErrors: policyMetricsView.vaultWriteErrors,
+                startedAt: session.createdAt,
+                sessionAgeSeconds: Math.max(0, Math.floor((Date.now() - session.createdAt) / 1000)),
+                policy: policyMetricsView,
             },
         };
     },
@@ -1105,10 +1510,27 @@ export const TOOL_HANDLERS = {
                 sessionId,
             };
         }
-        const roundsCompleted = session.currentRound;
-        const successTrajectory = [...session.successTrajectory];
+        const loopId = session.loopId;
+        const roundCursor = session.currentRound;
+        const roundsCompleted = roundCursor;
+        const machineBackedSuccessTrajectory = mgr.getMachineBackedSuccessTrajectory(loopId);
         mgr.delete(sessionId);
-        return { success: true, roundsCompleted, successTrajectory };
+        // v4.0.4: make the stop response self-describing. `cancelled` is the
+        // terminal reason the terminal sink just received; it is NOT persisted as
+        // a committed round fact, so resume/status still report "no committed
+        // terminal reason" after a restart. `success` remains tool-call success.
+        return {
+            ok: true,
+            success: true,
+            sessionId,
+            loopId,
+            roundsCompleted,
+            roundCursor,
+            sessionStatus: "stopped",
+            loopStopReason: MANUAL_STOP_REASON,
+            machineBackedSuccessRounds: machineBackedSuccessTrajectory.length,
+            machineBackedSuccessTrajectory,
+        };
     },
     async loopforge_pause(mgr, input) {
         const sessionId = String(input.sessionId ?? "");
@@ -1128,16 +1550,46 @@ export const TOOL_HANDLERS = {
                     "after a restart (no live session)",
             };
         }
+        // v4.0.2: an explicit window is validated at the tool boundary. The
+        // backend owns the rule; the boundary only converts the type.
+        const windowOptions = {};
+        for (const name of ["start", "end"]) {
+            const value = input[name];
+            if (value === undefined)
+                continue;
+            if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+                return {
+                    error: "invalid_argument",
+                    errorMessage: `${name} must be a positive integer`,
+                };
+            }
+            windowOptions[name] = value;
+        }
+        const pageFor = (resolvePage) => {
+            try {
+                return resolvePage();
+            }
+            catch (error) {
+                if (error instanceof ReplayWindowError) {
+                    return { error: "invalid_argument", errorMessage: error.message };
+                }
+                throw error;
+            }
+        };
         // Live session first: it disambiguates re-used loopIds and the session
         // registry is the cheapest lookup.
         if (sessionId) {
             const session = mgr.get(sessionId);
             if (session) {
-                const timeline = mgr.replayTimeline(sessionId) ?? [];
+                const page = pageFor(() => mgr.replayPage(sessionId, windowOptions));
+                if ("error" in page)
+                    return page;
                 return {
                     sessionId,
                     loopId: session.loopId,
-                    timeline,
+                    timeline: page.timeline,
+                    window: page.window,
+                    rollbacks: mgr.replayRollbacks(session.loopId),
                     legacyRounds: mgr.replayLegacyRounds(session.loopId),
                 };
             }
@@ -1154,8 +1606,10 @@ export const TOOL_HANDLERS = {
         }
         // Vault-direct replay — the timeline lives in the committed round
         // documents, not in the session registry.
-        const timeline = mgr.replayByLoop(loopId);
-        if (!timeline) {
+        const page = pageFor(() => mgr.replayPageByLoop(loopId, windowOptions));
+        if ("error" in page)
+            return page;
+        if (page.window.totalRounds === 0 && page.timeline.length === 0) {
             return {
                 error: "state_unavailable",
                 errorMessage: `no committed rounds found for loop "${loopId}"`,
@@ -1165,7 +1619,9 @@ export const TOOL_HANDLERS = {
         return {
             ...(sessionId ? { sessionId } : {}),
             loopId,
-            timeline,
+            timeline: page.timeline,
+            window: page.window,
+            rollbacks: mgr.replayRollbacks(loopId),
             legacyRounds: mgr.replayLegacyRounds(loopId),
         };
     },
@@ -1183,48 +1639,57 @@ export const TOOL_HANDLERS = {
                 errorMessage: `invalid loopId: ${error.message}`,
             };
         }
+        const inputs = {
+            ...(input.invocationLost === true ? { invocationLost: true } : {}),
+            ...(input.currentUserInstruction !== undefined
+                ? { currentUserInstruction: String(input.currentUserInstruction) }
+                : {}),
+        };
         // Paused recovery must run first so the persisted status is atomically
         // changed back to running before a prompt is returned.
         let result;
         try {
-            result = await mgr.unpause(loopId);
+            result = await mgr.unpause(loopId, inputs);
             if (!result) {
-                result = await mgr.resume(loopId);
+                result = await mgr.resume(loopId, inputs);
             }
         }
         catch (error) {
+            if (error instanceof InvocationInputError) {
+                return { error: "invalid_argument", errorMessage: error.message };
+            }
+            if (error instanceof SessionLeaseConflictError) {
+                return {
+                    error: "lease_conflict",
+                    errorMessage: `loop "${error.loopId}" is owned by another running LoopForge process`,
+                    details: { reason_code: "lease_conflict" },
+                    loopId,
+                };
+            }
             const projectionFailure = projectionErrorResult(error);
             if (projectionFailure)
                 return projectionFailure;
+            const stateFailure = stateErrorResult(error);
+            if (stateFailure)
+                return stateFailure;
             throw error;
         }
         if (!result) {
             return {
                 error: "state_unavailable",
                 errorMessage: `no saved session found for loop "${loopId}"`,
+                loopId,
             };
         }
-        return { ...result };
+        return { ...result, loopId };
     },
     async loopforge_gate_check(mgr, input) {
         // v3.7.1: hidden when disabled — direct calls get a stable error.
         if (!getPolicy().gate.enabled)
             return { error: "gate_disabled" };
-        const sessionId = String(input.sessionId ?? "");
-        const roundId = String(input.roundId ?? "");
         const action = input.action;
-        if (!sessionId) {
-            return { error: "invalid_argument", errorMessage: "sessionId is required" };
-        }
-        if (!roundId) {
-            return {
-                error: "round_id_required",
-                errorMessage: "roundId is required — pass the roundId from the latest response",
-                sessionId,
-            };
-        }
         if (!action || !isRecord(action)) {
-            return { error: "invalid_argument", errorMessage: "action is required", sessionId, roundId };
+            return { error: "invalid_argument", errorMessage: "action is required" };
         }
         const descriptor = {
             description: String(action.description ?? ""),
@@ -1248,11 +1713,9 @@ export const TOOL_HANDLERS = {
             return {
                 error: "invalid_argument",
                 errorMessage: "action.description is required",
-                sessionId,
-                roundId,
             };
         }
-        return mgr.checkGate(sessionId, roundId, descriptor);
+        return mgr.checkGate(input.submissionHandle, descriptor);
     },
     async loopforge_gate_resolve(mgr, input) {
         // v3.7.1: hidden when disabled — direct calls get a stable error.