@kirrosh/zond 0.23.0 → 0.26.1

package/src/cli/commands/checks.ts

@@ -16,8 +16,9 @@ import type { Command } from "commander";
 
 import { listChecks, runChecks } from "../../core/checks/index.ts";
 import { listStatefulChecks } from "../../core/checks/stateful.ts";
+import { resolveBudget, isBudget, BUDGETS, type Budget } from "../../core/checks/budget.ts";
 import { generateSarifReport } from "../../core/checks/sarif.ts";
-import { emitToStdout } from "../../core/reporter/ndjson.ts";
+import { emitToStdout, nowIso } from "../../core/reporter/ndjson.ts";
 import { parseWorkers } from "../../core/runner/async-pool.ts";
 import { createAdaptiveRateLimiter, createRateLimiter, type RateLimiter } from "../../core/runner/rate-limiter.ts";
 import { compileOperationFilter } from "../../core/selectors/operation-filter.ts";
@@ -26,11 +27,17 @@ import { readResourceMap } from "./discover.ts";
 import type { ReadbackDiffConfig, IdempotencyConfig, PaginationConfig, LifecycleConfig, SeedBodyConfig } from "../../core/generator/resources-builder.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 import { printError, printSuccess } from "../output.ts";
+import { SAFE_HELP, LIVE_HELP, resolveLive } from "../safe-live.ts";
 import { loadEnvironment } from "../../core/parser/variables.ts";
+import { readFixtureGaps, gapIndex } from "../../core/workspace/fixture-gaps.ts";
 import { getApi } from "../util/api-context.ts";
 import { VERSION } from "../version.ts";
 import { resolveOutput, OutputSpecError, type OutputSpec, type ResolvedOutput } from "../../core/output/index.ts";
 import type { RunChecksResult } from "../../core/checks/index.ts";
+import type { ChecksCaseEvent } from "../../core/checks/runner.ts";
+import { beginAuditRun, finalizeAuditRun, checksPersistEnabled, type AuditCaseRecord } from "../../core/audit/persist.ts";
+import { readCurrentSession } from "../../core/context/session.ts";
+import { getDb } from "../../db/schema.ts";
 
 /**
  * ARV-118 (m-19): typed declaration of every `--report` / `--output` /
@@ -119,6 +126,21 @@ interface ChecksRunOptions {
   strict405?: boolean;
   strict401?: boolean;
   maxRequests?: number;
+  /** ARV-342: operation-window for bounded/resumable sweeps of large specs. */
+  maxOps?: number;
+  skipOps?: number;
+  budget?: string;
+  showSuppressed?: boolean;
+  /** ARV-308: `--no-fail-on-findings` sets this to false (commander default
+   *  true) — keep exit 0 even when HIGH/CRITICAL findings exist so an
+   *  orchestrator can distinguish "found drift" from "command failed". */
+  failOnFindings?: boolean;
+  /** ARV-308: `--advisory` alias for --no-fail-on-findings. */
+  advisory?: boolean;
+  /** ARV-299: safe/live parity with `audit`. Default safe — mutating
+   *  stateful create-chains self-skip; `--live` runs them. */
+  safe?: boolean;
+  live?: boolean;
 }
 
 function parseAuthHeaders(values: string[] | undefined): Record<string, string> {
@@ -188,6 +210,8 @@ async function deriveResourceConfigsFromApi(
         limitParam: r.pagination.limit_param,
         defaultLimit: r.pagination.default_limit,
         itemsField: r.pagination.items_field,
+        pageParam: r.pagination.page_param,
+        startPage: r.pagination.start_page,
       };
     }
     if (r.lifecycle) {
@@ -240,6 +264,19 @@ async function derivePathVarsFromApi(apiName: string | undefined, dbPath: string
   }
 }
 
