@riddledc/riddle-proof 0.5.46 → 0.5.48

package/README.md

@@ -63,9 +63,10 @@ Codex/CLI-style testing:
 
 ```sh
 riddle-proof-loop run --request-json request.json --checkpoint-mode yield
+riddle-proof-loop run --request-json request.json --agent local
 riddle-proof-loop status --state-path /tmp/riddle-proof-run.json
 riddle-proof-loop respond --state-path /tmp/riddle-proof-run.json --response-json response.json
-riddle-proof-loop doctor codex_exec
+riddle-proof-loop doctor local
 ```
 
 In yield mode, the harness returns portable checkpoint packets for recon,
@@ -73,6 +74,10 @@ authoring, implementation, proof assessment, and evidence recovery. A host can
 answer those packets with `riddle-proof.checkpoint_response.v1` JSON without
 needing OpenClaw-specific proof semantics.
 
+`--agent local` is the generic CLI executor slot. The current implementation
+uses the local Codex CLI adapter underneath, but the loop contract and CLI
+surface are intentionally not Codex-specific.
+
 ## Runner Harness
 
 `runRiddleProof` is the reusable idea-to-PR workflow driver. It does not ship

package/dist/{chunk-X3AQ2WUM.js → chunk-2RS4PBYK.js}

@@ -10,7 +10,7 @@ import {
   createRunStatusSnapshot,
   normalizeRunParams,
   setRunStatus
-} from "./chunk-JTNMEH57.js";
+} from "./chunk-JOXTKWX6.js";
 import {
   createRiddleProofRunCard
 } from "./chunk-PLSGW2GI.js";
@@ -281,6 +281,20 @@ function checkpointContinueStage(result) {
   const resume = recordValue(result.checkpointContract?.resume);
   return nonEmptyString(resume?.continue_with_stage);
 }
