@riddledc/riddle-proof 0.5.45 → 0.5.46

package/dist/index.cjs

@@ -2761,6 +2761,7 @@ __export(index_exports, {
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION: () => RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
   RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION: () => RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
   RIDDLE_PROOF_PLAYABILITY_VERSION: () => RIDDLE_PROOF_PLAYABILITY_VERSION,
+  RIDDLE_PROOF_RUN_CARD_VERSION: () => RIDDLE_PROOF_RUN_CARD_VERSION,
   RIDDLE_PROOF_RUN_STATE_VERSION: () => RIDDLE_PROOF_RUN_STATE_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION: () => RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_VERSION: () => RIDDLE_PROOF_VISUAL_SESSION_VERSION,
@@ -2774,13 +2775,17 @@ __export(index_exports, {
   buildAuthorCheckpointPacket: () => buildAuthorCheckpointPacket,
   buildCheckpointPacketForEngineResult: () => buildCheckpointPacketForEngineResult,
   buildProofAssessmentCheckpointPacket: () => buildProofAssessmentCheckpointPacket,
+  buildStageCheckpointPacket: () => buildStageCheckpointPacket,
   buildVisualProofSession: () => buildVisualProofSession,
   checkpointResponseIdentity: () => checkpointResponseIdentity,
   checkpointSummaryFromState: () => checkpointSummaryFromState,
   compactRecord: () => compactRecord,
   compareVisualProofSessionFingerprint: () => compareVisualProofSessionFingerprint,
   createCaptureDiagnostic: () => createCaptureDiagnostic,
+  createCodexExecAgentAdapter: () => createCodexExecAgentAdapter,
+  createCodexExecJsonRunner: () => createCodexExecJsonRunner,
   createDisabledRiddleProofAgentAdapter: () => createDisabledRiddleProofAgentAdapter,
+  createRiddleProofRunCard: () => createRiddleProofRunCard,
   createRunResult: () => createRunResult,
   createRunState: () => createRunState,
   createRunStatusSnapshot: () => createRunStatusSnapshot,
@@ -2800,6 +2805,7 @@ __export(index_exports, {
   readRiddleProofRunStatus: () => readRiddleProofRunStatus,
   recordValue: () => recordValue,
   redactForProofDiagnostics: () => redactForProofDiagnostics,
+  runCodexExecAgentDoctor: () => runCodexExecAgentDoctor,
   runRiddleProof: () => runRiddleProof,
   runRiddleProofEngineHarness: () => runRiddleProofEngineHarness,
   setRunStatus: () => setRunStatus,
@@ -3018,248 +3024,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 normalizePrStatus2(value) {
-  const status = nonEmptyString(value)?.toLowerCase();
-  if (status === "merged") return "merged";
-  if (status === "open") return "open";
-  if (status === "closed") return "closed";
-  if (status === "not_found" || status === "not-found") return "not_found";
-  if (status === "unavailable") return "unavailable";
-  return status || "unknown";
-}
-function normalizePrLifecycleState(input, checkedAt = timestamp()) {
-  const value = recordValue(input);
-  if (!value) return void 0;
-  const cleanup = recordValue(value.cleanup);
-  const mergeCommit = nonEmptyString(value.merge_commit) || nonEmptyString(value.mergeCommit) || nonEmptyString(recordValue(value.mergeCommit)?.oid);
-  return compactRecord({
-    status: normalizePrStatus2(value.status || value.state),
-    pr_url: nonEmptyString(value.pr_url) || nonEmptyString(value.prUrl) || nonEmptyString(value.url),
-    pr_number: nonEmptyString(value.pr_number) || nonEmptyString(value.prNumber) || (typeof value.number === "number" ? String(value.number) : void 0),
-    repo: nonEmptyString(value.repo) || nonEmptyString(value.repository),
-    head_branch: nonEmptyString(value.head_branch) || nonEmptyString(value.headBranch) || nonEmptyString(value.headRefName),
-    base_branch: nonEmptyString(value.base_branch) || nonEmptyString(value.baseBranch) || nonEmptyString(value.baseRefName),
-    merge_commit: mergeCommit,
-    merged_at: nonEmptyString(value.merged_at) || nonEmptyString(value.mergedAt),
-    closed_at: nonEmptyString(value.closed_at) || nonEmptyString(value.closedAt),
-    checked_at: nonEmptyString(value.checked_at) || nonEmptyString(value.checkedAt) || checkedAt,
-    source: nonEmptyString(value.source),
-    next_action: nonEmptyString(value.next_action) || nonEmptyString(value.nextAction),
-    cleanup: cleanup && Object.keys(cleanup).length ? cleanup : void 0
-  });
-}
-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;
-}
-function applyPrLifecycleState(state, input, at = timestamp()) {
-  const prState = normalizePrLifecycleState(input, at);
-  if (!prState) return state;
-  state.pr_state = prState;
-  if (prState.pr_url) state.pr_url = prState.pr_url;
-  if (prState.head_branch) state.pr_branch = prState.head_branch;
-  if (prState.merge_commit) state.merge_commit = prState.merge_commit;
-  if (prState.merged_at) state.merged_at = prState.merged_at;
-  if (prState.cleanup) state.cleanup_report = prState.cleanup;
-  if (prState.status === "merged") {
-    state.finalized = true;
-    state.status = "completed";
-    state.ok = true;
-  }
-  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) {
@@ -3373,6 +3149,102 @@ function responseSchemaForProofAssessmentPacket() {
     }
   };
 }
+function responseSchemaForReconPacket() {
+  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_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}`;
@@ -3400,6 +3272,106 @@ function artifactsFromState(state) {
   }
   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";
@@ -3453,7 +3425,7 @@ function buildAuthorCheckpointPacket(input) {
       checkpoint,
       stage
     }),
-    created_at: input.created_at || timestamp2()
+    created_at: input.created_at || timestamp()
   };
 }
 function visualDeltaFromState(fullState) {
@@ -3502,16 +3474,16 @@ function buildProofAssessmentCheckpointPacket(input) {
   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 evidenceIssueCode = visualDeltaIssueCode(visualDelta, visualDeltaRequired);
+  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 = evidenceIssueCode ? "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.";
+  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: evidenceIssueCode ? "recover_evidence" : "assess_proof",
+    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) || "",
@@ -3536,7 +3508,7 @@ function buildProofAssessmentCheckpointPacket(input) {
       visual_delta_required: visualDeltaRequired,
       visual_delta_ready: visualDelta?.status === "measured" && visualDelta?.passed === true,
       visual_delta: jsonCloneRecord(visualDelta),
-      evidence_issue_code: evidenceIssueCode,
+      evidence_issue_code: evidenceIssueCode2,
       proof_assessment_request: jsonCloneRecord(proofAssessmentRequest),
       verify_decision_request: jsonCloneRecord(fullState.verify_decision_request),
       checkpoint_contract: jsonCloneRecord(input.engineResult.checkpointContract)
@@ -3553,9 +3525,9 @@ function buildProofAssessmentCheckpointPacket(input) {
     ],
     response_schema: responseSchemaForProofAssessmentPacket(),
     routing_hint: {
-      suggested_role: evidenceIssueCode ? "proof_judge" : "proof_judge",
+      suggested_role: evidenceIssueCode2 ? "proof_judge" : "proof_judge",
       visibility: input.visibility || "quiet",
-      urgency: evidenceIssueCode ? "high" : "normal",
+      urgency: evidenceIssueCode2 ? "high" : "normal",
       can_auto_answer: input.visibility !== "manual"
     },
     resume_token: resumeTokenFor({
@@ -3564,7 +3536,7 @@ function buildProofAssessmentCheckpointPacket(input) {
       checkpoint,
       stage
     }),
-    created_at: input.created_at || timestamp2()
+    created_at: input.created_at || timestamp()
   };
 }
 function buildCheckpointPacketForEngineResult(input) {
@@ -3572,7 +3544,12 @@ function buildCheckpointPacketForEngineResult(input) {
   if (checkpoint === "verify_supervisor_judgment" || checkpoint === "verify_supervisor_judgment_required" || checkpoint === "verify_human_escalation") {
     return buildProofAssessmentCheckpointPacket(input);
   }
-  return buildAuthorCheckpointPacket(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);
@@ -3596,7 +3573,7 @@ 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) {
@@ -3685,9 +3662,389 @@ function proofContractFromAuthorCheckpointResponse(response, packet, payload) {
     rationale: jsonCloneValue(payload.rationale),
     verdict_dimensions: jsonCloneRecord(payload.verdict_dimensions),
     payload: jsonCloneRecord(payload),
-    created_at: timestamp2()
+    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 normalizePrStatus2(value) {
+  const status = nonEmptyString(value)?.toLowerCase();
+  if (status === "merged") return "merged";
+  if (status === "open") return "open";
+  if (status === "closed") return "closed";
+  if (status === "not_found" || status === "not-found") return "not_found";
+  if (status === "unavailable") return "unavailable";
+  return status || "unknown";
+}
+function normalizePrLifecycleState(input, checkedAt = timestamp2()) {
+  const value = recordValue(input);
+  if (!value) return void 0;
+  const cleanup = recordValue(value.cleanup);
+  const mergeCommit = nonEmptyString(value.merge_commit) || nonEmptyString(value.mergeCommit) || nonEmptyString(recordValue(value.mergeCommit)?.oid);
+  return compactRecord({
+    status: normalizePrStatus2(value.status || value.state),
+    pr_url: nonEmptyString(value.pr_url) || nonEmptyString(value.prUrl) || nonEmptyString(value.url),
+    pr_number: nonEmptyString(value.pr_number) || nonEmptyString(value.prNumber) || (typeof value.number === "number" ? String(value.number) : void 0),
+    repo: nonEmptyString(value.repo) || nonEmptyString(value.repository),
+    head_branch: nonEmptyString(value.head_branch) || nonEmptyString(value.headBranch) || nonEmptyString(value.headRefName),
+    base_branch: nonEmptyString(value.base_branch) || nonEmptyString(value.baseBranch) || nonEmptyString(value.baseRefName),
+    merge_commit: mergeCommit,
+    merged_at: nonEmptyString(value.merged_at) || nonEmptyString(value.mergedAt),
+    closed_at: nonEmptyString(value.closed_at) || nonEmptyString(value.closedAt),
+    checked_at: nonEmptyString(value.checked_at) || nonEmptyString(value.checkedAt) || checkedAt,
+    source: nonEmptyString(value.source),
+    next_action: nonEmptyString(value.next_action) || nonEmptyString(value.nextAction),
+    cleanup: cleanup && Object.keys(cleanup).length ? cleanup : void 0
+  });
+}
+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 || timestamp2();
+  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,
+    run_card: input.run_card,
+    checkpoint_history: input.checkpoint_history,
+    events: input.events ? [...input.events] : []
+  });
+}
+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 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
+    })
+  });
+}
+function createRunStatusSnapshot(state, at = timestamp2()) {
+  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: 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;
+}
+function applyPrLifecycleState(state, input, at = timestamp2()) {
+  const prState = normalizePrLifecycleState(input, at);
+  if (!prState) return state;
+  state.pr_state = prState;
+  if (prState.pr_url) state.pr_url = prState.pr_url;
+  if (prState.head_branch) state.pr_branch = prState.head_branch;
+  if (prState.merge_commit) state.merge_commit = prState.merge_commit;
+  if (prState.merged_at) state.merged_at = prState.merged_at;
+  if (prState.cleanup) state.cleanup_report = prState.cleanup;
+  if (prState.status === "merged") {
+    state.finalized = true;
+    state.status = "completed";
+    state.ok = true;
+  }
+  state.updated_at = at;
+  return state;
+}
 
 // src/runner.ts
 function errorDetails(error) {
@@ -4252,6 +4609,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);
@@ -4331,7 +4692,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 || "");
@@ -4476,6 +4837,41 @@ function proofAssessmentPayloadFromCheckpointResponse(response) {
     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";
@@ -4564,7 +4960,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);
@@ -4590,7 +4986,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,
@@ -4777,6 +5173,67 @@ 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") {
@@ -5044,6 +5501,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 };
@@ -5079,6 +5539,13 @@ 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") {
@@ -5291,7 +5758,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,
@@ -5358,6 +5825,755 @@ async function runRiddleProofEngineHarness(input) {
   });
 }
 
+// src/codex-exec-agent.ts
+var import_node_child_process3 = require("child_process");
+var import_node_fs4 = require("fs");
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
+var REFINED_INPUTS_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["server_path", "wait_for_selector", "reference"],
+  properties: {
+    server_path: { type: ["string", "null"] },
+    wait_for_selector: { type: ["string", "null"] },
+    reference: { enum: ["before", "prod", "both", null] }
+  }
+};
+var BASELINE_UNDERSTANDING_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "reference",
+    "target_route",
+    "before_evidence_url",
+    "visible_before_state",
+    "relevant_elements",
+    "requested_change",
+    "proof_focus",
+    "stop_condition",
+    "quality_risks"
+  ],
+  properties: {
+    reference: { type: "string", enum: ["before", "prod", "both", "unknown"] },
+    target_route: { type: "string" },
+    before_evidence_url: { type: "string" },
+    visible_before_state: { type: "string" },
+    relevant_elements: { type: "array", items: { type: "string" } },
+    requested_change: { type: "string" },
+    proof_focus: { type: "string" },
+    stop_condition: { type: "string" },
+    quality_risks: { type: "array", items: { type: "string" } }
+  }
+};
+var RECON_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "decision",
+    "summary",
+    "baseline_understanding",
+    "continue_with_stage",
+    "escalation_target",
+    "refined_inputs",
+    "reasons",
+    "source"
+  ],
+  properties: {
+    decision: { type: "string", enum: ["retry_recon", "ready_for_author", "recon_stuck"] },
+    summary: { type: "string" },
+    baseline_understanding: BASELINE_UNDERSTANDING_SCHEMA,
+    continue_with_stage: { type: "string", enum: ["recon", "author"] },
+    escalation_target: { type: "string", enum: ["agent", "human"] },
+    refined_inputs: REFINED_INPUTS_SCHEMA,
+    reasons: { type: "array", items: { type: "string" } },
+    source: { type: "string", enum: ["supervising_agent"] }
+  }
+};
+var AUTHOR_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "proof_plan",
+    "capture_script",
+    "baseline_understanding_used",
+    "refined_inputs",
+    "rationale",
+    "confidence",
+    "summary"
+  ],
+  properties: {
+    proof_plan: { type: "string" },
+    capture_script: { type: "string" },
+    baseline_understanding_used: BASELINE_UNDERSTANDING_SCHEMA,
+    refined_inputs: REFINED_INPUTS_SCHEMA,
+    rationale: { type: "array", items: { type: "string" } },
+    confidence: { type: "string", enum: ["low", "medium", "high"] },
+    summary: { type: "string" }
+  }
+};
+var IMPLEMENT_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["summary", "implementation_notes", "changed_files", "tests_run", "blockers"],
+  properties: {
+    summary: { type: "string" },
+    implementation_notes: { type: "string" },
+    changed_files: { type: "array", items: { type: "string" } },
+    tests_run: { type: "array", items: { type: "string" } },
+    blockers: { type: "array", items: { type: "string" } }
+  }
+};
+var PROOF_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "decision",
+    "summary",
+    "recommended_stage",
+    "continue_with_stage",
+    "escalation_target",
+    "reasons",
+    "source"
+  ],
+  properties: {
+    decision: {
+      type: "string",
+      enum: [
+        "ready_to_ship",
+        "needs_richer_proof",
+        "revise_capture",
+        "needs_recon",
+        "needs_implementation"
+      ]
+    },
+    summary: { type: "string" },
+    recommended_stage: { type: "string", enum: ["ship", "author", "implement", "recon", "verify"] },
+    continue_with_stage: { type: "string", enum: ["ship", "author", "implement", "recon", "verify"] },
+    escalation_target: { type: "string", enum: ["agent", "human"] },
+    reasons: { type: "array", items: { type: "string" } },
+    source: { type: "string", enum: ["supervising_agent"] }
+  }
+};
+var PROMPT_STRING_LIMIT = 2e3;
+var PROMPT_ARRAY_LIMIT = 12;
+var PROMPT_OBJECT_KEY_LIMIT = 70;
+var PROMPT_BLOCK_LIMIT = 12e4;
+var PROMPT_KEY_PRIORITY = [
+  "ok",
+  "status",
+  "stage",
+  "checkpoint",
+  "summary",
+  "state_path",
+  "repo",
+  "branch",
+  "change_request",
+  "context",
+  "success_criteria",
+  "verification_mode",
+  "reference",
+  "server_path",
+  "wait_for_selector",
+  "before_cdn",
+  "prod_cdn",
+  "after_cdn",
+  "before_baseline",
+  "prod_baseline",
+  "recon_assessment",
+  "baseline_understanding",
+  "supervisor_author_packet",
+  "proof_plan",
+  "capture_script",
+  "implementation_status",
+  "implementation_summary",
+  "implementation_notes",
+  "changed_files",
+  "verify_status",
+  "verify_summary",
+  "proof_assessment",
+  "proof_assessment_request",
+  "semantic_context",
+  "visual_delta",
+  "proof_evidence_present",
+  "proof_evidence_sample",
+  "artifacts",
+  "assertions",
+  "checkpointContract",
+  "shipGate",
+  "last_error",
+  "errors",
+  "events"
+];
+var PROMPT_PRIORITY_INDEX = new Map(PROMPT_KEY_PRIORITY.map((key, index) => [key, index]));
+function truncatePromptString(value, limit = PROMPT_STRING_LIMIT) {
+  if (value.length <= limit) return value;
+  return `${value.slice(0, limit)}
+...[truncated ${value.length - limit} chars]`;
+}
+function compactPromptValue(value, depth = 0, key = "") {
+  if (value === null || typeof value === "boolean" || typeof value === "number") return value;
+  if (typeof value === "string") {
+    const lowerKey = key.toLowerCase();
+    const looksLikeUrl = /^https?:\/\//.test(value);
+    if (!looksLikeUrl && (lowerKey.includes("base64") || lowerKey.includes("data_url") || lowerKey.includes("screenshot_blob"))) {
+      return `[omitted ${value.length} chars from ${key || "large artifact"}]`;
+    }
+    const limit = looksLikeUrl ? 1e3 : depth <= 1 ? PROMPT_STRING_LIMIT : 1200;
+    return truncatePromptString(value, limit);
+  }
+  if (Array.isArray(value)) {
+    const lowerKey = key.toLowerCase();
+    const items = lowerKey.includes("event") || lowerKey.includes("histor") || lowerKey.includes("retry") ? value.slice(-PROMPT_ARRAY_LIMIT) : value.slice(0, PROMPT_ARRAY_LIMIT);
+    const compacted = items.map((item) => compactPromptValue(item, depth + 1, key));
+    if (value.length > items.length) {
+      const omitted = value.length - items.length;
+      return lowerKey.includes("event") || lowerKey.includes("histor") || lowerKey.includes("retry") ? [{ omittedEarlierItems: omitted }, ...compacted] : [...compacted, { omittedItems: omitted }];
+    }
+    return compacted;
+  }
+  if (!value || typeof value !== "object") return String(value);
+  const entries = Object.entries(value).sort(([left], [right]) => {
+    const leftPriority = PROMPT_PRIORITY_INDEX.get(left) ?? 1e3;
+    const rightPriority = PROMPT_PRIORITY_INDEX.get(right) ?? 1e3;
+    if (leftPriority !== rightPriority) return leftPriority - rightPriority;
+    return left.localeCompare(right);
+  });
+  const result = {};
+  for (const [entryKey, entryValue] of entries.slice(0, PROMPT_OBJECT_KEY_LIMIT)) {
+    result[entryKey] = compactPromptValue(entryValue, depth + 1, entryKey);
+  }
+  if (entries.length > PROMPT_OBJECT_KEY_LIMIT) {
+    result.__omitted_keys = entries.length - PROMPT_OBJECT_KEY_LIMIT;
+  }
+  return result;
+}
+function jsonBlock(label, value) {
+  let json = JSON.stringify(compactPromptValue(value), null, 2);
+  if (json.length > PROMPT_BLOCK_LIMIT) {
+    json = `${json.slice(0, PROMPT_BLOCK_LIMIT)}
+...[truncated ${json.length - PROMPT_BLOCK_LIMIT} chars from compacted ${label}]`;
+  }
+  return `${label}:
+${json}`;
+}
+function resolveWorkdir(context, fallback = "/tmp") {
+  const after = typeof context.fullRiddleState?.after_worktree === "string" ? context.fullRiddleState.after_worktree.trim() : "";
+  return after || fallback;
+}
+function basePrompt(context, role) {
+  return [
+    role,
+    "",
+    "You are the supervising Codex worker inside the Riddle Proof harness.",
+    "Return only JSON matching the provided output schema.",
+    "Do not ask the human to manually continue. If blocked, encode the blocker in the JSON fields allowed by the schema.",
+    "Large raw artifacts are summarized before this prompt. Use preserved state summaries, URLs, file paths, and proof evidence samples instead of expecting full raw logs or binary artifacts inline.",
+    "",
+    jsonBlock("Original request", context.request),
+    jsonBlock("Riddle checkpoint result", context.engineResult),
+    jsonBlock("Full riddle state", context.fullRiddleState || {})
+  ].join("\n");
+}
+function schemaRequiredKeys(schema) {
+  const required = schema?.required;
+  return Array.isArray(required) ? required.filter((key) => typeof key === "string" && key.length > 0) : [];
+}
+function isSchemaShapedObject(value, schema) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const required = schemaRequiredKeys(schema);
+  return required.every((key) => Object.prototype.hasOwnProperty.call(value, key));
+}
+function parseJsonCandidate(raw, schema) {
+  try {
+    const parsed = JSON.parse(raw);
+    return isSchemaShapedObject(parsed, schema) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function extractJsonObjectCandidates(raw) {
+  const candidates = [];
+  let depth = 0;
+  let start = -1;
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < raw.length; index += 1) {
+    const char = raw[index];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{") {
+      if (depth === 0) start = index;
+      depth += 1;
+      continue;
+    }
+    if (char === "}" && depth > 0) {
+      depth -= 1;
+      if (depth === 0 && start >= 0) {
+        candidates.push(raw.slice(start, index + 1));
+        start = -1;
+      }
+    }
+  }
+  return candidates;
+}
+function parseJsonObject(raw, schema) {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  const whole = parseJsonCandidate(trimmed, schema);
+  if (whole) return whole;
+  const lines = trimmed.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const parsed = parseJsonCandidate(lines[index], schema);
+    if (parsed) return parsed;
+  }
+  const candidates = extractJsonObjectCandidates(trimmed);
+  for (let index = candidates.length - 1; index >= 0; index -= 1) {
+    const parsed = parseJsonCandidate(candidates[index], schema);
+    if (parsed) return parsed;
+  }
+  return null;
+}
+function isHarnessVerificationOnlyBlocker(blocker) {
+  const text = blocker.toLowerCase();
+  return (text.includes("erofs") || text.includes("read-only file system")) && text.includes("node_modules") && (text.includes(".vite-temp") || text.includes("vite.config"));
+}
+function createCodexExecJsonRunner(config = {}) {
+  return (request) => {
+    if (!request.workdir || !(0, import_node_fs4.existsSync)(request.workdir)) {
+      return {
+        ok: false,
+        blocker: {
+          code: "codex_workdir_missing",
+          message: `Codex workdir does not exist for ${request.purpose}.`,
+          details: { workdir: request.workdir }
+        }
+      };
+    }
+    const tmpDir = (0, import_node_fs4.mkdtempSync)(import_node_path4.default.join(import_node_os.default.tmpdir(), "riddle-proof-codex-"));
+    const schemaPath = import_node_path4.default.join(tmpDir, "schema.json");
+    const lastMessagePath = import_node_path4.default.join(tmpDir, "last-message.json");
+    (0, import_node_fs4.writeFileSync)(schemaPath, JSON.stringify(request.schema, null, 2));
+    const args = [
+      "exec",
+      "--json",
+      "--output-schema",
+      schemaPath,
+      "--output-last-message",
+      lastMessagePath,
+      "--cd",
+      request.workdir,
+      "--sandbox",
+      config.codexSandbox || "workspace-write",
+      "--skip-git-repo-check"
+    ];
+    if (config.codexFullAuto !== false) args.push("--full-auto");
+    if (config.codexModel) args.push("-m", config.codexModel);
+    args.push("-");
+    const env = { ...process.env };
+    if (config.codexHome) env.CODEX_HOME = config.codexHome;
+    delete env.OPENAI_API_KEY;
+    try {
+      const proc = (0, import_node_child_process3.spawnSync)(config.codexCommand || "codex", args, {
+        input: request.prompt,
+        encoding: "utf-8",
+        timeout: Number(config.codexTimeoutMs || 6e5),
+        maxBuffer: 10 * 1024 * 1024,
+        env
+      });
+      if (proc.error) {
+        const timedOut = proc.error.code === "ETIMEDOUT";
+        return {
+          ok: false,
+          stdout: proc.stdout || "",
+          stderr: proc.stderr || "",
+          blocker: {
+            code: timedOut ? "codex_timeout" : "codex_exec_error",
+            message: timedOut ? `Codex timed out during ${request.purpose}.` : `Codex failed to start or complete ${request.purpose}.`,
+            details: { error: proc.error.message }
+          }
+        };
+      }
+      if (proc.status !== 0) {
+        return {
+          ok: false,
+          stdout: proc.stdout || "",
+          stderr: proc.stderr || "",
+          blocker: {
+            code: "codex_nonzero_exit",
+            message: `Codex exited with status ${proc.status} during ${request.purpose}.`,
+            details: { stdout: proc.stdout || "", stderr: proc.stderr || "" }
+          }
+        };
+      }
+      const finalText = (0, import_node_fs4.existsSync)(lastMessagePath) ? (0, import_node_fs4.readFileSync)(lastMessagePath, "utf-8") : String(proc.stdout || "");
+      const parsed = parseJsonObject(finalText, request.schema);
+      if (!parsed) {
+        return {
+          ok: false,
+          stdout: proc.stdout || "",
+          stderr: proc.stderr || "",
+          blocker: {
+            code: "codex_invalid_json",
+            message: `Codex completed ${request.purpose}, but did not return valid JSON.`,
+            details: { finalText, stdout: proc.stdout || "", stderr: proc.stderr || "" }
+          }
+        };
+      }
+      return {
+        ok: true,
+        json: parsed,
+        stdout: proc.stdout || "",
+        stderr: proc.stderr || ""
+      };
+    } finally {
+      (0, import_node_fs4.rmSync)(tmpDir, { recursive: true, force: true });
+    }
+  };
+}
+async function callRunner(runner, request) {
+  return runner(request);
+}
+function payloadOrBlocker(raw, checkpoint) {
+  if (!raw.ok || !raw.json) {
+    const blocker = raw.blocker || {
+      code: "codex_runner_failed",
+      message: "Codex runner failed without a detailed blocker.",
+      details: { stdout: raw.stdout || "", stderr: raw.stderr || "" }
+    };
+    return {
+      ok: false,
+      blocker: {
+        ...blocker,
+        checkpoint
+      }
+    };
+  }
+  return {
+    ok: true,
+    payload: raw.json,
+    summary: typeof raw.json.summary === "string" ? raw.json.summary : void 0
+  };
+}
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function parseGitStatusPaths2(status) {
+  return status.split(/\r?\n/).map((line) => line.trimEnd()).filter(Boolean).map((line) => {
+    let item = line.length > 3 ? line.slice(3) : line;
+    if (item.includes(" -> ")) item = item.split(" -> ").pop() || item;
+    return item.trim();
+  }).filter(Boolean);
+}
+function isToolNoisePath2(filePath) {
+  return filePath === ".codex" || filePath.startsWith(".codex/") || filePath === ".oc-smoke" || filePath.startsWith(".oc-smoke/");
+}
+function hasGitDiff2(workdir) {
+  try {
+    const status = git(["status", "--porcelain"], workdir);
+    return parseGitStatusPaths2(status).some((filePath) => !isToolNoisePath2(filePath));
+  } catch {
+    return false;
+  }
+}
+function buildImplementationPrompt(context, extraLines = []) {
+  return [
+    basePrompt(context, "Implement the requested code change in the after worktree."),
+    "Make the code changes directly in this repository.",
+    "Use the recon-approved baseline understanding in the state to decide exactly what prior UI/state is being changed.",
+    "Run focused checks when practical.",
+    "If a focused check is blocked only by the harness sandbox writing Vite temp config into a shared/symlinked node_modules path (for example EROFS on node_modules/.vite-temp/vite.config...), do not treat that as an implementation blocker when the requested git diff exists. Record it in tests_run or implementation_notes instead so the harness can advance to its own verify stage.",
+    "Leave a real git diff in the after worktree. Do not commit or push.",
+    "Before you return success, run git status --short and git diff --name-only in this repository and verify they show the intended change.",
+    "Do not return success with empty changed_files or a clean git status. If you cannot create the requested diff, explain why in blockers instead.",
+    "changed_files should match the real git diff as closely as practical.",
+    "Return changed_files, implementation_notes, tests_run, and blockers if any.",
+    "Use empty arrays for tests_run or blockers when none apply.",
+    ...extraLines
+  ].join("\n");
+}
+function createCodexExecAgentAdapter(config = {}, runner = createCodexExecJsonRunner(config)) {
+  return {
+    async assessRecon(context) {
+      const raw = await callRunner(runner, {
+        purpose: "recon assessment",
+        workdir: resolveWorkdir(context),
+        schema: RECON_SCHEMA,
+        prompt: [
+          basePrompt(context, "Judge the latest recon packet."),
+          "Decide whether recon should retry, continue to author, or escalate to the human.",
+          "This is the first intelligent before-evidence gate. It runs before proof authoring and before any code edits.",
+          "Prefer ready_for_author only when the baseline evidence is trustworthy for the requested change.",
+          "Do not approve recon just because telemetry_ready is true or a screenshot URL exists.",
+          "Inspect the baseline evidence in the state: screenshot URLs, structured pageState details, visible_text_sample, headings, buttons, links, canvas_count, large_visible_elements, observed_path, and route candidates.",
+          "Fill baseline_understanding with concrete observations about what the before/prod evidence shows, what exact user request it anchors, what proof should focus on, and what stop condition would satisfy the request.",
+          "If you cannot write a specific baseline_understanding from the current evidence, choose retry_recon or recon_stuck; do not choose ready_for_author.",
+          "Reject blank, banner-only, app-shell-only, loading-only, generic landing, source-import path, or wrong-feature baselines; retry recon with a better server_path or selector instead.",
+          "Your summary must say what is visibly present in the approved baseline or why the current baseline is not good enough.",
+          "Always include refined_inputs; use null values for server_path, wait_for_selector, or reference when no refinement is needed."
+        ].join("\n")
+      });
+      return payloadOrBlocker(raw, context.checkpoint);
+    },
+    async authorProofPacket(context) {
+      const raw = await callRunner(runner, {
+        purpose: "proof packet authoring",
+        workdir: resolveWorkdir(context),
+        schema: AUTHOR_SCHEMA,
+        prompt: [
+          basePrompt(context, "Author the proof packet."),
+          "Write a proof_plan and capture_script that will verify the exact user-facing change.",
+          "Use recon_assessment.baseline_understanding as the source of truth. Do not author a proof plan unless it names the observed before state and the requested delta from that state.",
+          "Use the recon-approved route and baseline context; make the plan name the concrete target, expected before state, expected after state, and stop condition.",
+          "Choose the evidence modality from verification_mode and success_criteria: screenshots for visual/UI proof, interactions plus screenshots for interaction proof, structured metrics/logs/JSON/audio analysis for non-visual proof.",
+          "For playable/gameplay proof, treat screenshots as supporting artifacts only: start the game, send keyboard or pointer input, measure state before/after, measure non-HUD canvas/playfield pixel deltas across time, and return playability evidence with version riddle-proof.playability.v1.",
+          "For structured proof, collect meaningful measurements inside page.evaluate and set window.__riddleProofEvidence in that browser page context to a JSON-serializable object. Screenshots are optional supporting context for data/audio/log/metric/custom modes.",
+          "Do not assign globalThis.__riddleProofEvidence, window.__riddleProofEvidence, or self.__riddleProofEvidence outside page.evaluate; the Riddle worker context may not expose those globals safely.",
+          "Do not call Playwright page.* APIs inside page.evaluate; page.evaluate runs in the browser page, while page.waitForFunction, page.waitForSelector, page.click, and saveScreenshot belong in the outer capture script.",
+          "When page.evaluate needs data from the outer Playwright script, pass exactly one serializable argument object; do not pass multiple positional arguments.",
+          "When setting Playwright wait timeouts, use the correct signature: await page.waitForFunction(fn, undefined, { timeout: 60000 }). Do not write page.waitForFunction(fn, { timeout: 60000 }); that passes the object as the page argument and leaves the default timeout in place.",
+          "For audio/data/metric proof, return and persist the same evidence object: const evidence = await page.evaluate(async () => { /* browser measurements */ window.__riddleProofEvidence = { ... }; return window.__riddleProofEvidence; }); Then assert evidence fields before saving screenshots.",
+          "If a capture attempt errors or proof_evidence is absent, revise the capture_script to make structured evidence easier to collect; do not only add more screenshots for non-visual proof.",
+          "When checking visible copy, normalize text before exact matching: const normalizedText = (document.body?.innerText || '').replace(/\\s+/g, ' ').trim(); Avoid raw innerText.includes(exact sentence) because browser line wrapping can split copy.",
+          "Prefer success-oriented evidence booleans such as newCopyVisible: true and oldCopyAbsent: true. If a positive assertion is false while screenshots/text samples look right, fix the capture script instead of leaving contradictory proof evidence.",
+          "Include a short matchedSnippet or normalizedTextSample when proofing copy so assertion mismatches are diagnosable.",
+          "For visual/UI proof, include saveScreenshot('after-proof') exactly once.",
+          "Avoid generic proof language. The packet should be specific enough that verify can tell whether the requested change actually happened.",
+          "Echo the baseline understanding you used in baseline_understanding_used so later stages can detect drift.",
+          "Use refined_inputs for server_path, wait_for_selector, or reference when useful; use null values when no refinement is needed."
+        ].join("\n")
+      });
+      return payloadOrBlocker(raw, context.checkpoint);
+    },
+    async implementChange(context) {
+      if (!context.workdir || !(0, import_node_fs4.existsSync)(context.workdir)) {
+        return {
+          ok: false,
+          blocker: {
+            code: "implementation_workdir_missing",
+            checkpoint: context.checkpoint,
+            message: "The Riddle Proof state does not include an after worktree that exists on disk.",
+            details: { workdir: context.workdir || null }
+          }
+        };
+      }
+      const workdir = context.workdir;
+      const attemptSummaries = [];
+      const runImplementationAttempt = async (purpose, extraLines = []) => {
+        const raw = await callRunner(runner, {
+          purpose,
+          workdir,
+          schema: IMPLEMENT_SCHEMA,
+          prompt: buildImplementationPrompt(context, extraLines)
+        });
+        if (!raw.ok || !raw.json) {
+          return {
+            ok: false,
+            payload: payloadOrBlocker(raw, context.checkpoint)
+          };
+        }
+        const changedFiles = stringArray(raw.json.changed_files);
+        const blockers = stringArray(raw.json.blockers);
+        const testsRun = stringArray(raw.json.tests_run);
+        const softVerificationBlockers = changedFiles.length ? blockers.filter(isHarnessVerificationOnlyBlocker) : [];
+        const hardBlockers = blockers.filter((item) => !softVerificationBlockers.includes(item));
+        const implementationNotesRaw = typeof raw.json.implementation_notes === "string" ? raw.json.implementation_notes : "";
+        const summary = typeof raw.json.summary === "string" ? raw.json.summary : "";
+        const implementationNotes = [
+          implementationNotesRaw,
+          ...softVerificationBlockers.map((item) => `Harness verification note: ${item}`)
+        ].filter(Boolean).join("\n");
+        const agentDetails = {
+          agent_purpose: purpose,
+          agent_summary: summary,
+          agent_changed_files: changedFiles,
+          agent_tests_run: testsRun,
+          agent_blockers: blockers
+        };
+        attemptSummaries.push({
+          purpose,
+          summary,
+          changed_files: changedFiles,
+          tests_run: testsRun,
+          blockers
+        });
+        if (hardBlockers.length) {
+          return {
+            ok: false,
+            payload: {
+              ok: false,
+              blocker: {
+                code: "codex_implementation_blocked",
+                checkpoint: context.checkpoint,
+                message: summary || "Codex reported implementation blockers.",
+                details: {
+                  blockers: hardBlockers,
+                  changedFiles,
+                  testsRun,
+                  implementationNotes: implementationNotesRaw,
+                  ...agentDetails
+                }
+              }
+            }
+          };
+        }
+        return {
+          ok: true,
+          summary,
+          changedFiles,
+          testsRun,
+          implementationNotes,
+          implementationNotesRaw,
+          softVerificationBlockers,
+          hardBlockers,
+          agentDetails
+        };
+      };
+      let attempt = await runImplementationAttempt("implementation");
+      if (!attempt.ok) return attempt.payload;
+      let diffDetected = hasGitDiff2(workdir);
+      if (!diffDetected) {
+        attempt = await runImplementationAttempt("implementation retry", [
+          "The previous implementation attempt returned without a detectable git diff in this repository.",
+          `Previous summary: ${attempt.summary || "(none)"}`,
+          `Previous changed_files: ${JSON.stringify(attempt.changedFiles)}`,
+          "Before you return success this time, run git status --short and git diff --name-only. If they are still empty, do not return success; either keep editing or explain the blocker."
+        ]);
+        if (!attempt.ok) return attempt.payload;
+        diffDetected = hasGitDiff2(workdir);
+      }
+      return {
+        ok: true,
+        summary: attempt.summary || void 0,
+        implementationNotes: attempt.implementationNotes || void 0,
+        changedFiles: attempt.changedFiles,
+        testsRun: attempt.testsRun,
+        details: {
+          ...attempt.agentDetails,
+          implementation_notes: attempt.implementationNotes || attempt.implementationNotesRaw || "",
+          soft_verification_blockers: attempt.softVerificationBlockers,
+          hard_blocker_count: attempt.hardBlockers.length,
+          retry_attempted: attemptSummaries.length > 1,
+          attempt_count: attemptSummaries.length,
+          attempt_summaries: attemptSummaries,
+          post_agent_diff_detected: diffDetected
+        }
+      };
+    },
+    async assessProof(context) {
+      const raw = await callRunner(runner, {
+        purpose: "proof assessment",
+        workdir: resolveWorkdir(context),
+        schema: PROOF_SCHEMA,
+        prompt: [
+          basePrompt(context, "Judge the proof bundle."),
+          "Decide whether the evidence is ready_to_ship or which internal stage should run next.",
+          "Only use ready_to_ship when the before/prod and after evidence actually prove the requested change.",
+          "Do not assume screenshots are required for every verification_mode. For data/audio/log/metric/custom proof, inspect the structured evidence bundle, proof_evidence_sample, artifacts, assertions, and success criteria directly.",
+          "Use semantic_context.route, headings, buttons, and text anchors to ground route/content judgment before calling screenshot evidence wrong-route or unrelated.",
+          "If structured proof evidence contains failed positive assertions, such as newCopyVisible: false or hasExpectedText: false, do not choose ready_to_ship until the evidence is reconciled or a richer proof is produced.",
+          "For visual/UI proof, screenshots and route/page-state quality still matter, but capture success alone is not proof.",
+          "For playable/gameplay proof, do not choose ready_to_ship unless playability evidence shows accepted input, state/time progression, and playfield/canvas pixel motion; a static generated scene is not playable proof.",
+          "For visual/UI polish, reject changes that are technically different but not legible to a reviewer. If visual_delta.status is measured and visual_delta.passed is false, choose needs_implementation when the visible result is wrong, or needs_richer_proof only when non-visual proof artifacts are insufficient.",
+          "If required visual_delta is unmeasured, missing, or not_applicable, choose revise_capture with recommended_stage=verify and continue_with_stage=verify so the same run stays in evidence/comparison recovery; do not choose ready_to_ship or generic needs_richer_proof for that missing metric.",
+          "Do not ship if the baseline is blank, shell-only, generic, or unrelated to the requested feature.",
+          "Your summary must name the concrete change, the target that was tested, what changed between baseline and after evidence, and why the stop condition is satisfied."
+        ].join("\n")
+      });
+      return payloadOrBlocker(raw, context.checkpoint);
+    }
+  };
+}
+function git(args, workdir) {
+  return (0, import_node_child_process3.execFileSync)("git", args, {
+    cwd: workdir,
+    encoding: "utf-8",
+    timeout: 1e4
+  });
+}
+async function runCodexExecAgentDoctor(config = {}, runner = createCodexExecJsonRunner(config)) {
+  const workdir = (0, import_node_fs4.mkdtempSync)(import_node_path4.default.join(import_node_os.default.tmpdir(), "riddle-proof-codex-doctor-"));
+  const targetPath = import_node_path4.default.join(workdir, "target.txt");
+  (0, import_node_fs4.writeFileSync)(targetPath, "color=red\n");
+  try {
+    git(["init", "-b", "main"], workdir);
+    git(["config", "user.email", "doctor@example.com"], workdir);
+    git(["config", "user.name", "Riddle Proof Doctor"], workdir);
+    git(["add", "target.txt"], workdir);
+    git(["commit", "-m", "initial doctor fixture"], workdir);
+  } catch (error) {
+    return {
+      ok: false,
+      status: "blocked",
+      blocker: {
+        code: "doctor_git_setup_failed",
+        message: "Could not create the temporary doctor git fixture.",
+        details: { error: error instanceof Error ? error.message : String(error), workdir }
+      }
+    };
+  }
+  const raw = await callRunner(runner, {
+    purpose: "codex exec doctor implementation",
+    workdir,
+    schema: IMPLEMENT_SCHEMA,
+    prompt: [
+      "You are running a Riddle Proof Codex exec doctor check.",
+      "In this temporary git repository, edit target.txt so it says exactly: color=blue",
+      "Do not commit. Leave a git diff.",
+      "Return JSON matching the schema with changed_files containing target.txt.",
+      "Use empty arrays for tests_run and blockers."
+    ].join("\n")
+  });
+  if (!raw.ok || !raw.json) {
+    return {
+      ok: false,
+      status: "blocked",
+      blocker: {
+        ...raw.blocker || {
+          code: "doctor_codex_failed",
+          message: "Codex doctor runner failed.",
+          details: { stdout: raw.stdout || "", stderr: raw.stderr || "" }
+        },
+        details: {
+          ...raw.blocker?.details || {},
+          workdir
+        }
+      }
+    };
+  }
+  const content = (0, import_node_fs4.readFileSync)(targetPath, "utf-8");
+  const status = git(["status", "--porcelain"], workdir);
+  const changedFiles = stringArray(raw.json.changed_files);
+  const ok = content.trim() === "color=blue" && status.includes("target.txt");
+  return {
+    ok,
+    status: ok ? "passed" : "blocked",
+    workdir,
+    changedFiles,
+    implementationSummary: raw.json.summary || null,
+    implementationNotes: raw.json.implementation_notes || null,
+    gitStatus: status,
+    targetContent: content,
+    blocker: ok ? null : {
+      code: "doctor_diff_missing_or_wrong",
+      message: "Codex doctor completed, but target.txt was not changed to color=blue with a git diff.",
+      details: { workdir, changedFiles, gitStatus: status, targetContent: content }
+    }
+  };
+}
+
 // src/diagnostics.ts
 var RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION = "riddle-proof.capture-diagnostic.v1";
 var DEFAULT_DIAGNOSTIC_STRING_LIMIT = 2e3;
@@ -5975,6 +7191,7 @@ function parseJson(value) {
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
   RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
   RIDDLE_PROOF_PLAYABILITY_VERSION,
+  RIDDLE_PROOF_RUN_CARD_VERSION,
   RIDDLE_PROOF_RUN_STATE_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_VERSION,
@@ -5988,13 +7205,17 @@ function parseJson(value) {
   buildAuthorCheckpointPacket,
   buildCheckpointPacketForEngineResult,
   buildProofAssessmentCheckpointPacket,
+  buildStageCheckpointPacket,
   buildVisualProofSession,
   checkpointResponseIdentity,
   checkpointSummaryFromState,
   compactRecord,
   compareVisualProofSessionFingerprint,
   createCaptureDiagnostic,
+  createCodexExecAgentAdapter,
+  createCodexExecJsonRunner,
   createDisabledRiddleProofAgentAdapter,
+  createRiddleProofRunCard,
   createRunResult,
   createRunState,
   createRunStatusSnapshot,
@@ -6014,6 +7235,7 @@ function parseJson(value) {
   readRiddleProofRunStatus,
   recordValue,
   redactForProofDiagnostics,
+  runCodexExecAgentDoctor,
   runRiddleProof,
   runRiddleProofEngineHarness,
   setRunStatus,