@riddledc/riddle-proof 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-export { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter } from './types.cjs';
+export { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter } from './types.cjs';
 export { TerminalMetadataInput, applyTerminalMetadata, compactRecord, createRunResult, isSuccessfulStatus, isTerminalStatus, nonEmptyString, normalizeTerminalMetadata, recordValue } from './result.cjs';
-export { CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, RunEventInput, appendRunEvent, createRunState, normalizeIntegrationContext, normalizeRunParams, setRunStatus } from './state.cjs';
+export { CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, RunEventInput, appendRunEvent, appendStageHeartbeat, createRunState, createRunStatusSnapshot, normalizeIntegrationContext, normalizeRunParams, setRunStatus } from './state.cjs';
 export { RiddleProofRunnerAdapters, RunRiddleProofInput, runRiddleProof } from './runner.cjs';
+export { RiddleProofAgentAdapter, RiddleProofAgentPayload, RiddleProofEngine, RiddleProofEngineHarnessConfig, RiddleProofEngineHarnessContext, RiddleProofEngineResult, RiddleProofShipMode, RiddleProofWorkflowParams, RunRiddleProofEngineHarnessInput, createDisabledRiddleProofAgentAdapter, readRiddleProofRunStatus, runRiddleProofEngineHarness } from './engine-harness.cjs';

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter } from './types.js';
+export { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter } from './types.js';
 export { TerminalMetadataInput, applyTerminalMetadata, compactRecord, createRunResult, isSuccessfulStatus, isTerminalStatus, nonEmptyString, normalizeTerminalMetadata, recordValue } from './result.js';
-export { CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, RunEventInput, appendRunEvent, createRunState, normalizeIntegrationContext, normalizeRunParams, setRunStatus } from './state.js';
+export { CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, RunEventInput, appendRunEvent, appendStageHeartbeat, createRunState, createRunStatusSnapshot, normalizeIntegrationContext, normalizeRunParams, setRunStatus } from './state.js';
 export { RiddleProofRunnerAdapters, RunRiddleProofInput, runRiddleProof } from './runner.js';
+export { RiddleProofAgentAdapter, RiddleProofAgentPayload, RiddleProofEngine, RiddleProofEngineHarnessConfig, RiddleProofEngineHarnessContext, RiddleProofEngineResult, RiddleProofShipMode, RiddleProofWorkflowParams, RunRiddleProofEngineHarnessInput, createDisabledRiddleProofAgentAdapter, readRiddleProofRunStatus, runRiddleProofEngineHarness } from './engine-harness.js';

package/dist/index.js

@@ -1,14 +1,21 @@
+import {
+  createDisabledRiddleProofAgentAdapter,
+  readRiddleProofRunStatus,
+  runRiddleProofEngineHarness
+} from "./chunk-US63AYQU.js";
 import {
   runRiddleProof
-} from "./chunk-GWGXPNON.js";
+} from "./chunk-F65YYXVO.js";
 import {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent,
+  appendStageHeartbeat,
   createRunState,
+  createRunStatusSnapshot,
   normalizeIntegrationContext,
   normalizeRunParams,
   setRunStatus
-} from "./chunk-EPVZKWUS.js";
+} from "./chunk-5FHUOSNO.js";
 import {
   applyTerminalMetadata,
   compactRecord,
@@ -18,22 +25,27 @@ import {
   nonEmptyString,
   normalizeTerminalMetadata,
   recordValue
-} from "./chunk-2ZQNXVQC.js";
+} from "./chunk-5DC6YXN4.js";
 import "./chunk-6F4PWJZI.js";
 export {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent,
+  appendStageHeartbeat,
   applyTerminalMetadata,
   compactRecord,
+  createDisabledRiddleProofAgentAdapter,
   createRunResult,
   createRunState,
+  createRunStatusSnapshot,
   isSuccessfulStatus,
   isTerminalStatus,
   nonEmptyString,
   normalizeIntegrationContext,
   normalizeRunParams,
   normalizeTerminalMetadata,
+  readRiddleProofRunStatus,
   recordValue,
   runRiddleProof,
+  runRiddleProofEngineHarness,
   setRunStatus
 };

