@kirrosh/zond 0.23.0 → 0.26.0

package/src/cli/commands/probe/_seed-bodies.ts

@@ -0,0 +1,52 @@
+/**
+ * ARV-269: shared loader for agent-authored `seed_body` overlays.
+ *
+ * Stateful checks already consume `.api-resources.local.yaml::seed_body`
+ * via `resolveCreateBody` (`core/checks/checks/_crud-helpers.ts`). Before
+ * ARV-269 the live probes (mass-assignment, security) did not — every
+ * baseline POST fell back to `generateFromSchema`, which strict APIs like
+ * Stripe v1 routinely reject as 400 with `INCONCLUSIVE-baseline`. The
+ * agent-authored overlay (ARV-187 pipeline) silently lost half its ROI.
+ *
+ * This helper builds the `Map<"METHOD path", SeedBodyConfig>` the probe
+ * runners consume. It's a CLI-layer helper because it crosses into
+ * `cli/commands/discover.ts` (the resource-map loader); keeping it under
+ * `core/probe` would inject a CLI dependency into the runtime.
+ */
+import { resolveApiCollection } from "../../resolve.ts";
+import { readResourceMap } from "../discover.ts";
+import type { SeedBodyConfig } from "../../../core/generator/resources-builder.ts";
+
+/** Parse the "METHOD /path" labels used in `.api-resources.yaml`. */
+function parseLabel(label: string): { method: string; path: string } | null {
+  const parts = label.trim().split(/\s+/);
+  if (parts.length < 2) return null;
+  return { method: parts[0]!.toUpperCase(), path: parts[1]! };
+}
+
+/**
+ * Returns undefined when no API context is in scope (raw `--spec`
+ * invocation) or when no resource declares `seed_body`. Probe runners
+ * treat undefined as "no overlay" and keep the legacy generator path.
+ */
+export async function loadSeedBodyOverlays(
+  apiName: string | undefined,
+  dbPath?: string,
+): Promise<Map<string, SeedBodyConfig> | undefined> {
+  if (!apiName) return undefined;
+  const col = resolveApiCollection(apiName, dbPath);
+  if ("error" in col || !col.baseDir) return undefined;
+  const map = await readResourceMap(col.baseDir);
+  if (!map) return undefined;
+  const out = new Map<string, SeedBodyConfig>();
+  for (const r of map.resources) {
+    if (!r.seed_body || !r.endpoints?.create) continue;
+    const parsed = parseLabel(r.endpoints.create);
+    if (!parsed) continue;
+    out.set(`${parsed.method} ${parsed.path}`, {
+      contentType: r.seed_body.content_type,
+      body: r.seed_body.body,
+    });
+  }
+  return out.size > 0 ? out : undefined;
+}

package/src/cli/commands/probe/mass-assignment.ts

@@ -17,6 +17,7 @@ import { printMutationBanner, countCleanupFailures } from "../../../core/probe/s
 import { MassAssignmentProbe } from "../../../core/probe/mass-assignment-probe-class.ts";
 import { summarizeDryRun, formatDryRunDigest } from "../../../core/probe/dry-run-envelope.ts";
 import { compileOperationFilter } from "../../../core/selectors/operation-filter.ts";
+import { loadSeedBodyOverlays } from "./_seed-bodies.ts";
 import type { EndpointVerdict, MassAssignmentResult } from "../../../core/probe/mass-assignment-probe.ts";
 import type { ProbeEndpointResult, ProbeEndpointStatus, ProbeFindingSeverity } from "../../../core/probe/types.ts";
 
