@riddledc/riddle-proof 0.5.44 → 0.5.46

package/dist/engine-harness.cjs

@@ -2971,201 +2971,18 @@ function createRunResult(input) {
     checkpoint_summary: state.checkpoint_summary,
     state_paths: state.state_paths,
     proof_contract: state.proof_contract,
+    run_card: state.run_card,
     proof_session: state.proof_session,
     evidence_bundle: input.evidence_bundle,
     raw: input.raw
   });
 }
 
-// src/state.ts
-var RIDDLE_PROOF_RUN_STATE_VERSION = "riddle-proof.run-state.v1";
-function timestamp() {
-  return (/* @__PURE__ */ new Date()).toISOString();
-}
-function createRunId(createdAt) {
-  const stamp = createdAt.replace(/\D/g, "").slice(0, 14) || "unknown";
-  const entropy = Math.random().toString(36).slice(2, 8) || "run";
-  return `rp_${stamp}_${entropy}`;
-}
-function elapsedMs(start, end) {
-  const startMs = start ? Date.parse(start) : NaN;
-  const endMs = end ? Date.parse(end) : NaN;
-  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return void 0;
-  return Math.max(0, endMs - startMs);
-}
-function normalizeIntegrationContext(input, fallbackSource) {
-  const value = recordValue(input);
-  if (!value) {
-    return fallbackSource ? { source: fallbackSource } : void 0;
-  }
-  const metadata = recordValue(value.metadata);
-  return compactRecord({
-    source: nonEmptyString(value.source) || fallbackSource,
-    channel_id: nonEmptyString(value.channel_id),
-    thread_id: nonEmptyString(value.thread_id),
-    message_id: nonEmptyString(value.message_id),
-    source_url: nonEmptyString(value.source_url),
-    metadata: metadata && Object.keys(metadata).length ? metadata : void 0
-  });
-}
-function normalizeRunParams(input) {
-  return compactRecord({
-    repo: input.repo,
-    branch: input.branch,
-    change_request: input.change_request,
-    commit_message: input.commit_message,
-    prod_url: input.prod_url,
-    capture_script: input.capture_script,
-    success_criteria: input.success_criteria,
-    assertions: input.assertions,
-    verification_mode: input.verification_mode,
-    resume_session: input.resume_session,
-    target_image_url: input.target_image_url,
-    target_image_hash: input.target_image_hash,
-    viewport_matrix: input.viewport_matrix,
-    deterministic_setup: input.deterministic_setup,
-    reference: input.reference,
-    base_branch: input.base_branch,
-    before_ref: input.before_ref,
-    allow_static_preview_fallback: input.allow_static_preview_fallback,
-    context: input.context,
-    reviewer: input.reviewer,
-    mode: input.mode,
-    build_command: input.build_command,
-    build_output: input.build_output,
-    server_image: input.server_image,
-    server_command: input.server_command,
-    server_port: input.server_port,
-    server_path: input.server_path,
-    use_auth: input.use_auth,
-    auth_localStorage_json: input.auth_localStorage_json,
-    auth_cookies_json: input.auth_cookies_json,
-    auth_headers_json: input.auth_headers_json,
-    color_scheme: input.color_scheme,
-    wait_for_selector: input.wait_for_selector,
-    ship_mode: input.ship_mode,
-    leave_draft: input.leave_draft,
-    engine_state_path: input.engine_state_path,
-    harness_state_path: input.harness_state_path,
-    max_iterations: input.max_iterations,
-    auto_approve: input.auto_approve,
-    dry_run: input.dry_run,
-    integration_context: normalizeIntegrationContext(input.integration_context)
-  });
-}
-function createRunState(input) {
-  const createdAt = input.created_at || timestamp();
-  return compactRecord({
-    version: RIDDLE_PROOF_RUN_STATE_VERSION,
-    run_id: input.run_id || createRunId(createdAt),
-    state_path: input.state_path,
-    worktree_path: input.worktree_path,
-    branch: input.branch || input.request.branch,
-    current_stage: input.current_stage ?? null,
-    stage_started_at: input.stage_started_at ?? null,
-    status: input.status || "running",
-    created_at: createdAt,
-    updated_at: input.updated_at || createdAt,
-    request: normalizeRunParams(input.request),
-    iterations: input.iterations ?? 0,
-    last_checkpoint: input.last_checkpoint ?? null,
-    checkpoint_packet: input.checkpoint_packet,
-    checkpoint_summary: input.checkpoint_summary,
-    state_paths: input.state_paths,
-    proof_contract: input.proof_contract,
-    checkpoint_history: input.checkpoint_history,
-    events: input.events ? [...input.events] : []
-  });
-}
-function appendRunEvent(state, input) {
-  const event = {
-    ts: input.ts || timestamp(),
-    kind: input.kind,
-    checkpoint: input.checkpoint,
-    stage: input.stage,
-    summary: input.summary,
-    details: input.details
-  };
-  state.events.push(compactRecord({
-    ts: event.ts,
-    kind: event.kind,
-    checkpoint: event.checkpoint,
-    stage: event.stage,
-    summary: event.summary,
-    details: event.details
-  }));
-  if (input.checkpoint !== void 0) state.last_checkpoint = input.checkpoint;
-  if (input.stage !== void 0) {
-    if (state.current_stage !== input.stage) state.stage_started_at = event.ts;
-    state.current_stage = input.stage;
-  }
-  state.updated_at = event.ts;
-  return state;
-}
-function appendStageHeartbeat(state, input) {
-  const at = input.ts || timestamp();
-  return appendRunEvent(state, {
-    ts: at,
-    kind: "stage.heartbeat",
-    checkpoint: input.checkpoint || `${input.stage}_heartbeat`,
-    stage: input.stage,
-    summary: input.summary || `${input.stage} stage is active.`,
-    details: compactRecord({
-      elapsed_ms: elapsedMs(state.created_at, at),
-      stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
-      wait_reason: input.wait_reason,
-      blocker: input.blocker,
-      ...input.details
-    })
-  });
-}
-function createRunStatusSnapshot(state, at = timestamp()) {
-  const latestEvent = state.events[state.events.length - 1];
-  const runId = state.run_id || "unknown";
-  return compactRecord({
-    run_id: runId,
-    status: state.status,
-    is_terminal: isTerminalStatus(state.status),
-    monitor_should_continue: !isTerminalStatus(state.status),
-    current_stage: state.current_stage ?? null,
-    state_path: state.state_path ?? null,
-    worktree_path: state.worktree_path ?? null,
-    branch: state.branch ?? null,
-    pr_url: state.pr_url ?? null,
-    pr_branch: state.pr_branch ?? null,
-    pr_state: state.pr_state,
-    ci_status: state.ci_status,
-    ship_commit: state.ship_commit,
-    ship_remote_head: state.ship_remote_head,
-    merge_commit: state.merge_commit,
-    merged_at: state.merged_at,
-    proof_comment_url: state.proof_comment_url,
-    cleanup_report: state.cleanup_report,
-    iterations: state.iterations,
-    last_checkpoint: state.last_checkpoint ?? null,
-    updated_at: state.updated_at,
-    elapsed_ms: elapsedMs(state.created_at, at),
-    stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
-    blocker: state.blocker,
-    checkpoint_packet: state.checkpoint_packet,
-    checkpoint_summary: state.checkpoint_summary,
-    state_paths: state.state_paths,
-    proof_contract: state.proof_contract,
-    latest_event: latestEvent
-  });
-}
-function setRunStatus(state, status, at = timestamp()) {
-  state.status = status;
-  state.ok = status !== "blocked" && status !== "failed";
-  state.updated_at = at;
-  return state;
-}
-
 // src/checkpoint.ts
 var import_node_crypto = __toESM(require("crypto"), 1);
 var RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION = "riddle-proof.checkpoint.v1";
 var RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION = "riddle-proof.checkpoint_response.v1";
-function timestamp2() {
+function timestamp() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 function jsonCloneRecord(value) {
@@ -3238,59 +3055,296 @@ function responseSchemaForAuthorPacket() {
     }
   };
 }