+function checkpointRecommendedStage(result) {
+  const resumeStage = checkpointContinueStage(result);
+  if (resumeStage) return resumeStage;
+  return nonEmptyString(result.checkpointContract?.recommended_advance_stage) || nonEmptyString(result.decisionRequest?.continue_with_stage) || nonEmptyString(result.decisionRequest?.recommended_advance_stage) || nonEmptyString(recordValue(result.decisionRequest)?.continueWithStage) || nonEmptyString(recordValue(result.decisionRequest)?.recommendedAdvanceStage);
+}
+function stageCheckpointContinuation(result) {
+  const stage = checkpointRecommendedStage(result);
+  if (!stage) return null;
+  return {
+    action: "run",
+    state_path: String(result.state_path || ""),
+    advance_stage: stage
+  };
+}
 function recommendedContinuation(result) {
   const continueStage = checkpointContinueStage(result);
   if (!continueStage) return null;
@@ -323,6 +337,18 @@ function defaultStageForProofCheckpointDecision(decision) {
   if (decision === "needs_richer_proof") return "author";
   return null;
 }
+function checkpointContractFromPacket(packet) {
+  return recordValue(packet.evidence_excerpt?.checkpoint_contract) || recordValue(recordValue(packet.state_excerpt?.stage_decision_request)?.checkpoint_contract) || null;
+}
+function stageFromCheckpointResponse(response, packet) {
+  if (response.decision === "needs_recon") return "recon";
+  if (response.decision === "needs_implementation") return "implement";
+  const payload = recordValue(response.payload) || {};
+  const contract = checkpointContractFromPacket(packet);
+  const resume = recordValue(contract?.resume);
+  const stage = response.continue_with_stage || nonEmptyString(payload.continue_with_stage) || nonEmptyString(payload.recommended_stage) || nonEmptyString(resume?.continue_with_stage) || (response.decision === "retry_stage" ? packet.stage : "");
+  return stage ? stage : null;
+}
 function proofAssessmentPayloadFromCheckpointResponse(response) {
   if (![
     "ready_to_ship",
@@ -425,6 +451,13 @@ function visualDeltaEvidenceRecoveryAssessment(state, payload, blocker) {
     blockers: [...blockers, blocker]
   };
 }
+function isRecoverableStageCheckpoint(checkpoint) {
+  return [
+    "ship_gate_blocked",
+    "verify_required",
+    "verify_supervisor_judgment_required"
+  ].includes(checkpoint);
+}
 function contextFor(request, state, result) {
   return {
     request,
@@ -771,6 +804,18 @@ function checkpointResponseContinuation(state, value) {
       };
     }
   }
+  if (response.decision === "continue_stage" || response.decision === "retry_stage" || response.decision === "needs_implementation") {
+    const stage = stageFromCheckpointResponse(response, packet);
+    if (stage) {
+      appendCheckpointResponse(state, response);
+      return {
+        next: {
+          ...base,
+          advance_stage: stage
+        }
+      };
+    }
+  }
   appendCheckpointResponse(state, response, { clear_packet: false });
   return {
     blocker: {
@@ -893,18 +938,23 @@ async function handleImplementation(request, state, result, agent) {
         adapter_details: implementation.details || null
       })
     });
-    return {
-      blocker: {
-        code: "implementation_diff_missing",
+    recordEvent(state, {
+      kind: "agent.implementation.retry_requested",
+      checkpoint: result.checkpoint || null,
+      stage: "implement",
+      summary: "Implementation adapter left no detectable diff; retrying the implement checkpoint inside the bounded loop.",
+      details: compactRecord({
+        worktree_path: workdir || null,
         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: compactRecord({
-          worktree_path: workdir || null,
-          changed_files: implementation.changedFiles || [],
-          tests_run: implementation.testsRun || [],
-          implementation_notes: implementation.implementationNotes || null,
-          adapter_details: implementation.details || null
-        })
+        next_stage: "implement"
+      })
+    });
+    return {
+      next: {
+        action: "run",
+        state_path: String(result.state_path || ""),
+        advance_stage: "implement",
+        implementation_notes: implementation.implementationNotes || implementation.summary || "Implementation adapter returned without a detectable git diff; retry the implement checkpoint."
       }
     };
   }
@@ -940,16 +990,32 @@ async function routeCheckpoint(request, state, result, agent, input) {
       terminal: terminalResult(state, "completed", result, result.summary || "Riddle Proof engine completed.")
     };
   }
+  if (isRecoverableStageCheckpoint(checkpoint) && !input.dry_run && !request.dry_run) {
+    if (input.checkpoint_mode === "yield") {
+      return { terminal: checkpointAwaitingResult(state, result, input.checkpoint_visibility) };
+    }
+    const next = stageCheckpointContinuation(result);
+    if (next) {
+      recordEvent(state, {
+        kind: "checkpoint.recovery_continuation",
+        checkpoint,
+        stage: stageFromCheckpoint(result),
+        summary: `Routing recoverable checkpoint ${checkpoint} back to ${next.advance_stage}.`,
+        details: {
+          next,
+          checkpointContract: result.checkpointContract || null
+        }
+      });
+      return { next };
+    }
+  }
   const failureBlocker = engineFailureBlocker(result, checkpoint);
   if (failureBlocker) {
     return { blocker: failureBlocker };
   }
   if ([
     "recon_human_escalation",
-    "verify_human_escalation",
-    "ship_gate_blocked",
-    "verify_required",
-    "verify_supervisor_judgment_required"
+    "verify_human_escalation"
   ].includes(checkpoint) && result.ok === false) {
     return {
       blocker: {

package/dist/{chunk-JTNMEH57.js → chunk-JOXTKWX6.js}

@@ -213,7 +213,7 @@ function createRunStatusSnapshot(state, at = timestamp()) {
     checkpoint_summary: state.checkpoint_summary,
     state_paths: state.state_paths,
     proof_contract: state.proof_contract,
-    run_card: createRiddleProofRunCard(state, { at }),
+    run_card: state.run_card || createRiddleProofRunCard(state, { at }),
     latest_event: latestEvent
   });
 }

package/dist/{chunk-L26NTZOU.js → chunk-N3ZNBRIG.js}

@@ -3,7 +3,7 @@ import {
   appendStageHeartbeat,
   createRunState,
   setRunStatus
-} from "./chunk-JTNMEH57.js";
+} from "./chunk-JOXTKWX6.js";
 import {
   createRunResult
 } from "./chunk-DUFDZJOF.js";

package/dist/cli.cjs

@@ -1747,9 +1747,27 @@ async function executeWorkflow(params, pluginConfig, resolvedConfig) {
     }
     return "inspect the ship gate details, repair the missing invariant, then resume the run";
   };
+  const shipGateRecoveryStage = (shipGate) => {
+    const reasons = shipGate.reasons || [];
+    if (reasons.some((reason) => reason.includes("before_cdn") || reason.includes("prod_cdn") || reason.includes("prod_url"))) {
+      return "recon";
+    }
+    if (reasons.some((reason) => reason.includes("implementation"))) {
+      return "implement";
+    }
+    if (reasons.some((reason) => reason.includes("after_cdn") || reason.includes("verify_status") || reason.includes("visual_delta"))) {
+      return "verify";
+    }
+    if (reasons.some((reason) => reason.includes("proof_assessment"))) {
+      return "verify";
+    }
+    return "verify";
+  };
   const shipGateBlocked = (state, executed, details = {}) => {
     const shipGate = validateShipGate(state);
     const nextAction = primaryShipGateNextAction(shipGate);
+    const recoveryStage = shipGateRecoveryStage(shipGate);
+    const advanceOptions = Array.from(/* @__PURE__ */ new Set([recoveryStage, "verify", "author", "implement", "recon", "ship"]));
     return checkpoint(
       "verify",
       "ship_gate_blocked",
@@ -1757,12 +1775,13 @@ async function executeWorkflow(params, pluginConfig, resolvedConfig) {
       {
         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",
+        advanceOptions,
+        recommendedAdvanceStage: recoveryStage,
+        continueWithStage: recoveryStage,
         blocking: true,
-        details: { ...details, shipGate, next_action: nextAction, executed },
+        details: { ...details, shipGate, next_action: nextAction, recovery_stage: recoveryStage, executed },
         nextAction,
+        recoveryStage,
         shipGate,
         verifyStatus: state?.verify_status || null,
         mergeRecommendation: state?.merge_recommendation || null,
@@ -3931,7 +3950,7 @@ function createRunStatusSnapshot(state, at = timestamp2()) {
     checkpoint_summary: state.checkpoint_summary,
     state_paths: state.state_paths,
     proof_contract: state.proof_contract,
-    run_card: createRiddleProofRunCard(state, { at }),
+    run_card: state.run_card || createRiddleProofRunCard(state, { at }),
     latest_event: latestEvent
   });
 }
@@ -4180,6 +4199,20 @@ function checkpointContinueStage2(result) {
   const resume = recordValue(result.checkpointContract?.resume);
   return nonEmptyString(resume?.continue_with_stage);
 }
+function checkpointRecommendedStage(result) {
+  const resumeStage = checkpointContinueStage2(result);
+  if (resumeStage) return resumeStage;
+  return nonEmptyString(result.checkpointContract?.recommended_advance_stage) || nonEmptyString(result.decisionRequest?.continue_with_stage) || nonEmptyString(result.decisionRequest?.recommended_advance_stage) || nonEmptyString(recordValue(result.decisionRequest)?.continueWithStage) || nonEmptyString(recordValue(result.decisionRequest)?.recommendedAdvanceStage);
+}
+function stageCheckpointContinuation(result) {
+  const stage = checkpointRecommendedStage(result);
+  if (!stage) return null;
+  return {
+    action: "run",
+    state_path: String(result.state_path || ""),
+    advance_stage: stage
+  };
+}
 function recommendedContinuation(result) {
   const continueStage = checkpointContinueStage2(result);
   if (!continueStage) return null;
@@ -4222,6 +4255,18 @@ function defaultStageForProofCheckpointDecision(decision) {
   if (decision === "needs_richer_proof") return "author";
   return null;
 }
+function checkpointContractFromPacket(packet) {
+  return recordValue(packet.evidence_excerpt?.checkpoint_contract) || recordValue(recordValue(packet.state_excerpt?.stage_decision_request)?.checkpoint_contract) || null;
+}
+function stageFromCheckpointResponse(response, packet) {
+  if (response.decision === "needs_recon") return "recon";
+  if (response.decision === "needs_implementation") return "implement";
+  const payload = recordValue(response.payload) || {};
+  const contract = checkpointContractFromPacket(packet);
+  const resume = recordValue(contract?.resume);
+  const stage = response.continue_with_stage || nonEmptyString(payload.continue_with_stage) || nonEmptyString(payload.recommended_stage) || nonEmptyString(resume?.continue_with_stage) || (response.decision === "retry_stage" ? packet.stage : "");
+  return stage ? stage : null;
+}
 function proofAssessmentPayloadFromCheckpointResponse(response) {
   if (![
     "ready_to_ship",
@@ -4324,6 +4369,13 @@ function visualDeltaEvidenceRecoveryAssessment(state, payload, blocker) {
     blockers: [...blockers, blocker]
   };
 }
+function isRecoverableStageCheckpoint(checkpoint) {
+  return [
+    "ship_gate_blocked",
+    "verify_required",
+    "verify_supervisor_judgment_required"
+  ].includes(checkpoint);
+}
 function contextFor(request, state, result) {
   return {
     request,
@@ -4670,6 +4722,18 @@ function checkpointResponseContinuation(state, value) {
       };
     }
   }
+  if (response.decision === "continue_stage" || response.decision === "retry_stage" || response.decision === "needs_implementation") {
+    const stage = stageFromCheckpointResponse(response, packet);
+    if (stage) {
+      appendCheckpointResponse(state, response);
+      return {
+        next: {
+          ...base,
+          advance_stage: stage
+        }
+      };
+    }
+  }
   appendCheckpointResponse(state, response, { clear_packet: false });
   return {
     blocker: {
@@ -4792,18 +4856,23 @@ async function handleImplementation(request, state, result, agent) {
         adapter_details: implementation.details || null
       })
     });
-    return {
-      blocker: {
-        code: "implementation_diff_missing",
+    recordEvent(state, {
+      kind: "agent.implementation.retry_requested",
+      checkpoint: result.checkpoint || null,
+      stage: "implement",
+      summary: "Implementation adapter left no detectable diff; retrying the implement checkpoint inside the bounded loop.",
+      details: compactRecord({
+        worktree_path: workdir || null,
         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: compactRecord({
-          worktree_path: workdir || null,
-          changed_files: implementation.changedFiles || [],
-          tests_run: implementation.testsRun || [],
-          implementation_notes: implementation.implementationNotes || null,
-          adapter_details: implementation.details || null
-        })
+        next_stage: "implement"
+      })
+    });
+    return {
+      next: {
+        action: "run",
+        state_path: String(result.state_path || ""),
+        advance_stage: "implement",
+        implementation_notes: implementation.implementationNotes || implementation.summary || "Implementation adapter returned without a detectable git diff; retry the implement checkpoint."
       }
     };
   }
@@ -4839,16 +4908,32 @@ async function routeCheckpoint(request, state, result, agent, input) {
       terminal: terminalResult(state, "completed", result, result.summary || "Riddle Proof engine completed.")
     };
   }
+  if (isRecoverableStageCheckpoint(checkpoint) && !input.dry_run && !request.dry_run) {
+    if (input.checkpoint_mode === "yield") {
+      return { terminal: checkpointAwaitingResult(state, result, input.checkpoint_visibility) };
+    }
+    const next = stageCheckpointContinuation(result);
+    if (next) {
+      recordEvent(state, {
+        kind: "checkpoint.recovery_continuation",
+        checkpoint,
+        stage: stageFromCheckpoint2(result),
+        summary: `Routing recoverable checkpoint ${checkpoint} back to ${next.advance_stage}.`,
+        details: {
+          next,
+          checkpointContract: result.checkpointContract || null
+        }
+      });
+      return { next };
+    }
+  }
   const failureBlocker = engineFailureBlocker(result, checkpoint);
   if (failureBlocker) {
     return { blocker: failureBlocker };
   }
   if ([
     "recon_human_escalation",
-    "verify_human_escalation",
-    "ship_gate_blocked",
-    "verify_required",
-    "verify_supervisor_judgment_required"
+    "verify_human_escalation"
   ].includes(checkpoint) && result.ok === false) {
     return {
       blocker: {
@@ -5988,12 +6073,13 @@ async function runCodexExecAgentDoctor(config = {}, runner = createCodexExecJson
 function usage() {
   return [
     "Usage:",
-    "  riddle-proof-loop run --request-json <file|json|-> [--agent disabled|codex_exec] [--checkpoint-mode yield|auto]",
+    "  riddle-proof-loop run --request-json <file|json|-> [--agent disabled|local] [--checkpoint-mode yield|auto]",
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop status --state-path <path>",
-    "  riddle-proof-loop doctor codex_exec [--codex-command <path>]",
+    "  riddle-proof-loop doctor local [--codex-command <path>]",
     "",
-    "The default CLI run mode is checkpoint-mode=yield unless --agent codex_exec is used."
+    "The default CLI run mode is checkpoint-mode=yield unless --agent local is used.",
+    "Compatibility aliases: --agent codex_exec and doctor codex_exec."
   ].join("\n");
 }
 function parseArgs(argv) {
@@ -6050,11 +6136,14 @@ function codexConfig(options) {
     codexFullAuto: codexFullAuto === "false" ? false : void 0
   };
 }
+function isLocalAgentMode(value) {
+  return value === "local" || value === "local_exec" || value === "codex_exec";
+}
 function agentFor(options) {
   const agentMode = optionString(options, "agent") || "disabled";
-  if (agentMode === "codex_exec") return createCodexExecAgentAdapter(codexConfig(options));
+  if (isLocalAgentMode(agentMode)) return createCodexExecAgentAdapter(codexConfig(options));
   if (agentMode === "disabled") return createDisabledRiddleProofAgentAdapter();
-  throw new Error(`Unsupported --agent ${agentMode}. Use disabled or codex_exec.`);
+  throw new Error(`Unsupported --agent ${agentMode}. Use disabled or local.`);
 }
 function requestForRun(options) {
   const statePath = optionString(options, "statePath");
@@ -6067,7 +6156,7 @@ function requestForRun(options) {
 function checkpointModeFor(options) {
   const explicit = optionString(options, "checkpointMode");
   if (explicit) return explicit;
-  return optionString(options, "agent") === "codex_exec" ? "auto" : "yield";
+  return isLocalAgentMode(optionString(options, "agent")) ? "auto" : "yield";
 }
 async function main() {
   const { positional, options } = parseArgs(process.argv.slice(2));
@@ -6079,7 +6168,7 @@ async function main() {
   }
   if (command === "doctor") {
     const subject = positional[1];
-    if (subject !== "codex_exec") throw new Error("Only `doctor codex_exec` is supported.");
+    if (!isLocalAgentMode(subject)) throw new Error("Only `doctor local` is supported.");
     const result = await runCodexExecAgentDoctor(codexConfig(options));
     process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
@@ -6109,6 +6198,7 @@ async function main() {
       agent: agentFor(options),
       config: {
         stateDir: optionString(options, "stateDir"),
+        riddleEngineModuleUrl: optionString(options, "riddleEngineModuleUrl"),
         riddleProofDir: optionString(options, "riddleProofDir"),
         defaultReviewer: optionString(options, "defaultReviewer"),
         defaultShipMode: optionString(options, "defaultShipMode")

package/dist/cli.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import {
-  createCodexExecAgentAdapter,
-  runCodexExecAgentDoctor
-} from "./chunk-NOBFZDZG.js";
 import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-X3AQ2WUM.js";
+} from "./chunk-2RS4PBYK.js";
 import "./chunk-4ASMX4R6.js";
-import "./chunk-JTNMEH57.js";
+import "./chunk-JFQXAJH2.js";
+import {
+  createCodexExecAgentAdapter,
+  runCodexExecAgentDoctor
+} from "./chunk-NOBFZDZG.js";
+import "./chunk-JOXTKWX6.js";
 import "./chunk-PLSGW2GI.js";
 import "./chunk-R6SCWJCI.js";
 import "./chunk-DUFDZJOF.js";
@@ -19,12 +20,13 @@ import { existsSync, readFileSync } from "fs";
 function usage() {
   return [
     "Usage:",
-    "  riddle-proof-loop run --request-json <file|json|-> [--agent disabled|codex_exec] [--checkpoint-mode yield|auto]",
+    "  riddle-proof-loop run --request-json <file|json|-> [--agent disabled|local] [--checkpoint-mode yield|auto]",
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop status --state-path <path>",
-    "  riddle-proof-loop doctor codex_exec [--codex-command <path>]",
+    "  riddle-proof-loop doctor local [--codex-command <path>]",
     "",
-    "The default CLI run mode is checkpoint-mode=yield unless --agent codex_exec is used."
+    "The default CLI run mode is checkpoint-mode=yield unless --agent local is used.",
+    "Compatibility aliases: --agent codex_exec and doctor codex_exec."
   ].join("\n");
 }
 function parseArgs(argv) {
@@ -81,11 +83,14 @@ function codexConfig(options) {
     codexFullAuto: codexFullAuto === "false" ? false : void 0
   };
 }
+function isLocalAgentMode(value) {
+  return value === "local" || value === "local_exec" || value === "codex_exec";
+}
 function agentFor(options) {
   const agentMode = optionString(options, "agent") || "disabled";
-  if (agentMode === "codex_exec") return createCodexExecAgentAdapter(codexConfig(options));
+  if (isLocalAgentMode(agentMode)) return createCodexExecAgentAdapter(codexConfig(options));
   if (agentMode === "disabled") return createDisabledRiddleProofAgentAdapter();
-  throw new Error(`Unsupported --agent ${agentMode}. Use disabled or codex_exec.`);
+  throw new Error(`Unsupported --agent ${agentMode}. Use disabled or local.`);
 }
 function requestForRun(options) {
   const statePath = optionString(options, "statePath");
@@ -98,7 +103,7 @@ function requestForRun(options) {
 function checkpointModeFor(options) {
   const explicit = optionString(options, "checkpointMode");
   if (explicit) return explicit;
-  return optionString(options, "agent") === "codex_exec" ? "auto" : "yield";
+  return isLocalAgentMode(optionString(options, "agent")) ? "auto" : "yield";
 }
 async function main() {
   const { positional, options } = parseArgs(process.argv.slice(2));
@@ -110,7 +115,7 @@ async function main() {
   }
   if (command === "doctor") {
     const subject = positional[1];
-    if (subject !== "codex_exec") throw new Error("Only `doctor codex_exec` is supported.");
+    if (!isLocalAgentMode(subject)) throw new Error("Only `doctor local` is supported.");
     const result = await runCodexExecAgentDoctor(codexConfig(options));
     process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
@@ -140,6 +145,7 @@ async function main() {
       agent: agentFor(options),
       config: {
         stateDir: optionString(options, "stateDir"),
+        riddleEngineModuleUrl: optionString(options, "riddleEngineModuleUrl"),
         riddleProofDir: optionString(options, "riddleProofDir"),
         defaultReviewer: optionString(options, "defaultReviewer"),
         defaultShipMode: optionString(options, "defaultShipMode")