@riddledc/riddle-proof 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "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)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   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/index.ts
@@ -22,18 +32,23 @@ var index_exports = {};
 __export(index_exports, {
   RIDDLE_PROOF_RUN_STATE_VERSION: () => RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent: () => appendRunEvent,
+  appendStageHeartbeat: () => appendStageHeartbeat,
   applyTerminalMetadata: () => applyTerminalMetadata,
   compactRecord: () => compactRecord,
+  createDisabledRiddleProofAgentAdapter: () => createDisabledRiddleProofAgentAdapter,
   createRunResult: () => createRunResult,
   createRunState: () => createRunState,
+  createRunStatusSnapshot: () => createRunStatusSnapshot,
   isSuccessfulStatus: () => isSuccessfulStatus,
   isTerminalStatus: () => isTerminalStatus,
   nonEmptyString: () => nonEmptyString,
   normalizeIntegrationContext: () => normalizeIntegrationContext,
   normalizeRunParams: () => normalizeRunParams,
   normalizeTerminalMetadata: () => normalizeTerminalMetadata,
+  readRiddleProofRunStatus: () => readRiddleProofRunStatus,
   recordValue: () => recordValue,
   runRiddleProof: () => runRiddleProof,
+  runRiddleProofEngineHarness: () => runRiddleProofEngineHarness,
   setRunStatus: () => setRunStatus
 });
 module.exports = __toCommonJS(index_exports);