@@ -85,6 +86,17 @@ export interface ProbeMassAssignmentOptions {
    *  spec-extension support (x-zond-suspect-fields) is tracked in
    *  ARV-189. */
   suspectField?: string[];
+  /** ARV-265: collection name for audit-coverage attribution. Set by
+   *  the CLI when --api / current-api resolves; left undefined for
+   *  bare-spec invocations. */
+  apiName?: string;
+  /** ARV-302: cap the number of endpoints probed in this run (after
+   *  --include / --exclude / --tag filters). Used by `zond audit
+   *  --budget` so probe stages stay inside a wall-clock budget instead
+   *  of unbounded scanning (Stripe: 587 endpoints, 3.6k probes — silent
+   *  10+ min). When the cap trims the set, a warning is emitted so the
+   *  user knows the run was partial. */
+  maxEndpoints?: number;
 }
 
 export async function probeMassAssignmentCommand(
@@ -131,6 +143,23 @@ export async function probeMassAssignmentCommand(
       }
       endpoints = endpoints.filter(compiled.filter);
     }
+    // ARV-302: --max-endpoints cap — applied after include/exclude/tag
+    // filters so the user-visible filter intent is preserved. The cap
+    // is a coarse time-budget knob (`zond audit --budget standard` →
+    // 50 endpoints), not a sampling strategy: take the first N from
+    // the filtered list. A warning fires so partial output is obvious.
+    let cappedEndpoints = false;
+    if (typeof options.maxEndpoints === "number" && options.maxEndpoints > 0
+        && endpoints.length > options.maxEndpoints) {
+      const total = endpoints.length;
+      endpoints = endpoints.slice(0, options.maxEndpoints);
+      cappedEndpoints = true;
+      if (!options.json) {
+        process.stderr.write(
+          `zond: probe mass-assignment capped at ${options.maxEndpoints}/${total} endpoints (--max-endpoints) — pass --max-endpoints <N> or --budget full to widen.\n`,
+        );
+      }
+    }
 
     // Load env vars (base_url, auth_token, api_key, path-param overrides).
     let vars: Record<string, string> = {};
@@ -160,6 +189,24 @@ export async function probeMassAssignmentCommand(
         options: {},
       });
       const data = summarizeDryRun(plan);