package/dist/openclaw.cjs

@@ -81,6 +81,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)
   });
 }
@@ -139,6 +144,11 @@ function toRiddleProofRunParams(params) {
     color_scheme: params.color_scheme,
     wait_for_selector: params.wait_for_selector,
     ship_mode: params.ship_mode || (params.ship_after_verify ? "ship" : void 0),
+    engine_state_path: params.state_path,
+    harness_state_path: params.harness_state_path,
+    max_iterations: params.max_iterations,
+    auto_approve: params.auto_approve,
+    dry_run: params.dry_run,
     integration_context: openClawIntegrationContext(params)
   });
 }

package/dist/openclaw.d.cts

@@ -28,6 +28,11 @@ interface OpenClawProofedChangeParams {
     wait_for_selector?: string;
     ship_after_verify?: boolean;
     ship_mode?: "none" | "ship";
+    state_path?: string;
+    harness_state_path?: string;
+    max_iterations?: number;
+    auto_approve?: boolean;
+    dry_run?: boolean;
     discord_channel?: string;
     discord_thread_id?: string;
     discord_message_id?: string;

package/dist/openclaw.d.ts

@@ -28,6 +28,11 @@ interface OpenClawProofedChangeParams {
     wait_for_selector?: string;
     ship_after_verify?: boolean;
     ship_mode?: "none" | "ship";
+    state_path?: string;
+    harness_state_path?: string;
+    max_iterations?: number;
+    auto_approve?: boolean;
+    dry_run?: boolean;
     discord_channel?: string;
     discord_thread_id?: string;
     discord_message_id?: string;

package/dist/openclaw.js

@@ -1,10 +1,10 @@
 import {
   normalizeIntegrationContext,
   normalizeRunParams
-} from "./chunk-EPVZKWUS.js";
+} from "./chunk-5FHUOSNO.js";
 import {
   compactRecord
-} from "./chunk-2ZQNXVQC.js";
+} from "./chunk-5DC6YXN4.js";
 
 // src/openclaw.ts
 function parseOpenClawAssertions(value) {
@@ -60,6 +60,11 @@ function toRiddleProofRunParams(params) {
     color_scheme: params.color_scheme,
     wait_for_selector: params.wait_for_selector,
     ship_mode: params.ship_mode || (params.ship_after_verify ? "ship" : void 0),
+    engine_state_path: params.state_path,
+    harness_state_path: params.harness_state_path,
+    max_iterations: params.max_iterations,
+    auto_approve: params.auto_approve,
+    dry_run: params.dry_run,
     integration_context: openClawIntegrationContext(params)
   });
 }

package/dist/result.cjs

@@ -83,7 +83,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,

package/dist/result.js

@@ -7,7 +7,7 @@ import {
   nonEmptyString,
   normalizeTerminalMetadata,
   recordValue
-} from "./chunk-2ZQNXVQC.js";
+} from "./chunk-5DC6YXN4.js";
 export {
   applyTerminalMetadata,
   compactRecord,

package/dist/runner.cjs

@@ -59,7 +59,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,
@@ -81,6 +85,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) {
@@ -124,6 +139,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)
   });
 }
@@ -131,7 +151,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,
@@ -159,9 +184,30 @@ 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 setRunStatus(state, status, at = timestamp()) {
   state.status = status;
   state.ok = status !== "blocked" && status !== "failed";
@@ -246,7 +292,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));
@@ -256,12 +303,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",
@@ -284,7 +389,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",
@@ -293,6 +400,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)
         }
       });
@@ -345,6 +455,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",
@@ -391,6 +506,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",
@@ -440,6 +562,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;
@@ -529,6 +658,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 });

package/dist/runner.d.cts