+/** ARV-324: load `.fixture-gaps.yaml` (written by a prior prepare-fixtures/
+ *  discover run) so findings on a known-empty/inaccessible operation get
+ *  `fix_fixture` instead of `report_backend_bug`. Undefined (not an empty
+ *  Set) when there's no API context or no gaps file, so the classifier
+ *  can tell "nothing to check" apart from "checked, no gaps". */
+async function deriveFixtureGapsFromApi(apiName: string | undefined, dbPath: string | undefined): Promise<Set<string> | undefined> {
+  if (!apiName) return undefined;
+  const col = resolveApiCollection(apiName, dbPath);
+  if ("error" in col || !col.baseDir) return undefined;
+  const gaps = await readFixtureGaps(col.baseDir);
+  return gaps.length > 0 ? gapIndex(gaps) : undefined;
+}
+
 async function deriveAuthHeadersFromApi(apiName: string | undefined, dbPath: string | undefined): Promise<Record<string, string>> {
   if (!apiName) return {};
   const col = resolveApiCollection(apiName, dbPath);
@@ -338,9 +375,22 @@ function splitList(values: string[] | undefined): string[] | undefined {
 // instead of hand-listing cross_call_references, idempotency_replay, … —
 // matching the prior `--phase stateful` UX promise without overloading the
 // case-generation `--phase` flag.
-function expandStatefulAlias(ids: string[] | undefined): string[] | undefined {
+// ARV-325: `ignored_auth` / `open_cors_on_sensitive` live in the stateful
+// *registry* (they need the stateful harness to run), but semantically they
+// are auth/security checks. Users reading `--check stateful` expect
+// state-machine probes, not a full security pass — on Stripe the pair added
+// ~520 extra cases and turned a sub-minute run into ~10 minutes. Keep them
+// runnable by explicit id; just don't smuggle them in through the alias.
+const STATEFUL_ALIAS_EXCLUDED: ReadonlySet<string> = new Set([
+  "ignored_auth",
+  "open_cors_on_sensitive",
+]);
+
+export function expandStatefulAlias(ids: string[] | undefined): string[] | undefined {
   if (!ids) return ids;
-  const statefulIds = listStatefulChecks().map((c) => c.id);
+  const statefulIds = listStatefulChecks()
+    .map((c) => c.id)
+    .filter((id) => !STATEFUL_ALIAS_EXCLUDED.has(id));
   const out: string[] = [];
   for (const id of ids) {
     if (id === "stateful") out.push(...statefulIds);
@@ -432,6 +482,7 @@ async function checksRunAction(_args: unknown, cmd: Command): Promise<void> {
   // rounds and CI can't distinguish "spec stable" from "checks ignored deltas").
   const pathVars = await derivePathVarsFromApi(apiName, opts.db);
   const resourceConfigs = await deriveResourceConfigsFromApi(apiName, opts.db);
+  const fixtureGaps = await deriveFixtureGapsFromApi(apiName, opts.db);
 
   const phaseRaw = typeof opts.phase === "string" ? opts.phase : "examples";
   if (phaseRaw !== "examples" && phaseRaw !== "coverage" && phaseRaw !== "all") {
@@ -503,27 +554,179 @@ async function checksRunAction(_args: unknown, cmd: Command): Promise<void> {
   const ndjsonOutputPath: string | undefined = ndjson && resolved.channel === "file" ? resolved.path : undefined;
   let ndjsonFd: number | undefined;
   let ndjsonEventCount = 0;
+  let ndjsonLastFullyWritten = true;
   if (ndjsonOutputPath) {
     ndjsonFd = openSync(ndjsonOutputPath, "w");
   }
+  // ARV-343: accumulate a running summary from the stream so a SIGTERM'd
+  // run still emits a terminal `summary` line (operations/cases counted so
+  // far) instead of dying before the runner's emit stage — triage's
+  // `sweepWindows`/status-dist read `.summary.operations` and had to
+  // reconstruct it from raw NDJSON when the window was killed mid-flight.
+  const partialOps = new Set<string>();
+  const partialChecks = new Set<string>();
+  let partialCases = 0;
+  let partialFindings = 0;
+  const partialBySeverity = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+  const accumulate = (ev: import("../../core/reporter/ndjson.ts").NdjsonEvent) => {
+    if (ev.type === "check_result") {
+      partialCases += 1;
+      partialChecks.add(ev.check);
+      partialOps.add(`${ev.operation.method} ${ev.operation.path}`);
+    } else if (ev.type === "check_start") {
+      partialOps.add(`${ev.operation.method} ${ev.operation.path}`);
+    } else if (ev.type === "finding") {
+      partialFindings += 1;
+      const sev = ev.finding.severity as keyof typeof partialBySeverity;
+      if (sev in partialBySeverity) partialBySeverity[sev] += 1;
+    }
+  };
   const ndjsonOnEvent = ndjson
     ? (ndjsonFd !== undefined
         ? (ev: import("../../core/reporter/ndjson.ts").NdjsonEvent) => {
+            accumulate(ev);
+            ndjsonLastFullyWritten = false;
             ndjsonEventCount += 1;
             writeSync(ndjsonFd!, `${JSON.stringify(ev)}\n`);
+            ndjsonLastFullyWritten = true;
           }
-        : emitToStdout)
+        // ARV-323: count stdout-channel events too — the SIGTERM handler
+        // reports `ndjsonEventCount`, and with a shell-redirected stdout
+        // stream it claimed "0 event(s) flushed" while the redirect target
+        // already held thousands of lines.
+        : (ev: import("../../core/reporter/ndjson.ts").NdjsonEvent) => {
+            accumulate(ev);
+            ndjsonEventCount += 1;
+            emitToStdout(ev);
+          })
     : undefined;
 
+  // ARV-230: clean SIGTERM/SIGINT shutdown for NDJSON streams. Without
+  // this, killing a long `checks run --report ndjson` leaves a truncated
+  // last line in the file (or in the consumer's pipe) and downstream
+  // `jq -s` chokes until the user strips it with `sed '$d'`. The handler
+  // closes the fd (or drains stdout) and exits with the conventional
+  // 128+signo code instead of letting Node default-terminate mid-write.
+  let removeNdjsonSigHandlers: (() => void) | undefined;
+  if (ndjson) {
+    const shutdown = (signo: number) => {
+      try {
+        // ARV-343: flush a partial terminal summary from the running
+        // accumulators. Schema-exact (CheckRunSummarySchema) so downstream
+        // `jq '.summary.operations'` and status-dist stay analyzable;
+        // by_category/skipped are left empty (not derivable in the CLI) —
+        // the stderr interrupt note below flags that it's a partial count.
+        const partialSummary = {
+          type: "summary" as const,
+          ts: nowIso(),
+          summary: {
+            operations: partialOps.size,
+            cases: partialCases,
+            checks_run: partialChecks.size,
+            findings: partialFindings,
+            by_severity: { ...partialBySeverity },
+            by_category: { security: 0, reliability: 0, contract: 0, hygiene: 0 },
+            skipped_outcomes: {},
+            skipped_outcomes_grouped: [],
+          },
+        };
+        if (ndjsonFd !== undefined) {
+          if (!ndjsonLastFullyWritten) {
+            try { writeSync(ndjsonFd, "\n"); } catch { /* fd already gone */ }
+          }
+          try { writeSync(ndjsonFd, `${JSON.stringify(partialSummary)}\n`); } catch { /* fd already gone */ }
+          try { closeSync(ndjsonFd); } catch { /* already closed */ }
+          ndjsonFd = undefined;
+        } else {
+          try { emitToStdout(partialSummary); } catch { /* stdout gone */ }
+        }
+      } catch { /* swallow; we're tearing down */ }
+      // ARV-323: "emitted" not "flushed" — on the stdout channel the last
+      // few lines may still sit in the pipe buffer, so the count is a
+      // lower bound of what the consumer/file will contain, never an
+      // excuse to discard a partial-but-real stream.
+      try { process.stderr.write(`zond: NDJSON run interrupted (signal ${signo}); ${ndjsonEventCount} event(s) + a partial summary (${partialOps.size} ops, ${partialCases} cases so far) emitted before interrupt (partial stream is usable).\n`); } catch { /* ignore */ }
+      process.exit(128 + signo);
+    };
+    const onTerm = () => shutdown(15);
+    const onInt = () => shutdown(2);
+    process.on("SIGTERM", onTerm);
+    process.on("SIGINT", onInt);
+    removeNdjsonSigHandlers = () => {
+      process.off("SIGTERM", onTerm);
+      process.off("SIGINT", onInt);
+    };
+  }
+
+  // ARV-265: accumulate every HTTP case `runChecks` dispatches so we can
+  // persist them into the run/results tables after the run completes. The
+  // adapter maps ChecksCaseEvent → AuditCaseRecord (1:1) and groups by
+  // synthetic suite path (`apis/<api>/checks/<phase>`) so `detectRunKind`
+  // would still classify these rows as `check`-kind on legacy queries.
+  const auditPersist = checksPersistEnabled();
+  const auditCases: AuditCaseRecord[] = [];
+  const auditSuiteRoot = `apis/${apiName ?? "_"}/checks`;
+  const onCase = auditPersist
+    ? (ev: ChecksCaseEvent) => {
+        const phaseLabel = ev.phase === "response" ? "response" : ev.phase.replace("stateful_", "stateful/");
+        const suiteFile = `${auditSuiteRoot}/${phaseLabel}.yaml`;
+        const status = ev.verdict === "pass" ? "pass"
+          : ev.verdict === "fail" ? "fail"
+          : ev.verdict === "skip" ? "skip"
+          : "error";
+        auditCases.push({
+          suiteName: `checks/${phaseLabel}`,
+          suiteFile,
+          testName: `${ev.checkId}::${ev.operation.method.toUpperCase()} ${ev.operation.path}`,
+          status,
+          request: ev.request,
+          ...(ev.response ? { response: ev.response } : {}),
+          durationMs: ev.durationMs,
+          ...(ev.error ? { error: ev.error } : {}),
+        });
+      }
+    : undefined;
+
+  let budget: Budget | undefined;
+  if (opts.budget !== undefined) {
+    if (!isBudget(opts.budget)) {
+      printError(`--budget must be one of: ${BUDGETS.join(", ")}; got '${opts.budget}'`);
+      process.exit(1);
+    }
+    budget = opts.budget;
+  }
+  const includeList = expandStatefulAlias(splitList(opts.check));
+  const statefulIds = new Set(listStatefulChecks().map((c) => c.id));
+  const includesStateful = includeList?.some((id) => statefulIds.has(id)) === true;
+  const budgetResolved = resolveBudget(budget, opts.maxRequests, {
+    forceStatefulIfIncluded: includesStateful,
+  });
+
+  // ARV-328: throttled progress line on stderr during long runs (CI jobs
+  // and subagents with wall-clock budgets had zero visibility — the only
+  // artifact was the growing ndjson file). stderr never corrupts stdout
+  // reports; 10s throttle keeps short runs silent.
+  const PROGRESS_INTERVAL_MS = 10_000;
+  let lastProgressAt = Date.now();
+  const onProgress = (p: { done: number; total: number; cases: number }) => {
+    const now = Date.now();
+    if (now - lastProgressAt < PROGRESS_INTERVAL_MS) return;
+    lastProgressAt = now;
+    try {
+      process.stderr.write(`zond: progress — ${p.done}/${p.total} operations, ${p.cases} case(s) run\n`);
+    } catch { /* ignore */ }
+  };
+
   try {
     const result = await runChecks({
       specPath: specRes.spec,
       baseUrl: baseRes.baseUrl,
-      include: expandStatefulAlias(splitList(opts.check)),
+      include: includeList,
       exclude: expandStatefulAlias(splitList(opts.excludeCheck)),
       timeoutMs: typeof opts.timeout === "number" ? opts.timeout : undefined,
       authHeaders: Object.keys(authHeaders).length > 0 ? authHeaders : undefined,
       pathVars: Object.keys(pathVars).length > 0 ? pathVars : undefined,
+      fixtureGaps,
       resourceConfigs,
       bootstrapCleanupFailed: opts.bootstrapCleanupFailed === true,
       phase: phaseRaw as "examples" | "coverage" | "all",
@@ -533,13 +736,44 @@ async function checksRunAction(_args: unknown, cmd: Command): Promise<void> {
       mode: modeRaw as "positive" | "negative" | "all",
       operationFilter,
       onEvent: ndjsonOnEvent,
+      onCase,
+      onProgress,
       // ARV-8: bounded concurrency at op-level + optional rate-limiter
       // gating. workers=1 (default) preserves the pre-ARV-8 sequential
       // path inside runPool — same observable behaviour.
       workers,
       rateLimiter,
-      maxRequests: typeof opts.maxRequests === "number" && opts.maxRequests > 0 ? opts.maxRequests : undefined,
+      maxRequests: budgetResolved.maxRequests,
+      skipStateful: budgetResolved.skipStateful,
+      maxOps: opts.maxOps,
+      skipOps: opts.skipOps,
+      safe: !resolveLive(opts),
     });
+
+    // ARV-265: persist the accumulated cases as a `run_kind='check'` run
+    // so `zond coverage --scope audit` can count them. Failures here
+    // degrade to a warning — the user's primary command already succeeded.
+    if (auditPersist && auditCases.length > 0) {
+      try {
+        getDb(opts.db);
+        const { findCollectionByNameOrId } = await import("../../db/queries.ts");
+        const collectionId = apiName ? findCollectionByNameOrId(apiName)?.id : undefined;
+        const session = readCurrentSession();
+        const runId = beginAuditRun({
+          runKind: "check",
+          ...(collectionId != null ? { collectionId } : {}),
+          ...(session?.id ? { sessionId: session.id } : {}),
+          tags: ["checks", `phase:${phaseRaw}`, `mode:${modeRaw}`],
+        });
+        finalizeAuditRun(runId, auditCases);
+      } catch (err) {
+        // Audit persistence is best-effort. Surface the failure on stderr
+        // so an agent can detect it (the missing audit-coverage downstream
+        // will already point them here) without breaking the run.
+        const msg = (err as Error).message;
+        process.stderr.write(`zond: audit persistence failed (${msg}). Re-run with ZOND_CHECKS_PERSIST=0 to silence.\n`);
+      }
+    }
     const warnings: string[] = [];
     for (const id of result.selection.unknown) {
       warnings.push(`Unknown check: "${id}" — ignored. Run \`zond checks list\` to see registered ids.`);
@@ -612,50 +846,104 @@ async function checksRunAction(_args: unknown, cmd: Command): Promise<void> {
       }
       const skipLine = formatSkippedOutcomes(s.skipped_outcomes);
       if (skipLine) console.log(`  ${skipLine}`);
-      // ARV-18: aggregate identical findings (same check + same response
-      // status + same severity) so a 30-operation 401-not-in-spec sweep
-      // collapses to one row instead of drowning out single-shot findings.
-      // Per-operation detail is restored under --verbose; the JSON envelope
-      // and SARIF sidecar always carry the full unaggregated list.
+      // ARV-60: spec-level rollup. When the runner detected ≥80% of a
+      // check's applicable ops sharing one root cause, print one summary
+      // row with an actionable fix hint instead of N per-op rows that
+      // all say the same thing. `--verbose` always shows per-op detail
+      // (and JSON/SARIF carry the full unaggregated list regardless).
+      const rolledUpOps = new Set<string>();
+      if (!opts.verbose) {
+        for (const sf of result.data.spec_findings) {
+          if (sf.kind === "status_drift") {
+            for (const op of sf.affected_operations) {
+              rolledUpOps.add(`${sf.check}|${op.method} ${op.path}`);
+            }
+            console.log(
+              `  [${sf.severity}] ${sf.check} — ${sf.reason} (${sf.count}/${sf.applicable} operations)`,
+            );
+            console.log(`         → ${sf.fix_hint}`);
+          } else {
+            // missing_declaration / no_detector / other — no affected_operations
+            // to enumerate; surfaces as a single info row + fix hint.
+            const tag = sf.kind === "no_detector"
+              ? `${sf.count === 0 ? "0 cases" : `${sf.count} cases`} / ${sf.applicable} applicable ops`
+              : `${sf.count}/${sf.applicable} cases`;
+            console.log(`  [${sf.severity}] ${sf.check} — ${sf.reason} (${tag})`);
+            console.log(`         → ${sf.fix_hint}`);
+          }
+        }
+      }
+      // ARV-283 AC#4: suppressed findings stay in the ndjson audit-trail
+      // but are hidden from the human summary unless `--show-suppressed`
+      // is passed. They never count toward CI gates regardless.
+      const activeFindings = result.data.findings.filter((f) => !f.suppressed_by);
+      const suppressedFindings = result.data.findings.filter((f) => f.suppressed_by);
+
+      // Per-op findings — skip those already covered by a status_drift
+      // rollup unless --verbose was passed.
       if (opts.verbose) {
-        for (const f of result.data.findings) {
+        for (const f of activeFindings) {
           console.log(`  [${f.severity}] ${f.check} ${f.operation.method} ${f.operation.path} — ${f.message}`);
         }
       } else {
-        const groups = new Map<string, { severity: string; check: string; status: number; ops: Set<string>; sample: string }>();
-        for (const f of result.data.findings) {
-          const status = f.response_summary?.status ?? 0;
-          const key = `${f.severity}|${f.check}|${status}`;
-          const opKey = `${f.operation.method} ${f.operation.path}`;
-          let g = groups.get(key);
-          if (!g) {
-            g = { severity: f.severity, check: f.check, status, ops: new Set(), sample: f.message };
-            groups.set(key, g);
-          }
-          g.ops.add(opKey);
+        // ARV-18: dedup identical findings on the SAME op (multiple cases
+        // hitting the same gap) before printing. Spec-rollup above already
+        // handled the across-op clusters; this collapses the within-op
+        // duplicates so the human summary stays readable even when boundary
+        // mutations each trip the same status.
+        const seen = new Set<string>();
+        for (const f of activeFindings) {
+          const opKey = `${f.check}|${f.operation.method} ${f.operation.path}`;
+          if (rolledUpOps.has(opKey)) continue;
+          const dedupKey = `${f.severity}|${opKey}|${f.response_summary?.status ?? 0}|${f.message}`;
+          if (seen.has(dedupKey)) continue;
+          seen.add(dedupKey);
+          console.log(`  [${f.severity}] ${f.check} ${f.operation.method} ${f.operation.path} — ${f.message}`);
         }
-        for (const g of groups.values()) {
-          if (g.ops.size <= 1) {
-            const op = [...g.ops][0] ?? "(unknown op)";
-            console.log(`  [${g.severity}] ${g.check} ${op} — ${g.sample}`);
-          } else {
-            const stem = g.status > 0
-              ? `Status ${g.status} not declared / unexpected`
-              : g.sample.replace(/ for [A-Z]+ .+$/, "");
-            console.log(`  [${g.severity}] ${g.check} — ${stem} (${g.ops.size} operation${g.ops.size === 1 ? "" : "s"} affected; --verbose for per-op detail)`);
-          }
+      }
+
+      if (opts.showSuppressed && suppressedFindings.length > 0) {
+        console.log(`\nSuppressed (${suppressedFindings.length}, not counted in summary):`);
+        for (const f of suppressedFindings) {
+          const sb = f.suppressed_by!;
+          console.log(`  [${f.severity}] ${f.check} ${f.operation.method} ${f.operation.path} — ${f.message}`);
+          console.log(`         ↳ suppressed by ${sb.source}#${sb.rule_index}: ${sb.reason}`);
         }
       }
     }
     // Exit-code rule: 0 when no HIGH/CRITICAL findings, 1 otherwise. LOW/MEDIUM
     // findings are reported but don't gate CI by default — agents that want
     // strict gating can post-process the JSON envelope.
+    //
+    // ARV-308: --no-fail-on-findings / --advisory keeps exit 0 even with
+    // HIGH/CRITICAL findings, mirroring `zond run --no-fail-on-failures`, so
+    // an orchestrator can tell "found drift" (exit 0, findings in envelope)
+    // from "command failed" (exit 2). The stderr tail still names the count.
+    const advisory = opts.advisory === true || opts.failOnFindings === false;
+    // ARV-320: this used to skip on ndjson under the assumption that "stderr
+    // already carried the summary just above" — false for ndjson, which takes
+    // a separate branch that only ever writes "NDJSON report written to
+    // <path>" to stderr. Under `--report ndjson` + `set -e` in CI, that made
+    // exit 1 look unexplained (report-zond friction on the 2026-07-02 Stripe
+    // run: "this step will 'fail' silently with valid data sitting right
+    // there"). Always write the reason to stderr — it's stderr, not stdout,
+    // so ndjson's stdout-discipline (AC#5) is untouched.
+    if (result.high_or_critical > 0) {
+      const suffix = advisory
+        ? " — advisory mode, exiting 0 (findings are in the envelope)"
+        : " — exiting with code 1 (pass --no-fail-on-findings / --advisory to suppress, e.g. for advisory runs)";
+      process.stderr.write(
+        `zond: ${result.high_or_critical} HIGH/CRITICAL finding(s)${suffix}.\n`,
+      );
+    }
     if (ndjsonFd !== undefined) closeSync(ndjsonFd);
-    process.exit(result.high_or_critical > 0 ? 1 : 0);
+    removeNdjsonSigHandlers?.();
+    process.exit(result.high_or_critical > 0 && !advisory ? 1 : 0);
   } catch (err) {
     if (ndjsonFd !== undefined) {
       try { closeSync(ndjsonFd); } catch { /* fd may already be invalid */ }
     }
+    removeNdjsonSigHandlers?.();
     const msg = err instanceof Error ? err.message : String(err);
     if (json) printJson(jsonError("checks run", [msg]));
     else printError(msg);
@@ -677,7 +965,7 @@ function defineRun(parent: Command): void {
     .option("--api <name>", "Use the registered API's spec + .env.yaml")
     .option("--spec <path>", "Explicit OpenAPI spec path (overrides --api)")
     .option("--base-url <url>", "Base URL for requests (overrides --api env file)")
-    .option("--check <ids...>", "Only run these checks (comma-separated or repeated)")
+    .option("--check <ids...>", "Only run these checks (comma-separated or repeated). 'stateful' expands to the state-machine set: use_after_free, ensure_resource_availability, cross_call_references, idempotency_replay, pagination_invariants, lifecycle_transitions, cursor_boundary_fuzzing — NOT ignored_auth/open_cors_on_sensitive (run those by explicit id)")
     .option("--exclude-check <ids...>", "Skip these checks (comma-separated or repeated)")
     .option("--timeout <ms>", "Per-request timeout in ms", (v) => Number.parseInt(v, 10))
     .option("--db <path>", "SQLite path (for --api lookup)")
@@ -741,9 +1029,37 @@ function defineRun(parent: Command): void {
     )
     .option(
       "--max-requests <n>",
-      "ARV-227: hard cap on outbound HTTP requests for the whole run (per-response + stateful share the same budget). Once reached, remaining cases short-circuit with `max-requests-cap-reached` in summary.skipped_outcomes. Use to keep coverage runs against large specs (github, kubernetes) bounded.",
+      "ARV-227: hard cap on outbound HTTP requests for the whole run (per-response + stateful share the same budget). Once reached, remaining cases short-circuit with `max-requests-cap-reached` in summary.skipped_outcomes. Always wins over the --budget tier cap.",
+      (v) => Number.parseInt(v, 10),
+    )
+    .option(
+      "--max-ops <n>",
+      "ARV-342: cap this run to N operations (deterministic op-window). Pair with --skip-ops to sweep a large spec in bounded, resumable slices that each finish in a short budget. A window whose summary.operations < N is the last slice.",
+      (v) => Number.parseInt(v, 10),
+    )
+    .option(
+      "--skip-ops <n>",
+      "ARV-342: skip the first N operations (post-filter, deterministic order) before applying --max-ops. Resume token for windowed sweeps: skip 0, skip 50, skip 100, …",
       (v) => Number.parseInt(v, 10),
     )
+    .option(
+      "--budget <tier>",
+      "ARV-292: adaptive cap and stateful gating tier. `quick` (cap 50, skip stateful) → ~60-sec gate. `standard` (cap 500, all checks). `full` (uncapped). Omitted ⇒ legacy uncapped behaviour. --max-requests always overrides the tier cap; `--check stateful` opts back into stateful even under `quick`.",
+    )
+    .option(
+      "--show-suppressed",
+      "Show findings suppressed by the deterministic broken-baseline guard in the text summary (with their suppressed_by trace). Suppressed findings stay in the ndjson/JSON audit-trail regardless of this flag and never count toward CI exit codes.",
+    )
+    .option(
+      "--no-fail-on-findings",
+      "ARV-308: keep exit code 0 even when HIGH/CRITICAL findings exist (advisory runs). Mirrors `zond run --no-fail-on-failures`. Lets an orchestrator distinguish 'found drift' (exit 0) from 'command failed' (exit 2). Default: exit 1 on any HIGH/CRITICAL finding.",
+    )
+    .option(
+      "--advisory",
+      "ARV-308: alias for --no-fail-on-findings.",
+    )
+    .option("--safe", SAFE_HELP)
+    .option("--live", LIVE_HELP)
     .action(checksRunAction);
 }
 

package/src/cli/commands/cleanup.ts

@@ -9,6 +9,7 @@
  */
 import { loadOrphans, markRemoved } from "../../core/probe/orphan-tracker.ts";
 import type { OrphanRecord } from "../../core/probe/orphan-tracker.ts";
+import { encodePathForRepro } from "../../core/probe/shared.ts";
 import { executeRequest } from "../../core/runner/http-client.ts";
 import { loadEnvironment, loadEnvMeta } from "../../core/parser/variables.ts";
 import { resolveTimeoutMs } from "../../core/workspace/config.ts";
@@ -41,37 +42,10 @@ export interface CleanupOptions {
  * raw `\r`, `\n`, spaces, etc. (e.g. label name `zond-safe\rX-Zond: yes`),
  * which makes the DELETE URL malformed: the API gets a request line with an
  * embedded CR and silently splits or routes elsewhere → 404 → record stays
- * in the queue and the resource leaks.
- *
- * Encode unsafe characters per path-segment while preserving anything that
- * is already percent-encoded. Slashes (segment separators), the unreserved
- * set, and a conservative slice of sub-delims are kept verbatim.
+ * in the queue and the resource leaks. Encoding is shared with the
+ * security-probe digest via `core/probe/shared.ts#encodePathForRepro`.
  */
-export function encodeOrphanPath(deletePath: string): string {
-  const SAFE = /[A-Za-z0-9._~!$&'()*+,;=:@-]/;
-  return deletePath
-    .split("/")
-    .map((segment) => {
-      if (segment.length === 0) return segment;
-      let out = "";
-      for (let i = 0; i < segment.length; i++) {
-        const ch = segment.charAt(i);
-        // Preserve existing percent escapes (`%XX`) — probe pre-encoded.
-        if (ch === "%" && /^[0-9A-Fa-f]{2}$/.test(segment.slice(i + 1, i + 3))) {
-          out += segment.slice(i, i + 3);
-          i += 2;
-          continue;
-        }
-        if (SAFE.test(ch)) {
-          out += ch;
-        } else {
-          out += encodeURIComponent(ch);
-        }
-      }
-      return out;
-    })
-    .join("/");
-}
+export const encodeOrphanPath = encodePathForRepro;
 
 export async function cleanupCommand(opts: CleanupOptions): Promise<number> {
   if (!opts.orphans) {