+      // ARV-317: persist the planned inventory when --output is given, so it
+      // survives beyond stdout (an agent can read it back). --emit-tests is
+      // skipped on dry-run — there are no findings to turn into regression
+      // suites; the plan digest is the dry-run deliverable.
+      // ARV-321: say so explicitly. A silent no-op read as a bug on the live
+      // Stripe run (report-zond friction, 2026-07-02) — the target dir stayed
+      // empty with zero signal that --emit-tests was ignored.
+      if (options.emitTests) {
+        printWarning(`--emit-tests skipped: safe/dry-run mode has no live verdicts to lock in as regression suites. Re-run with --live to emit ${options.emitTests}.`);
+      }
+      if (options.output) {
+        const payload = options.report === "json"
+          ? JSON.stringify(data, null, 2)
+          : formatDryRunDigest(plan);
+        await mkdir(join(options.output, "..").replace(/\/\.$/, ""), { recursive: true }).catch(() => {});
+        rotateOutputTarget(options.output, { overwrite: options.overwrite });
+        await writeFile(options.output, payload + "\n", "utf-8");
+      }
       if (options.json) {
         printJson(jsonOk("probe-mass-assignment", data));
       } else {
@@ -180,15 +227,54 @@ export async function probeMassAssignmentCommand(
     // is off — this banner is about the cleanup-pass, too.
     printMutationBanner("probe-mass-assignment", vars, { quiet: options.json === true });
 
-    const result = await runMassAssignmentProbes({
-      endpoints,
-      securitySchemes,
-      vars,
-      noCleanup: options.noCleanup,
-      timeoutMs: options.timeoutMs,
-      discover: !options.noDiscover,
-      extraSuspectFields: parseSuspectFieldFlags(options.suspectField),
-    });
+    // ARV-265: capture HTTP touches for audit-coverage. Dry-run never
+    // reaches this branch (early return above), so AC#5 holds.
+    const { withHttpAudit, beginAuditRun, finalizeAuditRun, auditRecordToCase, checksPersistEnabled } =
+      await import("../../../core/audit/persist.ts");
+    const auditEnabled = checksPersistEnabled();
+    // ARV-269: lift agent-authored `seed_body` overlays out of
+    // `.api-resources.local.yaml` so create-endpoint baselines win against
+    // strict validators. No-op when --api isn't set (raw --spec invocation).
+    const seedBodies = await loadSeedBodyOverlays(options.apiName);
+    const { value: result, records: auditRecords } = await withHttpAudit(async () =>
+      runMassAssignmentProbes({
+        endpoints,
+        securitySchemes,
+        vars,
+        noCleanup: options.noCleanup,
+        timeoutMs: options.timeoutMs,
+        discover: !options.noDiscover,
+        extraSuspectFields: parseSuspectFieldFlags(options.suspectField),
+        seedBodies,
+      }),
+    );
+
+    if (auditEnabled && auditRecords.length > 0) {
+      try {
+        const { getDb } = await import("../../../db/schema.ts");
+        const { findCollectionByNameOrId } = await import("../../../db/queries.ts");
+        const { readCurrentSession } = await import("../../../core/context/session.ts");
+        getDb();
+        const collectionId = options.apiName ? findCollectionByNameOrId(options.apiName)?.id : undefined;
+        const session = readCurrentSession();
+        const runId = beginAuditRun({
+          runKind: "probe",
+          ...(collectionId != null ? { collectionId } : {}),
+          ...(session?.id ? { sessionId: session.id } : {}),
+          tags: ["probe", "mass-assignment"],
+        });
+        const suiteFile = `apis/${options.apiName ?? "_"}/probes/mass-assignment.yaml`;
+        finalizeAuditRun(runId, auditRecords.map((rec) =>
+          auditRecordToCase(rec, {
+            suiteName: "probe/mass-assignment",
+            suiteFile,
+            testName: `mass-assignment::${rec.request.method.toUpperCase()} ${rec.request.url}`,
+          }),
+        ));
+      } catch (err) {
+        process.stderr.write(`zond: audit persistence failed (${(err as Error).message}).\n`);
+      }
+    }
 
     // ARV-252: filter verdicts for display under the evidence-chain
     // principle. Silently-ignored (correct framework behaviour) never
@@ -246,7 +332,12 @@ export async function probeMassAssignmentCommand(
             by_status: maByStatus(structuredEndpoints),
           },
           orphans,
-          warnings: result.warnings,
+          warnings: cappedEndpoints
+            ? [
+                ...result.warnings,
+                `--max-endpoints capped this run at ${options.maxEndpoints}; pass --max-endpoints <N> or --budget full to widen.`,
+              ]
+            : result.warnings,
           emittedTests: emittedSuites,
         }),
       );

package/src/cli/commands/probe/security.ts

@@ -20,6 +20,7 @@ import { persistVerdictsAsOrphans } from "../../../core/probe/orphan-tracker.ts"
 import { SecurityProbe } from "../../../core/probe/security-probe-class.ts";
 import { summarizeDryRun } from "../../../core/probe/dry-run-envelope.ts";
 import { compileOperationFilter } from "../../../core/selectors/operation-filter.ts";
+import { loadSeedBodyOverlays } from "./_seed-bodies.ts";
 
 interface Buckets {
   high: number;
@@ -95,6 +96,11 @@ export interface ProbeSecurityOptions {
    *  reflection — sanitization signal only). Hidden by default since
    *  they carry single_signal proof with no exploit pathway. */
   verbose?: boolean;
+  /** ARV-302: cap the number of endpoints probed in this run (after
+   *  --include / --exclude / --tag filters). Used by `zond audit
+   *  --budget` to keep the security stage inside a wall-clock budget
+   *  on big specs (Stripe: 587 endpoints) instead of unbounded scanning. */
+  maxEndpoints?: number;
 }
 
 function parseClasses(input: string): SecurityClass[] | string {
@@ -157,6 +163,21 @@ export async function probeSecurityCommand(
       }
       endpoints = endpoints.filter(compiled.filter);
     }
