@riddledc/riddle-proof 0.7.23 → 0.7.25

package/README.md

@@ -339,6 +339,16 @@ that performs the interaction. If proof is weak, keep the diagnostics history in
 the run state so the next agent can see the last route, tool status, artifact
 shape, and errors without rerunning blind.
 
+### Riddle Job Polling
+
+`riddle-proof-loop riddle-poll <job-id> --wait` keeps stdout as JSON and writes
+human progress lines to stderr while waiting. The JSON result includes
+`poll.timed_out`, `poll.elapsed_ms`, `poll.queue_elapsed_ms`, and
+`poll.running_without_submission` so delayed dispatch is distinguishable from a
+terminal proof failure. If `--wait` exhausts its attempts before a terminal job
+status, the command exits non-zero and the result explains the last observed
+status and `submitted_at` state.
+
 ## OpenClaw Adapter Boundary
 
 `@riddledc/riddle-proof/openclaw` translates OpenClaw Riddle Proof tool params

package/dist/{chunk-5KOHSE4V.js → chunk-7PSWK57T.js}

@@ -196,21 +196,109 @@ async function runRiddleScript(config, input) {
 function isTerminalRiddleJobStatus(status) {
   return ["completed", "complete", "completed_error", "completed_timeout", "failed"].includes(String(status || ""));
 }
+function stringField(record, key) {
+  const value = record?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function parseTimestampMs(value) {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function buildPollSnapshot(jobId, job, input) {
+  const status = job?.status ? String(job.status) : null;
+  const terminal = isTerminalRiddleJobStatus(status);
+  const createdAt = stringField(job, "created_at");
+  const submittedAt = stringField(job, "submitted_at");
+  const completedAt = stringField(job, "completed_at");
+  const createdMs = parseTimestampMs(createdAt);
+  const submittedMs = parseTimestampMs(submittedAt);
+  let queueElapsedMs = null;
+  if (createdMs !== null && submittedMs !== null) {
+    queueElapsedMs = Math.max(0, submittedMs - createdMs);
+  } else if (createdMs !== null && !submittedAt && !terminal) {
+    queueElapsedMs = Math.max(0, input.observedAt - createdMs);
+  }
+  return {
+    job_id: jobId,
+    status,
+    terminal,
+    attempt: input.attempt,
+    attempts: input.attempts,
+    elapsed_ms: Math.max(0, input.observedAt - input.startedAt),
+    created_at: createdAt,
+    submitted_at: submittedAt,
+    completed_at: completedAt,
+    queue_elapsed_ms: queueElapsedMs,
+    running_without_submission: Boolean(status && !terminal && !submittedAt)
+  };
+}
+function pollMessage(snapshot, timedOut) {
+  if (!timedOut) return void 0;
+  const submitted = snapshot.submitted_at || "not submitted";
+  const queue = snapshot.queue_elapsed_ms !== null ? ` queue_elapsed_ms=${snapshot.queue_elapsed_ms}` : "";
+  return `Riddle job ${snapshot.job_id} did not reach a terminal status after ${snapshot.attempt} poll attempts; status=${snapshot.status || "unknown"} submitted_at=${submitted}.${queue}`;
+}
 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;
+  const attempts = Math.max(1, Math.floor(options.attempts ?? (options.wait ? 300 : 1)));
+  const intervalMs = Math.max(0, Math.floor(options.intervalMs ?? 2e3));
+  const progressEveryMs = Math.max(0, Math.floor(options.progressEveryMs ?? 1e4));
+  const startedAt = Date.now();
   let job = null;
+  let lastSnapshot = null;
+  let lastProgressAt = 0;
+  let lastProgressKey = "";
   for (let index = 0; index < attempts; index += 1) {
     job = await riddleRequestJson(config, `/v1/jobs/${jobId}`);
-    if (isTerminalRiddleJobStatus(job.status)) break;
+    const observedAt = Date.now();
+    lastSnapshot = buildPollSnapshot(jobId, job, {
+      attempt: index + 1,
+      attempts,
+      startedAt,
+      observedAt
+    });
+    const progressKey = [
+      lastSnapshot.status || "unknown",
+      lastSnapshot.terminal ? "terminal" : "nonterminal",
+      lastSnapshot.submitted_at ? "submitted" : "unsubmitted"
+    ].join(":");
+    if (options.onProgress) {
+      const shouldReport = index === 0 || lastSnapshot.terminal || progressKey !== lastProgressKey || observedAt - lastProgressAt >= progressEveryMs;
+      if (shouldReport) {
+        lastProgressAt = observedAt;
+        lastProgressKey = progressKey;
+        await options.onProgress(lastSnapshot);
+      }
+    }
+    if (lastSnapshot.terminal) break;
     if (index + 1 < attempts) {
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
   }
   const status = job?.status ? String(job.status) : null;
+  const fallbackObservedAt = Date.now();
+  const snapshot = lastSnapshot || buildPollSnapshot(jobId, job, {
+    attempt: 0,
+    attempts,
+    startedAt,
+    observedAt: fallbackObservedAt
+  });
   if (!isTerminalRiddleJobStatus(status)) {
-    return { ok: true, job_id: jobId, status, terminal: false, job };
+    const timedOut = Boolean(options.wait);
+    return {
+      ok: !timedOut,
+      job_id: jobId,
+      status,
+      terminal: false,
+      job,
+      poll: {
+        ...snapshot,
+        timed_out: timedOut,
+        interval_ms: intervalMs,
+        message: pollMessage(snapshot, timedOut)
+      }
+    };
   }
   const artifacts = await riddleRequestJson(config, `/v1/jobs/${jobId}/artifacts`);
   return {
@@ -219,7 +307,12 @@ async function pollRiddleJob(config, jobId, options = {}) {
     status,
     terminal: true,
     job,
-    artifacts
+    artifacts,
+    poll: {
+      ...snapshot,
+      timed_out: false,
+      interval_ms: intervalMs
+    }
   };
 }
 function createRiddleApiClient(config = {}) {

package/dist/{chunk-XOM2OYAB.js → chunk-SDSBS64X.js}

@@ -1121,6 +1121,20 @@ async function captureViewport(viewport) {
     const scrollWidth = documentElement ? documentElement.scrollWidth : 0;
     const viewportWidth = clientWidth || window.innerWidth;
     const overflowOffenders = [];
+    function isContainedByHorizontalScroller(element) {
+      let current = element.parentElement;
+      while (current && current !== body && current !== documentElement) {
+        const style = window.getComputedStyle(current);
+        const overflowX = style.overflowX || style.overflow || "";
+        if ((overflowX === "auto" || overflowX === "scroll") && current.scrollWidth > current.clientWidth + 1) {
+          const currentRect = current.getBoundingClientRect();
+          const contained = currentRect.left >= -0.5 && currentRect.right <= viewportWidth + 0.5;
+          if (contained) return true;
+        }
+        current = current.parentElement;
+      }
+      return false;
+    }
     for (const element of Array.from(body ? body.querySelectorAll("*") : [])) {
       const rect = element.getBoundingClientRect();
       if (!rect || rect.width < 1 || rect.height < 1) continue;
@@ -1130,6 +1144,7 @@ async function captureViewport(viewport) {
       const rightOverflow = Math.max(0, rect.right - viewportWidth);
       const overflow = Math.max(leftOverflow, rightOverflow);
       if (overflow <= 0.5) continue;
+      if (isContainedByHorizontalScroller(element)) continue;
       const tag = element.tagName ? element.tagName.toLowerCase() : "element";
       const id = element.id ? "#" + element.id : "";
       const className = typeof element.className === "string"
@@ -1161,6 +1176,7 @@ async function captureViewport(viewport) {
       pathname: location.pathname,
       title: document.title,
       body_text_length: text.length,
+      body_text: text,
       body_text_sample: text.slice(0, 8000),
       scroll_width: scrollWidth,
       client_width: clientWidth,
@@ -1186,7 +1202,7 @@ async function captureViewport(viewport) {
       selectors[check.selector] = await selectorStats(check.selector);
     }
     if ((check.type === "text_visible" || check.type === "text_absent") && (check.text || check.pattern)) {
-      text_matches[textKey(check)] = textMatches(dom.body_text_sample || "", check);
+      text_matches[textKey(check)] = textMatches(dom.body_text || dom.body_text_sample || "", check);
     }
   }
   const screenshotLabel = profileSlug + "-" + viewport.name;

package/dist/cli.cjs

@@ -6743,21 +6743,109 @@ async function runRiddleScript(config, input) {
 function isTerminalRiddleJobStatus(status) {
   return ["completed", "complete", "completed_error", "completed_timeout", "failed"].includes(String(status || ""));
 }
+function stringField(record, key) {
+  const value = record?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function parseTimestampMs(value) {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function buildPollSnapshot(jobId, job, input) {
+  const status = job?.status ? String(job.status) : null;
+  const terminal = isTerminalRiddleJobStatus(status);
+  const createdAt = stringField(job, "created_at");
+  const submittedAt = stringField(job, "submitted_at");
+  const completedAt = stringField(job, "completed_at");
+  const createdMs = parseTimestampMs(createdAt);
+  const submittedMs = parseTimestampMs(submittedAt);
+  let queueElapsedMs = null;
+  if (createdMs !== null && submittedMs !== null) {
+    queueElapsedMs = Math.max(0, submittedMs - createdMs);
+  } else if (createdMs !== null && !submittedAt && !terminal) {
+    queueElapsedMs = Math.max(0, input.observedAt - createdMs);
+  }
+  return {
+    job_id: jobId,
+    status,
+    terminal,
+    attempt: input.attempt,
+    attempts: input.attempts,
+    elapsed_ms: Math.max(0, input.observedAt - input.startedAt),
+    created_at: createdAt,
+    submitted_at: submittedAt,
+    completed_at: completedAt,
+    queue_elapsed_ms: queueElapsedMs,
+    running_without_submission: Boolean(status && !terminal && !submittedAt)
+  };
+}
+function pollMessage(snapshot, timedOut) {
+  if (!timedOut) return void 0;
+  const submitted = snapshot.submitted_at || "not submitted";
+  const queue = snapshot.queue_elapsed_ms !== null ? ` queue_elapsed_ms=${snapshot.queue_elapsed_ms}` : "";
+  return `Riddle job ${snapshot.job_id} did not reach a terminal status after ${snapshot.attempt} poll attempts; status=${snapshot.status || "unknown"} submitted_at=${submitted}.${queue}`;
+}
 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;
+  const attempts = Math.max(1, Math.floor(options.attempts ?? (options.wait ? 300 : 1)));
+  const intervalMs = Math.max(0, Math.floor(options.intervalMs ?? 2e3));
+  const progressEveryMs = Math.max(0, Math.floor(options.progressEveryMs ?? 1e4));
+  const startedAt = Date.now();
   let job = null;
+  let lastSnapshot = null;
+  let lastProgressAt = 0;
+  let lastProgressKey = "";
   for (let index = 0; index < attempts; index += 1) {
     job = await riddleRequestJson(config, `/v1/jobs/${jobId}`);
-    if (isTerminalRiddleJobStatus(job.status)) break;
+    const observedAt = Date.now();
+    lastSnapshot = buildPollSnapshot(jobId, job, {
+      attempt: index + 1,
+      attempts,
+      startedAt,
+      observedAt
+    });
+    const progressKey = [
+      lastSnapshot.status || "unknown",
+      lastSnapshot.terminal ? "terminal" : "nonterminal",
+      lastSnapshot.submitted_at ? "submitted" : "unsubmitted"
+    ].join(":");
+    if (options.onProgress) {
+      const shouldReport = index === 0 || lastSnapshot.terminal || progressKey !== lastProgressKey || observedAt - lastProgressAt >= progressEveryMs;
+      if (shouldReport) {
+        lastProgressAt = observedAt;
+        lastProgressKey = progressKey;
+        await options.onProgress(lastSnapshot);
+      }
+    }
+    if (lastSnapshot.terminal) break;
     if (index + 1 < attempts) {
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
   }
   const status = job?.status ? String(job.status) : null;
+  const fallbackObservedAt = Date.now();
+  const snapshot = lastSnapshot || buildPollSnapshot(jobId, job, {
+    attempt: 0,
+    attempts,
+    startedAt,
+    observedAt: fallbackObservedAt
+  });
   if (!isTerminalRiddleJobStatus(status)) {
-    return { ok: true, job_id: jobId, status, terminal: false, job };
+    const timedOut = Boolean(options.wait);
+    return {
+      ok: !timedOut,
+      job_id: jobId,
+      status,
+      terminal: false,
+      job,
+      poll: {
+        ...snapshot,
+        timed_out: timedOut,
+        interval_ms: intervalMs,
+        message: pollMessage(snapshot, timedOut)
+      }
+    };
   }
   const artifacts = await riddleRequestJson(config, `/v1/jobs/${jobId}/artifacts`);
   return {
@@ -6766,7 +6854,12 @@ async function pollRiddleJob(config, jobId, options = {}) {
     status,
     terminal: true,
     job,
-    artifacts
+    artifacts,
+    poll: {
+      ...snapshot,
+      timed_out: false,
+      interval_ms: intervalMs
+    }
   };
 }
 function createRiddleApiClient(config = {}) {
@@ -7885,6 +7978,20 @@ async function captureViewport(viewport) {
     const scrollWidth = documentElement ? documentElement.scrollWidth : 0;
     const viewportWidth = clientWidth || window.innerWidth;
     const overflowOffenders = [];
+    function isContainedByHorizontalScroller(element) {
+      let current = element.parentElement;
+      while (current && current !== body && current !== documentElement) {
+        const style = window.getComputedStyle(current);
+        const overflowX = style.overflowX || style.overflow || "";
+        if ((overflowX === "auto" || overflowX === "scroll") && current.scrollWidth > current.clientWidth + 1) {
+          const currentRect = current.getBoundingClientRect();
+          const contained = currentRect.left >= -0.5 && currentRect.right <= viewportWidth + 0.5;
+          if (contained) return true;
+        }
+        current = current.parentElement;
+      }
+      return false;
+    }
     for (const element of Array.from(body ? body.querySelectorAll("*") : [])) {
       const rect = element.getBoundingClientRect();
       if (!rect || rect.width < 1 || rect.height < 1) continue;
@@ -7894,6 +8001,7 @@ async function captureViewport(viewport) {
       const rightOverflow = Math.max(0, rect.right - viewportWidth);
       const overflow = Math.max(leftOverflow, rightOverflow);
       if (overflow <= 0.5) continue;
+      if (isContainedByHorizontalScroller(element)) continue;
       const tag = element.tagName ? element.tagName.toLowerCase() : "element";
       const id = element.id ? "#" + element.id : "";
       const className = typeof element.className === "string"
@@ -7925,6 +8033,7 @@ async function captureViewport(viewport) {
       pathname: location.pathname,
       title: document.title,
       body_text_length: text.length,
+      body_text: text,
       body_text_sample: text.slice(0, 8000),
       scroll_width: scrollWidth,
       client_width: clientWidth,
@@ -7950,7 +8059,7 @@ async function captureViewport(viewport) {
       selectors[check.selector] = await selectorStats(check.selector);
     }
     if ((check.type === "text_visible" || check.type === "text_absent") && (check.text || check.pattern)) {
-      text_matches[textKey(check)] = textMatches(dom.body_text_sample || "", check);
+      text_matches[textKey(check)] = textMatches(dom.body_text || dom.body_text_sample || "", check);
     }
   }
   const screenshotLabel = profileSlug + "-" + viewport.name;
@@ -8140,7 +8249,7 @@ function usage() {
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label>",
     "  riddle-proof-loop riddle-server-preview <directory> --script-file <file> [--path /route] [--wait-for-selector selector]",
     "  riddle-proof-loop riddle-run-script --url <url> --script-file <file> [--viewport 1280x720]",
-    "  riddle-proof-loop riddle-poll <job-id> [--wait]",
+    "  riddle-proof-loop riddle-poll <job-id> [--wait] [--attempts n] [--quiet]",
     "  riddle-proof-loop doctor local [--codex-command <path>]",
     "",
     "The default CLI run mode is checkpoint-mode=yield unless --agent local is used.",
@@ -8174,6 +8283,26 @@ function optionString(options, key) {
 function readStdin() {
   return (0, import_node_fs6.readFileSync)(0, "utf-8");
 }
+function formatPollDuration(ms) {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) return "n/a";
+  const seconds = Math.max(0, Math.round(ms / 1e3));
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return minutes > 0 ? `${minutes}m${String(remainder).padStart(2, "0")}s` : `${seconds}s`;
+}
+function riddlePollProgressLine(snapshot) {
+  const submittedAt = snapshot.submitted_at || "not-submitted";
+  const queuePart = snapshot.running_without_submission ? ` queued_for=${formatPollDuration(snapshot.queue_elapsed_ms)}` : snapshot.queue_elapsed_ms !== null ? ` queue=${formatPollDuration(snapshot.queue_elapsed_ms)}` : "";
+  const terminalPart = snapshot.terminal ? " terminal=true" : "";
+  return [
+    "[riddle-poll]",
+    snapshot.job_id,
+    `status=${snapshot.status || "unknown"}`,
+    `attempt=${snapshot.attempt}/${snapshot.attempts}`,
+    `elapsed=${formatPollDuration(snapshot.elapsed_ms)}`,
+    `submitted_at=${submittedAt}${queuePart}${terminalPart}`
+  ].join(" ");
+}
 function readJsonValue(value, label) {
   if (!value) throw new Error(`${label} is required.`);
   const raw = value === "-" ? readStdin() : (0, import_node_fs6.existsSync)(value) ? (0, import_node_fs6.readFileSync)(value, "utf-8") : value;
@@ -8605,10 +8734,16 @@ async function main() {
   if (command === "riddle-poll") {
     const jobId = positional[1];
     if (!jobId) throw new Error("riddle-poll requires <job-id>.");
+    const wait = options.wait === true;
     const result = await createRiddleApiClient(riddleClientConfig(options)).pollJob(jobId, {
-      wait: options.wait === true,
+      wait,
       attempts: optionString(options, "attempts") ? Number(optionString(options, "attempts")) : void 0,
-      intervalMs: optionString(options, "intervalMs") ? Number(optionString(options, "intervalMs")) : void 0
+      intervalMs: optionString(options, "intervalMs") ? Number(optionString(options, "intervalMs")) : void 0,
+      progressEveryMs: optionString(options, "progressEveryMs") ? Number(optionString(options, "progressEveryMs")) : void 0,
+      onProgress: wait && options.quiet !== true ? (snapshot) => {
+        process.stderr.write(`${riddlePollProgressLine(snapshot)}
+`);
+      } : void 0
     });
     process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);

package/dist/cli.js

@@ -10,11 +10,11 @@ import {
   profileStatusExitCode,
   resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec
-} from "./chunk-XOM2OYAB.js";
+} from "./chunk-SDSBS64X.js";
 import {
   createRiddleApiClient,
   parseRiddleViewport
-} from "./chunk-5KOHSE4V.js";
+} from "./chunk-7PSWK57T.js";
 import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
@@ -48,7 +48,7 @@ function usage() {
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label>",
     "  riddle-proof-loop riddle-server-preview <directory> --script-file <file> [--path /route] [--wait-for-selector selector]",
     "  riddle-proof-loop riddle-run-script --url <url> --script-file <file> [--viewport 1280x720]",
-    "  riddle-proof-loop riddle-poll <job-id> [--wait]",
+    "  riddle-proof-loop riddle-poll <job-id> [--wait] [--attempts n] [--quiet]",
     "  riddle-proof-loop doctor local [--codex-command <path>]",
     "",
     "The default CLI run mode is checkpoint-mode=yield unless --agent local is used.",
@@ -82,6 +82,26 @@ function optionString(options, key) {
 function readStdin() {
   return readFileSync(0, "utf-8");
 }
+function formatPollDuration(ms) {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) return "n/a";
+  const seconds = Math.max(0, Math.round(ms / 1e3));
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return minutes > 0 ? `${minutes}m${String(remainder).padStart(2, "0")}s` : `${seconds}s`;
+}
+function riddlePollProgressLine(snapshot) {
+  const submittedAt = snapshot.submitted_at || "not-submitted";
+  const queuePart = snapshot.running_without_submission ? ` queued_for=${formatPollDuration(snapshot.queue_elapsed_ms)}` : snapshot.queue_elapsed_ms !== null ? ` queue=${formatPollDuration(snapshot.queue_elapsed_ms)}` : "";
+  const terminalPart = snapshot.terminal ? " terminal=true" : "";
+  return [
+    "[riddle-poll]",
+    snapshot.job_id,
+    `status=${snapshot.status || "unknown"}`,
+    `attempt=${snapshot.attempt}/${snapshot.attempts}`,
+    `elapsed=${formatPollDuration(snapshot.elapsed_ms)}`,
+    `submitted_at=${submittedAt}${queuePart}${terminalPart}`
+  ].join(" ");
+}
 function readJsonValue(value, label) {
   if (!value) throw new Error(`${label} is required.`);
   const raw = value === "-" ? readStdin() : existsSync(value) ? readFileSync(value, "utf-8") : value;
@@ -513,10 +533,16 @@ async function main() {
   if (command === "riddle-poll") {
     const jobId = positional[1];
     if (!jobId) throw new Error("riddle-poll requires <job-id>.");
+    const wait = options.wait === true;
     const result = await createRiddleApiClient(riddleClientConfig(options)).pollJob(jobId, {
-      wait: options.wait === true,
+      wait,
       attempts: optionString(options, "attempts") ? Number(optionString(options, "attempts")) : void 0,
-      intervalMs: optionString(options, "intervalMs") ? Number(optionString(options, "intervalMs")) : void 0
+      intervalMs: optionString(options, "intervalMs") ? Number(optionString(options, "intervalMs")) : void 0,
+      progressEveryMs: optionString(options, "progressEveryMs") ? Number(optionString(options, "progressEveryMs")) : void 0,
+      onProgress: wait && options.quiet !== true ? (snapshot) => {
+        process.stderr.write(`${riddlePollProgressLine(snapshot)}
+`);
+      } : void 0
     });
     process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);

package/dist/index.cjs

@@ -9835,6 +9835,20 @@ async function captureViewport(viewport) {
     const scrollWidth = documentElement ? documentElement.scrollWidth : 0;
     const viewportWidth = clientWidth || window.innerWidth;
     const overflowOffenders = [];
+    function isContainedByHorizontalScroller(element) {
+      let current = element.parentElement;
+      while (current && current !== body && current !== documentElement) {
+        const style = window.getComputedStyle(current);
+        const overflowX = style.overflowX || style.overflow || "";
+        if ((overflowX === "auto" || overflowX === "scroll") && current.scrollWidth > current.clientWidth + 1) {
+          const currentRect = current.getBoundingClientRect();
+          const contained = currentRect.left >= -0.5 && currentRect.right <= viewportWidth + 0.5;
+          if (contained) return true;
+        }
+        current = current.parentElement;
+      }
+      return false;
+    }
     for (const element of Array.from(body ? body.querySelectorAll("*") : [])) {
       const rect = element.getBoundingClientRect();
       if (!rect || rect.width < 1 || rect.height < 1) continue;
@@ -9844,6 +9858,7 @@ async function captureViewport(viewport) {
       const rightOverflow = Math.max(0, rect.right - viewportWidth);
       const overflow = Math.max(leftOverflow, rightOverflow);
       if (overflow <= 0.5) continue;
+      if (isContainedByHorizontalScroller(element)) continue;
       const tag = element.tagName ? element.tagName.toLowerCase() : "element";
       const id = element.id ? "#" + element.id : "";
       const className = typeof element.className === "string"
@@ -9875,6 +9890,7 @@ async function captureViewport(viewport) {
       pathname: location.pathname,
       title: document.title,
       body_text_length: text.length,
+      body_text: text,
       body_text_sample: text.slice(0, 8000),
       scroll_width: scrollWidth,
       client_width: clientWidth,
@@ -9900,7 +9916,7 @@ async function captureViewport(viewport) {
       selectors[check.selector] = await selectorStats(check.selector);
     }
     if ((check.type === "text_visible" || check.type === "text_absent") && (check.text || check.pattern)) {
-      text_matches[textKey(check)] = textMatches(dom.body_text_sample || "", check);
+      text_matches[textKey(check)] = textMatches(dom.body_text || dom.body_text_sample || "", check);
     }
   }
   const screenshotLabel = profileSlug + "-" + viewport.name;
@@ -10275,21 +10291,109 @@ async function runRiddleScript(config, input) {
 function isTerminalRiddleJobStatus(status) {
   return ["completed", "complete", "completed_error", "completed_timeout", "failed"].includes(String(status || ""));
 }
+function stringField(record, key) {
+  const value = record?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function parseTimestampMs(value) {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function buildPollSnapshot(jobId, job, input) {
+  const status = job?.status ? String(job.status) : null;
+  const terminal = isTerminalRiddleJobStatus(status);
+  const createdAt = stringField(job, "created_at");
+  const submittedAt = stringField(job, "submitted_at");
+  const completedAt = stringField(job, "completed_at");
+  const createdMs = parseTimestampMs(createdAt);
+  const submittedMs = parseTimestampMs(submittedAt);
+  let queueElapsedMs = null;
+  if (createdMs !== null && submittedMs !== null) {
+    queueElapsedMs = Math.max(0, submittedMs - createdMs);
+  } else if (createdMs !== null && !submittedAt && !terminal) {
+    queueElapsedMs = Math.max(0, input.observedAt - createdMs);
+  }
+  return {
+    job_id: jobId,
+    status,
+    terminal,
+    attempt: input.attempt,
+    attempts: input.attempts,
+    elapsed_ms: Math.max(0, input.observedAt - input.startedAt),
+    created_at: createdAt,
+    submitted_at: submittedAt,
+    completed_at: completedAt,
+    queue_elapsed_ms: queueElapsedMs,
+    running_without_submission: Boolean(status && !terminal && !submittedAt)
+  };
+}
+function pollMessage(snapshot, timedOut) {
+  if (!timedOut) return void 0;
+  const submitted = snapshot.submitted_at || "not submitted";
+  const queue = snapshot.queue_elapsed_ms !== null ? ` queue_elapsed_ms=${snapshot.queue_elapsed_ms}` : "";
+  return `Riddle job ${snapshot.job_id} did not reach a terminal status after ${snapshot.attempt} poll attempts; status=${snapshot.status || "unknown"} submitted_at=${submitted}.${queue}`;
+}
 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;
+  const attempts = Math.max(1, Math.floor(options.attempts ?? (options.wait ? 300 : 1)));
+  const intervalMs = Math.max(0, Math.floor(options.intervalMs ?? 2e3));
+  const progressEveryMs = Math.max(0, Math.floor(options.progressEveryMs ?? 1e4));
+  const startedAt = Date.now();
   let job = null;
+  let lastSnapshot = null;
+  let lastProgressAt = 0;
+  let lastProgressKey = "";
   for (let index = 0; index < attempts; index += 1) {
     job = await riddleRequestJson(config, `/v1/jobs/${jobId}`);
-    if (isTerminalRiddleJobStatus(job.status)) break;
+    const observedAt = Date.now();
+    lastSnapshot = buildPollSnapshot(jobId, job, {
+      attempt: index + 1,
+      attempts,
+      startedAt,
+      observedAt
+    });
+    const progressKey = [
+      lastSnapshot.status || "unknown",
+      lastSnapshot.terminal ? "terminal" : "nonterminal",
+      lastSnapshot.submitted_at ? "submitted" : "unsubmitted"
+    ].join(":");
+    if (options.onProgress) {
+      const shouldReport = index === 0 || lastSnapshot.terminal || progressKey !== lastProgressKey || observedAt - lastProgressAt >= progressEveryMs;
+      if (shouldReport) {
+        lastProgressAt = observedAt;
+        lastProgressKey = progressKey;
+        await options.onProgress(lastSnapshot);
+      }
+    }
+    if (lastSnapshot.terminal) break;
     if (index + 1 < attempts) {
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
   }
   const status = job?.status ? String(job.status) : null;
+  const fallbackObservedAt = Date.now();
+  const snapshot = lastSnapshot || buildPollSnapshot(jobId, job, {
+    attempt: 0,
+    attempts,
+    startedAt,
+    observedAt: fallbackObservedAt
+  });
   if (!isTerminalRiddleJobStatus(status)) {
-    return { ok: true, job_id: jobId, status, terminal: false, job };
+    const timedOut = Boolean(options.wait);
+    return {
+      ok: !timedOut,
+      job_id: jobId,
+      status,
+      terminal: false,
+      job,
+      poll: {
+        ...snapshot,
+        timed_out: timedOut,
+        interval_ms: intervalMs,
+        message: pollMessage(snapshot, timedOut)
+      }
+    };
   }
   const artifacts = await riddleRequestJson(config, `/v1/jobs/${jobId}/artifacts`);
   return {
@@ -10298,7 +10402,12 @@ async function pollRiddleJob(config, jobId, options = {}) {
     status,
     terminal: true,
     job,
-    artifacts
+    artifacts,
+    poll: {
+      ...snapshot,
+      timed_out: false,
+      interval_ms: intervalMs
+    }
   };
 }
 function createRiddleApiClient(config = {}) {

package/dist/index.d.cts

@@ -11,4 +11,4 @@ export { BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_V
 export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, RiddleProofPlayabilityAssessment, RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode } from './playability.cjs';
 export { AssessBasicGameplayOptions, AttachBasicGameplayArtifactOptions, BASIC_GAMEPLAY_ACTION_TYPES, BASIC_GAMEPLAY_PROGRESS_CHECK_TYPES, BasicGameplayActionResult, BasicGameplayActionType, BasicGameplayArtifactResolution, BasicGameplayAssessmentSummary, BasicGameplayBoundsOffender, BasicGameplayCanvasState, BasicGameplayCatchRecord, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayFixReference, BasicGameplayMetric, BasicGameplayMobileEvidence, BasicGameplayProgressCheckType, BasicGameplayProgressionCheck, BasicGameplayProofArtifact, BasicGameplayResponsiveViewportEvidence, BasicGameplayRouteReference, BasicGameplaySnapshot, BasicGameplaySuiteFailure, BasicGameplayWarningCode, CreateBasicGameplayCatchSummaryInput, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayCatchSummary, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayProgressionCheck, assessBasicGameplayProgressionChecks, assessBasicGameplayRoute, attachBasicGameplayArtifactScreenshotHashes, augmentBasicGameplayAssessmentWithProgressionChecks, compactBasicGameplayText, createBasicGameplayCatchRecords, createBasicGameplayCatchSummary, extractBasicGameplayEvidence, resolveBasicGameplayProgressionCheckWithArtifactScreenshots, sanitizeBasicGameplayJsonString } from './basic-gameplay.cjs';
 export { NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, RiddleProofProfile, RiddleProofProfileArtifactRef, RiddleProofProfileBaselinePolicy, RiddleProofProfileBoundsOffender, RiddleProofProfileCheck, RiddleProofProfileCheckResult, RiddleProofProfileCheckType, RiddleProofProfileEvidence, RiddleProofProfileFailureAction, RiddleProofProfileResult, RiddleProofProfileRouteEvidence, RiddleProofProfileRunner, RiddleProofProfileSetupAction, RiddleProofProfileSetupActionType, RiddleProofProfileStatus, RiddleProofProfileTarget, RiddleProofProfileViewport, RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, extractRiddleProofProfileResult, normalizeRiddleProofProfile, profileStatusExitCode, resolveRiddleProofProfileRouteUrl, resolveRiddleProofProfileTargetUrl, resolveRiddleProofProfileTimeoutSec, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult } from './profile.cjs';
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobResult, RiddlePreviewDeployResult, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.cjs';
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployResult, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.cjs';

package/dist/index.d.ts

@@ -11,4 +11,4 @@ export { BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_V
 export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, RiddleProofPlayabilityAssessment, RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode } from './playability.js';
 export { AssessBasicGameplayOptions, AttachBasicGameplayArtifactOptions, BASIC_GAMEPLAY_ACTION_TYPES, BASIC_GAMEPLAY_PROGRESS_CHECK_TYPES, BasicGameplayActionResult, BasicGameplayActionType, BasicGameplayArtifactResolution, BasicGameplayAssessmentSummary, BasicGameplayBoundsOffender, BasicGameplayCanvasState, BasicGameplayCatchRecord, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayFixReference, BasicGameplayMetric, BasicGameplayMobileEvidence, BasicGameplayProgressCheckType, BasicGameplayProgressionCheck, BasicGameplayProofArtifact, BasicGameplayResponsiveViewportEvidence, BasicGameplayRouteReference, BasicGameplaySnapshot, BasicGameplaySuiteFailure, BasicGameplayWarningCode, CreateBasicGameplayCatchSummaryInput, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayCatchSummary, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayProgressionCheck, assessBasicGameplayProgressionChecks, assessBasicGameplayRoute, attachBasicGameplayArtifactScreenshotHashes, augmentBasicGameplayAssessmentWithProgressionChecks, compactBasicGameplayText, createBasicGameplayCatchRecords, createBasicGameplayCatchSummary, extractBasicGameplayEvidence, resolveBasicGameplayProgressionCheckWithArtifactScreenshots, sanitizeBasicGameplayJsonString } from './basic-gameplay.js';
 export { NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, RiddleProofProfile, RiddleProofProfileArtifactRef, RiddleProofProfileBaselinePolicy, RiddleProofProfileBoundsOffender, RiddleProofProfileCheck, RiddleProofProfileCheckResult, RiddleProofProfileCheckType, RiddleProofProfileEvidence, RiddleProofProfileFailureAction, RiddleProofProfileResult, RiddleProofProfileRouteEvidence, RiddleProofProfileRunner, RiddleProofProfileSetupAction, RiddleProofProfileSetupActionType, RiddleProofProfileStatus, RiddleProofProfileTarget, RiddleProofProfileViewport, RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, extractRiddleProofProfileResult, normalizeRiddleProofProfile, profileStatusExitCode, resolveRiddleProofProfileRouteUrl, resolveRiddleProofProfileTargetUrl, resolveRiddleProofProfileTimeoutSec, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult } from './profile.js';
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobResult, RiddlePreviewDeployResult, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.js';
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployResult, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.js';

package/dist/index.js

@@ -58,7 +58,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-XOM2OYAB.js";
+} from "./chunk-SDSBS64X.js";
 import {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
@@ -72,7 +72,7 @@ import {
   riddleRequestJson,
   runRiddleScript,
   runRiddleServerPreview
-} from "./chunk-5KOHSE4V.js";
+} from "./chunk-7PSWK57T.js";
 import {
   DEFAULT_DIAGNOSTIC_ARRAY_LIMIT,
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,

package/dist/profile.cjs

@@ -1164,6 +1164,20 @@ async function captureViewport(viewport) {
     const scrollWidth = documentElement ? documentElement.scrollWidth : 0;
     const viewportWidth = clientWidth || window.innerWidth;
     const overflowOffenders = [];
+    function isContainedByHorizontalScroller(element) {
+      let current = element.parentElement;
+      while (current && current !== body && current !== documentElement) {
+        const style = window.getComputedStyle(current);
+        const overflowX = style.overflowX || style.overflow || "";
+        if ((overflowX === "auto" || overflowX === "scroll") && current.scrollWidth > current.clientWidth + 1) {
+          const currentRect = current.getBoundingClientRect();
+          const contained = currentRect.left >= -0.5 && currentRect.right <= viewportWidth + 0.5;
+          if (contained) return true;
+        }
+        current = current.parentElement;
+      }
+      return false;
+    }
     for (const element of Array.from(body ? body.querySelectorAll("*") : [])) {
       const rect = element.getBoundingClientRect();
       if (!rect || rect.width < 1 || rect.height < 1) continue;
@@ -1173,6 +1187,7 @@ async function captureViewport(viewport) {
       const rightOverflow = Math.max(0, rect.right - viewportWidth);
       const overflow = Math.max(leftOverflow, rightOverflow);
       if (overflow <= 0.5) continue;
+      if (isContainedByHorizontalScroller(element)) continue;
       const tag = element.tagName ? element.tagName.toLowerCase() : "element";
       const id = element.id ? "#" + element.id : "";
       const className = typeof element.className === "string"
@@ -1204,6 +1219,7 @@ async function captureViewport(viewport) {
       pathname: location.pathname,
       title: document.title,
       body_text_length: text.length,
+      body_text: text,
       body_text_sample: text.slice(0, 8000),
       scroll_width: scrollWidth,
       client_width: clientWidth,
@@ -1229,7 +1245,7 @@ async function captureViewport(viewport) {
       selectors[check.selector] = await selectorStats(check.selector);
     }
     if ((check.type === "text_visible" || check.type === "text_absent") && (check.text || check.pattern)) {
-      text_matches[textKey(check)] = textMatches(dom.body_text_sample || "", check);
+      text_matches[textKey(check)] = textMatches(dom.body_text || dom.body_text_sample || "", check);
     }
   }
   const screenshotLabel = profileSlug + "-" + viewport.name;

package/dist/profile.js

@@ -19,7 +19,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-XOM2OYAB.js";
+} from "./chunk-SDSBS64X.js";
 export {
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,
   RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,

package/dist/riddle-client.cjs

@@ -241,21 +241,109 @@ async function runRiddleScript(config, input) {
 function isTerminalRiddleJobStatus(status) {
   return ["completed", "complete", "completed_error", "completed_timeout", "failed"].includes(String(status || ""));
 }
+function stringField(record, key) {
+  const value = record?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function parseTimestampMs(value) {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function buildPollSnapshot(jobId, job, input) {
+  const status = job?.status ? String(job.status) : null;
+  const terminal = isTerminalRiddleJobStatus(status);
+  const createdAt = stringField(job, "created_at");
+  const submittedAt = stringField(job, "submitted_at");
+  const completedAt = stringField(job, "completed_at");
+  const createdMs = parseTimestampMs(createdAt);
+  const submittedMs = parseTimestampMs(submittedAt);
+  let queueElapsedMs = null;
+  if (createdMs !== null && submittedMs !== null) {
+    queueElapsedMs = Math.max(0, submittedMs - createdMs);
+  } else if (createdMs !== null && !submittedAt && !terminal) {
+    queueElapsedMs = Math.max(0, input.observedAt - createdMs);
+  }
+  return {
+    job_id: jobId,
+    status,
+    terminal,
+    attempt: input.attempt,
+    attempts: input.attempts,
+    elapsed_ms: Math.max(0, input.observedAt - input.startedAt),
+    created_at: createdAt,
+    submitted_at: submittedAt,
+    completed_at: completedAt,
+    queue_elapsed_ms: queueElapsedMs,
+    running_without_submission: Boolean(status && !terminal && !submittedAt)
+  };
+}
+function pollMessage(snapshot, timedOut) {
+  if (!timedOut) return void 0;
+  const submitted = snapshot.submitted_at || "not submitted";
+  const queue = snapshot.queue_elapsed_ms !== null ? ` queue_elapsed_ms=${snapshot.queue_elapsed_ms}` : "";
+  return `Riddle job ${snapshot.job_id} did not reach a terminal status after ${snapshot.attempt} poll attempts; status=${snapshot.status || "unknown"} submitted_at=${submitted}.${queue}`;
+}
 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;
+  const attempts = Math.max(1, Math.floor(options.attempts ?? (options.wait ? 300 : 1)));
+  const intervalMs = Math.max(0, Math.floor(options.intervalMs ?? 2e3));
+  const progressEveryMs = Math.max(0, Math.floor(options.progressEveryMs ?? 1e4));
+  const startedAt = Date.now();
   let job = null;
+  let lastSnapshot = null;
+  let lastProgressAt = 0;
+  let lastProgressKey = "";
   for (let index = 0; index < attempts; index += 1) {
     job = await riddleRequestJson(config, `/v1/jobs/${jobId}`);
-    if (isTerminalRiddleJobStatus(job.status)) break;
+    const observedAt = Date.now();
+    lastSnapshot = buildPollSnapshot(jobId, job, {
+      attempt: index + 1,
+      attempts,
+      startedAt,
+      observedAt
+    });
+    const progressKey = [
+      lastSnapshot.status || "unknown",
+      lastSnapshot.terminal ? "terminal" : "nonterminal",
+      lastSnapshot.submitted_at ? "submitted" : "unsubmitted"
+    ].join(":");
+    if (options.onProgress) {
+      const shouldReport = index === 0 || lastSnapshot.terminal || progressKey !== lastProgressKey || observedAt - lastProgressAt >= progressEveryMs;
+      if (shouldReport) {
+        lastProgressAt = observedAt;
+        lastProgressKey = progressKey;
+        await options.onProgress(lastSnapshot);
+      }
+    }
+    if (lastSnapshot.terminal) break;
     if (index + 1 < attempts) {
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
   }
   const status = job?.status ? String(job.status) : null;
+  const fallbackObservedAt = Date.now();
+  const snapshot = lastSnapshot || buildPollSnapshot(jobId, job, {
+    attempt: 0,
+    attempts,
+    startedAt,
+    observedAt: fallbackObservedAt
+  });
   if (!isTerminalRiddleJobStatus(status)) {
-    return { ok: true, job_id: jobId, status, terminal: false, job };
+    const timedOut = Boolean(options.wait);
+    return {
+      ok: !timedOut,
+      job_id: jobId,
+      status,
+      terminal: false,
+      job,
+      poll: {
+        ...snapshot,
+        timed_out: timedOut,
+        interval_ms: intervalMs,
+        message: pollMessage(snapshot, timedOut)
+      }
+    };
   }
   const artifacts = await riddleRequestJson(config, `/v1/jobs/${jobId}/artifacts`);
   return {
@@ -264,7 +352,12 @@ async function pollRiddleJob(config, jobId, options = {}) {
     status,
     terminal: true,
     job,
-    artifacts
+    artifacts,
+    poll: {
+      ...snapshot,
+      timed_out: false,
+      interval_ms: intervalMs
+    }
   };
 }
 function createRiddleApiClient(config = {}) {

package/dist/riddle-client.d.cts

@@ -7,6 +7,31 @@ interface RiddleClientConfig {
     apiBaseUrl?: string;
     fetchImpl?: RiddleFetch;
 }
+interface RiddlePollProgressSnapshot {
+    job_id: string;
+    status: string | null;
+    terminal: boolean;
+    attempt: number;
+    attempts: number;
+    elapsed_ms: number;
+    created_at: string | null;
+    submitted_at: string | null;
+    completed_at: string | null;
+    queue_elapsed_ms: number | null;
+    running_without_submission: boolean;
+}
+interface RiddlePollSummary extends RiddlePollProgressSnapshot {
+    timed_out: boolean;
+    interval_ms: number;
+    message?: string;
+}
+interface RiddlePollJobOptions {
+    wait?: boolean;
+    attempts?: number;
+    intervalMs?: number;
+    progressEveryMs?: number;
+    onProgress?: (snapshot: RiddlePollProgressSnapshot) => void | Promise<void>;
+}
 interface RiddlePreviewDeployResult {
     ok: true;
     id: string;
@@ -58,6 +83,7 @@ interface RiddlePollJobResult {
     terminal: boolean;
     job: Record<string, unknown> | null;
     artifacts?: Record<string, unknown> | null;
+    poll?: RiddlePollSummary;
 }
 interface RiddleServerPreviewResult {
     ok: boolean;
@@ -83,21 +109,13 @@ declare function parseRiddleViewport(value?: string): {
 declare function runRiddleServerPreview(config: RiddleClientConfig, input: RiddleServerPreviewInput): Promise<RiddleServerPreviewResult>;
 declare function runRiddleScript(config: RiddleClientConfig, input: RiddleRunScriptInput): Promise<Record<string, unknown>>;
 declare function isTerminalRiddleJobStatus(status: unknown): boolean;
-declare function pollRiddleJob(config: RiddleClientConfig, jobId: string, options?: {
-    wait?: boolean;
-    attempts?: number;
-    intervalMs?: number;
-}): Promise<RiddlePollJobResult>;
+declare function pollRiddleJob(config: RiddleClientConfig, jobId: string, options?: RiddlePollJobOptions): Promise<RiddlePollJobResult>;
 declare function createRiddleApiClient(config?: RiddleClientConfig): {
     requestJson: <T = unknown>(pathname: string, init?: RequestInit) => Promise<T>;
     deployStaticPreview: (directory: string, label: string) => Promise<RiddlePreviewDeployResult>;
     runScript: (input: RiddleRunScriptInput) => Promise<Record<string, unknown>>;
     runServerPreview: (input: RiddleServerPreviewInput) => Promise<RiddleServerPreviewResult>;
-    pollJob: (jobId: string, options?: {
-        wait?: boolean;
-        attempts?: number;
-        intervalMs?: number;
-    }) => Promise<RiddlePollJobResult>;
+    pollJob: (jobId: string, options?: RiddlePollJobOptions) => Promise<RiddlePollJobResult>;
 };
 
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobResult, type RiddlePreviewDeployResult, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview };
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobOptions, type RiddlePollJobResult, type RiddlePollProgressSnapshot, type RiddlePollSummary, type RiddlePreviewDeployResult, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview };

package/dist/riddle-client.d.ts

@@ -7,6 +7,31 @@ interface RiddleClientConfig {
     apiBaseUrl?: string;
     fetchImpl?: RiddleFetch;
 }
+interface RiddlePollProgressSnapshot {
+    job_id: string;
+    status: string | null;
+    terminal: boolean;
+    attempt: number;
+    attempts: number;
+    elapsed_ms: number;
+    created_at: string | null;
+    submitted_at: string | null;
+    completed_at: string | null;
+    queue_elapsed_ms: number | null;
+    running_without_submission: boolean;
+}
+interface RiddlePollSummary extends RiddlePollProgressSnapshot {
+    timed_out: boolean;
+    interval_ms: number;
+    message?: string;
+}
+interface RiddlePollJobOptions {
+    wait?: boolean;
+    attempts?: number;
+    intervalMs?: number;
+    progressEveryMs?: number;
+    onProgress?: (snapshot: RiddlePollProgressSnapshot) => void | Promise<void>;
+}
 interface RiddlePreviewDeployResult {
     ok: true;
     id: string;
@@ -58,6 +83,7 @@ interface RiddlePollJobResult {
     terminal: boolean;
     job: Record<string, unknown> | null;
     artifacts?: Record<string, unknown> | null;
+    poll?: RiddlePollSummary;
 }
 interface RiddleServerPreviewResult {
     ok: boolean;
@@ -83,21 +109,13 @@ declare function parseRiddleViewport(value?: string): {
 declare function runRiddleServerPreview(config: RiddleClientConfig, input: RiddleServerPreviewInput): Promise<RiddleServerPreviewResult>;
 declare function runRiddleScript(config: RiddleClientConfig, input: RiddleRunScriptInput): Promise<Record<string, unknown>>;
 declare function isTerminalRiddleJobStatus(status: unknown): boolean;
-declare function pollRiddleJob(config: RiddleClientConfig, jobId: string, options?: {
-    wait?: boolean;
-    attempts?: number;
-    intervalMs?: number;
-}): Promise<RiddlePollJobResult>;
+declare function pollRiddleJob(config: RiddleClientConfig, jobId: string, options?: RiddlePollJobOptions): Promise<RiddlePollJobResult>;
 declare function createRiddleApiClient(config?: RiddleClientConfig): {
     requestJson: <T = unknown>(pathname: string, init?: RequestInit) => Promise<T>;
     deployStaticPreview: (directory: string, label: string) => Promise<RiddlePreviewDeployResult>;
     runScript: (input: RiddleRunScriptInput) => Promise<Record<string, unknown>>;
     runServerPreview: (input: RiddleServerPreviewInput) => Promise<RiddleServerPreviewResult>;
-    pollJob: (jobId: string, options?: {
-        wait?: boolean;
-        attempts?: number;
-        intervalMs?: number;
-    }) => Promise<RiddlePollJobResult>;
+    pollJob: (jobId: string, options?: RiddlePollJobOptions) => Promise<RiddlePollJobResult>;
 };
 
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobResult, type RiddlePreviewDeployResult, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview };
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobOptions, type RiddlePollJobResult, type RiddlePollProgressSnapshot, type RiddlePollSummary, type RiddlePreviewDeployResult, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview };

package/dist/riddle-client.js

@@ -11,7 +11,7 @@ import {
   riddleRequestJson,
   runRiddleScript,
   runRiddleServerPreview
-} from "./chunk-5KOHSE4V.js";
+} from "./chunk-7PSWK57T.js";
 export {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.7.23",
+  "version": "0.7.25",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",