@@ -92,7 +107,11 @@ function createRunResult(input) {
   return compactRecord({
     ok,
     status,
+    run_id: state.run_id,
     state_path: input.state_path ?? state.state_path ?? null,
+    worktree_path: state.worktree_path ?? null,
+    branch: state.branch ?? null,
+    current_stage: state.current_stage ?? null,
     iterations: state.iterations,
     last_checkpoint: state.last_checkpoint ?? null,
     last_summary: input.last_summary ?? null,
@@ -114,6 +133,17 @@ var RIDDLE_PROOF_RUN_STATE_VERSION = "riddle-proof.run-state.v1";
 function timestamp() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+function createRunId(createdAt) {
+  const stamp = createdAt.replace(/\D/g, "").slice(0, 14) || "unknown";
+  const entropy = Math.random().toString(36).slice(2, 8) || "run";
+  return `rp_${stamp}_${entropy}`;
+}
+function elapsedMs(start, end) {
+  const startMs = start ? Date.parse(start) : NaN;
+  const endMs = end ? Date.parse(end) : NaN;
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return void 0;
+  return Math.max(0, endMs - startMs);
+}
 function normalizeIntegrationContext(input, fallbackSource) {
   const value = recordValue(input);
   if (!value) {
@@ -157,6 +187,11 @@ function normalizeRunParams(input) {
     color_scheme: input.color_scheme,
     wait_for_selector: input.wait_for_selector,
     ship_mode: input.ship_mode,
+    engine_state_path: input.engine_state_path,
+    harness_state_path: input.harness_state_path,
+    max_iterations: input.max_iterations,
+    auto_approve: input.auto_approve,
+    dry_run: input.dry_run,
     integration_context: normalizeIntegrationContext(input.integration_context)
   });
 }
@@ -164,7 +199,12 @@ function createRunState(input) {
   const createdAt = input.created_at || timestamp();
   return compactRecord({
     version: RIDDLE_PROOF_RUN_STATE_VERSION,
+    run_id: input.run_id || createRunId(createdAt),
     state_path: input.state_path,
+    worktree_path: input.worktree_path,
+    branch: input.branch || input.request.branch,
+    current_stage: input.current_stage ?? null,
+    stage_started_at: input.stage_started_at ?? null,
     status: input.status || "running",
     created_at: createdAt,
     updated_at: input.updated_at || createdAt,
@@ -192,9 +232,49 @@ function appendRunEvent(state, input) {
     details: event.details
   }));
   if (input.checkpoint !== void 0) state.last_checkpoint = input.checkpoint;
+  if (input.stage !== void 0) {
+    if (state.current_stage !== input.stage) state.stage_started_at = event.ts;
+    state.current_stage = input.stage;
+  }
   state.updated_at = event.ts;
   return state;
 }
+function appendStageHeartbeat(state, input) {
+  const at = input.ts || timestamp();
+  return appendRunEvent(state, {
+    ts: at,
+    kind: "stage.heartbeat",
+    checkpoint: input.checkpoint || `${input.stage}_heartbeat`,
+    stage: input.stage,
+    summary: input.summary || `${input.stage} stage is active.`,
+    details: compactRecord({
+      elapsed_ms: elapsedMs(state.created_at, at),
+      stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
+      wait_reason: input.wait_reason,
+      blocker: input.blocker,
+      ...input.details
+    })
+  });
+}
+function createRunStatusSnapshot(state, at = timestamp()) {
+  const latestEvent = state.events[state.events.length - 1];
+  const runId = state.run_id || "unknown";
+  return compactRecord({
+    run_id: runId,
+    status: state.status,
+    current_stage: state.current_stage ?? null,
+    state_path: state.state_path ?? null,
+    worktree_path: state.worktree_path ?? null,
+    branch: state.branch ?? null,
+    iterations: state.iterations,
+    last_checkpoint: state.last_checkpoint ?? null,
+    updated_at: state.updated_at,
+    elapsed_ms: elapsedMs(state.created_at, at),
+    stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
+    blocker: state.blocker,
+    latest_event: latestEvent
+  });
+}
 function setRunStatus(state, status, at = timestamp()) {
   state.status = status;
   state.ok = status !== "blocked" && status !== "failed";
@@ -279,7 +359,8 @@ async function notifyIfConfigured(input) {
 async function runRiddleProof(input) {
   const state = input.state || createRunState({
     request: input.request,
-    state_path: input.state_path
+    state_path: input.state_path,
+    worktree_path: input.workdir
   });
   const adapters = input.adapters || {};
   const maxIterations = Math.max(1, Math.trunc(input.max_iterations ?? 1));
@@ -289,12 +370,70 @@ async function runRiddleProof(input) {
     stage: "setup",
     summary: "Riddle Proof run started.",
     details: {
+      run_id: state.run_id,
+      state_path: state.state_path,
+      worktree_path: state.worktree_path,
+      branch: state.branch,
       max_iterations: maxIterations,
       ship_mode: state.request.ship_mode || "none"
     }
   });
+  appendStageHeartbeat(state, {
+    stage: "setup",
+    summary: "Setup stage is active.",
+    details: {
+      run_id: state.run_id,
+      state_path: state.state_path,
+      worktree_path: state.worktree_path,
+      branch: state.branch
+    }
+  });
   let workdir = input.workdir;
   let evidenceContext;
+  if (adapters.preflight) {
+    appendRunEvent(state, {
+      kind: "preflight.started",
+      checkpoint: "preflight_started",
+      stage: "preflight",
+      summary: "Riddle Proof preflight adapter started."
+    });
+    try {
+      const preflight = await adapters.preflight.preflight({ request: state.request, state });
+      if (!preflight.ok) {
+        return blockRun({
+          state,
+          stage: "preflight",
+          blocker: adapterBlocker(
+            "preflight_failed",
+            "The preflight adapter found blocking tool or model configuration issues.",
+            "preflight_failed",
+            {
+              blockers: preflight.blockers,
+              warnings: preflight.warnings,
+              degraded_capabilities: preflight.degraded_capabilities
+            }
+          ),
+          raw: { preflight }
+        });
+      }
+      appendRunEvent(state, {
+        kind: "preflight.completed",
+        checkpoint: "preflight_completed",
+        stage: "preflight",
+        summary: "Riddle Proof preflight adapter completed.",
+        details: {
+          warnings: preflight.warnings,
+          degraded_capabilities: preflight.degraded_capabilities
+        }
+      });
+    } catch (error) {
+      return blockRun({
+        state,
+        stage: "preflight",
+        blocker: adapterBlocker("preflight_exception", "The preflight adapter threw an exception.", "preflight_failed", errorDetails(error))
+      });
+    }
+  }
   if (adapters.setup) {
     appendRunEvent(state, {
       kind: "setup.started",
@@ -317,7 +456,9 @@ async function runRiddleProof(input) {
           raw: { setup }
         });
       }
-      workdir = setup.workdir || workdir;
+      workdir = setup.worktree_path || setup.workdir || workdir;
+      state.worktree_path = setup.worktree_path || setup.workdir || state.worktree_path;
+      state.branch = setup.branch || state.branch;
       evidenceContext = setup.evidence_context;
       appendRunEvent(state, {
         kind: "setup.completed",
@@ -326,6 +467,9 @@ async function runRiddleProof(input) {
         summary: "Riddle Proof setup adapter completed.",
         details: {
           has_workdir: Boolean(workdir),
+          worktree_path: state.worktree_path,
+          branch: state.branch,
+          cleanup_policy: setup.cleanup_policy,
           has_evidence_context: Boolean(evidenceContext)
         }
       });
@@ -378,6 +522,11 @@ async function runRiddleProof(input) {
   let assessment;
   for (let attempt = 0; attempt < maxIterations; attempt += 1) {
     state.iterations += 1;
+    appendStageHeartbeat(state, {
+      stage: "implement",
+      summary: "Implementation stage is active.",
+      details: { iteration: state.iterations }
+    });
     appendRunEvent(state, {
       kind: "implementation.started",
       checkpoint: "implementation_started",
@@ -424,6 +573,13 @@ async function runRiddleProof(input) {
         tests_run: implementation.tests_run
       }
     });
+    appendStageHeartbeat(state, {
+      stage: "prove",
+      summary: "Proof capture stage is active.",
+      details: {
+        verification_mode: state.request.verification_mode
+      }
+    });
     appendRunEvent(state, {
       kind: "proof.started",
       checkpoint: "proof_started",
@@ -473,6 +629,13 @@ async function runRiddleProof(input) {
       stage: "verify",
       summary: "Judge adapter started."
     });
+    appendStageHeartbeat(state, {
+      stage: "verify",
+      summary: "Verification stage is active.",
+      details: {
+        verification_mode: evidenceBundle.verification_mode
+      }
+    });
     try {
       assessment = await adapters.judge.assessProof({ state, evidence_bundle: evidenceBundle });
       state.proof_decision = assessment.decision;
@@ -562,6 +725,10 @@ async function runRiddleProof(input) {
     stage: "ship",
     summary: "Ship adapter started."
   });
+  appendStageHeartbeat(state, {
+    stage: "ship",
+    summary: "Ship stage is active."
+  });
   let metadata;
   try {
     metadata = await adapters.ship.ship({ state, assessment });
@@ -596,21 +763,681 @@ async function runRiddleProof(input) {
   });
   return notifyIfConfigured({ state, result, notification: adapters.notification });
 }
+
+// src/engine-harness.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+var import_node_crypto = __toESM(require("crypto"), 1);
+function timestamp2() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function createHarnessStatePath(stateDir) {
+  const stamp = timestamp2().replace(/\D/g, "").slice(0, 14) || "unknown";
+  return import_node_path.default.join(stateDir, `riddle-proof-run-${stamp}-${import_node_crypto.default.randomUUID().slice(0, 8)}.json`);
+}
+function ensureParent(filePath) {
+  (0, import_node_fs.mkdirSync)(import_node_path.default.dirname(filePath), { recursive: true });
+}
+function readJson(filePath) {
+  if (!filePath || !(0, import_node_fs.existsSync)(filePath)) return null;
+  try {
+    return JSON.parse((0, import_node_fs.readFileSync)(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJson(filePath, payload) {
+  ensureParent(filePath);
+  (0, import_node_fs.writeFileSync)(filePath, JSON.stringify(payload, null, 2) + "\n");
+}
+function loadRunState(input) {
+  if (input.state) return input.state;
+  const stateDir = input.config?.stateDir || "/tmp";
+  const statePath = input.state_path || input.request.harness_state_path || createHarnessStatePath(stateDir);
+  const existing = readJson(statePath);
+  if (existing?.version === "riddle-proof.run-state.v1" && Array.isArray(existing.events) && existing.request) {
+    return existing;
+  }
+  return createRunState({
+    request: input.request,
+    state_path: statePath
+  });
+}
+function persist(state) {
+  if (state.state_path) writeJson(state.state_path, state);
+}
+function recordEvent(state, event) {
+  appendRunEvent(state, event);
+  persist(state);
+}
+function heartbeat(state, input) {
+  appendStageHeartbeat(state, input);
+  persist(state);
+}
+function jsonParam(payload) {
+  return JSON.stringify(payload);
+}
+function engineStatePath(result, state) {
+  return nonEmptyString(result.state_path) || nonEmptyString(state.request.engine_state_path);
+}
+function fullRiddleState(result, state) {
+  return readJson(engineStatePath(result, state)) || recordValue(result.state) || null;
+}
+function workdirFromState(state) {
+  return nonEmptyString(state?.after_worktree) || nonEmptyString(state?.worktree_path) || null;
+}
+function hasGitDiff(workdir) {
+  if (!workdir || !(0, import_node_fs.existsSync)(workdir)) return false;
+  try {
+    const status = (0, import_node_child_process.execFileSync)("git", ["status", "--porcelain"], {
+      cwd: workdir,
+      encoding: "utf-8",
+      timeout: 1e4
+    });
+    return status.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+function removeEmptyToolArtifacts(workdir) {
+  if (!workdir || !(0, import_node_fs.existsSync)(workdir)) return [];
+  const artifactPath = import_node_path.default.join(workdir, ".codex");
+  if (!(0, import_node_fs.existsSync)(artifactPath)) return [];
+  try {
+    const status = (0, import_node_child_process.execFileSync)("git", ["status", "--porcelain", "--", ".codex"], {
+      cwd: workdir,
+      encoding: "utf-8",
+      timeout: 1e4
+    }).trim();
+    const stat = (0, import_node_fs.statSync)(artifactPath);
+    if (status.startsWith("?? ") && stat.isFile() && stat.size === 0) {
+      (0, import_node_fs.unlinkSync)(artifactPath);
+      return [".codex"];
+    }
+  } catch {
+    return [];
+  }
+  return [];
+}
+function stageFromCheckpoint(result) {
+  const explicitStage = nonEmptyString(result.stage);
+  if (explicitStage) return explicitStage;
+  const checkpoint = String(result.checkpoint || "");
+  if (checkpoint.startsWith("recon_")) return "recon";
+  if (checkpoint.startsWith("author_")) return "author";
+  if (checkpoint.startsWith("implement_")) return "implement";
+  if (checkpoint.startsWith("verify_")) return "verify";
+  if (checkpoint.startsWith("ship_")) return "ship";
+  if (checkpoint.includes("capture")) return "prove";
+  return "setup";
+}
+function stageFromWorkflowParams(params) {
+  const stage = nonEmptyString(params.advance_stage);
+  if (stage) return stage;
+  if (params.ship_after_verify) return "ship";
+  if (params.proof_assessment_json) return "verify";
+  if (params.implementation_notes) return "verify";
+  if (params.author_packet_json) return "implement";
+  if (params.recon_assessment_json) return "author";
+  return "setup";
+}
+function baseContinuation(result) {
+  return {
+    action: "run",
+    state_path: String(result.state_path || ""),
+    continue_from_checkpoint: true
+  };
+}
+function initialRunParams(request, input, state) {
+  return compactRecord({
+    action: "run",
+    repo: request.repo,
+    branch: request.branch,
+    change_request: request.change_request,
+    commit_message: request.commit_message,
+    prod_url: request.prod_url,
+    capture_script: request.capture_script,
+    success_criteria: request.success_criteria,
+    assertions_json: typeof request.assertions === "string" ? request.assertions : request.assertions === void 0 ? void 0 : JSON.stringify(request.assertions),
+    verification_mode: request.verification_mode,
+    reference: request.reference,
+    base_branch: request.base_branch,
+    before_ref: request.before_ref,
+    allow_static_preview_fallback: request.allow_static_preview_fallback,
+    context: request.context,
+    reviewer: request.reviewer,
+    mode: request.mode,
+    build_command: request.build_command,
+    build_output: request.build_output,
+    server_image: request.server_image,
+    server_command: request.server_command,
+    server_port: request.server_port,
+    server_path: request.server_path,
+    use_auth: request.use_auth,
+    color_scheme: request.color_scheme,
+    wait_for_selector: request.wait_for_selector,
+    discord_channel: request.integration_context?.channel_id,
+    discord_thread_id: request.integration_context?.thread_id,
+    discord_message_id: request.integration_context?.message_id,
+    discord_source_url: request.integration_context?.source_url,
+    state_path: request.engine_state_path || state.request.engine_state_path,
+    auto_approve: input.auto_approve ?? request.auto_approve
+  });
+}
+function effectiveShipMode(request, config) {
+  return request.ship_mode || config?.defaultShipMode || "ship";
+}
+function checkpointContinueStage(result) {
+  const resume = recordValue(result.checkpointContract?.resume);
+  return nonEmptyString(resume?.continue_with_stage);
+}
+function recommendedContinuation(result) {
+  const continueStage = checkpointContinueStage(result);
+  if (!continueStage) return null;
+  return {
+    action: "run",
+    state_path: String(result.state_path || ""),
+    advance_stage: continueStage
+  };
+}
+function defaultAwaitingStageContinuation(result) {
+  const contract = recordValue(result.checkpointContract) || {};
+  const stage = nonEmptyString(contract.stage) || nonEmptyString(result.stage) || "";
+  const nextStage = stage === "setup" ? "recon" : stage === "recon" ? "author" : stage === "author" ? "implement" : stage === "implement" || stage === "verify" ? "verify" : "";
+  if (!nextStage) return null;
+  return {
+    action: "run",
+    state_path: String(result.state_path || ""),
+    advance_stage: nextStage
+  };
+}
+function isReadyShipGate(result) {
+  const gate = recordValue(result.shipGate) || recordValue(result.checkpointContract?.ship_gate);
+  return Boolean(gate && gate.ok === true);
+}
+function proofAssessmentRequestsShip(payload) {
+  const decision = String(payload.decision || "");
+  const recommendedStage = String(payload.recommended_stage || "");
+  const continueStage = String(payload.continue_with_stage || "");
+  return decision === "ready_to_ship" || recommendedStage === "ship" || continueStage === "ship";
+}
+function proofAssessmentContinuation(request, result, payload, config) {
+  const proof_assessment_json = jsonParam(payload);
+  if (effectiveShipMode(request, config) === "ship" || !proofAssessmentRequestsShip(payload)) {
+    return { ...baseContinuation(result), proof_assessment_json };
+  }
+  return {
+    action: "run",
+    state_path: String(result.state_path || ""),
+    advance_stage: "verify",
+    proof_assessment_json
+  };
+}
+function contextFor(request, state, result) {
+  return {
+    request,
+    state,
+    engineResult: result,
+    fullRiddleState: fullRiddleState(result, state),
+    checkpoint: String(result.checkpoint || "unknown")
+  };
+}
+function requirePayload(action, payload, state, result) {
+  if (payload.blocker || payload.ok === false) {
+    return payload.blocker || {
+      code: `${action}_blocked`,
+      checkpoint: result.checkpoint || null,
+      message: payload.summary || `${action} did not return a usable payload.`
+    };
+  }
+  if (!payload.payload || typeof payload.payload !== "object") {
+    return {
+      code: `${action}_missing_payload`,
+      checkpoint: result.checkpoint || null,
+      message: `${action} did not return the JSON payload required by the riddle-proof checkpoint.`,
+      details: {
+        run_id: state.run_id,
+        state_path: state.state_path
+      }
+    };
+  }
+  return null;
+}
+function terminalResult(state, status, result, summary, raw = {}) {
+  setRunStatus(state, status);
+  const metadata = normalizeTerminalMetadata({
+    riddleState: result ? fullRiddleState(result, state) : null,
+    engineResult: result
+  });
+  applyTerminalMetadata(state, metadata);
+  persist(state);
+  return createRunResult({
+    state,
+    status,
+    last_summary: summary,
+    metadata,
+    raw: {
+      engine_state_path: result?.state_path || state.request.engine_state_path || null,
+      last_result: result,
+      ...raw
+    }
+  });
+}
+function blockerResult(state, result, blocker) {
+  state.blocker = blocker;
+  recordEvent(state, {
+    kind: "run.blocked",
+    checkpoint: blocker.checkpoint || result?.checkpoint || null,
+    stage: stageFromCheckpoint(result || {}),
+    summary: blocker.message,
+    details: {
+      code: blocker.code,
+      ...blocker.details
+    }
+  });
+  setRunStatus(state, "blocked");
+  persist(state);
+  return createRunResult({
+    state,
+    status: "blocked",
+    last_summary: blocker.message,
+    raw: {
+      engine_state_path: result?.state_path || state.request.engine_state_path || null,
+      last_result: result
+    }
+  });
+}
+function disabledAdapterPayload(action, context) {
+  return {
+    ok: false,
+    blocker: {
+      code: "agent_adapter_not_configured",
+      checkpoint: context.checkpoint,
+      message: `No agent adapter is configured for ${action}. The engine harness reached the checkpoint safely and stopped before faking agent output.`,
+      details: {
+        run_id: context.state.run_id,
+        state_path: context.state.state_path,
+        engine_state_path: context.engineResult.state_path || null,
+        checkpointContract: context.engineResult.checkpointContract || null
+      }
+    }
+  };
+}
+function createDisabledRiddleProofAgentAdapter() {
+  return {
+    assessRecon: (context) => Promise.resolve(disabledAdapterPayload("recon assessment", context)),
+    authorProofPacket: (context) => Promise.resolve(disabledAdapterPayload("proof packet authoring", context)),
+    implementChange: (context) => Promise.resolve(disabledAdapterPayload("implementation", context)),
+    assessProof: (context) => Promise.resolve(disabledAdapterPayload("proof assessment", context))
+  };
+}
+async function resolveEngine(input) {
+  if (typeof input.engine === "function") return input.engine();
+  if (input.engine) return input.engine;
+  const moduleUrl = input.config?.riddleEngineModuleUrl;
+  if (!moduleUrl) {
+    throw new Error("No riddle engine adapter or riddleEngineModuleUrl is configured.");
+  }
+  const mod = await import(moduleUrl);
+  if (typeof mod.createRiddleProofEngine !== "function") {
+    throw new Error(`Riddle engine module does not export createRiddleProofEngine: ${moduleUrl}`);
+  }
+  return mod.createRiddleProofEngine({
+    riddleProofDir: input.config?.riddleProofDir,
+    defaultReviewer: input.config?.defaultReviewer
+  });
+}
+async function handleImplementation(request, state, result, agent) {
+  const context = contextFor(request, state, result);
+  const workdir = workdirFromState(context.fullRiddleState);
+  state.worktree_path = workdir || state.worktree_path;
+  state.branch = nonEmptyString(context.fullRiddleState?.branch) || state.branch;
+  persist(state);
+  if (!workdir || !(0, import_node_fs.existsSync)(workdir)) {
+    return {
+      blocker: {
+        code: "implementation_worktree_missing",
+        checkpoint: result.checkpoint || null,
+        message: "The Riddle Proof engine state does not include an isolated after worktree that exists on disk.",
+        details: {
+          worktree_path: workdir || null,
+          engine_state_path: result.state_path || null
+        }
+      }
+    };
+  }
+  const implementation = await agent.implementChange({ ...context, workdir });
+  if (implementation.blocker || implementation.ok === false) {
+    return {
+      blocker: implementation.blocker || {
+        code: "implementation_blocked",
+        checkpoint: result.checkpoint || null,
+        message: implementation.summary || "Implementation adapter did not complete."
+      }
+    };
+  }
+  const cleanedArtifacts = removeEmptyToolArtifacts(workdir);
+  const diffDetected = implementation.diffDetected === true || hasGitDiff(workdir);
+  if (!diffDetected) {
+    return {
+      blocker: {
+        code: "implementation_diff_missing",
+        checkpoint: result.checkpoint || null,
+        message: "The implementation adapter returned, but the after worktree has no detectable git diff. The harness will not advance to verify.",
+        details: { worktree_path: workdir || null }
+      }
+    };
+  }
+  recordEvent(state, {
+    kind: "agent.implementation.completed",
+    checkpoint: result.checkpoint || null,
+    stage: "implement",
+    summary: implementation.summary || "Implementation adapter reported code changes.",
+    details: {
+      worktree_path: workdir || null,
+      diffDetected,
+      changed_files: implementation.changedFiles || [],
+      cleaned_artifacts: cleanedArtifacts
+    }
+  });
+  return {
+    next: compactRecord({
+      ...baseContinuation(result),
+      advance_stage: "implement",
+      implementation_notes: implementation.implementationNotes || implementation.summary
+    })
+  };
+}
+async function routeCheckpoint(request, state, result, agent, input) {
+  const checkpoint = String(result.checkpoint || "");
+  const context = contextFor(request, state, result);
+  if (!checkpoint) {
+    return {
+      terminal: terminalResult(state, "completed", result, result.summary || "Riddle Proof engine completed.")
+    };
+  }
+  if ([
+    "recon_human_escalation",
+    "verify_human_escalation",
+    "ship_gate_blocked",
+    "verify_required",
+    "verify_supervisor_judgment_required"
+  ].includes(checkpoint) && result.ok === false) {
+    return {
+      blocker: {
+        code: checkpoint,
+        checkpoint,
+        message: result.summary || `Riddle Proof blocked at ${checkpoint}.`,
+        details: { checkpointContract: result.checkpointContract || null }
+      }
+    };
+  }
+  if (checkpoint === "ship_review") {
+    return {
+      terminal: terminalResult(state, "shipped", result, result.summary || "Riddle Proof shipped.")
+    };
+  }
+  if (checkpoint === "verify_ship_ready") {
+    const shipMode = effectiveShipMode(request, input.config);
+    if (shipMode === "ship") {
+      if (!isReadyShipGate(result)) {
+        return {
+          blocker: {
+            code: "ship_gate_not_ready",
+            checkpoint,
+            message: "The harness reached verify_ship_ready, but the ship gate is not passing. It will not call ship.",
+            details: { shipGate: result.shipGate || result.checkpointContract?.ship_gate || null }
+          }
+        };
+      }
+      return { next: { ...baseContinuation(result), ship_after_verify: true } };
+    }
+    return {
+      terminal: terminalResult(state, "ready_to_ship", result, result.summary || "Riddle Proof is ready to ship.", {
+        ship_held: true
+      })
+    };
+  }
+  if (input.dry_run || request.dry_run) {
+    return {
+      blocker: {
+        code: "dry_run_checkpoint",
+        checkpoint,
+        message: "Dry run stopped before applying agent input to the Riddle Proof workflow.",
+        details: { checkpointContract: result.checkpointContract || null }
+      }
+    };
+  }
+  if (checkpoint === "recon_supervisor_judgment") {
+    const assessment = await agent.assessRecon(context);
+    const blocker = requirePayload("recon_assessment", assessment, state, result);
+    if (blocker) return { blocker };
+    recordEvent(state, {
+      kind: "agent.recon_assessment.completed",
+      checkpoint,
+      stage: "recon",
+      summary: assessment.summary,
+      details: { payload: assessment.payload }
+    });
+    return {
+      next: { ...baseContinuation(result), recon_assessment_json: jsonParam(assessment.payload) }
+    };
+  }
+  const continueStage = checkpointContinueStage(result);
+  const checkpointContinuesToAuthor = continueStage === "author";
+  if (checkpoint === "author_supervisor_judgment" || checkpoint === "verify_capture_retry" || checkpoint === "verify_agent_retry" && checkpointContinuesToAuthor) {
+    const packet = await agent.authorProofPacket(context);
+    const blocker = requirePayload("author_packet", packet, state, result);
+    if (blocker) return { blocker };
+    recordEvent(state, {
+      kind: "agent.author_packet.completed",
+      checkpoint,
+      stage: "author",
+      summary: packet.summary,
+      details: { payload: packet.payload }
+    });
+    return {
+      next: { ...baseContinuation(result), author_packet_json: jsonParam(packet.payload) }
+    };
+  }
+  if (checkpoint === "implement_changes_missing" || checkpoint === "implement_required" || checkpoint === "verify_agent_retry" && continueStage === "implement") {
+    return handleImplementation(request, state, result, agent);
+  }
+  if (checkpoint === "implement_review") {
+    return { next: { action: "run", state_path: String(result.state_path || ""), advance_stage: "verify" } };
+  }
+  if (checkpoint === "verify_supervisor_judgment") {
+    const assessment = await agent.assessProof(context);
+    const blocker = requirePayload("proof_assessment", assessment, state, result);
+    if (blocker) return { blocker };
+    const payload = assessment.payload;
+    recordEvent(state, {
+      kind: "agent.proof_assessment.completed",
+      checkpoint,
+      stage: "verify",
+      summary: assessment.summary,
+      details: { payload }
+    });
+    return { next: proofAssessmentContinuation(request, result, payload, input.config) };
+  }
+  if (checkpoint === "verify_agent_retry") {
+    const next = recommendedContinuation(result);
+    if (next) return { next };
+  }
+  if (checkpoint === "awaiting_stage_advance") {
+    const next = recommendedContinuation(result) || defaultAwaitingStageContinuation(result);
+    if (next) {
+      if (String(next.advance_stage || "") === "ship" && effectiveShipMode(request, input.config) !== "ship") {
+        return {
+          terminal: terminalResult(state, "ready_to_ship", result, result.summary || "Riddle Proof is ready to ship.", {
+            ship_held: true
+          })
+        };
+      }
+      return { next };
+    }
+  }
+  if (checkpoint.endsWith("_review")) {
+    const next = recommendedContinuation(result);
+    if (next) return { next };
+  }
+  return {
+    blocker: {
+      code: "unhandled_checkpoint",
+      checkpoint,
+      message: `The harness does not yet know how to safely continue checkpoint ${checkpoint}.`,
+      details: { checkpointContract: result.checkpointContract || null }
+    }
+  };
+}
+function readRiddleProofRunStatus(state_path) {
+  const state = readJson(state_path);
+  if (state?.version !== "riddle-proof.run-state.v1" || !Array.isArray(state.events)) return null;
+  return createRunStatusSnapshot(state);
+}
+async function runRiddleProofEngineHarness(input) {
+  const state = loadRunState(input);
+  state.request = normalizeRunParams({ ...state.request, ...input.request });
+  const request = state.request;
+  const agent = input.agent || createDisabledRiddleProofAgentAdapter();
+  const maxIterations = Math.max(
+    1,
+    Math.trunc(input.max_iterations ?? request.max_iterations ?? input.config?.defaultMaxIterations ?? 8)
+  );
+  state.status = "running";
+  state.ok = void 0;
+  state.blocker = void 0;
+  persist(state);
+  recordEvent(state, {
+    kind: "engine_harness.started",
+    checkpoint: "engine_harness_started",
+    stage: "setup",
+    summary: "Riddle Proof engine harness started.",
+    details: {
+      run_id: state.run_id,
+      state_path: state.state_path,
+      engine_state_path: request.engine_state_path || null,
+      max_iterations: maxIterations,
+      ship_mode: effectiveShipMode(request, input.config)
+    }
+  });
+  let engine;
+  try {
+    engine = await resolveEngine(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return blockerResult(state, null, {
+      code: "riddle_engine_not_configured",
+      checkpoint: "engine_resolve_failed",
+      message
+    });
+  }
+  let nextParams = initialRunParams(request, input, state);
+  let lastResult = null;
+  for (let index = 0; index < maxIterations; index += 1) {
+    state.iterations += 1;
+    const stage = stageFromWorkflowParams(nextParams);
+    heartbeat(state, {
+      stage,
+      summary: `${stage} stage is active.`,
+      details: {
+        iteration: state.iterations,
+        run_id: state.run_id,
+        state_path: state.state_path,
+        engine_state_path: nextParams.state_path || null,
+        worktree_path: state.worktree_path || null,
+        branch: state.branch || null
+      }
+    });
+    recordEvent(state, {
+      kind: "engine.call",
+      checkpoint: "engine_call",
+      stage,
+      summary: "Calling Riddle Proof engine.",
+      details: { params: nextParams }
+    });
+    let result;
+    try {
+      result = await engine.execute(nextParams);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return blockerResult(state, lastResult, {
+        code: "riddle_engine_exception",
+        checkpoint: "engine_call_failed",
+        message
+      });
+    }
+    lastResult = result;
+    const engineState = engineStatePath(result, state);
+    if (engineState) state.request.engine_state_path = engineState;
+    state.last_checkpoint = result.checkpoint || state.last_checkpoint || null;
+    const resultStage = stageFromCheckpoint(result);
+    heartbeat(state, {
+      stage: resultStage,
+      summary: `${resultStage} stage is active.`,
+      details: {
+        iteration: state.iterations,
+        run_id: state.run_id,
+        state_path: state.state_path,
+        engine_state_path: engineState || null,
+        checkpoint: result.checkpoint || null
+      }
+    });
+    recordEvent(state, {
+      kind: "engine.result",
+      checkpoint: result.checkpoint || null,
+      stage: resultStage,
+      summary: result.summary,
+      details: {
+        ok: result.ok ?? null,
+        engine_state_path: engineState || null,
+        checkpoint: result.checkpoint || null
+      }
+    });
+    const routed = await routeCheckpoint(request, state, result, agent, input);
+    if (routed.terminal) return routed.terminal;
+    if (routed.blocker) return blockerResult(state, result, routed.blocker);
+    if (!routed.next) {
+      return blockerResult(state, result, {
+        code: "missing_next_step",
+        checkpoint: result.checkpoint || null,
+        message: "The harness route returned no next step."
+      });
+    }
+    nextParams = routed.next;
+  }
+  return blockerResult(state, lastResult, {
+    code: "max_iterations_reached",
+    checkpoint: lastResult?.checkpoint || null,
+    message: `The harness reached max_iterations=${maxIterations} before the proof was ready or shipped.`,
+    details: {
+      nextParams,
+      lastCheckpoint: lastResult?.checkpoint || null,
+      lastSummary: lastResult?.summary || null
+    }
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent,
+  appendStageHeartbeat,
   applyTerminalMetadata,
   compactRecord,
+  createDisabledRiddleProofAgentAdapter,
   createRunResult,
   createRunState,
+  createRunStatusSnapshot,
   isSuccessfulStatus,
   isTerminalStatus,
   nonEmptyString,
   normalizeIntegrationContext,
   normalizeRunParams,
   normalizeTerminalMetadata,
+  readRiddleProofRunStatus,
   recordValue,
   runRiddleProof,
+  runRiddleProofEngineHarness,
   setRunStatus
 });