+    // ARV-302: --max-endpoints cap — see probe/mass-assignment.ts for the
+    // rationale. Applied after user-visible filters; a warning fires so
+    // partial output is obvious.
+    let cappedEndpoints = false;
+    if (typeof options.maxEndpoints === "number" && options.maxEndpoints > 0
+        && endpoints.length > options.maxEndpoints) {
+      const total = endpoints.length;
+      endpoints = endpoints.slice(0, options.maxEndpoints);
+      cappedEndpoints = true;
+      if (!options.json) {
+        process.stderr.write(
+          `zond: probe security capped at ${options.maxEndpoints}/${total} endpoints (--max-endpoints) — pass --max-endpoints <N> or --budget full to widen.\n`,
+        );
+      }
+    }
 
     let vars: Record<string, string> = {};
     if (options.env) {
@@ -196,10 +217,26 @@ export async function probeSecurityCommand(
         options: { isolated: options.isolated === true },
       });
       const data = summarizeDryRun(plan);
+      const { formatDryRunDigest } = await import("../../../core/probe/dry-run-envelope.ts");
+      // ARV-317: persist the planned inventory when --output is given (parity
+      // with probe mass-assignment). --emit-tests is skipped on dry-run —
+      // there are no findings to turn into regression suites.
+      // ARV-321: say so explicitly — see mass-assignment.ts for the friction
+      // that prompted this.
+      if (options.emitTests) {
+        printWarning(`--emit-tests skipped: safe/dry-run mode has no live verdicts to lock in as regression suites. Re-run with --live to emit ${options.emitTests}.`);
+      }
+      if (options.output) {
+        const payload = options.report === "json"
+          ? JSON.stringify(data, null, 2)
+          : formatDryRunDigest(plan);
+        await mkdir(join(options.output, "..").replace(/\/\.$/, ""), { recursive: true }).catch(() => {});
+        rotateOutputTarget(options.output, { overwrite: options.overwrite });
+        await writeFile(options.output, payload + "\n", "utf-8");
+      }
       if (options.json) {
         printJson(jsonOk("probe-security", data));
       } else {
-        const { formatDryRunDigest } = await import("../../../core/probe/dry-run-envelope.ts");
         console.log(formatDryRunDigest(plan));
       }
       return 0;
