@riddledc/riddle-proof 0.5.0 → 0.5.2

package/dist/proof-run-engine.cjs

@@ -0,0 +1,2499 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/proof-run-engine.ts
+var proof_run_engine_exports = {};
+__export(proof_run_engine_exports, {
+  createRiddleProofEngine: () => createRiddleProofEngine,
+  executeWorkflow: () => executeWorkflow
+});
+module.exports = __toCommonJS(proof_run_engine_exports);
+var import_node_child_process = require("child_process");
+var import_node_fs2 = require("fs");
+var import_node_path2 = __toESM(require("path"), 1);
+
+// src/proof-run-core.ts
+var import_node_fs = require("fs");
+var import_node_crypto = require("crypto");
+var import_node_path = __toESM(require("path"), 1);
+var import_node_url = require("url");
+var import_meta = {};
+var WORKFLOW_STAGE_ORDER = ["setup", "recon", "author", "implement", "verify", "ship"];
+var CHECKPOINT_CONTRACT_VERSION = "riddle-proof-run.checkpoint.v1";
+function currentDistDir() {
+  const meta = typeof import_meta === "object" ? import_meta : {};
+  if (typeof meta.url === "string" && meta.url) {
+    return import_node_path.default.dirname((0, import_node_url.fileURLToPath)(meta.url));
+  }
+  if (typeof __dirname === "string") return __dirname;
+  return process.cwd();
+}
+var BUNDLED_RIDDLE_PROOF_DIR = import_node_path.default.resolve(
+  currentDistDir(),
+  "..",
+  "runtime"
+);
+var RIDDLE_PROOF_DIR_CANDIDATES = [
+  BUNDLED_RIDDLE_PROOF_DIR
+];
+function createWorkflowStatePath() {
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+  return `/tmp/riddle-proof-state-${stamp}-${(0, import_node_crypto.randomUUID)().slice(0, 8)}.json`;
+}
+function argsPathForStatePath(statePath) {
+  const base = import_node_path.default.basename(statePath);
+  if (base.startsWith("riddle-proof-state")) {
+    return import_node_path.default.join(import_node_path.default.dirname(statePath), base.replace("riddle-proof-state", "riddle-proof-args"));
+  }
+  return import_node_path.default.join(import_node_path.default.dirname(statePath), `${base}.args.json`);
+}
+function isRiddleProofSkillDir(candidate) {
+  return (0, import_node_fs.existsSync)(workflowFile(candidate, "setup"));
+}
+function resolveRiddleProofDir(config = {}) {
+  if (config.riddleProofDir) return config.riddleProofDir;
+  const candidates = [
+    process.env.RIDDLE_PROOF_DIR,
+    ...RIDDLE_PROOF_DIR_CANDIDATES
+  ].filter((candidate) => Boolean(candidate));
+  return candidates.find(isRiddleProofSkillDir) || candidates.find((candidate) => (0, import_node_fs.existsSync)(candidate)) || RIDDLE_PROOF_DIR_CANDIDATES[0];
+}
+function resolveConfig(config = {}, params = {}) {
+  const configuredStatePath = config.statePath || "";
+  const shouldIsolateWorkflow = !params.state_path && !configuredStatePath && (params.action === "setup" || params.action === "run");
+  const statePath = params.state_path || (shouldIsolateWorkflow ? createWorkflowStatePath() : configuredStatePath || "/tmp/riddle-proof-state.json");
+  return {
+    riddleProofDir: resolveRiddleProofDir(config),
+    statePath,
+    argsPath: argsPathForStatePath(statePath),
+    defaultReviewer: config.defaultReviewer || "davisdiehl"
+  };
+}
+function ensureAction(action) {
+  if (["setup", "recon", "author", "implement", "verify", "ship", "status", "sync", "run"].includes(action)) {
+    return action;
+  }
+  throw new Error(`Unsupported action: ${action}`);
+}
+function workflowFile(riddleProofDir, action) {
+  return import_node_path.default.join(riddleProofDir, "pipelines", `riddle-proof-${action}.lobster`);
+}
+function buildSetupArgs(params, config) {
+  if (!params.repo) throw new Error("repo is required for setup/run");
+  if (!params.change_request) throw new Error("change_request is required for setup/run");
+  const commitMessage = (params.commit_message || params.change_request || "").trim();
+  const captureScript = (params.capture_script || "").trim();
+  const requestedReference = params.reference || (params.prod_url ? "both" : "before");
+  const reference = !params.prod_url && requestedReference !== "before" ? "before" : requestedReference;
+  if (!commitMessage) throw new Error("commit_message is required for setup/run");
+  return {
+    repo: params.repo,
+    branch: params.branch || "",
+    change_request: params.change_request,
+    commit_message: commitMessage,
+    prod_url: params.prod_url || "",
+    capture_script: captureScript,
+    success_criteria: params.success_criteria || "",
+    assertions_json: params.assertions_json || "",
+    verification_mode: params.verification_mode || "proof",
+    reference,
+    base_branch: params.base_branch || "main",
+    before_ref: params.before_ref || "",
+    allow_static_preview_fallback: params.allow_static_preview_fallback ? "true" : "",
+    context: params.context || "",
+    reviewer: params.reviewer || config.defaultReviewer,
+    mode: params.mode || "",
+    build_command: params.build_command || "npm run build",
+    build_output: params.build_output || "build",
+    server_image: params.server_image || "node:20-slim",
+    server_command: params.server_command || "npm start",
+    server_port: String(params.server_port || 3e3),
+    server_path: params.server_path || "",
+    server_path_source: params.server_path ? "user" : "",
+    use_auth: params.use_auth ? "true" : "",
+    auth_localStorage_json: params.auth_localStorage_json || "",
+    auth_cookies_json: params.auth_cookies_json || "",
+    auth_headers_json: params.auth_headers_json || "",
+    color_scheme: params.color_scheme || "",
+    wait_for_selector: params.wait_for_selector || "",
+    discord_channel: params.discord_channel || "",
+    discord_thread_id: params.discord_thread_id || "",
+    discord_message_id: params.discord_message_id || "",
+    discord_source_url: params.discord_source_url || "",
+    leave_draft: params.leave_draft ? "true" : ""
+  };
+}
+function readState(statePath) {
+  if (!(0, import_node_fs.existsSync)(statePath)) {
+    return null;
+  }
+  return JSON.parse((0, import_node_fs.readFileSync)(statePath, "utf-8"));
+}
+function writeState(statePath, state) {
+  (0, import_node_fs.writeFileSync)(statePath, JSON.stringify(state, null, 2));
+}
+function normalizeOptionalString(value) {
+  return typeof value === "string" ? value.trim() : void 0;
+}
+function knownEnvironmentIssuesFromNotes(notes) {
+  const text = notes.toLowerCase();
+  const issues = [];
+  if ((text.includes("erofs") || text.includes("read-only file system")) && text.includes("node_modules") && (text.includes(".vite-temp") || text.includes("vite.config"))) {
+    issues.push({
+      code: "vite_temp_config_erofs",
+      source: "implementation_notes",
+      severity: "environment",
+      summary: "Focused build verification hit the known Vite temp-config EROFS issue in shared node_modules."
+    });
+  }
+  return issues;
+}
+function guardProofEvidenceGlobalAssignments(script) {
+  return script.replace(
+    /^(\s*)(globalThis|window|self)\.__riddleProofEvidence\s*=\s*([^;\n]+);\s*$/gm,
+    (_match, indent, root, expression) => `${indent}try { if (typeof ${root} !== "undefined" && ${root}) ${root}.__riddleProofEvidence = ${expression.trim()}; } catch {}`
+  );
+}
+function normalizeCaptureScript(value) {
+  const script = normalizeOptionalString(value) || "";
+  return script ? guardProofEvidenceGlobalAssignments(script) : "";
+}
+function appendProofSummaryLine(state, line) {
+  const text = String(line || "").trim();
+  if (!text) return;
+  const existing = typeof state.proof_summary === "string" ? state.proof_summary.trim() : "";
+  if (existing.includes(text)) return;
+  state.proof_summary = existing ? `${existing}
+${text}` : text;
+}
+function hasAuthoredProofPlan(state = {}) {
+  return Boolean((state?.proof_plan || "").trim()) && Boolean((state?.capture_script || "").trim());
+}
+function syncAuthoringState(state = {}) {
+  const reconReady = ["ready_for_proof_plan", "completed"].includes(state?.recon_status || "");
+  const reconBlocked = ["needs_agent_decision", "needs_supervisor_judgment"].includes(state?.recon_status || "");
+  const reconExhausted = state?.recon_status === "exhausted";
+  if (reconBlocked) {
+    state.author_status = "needs_recon_judgment";
+  } else if (reconExhausted) {
+    state.author_status = "recon_exhausted";
+  } else if (!reconReady) {
+    state.author_status = state.author_status || "pending_recon";
+  } else if (state.author_status === "ready" || state.proof_plan_status === "ready") {
+    state.author_status = "ready";
+  } else {
+    state.author_status = "needs_authoring";
+  }
+  if (reconBlocked) {
+    state.proof_plan_status = "needs_recon_judgment";
+  } else if (reconExhausted) {
+    state.proof_plan_status = "recon_exhausted";
+  } else if (state.author_status === "ready" || state.proof_plan_status === "ready") {
+    state.proof_plan_status = "ready";
+  } else if (reconReady) {
+    state.proof_plan_status = "needs_authoring";
+  } else {
+    state.proof_plan_status = state.proof_plan_status || "pending_recon";
+  }
+  state.author_request = state.author_request || {};
+  state.author_summary = state.author_summary || "";
+  return state;
+}
+function ensureStageLoopState(state = {}) {
+  if (!state || typeof state !== "object") return state;
+  syncAuthoringState(state);
+  state.explicit_stage_gate = true;
+  state.stage_attempts = state.stage_attempts || {};
+  for (const stage of WORKFLOW_STAGE_ORDER) {
+    const current = state.stage_attempts[stage] || {};
+    state.stage_attempts[stage] = {
+      count: Number(current.count || 0),
+      last_status: current.last_status || null,
+      last_checkpoint: current.last_checkpoint || null,
+      last_summary: current.last_summary || null,
+      last_attempted_at: current.last_attempted_at || null,
+      history: Array.isArray(current.history) ? current.history : []
+    };
+  }
+  state.stage_decision_request = state.stage_decision_request || {};
+  state.active_checkpoint = state.active_checkpoint || null;
+  state.active_checkpoint_stage = state.active_checkpoint_stage || null;
+  state.last_requested_advance_stage = state.last_requested_advance_stage || null;
+  return state;
+}
+function clearStageDecisionRequest(state = {}) {
+  ensureStageLoopState(state);
+  state.stage_decision_request = {};
+  state.active_checkpoint = null;
+  state.active_checkpoint_stage = null;
+  return state;
+}
+function recordStageAttempt(state, stage, entry = {}) {
+  ensureStageLoopState(state);
+  const bucket = state.stage_attempts[stage];
+  const attemptNumber = Number(bucket.count || 0) + 1;
+  const item = {
+    attempt: attemptNumber,
+    stage,
+    status: entry.status || "completed",
+    checkpoint: entry.checkpoint || null,
+    summary: entry.summary || null,
+    requested_advance_stage: entry.requestedAdvanceStage || null,
+    halted_for_approval: Boolean(entry.haltedForApproval),
+    auto_approved: Boolean(entry.autoApproved),
+    error: entry.error || null,
+    details: entry.details || {},
+    attempted_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  bucket.count = attemptNumber;
+  bucket.last_status = item.status;
+  bucket.last_checkpoint = item.checkpoint;
+  bucket.last_summary = item.summary;
+  bucket.last_attempted_at = item.attempted_at;
+  bucket.history = [...bucket.history, item].slice(-25);
+  state.stage_attempts[stage] = bucket;
+  state.last_requested_advance_stage = entry.requestedAdvanceStage || state.last_requested_advance_stage || null;
+  return item;
+}
+function setStageDecisionRequest(state, request) {
+  ensureStageLoopState(state);
+  const continueWithStage = request.continueWithStage || request.recommendedAdvanceStage || null;
+  state.active_checkpoint = request.checkpoint;
+  state.active_checkpoint_stage = request.stage;
+  state.stage_decision_request = {
+    stage: request.stage,
+    checkpoint: request.checkpoint,
+    summary: request.summary,
+    next_actions: request.nextActions || [],
+    advance_options: request.advanceOptions || [],
+    recommended_advance_stage: request.recommendedAdvanceStage || null,
+    continue_from_checkpoint: Boolean(continueWithStage),
+    continue_with_stage: continueWithStage,
+    blocking: Boolean(request.blocking),
+    details: request.details || {},
+    checkpoint_contract: request.checkpointContract || null,
+    updated_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return state.stage_decision_request;
+}
+function checkpointContinueStage(state) {
+  ensureStageLoopState(state);
+  const stage = state?.stage_decision_request?.continue_with_stage || state?.stage_decision_request?.recommended_advance_stage || null;
+  return WORKFLOW_STAGE_ORDER.includes(stage) ? stage : null;
+}
+function invalidateVerifyEvidence(state = {}) {
+  if (!state || typeof state !== "object") {
+    return { invalidated: false };
+  }
+  const hadAfterCdn = typeof state.after_cdn === "string" && state.after_cdn.trim().length > 0;
+  const hadVerifyResults = Boolean(state.verify_results && Object.keys(state.verify_results).length > 0);
+  const hadMergeRecommendation = typeof state.merge_recommendation === "string" && state.merge_recommendation.trim().length > 0;
+  const hadProofSummary = typeof state.proof_summary === "string" && state.proof_summary.trim().length > 0;
+  const hadVerifyStatus = typeof state.verify_status === "string" && state.verify_status.trim().length > 0;
+  const hadVerifySummary = typeof state.verify_summary === "string" && state.verify_summary.trim().length > 0;
+  const hadVerifyDecisionRequest = Boolean(state.verify_decision_request && Object.keys(state.verify_decision_request).length > 0);
+  const hadEvidenceNotes = Array.isArray(state.evidence_notes) && state.evidence_notes.length > 0;
+  const hadProofAssessment = Boolean(state.proof_assessment && Object.keys(state.proof_assessment).length > 0);
+  const hadProofAssessmentRequest = Boolean(state.proof_assessment_request && Object.keys(state.proof_assessment_request).length > 0);
+  const invalidated = hadAfterCdn || hadVerifyResults || hadMergeRecommendation || hadProofSummary || hadVerifyStatus || hadVerifySummary || hadVerifyDecisionRequest || hadEvidenceNotes || hadProofAssessment || hadProofAssessmentRequest;
+  if (invalidated) {
+    state.after_cdn = "";
+    state.verify_results = {};
+    state.verify_status = "";
+    state.verify_summary = "";
+    state.verify_decision_request = {};
+    state.merge_recommendation = null;
+    state.proof_summary = "";
+    state.evidence_notes = [];
+    state.proof_assessment = {};
+    state.proof_assessment_source = null;
+    state.proof_assessment_request = {};
+  }
+  return {
+    invalidated,
+    hadAfterCdn,
+    hadVerifyResults,
+    hadMergeRecommendation,
+    hadProofSummary,
+    hadVerifyStatus,
+    hadVerifySummary,
+    hadVerifyDecisionRequest,
+    hadEvidenceNotes,
+    hadProofAssessment,
+    hadProofAssessmentRequest
+  };
+}
+function normalizedReference(state = {}) {
+  const reference = String(state?.requested_reference || state?.reference || "before").trim();
+  return reference || "before";
+}
+function normalizedProofAssessment(state = {}) {
+  const proofAssessment = state?.proof_assessment || {};
+  const source = String(proofAssessment?.source || state?.proof_assessment_source || "").trim().toLowerCase();
+  const decision = String(proofAssessment?.decision || "").trim();
+  return {
+    decision: decision || null,
+    source: source || null
+  };
+}
+function requiredBaselineLabelsForState(state = {}) {
+  const reference = normalizedReference(state);
+  const labels = [];
+  if (reference === "before" || reference === "both") labels.push("before");
+  if (reference === "prod" || reference === "both") labels.push("prod");
+  return labels;
+}
+function validateShipGate(state = {}) {
+  const reference = normalizedReference(state);
+  const prodUrl = String(state?.prod_url || "").trim();
+  const beforeCdn = String(state?.before_cdn || "").trim();
+  const prodCdn = String(state?.prod_cdn || "").trim();
+  const afterCdn = String(state?.after_cdn || "").trim();
+  const verifyStatus = String(state?.verify_status || "").trim();
+  const proofAssessment = normalizedProofAssessment(state);
+  const reasons = [];
+  if (!["before", "prod", "both"].includes(reference)) {
+    reasons.push(`reference must be before, prod, or both; got ${reference}`);
+  }
+  const requiredBaselines = requiredBaselineLabelsForState(state);
+  if (requiredBaselines.includes("before") && !beforeCdn) {
+    reasons.push("before_cdn is required before ship");
+  }
+  if (requiredBaselines.includes("prod")) {
+    if (!prodUrl) {
+      reasons.push(`prod_url is required when reference=${reference}`);
+    }
+    if (!prodCdn) {
+      reasons.push("prod_cdn is required before ship");
+    }
+  }
+  if (!afterCdn) {
+    reasons.push("after_cdn is required before ship");
+  }
+  if (verifyStatus !== "evidence_captured") {
+    reasons.push("verify_status must be evidence_captured before ship");
+  }
+  if (!["supervising_agent", "supervisor"].includes(proofAssessment.source || "")) {
+    reasons.push("proof_assessment.source must be supervising_agent before ship");
+  }
+  if (proofAssessment.decision !== "ready_to_ship") {
+    reasons.push("proof_assessment.decision must be ready_to_ship before ship");
+  }
+  return {
+    ok: reasons.length === 0,
+    reasons,
+    required_baselines: requiredBaselines,
+    evidence: {
+      reference,
+      prod_url: prodUrl || null,
+      before_cdn: beforeCdn || null,
+      prod_cdn: prodCdn || null,
+      after_cdn: afterCdn || null,
+      verify_status: verifyStatus || null,
+      proof_assessment_decision: proofAssessment.decision,
+      proof_assessment_source: proofAssessment.source
+    }
+  };
+}
+var CHECKPOINT_CONTRACT_SPECS = {
+  setup_review: {
+    purpose: "Inspect prepared workspace state before moving into recon."
+  },
+  recon_supervisor_judgment: {
+    purpose: "Supervising agent judges the latest recon attempt and either retries recon, promotes baselines for authoring, or escalates.",
+    accepted_inputs: [{
+      name: "recon_assessment_json",
+      type: "json",
+      required: true,
+      description: "JSON assessment with decision, summary, baseline_understanding, continue_with_stage, escalation_target, refined_inputs, and reasons."
+    }],
+    response_schema: {
+      decision: ["retry_recon", "ready_for_author", "recon_stuck"],
+      summary: "string",
+      baseline_understanding: {
+        reference: ["before", "prod", "both", "unknown"],
+        target_route: "string",
+        before_evidence_url: "string",
+        visible_before_state: "string",
+        relevant_elements: ["string"],
+        requested_change: "string",
+        proof_focus: "string",
+        stop_condition: "string",
+        quality_risks: ["string"]
+      },
+      continue_with_stage: ["recon", "author"],
+      escalation_target: ["agent", "human"],
+      refined_inputs: {
+        server_path: "string",
+        wait_for_selector: "string",
+        reference: ["before", "prod", "both"]
+      },
+      reasons: ["string"],
+      source: "supervising_agent"
+    },
+    required_state: ["recon_assessment_request", "recon_results.attempt_history"]
+  },
+  recon_review: {
+    purpose: "Recon baselines were promoted and the workflow is ready for proof authoring."
+  },
+  recon_human_escalation: {
+    purpose: "Recon is explicitly blocked for human direction after supervising-agent escalation."
+  },
+  author_supervisor_judgment: {
+    purpose: "Supervising agent authors the proof packet from recon observations.",
+    accepted_inputs: [{
+      name: "author_packet_json",
+      type: "json",
+      required: true,
+      description: "JSON proof packet with proof_plan, capture_script, optional refined_inputs, rationale, confidence, and summary."
+    }],
+    response_schema: {
+      proof_plan: "string",
+      capture_script: "string",
+      baseline_understanding_used: {
+        reference: ["before", "prod", "both", "unknown"],
+        target_route: "string",
+        before_evidence_url: "string",
+        visible_before_state: "string",
+        relevant_elements: ["string"],
+        requested_change: "string",
+        proof_focus: "string",
+        stop_condition: "string",
+        quality_risks: ["string"]
+      },
+      refined_inputs: {
+        server_path: "string",
+        wait_for_selector: "string",
+        reference: ["before", "prod", "both"]
+      },
+      rationale: ["string"],
+      confidence: "low | medium | high",
+      summary: "string"
+    },
+    required_state: ["author_request", "recon_results.baselines"]
+  },
+  author_review: {
+    purpose: "Proof packet is ready; choose whether to inspect, re-author, implement, or verify."
+  },
+  implement_changes_missing: {
+    purpose: "Implementation stage did not detect material code changes.",
+    accepted_inputs: [{
+      name: "make_code_changes",
+      type: "external_action",
+      required: true,
+      description: "Make the actual code changes in the after worktree, then resume the implement stage."
+    }]
+  },
+  implement_review: {
+    purpose: "Implementation changes were detected and stale verify evidence, if any, was invalidated."
+  },
+  implement_required: {
+    purpose: "Verify cannot run until implementation changes are recorded.",
+    accepted_inputs: [{
+      name: "make_code_changes",
+      type: "external_action",
+      required: true,
+      description: "Make the requested code change, then advance the run to implement."
+    }]
+  },
+  verify_capture_retry: {
+    purpose: "Verify capture was incomplete; the agent loop should revise capture authoring before shipping.",
+    accepted_inputs: [{
+      name: "author_packet_json",
+      type: "json",
+      description: "Optional revised proof packet if returning to author."
+    }],
+    required_state: ["verify_decision_request"]
+  },
+  verify_supervisor_judgment: {
+    purpose: "Supervising agent judges whether captured evidence proves the change is ready to ship.",
+    accepted_inputs: [{
+      name: "proof_assessment_json",
+      type: "json",
+      required: true,
+      description: "JSON assessment with decision, summary, recommended_stage, continue_with_stage, escalation_target, and reasons."
+    }],
+    response_schema: {
+      decision: ["ready_to_ship", "needs_richer_proof"],
+      summary: "string",
+      recommended_stage: ["ship", "author", "implement", "recon", "verify"],
+      continue_with_stage: ["ship", "author", "implement", "recon", "verify"],
+      escalation_target: ["agent", "human"],
+      reasons: ["string"],
+      source: "supervising_agent"
+    },
+    required_state: ["before_cdn or prod_cdn", "after_cdn", "proof_assessment_request"],
+    include_ship_gate: true
+  },
+  verify_human_escalation: {
+    purpose: "Proof loop is explicitly escalated to the human after supervising-agent judgment."
+  },
+  verify_agent_retry: {
+    purpose: "Supervising agent judged the proof insufficient and kept the workflow inside the internal loop.",
+    accepted_inputs: [{
+      name: "author_packet_json",
+      type: "json",
+      description: "Optional revised proof packet if the checkpoint resumes to author."
+    }]
+  },
+  verify_ship_ready: {
+    purpose: "Proof assessment is ready_to_ship and the next continuation should enter ship.",
+    include_ship_gate: true
+  },
+  verify_required: {
+    purpose: "Ship is blocked until verify captures usable after evidence.",
+    include_ship_gate: true
+  },
+  verify_supervisor_judgment_required: {
+    purpose: "Ship is blocked until the supervising agent judges the current evidence ready_to_ship.",
+    accepted_inputs: [{
+      name: "proof_assessment_json",
+      type: "json",
+      required: true,
+      description: "JSON assessment that must use decision=ready_to_ship before ship can continue."
+    }],
+    include_ship_gate: true
+  },
+  ship_gate_blocked: {
+    purpose: "Ship is blocked because required baseline, after evidence, or supervising-agent proof approval is missing.",
+    include_ship_gate: true
+  },
+  ship_review: {
+    purpose: "Ship completed; inspect the PR, proof comment, and CI status.",
+    include_ship_gate: true
+  }
+};
+function buildCheckpointContract(state, request) {
+  const spec = CHECKPOINT_CONTRACT_SPECS[request.checkpoint] || {
+    purpose: request.summary
+  };
+  const continueWithStage = request.continueWithStage || request.recommendedAdvanceStage || null;
+  const payload = {
+    version: CHECKPOINT_CONTRACT_VERSION,
+    checkpoint: request.checkpoint,
+    stage: request.stage,
+    purpose: spec.purpose,
+    summary: request.summary,
+    blocking: Boolean(request.blocking),
+    next_actions: request.nextActions || [],
+    advance_options: request.advanceOptions || [],
+    accepted_inputs: spec.accepted_inputs || [],
+    response_schema: spec.response_schema || null,
+    required_state: spec.required_state || [],
+    resume: {
+      action: "run",
+      state_path: request.statePath || null,
+      continue_from_checkpoint: Boolean(continueWithStage),
+      continue_with_stage: continueWithStage
+    }
+  };
+  if (spec.include_ship_gate) {
+    payload.ship_gate = validateShipGate(state);
+  }
+  return payload;
+}
+function mergeStateFromParams(statePath, params) {
+  const state = readState(statePath);
+  if (!state) return null;
+  ensureStageLoopState(state);
+  const stringFields = [
+    "change_request",
+    "commit_message",
+    "prod_url",
+    "capture_script",
+    "success_criteria",
+    "assertions_json",
+    "verification_mode",
+    "base_branch",
+    "before_ref",
+    "context",
+    "reviewer",
+    "build_command",
+    "build_output",
+    "server_image",
+    "server_command",
+    "server_path",
+    "wait_for_selector",
+    "discord_channel",
+    "discord_thread_id",
+    "discord_message_id",
+    "discord_source_url",
+    "auth_localStorage_json",
+    "auth_cookies_json",
+    "auth_headers_json",
+    "proof_plan",
+    "implementation_notes"
+  ];
+  for (const field of stringFields) {
+    if (params[field] !== void 0) {
+      state[field] = normalizeOptionalString(params[field]);
+    }
+  }
+  if (params.server_path !== void 0) {
+    state.server_path_source = "tool_param";
+  }
+  if (params.implementation_notes !== void 0) {
+    const issues = knownEnvironmentIssuesFromNotes(state.implementation_notes || "");
+    if (issues.length) state.implementation_environment_issues = issues;
+  }
+  if (params.reference !== void 0) state.reference = params.reference;
+  if (params.mode !== void 0) state.mode = params.mode;
+  if (params.allow_static_preview_fallback !== void 0) {
+    state.allow_static_preview_fallback = params.allow_static_preview_fallback;
+  }
+  if (params.server_port !== void 0) state.server_port = String(params.server_port);
+  if (params.color_scheme !== void 0) state.color_scheme = params.color_scheme || "";
+  if (params.use_auth !== void 0) state.use_auth = params.use_auth ? "true" : "";
+  if (params.leave_draft !== void 0) state.leave_draft = params.leave_draft ? "true" : "";
+  if (params.advance_stage !== void 0) state.last_requested_advance_stage = params.advance_stage;
+  if (params.recon_assessment_json !== void 0) {
+    const raw = normalizeOptionalString(params.recon_assessment_json) || "";
+    if (!raw) {
+      state.recon_assessment = {};
+      state.recon_assessment_source = null;
+    } else {
+      const parsed = JSON.parse(raw);
+      state.recon_assessment = {
+        ...parsed,
+        source: (parsed?.source || "supervising_agent").toString()
+      };
+      state.recon_assessment_source = state.recon_assessment.source;
+      if (parsed?.baseline_understanding && typeof parsed.baseline_understanding === "object") {
+        state.recon_baseline_understanding = parsed.baseline_understanding;
+      }
+      const refined = parsed?.refined_inputs || {};
+      if (typeof refined?.server_path === "string") {
+        state.server_path = normalizeOptionalString(refined.server_path) || "";
+        state.server_path_source = "supervising_agent";
+      }
+      if (typeof refined?.wait_for_selector === "string") state.wait_for_selector = normalizeOptionalString(refined.wait_for_selector) || "";
+      if (typeof refined?.reference === "string" && refined.reference.trim()) state.reference = refined.reference.trim();
+    }
+  }
+  if (params.author_packet_json !== void 0) {
+    const raw = normalizeOptionalString(params.author_packet_json) || "";
+    if (!raw) {
+      state.supervisor_author_packet = null;
+    } else {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed?.capture_script === "string") {
+        parsed.capture_script = normalizeCaptureScript(parsed.capture_script);
+      }
+      state.supervisor_author_packet = parsed;
+      if (typeof parsed?.proof_plan === "string") state.proof_plan = normalizeOptionalString(parsed.proof_plan) || "";
+      if (typeof parsed?.capture_script === "string") state.capture_script = normalizeCaptureScript(parsed.capture_script);
+      if (parsed?.baseline_understanding_used && typeof parsed.baseline_understanding_used === "object") {
+        state.author_baseline_understanding_used = parsed.baseline_understanding_used;
+      }
+      const refined = parsed?.refined_inputs || {};
+      if (typeof refined?.server_path === "string") {
+        state.server_path = normalizeOptionalString(refined.server_path) || "";
+        state.server_path_source = "supervising_agent";
+      }
+      if (typeof refined?.wait_for_selector === "string") state.wait_for_selector = normalizeOptionalString(refined.wait_for_selector) || "";
+      if (typeof refined?.reference === "string" && refined.reference.trim()) state.reference = refined.reference.trim();
+      if (typeof parsed?.confidence === "string") state.supervisor_author_confidence = normalizeOptionalString(parsed.confidence) || null;
+      if (parsed?.rationale !== void 0) state.supervisor_author_rationale = parsed.rationale;
+      if (typeof parsed?.summary === "string") state.supervisor_author_summary = normalizeOptionalString(parsed.summary) || null;
+      invalidateVerifyEvidence(state);
+    }
+  }
+  if (params.proof_assessment_json !== void 0) {
+    const raw = normalizeOptionalString(params.proof_assessment_json) || "";
+    if (!raw) {
+      state.proof_assessment = {};
+      state.proof_assessment_source = null;
+    } else {
+      const parsed = JSON.parse(raw);
+      state.proof_assessment = {
+        ...parsed,
+        source: (parsed?.source || "supervising_agent").toString()
+      };
+      state.proof_assessment_source = state.proof_assessment.source;
+      if (typeof parsed?.decision === "string") {
+        state.proof_decision = parsed.decision;
+      }
+      if (typeof parsed?.summary === "string") {
+        state.proof_assessment_summary = normalizeOptionalString(parsed.summary) || null;
+      }
+      if (parsed?.decision === "ready_to_ship") {
+        state.merge_recommendation = "ready-to-ship";
+      } else if (typeof parsed?.decision === "string" && parsed.decision.trim()) {
+        state.merge_recommendation = "do-not-merge";
+      }
+      appendProofSummaryLine(state, `Supervising proof assessment: ${state.proof_assessment.decision || "unknown"}`);
+      if (state.proof_assessment_summary) {
+        appendProofSummaryLine(state, `Assessment summary: ${state.proof_assessment_summary}`);
+      }
+      const reasons = Array.isArray(parsed?.reasons) ? parsed.reasons.filter((item) => typeof item === "string" && item.trim()).slice(0, 4) : [];
+      if (reasons.length) {
+        appendProofSummaryLine(state, `Assessment reasons: ${reasons.join("; ")}`);
+      }
+    }
+  }
+  if (params.assertions_json !== void 0) {
+    const raw = normalizeOptionalString(params.assertions_json) || "";
+    if (!raw) {
+      state.parsed_assertions = null;
+    } else {
+      state.parsed_assertions = JSON.parse(raw);
+    }
+  }
+  if ((params.proof_plan !== void 0 || params.capture_script !== void 0) && hasAuthoredProofPlan(state)) {
+    state.author_summary = state.author_summary || "Proof authoring inputs were updated from tool params.";
+  }
+  syncAuthoringState(state);
+  writeState(statePath, state);
+  return state;
+}
+function summarizeState(state) {
+  if (!state) {
+    return {
+      stage: "missing",
+      summary: "No riddle-proof state file exists yet.",
+      state: null
+    };
+  }
+  ensureStageLoopState(state);
+  const attemptCounts = Object.fromEntries(
+    WORKFLOW_STAGE_ORDER.map((stage) => [stage, Number(state.stage_attempts?.[stage]?.count || 0)])
+  );
+  const selected = {
+    workspace_ready: Boolean(state.workspace_ready),
+    repo: state.repo || null,
+    branch: state.branch || null,
+    mode: state.mode || null,
+    reference: state.reference || null,
+    before_ref: state.before_ref || null,
+    allow_static_preview_fallback: Boolean(state.allow_static_preview_fallback),
+    commit_message: state.commit_message || null,
+    author_status: state.author_status || null,
+    author_summary: state.author_summary || null,
+    author_request: state.author_request || null,
+    proof_plan_status: state.proof_plan_status || null,
+    proof_plan: state.proof_plan || null,
+    proof_plan_request: state.proof_plan_request || null,
+    proof_profile_applied: Boolean(state.proof_profile),
+    proof_profile: state.proof_profile || null,
+    recon_status: state.recon_status || null,
+    recon_assessment: state.recon_assessment || null,
+    recon_assessment_request: state.recon_assessment_request || null,
+    recon_assessment_source: state.recon_assessment_source || null,
+    recon_decision_request: state.recon_decision_request || null,
+    recon_attempts_used: Array.isArray(state.recon_results?.attempt_history) ? state.recon_results.attempt_history.length : 0,
+    recon_attempts_max: state.recon_results?.max_attempts || null,
+    recon_hypothesis: state.recon_hypothesis || null,
+    implementation_status: state.implementation_status || null,
+    implementation_summary: state.implementation_summary || null,
+    implementation_environment_issues: state.implementation_environment_issues || [],
+    verify_status: state.verify_status || null,
+    verify_summary: state.verify_summary || null,
+    verify_decision_request: state.verify_decision_request || null,
+    proof_assessment: state.proof_assessment || null,
+    proof_assessment_request: state.proof_assessment_request || null,
+    proof_assessment_source: state.proof_assessment_source || null,
+    merge_recommendation: state.merge_recommendation || null,
+    before_cdn: state.before_cdn || null,
+    after_cdn: state.after_cdn || null,
+    prod_cdn: state.prod_cdn || null,
+    pr_url: state.pr_url || null,
+    pr_branch: state.target_branch || state.branch || null,
+    pr_state: state.pr_state || null,
+    ship_commit: state.ship_commit || null,
+    ship_remote_head: state.ship_remote_head || null,
+    merge_commit: state.merge_commit || null,
+    merged_at: state.merged_at || null,
+    ship_push: state.ship_push || null,
+    ship_report: state.ship_report || null,
+    cleanup_report: state.cleanup_report || null,
+    proof_comment_url: state.proof_comment_url || null,
+    proof_assessment_comment_url: state.proof_assessment_comment_url || null,
+    marked_ready: typeof state.marked_ready === "boolean" ? state.marked_ready : null,
+    left_draft: typeof state.left_draft === "boolean" ? state.left_draft : null,
+    ci_status: state.ci_status || null,
+    reviewer: state.reviewer || null,
+    active_checkpoint: state.active_checkpoint || null,
+    active_checkpoint_stage: state.active_checkpoint_stage || null,
+    continue_with_stage: checkpointContinueStage(state),
+    stage_decision_request: state.stage_decision_request || {},
+    stage_attempt_counts: attemptCounts,
+    explicit_stage_gate: Boolean(state.explicit_stage_gate),
+    last_requested_advance_stage: state.last_requested_advance_stage || null,
+    recon_results: state.recon_results || null,
+    verify_results: state.verify_results || null
+  };
+  const parts = [
+    state.workspace_ready ? "workspace ready" : "workspace not ready",
+    state.mode ? `mode=${state.mode}` : null,
+    state.reference ? `reference=${state.reference}` : null,
+    state.author_status ? `author=${state.author_status}` : null,
+    state.proof_plan_status ? `proof=${state.proof_plan_status}` : null,
+    state.recon_status ? `recon=${state.recon_status}` : null,
+    state.implementation_status ? `implement=${state.implementation_status}` : null,
+    state.verify_status ? `verify=${state.verify_status}` : null,
+    state.active_checkpoint ? `checkpoint=${state.active_checkpoint}` : null,
+    state.after_cdn ? "after evidence captured" : null,
+    state.pr_url ? "PR linked" : null
+  ].filter(Boolean);
+  return {
+    stage: state.stage || (state.after_cdn ? "verified" : state.workspace_ready ? "setup" : "unknown"),
+    summary: parts.length ? parts.join(", ") : "State file present.",
+    state: selected
+  };
+}
+
+// src/proof-run-engine.ts
+function snapshotFor(statePath) {
+  return summarizeState(readState(statePath));
+}
+function authorReady(state) {
+  return state?.author_status === "ready" || state?.proof_plan_status === "ready";
+}
+function implementationReady(state) {
+  return ["changes_detected", "completed"].includes(state?.implementation_status || "");
+}
+function stageAfterAuthor(state) {
+  return implementationReady(state) ? "verify" : "implement";
+}
+function latestReconAttempt(state) {
+  const history = Array.isArray(state?.recon_results?.attempt_history) ? state.recon_results.attempt_history : [];
+  return history.length ? history[history.length - 1] : null;
+}
+function latestReconCapturedBaselines(state) {
+  const latest = latestReconAttempt(state);
+  if (latest?.captured_baselines && typeof latest.captured_baselines === "object") return latest.captured_baselines;
+  if (latest?.baselines && typeof latest.baselines === "object") return latest.baselines;
+  return state?.recon_results?.baselines || {};
+}
+function requiredReconBaselineLabels(state) {
+  const labels = [];
+  const reference = state?.requested_reference || state?.reference || "before";
+  if (reference === "before" || reference === "both") labels.push("before");
+  if ((reference === "prod" || reference === "both") && String(state?.prod_url || "").trim()) labels.push("prod");
+  return labels;
+}
+function latestReconHasRequiredBaselines(state) {
+  const baselines = latestReconCapturedBaselines(state);
+  return requiredReconBaselineLabels(state).every((label) => Boolean((baselines?.[label]?.url || "").trim()));
+}
+function hasReconBaselineUnderstanding(state) {
+  const understanding = state?.recon_assessment?.baseline_understanding || state?.recon_baseline_understanding || {};
+  return Boolean(
+    String(understanding?.visible_before_state || "").trim() && String(understanding?.requested_change || "").trim() && String(understanding?.proof_focus || "").trim() && String(understanding?.stop_condition || "").trim()
+  );
+}
+function promoteLatestReconBaselines(state) {
+  const baselines = latestReconCapturedBaselines(state);
+  state.recon_results = state.recon_results || {};
+  state.recon_results.baselines = baselines;
+  state.recon_results.selected_attempt = latestReconAttempt(state) || {};
+  state.before_cdn = (baselines?.before?.url || "").trim();
+  state.prod_cdn = (baselines?.prod?.url || "").trim();
+  return baselines;
+}
+function hasSupervisorReconAssessment(state) {
+  const reconAssessment2 = state?.recon_assessment || {};
+  const source = String(reconAssessment2?.source || state?.recon_assessment_source || "").trim().toLowerCase();
+  if (!reconAssessment2?.decision) return false;
+  return source === "supervising_agent" || source === "supervisor";
+}
+function reconAssessment(state) {
+  const assessment = state?.recon_assessment || {};
+  const decision = assessment?.decision || null;
+  const continueWithStage = assessment?.continue_with_stage || assessment?.recommended_stage || (decision === "ready_for_author" ? "author" : "recon");
+  return {
+    decision,
+    summary: assessment?.summary || state?.recon_assessment_request?.summary || state?.recon_summary || null,
+    recommendedStage: assessment?.recommended_stage || continueWithStage || null,
+    continueWithStage: continueWithStage || null,
+    escalationTarget: assessment?.escalation_target || "agent",
+    reasons: Array.isArray(assessment?.reasons) ? assessment.reasons : [],
+    raw: assessment,
+    source: String(assessment?.source || state?.recon_assessment_source || "").trim() || null
+  };
+}
+function updateState(statePath, mutate) {
+  const state = readState(statePath) || {};
+  mutate(state);
+  writeState(statePath, state);
+  return state;
+}
+function hasSupervisorProofAssessment(state) {
+  const proofAssessment = state?.proof_assessment || {};
+  const source = String(proofAssessment?.source || state?.proof_assessment_source || "").trim().toLowerCase();
+  if (!proofAssessment?.decision) return false;
+  return source === "supervising_agent" || source === "supervisor";
+}
+function verifyAssessment(state) {
+  const proofAssessment = state?.proof_assessment || {};
+  const verifyDecision = state?.verify_decision_request || {};
+  if (hasSupervisorProofAssessment(state)) {
+    return {
+      decision: proofAssessment?.decision || null,
+      summary: proofAssessment?.summary || verifyDecision?.summary || null,
+      recommendedStage: proofAssessment?.continue_with_stage || proofAssessment?.recommended_stage || verifyDecision?.continue_with_stage || verifyDecision?.recommended_stage || null,
+      continueWithStage: proofAssessment?.continue_with_stage || verifyDecision?.continue_with_stage || proofAssessment?.recommended_stage || verifyDecision?.recommended_stage || null,
+      escalationTarget: proofAssessment?.escalation_target || "agent",
+      reasons: Array.isArray(proofAssessment?.reasons) ? proofAssessment.reasons : [],
+      raw: proofAssessment,
+      source: "supervising_agent"
+    };
+  }
+  if (state?.verify_status === "capture_incomplete") {
+    return {
+      decision: verifyDecision?.capture_quality?.decision || "revise_capture",
+      summary: verifyDecision?.summary || "Verify needs another internal capture iteration before the evidence can be judged.",
+      recommendedStage: verifyDecision?.continue_with_stage || verifyDecision?.recommended_stage || "author",
+      continueWithStage: verifyDecision?.continue_with_stage || verifyDecision?.recommended_stage || "author",
+      escalationTarget: "agent",
+      reasons: Array.isArray(verifyDecision?.capture_quality?.reasons) ? verifyDecision.capture_quality.reasons : [],
+      raw: verifyDecision?.capture_quality || verifyDecision,
+      source: "workflow_capture"
+    };
+  }
+  return {
+    decision: null,
+    summary: verifyDecision?.summary || "Verify captured evidence and is waiting for supervising-agent proof assessment.",
+    recommendedStage: null,
+    continueWithStage: null,
+    escalationTarget: "agent",
+    reasons: [],
+    raw: proofAssessment,
+    source: "awaiting_supervisor"
+  };
+}
+function nonConvergenceSignals(state, assessment = verifyAssessment(state)) {
+  const verifyAttempts = Number(state?.stage_attempts?.verify?.count || 0);
+  const authorAttempts = Number(state?.stage_attempts?.author?.count || 0);
+  const reconAttempts = Number(state?.stage_attempts?.recon?.count || 0);
+  const continueStage = assessment.continueWithStage || assessment.recommendedStage || null;
+  return {
+    verifyAttempts,
+    authorAttempts,
+    reconAttempts,
+    continueStage,
+    warning: verifyAttempts >= 4 || continueStage === "author" && verifyAttempts >= 2 && authorAttempts >= 2 || continueStage === "recon" && verifyAttempts >= 2 && reconAttempts >= 2 || continueStage === "implement" && verifyAttempts >= 2
+  };
+}
+function shouldEscalateVerifyToHuman(_state, assessment = verifyAssessment(_state)) {
+  return assessment.escalationTarget === "human";
+}
+function recommendedAdvanceStage(state) {
+  if (!state?.workspace_ready) return "setup";
+  if (!state?.recon_results || ["needs_agent_decision", "needs_supervisor_judgment"].includes(state?.recon_status || "")) return "recon";
+  if (!authorReady(state)) return "author";
+  if (!implementationReady(state)) return "implement";
+  if (state?.verify_status === "capture_incomplete") return verifyAssessment(state).continueWithStage || verifyAssessment(state).recommendedStage || "author";
+  if (state?.verify_status === "evidence_captured") return verifyAssessment(state).continueWithStage || verifyAssessment(state).recommendedStage;
+  if (!(state?.after_cdn || "").trim()) return "verify";
+  return null;
+}
+function normalizeStageRequest(state, requestedAdvanceStage) {
+  if (requestedAdvanceStage) return requestedAdvanceStage;
+  if (!state?.workspace_ready) return null;
+  if (!state?.recon_results || ["needs_agent_decision", "needs_supervisor_judgment"].includes(state?.recon_status || "")) return "recon";
+  return null;
+}
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+function commandResult(command, args, cwd, timeout = 6e4) {
+  try {
+    return {
+      ok: true,
+      stdout: (0, import_node_child_process.execFileSync)(command, args, { cwd, encoding: "utf-8", timeout, stdio: ["ignore", "pipe", "pipe"] }),
+      stderr: ""
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: String(error?.stdout || ""),
+      stderr: String(error?.stderr || error?.message || "")
+    };
+  }
+}
+function repoDirForSync(state) {
+  const candidates = [
+    state?.repo_dir,
+    state?.after_worktree,
+    state?.before_worktree
+  ].map(stringValue).filter(Boolean);
+  return candidates.find((candidate) => (0, import_node_fs2.existsSync)(import_node_path2.default.join(candidate, ".git"))) || "";
+}
+function parseWorktreeList(output) {
+  const entries = [];
+  let current = {};
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.trim()) {
+      if (current.worktree) entries.push(current);
+      current = {};
+      continue;
+    }
+    const [key, ...rest] = line.split(" ");
+    const value = rest.join(" ").trim();
+    if (key === "worktree" || key === "HEAD" || key === "branch" || key === "detached") current[key] = value;
+  }
+  if (current.worktree) entries.push(current);
+  return entries;
+}
+function gitStdout(cwd, args, timeout = 6e4) {
+  const result = commandResult("git", args, cwd, timeout);
+  return result.ok ? result.stdout.trim() : "";
+}
+function shortBranch(ref) {
+  return ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+}
+function safeInteger(value) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function baseCheckoutReport(repoDir, baseBranch, updateRequested, updateAllowed) {
+  const remoteRef = `origin/${baseBranch}`;
+  const report = {
+    requested: updateRequested,
+    repo_dir: repoDir,
+    base_branch: baseBranch,
+    remote_ref: remoteRef,
+    updated: false
+  };
+  const listed = commandResult("git", ["worktree", "list", "--porcelain"], repoDir, 6e4);
+  if (!listed.ok) {
+    report.update_skipped = "worktree_list_failed";
+    report.error = listed.stderr.slice(0, 300);
+    return report;
+  }
+  const worktrees = parseWorktreeList(listed.stdout);
+  const baseRef = `refs/heads/${baseBranch}`;
+  const selected = worktrees.find((entry) => entry.branch === baseRef) || worktrees.find((entry) => import_node_path2.default.resolve(entry.worktree || "") === import_node_path2.default.resolve(repoDir) && shortBranch(entry.branch || "") === baseBranch);
+  if (!selected?.worktree) {
+    report.worktrees_seen = worktrees.map((entry) => ({
+      path: entry.worktree || null,
+      branch: entry.branch ? shortBranch(entry.branch) : null,
+      detached: Boolean(entry.detached)
+    }));
+    report.update_skipped = "base_worktree_not_found";
+    return report;
+  }
+  const baseDir = selected.worktree;
+  const branch = shortBranch(selected.branch || "");
+  const status = commandResult("git", ["status", "--porcelain"], baseDir, 6e4);
+  const clean = status.ok && !status.stdout.trim();
+  const localHead = gitStdout(baseDir, ["rev-parse", "HEAD"]);
+  const remoteHead = gitStdout(baseDir, ["rev-parse", "--verify", remoteRef]);
+  const counts = remoteHead ? gitStdout(baseDir, ["rev-list", "--left-right", "--count", `HEAD...${remoteRef}`]) : "";
+  const [aheadRaw, behindRaw] = counts.split(/\s+/);
+  Object.assign(report, {
+    base_worktree: baseDir,
+    branch: branch || null,
+    clean,
+    local_head: localHead || null,
+    remote_head: remoteHead || null,
+    ahead: safeInteger(aheadRaw || ""),
+    behind: safeInteger(behindRaw || "")
+  });
+  if (!updateRequested) {
+    report.update_skipped = "update_not_requested";
+    return report;
+  }
+  if (!updateAllowed) {
+    report.update_skipped = "fetch_failed";
+    return report;
+  }
+  if (branch !== baseBranch) {
+    report.update_skipped = "base_worktree_not_on_base_branch";
+    return report;
+  }
+  if (!status.ok) {
+    report.update_skipped = "status_failed";
+    report.status_error = status.stderr.slice(0, 300);
+    return report;
+  }
+  if (!clean) {
+    report.update_skipped = "base_worktree_dirty";
+    return report;
+  }
+  if (!remoteHead) {
+    report.update_skipped = "remote_ref_missing";
+    return report;
+  }
+  if (localHead && localHead === remoteHead) {
+    report.update_skipped = "already_current";
+    return report;
+  }
+  const merge = commandResult("git", ["merge", "--ff-only", remoteRef], baseDir, 12e4);
+  if (!merge.ok) {
+    report.update_skipped = "fast_forward_failed";
+    report.update_error = merge.stderr.slice(0, 500);
+    return report;
+  }
+  const updatedHead = gitStdout(baseDir, ["rev-parse", "HEAD"]);
+  const updatedCounts = gitStdout(baseDir, ["rev-list", "--left-right", "--count", `HEAD...${remoteRef}`]);
+  const [updatedAheadRaw, updatedBehindRaw] = updatedCounts.split(/\s+/);
+  report.updated = true;
+  report.local_head = updatedHead || report.local_head;
+  report.ahead = safeInteger(updatedAheadRaw || "");
+  report.behind = safeInteger(updatedBehindRaw || "");
+  report.update_summary = merge.stdout.trim().slice(0, 500);
+  return report;
+}
+function normalizeGhPrStatus(value) {
+  const status = stringValue(value).toLowerCase();
+  if (status === "merged") return "merged";
+  if (status === "open") return "open";
+  if (status === "closed") return "closed";
+  return status || "unknown";
+}
+function prRefFromState(state) {
+  return stringValue(state?.pr_number) || stringValue(state?.pr_url);
+}
+function prNumberFromUrl(url) {
+  const match = url.match(/\/pull\/(\d+)(?:$|[?#])/);
+  return match?.[1] || "";
+}
+function normalizePrState(raw, state, checkedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  const mergeCommit = typeof raw?.mergeCommit === "object" && raw.mergeCommit ? stringValue(raw.mergeCommit.oid) : stringValue(raw?.mergeCommit);
+  const url = stringValue(raw?.url) || stringValue(state?.pr_url);
+  return {
+    status: normalizeGhPrStatus(raw?.state),
+    pr_url: url || null,
+    pr_number: String(raw?.number || state?.pr_number || prNumberFromUrl(url) || ""),
+    repo: stringValue(state?.repo) || null,
+    head_branch: stringValue(raw?.headRefName) || stringValue(state?.target_branch) || stringValue(state?.branch) || null,
+    base_branch: stringValue(raw?.baseRefName) || stringValue(state?.base_branch) || "main",
+    merge_commit: mergeCommit || null,
+    merged_at: stringValue(raw?.mergedAt) || null,
+    closed_at: stringValue(raw?.closedAt) || null,
+    checked_at: checkedAt,
+    source: "gh"
+  };
+}
+function cleanupMergedProofRun(state, repoDir, params, prState) {
+  const cleanup = {
+    requested: params.cleanup_merged_pr !== false,
+    fetch_base: params.fetch_base !== false,
+    update_base_checkout: params.update_base_checkout !== false,
+    repo_dir: repoDir,
+    worktrees_removed: [],
+    worktree_remove_errors: [],
+    branches_deleted: [],
+    branch_delete_errors: [],
+    pruned: false
+  };
+  const baseBranch = stringValue(prState.base_branch) || stringValue(state?.base_branch) || "main";
+  let fetchedBase = params.fetch_base === false;
+  if (params.fetch_base !== false && baseBranch) {
+    const fetch = commandResult("git", ["fetch", "origin", baseBranch], repoDir, 12e4);
+    cleanup.fetch = fetch.ok ? { ok: true, base_branch: baseBranch } : { ok: false, base_branch: baseBranch, error: fetch.stderr.slice(0, 300) };
+    if (fetch.ok) {
+      fetchedBase = true;
+      state.base_synced_at = (/* @__PURE__ */ new Date()).toISOString();
+      state.base_branch = baseBranch;
+    }
+  }
+  cleanup.base_checkout = baseCheckoutReport(repoDir, baseBranch, params.update_base_checkout !== false, fetchedBase);
+  if (params.cleanup_merged_pr === false) {
+    cleanup.skipped = "cleanup_disabled";
+    return cleanup;
+  }
+  const removed = [];
+  const removeErrors = [];
+  for (const candidate of [state?.before_worktree, state?.after_worktree].map(stringValue).filter(Boolean)) {
+    if (!(0, import_node_fs2.existsSync)(candidate) || import_node_path2.default.resolve(candidate) === import_node_path2.default.resolve(repoDir)) continue;
+    const remove = commandResult("git", ["worktree", "remove", "--force", candidate], repoDir, 12e4);
+    if (remove.ok) {
+      removed.push(candidate);
+    } else {
+      removeErrors.push({ path: candidate, error: remove.stderr.slice(0, 300) });
+    }
+  }
+  cleanup.worktrees_removed = removed;
+  cleanup.worktree_remove_errors = removeErrors;
+  const afterBranch = stringValue(state?.after_worktree_branch);
+  if (afterBranch.startsWith("riddle-proof/")) {
+    const deleted = commandResult("git", ["branch", "-D", afterBranch], repoDir, 6e4);
+    if (deleted.ok) {
+      cleanup.branches_deleted = [afterBranch];
+    } else {
+      cleanup.branch_delete_errors = [{ branch: afterBranch, error: deleted.stderr.slice(0, 300) }];
+    }
+  }
+  const prune = commandResult("git", ["worktree", "prune"], repoDir, 6e4);
+  cleanup.pruned = prune.ok;
+  if (!prune.ok) cleanup.prune_error = prune.stderr.slice(0, 300);
+  return cleanup;
+}
+function syncPrLifecycle(statePath, params) {
+  const state = readState(statePath);
+  if (!state) {
+    return {
+      ok: false,
+      action: "sync",
+      state_path: statePath,
+      checkpoint: "pr_sync_not_found",
+      summary: "No readable Riddle Proof state exists at state_path.",
+      state: null,
+      nextAction: "Check the wrapper state_path or run riddle_proof_status first."
+    };
+  }
+  const repoDir = repoDirForSync(state);
+  const prRef = prRefFromState(state);
+  if (!repoDir || !prRef) {
+    const missingPr = !prRef;
+    const orphanSummary = "Riddle Proof state exists, but this run is not recoverable through PR sync because no PR URL or PR number was linked before it stopped.";
+    const orphanNextAction = "Treat this as an orphaned proof run: update the base checkout directly if needed, then clean stale proof worktrees or riddle-proof/* branches outside normal PR sync.";
+    const prState2 = {
+      status: missingPr ? "orphaned" : "unavailable",
+      pr_url: state.pr_url || null,
+      pr_number: String(state.pr_number || prNumberFromUrl(stringValue(state.pr_url)) || ""),
+      repo: state.repo || null,
+      head_branch: state.target_branch || state.branch || null,
+      base_branch: state.base_branch || "main",
+      checked_at: (/* @__PURE__ */ new Date()).toISOString(),
+      source: repoDir ? "state" : "local_state",
+      sync_recoverable: !missingPr,
+      sync_blocker: missingPr ? "missing_pr_linkage" : "missing_local_repo",
+      next_action: missingPr ? orphanNextAction : "State has a PR but no readable local git repo/worktree; restore repo access and rerun sync."
+    };
+    state.pr_state = prState2;
+    if (missingPr) state.pr_sync_summary = orphanSummary;
+    writeState(statePath, state);
+    return {
+      ok: false,
+      action: "sync",
+      state_path: statePath,
+      checkpoint: missingPr ? "pr_sync_no_pr" : "pr_sync_unavailable",
+      summary: missingPr ? orphanSummary : prState2.next_action,
+      state: summarizeState(state).state,
+      pr_state: prState2,
+      nextAction: prState2.next_action
+    };
+  }
+  const viewed = commandResult("gh", ["pr", "view", prRef, "--json", "state,mergedAt,closedAt,mergeCommit,headRefName,baseRefName,url,number"], repoDir, 6e4);
+  if (!viewed.ok) {
+    const prState2 = {
+      status: "unavailable",
+      pr_url: state.pr_url || null,
+      pr_number: String(state.pr_number || prNumberFromUrl(stringValue(state.pr_url)) || ""),
+      repo: state.repo || null,
+      head_branch: state.target_branch || state.branch || null,
+      base_branch: state.base_branch || "main",
+      checked_at: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "gh",
+      next_action: "GitHub PR state is unavailable; fix gh auth/repo access and rerun riddle_proof_sync."
+    };
+    state.pr_state = prState2;
+    state.cleanup_report = { requested: params.cleanup_merged_pr !== false, skipped: "pr_state_unavailable", error: viewed.stderr.slice(0, 300) };
+    writeState(statePath, state);
+    return {
+      ok: false,
+      action: "sync",
+      state_path: statePath,
+      checkpoint: "pr_sync_unavailable",
+      summary: prState2.next_action,
+      state: summarizeState(state).state,
+      pr_state: prState2,
+      cleanup: state.cleanup_report,
+      nextAction: prState2.next_action
+    };
+  }
+  let rawPr;
+  try {
+    rawPr = JSON.parse(viewed.stdout);
+  } catch {
+    rawPr = {};
+  }
+  const prState = normalizePrState(rawPr, state);
+  let cleanup = null;
+  let checkpoint = "pr_sync_open";
+  let ok = true;
+  let summary = "PR is still open; no merge cleanup was performed.";
+  let nextAction = "Wait for the PR to merge, then rerun riddle_proof_sync.";
+  if (prState.status === "merged") {
+    cleanup = cleanupMergedProofRun(state, repoDir, params, prState);
+    prState.cleanup = cleanup;
+    prState.next_action = "The PR is merged; sync recorded proof cleanup and the local base checkout refresh status.";
+    state.finalized = true;
+    state.merge_commit = prState.merge_commit || state.merge_commit || "";
+    state.merged_at = prState.merged_at || state.merged_at || "";
+    state.cleanup_report = cleanup;
+    checkpoint = "pr_sync_merged";
+    summary = "PR is merged and Riddle Proof state has been reconciled.";
+    nextAction = "Start the next proof run from the recorded base checkout; inspect cleanup.base_checkout only if it reports a skipped or failed fast-forward.";
+  } else if (prState.status === "closed") {
+    prState.next_action = "The PR is closed without a merge; inspect the PR before reusing or deleting the branch.";
+    checkpoint = "pr_sync_closed";
+    summary = "PR is closed without a merge; no merge cleanup was performed.";
+    nextAction = prState.next_action;
+  } else if (prState.status !== "open") {
+    ok = false;
+    prState.next_action = "PR state was not recognized; inspect gh pr view output and rerun sync.";
+    checkpoint = "pr_sync_unavailable";
+    summary = prState.next_action;
+    nextAction = prState.next_action;
+  }
+  state.pr_state = prState;
+  state.pr_url = prState.pr_url || state.pr_url;
+  state.pr_number = prState.pr_number || state.pr_number;
+  state.target_branch = prState.head_branch || state.target_branch || state.branch;
+  state.branch = prState.head_branch || state.branch;
+  state.base_branch = prState.base_branch || state.base_branch;
+  writeState(statePath, state);
+  const snapshot = summarizeState(state);
+  return {
+    ok,
+    action: "sync",
+    state_path: statePath,
+    checkpoint,
+    summary,
+    state: snapshot.state,
+    pr_state: prState,
+    cleanup,
+    nextAction
+  };
+}
+async function executeWorkflow(params, pluginConfig, resolvedConfig) {
+  const config = resolvedConfig || resolveConfig(pluginConfig, params);
+  const action = ensureAction(params.action);
+  if (!(0, import_node_fs2.existsSync)(config.riddleProofDir)) {
+    throw new Error(`riddle-proof runtime directory not found: ${config.riddleProofDir}`);
+  }
+  if (action === "status") {
+    return {
+      state_path: config.statePath,
+      ...summarizeState(readState(config.statePath))
+    };
+  }
+  if (action === "sync") {
+    return syncPrLifecycle(config.statePath, params);
+  }
+  const stateKey = import_node_path2.default.basename(config.statePath).replace(/[^A-Za-z0-9_.-]/g, "-");
+  const lobsterStateDir = import_node_path2.default.join(import_node_path2.default.dirname(config.statePath), "riddle-proof-lobster-state", stateKey);
+  (0, import_node_fs2.mkdirSync)(lobsterStateDir, { recursive: true });
+  const env = {
+    ...process.env,
+    RIDDLE_PROOF_DIR: config.riddleProofDir,
+    RIDDLE_PROOF_STATE_FILE: config.statePath,
+    RIDDLE_PROOF_ARGS_FILE: config.argsPath,
+    LOBSTER_STATE_DIR: lobsterStateDir
+  };
+  const lobsterCommand = process.env.RIDDLE_PROOF_LOBSTER_COMMAND || "lobster";
+  const lobsterPrefix = process.env.RIDDLE_PROOF_LOBSTER_SCRIPT ? [process.env.RIDDLE_PROOF_LOBSTER_SCRIPT] : [];
+  const runOne = (step) => {
+    const args = step === "setup" ? buildSetupArgs(params, config) : {};
+    let output;
+    try {
+      output = JSON.parse(
+        (0, import_node_child_process.execFileSync)(lobsterCommand, [...lobsterPrefix, "run", "--file", workflowFile(config.riddleProofDir, step), "--args-json", JSON.stringify(args)], {
+          encoding: "utf-8",
+          env
+        })
+      );
+    } catch (error) {
+      return {
+        ok: false,
+        step,
+        error: error?.message || String(error),
+        stdout: String(error?.stdout || ""),
+        stderr: String(error?.stderr || "")
+      };
+    }
+    if (output?.status === "needs_approval") {
+      if (!params.auto_approve) {
+        return {
+          ok: false,
+          haltedForApproval: true,
+          step,
+          approval: output.requiresApproval || null,
+          raw: output
+        };
+      }
+      const token = output?.requiresApproval?.resumeToken;
+      if (!token) throw new Error(`${step} requested approval without a resume token.`);
+      const resumed = JSON.parse(
+        (0, import_node_child_process.execFileSync)(lobsterCommand, [...lobsterPrefix, "resume", "--token", token, "--approve", "yes"], {
+          encoding: "utf-8",
+          env
+        })
+      );
+      return {
+        ok: resumed?.ok !== false,
+        step,
+        autoApproved: true,
+        raw: resumed
+      };
+    }
+    return {
+      ok: output?.ok !== false,
+      step,
+      raw: output
+    };
+  };
+  let effectiveAdvanceStage = params.advance_stage || null;
+  const recordAttempt = (stage, status, summary, extra = {}) => {
+    updateState(config.statePath, (state) => {
+      recordStageAttempt(state, stage, {
+        status,
+        summary,
+        checkpoint: extra.checkpoint || null,
+        requestedAdvanceStage: effectiveAdvanceStage || null,
+        haltedForApproval: extra.haltedForApproval,
+        autoApproved: extra.autoApproved,
+        error: extra.error || null,
+        details: extra.details || {}
+      });
+    });
+  };
+  const checkpoint = (stage, name, summary, extra = {}) => {
+    const decision = updateState(config.statePath, (state) => {
+      const checkpointContract = buildCheckpointContract(state, {
+        statePath: config.statePath,
+        stage,
+        checkpoint: name,
+        summary,
+        nextActions: extra.nextActions,
+        advanceOptions: extra.advanceOptions,
+        recommendedAdvanceStage: extra.recommendedAdvanceStage,
+        continueWithStage: extra.continueWithStage,
+        blocking: extra.blocking
+      });
+      setStageDecisionRequest(state, {
+        stage,
+        checkpoint: name,
+        summary,
+        nextActions: extra.nextActions,
+        advanceOptions: extra.advanceOptions,
+        recommendedAdvanceStage: extra.recommendedAdvanceStage,
+        continueWithStage: extra.continueWithStage,
+        blocking: extra.blocking,
+        details: extra.details,
+        checkpointContract
+      });
+    }).stage_decision_request;
+    const snapshot2 = snapshotFor(config.statePath);
+    return {
+      ok: extra.ok ?? true,
+      action,
+      state_path: config.statePath,
+      stage: snapshot2.stage,
+      checkpoint: name,
+      summary,
+      state: snapshot2.state,
+      decisionRequest: decision,
+      checkpointContract: decision?.checkpoint_contract || null,
+      ...extra
+    };
+  };
+  const primaryShipGateNextAction = (shipGate) => {
+    const reasons = shipGate.reasons || [];
+    if (reasons.some((reason) => reason.includes("proof_assessment"))) {
+      return "resume with riddle_proof_review using decision=ready_to_ship only after the screenshots and semantic evidence visibly prove the request; otherwise choose needs_implementation or needs_richer_proof";
+    }
+    if (reasons.some((reason) => reason.includes("after_cdn") || reason.includes("verify_status"))) {
+      return "rerun verify with stronger proof framing so after evidence is captured before shipping";
+    }
+    if (reasons.some((reason) => reason.includes("before_cdn") || reason.includes("prod_cdn") || reason.includes("prod_url"))) {
+      return "return to recon and capture the missing required baseline before shipping";
+    }
+    return "inspect the ship gate details, repair the missing invariant, then resume the run";
+  };
+  const shipGateBlocked = (state, executed, details = {}) => {
+    const shipGate = validateShipGate(state);
+    const nextAction = primaryShipGateNextAction(shipGate);
+    return checkpoint(
+      "verify",
+      "ship_gate_blocked",
+      `Ship is blocked until the proof bundle satisfies the hard ship gate. Next action: ${nextAction}.`,
+      {
+        ok: false,
+        nextActions: ["inspect_ship_gate", "advance_run_to_verify", "supply_proof_assessment_json", "return_to_recon_if_baseline_is_missing"],
+        advanceOptions: ["verify", "author", "implement", "recon"],
+        recommendedAdvanceStage: "verify",
+        continueWithStage: "verify",
+        blocking: true,
+        details: { ...details, shipGate, next_action: nextAction, executed },
+        nextAction,
+        shipGate,
+        verifyStatus: state?.verify_status || null,
+        mergeRecommendation: state?.merge_recommendation || null,
+        afterCdn: state?.after_cdn || null,
+        proofAssessment: state?.proof_assessment || null,
+        proofAssessmentRequest: state?.proof_assessment_request || null,
+        executed
+      }
+    );
+  };
+  const failedRun = (stage, summary, res, extra = {}) => {
+    recordAttempt(stage, res?.haltedForApproval ? "approval_required" : "failed", summary, {
+      checkpoint: extra.checkpoint || null,
+      haltedForApproval: res?.haltedForApproval || false,
+      autoApproved: res?.autoApproved || false,
+      error: res?.error || null,
+      details: extra.details
+    });
+    const snapshot2 = snapshotFor(config.statePath);
+    return {
+      ok: false,
+      action,
+      state_path: config.statePath,
+      stage: snapshot2.stage,
+      summary,
+      state: snapshot2.state,
+      approval: res?.approval || null,
+      error: res?.error || null,
+      checkpoint: extra.checkpoint || null,
+      ...extra
+    };
+  };
+  if (action !== "setup") {
+    mergeStateFromParams(config.statePath, params);
+  }
+  if (action === "run") {
+    const executed = [];
+    let state = readState(config.statePath);
+    if (!state || !state.workspace_ready || params.advance_stage === "setup") {
+      const setupRes = runOne("setup");
+      executed.push({ step: "setup", ok: setupRes.ok, haltedForApproval: setupRes.haltedForApproval || false, autoApproved: setupRes.autoApproved || false });
+      if (!setupRes.ok || setupRes.haltedForApproval) {
+        return failedRun("setup", setupRes.haltedForApproval ? "setup halted for approval" : "setup failed", setupRes, {
+          checkpoint: "setup_blocked"
+        });
+      }
+      recordAttempt("setup", "completed", "Setup completed and state/worktrees are ready.", {
+        checkpoint: params.advance_stage === "setup" ? "setup_review" : null,
+        autoApproved: setupRes.autoApproved || false
+      });
+      state = readState(config.statePath);
+      if (params.advance_stage === "setup") {
+        return checkpoint(
+          "setup",
+          "setup_review",
+          "Setup completed. Inspect the prepared workspace and explicitly advance to recon when ready.",
+          {
+            nextActions: ["inspect_setup_state", "advance_run_to_recon"],
+            advanceOptions: ["recon", "setup"],
+            recommendedAdvanceStage: "recon",
+            details: { executed },
+            executed
+          }
+        );
+      }
+    }
+    state = readState(config.statePath);
+    const continuedStage = params.continue_from_checkpoint ? checkpointContinueStage(state) : null;
+    if (params.continue_from_checkpoint && !continuedStage) {
+      const recommended = recommendedAdvanceStage(state);
+      return checkpoint(
+        state?.active_checkpoint_stage || recommended || "recon",
+        "continue_unavailable",
+        "This run call asked to continue from a checkpoint, but the current state has no resumable checkpoint. Inspect status or set advance_stage explicitly.",
+        {
+          ok: false,
+          nextActions: ["inspect_state", "set_advance_stage", "resume_run"],
+          advanceOptions: ["recon", "author", "implement", "verify", "ship"],
+          recommendedAdvanceStage: null,
+          blocking: true,
+          details: {
+            executed,
+            activeCheckpoint: state?.active_checkpoint || null,
+            suggestedAdvanceStage: recommended || null
+          },
+          suggestedAdvanceStage: recommended || null,
+          executed
+        }
+      );
+    }
+    effectiveAdvanceStage = params.advance_stage || continuedStage || null;
+    if (effectiveAdvanceStage) {
+      updateState(config.statePath, (state2) => {
+        clearStageDecisionRequest(state2);
+        state2.last_requested_advance_stage = effectiveAdvanceStage;
+      });
+      state = readState(config.statePath);
+    }
+    let requestedStage = normalizeStageRequest(state, effectiveAdvanceStage);
+    const reconCheckpointActive = ["needs_agent_decision", "needs_supervisor_judgment"].includes(state?.recon_status || "") || state?.active_checkpoint === "recon_supervisor_judgment";
+    if (requestedStage === "recon" && reconCheckpointActive) {
+      const latestAttempt = latestReconAttempt(state);
+      const latestCapturedBaselines = latestReconCapturedBaselines(state);
+      const latestAssessment = reconAssessment(state);
+      const reconAssessmentRequest = state?.recon_assessment_request || state?.recon_decision_request || null;
+      const reconDetails = {
+        executed,
+        latestAttempt,
+        latestCapturedBaselines,
+        reconAssessmentRequest,
+        reconAssessment: latestAssessment.raw
+      };
+      if (!hasSupervisorReconAssessment(state)) {
+        return checkpoint(
+          "recon",
+          "recon_supervisor_judgment",
+          "Recon gathered route hints, candidate paths, baseline captures, and observations. The supervising agent should now judge whether the latest baseline is trustworthy, whether recon should retry/reframe, and whether recon is done.",
+          {
+            nextActions: ["inspect_recon_packet", "supply_recon_assessment_json", "continue_internal_loop_with_checkpoint"],
+            advanceOptions: ["recon", "author"],
+            recommendedAdvanceStage: "recon",
+            continueWithStage: "recon",
+            blocking: false,
+            details: reconDetails,
+            reconAssessmentRequest,
+            reconDecisionRequest: state?.recon_decision_request || null,
+            executed
+          }
+        );
+      }
+      if (latestAssessment.decision === "recon_stuck" && latestAssessment.escalationTarget === "human") {
+        const summary = latestAssessment.summary || "The supervising agent concluded recon is genuinely stuck and should escalate to the human.";
+        recordAttempt("recon", "escalated", summary, {
+          checkpoint: "recon_human_escalation",
+          details: reconDetails
+        });
+        return checkpoint(
+          "recon",
+          "recon_human_escalation",
+          summary,
+          {
+            ok: false,
+            nextActions: ["inspect_recon_history", "summarize_failed_baselines", "ask_human_for_direction"],
+            advanceOptions: ["recon", "author"],
+            recommendedAdvanceStage: null,
+            continueWithStage: null,
+            blocking: true,
+            details: reconDetails,
+            reconAssessment: latestAssessment.raw,
+            reconAssessmentRequest,
+            executed
+          }
+        );
+      }
+      if ((latestAssessment.decision === "ready_for_author" || latestAssessment.continueWithStage === "author") && latestReconHasRequiredBaselines(state) && hasReconBaselineUnderstanding(state)) {
+        updateState(config.statePath, (currentState) => {
+          promoteLatestReconBaselines(currentState);
+          currentState.recon_status = "ready_for_proof_plan";
+          currentState.recon_results = currentState.recon_results || {};
+          currentState.recon_results.status = "ready_for_proof_plan";
+          currentState.recon_assessment_request = {};
+          currentState.recon_decision_request = {};
+          if ((currentState.proof_plan || "").trim() && (currentState.capture_script || "").trim()) {
+            currentState.author_status = "ready";
+            currentState.proof_plan_status = "ready";
+          } else if (!authorReady(currentState)) {
+            currentState.author_status = "needs_authoring";
+            currentState.proof_plan_status = "needs_authoring";
+          }
+        });
+        state = readState(config.statePath);
+        const approvedSummary = latestAssessment.summary || "The supervising agent approved the latest recon baseline and selected the route for proof authoring.";
+        if (params.advance_stage === "recon") {
+          recordAttempt("recon", "completed", approvedSummary, {
+            checkpoint: "recon_review",
+            details: {
+              ...reconDetails,
+              promotedBaselines: latestReconCapturedBaselines(state)
+            }
+          });
+          return checkpoint(
+            "recon",
+            "recon_review",
+            approvedSummary,
+            {
+              nextActions: ["inspect_recon_baseline", "continue_internal_loop_with_checkpoint", "advance_run_to_author"],
+              advanceOptions: ["author", "recon", "implement"],
+              recommendedAdvanceStage: "author",
+              continueWithStage: "author",
+              blocking: false,
+              details: {
+                ...reconDetails,
+                promotedBaselines: latestReconCapturedBaselines(state)
+              },
+              reconAssessment: latestAssessment.raw,
+              executed
+            }
+          );
+        }
+        recordAttempt("recon", "completed", approvedSummary, {
+          checkpoint: "recon_auto_continue",
+          details: {
+            ...reconDetails,
+            promotedBaselines: latestReconCapturedBaselines(state)
+          }
+        });
+        effectiveAdvanceStage = "author";
+        updateState(config.statePath, (currentState) => {
+          currentState.last_requested_advance_stage = "author";
+        });
+        state = readState(config.statePath);
+        requestedStage = normalizeStageRequest(state, effectiveAdvanceStage);
+      } else if (latestAssessment.decision === "ready_for_author") {
+        const missingUnderstanding = latestReconHasRequiredBaselines(state) && !hasReconBaselineUnderstanding(state);
+        return checkpoint(
+          "recon",
+          "recon_supervisor_judgment",
+          missingUnderstanding ? "The supervising agent tried to approve recon, but did not provide a concrete baseline_understanding. The before evidence must be understood before proof authoring or code edits begin." : "The supervising agent tried to approve recon, but the latest attempt is still missing one or more required baseline screenshots. Retry recon with a better plan or declare the loop genuinely stuck.",
+          {
+            ok: false,
+            nextActions: ["inspect_recon_packet", "refine_recon_plan", "continue_internal_loop_with_checkpoint"],
+            advanceOptions: ["recon", "author"],
+            recommendedAdvanceStage: "recon",
+            continueWithStage: "recon",
+            blocking: false,
+            details: reconDetails,
+            reconAssessment: latestAssessment.raw,
+            reconAssessmentRequest,
+            executed
+          }
+        );
+      } else {
+        updateState(config.statePath, (currentState) => {
+          currentState.recon_status = "";
+          currentState.recon_assessment = {};
+          currentState.recon_assessment_source = null;
+          currentState.recon_assessment_request = {};
+          currentState.recon_decision_request = {};
+          currentState.before_cdn = "";
+          currentState.prod_cdn = "";
+          currentState.recon_results = currentState.recon_results || {};
+          currentState.recon_results.baselines = {};
+          currentState.recon_results.selected_attempt = {};
+          currentState.recon_results.status = "retry_requested";
+        });
+        state = readState(config.statePath);
+      }
+    }
+    if (!state?.recon_results || state?.stage === "setup" || state?.stage === "preflight" || ["needs_agent_decision", "needs_supervisor_judgment"].includes(state?.recon_status || "") || requestedStage === "recon") {
+      const reconRes = runOne("recon");
+      executed.push({ step: "recon", ok: reconRes.ok, haltedForApproval: reconRes.haltedForApproval || false, autoApproved: reconRes.autoApproved || false });
+      if (!reconRes.ok || reconRes.haltedForApproval) {
+        return failedRun("recon", reconRes.haltedForApproval ? "recon halted for approval" : "recon failed", reconRes, {
+          checkpoint: "recon_failed",
+          details: { executed },
+          executed
+        });
+      }
+      state = readState(config.statePath);
+      if (["needs_agent_decision", "needs_supervisor_judgment"].includes(state?.recon_status || "")) {
+        const reconAssessmentRequest = state?.recon_assessment_request || state?.recon_decision_request || null;
+        const summary = "Recon gathered route hints, candidate paths, baseline captures, and observations. The supervising agent should now judge whether the latest baseline is trustworthy, whether recon should retry/reframe, and whether recon is done.";
+        const reconDetails = {
+          executed,
+          latestAttempt: latestReconAttempt(state),
+          latestCapturedBaselines: latestReconCapturedBaselines(state),
+          reconAssessmentRequest
+        };
+        recordAttempt("recon", "checkpoint", summary, {
+          autoApproved: reconRes.autoApproved || false,
+          checkpoint: "recon_supervisor_judgment",
+          details: reconDetails
+        });
+        return checkpoint(
+          "recon",
+          "recon_supervisor_judgment",
+          summary,
+          {
+            nextActions: ["inspect_recon_packet", "supply_recon_assessment_json", "continue_internal_loop_with_checkpoint"],
+            advanceOptions: ["recon", "author"],
+            recommendedAdvanceStage: "recon",
+            continueWithStage: "recon",
+            blocking: false,
+            details: reconDetails,
+            reconAssessmentRequest,
+            reconDecisionRequest: state?.recon_decision_request || null,
+            executed
+          }
+        );
+      }
+      recordAttempt("recon", "completed", "Recon completed and promoted an approved baseline context.", {
+        autoApproved: reconRes.autoApproved || false,
+        details: { executed }
+      });
+    }
+    state = readState(config.statePath);
+    if (!authorReady(state) || effectiveAdvanceStage === "author") {
+      const authorRes = runOne("author");
+      executed.push({ step: "author", ok: authorRes.ok, haltedForApproval: authorRes.haltedForApproval || false, autoApproved: authorRes.autoApproved || false });
+      if (!authorRes.ok || authorRes.haltedForApproval) {
+        return failedRun("author", authorRes.haltedForApproval ? "author halted for approval" : "author failed", authorRes, {
+          checkpoint: "author_failed",
+          details: { executed },
+          executed
+        });
+      }
+      state = readState(config.statePath);
+      if (!authorReady(state)) {
+        recordAttempt("author", "checkpoint", "Author prepared a supervisor judgment request instead of delegating proof authoring to an internal model.", {
+          autoApproved: authorRes.autoApproved || false,
+          checkpoint: "author_supervisor_judgment",
+          details: {
+            executed,
+            authorSummary: state?.author_summary || null,
+            authorRequest: state?.author_request || null,
+            serverPath: state?.server_path || null,
+            waitForSelector: state?.wait_for_selector || null
+          }
+        });
+        return checkpoint(
+          "author",
+          "author_supervisor_judgment",
+          "Author distilled recon into a proof-authoring request. The supervising agent should supply the proof packet, then resume the workflow.",
+          {
+            nextActions: ["inspect_author_request", "supply_author_packet_json_or_proof_plan", "continue_internal_loop_with_checkpoint"],
+            advanceOptions: ["author", "recon", "implement", "verify"],
+            recommendedAdvanceStage: "author",
+            continueWithStage: "author",
+            details: {
+              executed,
+              authorSummary: state?.author_summary || null,
+              authorRequest: state?.author_request || null,
+              proofPlanDraft: state?.author_request?.fallback_defaults?.proof_plan || null,
+              captureScriptDraft: state?.author_request?.fallback_defaults?.capture_script || null,
+              serverPathDraft: state?.author_request?.fallback_defaults?.server_path || null,
+              waitForSelectorDraft: state?.author_request?.fallback_defaults?.wait_for_selector || null
+            },
+            authorSummary: state?.author_summary || null,
+            authorRequest: state?.author_request || null,
+            proofPlanDraft: state?.author_request?.fallback_defaults?.proof_plan || null,
+            captureScriptDraft: state?.author_request?.fallback_defaults?.capture_script || null,
+            serverPathDraft: state?.author_request?.fallback_defaults?.server_path || null,
+            waitForSelectorDraft: state?.author_request?.fallback_defaults?.wait_for_selector || null,
+            executed
+          }
+        );
+      }
+      const authorNextStage = stageAfterAuthor(state);
+      const explicitAuthorDebug = params.advance_stage === "author";
+      recordAttempt("author", "completed", "Author applied the supervising agent's proof packet to recon observations.", {
+        autoApproved: authorRes.autoApproved || false,
+        checkpoint: explicitAuthorDebug ? "author_review" : "author_auto_continue",
+        details: {
+          executed,
+          authorSummary: state?.author_summary || null,
+          authorModel: state?.author_model || null,
+          authorRuntimeModelHint: state?.author_runtime_model_hint || null,
+          serverPath: state?.server_path || null,
+          waitForSelector: state?.wait_for_selector || null
+        }
+      });
+      if (explicitAuthorDebug) {
+        return checkpoint(
+          "author",
+          "author_review",
+          authorNextStage === "verify" ? "Author applied the supervising agent's proof packet. Because implementation is already recorded, you can continue straight into verify." : "Author applied the supervising agent's proof packet. Inspect it if needed, then continue into implement.",
+          {
+            nextActions: authorNextStage === "verify" ? ["inspect_proof_packet", "advance_run_to_verify", "rerun_author"] : ["inspect_proof_packet", "advance_run_to_implement", "rerun_author"],
+            advanceOptions: authorNextStage === "verify" ? ["author", "verify", "recon"] : ["author", "implement", "recon"],
+            recommendedAdvanceStage: authorNextStage,
+            continueWithStage: authorNextStage,
+            details: {
+              executed,
+              authorSummary: state?.author_summary || null,
+              authorModel: state?.author_model || null,
+              authorRuntimeModelHint: state?.author_runtime_model_hint || null,
+              proofPlan: state?.proof_plan || null,
+              serverPath: state?.server_path || null,
+              waitForSelector: state?.wait_for_selector || null
+            },
+            authorSummary: state?.author_summary || null,
+            authorModel: state?.author_model || null,
+            authorRuntimeModelHint: state?.author_runtime_model_hint || null,
+            proofPlan: state?.proof_plan || null,
+            serverPath: state?.server_path || null,
+            waitForSelector: state?.wait_for_selector || null,
+            executed
+          }
+        );
+      }
+      effectiveAdvanceStage = authorNextStage;
+      updateState(config.statePath, (currentState) => {
+        currentState.last_requested_advance_stage = authorNextStage;
+      });
+      state = readState(config.statePath);
+    }
+    if (!effectiveAdvanceStage) {
+      const recommended = recommendedAdvanceStage(state);
+      return checkpoint(
+        recommended || "implement",
+        "awaiting_stage_advance",
+        "Proof authoring is ready. The wrapper will not guess the next stage from here, explicitly choose whether to revisit recon/author, validate implementation, capture verify evidence, or ship.",
+        {
+          nextActions: ["inspect_state", "set_advance_stage", "resume_run"],
+          advanceOptions: ["recon", "author", "implement", "verify", "ship"],
+          recommendedAdvanceStage: recommended,
+          details: { executed },
+          executed
+        }
+      );
+    }
+    if (effectiveAdvanceStage === "implement") {
+      const implementRes = runOne("implement");
+      executed.push({ step: "implement", ok: implementRes.ok, haltedForApproval: implementRes.haltedForApproval || false, autoApproved: implementRes.autoApproved || false });
+      if (implementRes.haltedForApproval) {
+        return failedRun("implement", "implement halted for approval", implementRes, {
+          checkpoint: "implement_blocked",
+          details: { executed },
+          executed
+        });
+      }
+      if (!implementRes.ok) {
+        const implementError = `${implementRes.error || ""}
+${implementRes.stdout || ""}
+${implementRes.stderr || ""}`;
+        if (implementError.includes("No implementation detected")) {
+          recordAttempt("implement", "checkpoint", "Implementation checkpoint found no material code changes yet.", {
+            checkpoint: "implement_changes_missing",
+            error: implementRes.error || null,
+            details: { executed }
+          });
+          return checkpoint(
+            "implement",
+            "implement_changes_missing",
+            "Proof plan is ready, but code changes are not recorded yet. Make the implementation changes on the after worktree, then resume run.",
+            {
+              nextActions: ["make_code_changes", "rerun_implement"],
+              advanceOptions: ["implement", "author", "recon"],
+              recommendedAdvanceStage: "implement",
+              blocking: true,
+              details: { executed },
+              executed
+            }
+          );
+        }
+        return failedRun("implement", "implement failed", implementRes, {
+          checkpoint: "implement_failed",
+          details: { executed },
+          executed
+        });
+      }
+      let invalidatedVerifyEvidence2 = false;
+      updateState(config.statePath, (state2) => {
+        invalidatedVerifyEvidence2 = invalidateVerifyEvidence(state2).invalidated;
+      });
+      recordAttempt("implement", "completed", "Implementation checkpoint recorded code changes on the after worktree.", {
+        autoApproved: implementRes.autoApproved || false,
+        checkpoint: "implement_review",
+        details: { executed, invalidatedVerifyEvidence: invalidatedVerifyEvidence2 }
+      });
+      return checkpoint(
+        "implement",
+        "implement_review",
+        invalidatedVerifyEvidence2 ? "Implementation changes were detected and prior verify evidence was invalidated. Inspect the branch diff or notes, then explicitly choose whether to iterate implementation again or advance to verify." : "Implementation changes were detected. Inspect the branch diff or notes, then explicitly choose whether to iterate implementation again or advance to verify.",
+        {
+          nextActions: ["inspect_branch_diff", "rerun_implement", "advance_run_to_verify"],
+          advanceOptions: ["implement", "author", "verify", "recon"],
+          recommendedAdvanceStage: "verify",
+          details: {
+            executed,
+            implementationSummary: readState(config.statePath)?.implementation_summary || null,
+            invalidatedVerifyEvidence: invalidatedVerifyEvidence2
+          },
+          implementationSummary: readState(config.statePath)?.implementation_summary || null,
+          invalidatedVerifyEvidence: invalidatedVerifyEvidence2,
+          executed
+        }
+      );
+    }
+    if (effectiveAdvanceStage === "verify") {
+      state = readState(config.statePath);
+      if (!["changes_detected", "completed"].includes(state?.implementation_status || "")) {
+        return checkpoint(
+          "implement",
+          "implement_required",
+          "Verify is blocked until implementation has been recorded. Run the implement stage after making code changes, then resume verify.",
+          {
+            ok: false,
+            nextActions: ["make_code_changes", "advance_run_to_implement"],
+            advanceOptions: ["implement", "author", "recon"],
+            recommendedAdvanceStage: "implement",
+            continueWithStage: "implement",
+            blocking: true,
+            details: { executed },
+            executed
+          }
+        );
+      }
+      const hasIncomingProofAssessment = typeof params.proof_assessment_json === "string" && params.proof_assessment_json.trim().length > 0;
+      const canReuseVerifyEvidence = (params.advance_stage !== "verify" || hasIncomingProofAssessment) && state?.verify_status === "evidence_captured" && Boolean((state?.after_cdn || "").trim()) && (state?.active_checkpoint === "verify_supervisor_judgment" || hasSupervisorProofAssessment(state));
+      let verifyRes = { ok: true, step: "verify", reusedEvidence: canReuseVerifyEvidence };
+      if (!canReuseVerifyEvidence) {
+        verifyRes = runOne("verify");
+        executed.push({ step: "verify", ok: verifyRes.ok, haltedForApproval: verifyRes.haltedForApproval || false, autoApproved: verifyRes.autoApproved || false });
+        if (!verifyRes.ok || verifyRes.haltedForApproval) {
+          return failedRun("verify", verifyRes.haltedForApproval ? "verify halted for approval" : "verify failed", verifyRes, {
+            checkpoint: "verify_failed",
+            details: { executed },
+            executed
+          });
+        }
+      } else {
+        executed.push({ step: "verify", ok: true, reusedEvidence: true, haltedForApproval: false, autoApproved: false });
+      }
+      state = readState(config.statePath);
+      const verifyStatus = state?.verify_status || ((state?.after_cdn || "").trim() ? "evidence_captured" : "capture_incomplete");
+      const verifyDecisionRequest = state?.verify_decision_request || null;
+      const verifySummary = state?.verify_summary || state?.proof_summary || null;
+      const proofAssessment = verifyAssessment(state);
+      const convergenceSignals = nonConvergenceSignals(state, proofAssessment);
+      const verifyRecommendedStage = proofAssessment.recommendedStage || null;
+      const verifyContinueWithStage = shouldEscalateVerifyToHuman(state, proofAssessment) ? null : proofAssessment.continueWithStage || verifyRecommendedStage || null;
+      const verifyDetails = {
+        executed,
+        verifyStatus,
+        verifySummary,
+        afterCdn: state?.after_cdn || null,
+        mergeRecommendation: state?.merge_recommendation || null,
+        verifyDecisionRequest,
+        proofAssessment: proofAssessment.raw,
+        proofAssessmentSource: proofAssessment.source || null,
+        proofAssessmentRequest: state?.proof_assessment_request || null,
+        verifyRecommendedStage,
+        verifyContinueWithStage,
+        convergenceSignals
+      };
+      if (verifyStatus !== "evidence_captured") {
+        if ((verifyContinueWithStage || verifyRecommendedStage || "author") === "author") {
+          updateState(config.statePath, (currentState) => {
+            currentState.author_status = "needs_authoring";
+            currentState.proof_plan_status = "needs_authoring";
+            currentState.supervisor_author_packet = null;
+          });
+          state = readState(config.statePath);
+        }
+        const checkpointName = "verify_capture_retry";
+        const summary = "Verify ran, but the proof packet still needs internal capture-plan work before it should ship.";
+        recordAttempt("verify", "checkpoint", summary, {
+          autoApproved: verifyRes.autoApproved || false,
+          checkpoint: checkpointName,
+          details: verifyDetails
+        });
+        return checkpoint(
+          "verify",
+          checkpointName,
+          summary,
+          {
+            ok: true,
+            nextActions: ["inspect_after_capture", "continue_internal_loop_with_checkpoint", "return_to_recon_if_baseline_is_wrong"],
+            advanceOptions: ["author", "verify", "implement", "recon"],
+            recommendedAdvanceStage: verifyRecommendedStage || "author",
+            continueWithStage: verifyContinueWithStage || "author",
+            blocking: false,
+            details: verifyDetails,
+            verifyStatus,
+            verifySummary,
+            afterCdn: state?.after_cdn || null,
+            mergeRecommendation: state?.merge_recommendation || null,
+            verifyDecisionRequest,
+            proofAssessment: proofAssessment.raw,
+            executed
+          }
+        );
+      }
+      if (!hasSupervisorProofAssessment(state)) {
+        const summary = "Verify captured usable evidence. The supervising agent should now assess whether the proof supports ship or more internal iteration, then resume the workflow with proof_assessment_json.";
+        recordAttempt("verify", "checkpoint", summary, {
+          autoApproved: verifyRes.autoApproved || false,
+          checkpoint: "verify_supervisor_judgment",
+          details: verifyDetails
+        });
+        return checkpoint(
+          "verify",
+          "verify_supervisor_judgment",
+          summary,
+          {
+            nextActions: ["inspect_evidence", "author_proof_assessment_json", "continue_internal_loop_with_checkpoint"],
+            advanceOptions: ["verify", "author", "implement", "recon", "ship"],
+            recommendedAdvanceStage: "verify",
+            continueWithStage: "verify",
+            blocking: false,
+            details: verifyDetails,
+            verifyStatus,
+            verifySummary,
+            afterCdn: state?.after_cdn || null,
+            mergeRecommendation: state?.merge_recommendation || null,
+            verifyDecisionRequest,
+            proofAssessmentRequest: state?.proof_assessment_request || null,
+            executed
+          }
+        );
+      }
+      const shouldEscalate = shouldEscalateVerifyToHuman(state, proofAssessment);
+      if (shouldEscalate) {
+        const summary = "The supervising agent concluded the workflow hit a real wall and explicitly escalated the proof loop to the human.";
+        recordAttempt("verify", "escalated", summary, {
+          autoApproved: verifyRes.autoApproved || false,
+          checkpoint: "verify_human_escalation",
+          details: verifyDetails
+        });
+        return checkpoint(
+          "verify",
+          "verify_human_escalation",
+          summary,
+          {
+            ok: false,
+            nextActions: ["inspect_retry_history", "summarize_internal_loop", "ask_human_for_direction"],
+            advanceOptions: ["author", "implement", "ship", "verify", "recon"],
+            recommendedAdvanceStage: null,
+            continueWithStage: null,
+            blocking: true,
+            details: verifyDetails,
+            verifyStatus,
+            verifySummary,
+            afterCdn: state?.after_cdn || null,
+            mergeRecommendation: state?.merge_recommendation || null,
+            verifyDecisionRequest,
+            proofAssessment: proofAssessment.raw,
+            executed
+          }
+        );
+      }
+      const shouldAutoShip = verifyContinueWithStage === "ship" && (params.ship_after_verify || params.continue_from_checkpoint || params.advance_stage !== "verify");
+      if (shouldAutoShip) {
+        const shipGate = validateShipGate(state);
+        if (!shipGate.ok) {
+          recordAttempt("verify", "checkpoint", "Verify cannot continue into ship because the hard ship gate is missing required evidence or approval.", {
+            autoApproved: verifyRes.autoApproved || false,
+            checkpoint: "ship_gate_blocked",
+            details: { ...verifyDetails, shipGate }
+          });
+          return shipGateBlocked(state, executed, verifyDetails);
+        }
+        recordAttempt("verify", "checkpoint", "Verify captured a strong proof packet and is continuing directly into ship.", {
+          autoApproved: verifyRes.autoApproved || false,
+          checkpoint: "verify_then_ship",
+          details: { ...verifyDetails, shipGate }
+        });
+        const shipRes = runOne("ship");
+        executed.push({ step: "ship", ok: shipRes.ok, haltedForApproval: shipRes.haltedForApproval || false, autoApproved: shipRes.autoApproved || false });
+        if (!shipRes.ok || shipRes.haltedForApproval) {
+          const shipNextAction = shipRes?.error && String(shipRes.error).includes("temporary proof branch") ? "product bug: ship resolved a temporary proof branch; resolve the PR head branch before retrying ship" : "inspect the ship error, confirm the PR head branch and verified commit, then retry ship";
+          return failedRun("ship", shipRes.haltedForApproval ? "ship halted for approval" : "ship failed", shipRes, {
+            checkpoint: "ship_failed",
+            details: { executed, next_action: shipNextAction },
+            nextAction: shipNextAction,
+            executed
+          });
+        }
+        recordAttempt("ship", "completed", "Ship updated the PR and posted proof artifacts after the supervising agent judged the proof strong enough.", {
+          autoApproved: shipRes.autoApproved || false,
+          checkpoint: "ship_review",
+          details: { executed }
+        });
+        const snapshot2 = snapshotFor(config.statePath);
+        const summary = "The supervising agent judged the proof strong enough, so the workflow shipped automatically and left the PR as the main human review surface.";
+        const finalState = readState(config.statePath);
+        const shipReport = finalState?.ship_report || snapshot2.state?.ship_report || null;
+        return {
+          ok: true,
+          action,
+          state_path: config.statePath,
+          stage: snapshot2.stage,
+          checkpoint: "ship_review",
+          summary,
+          state: snapshot2.state,
+          shipReport,
+          checkpointContract: buildCheckpointContract(readState(config.statePath), {
+            statePath: config.statePath,
+            stage: "ship",
+            checkpoint: "ship_review",
+            summary,
+            nextActions: ["inspect_pr", "rerun_ship_if_needed"],
+            advanceOptions: ["ship", "verify", "author", "implement"],
+            recommendedAdvanceStage: "ship"
+          }),
+          executed
+        };
+      }
+      if (proofAssessment.decision === "ready_to_ship") {
+        const shipGate = validateShipGate(state);
+        if (!shipGate.ok) {
+          recordAttempt("verify", "checkpoint", "Verify cannot mark ship ready because the hard ship gate is missing required evidence or approval.", {
+            autoApproved: verifyRes.autoApproved || false,
+            checkpoint: "ship_gate_blocked",
+            details: { ...verifyDetails, shipGate }
+          });
+          return shipGateBlocked(state, executed, verifyDetails);
+        }
+        recordAttempt("verify", "checkpoint", "Verify captured a strong proof packet and is ready to continue into ship.", {
+          autoApproved: verifyRes.autoApproved || false,
+          checkpoint: "verify_ship_ready",
+          details: { ...verifyDetails, shipGate }
+        });
+        return checkpoint(
+          "verify",
+          "verify_ship_ready",
+          "The supervising agent judged the proof strong enough to continue into ship.",
+          {
+            nextActions: ["inspect_evidence", "continue_internal_loop_with_checkpoint", "advance_run_to_ship_if_you_need_manual_control"],
+            advanceOptions: ["ship", "verify", "author", "implement", "recon"],
+            recommendedAdvanceStage: "ship",
+            continueWithStage: "ship",
+            blocking: false,
+            details: { ...verifyDetails, shipGate },
+            shipGate,
+            verifyStatus,
+            verifySummary,
+            afterCdn: state?.after_cdn || null,
+            mergeRecommendation: state?.merge_recommendation || null,
+            verifyDecisionRequest,
+            proofAssessment: proofAssessment.raw,
+            executed
+          }
+        );
+      }
+      if (verifyContinueWithStage === "author") {
+        updateState(config.statePath, (currentState) => {
+          currentState.author_status = "needs_authoring";
+          currentState.proof_plan_status = "needs_authoring";
+          currentState.supervisor_author_packet = null;
+        });
+        state = readState(config.statePath);
+      }
+      const unresolvedSummary = convergenceSignals.warning ? "The supervising agent kept the workflow in the internal loop, but retry history suggests it may not be converging yet. Keep iterating internally or explicitly escalate with escalation_target=human when you conclude it is genuinely stuck." : "The supervising agent judged that the workflow should keep iterating internally before it ships.";
+      recordAttempt("verify", "checkpoint", unresolvedSummary, {
+        autoApproved: verifyRes.autoApproved || false,
+        checkpoint: "verify_agent_retry",
+        details: verifyDetails
+      });
+      return checkpoint(
+        "verify",
+        "verify_agent_retry",
+        unresolvedSummary,
+        {
+          ok: true,
+          nextActions: convergenceSignals.warning ? ["inspect_retry_history", "decide_whether_to_keep_iterating_or_escalate", "continue_internal_loop_with_checkpoint"] : ["inspect_proof_assessment", "continue_internal_loop_with_checkpoint", "return_to_implement_if_fix_failed"],
+          advanceOptions: ["author", "implement", "ship", "verify", "recon"],
+          recommendedAdvanceStage: verifyRecommendedStage,
+          continueWithStage: verifyContinueWithStage,
+          blocking: false,
+          details: verifyDetails,
+          verifyStatus,
+          verifySummary,
+          afterCdn: state?.after_cdn || null,
+          mergeRecommendation: state?.merge_recommendation || null,
+          verifyDecisionRequest,
+          proofAssessment: proofAssessment.raw,
+          executed
+        }
+      );
+    }
+    if (effectiveAdvanceStage === "ship") {
+      state = readState(config.statePath);
+      const shipAssessment = verifyAssessment(state);
+      const shipGate = validateShipGate(state);
+      if (state?.verify_status !== "evidence_captured") {
+        return checkpoint(
+          "verify",
+          "verify_required",
+          "Ship is blocked until verify has captured a usable proof packet. Run verify, inspect the evidence, then explicitly advance to ship only if the proof supports success.",
+          {
+            ok: false,
+            nextActions: ["advance_run_to_verify", "inspect_verify_state"],
+            advanceOptions: ["verify", "author", "implement", "recon"],
+            recommendedAdvanceStage: "verify",
+            continueWithStage: "verify",
+            blocking: true,
+            details: {
+              executed,
+              shipGate,
+              verifyStatus: state?.verify_status || null,
+              mergeRecommendation: state?.merge_recommendation || null,
+              afterCdn: state?.after_cdn || null
+            },
+            shipGate,
+            verifyStatus: state?.verify_status || null,
+            mergeRecommendation: state?.merge_recommendation || null,
+            afterCdn: state?.after_cdn || null,
+            executed
+          }
+        );
+      }
+      if (!hasSupervisorProofAssessment(state) || shipAssessment.decision !== "ready_to_ship") {
+        return checkpoint(
+          "verify",
+          "verify_supervisor_judgment_required",
+          "Ship is blocked until the supervising agent judges the current proof packet as ready_to_ship.",
+          {
+            ok: false,
+            nextActions: ["inspect_evidence", "supply_proof_assessment_json", "continue_internal_loop_with_checkpoint"],
+            advanceOptions: ["verify", "author", "implement", "recon", "ship"],
+            recommendedAdvanceStage: "verify",
+            continueWithStage: "verify",
+            blocking: true,
+            details: {
+              executed,
+              shipGate,
+              verifyStatus: state?.verify_status || null,
+              mergeRecommendation: state?.merge_recommendation || null,
+              afterCdn: state?.after_cdn || null,
+              proofAssessment: state?.proof_assessment || null,
+              proofAssessmentRequest: state?.proof_assessment_request || null
+            },
+            shipGate,
+            verifyStatus: state?.verify_status || null,
+            mergeRecommendation: state?.merge_recommendation || null,
+            afterCdn: state?.after_cdn || null,
+            proofAssessment: state?.proof_assessment || null,
+            proofAssessmentRequest: state?.proof_assessment_request || null,
+            executed
+          }
+        );
+      }
+      if (!shipGate.ok) {
+        return shipGateBlocked(state, executed, { shipAssessment: shipAssessment.raw });
+      }
+      const shipRes = runOne("ship");
+      executed.push({ step: "ship", ok: shipRes.ok, haltedForApproval: shipRes.haltedForApproval || false, autoApproved: shipRes.autoApproved || false });
+      if (!shipRes.ok || shipRes.haltedForApproval) {
+        return failedRun("ship", shipRes.haltedForApproval ? "ship halted for approval" : "ship failed", shipRes, {
+          checkpoint: "ship_failed",
+          details: { executed },
+          executed
+        });
+      }
+      recordAttempt("ship", "completed", "Ship updated the PR and posted proof artifacts.", {
+        autoApproved: shipRes.autoApproved || false,
+        checkpoint: "ship_review",
+        details: { executed }
+      });
+      return checkpoint(
+        "ship",
+        "ship_review",
+        "Ship completed. Review the PR, proof comment, and cleanup results. Re-run ship if you need to refresh the PR after more changes.",
+        {
+          nextActions: ["inspect_pr", "rerun_ship_if_needed"],
+          advanceOptions: ["ship", "verify", "author", "implement"],
+          recommendedAdvanceStage: "ship",
+          details: {
+            executed,
+            prUrl: readState(config.statePath)?.pr_url || null
+          },
+          prUrl: readState(config.statePath)?.pr_url || null,
+          executed
+        }
+      );
+    }
+  }
+  if (action === "ship") {
+    const state = readState(config.statePath);
+    const shipGate = validateShipGate(state);
+    if (state?.verify_status !== "evidence_captured") {
+      return checkpoint(
+        "verify",
+        "verify_required",
+        "Ship is blocked until verify has captured a usable proof packet. Run verify, inspect the evidence, then ship only if the proof supports success.",
+        {
+          ok: false,
+          nextActions: ["run_verify", "inspect_verify_state"],
+          advanceOptions: ["verify", "author", "implement", "recon"],
+          recommendedAdvanceStage: "verify",
+          continueWithStage: "verify",
+          blocking: true,
+          details: { shipGate },
+          shipGate,
+          verifyStatus: state?.verify_status || null,
+          mergeRecommendation: state?.merge_recommendation || null,
+          afterCdn: state?.after_cdn || null
+        }
+      );
+    }
+    if (!hasSupervisorProofAssessment(state) || verifyAssessment(state).decision !== "ready_to_ship") {
+      return checkpoint(
+        "verify",
+        "verify_supervisor_judgment_required",
+        "Ship is blocked until the supervising agent judges the current proof packet as ready_to_ship.",
+        {
+          ok: false,
+          nextActions: ["inspect_evidence", "supply_proof_assessment_json", "rerun_ship"],
+          advanceOptions: ["verify", "author", "implement", "recon", "ship"],
+          recommendedAdvanceStage: "verify",
+          continueWithStage: "verify",
+          blocking: true,
+          details: { shipGate },
+          shipGate,
+          verifyStatus: state?.verify_status || null,
+          mergeRecommendation: state?.merge_recommendation || null,
+          afterCdn: state?.after_cdn || null,
+          proofAssessment: state?.proof_assessment || null,
+          proofAssessmentRequest: state?.proof_assessment_request || null
+        }
+      );
+    }
+    if (!shipGate.ok) {
+      return shipGateBlocked(state, [], {});
+    }
+  }
+  const single = runOne(action);
+  if (!single.ok || single.haltedForApproval) {
+    return failedRun(action, single.haltedForApproval ? `${action} halted for approval` : `${action} failed`, single, {
+      checkpoint: `${action}_failed`
+    });
+  }
+  let invalidatedVerifyEvidence = false;
+  updateState(config.statePath, (state) => {
+    if (action === "implement") {
+      invalidatedVerifyEvidence = invalidateVerifyEvidence(state).invalidated;
+    }
+    clearStageDecisionRequest(state);
+  });
+  const singleSummary = action === "implement" && invalidatedVerifyEvidence ? "implement completed and invalidated prior verify evidence" : `${action} completed`;
+  recordAttempt(action, "completed", singleSummary, {
+    autoApproved: single.autoApproved || false,
+    details: action === "implement" ? { invalidatedVerifyEvidence } : {}
+  });
+  const snapshot = snapshotFor(config.statePath);
+  return {
+    ok: true,
+    action,
+    state_path: config.statePath,
+    stage: snapshot.stage,
+    summary: singleSummary,
+    state: snapshot.state,
+    approval: null,
+    autoApproved: single.autoApproved || false,
+    error: null
+  };
+}
+function createRiddleProofEngine(pluginConfig = {}) {
+  return {
+    execute(params) {
+      const config = resolveConfig(pluginConfig, params);
+      return executeWorkflow(params, pluginConfig, config);
+    },
+    status(statePath) {
+      const config = resolveConfig(pluginConfig, { action: "status", state_path: statePath });
+      return executeWorkflow({ action: "status", state_path: statePath }, pluginConfig, config);
+    },
+    resolveConfig(params = {}) {
+      return resolveConfig(pluginConfig, params);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRiddleProofEngine,
+  executeWorkflow
+});