@kirrosh/zond 0.23.0 → 0.26.0

package/src/cli/commands/audit.ts

@@ -4,8 +4,8 @@
  * Оборачивает 8-10 ручных шагов (prepare-fixtures → generate → probes
  * → session-wrapped run → coverage → HTML report) в одну команду:
  *
- *   1. `prepare-fixtures --apply` (или `--cascade --seed --apply` при
- *      `--seed`) — заполняет `.env.yaml` FK-идентификаторами.
+ *   1. `prepare-fixtures --apply` — single-pass, заполняет `.env.yaml`
+ *      FK-идентификаторами, что нашлись детерминированно.
  *   2. `generate` — пропускается если `apis/<name>/tests/` свежее, чем
  *      `spec.json` (mtime-эвристика; `--force` отключает skip).
  *   3. `probe static` (validation+methods, всегда). `mass-assignment` и
@@ -23,16 +23,19 @@
 
 import { existsSync, statSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import type { Command } from "commander";
 import { globalJson } from "../resolve.ts";
 import { getDb } from "../../db/schema.ts";
-import { findCollectionByNameOrId } from "../../db/queries.ts";
+import { findCollectionByNameOrId, listSessions, listRunsBySession } from "../../db/queries.ts";
 import { resolveCollectionSpec } from "../../core/setup-api.ts";
 import { printSuccess, printWarning, printError } from "../output.ts";
 import { getApi, MISSING_API_MESSAGE } from "../util/api-context.ts";
 import { jsonOk, printJson } from "../json-envelope.ts";
 import { VERSION } from "../version.ts";
+import { diagnoseRun, type DiagnoseResult } from "../../core/diagnostics/db-analysis.ts";
+import { readCurrentSession } from "../../core/context/session.ts";
+import { resolveBudget, isBudget, BUDGETS, type Budget } from "../../core/checks/budget.ts";
 
 interface Stage {
   key: string;
@@ -54,13 +57,19 @@ interface StageResult {
 export interface AuditOptions {
   api: string;
   dbPath?: string;
-  seed?: boolean;
   withMassAssignment?: boolean;
   withSecurity?: boolean;
   out?: string;
   dryRun?: boolean;
   force?: boolean;
   json?: boolean;
+  /** ARV-264: opt-in to the full pipeline against a real-traffic API.
+   *  When false (default), audit runs in safe mode — no mass-assignment /
+   *  security probes, no destructive probes. */
+  live?: boolean;
+  /** ARV-292: adaptive cap and stateful gating tier. Translates to
+   *  `--max-requests N` on every spawned `run` stage. */
+  budget?: Budget;
 }
 
 /**
@@ -79,20 +88,34 @@ function zondInvoker(): string[] {
 function buildStages(opts: AuditOptions, apiDir: string, specPath: string | null): Stage[] {
   const api = opts.api;
   const stages: Stage[] = [];
-
-  if (opts.seed) {
-    stages.push({
-      key: "prepare-fixtures-cascade",
-      name: "prepare-fixtures (cascade discover + seed)",
-      args: ["prepare-fixtures", "--api", api, "--apply", "--seed"],
-    });
-  } else {
-    stages.push({
-      key: "prepare-fixtures",
-      name: "prepare-fixtures (path-FK fixtures)",
-      args: ["prepare-fixtures", "--api", api, "--apply"],
-    });
-  }
+  const budgetResolved = resolveBudget(opts.budget, undefined);
+  const runMaxRequestsArgs: string[] = budgetResolved.maxRequests !== undefined
+    ? ["--max-requests", String(budgetResolved.maxRequests)]
+    // placeholder to keep the binding shape stable
+    : [];
+  // ARV-302: probes don't share `zond run`'s --max-requests vocabulary
+  // (probes scan endpoint-by-endpoint, not request-by-request). Map the
+  // budget tier to a coarse `--max-endpoints` cap so probe stages stay
+  // inside the same wall-clock budget. `full` keeps the legacy
+  // uncapped behaviour.
+  const probeMaxEndpointsByTier: Record<string, number | undefined> = {
+    quick: 10,
+    standard: 50,
+    full: undefined,
+  };
+  const probeMaxEndpoints = opts.budget ? probeMaxEndpointsByTier[opts.budget] : undefined;
+  const probeMaxEndpointsArgs: string[] = probeMaxEndpoints !== undefined
+    ? ["--max-endpoints", String(probeMaxEndpoints)]
+    : [];
+
+  // ARV-336: prep is always a single-pass `prepare-fixtures --apply`. It
+  // fills what discover resolves deterministically and reports the rest as
+  // gaps for the agent/user to fill by hand — no autonomous seed/cascade.
+  stages.push({
+    key: "prepare-fixtures",
+    name: "prepare-fixtures (path-FK fixtures)",
+    args: ["prepare-fixtures", "--api", api, "--apply"],
+  });
 
   stages.push({
     key: "generate",
@@ -120,7 +143,11 @@ function buildStages(opts: AuditOptions, apiDir: string, specPath: string | null
     args: ["probe", "static", "--api", api, "--output", join(apiDir, "probes", "static")],
   });
 
-  if (opts.withMassAssignment) {
+  // ARV-264: mass-assignment + security probes send real POST/PUT/DELETE
+  // traffic. Gate them behind --live so the default (safe) audit can't
+  // pollute a production API.
+  const liveProbesEnabled = opts.live === true;
+  if (opts.withMassAssignment && liveProbesEnabled) {
     stages.push({
       key: "probe-mass-assignment",
       name: "probe mass-assignment",
@@ -129,10 +156,11 @@ function buildStages(opts: AuditOptions, apiDir: string, specPath: string | null
         "--output", join(apiDir, "probes", "mass-assignment-digest.md"),
         "--emit-tests", join(apiDir, "probes", "mass-assignment"),
         "--overwrite",
+        ...probeMaxEndpointsArgs,
       ],
     });
   }
-  if (opts.withSecurity) {
+  if (opts.withSecurity && liveProbesEnabled) {
     stages.push({
       key: "probe-security",
       name: "probe security (ssrf,crlf,open-redirect)",
@@ -141,15 +169,39 @@ function buildStages(opts: AuditOptions, apiDir: string, specPath: string | null
         "--output", join(apiDir, "probes", "security-digest.md"),
         "--emit-tests", join(apiDir, "probes", "security"),
         "--overwrite",
+        ...probeMaxEndpointsArgs,
       ],
     });
   }
 
+  // ARV-65: if the user already has an active session, REUSE it — don't
+  // clobber their .zond/current-session by spawning audit's own. Skipping
+  // session-end is the critical half: otherwise audit clears the user's
+  // session even when start was a no-op.
+  const existingSession = readCurrentSession();
   const sessionLabel = `audit-${new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)}`;
-  stages.push({ key: "session-start", name: `session start (${sessionLabel})`, args: ["session", "start", "--label", sessionLabel] });
-  stages.push({ key: "run-tests", name: "run tests", args: ["run", join(apiDir, "tests"), "--api", api] });
-  stages.push({ key: "run-probes", name: "run probes", args: ["run", join(apiDir, "probes"), "--api", api] });
-  stages.push({ key: "session-end", name: "session end", args: ["session", "end"] });
+  if (existingSession) {
+    const reuseReason = `reusing active session ${existingSession.id}${existingSession.label ? ` (${existingSession.label})` : ""}`;
+    stages.push({
+      key: "session-start",
+      name: "session start (reused)",
+      args: ["session", "start", "--label", sessionLabel],
+      skip: () => reuseReason,
+    });
+    stages.push({ key: "run-tests", name: "run tests", args: ["run", join(apiDir, "tests"), "--api", api, ...runMaxRequestsArgs] });
+    stages.push({ key: "run-probes", name: "run probes", args: ["run", join(apiDir, "probes"), "--api", api, ...runMaxRequestsArgs] });
+    stages.push({
+      key: "session-end",
+      name: "session end (reused — kept active)",
+      args: ["session", "end"],
+      skip: () => reuseReason,
+    });
+  } else {
+    stages.push({ key: "session-start", name: `session start (${sessionLabel})`, args: ["session", "start", "--label", sessionLabel] });
+    stages.push({ key: "run-tests", name: "run tests", args: ["run", join(apiDir, "tests"), "--api", api, ...runMaxRequestsArgs] });
+    stages.push({ key: "run-probes", name: "run probes", args: ["run", join(apiDir, "probes"), "--api", api, ...runMaxRequestsArgs] });
+    stages.push({ key: "session-end", name: "session end", args: ["session", "end"] });
+  }
   // ARV-108: surface the post-stage coverage capture in the plan so the
   // dry-run listing matches the actual pipeline. The stage is special-cased
   // in auditCommand — we keep stdout for JSON parsing rather than inheriting.
@@ -174,13 +226,15 @@ async function runStage(stage: Stage, idx: number, total: number, json: boolean)
   const proc = Bun.spawn(cmd, { stdout: "inherit", stderr: "inherit" });
   const code = await proc.exited;
   const ms = Date.now() - t0;
-  return {
-    key: stage.key,
-    name: stage.name,
-    status: code === 0 ? "ok" : "failed",
-    exit_code: code,
-    duration_ms: ms,
-  };
+  const status: StageResult["status"] = code === 0 ? "ok" : "failed";
+  // ARV-66: print a per-stage completion line so the user sees OK/FAIL inline
+  // next to "Stage N/M" instead of inferring from the final summary. Subprocess
+  // stdio is inherited above, so this line lands AFTER the stage's own output.
+  if (!json) {
+    const tag = status === "ok" ? "OK" : `FAIL (exit ${code})`;
+    console.log(`    └─ ${tag} · ${(ms / 1000).toFixed(1)}s`);
+  }
+  return { key: stage.key, name: stage.name, status, exit_code: code, duration_ms: ms };
 }
 
 interface CoverageCapture {
@@ -190,22 +244,63 @@ interface CoverageCapture {
   durationMs: number;
 }
 
-async function captureCoverage(api: string): Promise<CoverageCapture> {
+/**
+ * ARV-301: build the coverage-stage CLI args. Exported so unit tests
+ * can assert that audit pins `--session-id <id>` rather than
+ * `--union session` whenever a session id was captured ahead of
+ * `session end` (the latter selector rejects closed sessions).
+ */
+export function buildCoverageStageArgs(api: string, sessionId?: string): string[] {
+  const sel = sessionId ? ["--session-id", sessionId] : ["--union", "session"];
+  return ["coverage", "--api", api, ...sel, "--json"];
+}
+
+/**
+ * ARV-301 follow-up: judge audit's coverage stage on the JSON envelope's
+ * `ok` field, not the subprocess exit code.
+ *
+ * `zond coverage` exits 1 when there are uncovered endpoints (legacy
+ * CI-gate behaviour) — that is a normal report state for audit's
+ * purposes, the envelope is well-formed and carries valid coverage
+ * data. Only exit 2 / non-JSON output / `ok:false` envelopes mean a
+ * real coverage failure.
+ *
+ * Exported pure function so unit tests can lock the contract without
+ * spawning a subprocess.
+ */
+export function interpretCoverageOutput(
+  stdout: string,
+  exitCode: number | null,
+): { data: unknown | null; parseError: string | null } {
+  let parsed: unknown = null;
+  let parseError: string | null = null;
+  try {
+    parsed = stdout.trim() ? JSON.parse(stdout) : null;
+  } catch (e) {
+    parseError = (e as Error).message;
+  }
+  if (parsed && typeof parsed === "object" && (parsed as { ok?: boolean }).ok === true) {
+    // Envelope says everything is fine; treat coverage as captured
+    // even if exit was 1 due to "has uncovered endpoints".
+    return { data: parsed, parseError: null };
+  }
+  // ok:false, or no envelope at all — propagate the failure signal.
+  // exitCode is intentionally not consulted here; callers attach it
+  // to the stage result for the user.
+  void exitCode;
+  return { data: null, parseError };
+}
+
+async function captureCoverage(api: string, sessionId?: string): Promise<CoverageCapture> {
   const t0 = Date.now();
   try {
-    const cmd = [...zondInvoker(), "coverage", "--api", api, "--union", "session", "--json"];
+    const cmd = [...zondInvoker(), ...buildCoverageStageArgs(api, sessionId)];
     const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
     const stdout = await new Response(proc.stdout).text();
     const code = await proc.exited;
     const ms = Date.now() - t0;
-    if (code !== 0) {
-      return { data: null, exitCode: code, parseError: null, durationMs: ms };
-    }
-    try {
-      return { data: JSON.parse(stdout), exitCode: code, parseError: null, durationMs: ms };
-    } catch (e) {
-      return { data: null, exitCode: code, parseError: (e as Error).message, durationMs: ms };
-    }
+    const { data, parseError } = interpretCoverageOutput(stdout, code);
+    return { data, exitCode: code, parseError, durationMs: ms };
   } catch (e) {
     return { data: null, exitCode: null, parseError: (e as Error).message, durationMs: Date.now() - t0 };
   }
@@ -231,6 +326,13 @@ export async function auditCommand(options: AuditOptions): Promise<number> {
     if (existsSync(guess)) specPath = guess;
   }
 
+  // ARV-264: surface what safe mode silently drops and run pre-flight
+  // checks (auth + security schemes) before any subprocess fires.
+  const preflightWarnings = runSafePreflight(options, specPath, apiDir);
+  if (!options.json) {
+    for (const w of preflightWarnings) printWarning(w);
+  }
+
   const stages = buildStages(options, apiDir, specPath);
   const out = options.out ?? "audit-report.html";
 
@@ -255,12 +357,19 @@ export async function auditCommand(options: AuditOptions): Promise<number> {
   const results: StageResult[] = [];
   let coverageJson: unknown = null;
   let coverageCapture: CoverageCapture | null = null;
+  // ARV-301: capture the active session id BEFORE session-end runs, so
+  // coverage can target it explicitly (--session-id) instead of via
+  // --union session, which would reject the now-closed session.
+  let pinnedSessionId: string | undefined;
   for (let i = 0; i < stages.length; i++) {
     const stage = stages[i]!;
+    if (stage.key === "session-end" && !pinnedSessionId) {
+      pinnedSessionId = readCurrentSession()?.id;
+    }
     if (stage.key === "coverage") {
       // ARV-108: coverage runs via captureCoverage so we keep stdout JSON.
       if (!options.json) console.log(`==> Stage ${i + 1}/${stages.length}: ${stage.name}`);
-      coverageCapture = await captureCoverage(options.api);
+      coverageCapture = await captureCoverage(options.api, pinnedSessionId);
       coverageJson = coverageCapture.data;
       const status: StageResult["status"] = coverageCapture.data
         ? "ok"
@@ -283,12 +392,48 @@ export async function auditCommand(options: AuditOptions): Promise<number> {
               ? `coverage exited ${coverageCapture.exitCode}`
               : undefined,
       });
+      // ARV-66: per-stage completion line for the coverage special-case too.
+      if (!options.json) {
+        const tag = status === "ok" ? "OK" : status === "skipped" ? "SKIPPED" : `FAIL (exit ${coverageCapture.exitCode})`;
+        console.log(`    └─ ${tag} · ${(coverageCapture.durationMs / 1000).toFixed(1)}s`);
+      }
       continue;
     }
     results.push(await runStage(stage, i + 1, stages.length, options.json === true));
   }
   const totalMs = Date.now() - t0;
 
+  // ARV-158: collect per-run drill-down from the audit session so the HTML
+  // can answer "WHICH 271 findings" instead of just "3 failed stages".
+  // The session was started by `session-start` and closed by `session-end`,
+  // so it's the most recent session in the DB at this point. listSessions(1)
+  // surfaces it; we then diagnose each run with failures > 0 (passed-only
+  // runs need no triage).
+  const drilldown: Array<{ run: { id: number; failed: number; total: number; passed: number }; diagnose: DiagnoseResult }> = [];
+  try {
+    const recent = listSessions(1);
+    const session = recent[0];
+    if (session?.session_id) {
+      const runs = listRunsBySession(session.session_id);
+      for (const r of runs) {
+        if (r.failed <= 0) continue;
+        try {
+          const diag = diagnoseRun(r.id, false, options.dbPath);
+          drilldown.push({
+            run: { id: r.id, failed: r.failed, total: r.total, passed: r.passed },
+            diagnose: diag,
+          });
+        } catch {
+          // diagnose of a single run failing should not break the report —
+          // skip and keep the rest.
+        }
+      }
+    }
+  } catch {
+    // DB unreachable / no sessions — leave drilldown empty; HTML degrades
+    // to the previous summary-only form.
+  }
+
   await writeAuditReport(out, {
     api: options.api,
     apiDir,
@@ -297,6 +442,7 @@ export async function auditCommand(options: AuditOptions): Promise<number> {
     coverage: coverageJson,
     coverageStage: results.find((r) => r.key === "coverage") ?? null,
     options,
+    drilldown,
   });
 
   // ARV-108: coverage is informational — keep it out of the fail count so we
@@ -315,7 +461,10 @@ export async function auditCommand(options: AuditOptions): Promise<number> {
     }));
   } else {
     console.log("");
-    const summary = `Audit complete (${results.length} stages, ${(totalMs / 1000).toFixed(1)}s) → ${out}`;
+    // ARV-80: print absolute path so the user can open the HTML report
+    // without traversing — `audit-report.html` (relative) hid the location
+    // behind cwd, especially when audit was invoked from a parent dir.
+    const summary = `Audit complete (${results.length} stages, ${(totalMs / 1000).toFixed(1)}s) → ${resolve(out)}`;
     if (failed === 0) {
       printSuccess(summary);
     } else {
@@ -325,7 +474,7 @@ export async function auditCommand(options: AuditOptions): Promise<number> {
   return failed === 0 ? 0 : 1;
 }
 
-interface ReportInput {
+export interface ReportInput {
   api: string;
   apiDir: string;
   stages: StageResult[];
@@ -335,6 +484,15 @@ interface ReportInput {
    *  distinguish "no session runs" from "coverage subcommand failed". */
   coverageStage: StageResult | null;
   options: AuditOptions;
+  /** ARV-158: per-run diagnose envelopes for runs in this audit's session
+   *  that had failures. Each entry feeds a collapsible drill-down block
+   *  in the HTML so the report answers "WHICH findings" inline. Empty
+   *  array when no runs failed or when DB lookup couldn't reach the
+   *  session. */
+  drilldown: Array<{
+    run: { id: number; failed: number; total: number; passed: number };
+    diagnose: DiagnoseResult;
+  }>;
 }
 
 function escapeHtml(s: string): string {
@@ -354,7 +512,10 @@ interface CoverageEnvelope {
   };
 }
 
-async function writeAuditReport(outPath: string, data: ReportInput): Promise<void> {
+/** ARV-158: exported for regression-test on HTML markup (drill-down
+ *  sections per failed run). Same signature as before — the export
+ *  doesn't expose anything CLI-internal. */
+export async function writeAuditReport(outPath: string, data: ReportInput): Promise<void> {
   const cov = data.coverage as CoverageEnvelope | null;
   const totals = cov?.data?.totals;
   const pass = cov?.data?.pass_coverage?.ratio;
@@ -367,7 +528,6 @@ async function writeAuditReport(outPath: string, data: ReportInput): Promise<voi
   }).join("\n");
 
   const reruncmd = `zond audit --api ${data.api}`
-    + (data.options.seed ? " --seed" : "")
     + (data.options.withMassAssignment ? " --with-mass-assignment" : "")
     + (data.options.withSecurity ? " --with-security" : "");
 
@@ -383,6 +543,59 @@ async function writeAuditReport(outPath: string, data: ReportInput): Promise<voi
         : `Coverage stage ${covStage.status} (exit ${covStage.exit_code ?? "?"}).`
     : "Coverage stage was not part of this audit (older binary?).";
 
+  // ARV-158: per-run drill-down — collapsible sections, one per failed
+  // run, surfacing by_recommended_action buckets (count + first example).
+  // Concrete commands replace the previous "type <run-id> manually" hint.
+  const drilldownBlocks = data.drilldown.length === 0
+    ? ""
+    : `<h2>Failures by run</h2>\n` + data.drilldown.map(({ run, diagnose }) => {
+        const buckets = diagnose.by_recommended_action ?? {};
+        // Sort buckets by priority (report_backend_bug first, then by count)
+        // — matches the zond-triage skill priority order.
+        const priorityOrder = [
+          "report_backend_bug",
+          "fix_spec",
+          "fix_auth_config",
+          "fix_env",
+          "fix_fixture",
+          "fix_network_config",
+          "regenerate_suite",
+          "tighten_validation",
+          "add_required_header",
+          "fix_test_logic",
+          "wontfix_known_limitation",
+        ];
+        const sortedKeys = Object.keys(buckets).sort((a, b) => {
+          const ai = priorityOrder.indexOf(a);
+          const bi = priorityOrder.indexOf(b);
+          if (ai === -1 && bi === -1) return (buckets[b]!.count) - (buckets[a]!.count);
+          if (ai === -1) return 1;
+          if (bi === -1) return -1;
+          return ai - bi;
+        });
+        const bucketsHtml = sortedKeys.length === 0
+          ? `<p class="muted">No <code>recommended_action</code> buckets — see raw failures via the commands below.</p>`
+          : `<ul class="buckets">` + sortedKeys.map((key) => {
+              const b = buckets[key]!;
+              const first = b.examples[0];
+              const sample = first
+                ? `<code>${escapeHtml(first.method)} ${escapeHtml(first.path)}</code> → <strong>${first.status}</strong>${first.reason ? ` — ${escapeHtml(first.reason)}` : ""}`
+                : "";
+              const moreExamples = b.examples.length > 1
+                ? ` <span class="muted">(+${b.examples.length - 1} more)</span>`
+                : "";
+              return `<li><strong>${escapeHtml(key)}</strong> ×${b.count}${sample ? ` — ${sample}${moreExamples}` : ""}</li>`;
+            }).join("\n") + `</ul>`;
+        return `<details>
+  <summary>Run #${run.id} — ${run.failed}/${run.total} failed (${run.passed} passed)</summary>
+  ${bucketsHtml}
+  <p class="cmds">
+    Drill in: <code>zond db diagnose --run-id ${run.id} --json</code> ·
+    <code>zond report export ${run.id}</code>
+  </p>
+</details>`;
+      }).join("\n");
+
   const coverageBlock = totals
     ? `<h2>Coverage (session union)</h2>
 <div class="cov">
@@ -413,6 +626,13 @@ tr.skip td:nth-child(2) { color: #888; font-style: italic; }
 .warn { background: #fef9e7; padding: 8px 12px; border-left: 3px solid #f0c040; margin: 1em 0; }
 code { background: #f4f4f4; padding: 1px 5px; border-radius: 3px; font-size: 0.9em; }
 ul { line-height: 1.6; }
+details { margin: 0.8em 0; border: 1px solid #eee; border-radius: 4px; padding: 0.3em 0.8em; }
+details summary { cursor: pointer; font-weight: 600; padding: 0.3em 0; }
+details[open] summary { border-bottom: 1px solid #eee; margin-bottom: 0.6em; }
+ul.buckets { padding-left: 1.2em; margin: 0.4em 0; }
+ul.buckets li { margin: 0.25em 0; }
+p.cmds { font-size: 0.88em; color: #555; margin-top: 0.8em; }
+.muted { color: #888; }
 </style></head>
 <body>
 <h1>zond audit — ${escapeHtml(data.api)}</h1>
@@ -427,21 +647,93 @@ ${stageRows}
 
 ${coverageBlock}
 
+${drilldownBlocks}
+
 <h2>Drill-down</h2>
 <ul>
-  <li>Per-run HTML: <code>zond report export &lt;run-id&gt;</code></li>
-  <li>Diagnose failures: <code>zond db diagnose &lt;run-id&gt; --json</code></li>
   <li>Re-run audit: <code>${escapeHtml(reruncmd)}</code></li>
+  <li>List recent runs: <code>zond db runs --limit 20</code></li>
+  <li>Per-run report: <code>zond report export &lt;run-id&gt;</code></li>
 </ul>
 </body></html>`;
 
   await writeFile(outPath, html, "utf-8");
 }
 
+/**
+ * ARV-264: pre-flight checks for safe-mode auditing.
+ *
+ *  1. Warn when the user passed `--seed` / `--with-mass-assignment` /
+ *     `--with-security` without `--live` — those stages are silently
+ *     dropped in safe mode and the user deserves to know.
+ *  2. Warn when the spec declares `components.securitySchemes` but the
+ *     workspace has no `auth_token` set — every probe will skip with
+ *     401 and the report will read as "all green" misleadingly.
+ *  3. Warn when no security schemes are declared at all (open API or
+ *     incomplete spec) — same misleading-green risk on auth gates.
+ */
+export function runSafePreflight(
+  opts: AuditOptions,
+  specPath: string | null,
+  apiDir: string,
+): string[] {
+  const out: string[] = [];
+  const safe = opts.live !== true;
+
+  if (safe) {
+    if (opts.withMassAssignment) {
+      out.push(
+        "audit --safe (default): --with-mass-assignment ignored. Mass-assignment probes POST mutated " +
+        "bodies and follow up with GET/DELETE — high blast radius. Re-run with --live to enable.",
+      );
+    }
+    if (opts.withSecurity) {
+      out.push(
+        "audit --safe (default): --with-security ignored. Security probes send live SSRF/CRLF/redirect " +
+        "payloads to real endpoints. Re-run with --live to enable.",
+      );
+    }
+  }
+
+  // Spec-level checks (cheap synchronous read; spec.json is JSON).
+  if (specPath && existsSync(specPath)) {
+    try {
+      const spec = JSON.parse(require("node:fs").readFileSync(specPath, "utf-8")) as {
+        components?: { securitySchemes?: Record<string, unknown> };
+      };
+      const hasSchemes = Boolean(
+        spec.components?.securitySchemes && Object.keys(spec.components.securitySchemes).length > 0,
+      );
+      const envPath = join(apiDir, ".env.yaml");
+      let authTokenSet = false;
+      if (existsSync(envPath)) {
+        const env = require("node:fs").readFileSync(envPath, "utf-8") as string;
+        // Match `auth_token: ...` lines whose value isn't an unfilled placeholder.
+        authTokenSet = /^\s*auth_token\s*:\s*(?!["']?\s*(<|UNSET|TODO|REPLACE|null|~)\b)\S/m.test(env);
+      }
+      if (hasSchemes && !authTokenSet) {
+        out.push(
+          "spec declares securitySchemes but auth_token is unset in .env.yaml — probes will likely hit " +
+          "401/403 and the report can read misleadingly green. Run `zond doctor --api " + opts.api + "` to fix.",
+        );
+      } else if (!hasSchemes) {
+        out.push(
+          "spec declares no securitySchemes — either the API is open or the spec is incomplete. " +
+          "Auth-related checks (ignored_auth, open_cors_on_sensitive) will skip; verify before sharing the report.",
+        );
+      }
+    } catch {
+      // Spec unreadable — separate failure mode, surfaced by other stages.
+    }
+  }
+
+  return out;
+}
+
 export function registerAudit(program: Command): void {
   program
     .command("audit")
-    .description("Macro: prepare-fixtures → generate → probes → run → coverage → HTML report (TASK-262)")
+    .description("Smoke + breadth-coverage macro: prepare-fixtures → generate → probe static → session-wrapped run → coverage → HTML report. For depth-checks / security probes / stateful invariants, drive the `zond` skill — `audit` is the breadth pass, depth is the skill's job.")
     // ARV-29: not `requiredOption` — same regression that hit prepare-fixtures
     // (TASK-20) and checks run (TASK-17). Commander routes `--api` to the
     // program-level option, so the subcommand's opts.api ends up undefined and
@@ -450,12 +742,16 @@ export function registerAudit(program: Command): void {
     // mirror > .zond/current-api.
     .option("--api <name>", "Registered API to audit. Falls back to ZOND_API / .zond/current-api.")
     .option("--db <path>", "Path to SQLite database file")
-    .option("--seed", "Use 'prepare-fixtures --cascade --seed --apply' instead of the plain single-pass prep stage")
-    .option("--with-mass-assignment", "Include 'probe mass-assignment' as an extra stage")
-    .option("--with-security", "Include 'probe security ssrf,crlf,open-redirect' as an extra stage")
+    .option("--with-mass-assignment", "Include 'probe mass-assignment' as an extra stage. Requires --live.")
+    .option("--with-security", "Include 'probe security ssrf,crlf,open-redirect' as an extra stage. Requires --live.")
+    .option("--live", "ARV-264: opt into the full pipeline against a real-traffic API. Without this flag, audit runs in safe mode: no mass-assignment / security probes, no destructive traffic. Use only against throwaway/sandbox accounts.")
     .option("--out <path>", "HTML report output path (default: audit-report.html)")
     .option("--dry-run", "Print the stage plan without executing anything")
     .option("--force", "Disable mtime-based skip (always regenerate, even if tests/ newer than spec)")
+    .option(
+      "--budget <tier>",
+      "ARV-292: adaptive request cap for spawned `run` stages. `quick` (50 req, ~60-sec gate), `standard` (500 req), `full` (uncapped). Omitted ⇒ legacy uncapped pipeline.",
+    )
     .action(async (opts, cmd: Command) => {
       // ARV-53.
       const apiName = getApi(cmd, opts);
@@ -465,16 +761,26 @@ export function registerAudit(program: Command): void {
         return;
       }
       opts.api = apiName;
+      let budget: Budget | undefined;
+      if (opts.budget !== undefined) {
+        if (!isBudget(opts.budget)) {
+          printError(`--budget must be one of: ${BUDGETS.join(", ")}; got '${opts.budget}'`);
+          process.exitCode = 2;
+          return;
+        }
+        budget = opts.budget;
+      }
       process.exitCode = await auditCommand({
         api: opts.api,
         dbPath: opts.db,
-        seed: opts.seed === true,
         withMassAssignment: opts.withMassAssignment === true,
         withSecurity: opts.withSecurity === true,
         out: opts.out,
         dryRun: opts.dryRun === true,
         force: opts.force === true,
         json: globalJson(cmd),
+        live: opts.live === true,
+        budget,
       });
     });
 }

package/src/cli/commands/check.ts

@@ -303,6 +303,10 @@ function defineCheckSpec(parent: Command, name: string): void {
     .option("--api <name>", "Use the registered API's spec (apis/<name>/spec.json)")
     .option("--strict", "Exit non-zero even on LOW-severity issues")
     .option("--ndjson", "Stream issues as one JSON per line (NDJSON), instead of the wrapped envelope")
+    .option(
+      "--report <format>",
+      "ARV-204: output format alias for parity with `checks run`. Accepts: console (default human summary), json (equivalent to --json envelope), ndjson (equivalent to --ndjson). Last writer wins if combined with --json/--ndjson.",
+    )
     .option(
       "--rule <list>",
       "Unified rule selector (TASK-291). Comma-separated items: 'B1' (whitelist), " +
@@ -329,10 +333,19 @@ function defineCheckSpec(parent: Command, name: string): void {
 
       const merged = mergeRuleFlags(opts.rule, opts.filterRule);
 
+      // ARV-204: --report ndjson|json|console aliases the existing booleans
+      // so scripts can keep one flag shape across `checks run` and `check spec`.
+      let report = typeof opts.report === "string" ? opts.report.toLowerCase() : undefined;
+      if (report && !["console", "json", "ndjson"].includes(report)) {
+        printError(`--report: unknown format '${opts.report}'. Use one of: console, json, ndjson.`);
+        process.exitCode = 2;
+        return;
+      }
+
       process.exitCode = await checkSpecCommand({
         specPath: resolved.spec,
-        json: globalJson(cmd),
-        ndjson: opts.ndjson === true,
+        json: globalJson(cmd) || report === "json",
+        ndjson: opts.ndjson === true || report === "ndjson",
         strict: opts.strict === true,
         rule: merged.cliRule,
         config: opts.config,