@riddledc/riddle-proof 0.5.52 → 0.5.54

package/dist/cli.cjs

@@ -363,6 +363,7 @@ function visualDeltaRequiredForState(state = {}) {
   const bundle = objectValue(state?.evidence_bundle);
   const contract = objectValue(bundle.artifact_contract);
   const required = objectValue(contract.required);
+  if (required.visual_delta === false) return false;
   return required.visual_delta === true || VISUAL_FIRST_MODES.has(normalizedVerificationMode(state));
 }
 function visualDeltaForState(state = {}) {
@@ -1407,9 +1408,9 @@ function cleanupMergedProofRun(state, repoDir, params, prState) {
   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) {
+    const fetch2 = commandResult("git", ["fetch", "origin", baseBranch], repoDir, 12e4);
+    cleanup.fetch = fetch2.ok ? { ok: true, base_branch: baseBranch } : { ok: false, base_branch: baseBranch, error: fetch2.stderr.slice(0, 300) };
+    if (fetch2.ok) {
       fetchedBase = true;
       state.base_synced_at = (/* @__PURE__ */ new Date()).toISOString();
       state.base_branch = baseBranch;
@@ -2770,7 +2771,7 @@ var init_proof_run_engine = __esm({
 });
 
 // src/cli.ts
-var import_node_fs5 = require("fs");
+var import_node_fs6 = require("fs");
 
 // src/engine-harness.ts
 var import_node_child_process2 = require("child_process");
@@ -3434,8 +3435,8 @@ function buildProofAssessmentCheckpointPacket(input) {
   const artifactContract = recordValue(proofAssessmentRequest.artifact_contract) || recordValue(bundle?.artifact_contract);
   const requiredSignals = recordValue(recordValue(artifactContract)?.required);
   const visualDelta = visualDeltaFromState(fullState);
-  const verificationMode = nonEmptyString(input.request.verification_mode) || nonEmptyString(fullState.verification_mode) || nonEmptyString(bundle?.verification_mode) || "proof";
-  const visualDeltaRequired = requiredSignals?.visual_delta === true || verificationModeRequiresVisualDelta(verificationMode);
+  const verificationMode = nonEmptyString(bundle?.verification_mode) || nonEmptyString(fullState.verification_mode) || nonEmptyString(input.request.verification_mode) || "proof";
+  const visualDeltaRequired = requiredSignals?.visual_delta !== false && (requiredSignals?.visual_delta === true || verificationModeRequiresVisualDelta(verificationMode));
   const evidenceIssueCode2 = visualDeltaIssueCode(visualDelta, visualDeltaRequired);
   const summary = nonEmptyString(input.engineResult.summary) || nonEmptyString(fullState.verify_summary) || "Verify captured evidence and needs a supervising proof assessment.";
   const recoveryHint = evidenceIssueCode2 ? "Required visual_delta evidence is incomplete. Keep this same run in verify/evidence recovery with decision=revise_capture and continue_with_stage=verify unless the evidence proves an implementation or recon problem." : "Assess whether the current artifacts prove the requested change, then choose the next stage.";
@@ -3982,6 +3983,7 @@ function normalizeRunParams(input) {
     leave_draft: input.leave_draft,
     engine_state_path: input.engine_state_path,
     harness_state_path: input.harness_state_path,
+    riddle_engine_module_url: input.riddle_engine_module_url,
     max_iterations: input.max_iterations,
     auto_approve: input.auto_approve,
     dry_run: input.dry_run,
@@ -6396,15 +6398,168 @@ async function runCodexExecAgentDoctor(config = {}, runner = createCodexExecJson
   };
 }
 
+// src/riddle-client.ts
+var import_node_child_process4 = require("child_process");
+var import_node_fs5 = require("fs");
+var import_node_os2 = require("os");
+var import_node_path5 = __toESM(require("path"), 1);
+var DEFAULT_RIDDLE_API_BASE_URL = "https://api.riddledc.com";
+var DEFAULT_RIDDLE_API_KEY_FILE = "/tmp/riddle-api-key";
+var RiddleApiError = class extends Error {
+  constructor(pathname, status, body) {
+    super(`Riddle API ${pathname} failed HTTP ${status}: ${body}`);
+    this.name = "RiddleApiError";
+    this.status = status;
+    this.body = body;
+    this.path = pathname;
+  }
+};
+function normalizeBaseUrl(value) {
+  return (value || DEFAULT_RIDDLE_API_BASE_URL).replace(/\/$/, "");
+}
+function fetchFor(config = {}) {
+  return config.fetchImpl || fetch;
+}
+function resolveRiddleApiKey(config = {}) {
+  if (config.apiKey?.trim()) return config.apiKey.trim();
+  if (process.env.RIDDLE_API_KEY?.trim()) return process.env.RIDDLE_API_KEY.trim();
+  const keyFile = config.apiKeyFile || process.env.RIDDLE_API_KEY_FILE || DEFAULT_RIDDLE_API_KEY_FILE;
+  if ((0, import_node_fs5.existsSync)(keyFile)) {
+    const key = (0, import_node_fs5.readFileSync)(keyFile, "utf8").trim();
+    if (key) return key;
+  }
+  throw new Error(`Riddle API key missing. Set RIDDLE_API_KEY or write ${DEFAULT_RIDDLE_API_KEY_FILE}.`);
+}
+async function riddleRequestJson(config, pathname, init = {}) {
+  const response = await fetchFor(config)(`${normalizeBaseUrl(config.apiBaseUrl)}${pathname}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${resolveRiddleApiKey(config)}`,
+      "Content-Type": "application/json",
+      ...init.headers || {}
+    }
+  });
+  const text = await response.text();
+  let json = null;
+  try {
+    json = JSON.parse(text);
+  } catch {
+  }
+  if (!response.ok) throw new RiddleApiError(pathname, response.status, text);
+  return json ?? text;
+}
+async function deployRiddleStaticPreview(config, directory, label) {
+  if (!directory?.trim()) throw new Error("directory is required");
+  if (!label?.trim()) throw new Error("label is required");
+  const created = await riddleRequestJson(config, "/v1/preview", {
+    method: "POST",
+    body: JSON.stringify({ framework: "spa", label })
+  });
+  const id = String(created.id || "");
+  const uploadUrl = String(created.upload_url || "");
+  if (!id || !uploadUrl) throw new Error("Riddle preview create response was missing id or upload_url.");
+  const scratch = (0, import_node_fs5.mkdtempSync)(import_node_path5.default.join((0, import_node_os2.tmpdir)(), "riddle-preview-upload-"));
+  const tarball = import_node_path5.default.join(scratch, `${id}.tar.gz`);
+  try {
+    (0, import_node_child_process4.execFileSync)("tar", ["czf", tarball, "-C", directory, "."], { stdio: "pipe" });
+    const upload = await fetchFor(config)(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": "application/gzip" },
+      body: (0, import_node_fs5.readFileSync)(tarball)
+    });
+    if (!upload.ok) {
+      throw new RiddleApiError(uploadUrl, upload.status, await upload.text());
+    }
+  } finally {
+    (0, import_node_fs5.rmSync)(scratch, { recursive: true, force: true });
+  }
+  const published = await riddleRequestJson(config, `/v1/preview/${id}/publish`, {
+    method: "POST"
+  });
+  return {
+    ok: true,
+    id: String(published.id || id),
+    label,
+    preview_url: String(published.preview_url || ""),
+    file_count: typeof published.file_count === "number" ? published.file_count : void 0,
+    total_bytes: typeof published.total_bytes === "number" ? published.total_bytes : void 0,
+    expires_at: typeof created.expires_at === "string" ? created.expires_at : void 0,
+    raw: published
+  };
+}
+function parseRiddleViewport(value) {
+  if (!value) return void 0;
+  const match = /^(\d+)x(\d+)$/.exec(value.trim());
+  if (!match) throw new Error("viewport must look like 1280x720");
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+async function runRiddleScript(config, input) {
+  if (!input.url?.trim()) throw new Error("url is required");
+  if (!input.script?.trim()) throw new Error("script is required");
+  const payload = {
+    url: input.url,
+    script: input.script,
+    sync: input.sync ?? false,
+    timeout_sec: input.timeoutSec || 120
+  };
+  if (input.viewport) payload.viewport = input.viewport;
+  if (input.include) payload.include = input.include;
+  if (input.options) payload.options = input.options;
+  return riddleRequestJson(config, "/v1/run", {
+    method: "POST",
+    body: JSON.stringify(payload)
+  });
+}
+function isTerminalRiddleJobStatus(status) {
+  return ["completed", "complete", "completed_error", "completed_timeout", "failed"].includes(String(status || ""));
+}
+async function pollRiddleJob(config, jobId, options = {}) {
+  if (!jobId?.trim()) throw new Error("jobId is required");
+  const attempts = options.attempts || (options.wait ? 60 : 1);
+  const intervalMs = options.intervalMs || 2e3;
+  let job = null;
+  for (let index = 0; index < attempts; index += 1) {
+    job = await riddleRequestJson(config, `/v1/jobs/${jobId}`);
+    if (isTerminalRiddleJobStatus(job.status)) break;
+    if (index + 1 < attempts) {
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  }
+  const status = job?.status ? String(job.status) : null;
+  if (!isTerminalRiddleJobStatus(status)) {
+    return { ok: true, job_id: jobId, status, terminal: false, job };
+  }
+  const artifacts = await riddleRequestJson(config, `/v1/jobs/${jobId}/artifacts`);
+  return {
+    ok: status === "completed" || status === "complete",
+    job_id: jobId,
+    status,
+    terminal: true,
+    job,
+    artifacts
+  };
+}
+function createRiddleApiClient(config = {}) {
+  return {
+    requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
+    deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
+    runScript: (input) => runRiddleScript(config, input),
+    pollJob: (jobId, options) => pollRiddleJob(config, jobId, options)
+  };
+}
+
 // src/cli.ts
 function usage() {
   return [
     "Usage:",
     "  riddle-proof-loop run --request-json <file|json|-> [--agent disabled|local] [--checkpoint-mode yield|auto]",
-    "  riddle-proof-loop checkpoint --state-path <path> [--decision <decision>]",
+    "  riddle-proof-loop checkpoint --state-path <path> [--decision <decision>] [--format json|markdown]",
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
+    "  riddle-proof-loop riddle-preview-deploy <build-dir> <label>",
+    "  riddle-proof-loop riddle-run-script --url <url> --script-file <file> [--viewport 1280x720]",
+    "  riddle-proof-loop riddle-poll <job-id> [--wait]",
     "  riddle-proof-loop doctor local [--codex-command <path>]",
     "",
     "The default CLI run mode is checkpoint-mode=yield unless --agent local is used.",
@@ -6436,11 +6591,11 @@ function optionString(options, key) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
 function readStdin() {
-  return (0, import_node_fs5.readFileSync)(0, "utf-8");
+  return (0, import_node_fs6.readFileSync)(0, "utf-8");
 }
 function readJsonValue(value, label) {
   if (!value) throw new Error(`${label} is required.`);
-  const raw = value === "-" ? readStdin() : (0, import_node_fs5.existsSync)(value) ? (0, import_node_fs5.readFileSync)(value, "utf-8") : value;
+  const raw = value === "-" ? readStdin() : (0, import_node_fs6.existsSync)(value) ? (0, import_node_fs6.readFileSync)(value, "utf-8") : value;
   const parsed = JSON.parse(raw);
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(`${label} must be a JSON object.`);
@@ -6453,7 +6608,7 @@ function readOptionalJsonRecord(value, label) {
 }
 function readOptionalJsonStringArray(value, label) {
   if (!value) return void 0;
-  const parsed = value === "-" ? JSON.parse(readStdin()) : (0, import_node_fs5.existsSync)(value) ? JSON.parse((0, import_node_fs5.readFileSync)(value, "utf-8")) : JSON.parse(value);
+  const parsed = value === "-" ? JSON.parse(readStdin()) : (0, import_node_fs6.existsSync)(value) ? JSON.parse((0, import_node_fs6.readFileSync)(value, "utf-8")) : JSON.parse(value);
   if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string")) {
     throw new Error(`${label} must be a JSON array of strings.`);
   }
@@ -6474,6 +6629,65 @@ function hasPlaceholderValue(value) {
   }
   return false;
 }
+function markdownJson(value) {
+  return JSON.stringify(value ?? null, null, 2);
+}
+function formatCheckpointMarkdown(input) {
+  const packet = input.checkpointPacket;
+  const runCard = input.runCard;
+  const lines = [
+    "# Riddle Proof Checkpoint",
+    "",
+    `Run: ${packet.run_id}`,
+    `State: ${input.statePath}`,
+    `Status: ${input.status || "awaiting_checkpoint"}`,
+    `Stage: ${packet.stage}`,
+    `Checkpoint: ${packet.checkpoint}`,
+    `Kind: ${packet.kind}`,
+    "",
+    "## Goal",
+    "",
+    runCard?.goal?.change_request || packet.change_request,
+    "",
+    "## Next Action",
+    "",
+    packet.question,
+    "",
+    "## Allowed Decisions",
+    "",
+    ...packet.allowed_decisions.map((decision) => `- ${decision}`),
+    ""
+  ];
+  if (packet.artifacts?.length) {
+    lines.push("## Artifacts", "");
+    for (const artifact of packet.artifacts) {
+      lines.push(`- ${artifact.role}: ${artifact.url || artifact.path || artifact.name || "available"}`);
+    }
+    lines.push("");
+  }
+  if (packet.evidence_excerpt && Object.keys(packet.evidence_excerpt).length) {
+    lines.push("## Evidence Excerpt", "", "```json", markdownJson(packet.evidence_excerpt), "```", "");
+  }
+  if (packet.state_excerpt && Object.keys(packet.state_excerpt).length) {
+    lines.push("## State Excerpt", "", "```json", markdownJson(packet.state_excerpt), "```", "");
+  }
+  lines.push(
+    "## Response Template",
+    "",
+    "```json",
+    markdownJson(input.responseTemplate),
+    "```",
+    "",
+    "## Next Command",
+    "",
+    "```sh",
+    `riddle-proof-loop respond --state-path ${input.statePath} --decision ${input.responseTemplate.decision} --summary <summary> --payload-json <file|json|->`,
+    "```",
+    ""
+  );
+  return `${lines.join("\n")}
+`;
+}
 function checkpointResponseForFlags(statePath, options) {
   const state = readRunState(statePath);
   if (!state.checkpoint_packet) {
@@ -6526,14 +6740,28 @@ function agentFor(options) {
   if (agentMode === "disabled") return createDisabledRiddleProofAgentAdapter();
   throw new Error(`Unsupported --agent ${agentMode}. Use disabled or local.`);
 }
+function riddleClientConfig(options) {
+  return {
+    apiKey: optionString(options, "apiKey"),
+    apiKeyFile: optionString(options, "apiKeyFile"),
+    apiBaseUrl: optionString(options, "apiBaseUrl")
+  };
+}
 function requestForRun(options) {
   const statePath = optionString(options, "statePath");
+  const withEngineModuleUrl = (request) => {
+    const moduleUrl = optionString(options, "riddleEngineModuleUrl");
+    return moduleUrl && !request.riddle_engine_module_url ? { ...request, riddle_engine_module_url: moduleUrl } : request;
+  };
   if (optionString(options, "requestJson")) {
-    return readJsonValue(optionString(options, "requestJson"), "--request-json");
+    return withEngineModuleUrl(readJsonValue(optionString(options, "requestJson"), "--request-json"));
   }
-  if (statePath) return readRunState(statePath).request;
+  if (statePath) return withEngineModuleUrl(readRunState(statePath).request);
   throw new Error("--request-json is required unless --state-path points to an existing run state.");
 }
+function riddleEngineModuleUrlFor(options, request) {
+  return optionString(options, "riddleEngineModuleUrl") || (typeof request.riddle_engine_module_url === "string" && request.riddle_engine_module_url.trim() ? request.riddle_engine_module_url.trim() : void 0);
+}
 function checkpointModeFor(options) {
   const explicit = optionString(options, "checkpointMode");
   if (explicit) return explicit;
@@ -6565,6 +6793,42 @@ async function main() {
 `);
     return;
   }
+  if (command === "riddle-preview-deploy") {
+    const buildDir = positional[1];
+    const label = positional[2];
+    const result = await createRiddleApiClient(riddleClientConfig(options)).deployStaticPreview(buildDir, label);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  if (command === "riddle-run-script") {
+    const url = optionString(options, "url");
+    const scriptFile = optionString(options, "scriptFile");
+    if (!url || !scriptFile) throw new Error("riddle-run-script requires --url and --script-file.");
+    const result = await createRiddleApiClient(riddleClientConfig(options)).runScript({
+      url,
+      script: (0, import_node_fs6.readFileSync)(scriptFile, "utf-8"),
+      viewport: parseRiddleViewport(optionString(options, "viewport")),
+      timeoutSec: optionString(options, "timeout") ? Number(optionString(options, "timeout")) : void 0,
+      sync: options.sync === true ? true : void 0
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  if (command === "riddle-poll") {
+    const jobId = positional[1];
+    if (!jobId) throw new Error("riddle-poll requires <job-id>.");
+    const result = await createRiddleApiClient(riddleClientConfig(options)).pollJob(jobId, {
+      wait: options.wait === true,
+      attempts: optionString(options, "attempts") ? Number(optionString(options, "attempts")) : void 0,
+      intervalMs: optionString(options, "intervalMs") ? Number(optionString(options, "intervalMs")) : void 0
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    process.exitCode = result.ok ? 0 : 1;
+    return;
+  }
   if (command === "checkpoint") {
     const statePath = optionString(options, "statePath");
     if (!statePath) throw new Error("--state-path is required.");
@@ -6577,6 +6841,18 @@ async function main() {
       decision: optionString(options, "decision"),
       source_kind: optionString(options, "sourceKind") || "codex"
     });
+    const format = optionString(options, "format") || "json";
+    if (format === "markdown" || format === "md") {
+      process.stdout.write(formatCheckpointMarkdown({
+        statePath,
+        status: snapshot?.status || state.status,
+        checkpointPacket: state.checkpoint_packet,
+        runCard: snapshot?.run_card || state.run_card || null,
+        responseTemplate
+      }));
+      return;
+    }
+    if (format !== "json") throw new Error("--format must be json or markdown.");
     process.stdout.write(`${JSON.stringify({
       checkpoint_packet: state.checkpoint_packet,
       run_card: snapshot?.run_card || state.run_card || null,
@@ -6603,7 +6879,7 @@ async function main() {
       agent: agentFor(options),
       config: {
         stateDir: optionString(options, "stateDir"),
-        riddleEngineModuleUrl: optionString(options, "riddleEngineModuleUrl"),
+        riddleEngineModuleUrl: riddleEngineModuleUrlFor(options, request),
         riddleProofDir: optionString(options, "riddleProofDir"),
         defaultReviewer: optionString(options, "defaultReviewer"),
         defaultShipMode: optionString(options, "defaultShipMode")

package/dist/cli.js

@@ -1,20 +1,24 @@
 #!/usr/bin/env node
+import {
+  createRiddleApiClient,
+  parseRiddleViewport
+} from "./chunk-UR6ADV4Y.js";
 import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-KYGWIA7A.js";
-import "./chunk-4ASMX4R6.js";
+} from "./chunk-A2AWRZ5B.js";
+import "./chunk-RFJ5BQF6.js";
 import "./chunk-JFQXAJH2.js";
 import {
   createCodexExecAgentAdapter,
   runCodexExecAgentDoctor
 } from "./chunk-3266V3MO.js";
-import "./chunk-PVUZZ2P6.js";
-import "./chunk-53UPEUVU.js";
+import "./chunk-MO24D3PY.js";
+import "./chunk-3UHWI3FO.js";
 import {
   createCheckpointResponseTemplate
-} from "./chunk-T5RHGGQ2.js";
+} from "./chunk-33XO42CY.js";
 import "./chunk-DUFDZJOF.js";
 
 // src/cli.ts
@@ -23,10 +27,13 @@ function usage() {
   return [
     "Usage:",
     "  riddle-proof-loop run --request-json <file|json|-> [--agent disabled|local] [--checkpoint-mode yield|auto]",
-    "  riddle-proof-loop checkpoint --state-path <path> [--decision <decision>]",
+    "  riddle-proof-loop checkpoint --state-path <path> [--decision <decision>] [--format json|markdown]",
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
+    "  riddle-proof-loop riddle-preview-deploy <build-dir> <label>",
+    "  riddle-proof-loop riddle-run-script --url <url> --script-file <file> [--viewport 1280x720]",
+    "  riddle-proof-loop riddle-poll <job-id> [--wait]",
     "  riddle-proof-loop doctor local [--codex-command <path>]",
     "",
     "The default CLI run mode is checkpoint-mode=yield unless --agent local is used.",
@@ -96,6 +103,65 @@ function hasPlaceholderValue(value) {
   }
   return false;
 }
+function markdownJson(value) {
+  return JSON.stringify(value ?? null, null, 2);
+}
+function formatCheckpointMarkdown(input) {
+  const packet = input.checkpointPacket;
+  const runCard = input.runCard;
+  const lines = [
+    "# Riddle Proof Checkpoint",
+    "",
+    `Run: ${packet.run_id}`,
+    `State: ${input.statePath}`,
+    `Status: ${input.status || "awaiting_checkpoint"}`,
+    `Stage: ${packet.stage}`,
+    `Checkpoint: ${packet.checkpoint}`,
+    `Kind: ${packet.kind}`,
+    "",
+    "## Goal",
+    "",
+    runCard?.goal?.change_request || packet.change_request,
+    "",
+    "## Next Action",
+    "",
+    packet.question,
+    "",
+    "## Allowed Decisions",
+    "",
+    ...packet.allowed_decisions.map((decision) => `- ${decision}`),
+    ""
+  ];
+  if (packet.artifacts?.length) {
+    lines.push("## Artifacts", "");
+    for (const artifact of packet.artifacts) {
+      lines.push(`- ${artifact.role}: ${artifact.url || artifact.path || artifact.name || "available"}`);
+    }
+    lines.push("");
+  }
+  if (packet.evidence_excerpt && Object.keys(packet.evidence_excerpt).length) {
+    lines.push("## Evidence Excerpt", "", "```json", markdownJson(packet.evidence_excerpt), "```", "");
+  }
+  if (packet.state_excerpt && Object.keys(packet.state_excerpt).length) {
+    lines.push("## State Excerpt", "", "```json", markdownJson(packet.state_excerpt), "```", "");
+  }
+  lines.push(
+    "## Response Template",
+    "",
+    "```json",
+    markdownJson(input.responseTemplate),
+    "```",
+    "",
+    "## Next Command",
+    "",
+    "```sh",
+    `riddle-proof-loop respond --state-path ${input.statePath} --decision ${input.responseTemplate.decision} --summary <summary> --payload-json <file|json|->`,
+    "```",
+    ""
+  );
+  return `${lines.join("\n")}
+`;
+}
 function checkpointResponseForFlags(statePath, options) {
   const state = readRunState(statePath);
   if (!state.checkpoint_packet) {
@@ -148,14 +214,28 @@ function agentFor(options) {
   if (agentMode === "disabled") return createDisabledRiddleProofAgentAdapter();
   throw new Error(`Unsupported --agent ${agentMode}. Use disabled or local.`);
 }
+function riddleClientConfig(options) {
+  return {
+    apiKey: optionString(options, "apiKey"),
+    apiKeyFile: optionString(options, "apiKeyFile"),
+    apiBaseUrl: optionString(options, "apiBaseUrl")
+  };
+}
 function requestForRun(options) {
   const statePath = optionString(options, "statePath");
+  const withEngineModuleUrl = (request) => {
+    const moduleUrl = optionString(options, "riddleEngineModuleUrl");
+    return moduleUrl && !request.riddle_engine_module_url ? { ...request, riddle_engine_module_url: moduleUrl } : request;
+  };
   if (optionString(options, "requestJson")) {
-    return readJsonValue(optionString(options, "requestJson"), "--request-json");
+    return withEngineModuleUrl(readJsonValue(optionString(options, "requestJson"), "--request-json"));
   }
-  if (statePath) return readRunState(statePath).request;
+  if (statePath) return withEngineModuleUrl(readRunState(statePath).request);
   throw new Error("--request-json is required unless --state-path points to an existing run state.");
 }
+function riddleEngineModuleUrlFor(options, request) {
+  return optionString(options, "riddleEngineModuleUrl") || (typeof request.riddle_engine_module_url === "string" && request.riddle_engine_module_url.trim() ? request.riddle_engine_module_url.trim() : void 0);
+}
 function checkpointModeFor(options) {
   const explicit = optionString(options, "checkpointMode");
   if (explicit) return explicit;
@@ -187,6 +267,42 @@ async function main() {
 `);
     return;
   }
+  if (command === "riddle-preview-deploy") {
+    const buildDir = positional[1];
+    const label = positional[2];
+    const result = await createRiddleApiClient(riddleClientConfig(options)).deployStaticPreview(buildDir, label);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  if (command === "riddle-run-script") {
+    const url = optionString(options, "url");
+    const scriptFile = optionString(options, "scriptFile");
+    if (!url || !scriptFile) throw new Error("riddle-run-script requires --url and --script-file.");
+    const result = await createRiddleApiClient(riddleClientConfig(options)).runScript({
+      url,
+      script: readFileSync(scriptFile, "utf-8"),
+      viewport: parseRiddleViewport(optionString(options, "viewport")),
+      timeoutSec: optionString(options, "timeout") ? Number(optionString(options, "timeout")) : void 0,
+      sync: options.sync === true ? true : void 0
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  if (command === "riddle-poll") {
+    const jobId = positional[1];
+    if (!jobId) throw new Error("riddle-poll requires <job-id>.");
+    const result = await createRiddleApiClient(riddleClientConfig(options)).pollJob(jobId, {
+      wait: options.wait === true,
+      attempts: optionString(options, "attempts") ? Number(optionString(options, "attempts")) : void 0,
+      intervalMs: optionString(options, "intervalMs") ? Number(optionString(options, "intervalMs")) : void 0
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    process.exitCode = result.ok ? 0 : 1;
+    return;
+  }
   if (command === "checkpoint") {
     const statePath = optionString(options, "statePath");
     if (!statePath) throw new Error("--state-path is required.");
@@ -199,6 +315,18 @@ async function main() {
       decision: optionString(options, "decision"),
       source_kind: optionString(options, "sourceKind") || "codex"
     });
+    const format = optionString(options, "format") || "json";
+    if (format === "markdown" || format === "md") {
+      process.stdout.write(formatCheckpointMarkdown({
+        statePath,
+        status: snapshot?.status || state.status,
+        checkpointPacket: state.checkpoint_packet,
+        runCard: snapshot?.run_card || state.run_card || null,
+        responseTemplate
+      }));
+      return;
+    }
+    if (format !== "json") throw new Error("--format must be json or markdown.");
     process.stdout.write(`${JSON.stringify({
       checkpoint_packet: state.checkpoint_packet,
       run_card: snapshot?.run_card || state.run_card || null,
@@ -225,7 +353,7 @@ async function main() {
       agent: agentFor(options),
       config: {
         stateDir: optionString(options, "stateDir"),
-        riddleEngineModuleUrl: optionString(options, "riddleEngineModuleUrl"),
+        riddleEngineModuleUrl: riddleEngineModuleUrlFor(options, request),
         riddleProofDir: optionString(options, "riddleProofDir"),
         defaultReviewer: optionString(options, "defaultReviewer"),
         defaultShipMode: optionString(options, "defaultShipMode")

package/dist/engine-harness.cjs

@@ -363,6 +363,7 @@ function visualDeltaRequiredForState(state = {}) {
   const bundle = objectValue(state?.evidence_bundle);
   const contract = objectValue(bundle.artifact_contract);
   const required = objectValue(contract.required);
+  if (required.visual_delta === false) return false;
   return required.visual_delta === true || VISUAL_FIRST_MODES.has(normalizedVerificationMode(state));
 }
 function visualDeltaForState(state = {}) {
@@ -3438,8 +3439,8 @@ function buildProofAssessmentCheckpointPacket(input) {
   const artifactContract = recordValue(proofAssessmentRequest.artifact_contract) || recordValue(bundle?.artifact_contract);
   const requiredSignals = recordValue(recordValue(artifactContract)?.required);
   const visualDelta = visualDeltaFromState(fullState);
-  const verificationMode = nonEmptyString(input.request.verification_mode) || nonEmptyString(fullState.verification_mode) || nonEmptyString(bundle?.verification_mode) || "proof";
-  const visualDeltaRequired = requiredSignals?.visual_delta === true || verificationModeRequiresVisualDelta(verificationMode);
+  const verificationMode = nonEmptyString(bundle?.verification_mode) || nonEmptyString(fullState.verification_mode) || nonEmptyString(input.request.verification_mode) || "proof";
+  const visualDeltaRequired = requiredSignals?.visual_delta !== false && (requiredSignals?.visual_delta === true || verificationModeRequiresVisualDelta(verificationMode));
   const evidenceIssueCode2 = visualDeltaIssueCode(visualDelta, visualDeltaRequired);
   const summary = nonEmptyString(input.engineResult.summary) || nonEmptyString(fullState.verify_summary) || "Verify captured evidence and needs a supervising proof assessment.";
   const recoveryHint = evidenceIssueCode2 ? "Required visual_delta evidence is incomplete. Keep this same run in verify/evidence recovery with decision=revise_capture and continue_with_stage=verify unless the evidence proves an implementation or recon problem." : "Assess whether the current artifacts prove the requested change, then choose the next stage.";
@@ -3912,6 +3913,7 @@ function normalizeRunParams(input) {
     leave_draft: input.leave_draft,
     engine_state_path: input.engine_state_path,
     harness_state_path: input.harness_state_path,
+    riddle_engine_module_url: input.riddle_engine_module_url,
     max_iterations: input.max_iterations,
     auto_approve: input.auto_approve,
     dry_run: input.dry_run,

package/dist/engine-harness.js

@@ -2,11 +2,11 @@ import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-KYGWIA7A.js";
-import "./chunk-4ASMX4R6.js";
-import "./chunk-PVUZZ2P6.js";
-import "./chunk-53UPEUVU.js";
-import "./chunk-T5RHGGQ2.js";
+} from "./chunk-A2AWRZ5B.js";
+import "./chunk-RFJ5BQF6.js";
+import "./chunk-MO24D3PY.js";
+import "./chunk-3UHWI3FO.js";
+import "./chunk-33XO42CY.js";
 import "./chunk-DUFDZJOF.js";
 export {
   createDisabledRiddleProofAgentAdapter,