@@ -1,6 +1,7 @@
-import { SetupAdapter, ImplementationAdapter, ProofAdapter, JudgeAdapter, ShipAdapter, NotificationAdapter, RiddleProofRunParams, RiddleProofRunState, RiddleProofRunResult } from './types.cjs';
+import { PreflightAdapter, SetupAdapter, ImplementationAdapter, ProofAdapter, JudgeAdapter, ShipAdapter, NotificationAdapter, RiddleProofRunParams, RiddleProofRunState, RiddleProofRunResult } from './types.cjs';
 
 interface RiddleProofRunnerAdapters {
+    preflight?: PreflightAdapter;
     setup?: SetupAdapter;
     implementation?: ImplementationAdapter;
     proof?: ProofAdapter;

package/dist/runner.d.ts

@@ -1,6 +1,7 @@
-import { SetupAdapter, ImplementationAdapter, ProofAdapter, JudgeAdapter, ShipAdapter, NotificationAdapter, RiddleProofRunParams, RiddleProofRunState, RiddleProofRunResult } from './types.js';
+import { PreflightAdapter, SetupAdapter, ImplementationAdapter, ProofAdapter, JudgeAdapter, ShipAdapter, NotificationAdapter, RiddleProofRunParams, RiddleProofRunState, RiddleProofRunResult } from './types.js';
 
 interface RiddleProofRunnerAdapters {
+    preflight?: PreflightAdapter;
     setup?: SetupAdapter;
     implementation?: ImplementationAdapter;
     proof?: ProofAdapter;

package/dist/runner.js

@@ -1,8 +1,8 @@
 import {
   runRiddleProof
-} from "./chunk-GWGXPNON.js";
-import "./chunk-EPVZKWUS.js";
-import "./chunk-2ZQNXVQC.js";
+} from "./chunk-F65YYXVO.js";
+import "./chunk-5FHUOSNO.js";
+import "./chunk-5DC6YXN4.js";
 export {
   runRiddleProof
 };

package/dist/state.cjs

@@ -22,7 +22,9 @@ var state_exports = {};
 __export(state_exports, {
   RIDDLE_PROOF_RUN_STATE_VERSION: () => RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent: () => appendRunEvent,
+  appendStageHeartbeat: () => appendStageHeartbeat,
   createRunState: () => createRunState,
+  createRunStatusSnapshot: () => createRunStatusSnapshot,
   normalizeIntegrationContext: () => normalizeIntegrationContext,
   normalizeRunParams: () => normalizeRunParams,
   setRunStatus: () => setRunStatus
@@ -45,6 +47,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) {
@@ -88,6 +101,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)
   });
 }
