@kirrosh/zond 0.22.0 → 0.26.0

package/src/cli/commands/audit.ts

@@ -0,0 +1,786 @@
+/**
+ * `zond audit --api X` — macro-команда для полного pipeline (TASK-262).
+ *
+ * Оборачивает 8-10 ручных шагов (prepare-fixtures → generate → probes
+ * → session-wrapped run → coverage → HTML report) в одну команду:
+ *
+ *   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` и
+ *      `security` — за `--with-mass-assignment` / `--with-security`.
+ *   4. `session start` → `run apis/<name>/tests` + `run apis/<name>/probes`
+ *      → `session end`. Все runs наследуют один session_id.
+ *   5. `coverage --api X --union session --json` для embed'a в репорт.
+ *   6. Запись `audit-report.html` (или `--out`) с таблицей stages,
+ *      coverage-сводкой и подсказками для drill-down.
+ *
+ * Каждая stage спавнится как отдельный subprocess `zond ...`. Failure
+ * любой stage НЕ останавливает pipeline — финальный exit 1 если хоть одна
+ * упала, 0 если все ok. `--dry-run` печатает план без выполнения.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import type { Command } from "commander";
+import { globalJson } from "../resolve.ts";
+import { getDb } from "../../db/schema.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;
+  name: string;
+  args: string[];
+  /** If returns string, stage is skipped with that reason. */
+  skip?: () => string | null;
+}
+
+interface StageResult {
+  key: string;
+  name: string;
+  status: "ok" | "failed" | "skipped";
+  exit_code: number | null;
+  duration_ms: number;
+  reason?: string;
+}
+
+export interface AuditOptions {
+  api: string;
+  dbPath?: string;
+  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;
+}
+
+/**
+ * Build the prefix for self-spawning `zond ...`. When the binary is
+ * compiled, `process.execPath` IS the zond binary. In dev, `bun` runs the
+ * script directly — fall back to `[bun, src/cli/index.ts]`.
+ */
+function zondInvoker(): string[] {
+  const exec = process.execPath;
+  const base = exec.replace(/\\/g, "/");
+  if (base.endsWith("/zond") || base.endsWith("/zond.exe")) return [exec];
+  const script = process.argv[1] || "src/cli/index.ts";
+  return [exec, script];
+}
+
+function buildStages(opts: AuditOptions, apiDir: string, specPath: string | null): Stage[] {
+  const api = opts.api;
+  const stages: Stage[] = [];
+  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",
+    name: "generate (smoke + crud)",
+    args: ["generate", "--api", api, "--output", join(apiDir, "tests")],
+    skip: () => {
+      if (opts.force) return null;
+      if (!specPath || !existsSync(specPath)) return null;
+      const testsDir = join(apiDir, "tests");
+      if (!existsSync(testsDir)) return null;
+      try {
+        const specMtime = statSync(specPath).mtimeMs;
+        const testsMtime = statSync(testsDir).mtimeMs;
+        if (testsMtime > specMtime) return "tests/ newer than spec — pass --force to regenerate";
+      } catch {
+        // ignore — fall through to running generate
+      }
+      return null;
+    },
+  });
+
+  stages.push({
+    key: "probe-static",
+    name: "probe static (validation+methods)",
+    args: ["probe", "static", "--api", api, "--output", join(apiDir, "probes", "static")],
+  });
+
+  // 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",
+      args: [
+        "probe", "mass-assignment", "--api", api,
+        "--output", join(apiDir, "probes", "mass-assignment-digest.md"),
+        "--emit-tests", join(apiDir, "probes", "mass-assignment"),
+        "--overwrite",
+        ...probeMaxEndpointsArgs,
+      ],
+    });
+  }
+  if (opts.withSecurity && liveProbesEnabled) {
+    stages.push({
+      key: "probe-security",
+      name: "probe security (ssrf,crlf,open-redirect)",
+      args: [
+        "probe", "security", "ssrf,crlf,open-redirect", "--api", api,
+        "--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)}`;
+  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.
+  stages.push({
+    key: "coverage",
+    name: "coverage (session union)",
+    args: ["coverage", "--api", api, "--union", "session", "--json"],
+  });
+
+  return stages;
+}
+
+async function runStage(stage: Stage, idx: number, total: number, json: boolean): Promise<StageResult> {
+  const skipReason = stage.skip?.();
+  if (skipReason) {
+    if (!json) console.log(`==> Stage ${idx}/${total}: ${stage.name} — skipped (${skipReason})`);
+    return { key: stage.key, name: stage.name, status: "skipped", exit_code: null, duration_ms: 0, reason: skipReason };
+  }
+  if (!json) console.log(`==> Stage ${idx}/${total}: ${stage.name}`);
+  const t0 = Date.now();
+  const cmd = [...zondInvoker(), ...stage.args];
+  const proc = Bun.spawn(cmd, { stdout: "inherit", stderr: "inherit" });
+  const code = await proc.exited;
+  const ms = Date.now() - t0;
+  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 {
+  data: unknown | null;
+  exitCode: number | null;
+  parseError: string | null;
+  durationMs: number;
+}
+
+/**
+ * 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(), ...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;
+    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 };
+  }
+}
+
+export async function auditCommand(options: AuditOptions): Promise<number> {
+  // Like bootstrap: fall back to apis/<name>/ when no DB/collection — the
+  // workspace-on-disk shape is enough for the macro to drive subprocesses.
+  let apiDir = `apis/${options.api}`;
+  let specPath: string | null = null;
+  try {
+    getDb(options.dbPath);
+    const col = findCollectionByNameOrId(options.api);
+    if (col) {
+      apiDir = col.base_dir ?? apiDir;
+      specPath = col.openapi_spec ? resolveCollectionSpec(col.openapi_spec) : null;
+    }
+  } catch {
+    // No DB — keep filesystem-only fallback.
+  }
+  if (!specPath) {
+    const guess = join(apiDir, "spec.json");
+    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";
+
+  if (options.dryRun) {
+    if (options.json) {
+      printJson(jsonOk("audit", {
+        plan: stages.map((s) => ({ key: s.key, name: s.name, args: s.args })),
+        out,
+      }));
+    } else {
+      console.log(`Plan: zond audit --api ${options.api} (${stages.length} stages)`);
+      stages.forEach((s, i) => {
+        console.log(`  ${(i + 1).toString().padStart(2)}. ${s.name}`);
+        console.log(`        zond ${s.args.join(" ")}`);
+      });
+      console.log(`\nReport will be written to: ${out}`);
+    }
+    return 0;
+  }
+
+  const t0 = Date.now();
+  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, pinnedSessionId);
+      coverageJson = coverageCapture.data;
+      const status: StageResult["status"] = coverageCapture.data
+        ? "ok"
+        : coverageCapture.exitCode === 0 && coverageCapture.parseError
+          ? "failed"
+          : coverageCapture.exitCode === 0
+            ? "skipped"
+            : "failed";
+      results.push({
+        key: stage.key,
+        name: stage.name,
+        status,
+        exit_code: coverageCapture.exitCode,
+        duration_ms: coverageCapture.durationMs,
+        reason: status === "skipped"
+          ? "no runs in session"
+          : coverageCapture.parseError
+            ? `non-JSON output: ${coverageCapture.parseError}`
+            : status === "failed"
+              ? `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,
+    stages: results,
+    totalMs,
+    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
+  // don't regress the "non-fatal coverage" contract.
+  const failedStages = results.filter((r) => r.status === "failed" && r.key !== "coverage");
+  const failed = failedStages.length;
+
+  if (options.json) {
+    printJson(jsonOk("audit", {
+      api: options.api,
+      stages: results,
+      total_ms: totalMs,
+      failed_stages: failed,
+      report: out,
+      coverage: coverageJson,
+    }));
+  } else {
+    console.log("");
+    // 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 {
+      printWarning(`${summary} — ${failed} failed: ${failedStages.map((s) => s.key).join(", ")}`);
+    }
+  }
+  return failed === 0 ? 0 : 1;
+}
+
+export interface ReportInput {
+  api: string;
+  apiDir: string;
+  stages: StageResult[];
+  totalMs: number;
+  coverage: unknown;
+  /** ARV-108: outcome of the post-stage coverage capture, so the HTML can
+   *  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 {
+  return s.replace(/[&<>"']/g, (c) => {
+    const map: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+    return map[c]!;
+  });
+}
+
+interface CoverageEnvelope {
+  data?: {
+    totals?: { all?: number; covered2xx?: number; coveredButNon2xx?: number; unhit?: number };
+    pass_coverage?: { ratio?: number };
+    hit_coverage?: { ratio?: number };
+    coveredButNon2xxEndpoints?: Array<{ endpoint?: string }>;
+    unhitEndpoints?: Array<{ endpoint?: string }>;
+  };
+}
+
+/** 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;
+  const hit = cov?.data?.hit_coverage?.ratio;
+
+  const stageRows = data.stages.map((s) => {
+    const cls = s.status === "ok" ? "ok" : s.status === "failed" ? "fail" : "skip";
+    const ms = s.duration_ms === 0 ? "—" : `${(s.duration_ms / 1000).toFixed(1)}s`;
+    return `<tr class="${cls}"><td>${escapeHtml(s.name)}</td><td>${s.status}</td><td>${s.exit_code ?? "—"}</td><td>${ms}</td><td>${escapeHtml(s.reason ?? "")}</td></tr>`;
+  }).join("\n");
+
+  const reruncmd = `zond audit --api ${data.api}`
+    + (data.options.withMassAssignment ? " --with-mass-assignment" : "")
+    + (data.options.withSecurity ? " --with-security" : "");
+
+  const covStage = data.coverageStage;
+  // ARV-108: tailor the warning to what actually happened so the HTML stops
+  // misreporting "stage failed" when the stage was skipped (no runs in the
+  // session) or simply produced unparseable output.
+  const coverageWarning = covStage
+    ? covStage.status === "skipped"
+      ? "No session runs to summarise. Add `--with-mass-assignment` / `--with-security`, or run tests/probes that succeed."
+      : covStage.reason
+        ? `Coverage stage ${covStage.status}: ${escapeHtml(covStage.reason)}.`
+        : `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">
+  <div><div class="num">${totals.covered2xx ?? 0}/${totals.all ?? 0}</div><div class="lbl">covered2xx</div></div>
+  <div><div class="num">${totals.coveredButNon2xx ?? 0}</div><div class="lbl">covered but non-2xx</div></div>
+  <div><div class="num">${totals.unhit ?? 0}</div><div class="lbl">unhit</div></div>
+  ${typeof pass === "number" ? `<div><div class="num">${(pass * 100).toFixed(0)}%</div><div class="lbl">pass coverage</div></div>` : ""}
+  ${typeof hit === "number" ? `<div><div class="num">${(hit * 100).toFixed(0)}%</div><div class="lbl">hit coverage</div></div>` : ""}
+</div>`
+    : `<h2>Coverage</h2><div class="warn">${coverageWarning}</div>`;
+
+  const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>zond audit — ${escapeHtml(data.api)}</title>
+<style>
+body { font: 14px -apple-system, system-ui, sans-serif; max-width: 960px; margin: 2em auto; padding: 0 1em; color: #222; }
+h1 { font-size: 1.4em; margin-bottom: 0.2em; }
+h2 { font-size: 1.05em; margin-top: 2em; border-bottom: 1px solid #eee; padding-bottom: 0.3em; }
+.meta { color: #666; font-size: 0.9em; margin-bottom: 1em; }
+table { border-collapse: collapse; width: 100%; margin: 1em 0; font-size: 0.92em; }
+th, td { text-align: left; padding: 6px 10px; border-bottom: 1px solid #eee; }
+th { background: #f7f7f7; }
+tr.ok td:nth-child(2) { color: #0a7; }
+tr.fail td:nth-child(2) { color: #c33; font-weight: 600; }
+tr.skip td:nth-child(2) { color: #888; font-style: italic; }
+.cov { display: flex; gap: 2em; margin: 1em 0; flex-wrap: wrap; }
+.cov .num { font-size: 1.6em; font-weight: 600; }
+.cov .lbl { font-size: 0.8em; color: #666; }
+.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>
+<div class="meta">
+  zond ${escapeHtml(VERSION)} · ${new Date().toISOString()} · total ${(data.totalMs / 1000).toFixed(1)}s · apiDir <code>${escapeHtml(data.apiDir)}</code>
+</div>
+
+<h2>Stages</h2>
+<table><thead><tr><th>Stage</th><th>Status</th><th>Exit</th><th>Duration</th><th>Note</th></tr></thead><tbody>
+${stageRows}
+</tbody></table>
+
+${coverageBlock}
+
+${drilldownBlocks}
+
+<h2>Drill-down</h2>
+<ul>
+  <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("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
+    // requiredOption rejects every form (`--api foo`, `--api=foo`, even
+    // `zond --api foo audit`). Fall back the same way: explicit > program-level
+    // 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("--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);
+      if (!apiName) {
+        printError(MISSING_API_MESSAGE);
+        process.exitCode = 2;
+        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,
+        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,
+      });
+    });
+}