-function resumeTokenFor(input) {
-  const hash = import_node_crypto.default.createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 24);
-  return `rpchk_${hash}`;
-}
-function artifactsFromState(state) {
-  const artifacts = [];
-  for (const role of ["before", "prod", "after"]) {
-    const url = nonEmptyString(state?.[`${role}_cdn`]);
-    if (url) artifacts.push({ role, url, name: `${role}.png`, mime_type: "image/png" });
-  }
-  const authorRequest = recordValue(state?.author_request);
-  const latestAttempt = recordValue(authorRequest?.latest_attempt);
-  const observations = recordValue(latestAttempt?.observations);
-  for (const [label, observation] of Object.entries(observations || {})) {
-    const record = recordValue(observation);
-    const url = nonEmptyString(record?.url);
-    if (url && !artifacts.some((artifact) => artifact.url === url)) {
-      artifacts.push({
-        role: label === "before" || label === "prod" ? label : "json",
-        url,
-        name: `${label}-observation`,
-        summary: compactText(record?.reason, 240)
-      });
+function responseSchemaForProofAssessmentPacket() {
+  return {
+    type: "object",
+    required: ["version", "run_id", "checkpoint", "decision", "summary", "created_at"],
+    additionalProperties: false,
+    properties: {
+      version: { const: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION },
+      run_id: { type: "string" },
+      checkpoint: { type: "string" },
+      resume_token: { type: "string" },
+      decision: {
+        type: "string",
+        enum: [
+          "ready_to_ship",
+          "needs_richer_proof",
+          "revise_capture",
+          "needs_recon",
+          "needs_implementation",
+          "blocked",
+          "human_review"
+        ]
+      },
+      summary: { type: "string" },
+      payload: {
+        type: "object",
+        description: "Optional structured assessment details, including recommended_stage, continue_with_stage, visual_delta notes, or blocker diagnostics."
+      },
+      reasons: { type: "array", items: { type: "string" } },
+      continue_with_stage: { type: "string", enum: ["ship", "author", "implement", "recon", "verify"] },
+      source: {
+        type: "object",
+        properties: {
+          kind: { type: "string" },
+          session_id: { type: "string" },
+          user_id: { type: "string" }
+        }
+      },
+      created_at: { type: "string" }
     }
-  }
-  return artifacts.slice(0, 16);
+  };
 }
-function buildAuthorCheckpointPacket(input) {
-  const checkpoint = nonEmptyString(input.engineResult.checkpoint) || "author_supervisor_judgment";
-  const stage = "author";
-  const runId = input.runState.run_id || "unknown";
-  const fullState = input.fullRiddleState || {};
-  const decisionDetails = recordValue(input.engineResult.decisionRequest?.details);
-  const authorRequest = recordValue(fullState.author_request) || recordValue(fullState.proof_plan_request) || recordValue(decisionDetails?.authorRequest) || {};
-  const fallbackDefaults = recordValue(authorRequest.fallback_defaults) || {};
-  const reconResults = recordValue(fullState.recon_results);
-  const checkpointContract = recordValue(input.engineResult.checkpointContract);
-  const summary = nonEmptyString(input.engineResult.summary) || nonEmptyString(fullState.author_summary) || "Author checkpoint needs a supervising proof packet.";
+function responseSchemaForReconPacket() {
   return {
-    version: RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
-    run_id: runId,
-    state_path: input.runState.state_path,
-    stage,
-    checkpoint,
-    kind: "author_proof",
-    summary,
-    question: "Author the proof packet for this Riddle Proof run. Return a CheckpointResponse with decision=author_packet and payload containing proof_plan and capture_script.",
-    change_request: input.request.change_request || nonEmptyString(fullState.change_request) || "",
-    context: input.request.context,
-    artifacts: artifactsFromState(fullState),
-    state_excerpt: compactRecord({
-      repo: input.request.repo || fullState.repo,
-      branch: input.request.branch || fullState.branch,
+    type: "object",
+    required: ["version", "run_id", "checkpoint", "decision", "summary", "created_at"],
+    additionalProperties: false,
+    properties: {
+      version: { const: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION },
+      run_id: { type: "string" },
+      checkpoint: { type: "string" },
+      resume_token: { type: "string" },
+      decision: {
+        type: "string",
+        enum: ["ready_for_author", "retry_recon", "recon_stuck", "needs_recon", "blocked", "human_review"]
+      },
+      summary: { type: "string" },
+      payload: {
+        type: "object",
+        description: "Optional recon assessment details such as baseline_understanding, refined_inputs, reasons, or diagnostic blocker context."
+      },
+      reasons: { type: "array", items: { type: "string" } },
+      continue_with_stage: { type: "string", enum: ["recon", "author"] },
+      source: {
+        type: "object",
+        properties: {
+          kind: { type: "string" },
+          session_id: { type: "string" },
+          user_id: { type: "string" }
+        }
+      },
+      created_at: { type: "string" }
+    }
+  };
+}
+function responseSchemaForImplementationPacket() {
+  return {
+    type: "object",
+    required: ["version", "run_id", "checkpoint", "decision", "summary", "created_at"],
+    additionalProperties: false,
+    properties: {
+      version: { const: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION },
+      run_id: { type: "string" },
+      checkpoint: { type: "string" },
+      resume_token: { type: "string" },
+      decision: {
+        type: "string",
+        enum: ["implementation_complete", "needs_author", "needs_recon", "blocked", "human_review"]
+      },
+      summary: { type: "string" },
+      payload: {
+        type: "object",
+        description: "Implementation details such as changed_files, tests_run, and implementation_notes. The changed worktree must contain a real git diff before verify can advance."
+      },
+      reasons: { type: "array", items: { type: "string" } },
+      continue_with_stage: { type: "string", enum: ["implement", "verify", "author", "recon"] },
+      source: {
+        type: "object",
+        properties: {
+          kind: { type: "string" },
+          session_id: { type: "string" },
+          user_id: { type: "string" }
+        }
+      },
+      created_at: { type: "string" }
+    }
+  };
+}
+function responseSchemaForAdvancePacket(stage) {
+  return {
+    type: "object",
+    required: ["version", "run_id", "checkpoint", "decision", "summary", "created_at"],
+    additionalProperties: false,
+    properties: {
+      version: { const: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION },
+      run_id: { type: "string" },
+      checkpoint: { type: "string" },
+      resume_token: { type: "string" },
+      decision: {
+        type: "string",
+        enum: ["continue_stage", "retry_stage", "needs_recon", "needs_implementation", "blocked", "human_review"]
+      },
+      summary: { type: "string" },
+      payload: { type: "object" },
+      reasons: { type: "array", items: { type: "string" } },
+      continue_with_stage: { type: "string", enum: ["recon", "author", "implement", "verify", "ship", stage] },
+      source: {
+        type: "object",
+        properties: {
+          kind: { type: "string" },
+          session_id: { type: "string" },
+          user_id: { type: "string" }
+        }
+      },
+      created_at: { type: "string" }
+    }
+  };
+}
+function resumeTokenFor(input) {
+  const hash = import_node_crypto.default.createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 24);
+  return `rpchk_${hash}`;
+}
+function artifactsFromState(state) {
+  const artifacts = [];
+  for (const role of ["before", "prod", "after"]) {
+    const url = nonEmptyString(state?.[`${role}_cdn`]);
+    if (url) artifacts.push({ role, url, name: `${role}.png`, mime_type: "image/png" });
+  }
+  const authorRequest = recordValue(state?.author_request);
+  const latestAttempt = recordValue(authorRequest?.latest_attempt);
+  const observations = recordValue(latestAttempt?.observations);
+  for (const [label, observation] of Object.entries(observations || {})) {
+    const record = recordValue(observation);
+    const url = nonEmptyString(record?.url);
+    if (url && !artifacts.some((artifact) => artifact.url === url)) {
+      artifacts.push({
+        role: label === "before" || label === "prod" ? label : "json",
+        url,
+        name: `${label}-observation`,
+        summary: compactText(record?.reason, 240)
+      });
+    }
+  }
+  return artifacts.slice(0, 16);
+}
+function stageFromCheckpoint(checkpoint) {
+  if (checkpoint.startsWith("recon_")) return "recon";
+  if (checkpoint.startsWith("author_")) return "author";
+  if (checkpoint.startsWith("implement_")) return "implement";
+  if (checkpoint.startsWith("verify_")) return "verify";
+  if (checkpoint.startsWith("ship_")) return "ship";
+  if (checkpoint.startsWith("pr_sync_")) return "notify";
+  if (checkpoint.includes("capture")) return "prove";
+  return "setup";
+}
+function allowedDecisionsForStage(stage, checkpoint) {
+  if (stage === "recon") return ["ready_for_author", "retry_recon", "recon_stuck", "blocked", "human_review"];
+  if (stage === "implement") return ["implementation_complete", "needs_author", "needs_recon", "blocked", "human_review"];
+  if (stage === "ship") return ["continue_stage", "needs_implementation", "needs_recon", "blocked", "human_review"];
+  if (checkpoint === "awaiting_stage_advance") return ["continue_stage", "retry_stage", "blocked", "human_review"];
+  return ["continue_stage", "needs_recon", "needs_implementation", "blocked", "human_review"];
+}
+function packetKindForStage(stage, checkpoint) {
+  if (stage === "recon") return "assess_recon";
+  if (stage === "implement") return "implement_change";
+  if (checkpoint.includes("human")) return "human_review";
+  return "advance_decision";
+}
+function responseSchemaForStage(stage, checkpoint) {
+  if (stage === "recon") return responseSchemaForReconPacket();
+  if (stage === "implement") return responseSchemaForImplementationPacket();
+  return responseSchemaForAdvancePacket(stage);
+}
+function questionForStage(stage, checkpoint) {
+  if (stage === "recon") {
+    return "Assess the baseline/recon evidence. Return ready_for_author only when the baseline is trustworthy; otherwise choose retry_recon, recon_stuck, blocked, or human_review.";
+  }
+  if (stage === "implement") {
+    return "Implement the requested change in the after worktree, leave a real git diff, then return implementation_complete with changed_files/tests_run/implementation_notes. Choose blocked or human_review if implementation cannot honestly advance.";
+  }
+  if (stage === "ship") {
+    return "Assess whether the ship gate can continue. Return continue_stage only if proof, PR, and policy gates are satisfied; otherwise route to the appropriate earlier stage or block with a concrete reason.";
+  }
+  return "Choose the next Riddle Proof stage for this durable run, or block with a concrete reason if the run cannot honestly advance.";
+}
+function buildStageCheckpointPacket(input) {
+  const checkpoint = nonEmptyString(input.engineResult.checkpoint) || "stage_checkpoint";
+  const stage = nonEmptyString(input.engineResult.stage) || stageFromCheckpoint(checkpoint);
+  const runId = input.runState.run_id || "unknown";
+  const fullState = input.fullRiddleState || {};
+  const decisionDetails = recordValue(input.engineResult.decisionRequest?.details);
+  const checkpointContract = recordValue(input.engineResult.checkpointContract);
+  const summary = nonEmptyString(input.engineResult.summary) || nonEmptyString(fullState.stage_summary) || `${stage} checkpoint needs a supervising decision.`;
+  const kind = packetKindForStage(stage, checkpoint);
+  return {
+    version: RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
+    run_id: runId,
+    state_path: input.runState.state_path,
+    stage,
+    checkpoint,
+    kind,
+    summary,
+    question: questionForStage(stage, checkpoint),
+    change_request: input.request.change_request || nonEmptyString(fullState.change_request) || "",
+    context: input.request.context,
+    artifacts: artifactsFromState(fullState),
+    state_excerpt: compactRecord({
+      repo: input.request.repo || fullState.repo,
+      branch: input.request.branch || fullState.branch,
+      after_worktree: fullState.after_worktree || input.runState.worktree_path,
+      verification_mode: input.request.verification_mode || fullState.verification_mode,
+      reference: input.request.reference || fullState.reference,
+      server_path: fullState.server_path,
+      wait_for_selector: fullState.wait_for_selector,
+      recon_status: fullState.recon_status,
+      author_status: fullState.author_status,
+      implementation_status: fullState.implementation_status,
+      verify_status: fullState.verify_status,
+      stage_decision_request: jsonCloneRecord(fullState.stage_decision_request)
+    }),
+    evidence_excerpt: compactRecord({
+      before_cdn: fullState.before_cdn || null,
+      prod_cdn: fullState.prod_cdn || null,
+      after_cdn: fullState.after_cdn || null,
+      recon_results: jsonCloneRecord(fullState.recon_results),
+      checkpoint_contract: jsonCloneRecord(checkpointContract),
+      decision_details: jsonCloneRecord(decisionDetails)
+    }),
+    allowed_decisions: allowedDecisionsForStage(stage, checkpoint),
+    response_schema: responseSchemaForStage(stage, checkpoint),
+    routing_hint: {
+      suggested_role: stage === "implement" ? "builder_agent" : checkpoint.includes("human") ? "human" : "main_agent",
+      visibility: input.visibility || "quiet",
+      urgency: stage === "ship" ? "high" : "normal",
+      can_auto_answer: input.visibility !== "manual"
+    },
+    resume_token: resumeTokenFor({
+      runId,
+      statePath: input.engineResult.state_path || input.request.engine_state_path || null,
+      checkpoint,
+      stage
+    }),
+    created_at: input.created_at || timestamp()
+  };
+}
+function buildAuthorCheckpointPacket(input) {
+  const checkpoint = nonEmptyString(input.engineResult.checkpoint) || "author_supervisor_judgment";
+  const stage = "author";
+  const runId = input.runState.run_id || "unknown";
+  const fullState = input.fullRiddleState || {};
+  const decisionDetails = recordValue(input.engineResult.decisionRequest?.details);
+  const authorRequest = recordValue(fullState.author_request) || recordValue(fullState.proof_plan_request) || recordValue(decisionDetails?.authorRequest) || {};
+  const fallbackDefaults = recordValue(authorRequest.fallback_defaults) || {};
+  const reconResults = recordValue(fullState.recon_results);
+  const checkpointContract = recordValue(input.engineResult.checkpointContract);
+  const summary = nonEmptyString(input.engineResult.summary) || nonEmptyString(fullState.author_summary) || "Author checkpoint needs a supervising proof packet.";
+  return {
+    version: RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
+    run_id: runId,
+    state_path: input.runState.state_path,
+    stage,
+    checkpoint,
+    kind: "author_proof",
+    summary,
+    question: "Author the proof packet for this Riddle Proof run. Return a CheckpointResponse with decision=author_packet and payload containing proof_plan and capture_script.",
+    change_request: input.request.change_request || nonEmptyString(fullState.change_request) || "",
+    context: input.request.context,
+    artifacts: artifactsFromState(fullState),
+    state_excerpt: compactRecord({
+      repo: input.request.repo || fullState.repo,
+      branch: input.request.branch || fullState.branch,
       verification_mode: input.request.verification_mode || fullState.verification_mode,
       reference: input.request.reference || fullState.reference,
       server_path: fullState.server_path,
@@ -3318,9 +3372,132 @@ function buildAuthorCheckpointPacket(input) {
       checkpoint,
       stage
     }),
-    created_at: input.created_at || timestamp2()
+    created_at: input.created_at || timestamp()
   };
 }
+function visualDeltaFromState(fullState) {
+  const bundle = recordValue(fullState.evidence_bundle);
+  const after = recordValue(bundle?.after);
+  const afterDelta = recordValue(after?.visual_delta);
+  if (afterDelta && Object.keys(afterDelta).length) return afterDelta;
+  const proofAssessmentRequest = recordValue(fullState.proof_assessment_request);
+  return recordValue(proofAssessmentRequest?.visual_delta) || null;
+}
+function verificationModeRequiresVisualDelta(value) {
+  const mode = String(value || "proof").trim().toLowerCase();
+  return [
+    "visual",
+    "render",
+    "interaction",
+    "ui",
+    "layout",
+    "screenshot",
+    "canvas",
+    "animation"
+  ].includes(mode);
+}
+function visualDeltaIssueCode(visualDelta, required) {
+  const status = String(visualDelta?.status || "").trim();
+  const reason = String(visualDelta?.reason || "").toLowerCase();
+  if (status === "unmeasured") {
+    if (reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator")) {
+      return "comparator_fetch_blocked";
+    }
+    return "visual_delta_unmeasured";
+  }
+  if (status === "measured" && visualDelta?.passed === false) return "semantic_proof_failed";
+  if (required && status !== "measured") return "visual_delta_unmeasured";
+  return null;
+}
+function buildProofAssessmentCheckpointPacket(input) {
+  const checkpoint = nonEmptyString(input.engineResult.checkpoint) || "verify_supervisor_judgment";
+  const stage = "verify";
+  const runId = input.runState.run_id || "unknown";
+  const fullState = input.fullRiddleState || {};
+  const proofAssessmentRequest = recordValue(fullState.proof_assessment_request) || recordValue(recordValue(fullState.verify_decision_request)?.assessment_request) || recordValue(input.engineResult.decisionRequest?.details) || {};
+  const bundle = recordValue(fullState.evidence_bundle);
+  const artifactContract = recordValue(proofAssessmentRequest.artifact_contract) || recordValue(bundle?.artifact_contract);
+  const requiredSignals = recordValue(recordValue(artifactContract)?.required);
+  const visualDelta = visualDeltaFromState(fullState);
+  const verificationMode = nonEmptyString(input.request.verification_mode) || nonEmptyString(fullState.verification_mode) || nonEmptyString(bundle?.verification_mode) || "proof";
+  const visualDeltaRequired = requiredSignals?.visual_delta === true || verificationModeRequiresVisualDelta(verificationMode);
+  const evidenceIssueCode2 = visualDeltaIssueCode(visualDelta, visualDeltaRequired);
+  const summary = nonEmptyString(input.engineResult.summary) || nonEmptyString(fullState.verify_summary) || "Verify captured evidence and needs a supervising proof assessment.";
+  const recoveryHint = evidenceIssueCode2 ? "Required visual_delta evidence is incomplete. Keep this same run in verify/evidence recovery with decision=revise_capture and continue_with_stage=verify unless the evidence proves an implementation or recon problem." : "Assess whether the current artifacts prove the requested change, then choose the next stage.";
+  return {
+    version: RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
+    run_id: runId,
+    state_path: input.runState.state_path,
+    stage,
+    checkpoint,
+    kind: evidenceIssueCode2 ? "recover_evidence" : "assess_proof",
+    summary,
+    question: `Assess the current Riddle Proof evidence. ${recoveryHint} Return a CheckpointResponse using one allowed decision.`,
+    change_request: input.request.change_request || nonEmptyString(fullState.change_request) || "",
+    context: input.request.context,
+    artifacts: artifactsFromState(fullState),
+    state_excerpt: compactRecord({
+      repo: input.request.repo || fullState.repo,
+      branch: input.request.branch || fullState.branch,
+      verification_mode: verificationMode,
+      reference: input.request.reference || fullState.reference,
+      server_path: fullState.server_path,
+      wait_for_selector: fullState.wait_for_selector,
+      implementation_status: fullState.implementation_status,
+      implementation_summary: fullState.implementation_summary,
+      changed_files: jsonCloneValue(fullState.changed_files),
+      proof_plan: compactText(fullState.proof_plan, 1200)
+    }),
+    evidence_excerpt: compactRecord({
+      before_cdn: fullState.before_cdn || null,
+      prod_cdn: fullState.prod_cdn || null,
+      after_cdn: fullState.after_cdn || null,
+      visual_delta_required: visualDeltaRequired,
+      visual_delta_ready: visualDelta?.status === "measured" && visualDelta?.passed === true,
+      visual_delta: jsonCloneRecord(visualDelta),
+      evidence_issue_code: evidenceIssueCode2,
+      proof_assessment_request: jsonCloneRecord(proofAssessmentRequest),
+      verify_decision_request: jsonCloneRecord(fullState.verify_decision_request),
+      checkpoint_contract: jsonCloneRecord(input.engineResult.checkpointContract)
+    }),
+    artifact_contract: jsonCloneRecord(artifactContract),
+    allowed_decisions: [
+      "ready_to_ship",
+      "needs_richer_proof",
+      "revise_capture",
+      "needs_recon",
+      "needs_implementation",
+      "blocked",
+      "human_review"
+    ],
+    response_schema: responseSchemaForProofAssessmentPacket(),
+    routing_hint: {
+      suggested_role: evidenceIssueCode2 ? "proof_judge" : "proof_judge",
+      visibility: input.visibility || "quiet",
+      urgency: evidenceIssueCode2 ? "high" : "normal",
+      can_auto_answer: input.visibility !== "manual"
+    },
+    resume_token: resumeTokenFor({
+      runId,
+      statePath: input.engineResult.state_path || input.request.engine_state_path || null,
+      checkpoint,
+      stage
+    }),
+    created_at: input.created_at || timestamp()
+  };
+}
+function buildCheckpointPacketForEngineResult(input) {
+  const checkpoint = nonEmptyString(input.engineResult.checkpoint) || "";
+  if (checkpoint === "verify_supervisor_judgment" || checkpoint === "verify_supervisor_judgment_required" || checkpoint === "verify_human_escalation") {
+    return buildProofAssessmentCheckpointPacket(input);
+  }
+  const resume = recordValue(input.engineResult.checkpointContract?.resume);
+  const continueStage = nonEmptyString(resume?.continue_with_stage);
+  if (checkpoint === "author_supervisor_judgment" || checkpoint === "verify_capture_retry" || checkpoint === "verify_agent_retry" && continueStage === "author") {
+    return buildAuthorCheckpointPacket(input);
+  }
+  return buildStageCheckpointPacket(input);
+}
 function normalizeCheckpointResponse(value) {
   const record = recordValue(value);
   if (!record) return null;
@@ -3343,98 +3520,431 @@ function normalizeCheckpointResponse(value) {
     reasons: Array.isArray(record.reasons) ? record.reasons.filter((item) => typeof item === "string") : void 0,
     continue_with_stage: nonEmptyString(record.continue_with_stage),
     source: jsonCloneRecord(record.source),
-    created_at: nonEmptyString(record.created_at) || timestamp2()
+    created_at: nonEmptyString(record.created_at) || timestamp()
+  });
+}
+function checkpointSummaryFromState(state, engineStatePath2) {
+  const history = state.checkpoint_history || [];
+  const packets = history.filter((entry) => entry.packet);
+  const responses = history.filter((entry) => entry.response);
+  const duplicateResponses = (state.events || []).filter((event) => event.kind === "checkpoint.response.duplicate");
+  const latestPacketEntry = [...history].reverse().find((entry) => entry.packet);
+  const latestResponseEntry = [...history].reverse().find((entry) => entry.response);
+  const latestPacket = state.checkpoint_packet || latestPacketEntry?.packet;
+  const latestResponse = latestResponseEntry?.response;
+  const latestResumeToken = latestPacket?.resume_token || null;
+  const latestResponseToken = latestResponse?.resume_token || null;
+  const tokenMatches = latestResumeToken && latestResponseToken ? latestResumeToken === latestResponseToken : latestResumeToken || latestResponseToken ? false : null;
+  return compactRecord({
+    pending: Boolean(state.checkpoint_packet),
+    packet_count: packets.length,
+    response_count: responses.length,
+    duplicate_response_count: duplicateResponses.length,
+    latest_checkpoint: state.checkpoint_packet?.checkpoint || latestResponse?.checkpoint || state.last_checkpoint || null,
+    latest_stage: state.checkpoint_packet?.stage || latestResponse?.continue_with_stage || state.current_stage || null,
+    latest_kind: state.checkpoint_packet?.kind || latestPacket?.kind || null,
+    latest_decision: latestResponse?.decision || null,
+    latest_packet_summary: latestPacket?.summary || null,
+    latest_response_summary: latestResponse?.summary || null,
+    latest_resume_token: latestResumeToken,
+    latest_response_token: latestResponseToken,
+    token_matches: tokenMatches,
+    last_packet_at: latestPacketEntry?.ts || null,
+    last_response_at: latestResponseEntry?.ts || null,
+    state_paths: statePathsForRunState(state, engineStatePath2)
+  });
+}
+function isDuplicateCheckpointResponse(state, response) {
+  const identity = checkpointResponseIdentity(response);
+  return (state.checkpoint_history || []).some((entry) => entry.response ? checkpointResponseIdentity(entry.response) === identity : false);
+}
+function checkpointResponseIdentity(response) {
+  const logicalResponse = compactRecord({
+    run_id: response.run_id,
+    checkpoint: response.checkpoint,
+    resume_token: response.resume_token,
+    decision: response.decision,
+    summary: response.summary,
+    payload: response.payload,
+    reasons: response.reasons,
+    continue_with_stage: response.continue_with_stage,
+    source: response.source
+  });
+  return import_node_crypto.default.createHash("sha256").update(stableJson(logicalResponse)).digest("hex").slice(0, 24);
+}
+function authorPacketPayloadFromCheckpointResponse(response) {
+  if (response.decision !== "author_packet") return null;
+  const payload = recordValue(response.payload);
+  if (!payload) return null;
+  const nested = recordValue(payload.author_packet);
+  const candidate = nested || payload;
+  if (!nonEmptyString(candidate.proof_plan) || !nonEmptyString(candidate.capture_script)) return null;
+  return candidate;
+}
+function proofContractFromAuthorCheckpointResponse(response, packet, payload) {
+  const refinedInputs = recordValue(payload.refined_inputs) || {};
+  return compactRecord({
+    version: "riddle-proof.proof-contract.v1",
+    checkpoint: packet.checkpoint,
+    source_response: compactRecord({
+      run_id: response.run_id,
+      checkpoint: response.checkpoint,
+      resume_token: response.resume_token,
+      decision: response.decision,
+      summary: response.summary,
+      created_at: response.created_at
+    }),
+    proof_plan: nonEmptyString(payload.proof_plan),
+    capture_script: nonEmptyString(payload.capture_script),
+    artifact_contract: jsonCloneRecord(payload.artifact_contract),
+    assertions: jsonCloneValue(payload.assertions),
+    baseline_understanding: jsonCloneRecord(payload.baseline_understanding) || jsonCloneRecord(payload.recon_baseline_understanding) || jsonCloneRecord(packet.state_excerpt?.recon_baseline_understanding),
+    route_assumptions: compactRecord({
+      server_path: nonEmptyString(refinedInputs.server_path) || nonEmptyString(payload.server_path) || nonEmptyString(packet.state_excerpt?.server_path),
+      wait_for_selector: nonEmptyString(refinedInputs.wait_for_selector) || nonEmptyString(payload.wait_for_selector) || nonEmptyString(packet.state_excerpt?.wait_for_selector),
+      reference: nonEmptyString(refinedInputs.reference) || nonEmptyString(payload.reference),
+      expected_path: nonEmptyString(payload.expected_path) || nonEmptyString(refinedInputs.expected_path)
+    }),
+    stop_condition: nonEmptyString(payload.stop_condition),
+    rationale: jsonCloneValue(payload.rationale),
+    verdict_dimensions: jsonCloneRecord(payload.verdict_dimensions),
+    payload: jsonCloneRecord(payload),
+    created_at: timestamp()
+  });
+}
+
+// src/run-card.ts
+var RIDDLE_PROOF_RUN_CARD_VERSION = "riddle-proof.run-card.v1";
+function elapsedMs(start, end) {
+  const startMs = start ? Date.parse(start) : NaN;
+  const endMs = end ? Date.parse(end) : NaN;
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return void 0;
+  return Math.max(0, endMs - startMs);
+}
+function jsonCloneRecord2(value) {
+  const record = recordValue(value);
+  if (!record) return void 0;
+  try {
+    return JSON.parse(JSON.stringify(record));
+  } catch {
+    return { ...record };
+  }
+}
+function compactText2(value, limit = 600) {
+  const text = nonEmptyString(value);
+  if (!text) return void 0;
+  return text.length <= limit ? text : `${text.slice(0, limit - 20).trimEnd()}...`;
+}
+function visualDeltaFrom(input) {
+  const fullState = input.fullRiddleState || {};
+  const bundle = recordValue(fullState.evidence_bundle);
+  const after = recordValue(bundle?.after);
+  const afterDelta = recordValue(after?.visual_delta);
+  if (afterDelta && Object.keys(afterDelta).length) return afterDelta;
+  const requestDelta = recordValue(recordValue(fullState.proof_assessment_request)?.visual_delta);
+  if (requestDelta && Object.keys(requestDelta).length) return requestDelta;
+  const packetDelta = recordValue(input.runState.checkpoint_packet?.evidence_excerpt?.visual_delta);
+  return packetDelta && Object.keys(packetDelta).length ? packetDelta : void 0;
+}
+function artifactsFrom(input) {
+  const packetArtifacts = input.runState.checkpoint_packet?.artifacts;
+  if (packetArtifacts?.length) return packetArtifacts.slice(0, 12);
+  const fullState = input.fullRiddleState || {};
+  const artifacts = [];
+  for (const role of ["before", "prod", "after"]) {
+    const url = nonEmptyString(fullState[`${role}_cdn`]) || nonEmptyString(input.runState[`${role}_artifact_url`]);
+    if (url) artifacts.push({ role, url, name: `${role}.png`, mime_type: "image/png" });
+  }
+  return artifacts.length ? artifacts : void 0;
+}
+function ownerFor(state) {
+  if (state.status === "awaiting_checkpoint") {
+    const role = nonEmptyString(state.checkpoint_packet?.routing_hint?.suggested_role);
+    return role || "supervising_agent";
+  }
+  if (state.status === "running") return "engine";
+  if (state.status === "blocked" || state.status === "failed") return "human_or_operator";
+  return "none";
+}
+function actionFor(state) {
+  if (state.status === "awaiting_checkpoint") return state.checkpoint_packet?.question || "Answer the pending checkpoint.";
+  if (state.status === "running") return "Continue the current Riddle Proof stage.";
+  if (state.status === "blocked" || state.status === "failed") return state.blocker?.message || "Inspect the blocker and decide whether a new run or infrastructure repair is needed.";
+  if (state.status === "ready_to_ship") return "Ship is held by policy; review PR/ship policy before advancing.";
+  return "No next action; run is terminal.";
+}
+function evidenceIssueCode(input) {
+  const packetIssue = nonEmptyString(input.runState.checkpoint_packet?.evidence_excerpt?.evidence_issue_code);
+  if (packetIssue) return packetIssue;
+  const assessmentIssue = nonEmptyString(recordValue(input.fullRiddleState?.proof_assessment)?.evidence_issue_code);
+  if (assessmentIssue) return assessmentIssue;
+  const delta = visualDeltaFrom(input);
+  const status = nonEmptyString(delta?.status);
+  if (status === "unmeasured") {
+    const reason = `${nonEmptyString(delta?.reason) || ""}
+${input.runState.blocker?.message || ""}`.toLowerCase();
+    return reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator") ? "comparator_fetch_blocked" : "visual_delta_unmeasured";
+  }
+  if (status === "measured" && delta?.passed === false) return "semantic_proof_failed";
+  return void 0;
+}
+function createRiddleProofRunCard(state, input = {}) {
+  const at = input.at || (/* @__PURE__ */ new Date()).toISOString();
+  const fullState = input.fullRiddleState || {};
+  const packet = state.checkpoint_packet;
+  const latestEvent = state.events[state.events.length - 1];
+  const bundle = recordValue(fullState.evidence_bundle);
+  const artifactContract = jsonCloneRecord2(packet?.artifact_contract) || jsonCloneRecord2(recordValue(fullState.proof_assessment_request)?.artifact_contract) || jsonCloneRecord2(recordValue(bundle?.artifact_contract)) || jsonCloneRecord2(state.proof_contract?.artifact_contract);
+  const required = jsonCloneRecord2(recordValue(artifactContract)?.required);
+  const statePaths = input.state_paths || state.state_paths || statePathsForRunState(state);
+  const visualDelta = visualDeltaFrom({ fullRiddleState: fullState, runState: state });
+  const artifacts = artifactsFrom({ fullRiddleState: fullState, runState: state });
+  return {
+    version: RIDDLE_PROOF_RUN_CARD_VERSION,
+    run_id: state.run_id || "unknown",
+    status: state.status,
+    goal: compactRecord({
+      repo: state.request.repo || nonEmptyString(fullState.repo),
+      branch: state.request.branch || nonEmptyString(fullState.branch),
+      change_request: state.request.change_request || nonEmptyString(fullState.change_request),
+      verification_mode: state.request.verification_mode || nonEmptyString(fullState.verification_mode),
+      success_criteria: state.request.success_criteria
+    }),
+    durable_state: compactRecord({
+      ...statePaths,
+      worktree_path: state.worktree_path || nonEmptyString(fullState.after_worktree) || null,
+      branch: state.branch || nonEmptyString(fullState.branch) || null
+    }),
+    current_phase: compactRecord({
+      stage: state.current_stage ?? null,
+      checkpoint: state.last_checkpoint ?? packet?.checkpoint ?? null,
+      latest_event: latestEvent?.kind ?? null,
+      elapsed_ms: elapsedMs(state.created_at, at),
+      stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
+      iterations: state.iterations
+    }),
+    owner_next_action: compactRecord({
+      owner: ownerFor(state),
+      action: actionFor(state),
+      checkpoint_kind: packet?.kind || null,
+      allowed_decisions: packet?.allowed_decisions,
+      retryable: state.status === "running" || state.status === "awaiting_checkpoint",
+      reason: state.blocker?.code || packet?.summary || latestEvent?.summary || null
+    }),
+    evidence_contract: compactRecord({
+      verification_mode: state.request.verification_mode || nonEmptyString(fullState.verification_mode),
+      required,
+      artifact_contract: artifactContract,
+      proof_plan: compactText2(state.proof_contract?.proof_plan || fullState.proof_plan, 600),
+      stop_condition: compactText2(state.proof_contract?.stop_condition, 400)
+    }),
+    latest_evidence: compactRecord({
+      before_url: nonEmptyString(fullState.before_cdn) || state.before_artifact_url || null,
+      prod_url: nonEmptyString(fullState.prod_cdn) || state.prod_artifact_url || null,
+      after_url: nonEmptyString(fullState.after_cdn) || state.after_artifact_url || null,
+      visual_delta: visualDelta || null,
+      evidence_issue_code: evidenceIssueCode({ fullRiddleState: fullState, runState: state }) || null,
+      proof_evidence_present: fullState.proof_evidence_present === true || Boolean(bundle?.proof_evidence || bundle?.proof_evidence_sample),
+      artifacts
+    }),
+    stop_condition: compactRecord({
+      status: state.status,
+      terminal: isTerminalStatus(state.status),
+      blocker_code: state.blocker?.code || null,
+      blocker_message: state.blocker?.message || null,
+      proof_decision: state.proof_decision,
+      merge_recommendation: state.merge_recommendation,
+      monitor_should_continue: !isTerminalStatus(state.status)
+    }),
+    updated_at: state.updated_at
+  };
+}
+
+// src/state.ts
+var RIDDLE_PROOF_RUN_STATE_VERSION = "riddle-proof.run-state.v1";
+function timestamp2() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function createRunId(createdAt) {
+  const stamp = createdAt.replace(/\D/g, "").slice(0, 14) || "unknown";
+  const entropy = Math.random().toString(36).slice(2, 8) || "run";
+  return `rp_${stamp}_${entropy}`;
+}
+function elapsedMs2(start, end) {
+  const startMs = start ? Date.parse(start) : NaN;
+  const endMs = end ? Date.parse(end) : NaN;
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return void 0;
+  return Math.max(0, endMs - startMs);
+}
+function normalizeIntegrationContext(input, fallbackSource) {
+  const value = recordValue(input);
+  if (!value) {
+    return fallbackSource ? { source: fallbackSource } : void 0;
+  }
+  const metadata = recordValue(value.metadata);
+  return compactRecord({
+    source: nonEmptyString(value.source) || fallbackSource,
+    channel_id: nonEmptyString(value.channel_id),
+    thread_id: nonEmptyString(value.thread_id),
+    message_id: nonEmptyString(value.message_id),
+    source_url: nonEmptyString(value.source_url),
+    metadata: metadata && Object.keys(metadata).length ? metadata : void 0
+  });
+}
+function normalizeRunParams(input) {
+  return compactRecord({
+    repo: input.repo,
+    branch: input.branch,
+    change_request: input.change_request,
+    commit_message: input.commit_message,
+    prod_url: input.prod_url,
+    capture_script: input.capture_script,
+    success_criteria: input.success_criteria,
+    assertions: input.assertions,
+    verification_mode: input.verification_mode,
+    resume_session: input.resume_session,
+    target_image_url: input.target_image_url,
+    target_image_hash: input.target_image_hash,
+    viewport_matrix: input.viewport_matrix,
+    deterministic_setup: input.deterministic_setup,
+    reference: input.reference,
+    base_branch: input.base_branch,
+    before_ref: input.before_ref,
+    allow_static_preview_fallback: input.allow_static_preview_fallback,
+    context: input.context,
+    reviewer: input.reviewer,
+    mode: input.mode,
+    build_command: input.build_command,
+    build_output: input.build_output,
+    server_image: input.server_image,
+    server_command: input.server_command,
+    server_port: input.server_port,
+    server_path: input.server_path,
+    use_auth: input.use_auth,
+    auth_localStorage_json: input.auth_localStorage_json,
+    auth_cookies_json: input.auth_cookies_json,
+    auth_headers_json: input.auth_headers_json,
+    color_scheme: input.color_scheme,
+    wait_for_selector: input.wait_for_selector,
+    ship_mode: input.ship_mode,
+    leave_draft: input.leave_draft,
+    engine_state_path: input.engine_state_path,
+    harness_state_path: input.harness_state_path,
+    max_iterations: input.max_iterations,
+    auto_approve: input.auto_approve,
+    dry_run: input.dry_run,
+    integration_context: normalizeIntegrationContext(input.integration_context)
   });
 }
-function checkpointSummaryFromState(state, engineStatePath2) {
-  const history = state.checkpoint_history || [];
-  const packets = history.filter((entry) => entry.packet);
-  const responses = history.filter((entry) => entry.response);
-  const duplicateResponses = (state.events || []).filter((event) => event.kind === "checkpoint.response.duplicate");
-  const latestPacketEntry = [...history].reverse().find((entry) => entry.packet);
-  const latestResponseEntry = [...history].reverse().find((entry) => entry.response);
-  const latestPacket = state.checkpoint_packet || latestPacketEntry?.packet;
-  const latestResponse = latestResponseEntry?.response;
-  const latestResumeToken = latestPacket?.resume_token || null;
-  const latestResponseToken = latestResponse?.resume_token || null;
-  const tokenMatches = latestResumeToken && latestResponseToken ? latestResumeToken === latestResponseToken : latestResumeToken || latestResponseToken ? false : null;
+function createRunState(input) {
+  const createdAt = input.created_at || timestamp2();
   return compactRecord({
-    pending: Boolean(state.checkpoint_packet),
-    packet_count: packets.length,
-    response_count: responses.length,
-    duplicate_response_count: duplicateResponses.length,
-    latest_checkpoint: state.checkpoint_packet?.checkpoint || latestResponse?.checkpoint || state.last_checkpoint || null,
-    latest_stage: state.checkpoint_packet?.stage || latestResponse?.continue_with_stage || state.current_stage || null,
-    latest_kind: state.checkpoint_packet?.kind || latestPacket?.kind || null,
-    latest_decision: latestResponse?.decision || null,
-    latest_packet_summary: latestPacket?.summary || null,
-    latest_response_summary: latestResponse?.summary || null,
-    latest_resume_token: latestResumeToken,
-    latest_response_token: latestResponseToken,
-    token_matches: tokenMatches,
-    last_packet_at: latestPacketEntry?.ts || null,
-    last_response_at: latestResponseEntry?.ts || null,
-    state_paths: statePathsForRunState(state, engineStatePath2)
+    version: RIDDLE_PROOF_RUN_STATE_VERSION,
+    run_id: input.run_id || createRunId(createdAt),
+    state_path: input.state_path,
+    worktree_path: input.worktree_path,
+    branch: input.branch || input.request.branch,
+    current_stage: input.current_stage ?? null,
+    stage_started_at: input.stage_started_at ?? null,
+    status: input.status || "running",
+    created_at: createdAt,
+    updated_at: input.updated_at || createdAt,
+    request: normalizeRunParams(input.request),
+    iterations: input.iterations ?? 0,
+    last_checkpoint: input.last_checkpoint ?? null,
+    checkpoint_packet: input.checkpoint_packet,
+    checkpoint_summary: input.checkpoint_summary,
+    state_paths: input.state_paths,
+    proof_contract: input.proof_contract,
+    run_card: input.run_card,
+    checkpoint_history: input.checkpoint_history,
+    events: input.events ? [...input.events] : []
   });
 }
-function isDuplicateCheckpointResponse(state, response) {
-  const identity = checkpointResponseIdentity(response);
-  return (state.checkpoint_history || []).some((entry) => entry.response ? checkpointResponseIdentity(entry.response) === identity : false);
+function appendRunEvent(state, input) {
+  const event = {
+    ts: input.ts || timestamp2(),
+    kind: input.kind,
+    checkpoint: input.checkpoint,
+    stage: input.stage,
+    summary: input.summary,
+    details: input.details
+  };
+  state.events.push(compactRecord({
+    ts: event.ts,
+    kind: event.kind,
+    checkpoint: event.checkpoint,
+    stage: event.stage,
+    summary: event.summary,
+    details: event.details
+  }));
+  if (input.checkpoint !== void 0) state.last_checkpoint = input.checkpoint;
+  if (input.stage !== void 0) {
+    if (state.current_stage !== input.stage) state.stage_started_at = event.ts;
+    state.current_stage = input.stage;
+  }
+  state.updated_at = event.ts;
+  return state;
 }
-function checkpointResponseIdentity(response) {
-  const logicalResponse = compactRecord({
-    run_id: response.run_id,
-    checkpoint: response.checkpoint,
-    resume_token: response.resume_token,
-    decision: response.decision,
-    summary: response.summary,
-    payload: response.payload,
-    reasons: response.reasons,
-    continue_with_stage: response.continue_with_stage,
-    source: response.source
+function appendStageHeartbeat(state, input) {
+  const at = input.ts || timestamp2();
+  return appendRunEvent(state, {
+    ts: at,
+    kind: "stage.heartbeat",
+    checkpoint: input.checkpoint || `${input.stage}_heartbeat`,
+    stage: input.stage,
+    summary: input.summary || `${input.stage} stage is active.`,
+    details: compactRecord({
+      elapsed_ms: elapsedMs2(state.created_at, at),
+      stage_elapsed_ms: elapsedMs2(state.stage_started_at, at),
+      wait_reason: input.wait_reason,
+      blocker: input.blocker,
+      ...input.details
+    })
   });
-  return import_node_crypto.default.createHash("sha256").update(stableJson(logicalResponse)).digest("hex").slice(0, 24);
-}
-function authorPacketPayloadFromCheckpointResponse(response) {
-  if (response.decision !== "author_packet") return null;
-  const payload = recordValue(response.payload);
-  if (!payload) return null;
-  const nested = recordValue(payload.author_packet);
-  const candidate = nested || payload;
-  if (!nonEmptyString(candidate.proof_plan) || !nonEmptyString(candidate.capture_script)) return null;
-  return candidate;
 }
-function proofContractFromAuthorCheckpointResponse(response, packet, payload) {
-  const refinedInputs = recordValue(payload.refined_inputs) || {};
+function createRunStatusSnapshot(state, at = timestamp2()) {
+  const latestEvent = state.events[state.events.length - 1];
+  const runId = state.run_id || "unknown";
   return compactRecord({
-    version: "riddle-proof.proof-contract.v1",
-    checkpoint: packet.checkpoint,
-    source_response: compactRecord({
-      run_id: response.run_id,
-      checkpoint: response.checkpoint,
-      resume_token: response.resume_token,
-      decision: response.decision,
-      summary: response.summary,
-      created_at: response.created_at
-    }),
-    proof_plan: nonEmptyString(payload.proof_plan),
-    capture_script: nonEmptyString(payload.capture_script),
-    artifact_contract: jsonCloneRecord(payload.artifact_contract),
-    assertions: jsonCloneValue(payload.assertions),
-    baseline_understanding: jsonCloneRecord(payload.baseline_understanding) || jsonCloneRecord(payload.recon_baseline_understanding) || jsonCloneRecord(packet.state_excerpt?.recon_baseline_understanding),
-    route_assumptions: compactRecord({
-      server_path: nonEmptyString(refinedInputs.server_path) || nonEmptyString(payload.server_path) || nonEmptyString(packet.state_excerpt?.server_path),
-      wait_for_selector: nonEmptyString(refinedInputs.wait_for_selector) || nonEmptyString(payload.wait_for_selector) || nonEmptyString(packet.state_excerpt?.wait_for_selector),
-      reference: nonEmptyString(refinedInputs.reference) || nonEmptyString(payload.reference),
-      expected_path: nonEmptyString(payload.expected_path) || nonEmptyString(refinedInputs.expected_path)
-    }),
-    stop_condition: nonEmptyString(payload.stop_condition),
-    rationale: jsonCloneValue(payload.rationale),
-    verdict_dimensions: jsonCloneRecord(payload.verdict_dimensions),
-    payload: jsonCloneRecord(payload),
-    created_at: timestamp2()
+    run_id: runId,
+    status: state.status,
+    is_terminal: isTerminalStatus(state.status),
+    monitor_should_continue: !isTerminalStatus(state.status),
+    current_stage: state.current_stage ?? null,
+    state_path: state.state_path ?? null,
+    worktree_path: state.worktree_path ?? null,
+    branch: state.branch ?? null,
+    pr_url: state.pr_url ?? null,
+    pr_branch: state.pr_branch ?? null,
+    pr_state: state.pr_state,
+    ci_status: state.ci_status,
+    ship_commit: state.ship_commit,
+    ship_remote_head: state.ship_remote_head,
+    merge_commit: state.merge_commit,
+    merged_at: state.merged_at,
+    proof_comment_url: state.proof_comment_url,
+    cleanup_report: state.cleanup_report,
+    iterations: state.iterations,
+    last_checkpoint: state.last_checkpoint ?? null,
+    updated_at: state.updated_at,
+    elapsed_ms: elapsedMs2(state.created_at, at),
+    stage_elapsed_ms: elapsedMs2(state.stage_started_at, at),
+    blocker: state.blocker,
+    checkpoint_packet: state.checkpoint_packet,
+    checkpoint_summary: state.checkpoint_summary,
+    state_paths: state.state_paths,
+    proof_contract: state.proof_contract,
+    run_card: createRiddleProofRunCard(state, { at }),
+    latest_event: latestEvent
   });
 }
+function setRunStatus(state, status, at = timestamp2()) {
+  state.status = status;
+  state.ok = status !== "blocked" && status !== "failed";
+  state.updated_at = at;
+  return state;
+}
 
 // src/engine-harness.ts
 init_proof_run_core();
@@ -3513,6 +4023,10 @@ function shouldPreserveFinalizedRunState(filePath, incoming) {
 function persist(state) {
   state.state_paths = statePathsForRunState(state);
   state.checkpoint_summary = checkpointSummaryFromState(state);
+  state.run_card = createRiddleProofRunCard(state, {
+    fullRiddleState: readJson(state.request.engine_state_path),
+    state_paths: state.state_paths
+  });
   if (!state.state_path) return;
   if (shouldPreserveFinalizedRunState(state.state_path, state)) return;
   writeJson(state.state_path, state);
@@ -3592,7 +4106,7 @@ function removeEmptyToolArtifacts(workdir) {
   }
   return [];
 }
-function stageFromCheckpoint(result) {
+function stageFromCheckpoint2(result) {
   const explicitStage = nonEmptyString(result.stage);
   if (explicitStage) return explicitStage;
   const checkpoint = String(result.checkpoint || "");
@@ -3704,6 +4218,74 @@ function proofAssessmentContinuation(result, payload) {
   const proof_assessment_json = jsonParam(payload);
   return { ...baseContinuation(result), proof_assessment_json };
 }
+function defaultStageForProofCheckpointDecision(decision) {
+  if (decision === "ready_to_ship") return "ship";
+  if (decision === "needs_implementation") return "implement";
+  if (decision === "needs_recon") return "recon";
+  if (decision === "revise_capture") return "verify";
+  if (decision === "needs_richer_proof") return "author";
+  return null;
+}
+function proofAssessmentPayloadFromCheckpointResponse(response) {
+  if (![
+    "ready_to_ship",
+    "needs_richer_proof",
+    "revise_capture",
+    "needs_recon",
+    "needs_implementation"
+  ].includes(response.decision)) {
+    return null;
+  }
+  const payload = recordValue(response.payload) || {};
+  const stage = nonEmptyString(payload.continue_with_stage) || response.continue_with_stage || nonEmptyString(payload.recommended_stage) || defaultStageForProofCheckpointDecision(response.decision);
+  return compactRecord({
+    ...payload,
+    decision: response.decision,
+    summary: response.summary,
+    recommended_stage: nonEmptyString(payload.recommended_stage) || stage || void 0,
+    continue_with_stage: stage || void 0,
+    escalation_target: nonEmptyString(payload.escalation_target) || "agent",
+    reasons: Array.isArray(response.reasons) ? response.reasons : Array.isArray(payload.reasons) ? payload.reasons : [],
+    source: "supervising_agent",
+    checkpoint_response_source: response.source || null,
+    checkpoint_response_created_at: response.created_at
+  });
+}
+function reconAssessmentPayloadFromCheckpointResponse(response) {
+  if (![
+    "ready_for_author",
+    "retry_recon",
+    "recon_stuck",
+    "needs_recon"
+  ].includes(response.decision)) {
+    return null;
+  }
+  const payload = recordValue(response.payload) || {};
+  const decision = response.decision === "needs_recon" ? "retry_recon" : response.decision;
+  const continueStage = response.continue_with_stage || nonEmptyString(payload.continue_with_stage) || (decision === "ready_for_author" ? "author" : "recon");
+  return compactRecord({
+    ...payload,
+    decision,
+    summary: response.summary,
+    continue_with_stage: continueStage,
+    escalation_target: nonEmptyString(payload.escalation_target) || (decision === "recon_stuck" ? "human" : "agent"),
+    reasons: Array.isArray(response.reasons) ? response.reasons : Array.isArray(payload.reasons) ? payload.reasons : [],
+    source: "supervising_agent",
+    checkpoint_response_source: response.source || null,
+    checkpoint_response_created_at: response.created_at
+  });
+}
+function implementationNotesFromCheckpointResponse(response) {
+  const payload = recordValue(response.payload) || {};
+  const notes = nonEmptyString(payload.implementation_notes) || nonEmptyString(payload.implementationNotes) || nonEmptyString(payload.summary) || response.summary;
+  const changedFiles = Array.isArray(payload.changed_files) ? payload.changed_files.filter((item) => typeof item === "string") : [];
+  const testsRun = Array.isArray(payload.tests_run) ? payload.tests_run.filter((item) => typeof item === "string") : [];
+  return [
+    notes,
+    changedFiles.length ? `changed_files=${changedFiles.join(", ")}` : "",
+    testsRun.length ? `tests_run=${testsRun.join(", ")}` : ""
+  ].filter(Boolean).join("\n");
+}
 function proofAssessmentVisualBlocker(state, payload) {
   if (!proofAssessmentRequestsShip(payload)) return null;
   const source = nonEmptyString(payload.source) || "supervising_agent";
@@ -3792,7 +4374,7 @@ function engineFailureBlocker(result, checkpoint) {
 }
 function terminalResult(state, status, result, summary, raw = {}) {
   if (result) {
-    const terminalStage = stageFromCheckpoint(result);
+    const terminalStage = stageFromCheckpoint2(result);
     if (terminalStage !== "setup") state.current_stage = terminalStage;
   }
   setRunStatus(state, status);
@@ -3818,7 +4400,7 @@ function terminalResult(state, status, result, summary, raw = {}) {
 function blockerResult(state, result, blocker) {
   state.blocker = blocker;
   const blockerStage = nonEmptyString(recordValue(blocker.details)?.stage);
-  const stage = blockerStage || stageFromCheckpoint(result || { checkpoint: blocker.checkpoint || void 0 });
+  const stage = blockerStage || stageFromCheckpoint2(result || { checkpoint: blocker.checkpoint || void 0 });
   recordEvent(state, {
     kind: "run.blocked",
     checkpoint: blocker.checkpoint || result?.checkpoint || null,
@@ -3842,7 +4424,7 @@ function blockerResult(state, result, blocker) {
   });
 }
 function checkpointAwaitingResult(state, result, visibility) {
-  const packet = buildAuthorCheckpointPacket({
+  const packet = buildCheckpointPacketForEngineResult({
     request: state.request,
     runState: state,
     engineResult: result,
@@ -4005,10 +4587,93 @@ function checkpointResponseContinuation(state, value) {
     appendCheckpointResponse(state, response);
     return { next: { ...base, author_packet_json: jsonParam(payload) } };
   }
+  if (packet.kind === "assess_recon" || packet.stage === "recon") {
+    const assessment = reconAssessmentPayloadFromCheckpointResponse(response);
+    if (assessment) {
+      appendCheckpointResponse(state, response);
+      return { next: { ...base, recon_assessment_json: jsonParam(assessment) } };
+    }
+    if (response.decision === "blocked" || response.decision === "human_review") {
+      appendCheckpointResponse(state, response, { clear_packet: false });
+      return {
+        blocker: {
+          code: `checkpoint_response_${response.decision}`,
+          checkpoint: packet.checkpoint,
+          message: response.summary || `Checkpoint response stopped recon with decision=${response.decision}.`,
+          details: { stage: packet.stage, response }
+        }
+      };
+    }
+  }
+  if (packet.kind === "implement_change" || packet.stage === "implement") {
+    if (response.decision === "implementation_complete") {
+      const workdir = nonEmptyString(packet.state_excerpt?.after_worktree) || state.worktree_path;
+      if (workdir) state.worktree_path = workdir;
+      if (!hasGitDiff(workdir)) {
+        return {
+          blocker: {
+            code: "implementation_diff_missing",
+            checkpoint: packet.checkpoint,
+            message: "Checkpoint response claimed implementation_complete, but the after worktree has no detectable git diff.",
+            details: { stage: packet.stage, worktree_path: workdir || null, response }
+          }
+        };
+      }
+      appendCheckpointResponse(state, response);
+      return {
+        next: {
+          ...base,
+          advance_stage: "implement",
+          implementation_notes: implementationNotesFromCheckpointResponse(response)
+        }
+      };
+    }
+    if (response.decision === "needs_author") {
+      appendCheckpointResponse(state, response);
+      return { next: { ...base, advance_stage: "author" } };
+    }
+    if (response.decision === "needs_recon") {
+      appendCheckpointResponse(state, response);
+      return { next: { ...base, advance_stage: "recon" } };
+    }
+    if (response.decision === "blocked" || response.decision === "human_review") {
+      appendCheckpointResponse(state, response, { clear_packet: false });
+      return {
+        blocker: {
+          code: `checkpoint_response_${response.decision}`,
+          checkpoint: packet.checkpoint,
+          message: response.summary || `Checkpoint response stopped implementation with decision=${response.decision}.`,
+          details: { stage: packet.stage, response }
+        }
+      };
+    }
+  }
   if (response.decision === "needs_recon") {
     appendCheckpointResponse(state, response);
+    if (packet.kind === "assess_proof" || packet.kind === "recover_evidence" || packet.stage === "verify") {
+      const assessment = proofAssessmentPayloadFromCheckpointResponse(response);
+      if (assessment) return { next: { ...base, proof_assessment_json: jsonParam(assessment) } };
+    }
     return { next: { ...base, advance_stage: "recon" } };
   }
+  if (packet.kind === "assess_proof" || packet.kind === "recover_evidence" || packet.stage === "verify") {
+    const assessment = proofAssessmentPayloadFromCheckpointResponse(response);
+    if (assessment) {
+      appendCheckpointResponse(state, response);
+      return { next: { ...base, proof_assessment_json: jsonParam(assessment) } };
+    }
+    if (response.decision === "blocked" || response.decision === "human_review") {
+      appendCheckpointResponse(state, response, { clear_packet: false });
+      return {
+        blocker: {
+          code: `checkpoint_response_${response.decision}`,
+          checkpoint: packet.checkpoint,
+          message: response.summary || `Checkpoint response stopped the run with decision=${response.decision}.`,
+          details: { stage: packet.stage, response }
+        }
+      };
+    }
+  }
   appendCheckpointResponse(state, response, { clear_packet: false });
   return {
     blocker: {
@@ -4250,6 +4915,9 @@ async function routeCheckpoint(request, state, result, agent, input) {
     };
   }
   if (checkpoint === "recon_supervisor_judgment") {
+    if (input.checkpoint_mode === "yield") {
+      return { terminal: checkpointAwaitingResult(state, result, input.checkpoint_visibility) };
+    }
     const assessment = await agent.assessRecon(context);
     const blocker = requirePayload("recon_assessment", assessment, state, result);
     if (blocker) return { blocker };
@@ -4285,15 +4953,37 @@ async function routeCheckpoint(request, state, result, agent, input) {
     };
   }
   if (checkpoint === "implement_changes_missing" || checkpoint === "implement_required" || checkpoint === "verify_agent_retry" && continueStage === "implement") {
+    if (input.checkpoint_mode === "yield") {
+      const fullState = context.fullRiddleState || {};
+      state.worktree_path = workdirFromState(fullState) || state.worktree_path;
+      state.branch = nonEmptyString(fullState.branch) || state.branch;
+      persist(state);
+      return { terminal: checkpointAwaitingResult(state, result, input.checkpoint_visibility) };
+    }
     return handleImplementation(request, state, result, agent);
   }
   if (checkpoint === "implement_review") {
     return { next: { action: "run", state_path: String(result.state_path || ""), advance_stage: "verify" } };
   }
   if (checkpoint === "verify_supervisor_judgment") {
+    if (input.checkpoint_mode === "yield") {
+      return { terminal: checkpointAwaitingResult(state, result, input.checkpoint_visibility) };
+    }
     const assessment = await agent.assessProof(context);
     const blocker = requirePayload("proof_assessment", assessment, state, result);
-    if (blocker) return { blocker };
+    if (blocker) {
+      if (blocker.code === "main_agent_proof_review_required") {
+        recordEvent(state, {
+          kind: "checkpoint.packet.requested",
+          checkpoint,
+          stage: "verify",
+          summary: "Main-agent proof review is being converted to a portable checkpoint packet.",
+          details: { blocker }
+        });
+        return { terminal: checkpointAwaitingResult(state, result, input.checkpoint_visibility) };
+      }
+      return { blocker };
+    }
     const payload = assessment.payload;
     recordEvent(state, {
       kind: "agent.proof_assessment.completed",
@@ -4482,7 +5172,7 @@ async function runRiddleProofEngineHarness(input) {
     const engineState = engineStatePath(result, state);
     if (engineState) state.request.engine_state_path = engineState;
     state.last_checkpoint = result.checkpoint || state.last_checkpoint || null;
-    const resultStage = stageFromCheckpoint(result);
+    const resultStage = stageFromCheckpoint2(result);
     stageIterations[resultStage] = (stageIterations[resultStage] || 0) + 1;
     heartbeat(state, {
       stage: resultStage,