@@ -210,17 +247,55 @@ export async function probeSecurityCommand(
     // travel in the envelope instead).
     printMutationBanner("probe-security", vars, { quiet: options.json === true });
 
-    const result = await runSecurityProbes({
-      endpoints,
-      securitySchemes,
-      vars,
-      classes,
-      noCleanup: options.noCleanup,
-      timeoutMs: options.timeoutMs,
-      dryRun: options.dryRun,
-      isolated: options.isolated === true,
-      allowLeaks: options.allowLeaks === true,
-    });
+    // ARV-265: capture every HTTP request the probe sends so audit-coverage
+    // sees the touches. Dry-run never reaches this branch (early return
+    // above), so AC#5 holds — only live probes pollute the run table.
+    const { withHttpAudit, beginAuditRun, finalizeAuditRun, auditRecordToCase, checksPersistEnabled } =
+      await import("../../../core/audit/persist.ts");
+    const auditEnabled = checksPersistEnabled();
+    // ARV-269: same overlay-lift as probe-mass-assignment.
+    const seedBodies = await loadSeedBodyOverlays(options.apiName);
+    const { value: result, records: auditRecords } = await withHttpAudit(async () =>
+      runSecurityProbes({
+        endpoints,
+        securitySchemes,
+        vars,
+        classes,
+        noCleanup: options.noCleanup,
+        timeoutMs: options.timeoutMs,
+        dryRun: options.dryRun,
+        isolated: options.isolated === true,
+        allowLeaks: options.allowLeaks === true,
+        seedBodies,
+      }),
+    );
+
+    if (auditEnabled && auditRecords.length > 0) {
+      try {
+        const { getDb } = await import("../../../db/schema.ts");
+        const { findCollectionByNameOrId } = await import("../../../db/queries.ts");
+        const { readCurrentSession } = await import("../../../core/context/session.ts");
+        getDb();
+        const collectionId = options.apiName ? findCollectionByNameOrId(options.apiName)?.id : undefined;
+        const session = readCurrentSession();
+        const runId = beginAuditRun({
+          runKind: "probe",
+          ...(collectionId != null ? { collectionId } : {}),
+          ...(session?.id ? { sessionId: session.id } : {}),
+          tags: ["probe", "security", ...classes],
+        });
+        const suiteFile = `apis/${options.apiName ?? "_"}/probes/security.yaml`;
+        finalizeAuditRun(runId, auditRecords.map((rec) =>
+          auditRecordToCase(rec, {
+            suiteName: "probe/security",
+            suiteFile,
+            testName: `security::${rec.request.method.toUpperCase()} ${rec.request.url}`,
+          }),
+        ));
+      } catch (err) {
+        process.stderr.write(`zond: audit persistence failed (${(err as Error).message}).\n`);
+      }
+    }
 
     // ARV-253: filter verdicts for display under the evidence-chain
     // principle. INFO-severity findings (CRLF accepted, no reflection
@@ -328,6 +403,14 @@ export async function probeSecurityCommand(
           },
           orphans,
           emittedTests: emittedSuites,
+          // ARV-302: surface the partial-run warning so JSON consumers
+          // see that --max-endpoints trimmed the set (otherwise the cap
+          // is invisible in machine-readable output).
+          ...(cappedEndpoints ? {
+            warnings: [
+              `--max-endpoints capped this run at ${options.maxEndpoints}; pass --max-endpoints <N> or --budget full to widen.`,
+            ],
+          } : {}),
         }),
       );
     } else {

package/src/cli/commands/probe/webhooks.ts

@@ -31,6 +31,8 @@ export interface ProbeWebhooksOptions {
   output?: string;
   /** Envelope mode — wraps result in {ok, command, data, errors}. */
   json?: boolean;
+  /** API name for audit-coverage attribution. */
+  apiName?: string;
 }
 
 function severityCount(findings: WebhookFinding[]): { high: number; low: number } {

package/src/cli/commands/probe.ts

@@ -26,7 +26,8 @@ import { getApi } from "../util/api-context.ts";
 import { existsSync } from "fs";
 import { join, dirname } from "node:path";
 import { parsePositiveInt } from "../argv.ts";
-import { printError } from "../output.ts";
+import { printError, printWarning } from "../output.ts";
+import { SAFE_HELP, LIVE_HELP, resolveLive } from "../safe-live.ts";
 import { jsonError, printJson } from "../json-envelope.ts";
 import { loadEnvMeta } from "../../core/parser/variables.ts";
 import { resolveTimeoutMs } from "../../core/workspace/config.ts";
@@ -190,16 +191,49 @@ function defineProbeStatic(parent: Command, name: string): void {
     .option("--max-per-endpoint <N>", "Cap negative-input probes per endpoint (default 50)", parsePositiveInt("--max-per-endpoint"))
     .option("--no-cleanup", "Skip emission of follow-up DELETE cleanup steps for mutating probes (use in namespace-isolated test envs)")
     .option("--use-synthetic-parents", "Bake synthetic-by-type values into all path params (legacy). By default, non-attacked path params are emitted as {{name}} and resolved from .env.yaml at run time — needed to reach the leaf validator on nested paths (TASK-135).")
-    .option("--include <classes>", "Comma-separated subset of {validation, methods} (default: both)")
-    .option("--exclude <classes>", "Comma-separated subset to skip (mutually exclusive with --include)")
+    // ARV-225: probe static --include is a CLASS LIST ({validation, methods}),
+    // while sibling commands (probe security, probe mass-assignment, checks
+    // run) use SELECTOR grammar (path:/method:/tag:/operation-id:). Rename the
+    // canonical flag to --include-class / --exclude-class for clarity; keep
+    // --include / --exclude as deprecated aliases (warn on use).
+    .option("--include-class <classes>", "Comma-separated subset of {validation, methods} (default: both)")
+    .option("--exclude-class <classes>", "Comma-separated subset to skip (mutually exclusive with --include-class)")
+    .option("--include <classes>", "[deprecated, use --include-class] Comma-separated subset of {validation, methods}")
+    .option("--exclude <classes>", "[deprecated, use --exclude-class] Comma-separated subset to skip")
+    // ARV-299: static only *generates* probe suites (it never sends live
+    // traffic), so it is always safe. The flags exist for vocabulary parity
+    // with the sibling subcommands; --live is a no-op here and says so.
+    .option("--safe", SAFE_HELP)
+    .option("--live", LIVE_HELP)
     .action(async (specPos: string | undefined, optsArg, cmdRef: Command) => {
+      if (optsArg.live === true) {
+        printWarning("probe static only generates suites and never sends live traffic — --safe/--live have no effect here. Run the emitted suites with `zond run … --live` to execute them.");
+      }
       // ARV-33: see resolveProbeApi — keep the chain consistent with the
       // sibling subcommands (mass-assignment, security).
       const apiName = resolveProbeApi(optsArg.api, cmdRef);
       const resolved = resolveSpecArg(specPos, apiName, optsArg.db);
       if ("error" in resolved) { printError(resolved.error); process.exitCode = 2; return; }
 
-      const r = resolveStaticClasses(optsArg.include, optsArg.exclude);
+      // ARV-225: prefer --include-class / --exclude-class. Fall back to
+      // --include / --exclude with a one-line stderr deprecation note —
+      // these are the legacy names that collide semantically with the
+      // selector --include on sibling commands.
+      let includeClasses: string | undefined = optsArg.includeClass;
+      let excludeClasses: string | undefined = optsArg.excludeClass;
+      if (!includeClasses && optsArg.include) {
+        process.stderr.write(
+          "Warning: `probe static --include <classes>` is deprecated (class-list, not a selector — collides with probe security / checks run). Use --include-class.\n",
+        );
+        includeClasses = optsArg.include;
+      }
+      if (!excludeClasses && optsArg.exclude) {
+        process.stderr.write(
+          "Warning: `probe static --exclude <classes>` is deprecated. Use --exclude-class.\n",
+        );
+        excludeClasses = optsArg.exclude;
+      }
+      const r = resolveStaticClasses(includeClasses, excludeClasses);
       if ("error" in r) { printError(r.error); process.exitCode = 2; return; }
 
       // ARV-30: derive --output from the registered API's base_dir when the
@@ -245,7 +279,9 @@ function defineProbeMassAssignment(parent: Command, name: string): void {
     .option("--list-tags", "List available tags from spec and exit")
     .option("--no-cleanup", "Skip follow-up DELETE for resources accidentally created by 2xx probes")
     .option("--no-discover", "Disable auto-discovery of path-param fixtures via GET-on-list (TASK-92)")
-    .option("--dry-run", "Print which endpoints/fields would be attacked without sending requests (m-17 ARV-52)")
+    .option("--dry-run", "Print which endpoints/fields would be attacked without sending requests (m-17 ARV-52). Equivalent to the default --safe mode.")
+    .option("--safe", SAFE_HELP)
+    .option("--live", LIVE_HELP)
     .option(
       "--include <selector>",
       "Filter operations (m-15 ARV-9 grammar: path:/users/.* | tag:Webhooks | method:POST,PATCH | operation-id:create.*). Repeatable.",
@@ -269,7 +305,8 @@ function defineProbeMassAssignment(parent: Command, name: string): void {
       (v: string, prev: string[] = []) => prev.concat(v),
       [] as string[],
     )
-    .option("--emit-template <method:path>", "TASK-146: emit a ready-to-edit YAML probe template for one endpoint (e.g. \"POST:/users\") instead of running the live probe. Pairs `--output <file>` to write to disk (default: stdout). Use to drop down to manual catch-up after INCONCLUSIVE / INCONCLUSIVE-5XX verdicts without copy-pasting boilerplate from the skill.");
+    .option("--emit-template <method:path>", "TASK-146: emit a ready-to-edit YAML probe template for one endpoint (e.g. \"POST:/users\") instead of running the live probe. Pairs `--output <file>` to write to disk (default: stdout). Use to drop down to manual catch-up after INCONCLUSIVE / INCONCLUSIVE-5XX verdicts without copy-pasting boilerplate from the skill.")
+    .option("--max-endpoints <n>", "ARV-302: cap the number of endpoints probed in this run (after --include / --exclude / --tag filters). Used by `zond audit --budget` to keep probe stages inside a wall-clock budget instead of unbounded scanning.", parsePositiveInt("--max-endpoints"));
   addProbeReportOutputOptions(sub);
   sub.action(async (specPos: string | undefined, opts, cmd: Command) => {
       // ARV-33: resolve --api via the same fallback chain as prepare-fixtures /
@@ -291,11 +328,27 @@ function defineProbeMassAssignment(parent: Command, name: string): void {
         return;
       }
 
+      // ARV-299: safe (default) → plan only, no live mutating traffic. The
+      // proven --dry-run path IS the safe path, so we just force it on when
+      // --live is absent (and say so, unless the user already asked for a
+      // dry-run explicitly).
+      const live = resolveLive(opts);
+      const effectiveDryRun = opts.dryRun === true || !live;
+      // ARV-348: fail loudly (see probe security) — --emit-tests needs live
+      // verdicts; safe/dry-run mode would leave an empty dir + exit 0.
+      if (opts.emitTests && !live) {
+        printError("--emit-tests requires --live: safe/dry-run mode produces no live verdicts to lock into regression suites. Re-run with --live against a throwaway/sandbox account, or drop --emit-tests to just plan.");
+        process.exitCode = 2;
+        return;
+      }
+      if (!live && opts.dryRun !== true && !opts.listTags) {
+        printWarning("probe mass-assignment: safe mode (default) — planning only, no live attack traffic. Re-run with --live against a throwaway/sandbox account to send probes.");
+      }
       // m-17 / ARV-52 + ARV-58: dry-run and list-tags paths tolerate a
       // missing env file the way probe-security does — the user wants
       // to inspect the plan / available tags, not hit a live API.
       const envFile = resolveProbeEnv(opts.env, apiName, opts.db, {
-        tolerateMissing: opts.dryRun === true || opts.listTags === true,
+        tolerateMissing: effectiveDryRun || opts.listTags === true,
       });
       if ("error" in envFile) { printError(envFile.error); process.exitCode = 2; return; }
       const timeoutMs = await resolveProbeTimeout(opts.timeout, apiName, envFile.env);
@@ -305,6 +358,7 @@ function defineProbeMassAssignment(parent: Command, name: string): void {
       process.exitCode = await probeMassAssignmentCommand({
         specPath: resolved.spec,
         env: envFile.env,
+        apiName,
         output: rep.output,
         emitTests: opts.emitTests,
         tag: opts.tag,
@@ -314,12 +368,13 @@ function defineProbeMassAssignment(parent: Command, name: string): void {
         timeoutMs,
         overwrite: opts.overwrite === true,
         json,
-        dryRun: opts.dryRun === true,
+        dryRun: effectiveDryRun,
         include: Array.isArray(opts.include) && opts.include.length > 0 ? opts.include : undefined,
         exclude: Array.isArray(opts.exclude) && opts.exclude.length > 0 ? opts.exclude : undefined,
         report: rep.report,
         verbose: opts.verbose === true,
         suspectField: Array.isArray(opts.suspectField) && opts.suspectField.length > 0 ? opts.suspectField : undefined,
+        maxEndpoints: typeof opts.maxEndpoints === "number" ? opts.maxEndpoints : undefined,
       });
     });
 }
@@ -355,12 +410,15 @@ function defineProbeSecurity(parent: Command, name: string): void {
       (v: string, prev: string[] = []) => prev.concat(v),
       [] as string[],
     )
-    .option("--dry-run", "Print which endpoints/fields would be attacked without sending requests")
+    .option("--dry-run", "Print which endpoints/fields would be attacked without sending requests. Equivalent to the default --safe mode.")
+    .option("--safe", SAFE_HELP)
+    .option("--live", LIVE_HELP)
     .option("--timeout <ms>", "Per-request timeout in ms (overrides apis/<name>/.env.yaml `timeoutMs` and zond.config.yml `defaults.timeout_ms`; default 30000)", parsePositiveInt("--timeout"))
     .option(
       "--verbose",
       "ARV-253: surface INFO-severity findings (sanitization-signal-only, e.g. CRLF accepted but no reflection observed). Default hides them — they're single-signal proof with no exploit pathway.",
-    );
+    )
+    .option("--max-endpoints <n>", "ARV-302: cap the number of endpoints probed in this run (after --include / --exclude / --tag filters). Used by `zond audit --budget` to keep probe stages inside a wall-clock budget instead of unbounded scanning.", parsePositiveInt("--max-endpoints"));
   addProbeReportOutputOptions(sub);
   sub.action(async (classes: string | undefined, specPos: string | undefined, opts, cmd: Command) => {
       // ARV-36: missing-arg path should list the available classes (parity
@@ -378,6 +436,22 @@ function defineProbeSecurity(parent: Command, name: string): void {
       const apiName = resolveProbeApi(opts.api, cmd);
       const resolved = resolveSpecArg(specPos, apiName, opts.db);
       if ("error" in resolved) { printError(resolved.error); process.exitCode = 2; return; }
+      // ARV-299: safe (default) forces plan-only; live attack traffic needs --live.
+      const live = resolveLive(opts);
+      const effectiveDryRun = opts.dryRun === true || !live;
+      // ARV-348: fail loudly instead of silently producing an empty dir. Safe/
+      // dry-run mode has no live verdicts to lock into regression suites, so
+      // --emit-tests can't do anything — and a later `zond run <dir>` on the
+      // empty dir just prints "No test files found". One consistent message
+      // (—live), not the old contradictory "Re-run without --dry-run".
+      if (opts.emitTests && !live) {
+        printError("--emit-tests requires --live: safe/dry-run mode produces no live verdicts to lock into regression suites. Re-run with --live against a throwaway/sandbox account, or drop --emit-tests to just plan.");
+        process.exitCode = 2;
+        return;
+      }
+      if (!live && opts.dryRun !== true && !opts.listTags) {
+        printWarning("probe security: safe mode (default) — planning only, no live attack traffic. Re-run with --live against a throwaway/sandbox account to send probes.");
+      }
       // probe-security tolerates a missing env (--dry-run path), so don't
       // fail when --api is given but the env file isn't on disk yet.
       const envFile = resolveProbeEnv(opts.env, apiName, opts.db, { tolerateMissing: true });
@@ -395,7 +469,7 @@ function defineProbeSecurity(parent: Command, name: string): void {
         tag: opts.tag,
         listTags: opts.listTags,
         noCleanup: opts.cleanup === false,
-        dryRun: opts.dryRun === true,
+        dryRun: effectiveDryRun,
         timeoutMs,
         overwrite: opts.overwrite === true,
         json,
@@ -406,6 +480,7 @@ function defineProbeSecurity(parent: Command, name: string): void {
         include: Array.isArray(opts.include) && opts.include.length > 0 ? opts.include : undefined,
         exclude: Array.isArray(opts.exclude) && opts.exclude.length > 0 ? opts.exclude : undefined,
         verbose: opts.verbose === true,
+        maxEndpoints: typeof opts.maxEndpoints === "number" ? opts.maxEndpoints : undefined,
       });
     });
 }
@@ -443,6 +518,7 @@ function defineProbeWebhooks(parent: Command, name: string): void {
       report: rep.report,
       output: rep.output,
       json,
+      apiName,
     });
   });
 }