@@ -95,7 +113,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,
@@ -123,9 +146,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";
@@ -136,7 +199,9 @@ function setRunStatus(state, status, at = timestamp()) {
 0 && (module.exports = {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent,
+  appendStageHeartbeat,
   createRunState,
+  createRunStatusSnapshot,
   normalizeIntegrationContext,
   normalizeRunParams,
   setRunStatus

package/dist/state.d.cts

@@ -1,10 +1,15 @@
-import { RiddleProofRunParams, RiddleProofStatus, RiddleProofEvent, RiddleProofRunState, IntegrationContext } from './types.cjs';
+import { RiddleProofRunParams, RiddleProofStatus, RiddleProofStage, RiddleProofEvent, RiddleProofRunState, RiddleProofRunStatusSnapshot, IntegrationContext } from './types.cjs';
 
 declare const RIDDLE_PROOF_RUN_STATE_VERSION: "riddle-proof.run-state.v1";
 interface CreateRunStateInput {
     request: RiddleProofRunParams;
+    run_id?: string;
     status?: RiddleProofStatus;
     state_path?: string;
+    worktree_path?: string;
+    branch?: string;
+    current_stage?: RiddleProofStage | null;
+    stage_started_at?: string | null;
     created_at?: string;
     updated_at?: string;
     iterations?: number;
@@ -18,6 +23,16 @@ declare function normalizeIntegrationContext(input?: Partial<IntegrationContext>
 declare function normalizeRunParams(input: RiddleProofRunParams): RiddleProofRunParams;
 declare function createRunState(input: CreateRunStateInput): RiddleProofRunState;
 declare function appendRunEvent<T extends RiddleProofRunState>(state: T, input: RunEventInput): T;
+declare function appendStageHeartbeat<T extends RiddleProofRunState>(state: T, input: {
+    stage: RiddleProofStage;
+    summary?: string;
+    checkpoint?: string;
+    wait_reason?: string;
+    blocker?: string;
+    details?: Record<string, unknown>;
+    ts?: string;
+}): T;
+declare function createRunStatusSnapshot(state: RiddleProofRunState, at?: string): RiddleProofRunStatusSnapshot;
 declare function setRunStatus<T extends RiddleProofRunState>(state: T, status: RiddleProofStatus, at?: string): T;
 
-export { type CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, type RunEventInput, appendRunEvent, createRunState, normalizeIntegrationContext, normalizeRunParams, setRunStatus };
+export { type CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, type RunEventInput, appendRunEvent, appendStageHeartbeat, createRunState, createRunStatusSnapshot, normalizeIntegrationContext, normalizeRunParams, setRunStatus };

package/dist/state.d.ts

@@ -1,10 +1,15 @@
-import { RiddleProofRunParams, RiddleProofStatus, RiddleProofEvent, RiddleProofRunState, IntegrationContext } from './types.js';
+import { RiddleProofRunParams, RiddleProofStatus, RiddleProofStage, RiddleProofEvent, RiddleProofRunState, RiddleProofRunStatusSnapshot, IntegrationContext } from './types.js';
 
 declare const RIDDLE_PROOF_RUN_STATE_VERSION: "riddle-proof.run-state.v1";
 interface CreateRunStateInput {
     request: RiddleProofRunParams;
+    run_id?: string;
     status?: RiddleProofStatus;
     state_path?: string;
+    worktree_path?: string;
+    branch?: string;
+    current_stage?: RiddleProofStage | null;
+    stage_started_at?: string | null;
     created_at?: string;
     updated_at?: string;
     iterations?: number;
@@ -18,6 +23,16 @@ declare function normalizeIntegrationContext(input?: Partial<IntegrationContext>
 declare function normalizeRunParams(input: RiddleProofRunParams): RiddleProofRunParams;
 declare function createRunState(input: CreateRunStateInput): RiddleProofRunState;
 declare function appendRunEvent<T extends RiddleProofRunState>(state: T, input: RunEventInput): T;
+declare function appendStageHeartbeat<T extends RiddleProofRunState>(state: T, input: {
+    stage: RiddleProofStage;
+    summary?: string;
+    checkpoint?: string;
+    wait_reason?: string;
+    blocker?: string;
+    details?: Record<string, unknown>;
+    ts?: string;
+}): T;
+declare function createRunStatusSnapshot(state: RiddleProofRunState, at?: string): RiddleProofRunStatusSnapshot;
 declare function setRunStatus<T extends RiddleProofRunState>(state: T, status: RiddleProofStatus, at?: string): T;
 
-export { type CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, type RunEventInput, appendRunEvent, createRunState, normalizeIntegrationContext, normalizeRunParams, setRunStatus };
+export { type CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, type RunEventInput, appendRunEvent, appendStageHeartbeat, createRunState, createRunStatusSnapshot, normalizeIntegrationContext, normalizeRunParams, setRunStatus };

package/dist/state.js

@@ -1,16 +1,20 @@
 import {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent,
+  appendStageHeartbeat,
   createRunState,
+  createRunStatusSnapshot,
   normalizeIntegrationContext,
   normalizeRunParams,
   setRunStatus
-} from "./chunk-EPVZKWUS.js";
-import "./chunk-2ZQNXVQC.js";
+} from "./chunk-5FHUOSNO.js";
+import "./chunk-5DC6YXN4.js";
 export {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent,
+  appendStageHeartbeat,
   createRunState,
+  createRunStatusSnapshot,
   normalizeIntegrationContext,
   normalizeRunParams,
   setRunStatus