@kirrosh/zond 0.21.0 → 0.23.0

package/src/cli/commands/run.ts

@@ -1,25 +1,75 @@
 import { dirname } from "path";
 import { stat } from "node:fs/promises";
-import { parse } from "../../core/parser/yaml-parser.ts";
-import { loadEnvironment } from "../../core/parser/variables.ts";
-import { filterSuitesByTags, excludeSuitesByTags, filterSuitesByMethod } from "../../core/parser/filter.ts";
-import { runSuite } from "../../core/runner/executor.ts";
-import { getReporter } from "../../core/reporter/index.ts";
+import { parseSafe } from "../../core/parser/yaml-parser.ts";
+import { loadEnvironment, loadEnvMeta, loadEnvFile } from "../../core/parser/variables.ts";
+import { filterSuitesByTags, excludeSuitesByTags, filterSuitesByMethod, filterSuitesByOperationFilter } from "../../core/parser/filter.ts";
+import { preflightCheckVars, formatMissingVarLine, summarizeMissingVars } from "../../core/runner/preflight-vars.ts";
+import { runSuite, expandParameterize } from "../../core/runner/executor.ts";
+import {
+  ProgressTracker,
+  formatProgressLine,
+  PROGRESS_INTERVAL_MS,
+  PROGRESS_QUIET_MS,
+} from "../../core/runner/progress-tracker.ts";
+import { createSchemaValidator } from "../../core/runner/schema-validator.ts";
+import { readOpenApiSpec } from "../../core/generator/openapi-reader.ts";
+import { createRateLimiter, createAdaptiveRateLimiter } from "../../core/runner/rate-limiter.ts";
+import { getReporter, generateJsonReport, generateJunitXml } from "../../core/reporter/index.ts";
 import type { ReporterName } from "../../core/reporter/types.ts";
+import { resolveOutput, OutputSpecError, type OutputSpec } from "../../core/output/index.ts";
+import { writeFile, mkdir } from "node:fs/promises";
+import { dirname as pathDirname, resolve as pathResolve } from "node:path";
 import type { TestSuite } from "../../core/parser/types.ts";
 import type { TestRunResult } from "../../core/runner/types.ts";
 import { printError, printWarning } from "../output.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 import { getDb } from "../../db/schema.ts";
 import { createRun, finalizeRun, saveResults, findCollectionByTestPath } from "../../db/queries.ts";
-import { AUTH_PATH_RE } from "../../core/runner/execute-run.ts";
+import { AUTH_PATH_RE } from "../../core/runner/auth-path.ts";
+import { resolveCollectionSpec } from "../../core/setup-api.ts";
+import { findWorkspaceRoot } from "../../core/workspace/root.ts";
+import { existsSync } from "node:fs";
+import { buildSpecPointer } from "../../core/diagnostics/spec-pointer.ts";
+import { detectStatusDrifts, formatDriftPlan, applyDriftsToTests, appendToleratedDrifts } from "../../core/runner/learn-drift.ts";
+import { detectCiContext } from "../../core/runner/ci-context.ts";
+import { detectRunKind } from "../../core/runner/run-kind.ts";
+import { resolveRateLimit } from "../../core/workspace/config.ts";
+
+/**
+ * ARV-117 (m-19): OutputSpec for `zond run`. Three formats; console is
+ * the default (stdout, rich per-suite stream); `json` / `junit` default
+ * to stdout but accept `--output <path>` to redirect. None of the
+ * formats are envelope-wrapped — `--report json` is a test-run report
+ * (per-suite breakdown), NOT the `{ok, data, errors}` envelope that
+ * other commands emit for `--json`. That distinction is intentional
+ * (TASK-134) and remains enforced by the explicit absence of `--json`
+ * on this command.
+ */
+export const RUN_OUTPUT_SPEC: OutputSpec<unknown> = {
+  command: "run",
+  defaultFormat: "console",
+  formats: {
+    console: { defaultChannel: "stdout", description: "Rich per-suite stream (default)" },
+    json:    { defaultChannel: "stdout", description: "Per-test JSON breakdown (`generateJsonReport`)" },
+    junit:   { defaultChannel: "stdout", description: "JUnit XML — CI consumption" },
+  },
+};
 
 export interface RunOptions {
-  path: string;
+  /**
+   * One or more paths to a YAML file or a directory of YAML files.
+   * Multi-path: shell-glob expansion (`zond run tests/*.yaml`) — suites from
+   * every path are merged into a single run. The first path is used as the
+   * anchor for env-file resolution and DB collection lookup.
+   */
+  paths: string[];
   env?: string;
   report: ReporterName;
   timeout?: number;
+  rateLimit?: number | "auto";
   bail: boolean;
+  /** Run regular suites sequentially (one after another) instead of in parallel. */
+  sequential?: boolean;
   noDb?: boolean;
   dbPath?: string;
   authToken?: string;
@@ -27,32 +77,159 @@ export interface RunOptions {
   tag?: string[];
   excludeTag?: string[];
   method?: string;
+  /** ARV-25: parity with `zond generate`/`zond checks run` — selector
+   *  grammar `<path|method|tag|operation-id>:<value>`, repeatable, OR. */
+  include?: string[];
+  /** ARV-25: same grammar as `include`; evaluated after includes. */
+  exclude?: string[];
   envVars?: string[];
+  /** Hard-fail (exit 2) on undefined {{var}} references instead of warning. */
+  strictVars?: boolean;
   dryRun?: boolean;
   json?: boolean;
+  /** ARV-117: write the report to a file instead of stdout. Replaces
+   *  the legacy `--report-out` flag (no alias — see m-19 lesson §E).
+   *  Resolved through `core/output`'s OutputSpec policy. */
+  output?: string;
+  /** Validate every JSON response against the OpenAPI response schema. */
+  validateSchema?: boolean;
+  /** Explicit OpenAPI spec path/URL (overrides collection.openapi_spec). */
+  specPath?: string;
+  /** ARV-44: --api <name> passed alongside paths — used as the lookup-by-name
+   *  fallback when test-path lookup in DB doesn't yield a spec. Parity with
+   *  ARV-33 (probe mass-assignment / probe security). */
+  apiName?: string;
+  /** Group this run under a session id (multi-run campaigns). */
+  sessionId?: string;
+  /** TASK-144: per-step retry budget for transient network errors
+   *  (ECONNRESET / EPIPE / socket hang up / fetch failed / abort).
+   *  HTTP statuses are not retried by this path. Default 1, 0 disables. */
+  retryOnNetwork?: number;
+  /** TASK-282: detect "passing-test-but-wrong-status" drift and print a plan.
+   *  Implies --validate-schema (requires a spec) so we only flag drift when
+   *  the body matches the OpenAPI schema — the case where retrying with the
+   *  observed status would produce a green test. */
+  learn?: boolean;
+  /** TASK-282: actually mutate files instead of printing the plan. Requires
+   *  `learn: true` and a `learnTarget`. */
+  learnApply?: boolean;
+  /** TASK-282: where to record the drift — rewrite YAML (`test`) or append to
+   *  apis/<name>/tolerated-drifts.yaml (`drifts`). */
+  learnTarget?: "test" | "drifts";
+  /** TASK-265: console reporter emits only the grand-total summary line. */
+  quiet?: boolean;
+  /** ARV-72 (feedback round-02 / F14): default true. Set to false (via
+   *  --no-fail-on-failures) to keep exit code 0 even when steps failed —
+   *  useful for advisory runs (audit pre-pass, surface discovery) where
+   *  CI shouldn't break on a single test red. */
+  failOnFailures?: boolean;
+  /** ARV-249: hard cap on outgoing HTTP requests across the whole run.
+   *  Once reached, remaining steps short-circuit to `skip` with reason
+   *  `max-requests-cap-reached`. Useful for sampling huge probe-suite
+   *  runs and for CI time-boxing. Each `retry_until` attempt counts as
+   *  one request. */
+  maxRequests?: number;
+}
+
+/** ARV-249: rough up-front estimate of the total step count for the
+ *  progress reporter. Walks the parameterize cross-product so a 3×4 grid
+ *  on a 50-step suite reports as 600. for_each is dynamic (depends on
+ *  upstream captures) and not counted — the percentage will overshoot a
+ *  little on for_each-heavy suites; acceptable for an ETA. */
+function estimateTotalSteps(suites: TestSuite[]): number {
+  let total = 0;
+  for (const suite of suites) {
+    const iters = expandParameterize(suite.parameterize).length || 1;
+    total += suite.tests.length * iters;
+  }
+  return total;
 }
 
 export async function runCommand(options: RunOptions): Promise<number> {
-  // 1. Parse test files
-  let suites: TestSuite[];
-  try {
-    suites = await parse(options.path);
-  } catch (err) {
-    printError(err instanceof Error ? err.message : String(err));
+  if (options.paths.length === 0) {
+    printError("No path given");
+    return 2;
+  }
+  const emptyPaths = options.paths.filter((p) => typeof p !== "string" || p.trim().length === 0);
+  if (emptyPaths.length > 0) {
+    printError(`Empty path argument (got ${emptyPaths.length} blank entr${emptyPaths.length === 1 ? "y" : "ies"}) — pass a non-empty file or directory path`);
     return 2;
   }
+  // ARV-39: strip leading/trailing whitespace from path args so a stray space
+  // from copy-paste / shell history doesn't produce an ENOENT that quotes
+  // the rogue character. Mutating options.paths so downstream lookups
+  // (collection by test_path, env-file search) see the cleaned form.
+  options.paths = options.paths.map((p) => p.trim());
+  const primaryPath = options.paths[0]!;
+
+  // 1. Parse test files from every input path (collect parse errors instead
+  //    of silently skipping). Suites from all paths are merged into one run.
+  let suites: TestSuite[] = [];
+  const parseErrors: { file: string; error: string }[] = [];
+  for (const p of options.paths) {
+    try {
+      const parsed = await parseSafe(p);
+      suites.push(...parsed.suites);
+      parseErrors.push(...parsed.errors);
+    } catch (err) {
+      const raw = err instanceof Error ? err.message : String(err);
+      printError(formatPathError(p, raw));
+      return 2;
+    }
+  }
+
+  for (const pe of parseErrors) {
+    printWarning(`Skipped ${pe.file}: ${pe.error}`);
+  }
 
   if (suites.length === 0) {
-    printWarning(`No test files found in ${options.path}`);
+    const pathList = options.paths.join(", ");
+    if (parseErrors.length > 0) {
+      printError(`All ${parseErrors.length} test file(s) in ${pathList} failed to parse`);
+      return 2;
+    }
+    printWarning(`No test files found in ${pathList}`);
     return 0;
   }
 
+  // ARV-37: when a selector matches zero suites (typo'd --tag, dead --include
+  // pattern, etc.), exit non-zero. Previous fail-open let CI builds go green
+  // for `--tag smok` instead of `smoke`. For --tag we also surface the tags
+  // actually available so the user can correct without re-reading help.
+  // 1b0. ARV-25: unified --include/--exclude filter (parity with generate/checks).
+  //      Applied before tag/method filters so it can narrow the scope first.
+  if ((options.include && options.include.length > 0) || (options.exclude && options.exclude.length > 0)) {
+    const result = filterSuitesByOperationFilter(suites, options.include ?? [], options.exclude ?? []);
+    if (result.errors.length > 0) {
+      for (const err of result.errors) printError(err);
+      return 2;
+    }
+    suites = result.suites;
+    if (suites.length === 0) {
+      const parts: string[] = [];
+      if (options.include?.length) parts.push(`--include [${options.include.join(", ")}]`);
+      if (options.exclude?.length) parts.push(`--exclude [${options.exclude.join(", ")}]`);
+      printError(`No tests match ${parts.join(" / ")}`);
+      return 1;
+    }
+  }
+
   // 1b. Tag filter
   if (options.tag && options.tag.length > 0) {
+    const availableTags = collectAvailableTags(suites);
     suites = filterSuitesByTags(suites, options.tag);
     if (suites.length === 0) {
-      printWarning("No suites match the specified tags");
-      return 0;
+      const tagHint = availableTags.length > 0
+        ? ` Available tags: ${availableTags.join(", ")}.`
+        : " (loaded suites declare no tags.)";
+      if (parseErrors.length > 0) {
+        printError(
+          `No suites match tags [${options.tag.join(", ")}] — but ${parseErrors.length} file(s) failed to parse (see warnings above). Fix parse errors and retry.${tagHint}`
+        );
+        return 1;
+      }
+      printError(`No suites match tags [${options.tag.join(", ")}].${tagHint}`);
+      return 1;
     }
   }
 
@@ -60,8 +237,8 @@ export async function runCommand(options: RunOptions): Promise<number> {
   if (options.excludeTag && options.excludeTag.length > 0) {
     suites = excludeSuitesByTags(suites, options.excludeTag);
     if (suites.length === 0) {
-      printWarning("All suites excluded by --exclude-tag");
-      return 0;
+      printError(`All suites excluded by --exclude-tag [${options.excludeTag.join(", ")}]`);
+      return 1;
     }
   }
 
@@ -69,8 +246,8 @@ export async function runCommand(options: RunOptions): Promise<number> {
   if (options.method) {
     suites = filterSuitesByMethod(suites, options.method);
     if (suites.length === 0) {
-      printWarning(`No tests found with method ${options.method.toUpperCase()}`);
-      return 0;
+      printError(`No tests found with method ${options.method.toUpperCase()}`);
+      return 1;
     }
   }
 
@@ -92,13 +269,13 @@ export async function runCommand(options: RunOptions): Promise<number> {
 
   // 2. Load environment (resolve collection for scoped envs)
   // Use path itself as searchDir if it's a directory; dirname() on a dir path gives the parent
-  const pathStat = await stat(options.path).catch(() => null);
-  const searchDir = pathStat?.isDirectory() ? options.path : dirname(options.path);
+  const pathStat = await stat(primaryPath).catch(() => null);
+  const searchDir = pathStat?.isDirectory() ? primaryPath : dirname(primaryPath);
   let collectionForEnv: { id: number } | null = null;
   if (!options.noDb) {
     try {
       getDb(options.dbPath);
-      collectionForEnv = findCollectionByTestPath(options.path);
+      collectionForEnv = findCollectionByTestPath(primaryPath);
     } catch { /* DB not available — OK */ }
   }
 
@@ -110,6 +287,34 @@ export async function runCommand(options: RunOptions): Promise<number> {
     return 2;
   }
 
+  // Auto-load ./.env.yaml from cwd when --env not given and the searchDir env
+  // file produced nothing. Useful when running with absolute test paths from
+  // a collection cwd (e.g. APPLY agents in the auto-loop).
+  if (!options.env && Object.keys(env).length === 0) {
+    const cwd = process.cwd();
+    const cwdEnvPath = `${cwd}/.env.yaml`;
+    // Avoid double-load if cwd is already covered by searchDir or its parent
+    const alreadyCovered = cwd === searchDir || cwd === dirname(searchDir);
+    if (!alreadyCovered) {
+      try {
+        const cwdVars = await loadEnvFile(cwdEnvPath);
+        if (cwdVars && Object.keys(cwdVars).length > 0) {
+          env = { ...cwdVars };
+          if (!options.json) {
+            process.stderr.write(`zond: using ./.env.yaml (cwd fallback)\n`);
+          }
+        }
+      } catch (err) {
+        printError(`Failed to load environment: ${(err as Error).message}`);
+        return 2;
+      }
+    }
+  }
+
+  if (options.sessionId && !options.json) {
+    process.stderr.write(`zond: session ${options.sessionId} (run will be grouped)\n`);
+  }
+
   // Inject CLI auth token — overrides env file value
   if (options.authToken) {
     env.auth_token = options.authToken;
@@ -137,6 +342,167 @@ export async function runCommand(options: RunOptions): Promise<number> {
     }
   }
 
+  // 3b. Resolve rate limit: CLI flag > .env.yaml `rateLimit:` > workspace
+  // `defaults.rate_limit` (TASK-301) > undefined.
+  let envRateLimit: number | "auto" | undefined;
+  try {
+    envRateLimit = (await loadEnvMeta(options.env, searchDir)).rateLimit;
+  } catch { /* meta load failure is non-fatal */ }
+  const rateLimit = resolveRateLimit(options.rateLimit, envRateLimit);
+  // ARV-64 (feedback round-01 / F4): when no rate-limit was configured
+  // explicitly, default to an adaptive limiter. Adaptive is a no-op until
+  // a response carries RateLimit-* headers (RFC 9568) — in which case it
+  // learns the policy and throttles subsequent requests so a burst can't
+  // blow through small windows like small windows (e.g. 5 req/s). Without this default
+  // `zond run` ignored server-published rate-limit headers entirely and
+  // 22% of a typical sweep landed in 429.
+  let rateLimiter: ReturnType<typeof createAdaptiveRateLimiter> | undefined;
+  if (rateLimit === "auto") {
+    rateLimiter = createAdaptiveRateLimiter();
+  } else if (rateLimit !== undefined) {
+    rateLimiter = createRateLimiter(rateLimit);
+  } else {
+    rateLimiter = createAdaptiveRateLimiter();
+  }
+
+  // 3c. Resolve OpenAPI spec. Explicit --spec wins; otherwise fall back to the
+  // collection record. The doc is reused for --validate-schema (TASK-50) and
+  // for spec_pointer/spec_excerpt frozen evidence (TASK-102).
+  let schemaValidator: ReturnType<typeof createSchemaValidator> | undefined;
+  let openApiDoc: unknown | undefined;
+  {
+    let specPath = options.specPath;
+    if (!specPath) {
+      try {
+        const collection = findCollectionByTestPath(primaryPath);
+        if (collection?.openapi_spec) specPath = resolveCollectionSpec(collection.openapi_spec);
+      } catch { /* DB not available — fall through */ }
+    }
+    // ARV-44: parity with ARV-33 (probe mass-assignment / security). When the
+    // user passed --api <name> together with a path, the test-path lookup
+    // above may miss (path normalisation, alias, --all merge). Fall back to
+    // lookup-by-name, then to apis/<name>/spec.json on disk.
+    if (!specPath && options.apiName) {
+      try {
+        const byName = resolveApiCollection(options.apiName, options.dbPath);
+        if (!("error" in byName) && byName.spec) specPath = byName.spec;
+      } catch { /* fall through to disk probe */ }
+      if (!specPath) {
+        try {
+          const ws = findWorkspaceRoot();
+          const onDisk = pathResolve(ws.root, "apis", options.apiName, "spec.json");
+          if (existsSync(onDisk)) specPath = onDisk;
+        } catch { /* workspace not initialised — give up silently */ }
+      }
+    }
+    // ARV-209 (R12/F11): when --validate-schema is requested but no --api was
+    // passed (explicit suite path suppresses current-api fallback at the
+    // argv-parse level), still try to derive the spec from the test path
+    // pattern `apis/<name>/tests/...`. SKILL.md DEPTH-PASS examples use that
+    // exact shape and expect the spec to resolve automatically.
+    if (!specPath && primaryPath) {
+      const m = primaryPath.replace(/\\/g, "/").match(/(?:^|\/)apis\/([^\/]+)\/tests(?:\/|$)/);
+      if (m) {
+        const apiName = m[1]!;
+        try {
+          const byName = resolveApiCollection(apiName, options.dbPath);
+          if (!("error" in byName) && byName.spec) specPath = byName.spec;
+        } catch { /* fall through to disk probe */ }
+        if (!specPath) {
+          try {
+            const ws = findWorkspaceRoot();
+            const onDisk = pathResolve(ws.root, "apis", apiName, "spec.json");
+            if (existsSync(onDisk)) specPath = onDisk;
+          } catch { /* give up silently */ }
+        }
+      }
+    }
+    if (specPath) {
+      try {
+        openApiDoc = await readOpenApiSpec(specPath);
+      } catch (err) {
+        if (options.validateSchema) {
+          printError(`Failed to load OpenAPI spec '${specPath}': ${(err as Error).message}`);
+          return 2;
+        }
+        // spec_pointer is best-effort — non-fatal when spec can't be loaded.
+        printWarning(`Failed to load OpenAPI spec '${specPath}' for spec_pointer evidence: ${(err as Error).message}`);
+      }
+    }
+    // TASK-282: --learn requires schema validation evidence (status mismatch
+    // is only a "drift" if the body actually matches the OpenAPI contract —
+    // otherwise we'd silently encourage masking a real schema bug).
+    const needsSchema = options.validateSchema || options.learn;
+    if (needsSchema) {
+      if (!openApiDoc) {
+        const flag = options.learn ? "--learn" : "--validate-schema";
+        printError(
+          `${flag} requires --spec <path|url> or a collection with openapi_spec set. ` +
+          `Pass \`--api <name>\` (resolves apis/<name>/spec.json) or add \`--spec apis/<name>/spec.json\` explicitly.`,
+        );
+        return 2;
+      }
+      schemaValidator = createSchemaValidator(openApiDoc as Parameters<typeof createSchemaValidator>[0]);
+    }
+  }
+
+  // TASK-282: validate --learn flag combinations early (before run).
+  if (options.learnApply && !options.learn) {
+    printError("--learn-apply requires --learn");
+    return 2;
+  }
+  if (options.learnApply && !options.learnTarget) {
+    printError("--learn-apply requires --learn-target=test or --learn-target=drifts");
+    return 2;
+  }
+
+  // ARV-249: shared HTTP-request budget. `Infinity` means uncapped.
+  const requestBudget = options.maxRequests !== undefined && options.maxRequests > 0
+    ? { limit: options.maxRequests, used: 0 }
+    : undefined;
+
+  // ARV-249: progress reporter. Enabled when stderr is a TTY and the user
+  // hasn't opted out via --quiet. Suppressed for non-interactive output
+  // (CI logs already track timestamps; an extra line every 5s is noise).
+  const progressEnabled = !options.quiet
+    && !options.dryRun
+    && Boolean((process.stderr as { isTTY?: boolean }).isTTY);
+  const totalStepsForProgress = progressEnabled
+    ? estimateTotalSteps(suites)
+    : 0;
+  const tracker = progressEnabled
+    ? new ProgressTracker(totalStepsForProgress)
+    : undefined;
+  let lastProgressLineLen = 0;
+  const writeProgressLine = (final: boolean): void => {
+    if (!tracker) return;
+    const snap = tracker.snapshot();
+    // Hold off on the first emit until the run has actually been running
+    // a while — short test suites should stay silent.
+    if (!final && snap.elapsedMs < PROGRESS_QUIET_MS) return;
+    const line = formatProgressLine(snap);
+    // Overwrite previous line in place (single TTY row, no scroll).
+    const pad = " ".repeat(Math.max(0, lastProgressLineLen - line.length));
+    process.stderr.write(`\r${line}${pad}${final ? "\n" : ""}`);
+    lastProgressLineLen = line.length;
+  };
+  let progressInterval: ReturnType<typeof setInterval> | undefined;
+  if (tracker) {
+    progressInterval = setInterval(() => writeProgressLine(false), PROGRESS_INTERVAL_MS);
+    // Don't let the timer pin the event loop alive past run completion.
+    (progressInterval as { unref?: () => void }).unref?.();
+  }
+
+  const runOpts = {
+    rateLimiter,
+    schemaValidator,
+    networkRetries: options.retryOnNetwork,
+    requestBudget,
+    onStepDone: tracker
+      ? (step: import("../../core/runner/types.ts").StepResult) => tracker.recordStep(step)
+      : undefined,
+  };
+
   // 4. Run suites — setup suites run first (sequentially), their captures flow into regular suites
   const results: TestRunResult[] = [];
   const dryRun = options.dryRun === true;
@@ -145,8 +511,19 @@ export async function runCommand(options: RunOptions): Promise<number> {
   const regularSuites = suites.filter(s => !s.setup);
   const setupCaptures: Record<string, string> = {};
 
+  // 3d. Pre-flight variable check on setup suites — only `env` is known
+  //     (their captures don't exist yet).
+  {
+    const setupHits = preflightCheckVars(setupSuites, env);
+    emitMissingVarWarnings(setupHits);
+    if (options.strictVars && setupHits.length > 0) {
+      printError(`--strict-vars: ${setupHits.length} undefined variable reference(s) in setup suites`);
+      return 2;
+    }
+  }
+
   for (const suite of setupSuites) {
-    const result = await runSuite(suite, env, dryRun);
+    const result = await runSuite(suite, env, dryRun, runOpts);
     results.push(result);
     for (const step of result.steps) {
       for (const [k, v] of Object.entries(step.captures)) {
@@ -157,21 +534,49 @@ export async function runCommand(options: RunOptions): Promise<number> {
 
   const enrichedEnv = { ...env, ...setupCaptures };
 
+  // 3e. Pre-flight variable check on regular suites — env + setup captures
+  //     are known producers; per-suite captures/sets/parameterize handled inside.
+  {
+    const hits = preflightCheckVars(regularSuites, enrichedEnv);
+    emitMissingVarWarnings(hits);
+    if (options.strictVars && hits.length > 0) {
+      printError(`--strict-vars: ${hits.length} undefined variable reference(s)`);
+      return 2;
+    }
+  }
+
   if (options.bail) {
     // Sequential with bail at suite level
     for (const suite of regularSuites) {
-      const result = await runSuite(suite, enrichedEnv, dryRun);
+      const result = await runSuite(suite, enrichedEnv, dryRun, runOpts);
       results.push(result);
       if (!dryRun && (result.failed > 0 || result.steps.some((s) => s.status === "error"))) {
         break;
       }
     }
+  } else if (options.sequential) {
+    // Sequential without bail — run suites one by one
+    for (const suite of regularSuites) {
+      const result = await runSuite(suite, enrichedEnv, dryRun, runOpts);
+      results.push(result);
+    }
   } else {
     // Parallel
-    const all = await Promise.all(regularSuites.map((suite) => runSuite(suite, enrichedEnv, dryRun)));
+    const all = await Promise.all(regularSuites.map((suite) => runSuite(suite, enrichedEnv, dryRun, runOpts)));
     results.push(...all);
   }
 
+  // ARV-249: stop the progress tracker before any reporter output starts
+  // — overlapping carriage returns and report lines garble the terminal.
+  if (progressInterval !== undefined) {
+    clearInterval(progressInterval);
+    // Clear the in-place progress line so it doesn't linger above the report.
+    if (lastProgressLineLen > 0) {
+      process.stderr.write(`\r${" ".repeat(lastProgressLineLen)}\r`);
+      lastProgressLineLen = 0;
+    }
+  }
+
   // 5. Collect warnings
   const warnings: string[] = [];
   const rateLimited = results.flatMap(r => r.steps)
@@ -179,13 +584,119 @@ export async function runCommand(options: RunOptions): Promise<number> {
   if (rateLimited.length > 0) {
     warnings.push(`${rateLimited.length} request(s) hit rate limit (429). Consider: consolidating login steps, adding --bail, or using retry_until with delay.`);
   }
+  // ARV-249: surface --max-requests cap when it actually fired.
+  if (requestBudget && requestBudget.used >= requestBudget.limit) {
+    const cappedSteps = results.flatMap(r => r.steps)
+      .filter(s => s.status === "skip" && s.error === "max-requests-cap-reached").length;
+    if (cappedSteps > 0) {
+      warnings.push(`--max-requests ${requestBudget.limit} cap reached; ${cappedSteps} subsequent step(s) skipped. Raise the cap or narrow the suite to cover them.`);
+    }
+  }
 
-  // 5b. Report
+  // 5b. Report — ARV-117: route through core/output's OutputSpec so
+  // `--report <format>` + `--output <path>` follow the same policy as
+  // every other command. `--output` (was `--report-out`) is honoured for
+  // any format; with `console` format it falls back to JSON in the file
+  // (most useful), matching prior behaviour.
+  let resolvedOutput;
+  try {
+    resolvedOutput = resolveOutput(RUN_OUTPUT_SPEC, {
+      report: options.report,
+      output: options.output,
+    });
+  } catch (err) {
+    if (err instanceof OutputSpecError) {
+      printError(err.message);
+      return 2;
+    }
+    throw err;
+  }
   if (!options.json) {
-    const reporter = getReporter(options.report);
-    reporter.report(results);
-    for (const w of warnings) {
-      printWarning(w);
+    if (resolvedOutput.channel === "file") {
+      const outPath = resolvedOutput.path!;
+      let content: string;
+      let label: string;
+      switch (resolvedOutput.format) {
+        case "junit":
+          content = generateJunitXml(results);
+          label = "JUnit XML";
+          break;
+        case "json":
+        default: // "console" — fall back to JSON in the file (most useful)
+          content = generateJsonReport(results);
+          label = "JSON";
+          break;
+      }
+      try {
+        await mkdir(pathDirname(outPath), { recursive: true });
+        await writeFile(outPath, content, "utf-8");
+        process.stderr.write(`zond: ${label} report written to ${outPath}\n`);
+      } catch (err) {
+        printError(`Failed to write --output file ${outPath}: ${(err as Error).message}`);
+        return 2;
+      }
+      for (const w of warnings) {
+        printWarning(w);
+      }
+    } else {
+      const reporter = getReporter(options.report);
+      reporter.report(results, options.quiet ? { quiet: true } : undefined);
+      // TASK-265: --quiet drops the warnings tail too — they are non-essential
+      // run hints (deprecation, timing). Errors still reach stderr via the
+      // dedicated path; --strict-vars still aborts on undefined refs before
+      // we get here.
+      if (!options.quiet) {
+        for (const w of warnings) {
+          printWarning(w);
+        }
+      }
+    }
+  }
+
+  // 5b. Resolve spec_pointer + spec_excerpt for steps with provenance.
+  // Frozen evidence: pointer and excerpt are computed once, against the spec
+  // doc loaded at run time, and saved into the DB so later spec edits don't
+  // rewrite history.
+  if (openApiDoc) {
+    for (const r of results) {
+      for (const s of r.steps) {
+        if (!s.provenance) continue;
+        const ptr = buildSpecPointer(s.provenance, openApiDoc);
+        if (ptr) {
+          s.spec_pointer = ptr.pointer;
+          s.spec_excerpt = ptr.excerpt;
+        }
+      }
+    }
+  }
+
+  // 5c. TASK-282: --learn — surface or apply status-code drift.
+  if (options.learn) {
+    const drifts = detectStatusDrifts(results, { schemaValidatorAttached: schemaValidator !== undefined });
+    if (!options.learnApply) {
+      process.stderr.write(formatDriftPlan(drifts));
+    } else if (drifts.length === 0) {
+      process.stderr.write("zond: --learn-apply: no drift to apply\n");
+    } else if (options.learnTarget === "test") {
+      const applied = await applyDriftsToTests(drifts);
+      process.stderr.write(`zond: --learn-apply --learn-target=test: rewrote ${applied.updated} step(s)\n`);
+      for (const e of applied.errors) {
+        printWarning(`learn-apply: ${e.suite_file} step "${e.step_name}": ${e.reason}`);
+      }
+    } else if (options.learnTarget === "drifts") {
+      // Resolve apis/<name>/ from the primary path's collection record.
+      let apiDir: string | undefined;
+      try {
+        const collection = findCollectionByTestPath(primaryPath);
+        if (collection?.base_dir) apiDir = collection.base_dir;
+        else if (collection?.test_path) apiDir = dirname(collection.test_path);
+      } catch { /* DB unavailable */ }
+      if (!apiDir) {
+        printError("--learn-target=drifts: cannot resolve apis/<name>/ — collection not registered (run `zond add api <name>`)");
+        return 2;
+      }
+      const written = await appendToleratedDrifts(apiDir, drifts);
+      process.stderr.write(`zond: --learn-apply --learn-target=drifts: wrote ${written.written} entry(ies) to ${written.file}\n`);
     }
   }
 
@@ -194,11 +705,35 @@ export async function runCommand(options: RunOptions): Promise<number> {
   if (!options.noDb) {
     try {
       getDb(options.dbPath);
-      const collection = findCollectionByTestPath(options.path);
+      const collection = findCollectionByTestPath(primaryPath);
+      // TASK-274: capture suite-level tags executed in this run (plus any
+      // explicit --tag filter). Stored on the run row so
+      // `coverage --union tag:<x>` can later select runs by tag.
+      const tagSet = new Set<string>();
+      for (const s of suites) {
+        for (const t of s.tags ?? []) tagSet.add(t);
+      }
+      for (const t of options.tag ?? []) tagSet.add(t);
+      const tags = [...tagSet].sort();
+      // TASK-116: stamp CI context on the run row when running under a
+      // detected CI environment (or when the user passed an explicit
+      // `--trigger ci`). Manual runs default to trigger=manual with no
+      // commit/branch — preserving prior behaviour.
+      const ci = detectCiContext();
+      // ARV-55: classify the run by what kinds of suite files it executed
+      // *before* INSERT, so coverage's default query becomes a simple
+      // run_kind='regular' compare instead of a per-result regex scan.
+      const runKind = detectRunKind(suites.map((s) => s.filePath ?? null));
       savedRunId = createRun({
         started_at: results[0]?.started_at ?? new Date().toISOString(),
         environment: options.env,
         collection_id: collection?.id,
+        session_id: options.sessionId,
+        trigger: ci.trigger,
+        commit_sha: ci.commit_sha ?? undefined,
+        branch: ci.branch ?? undefined,
+        ...(tags.length > 0 ? { tags } : {}),
+        run_kind: runKind,
       });
       finalizeRun(savedRunId, results);
       saveResults(savedRunId, results);
@@ -216,6 +751,23 @@ export async function runCommand(options: RunOptions): Promise<number> {
   }
   const hasFailures = results.some((r) => r.failed > 0 || r.steps.some((s) => s.status === "error"));
 
+  // ARV-105 (F10): a suite where every step was skipped (e.g. probe-emitted
+  // regression suite that needs an unfilled capture-chain var) reports
+  // total>0, passed=0, failed=0, skipped=total. Without surfacing this,
+  // CI sees "0 failed" and the run looks green even though nothing was
+  // actually tested. Compute the list once and expose it in both the
+  // JSON envelope and the stderr tail.
+  const allSkippedSuites = results
+    .filter(r => r.total > 0 && r.passed === 0 && r.failed === 0 && r.skipped === r.total)
+    .map(r => ({
+      suite: r.suite_name,
+      ...(r.suite_file ? { file: r.suite_file } : {}),
+      total: r.total,
+      // Sample skip reason from the first step — usually "missing variable
+      // {{X}}" or similar. Helps the operator route to fixtures vs spec.
+      first_skip_reason: r.steps[0]?.error ?? null,
+    }));
+
   if (options.json) {
     const total = results.reduce((s, r) => s + r.total, 0);
     const passed = results.reduce((s, r) => s + r.passed, 0);
@@ -226,11 +778,337 @@ export async function runCommand(options: RunOptions): Promise<number> {
         test: s.name,
         ...(r.suite_file ? { file: r.suite_file } : {}),
         status: s.status,
+        ...(typeof s.response?.status === "number" ? { http_status: s.response.status } : {}),
+        ...(typeof s.response?.status === "number" && s.response.status >= 500 && s.response.status < 600 ? { is_5xx: true } : {}),
         error: s.error,
+        ...(s.failure_class ? { failure_class: s.failure_class, failure_class_reason: s.failure_class_reason } : {}),
+        ...(s.provenance ? { provenance: s.provenance } : {}),
+        ...(s.spec_pointer ? { spec_pointer: s.spec_pointer, spec_excerpt: s.spec_excerpt } : {}),
+        ...(s.network_retry ? { network_retry: s.network_retry } : {}),
       }))
     );
-    printJson(jsonOk("run", { summary: { total, passed, failed }, failures, warnings, runId: savedRunId }));
+    const fiveXx = failures.filter(f => f.is_5xx).length;
+    printJson(jsonOk("run", {
+      summary: { total, passed, failed, fiveXx, allSkippedSuites: allSkippedSuites.length },
+      failures,
+      ...(allSkippedSuites.length > 0 ? { all_skipped_suites: allSkippedSuites } : {}),
+      warnings,
+      runId: savedRunId,
+    }));
+  }
+
+  // ARV-105 (F10): non-json — name the all-skipped suites on stderr so a
+  // tail-eyeballing operator notices the visibility-pitfall. Doesn't gate
+  // exit code (skipping isn't a failure) but is loud enough that a green
+  // "0 failed" can no longer hide a regression suite that ran zero steps.
+  if (allSkippedSuites.length > 0 && !options.json) {
+    process.stderr.write(`zond: ${allSkippedSuites.length} suite(s) ran with every step skipped (no test executed — likely missing fixtures or capture-chain ids).\n`);
+    for (const s of allSkippedSuites) {
+      const reason = s.first_skip_reason ? ` — ${s.first_skip_reason}` : "";
+      process.stderr.write(`  - ${s.suite}${s.file ? ` (${s.file})` : ""}: ${s.total} step(s) skipped${reason}\n`);
+    }
+  }
+
+  // ARV-162 (round-08 F19): when suites failed parse-time validation
+  // (`zond check tests` reject — e.g. form value emitted unquoted, parsed
+  // as int), per-file warnings already went to stderr at the top of the
+  // run, but they easily get lost in long output. Add a loud trailing
+  // summary so "47/68 ran" doesn't silently hide 21 invalid files.
+  if (parseErrors.length > 0 && !options.json) {
+    process.stderr.write(
+      `zond: ${parseErrors.length} test file(s) skipped due to validation errors — ` +
+      `run \`zond check tests <path>\` to see why. Coverage numbers below exclude these files.\n`,
+    );
+  }
+
+  // ARV-72 (feedback round-02 / F14): make the exit-code → failures
+  // mapping visible. Tester reported "545 failed, exit_code=0" which is
+  // not what this function returns — but the symptom is real: the reader
+  // can't tell whether the surrounding shell or a wrapper script swallowed
+  // the non-zero exit. Print a one-line tail to stderr that names the
+  // exit code so wrapper scripts that hide it become obvious. Skipped in
+  // --json so the JSON envelope stays alone on stdout (this is stderr
+  // anyway, but skip avoids confusing parsers that capture both streams).
+  if (hasFailures && !options.json) {
+    const total = results.reduce((s, r) => s + r.failed, 0);
+    process.stderr.write(`zond: ${total} test step(s) failed — exiting with code 1 (pass --no-fail-on-failures to suppress, e.g. for advisory runs).\n`);
   }
 
+  if (hasFailures && options.failOnFailures === false) {
+    return 0;
+  }
   return hasFailures ? 1 : 0;
 }
+
+import type { Command } from "commander";
+import { Option } from "commander";
+import { resolveApiCollection } from "../resolve.ts";
+import { collect, flatSplit, parseNonNegativeInt, parsePositiveInt, parseRateLimit, parseReporter } from "../argv.ts";
+import { resolveSessionId } from "../../core/context/session.ts";
+import { getApi } from "../util/api-context.ts";
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * TASK-248: when 4+ hits collapse them into one summary line per unique
+ * variable name. Below threshold the per-(suite,step) form still helps
+ * users locate the missing reference.
+ */
+function emitMissingVarWarnings(hits: import("../../core/runner/preflight-vars.ts").MissingVarHit[]): void {
+  if (hits.length === 0) return;
+  if (hits.length < 4) {
+    for (const hit of hits) printWarning(formatMissingVarLine(hit));
+    return;
+  }
+  for (const line of summarizeMissingVars(hits)) printWarning(line);
+}
+
+/**
+ * ARV-39: rewrite an ENOENT bubbling up from `parseSafe` so the user sees
+ * a clean path quote and an actionable hint. Bun's raw glob/open error
+ * quotes the path with a trailing space ("'foo.yaml '"), which makes users
+ * think the path itself has a typo. We strip the noise and, when the file's
+ * parent directory exists, suggest either the dir form (`apis/<api>/tests`)
+ * or list its YAML siblings so the right invocation is discoverable.
+ */
+function formatPathError(path: string, raw: string): string {
+  const isEnoent = /ENOENT/i.test(raw) || /no such file or directory/i.test(raw);
+  if (!isEnoent) return raw;
+  const cleanPath = path.trim();
+  const parent = pathDirname(cleanPath);
+  const lines: string[] = [`Path not found: ${cleanPath}`];
+  // Parent directory exists → list known YAML suites to make the right
+  // invocation obvious. Parent missing → just say so; nothing useful to add.
+  try {
+    if (parent && existsSync(parent) && statSync(parent).isDirectory()) {
+      const siblings = readdirSync(parent)
+        .filter((f) => /\.ya?ml$/i.test(f))
+        .sort();
+      if (siblings.length === 0) {
+        lines.push(`(${parent}/ has no YAML files — did you forget to run \`zond generate\`?)`);
+      } else {
+        // Prefer suggesting the directory itself — that's the parity command
+        // most users actually want ("run all suites under apis/<api>/tests").
+        lines.push(`Did you mean \`zond run ${parent}\` (runs ${siblings.length} suite${siblings.length === 1 ? "" : "s"})?`);
+        const preview = siblings.slice(0, 6).map((s) => `  - ${parent}/${s}`).join("\n");
+        const more = siblings.length > 6 ? `\n  … ${siblings.length - 6} more` : "";
+        lines.push(`Known suites in ${parent}/:\n${preview}${more}`);
+      }
+    }
+  } catch { /* readdir / stat failed — fall through with the basic message */ }
+  return lines.join("\n");
+}
+
+/**
+ * ARV-37: list distinct tags across loaded suites so a fail-loud `--tag`
+ * mismatch can suggest the user-facing values without forcing them into
+ * `--help`. Order is alphabetical for stable output across runs.
+ */
+function collectAvailableTags(suites: { tags?: string[] }[]): string[] {
+  const seen = new Set<string>();
+  for (const s of suites) {
+    if (!s.tags) continue;
+    for (const t of s.tags) {
+      const trimmed = t.trim();
+      if (trimmed) seen.add(trimmed);
+    }
+  }
+  return [...seen].sort();
+}
+
+/**
+ * TASK-116: discover every `apis/<name>/tests/` directory in the workspace
+ * for `zond run --all`. Skips entries without a tests/ subdir (some APIs
+ * may have probes only). Returns absolute paths so the run command resolves
+ * env files correctly even when invoked from a subdirectory.
+ */
+function discoverWorkspaceTestPaths(): { paths: string[] } | { error: string } {
+  let root: string;
+  try {
+    const ws = findWorkspaceRoot();
+    if (ws.fromFallback) {
+      return { error: "--all requires a workspace marker (zond.config.yml). Run `zond init` first." };
+    }
+    root = ws.root;
+  } catch (err) {
+    return { error: `Failed to locate workspace root: ${(err as Error).message}` };
+  }
+
+  const apisDir = join(root, "apis");
+  if (!existsSync(apisDir)) return { paths: [] };
+
+  const out: string[] = [];
+  for (const entry of readdirSync(apisDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const testsDir = join(apisDir, entry.name, "tests");
+    if (!existsSync(testsDir)) continue;
+    try {
+      if (statSync(testsDir).isDirectory()) out.push(testsDir);
+    } catch { /* skip unreadable */ }
+  }
+  return { paths: out.sort() };
+}
+
+export function registerRun(program: Command): void {
+  program
+    .command("run [paths...]")
+    .description(
+      "Run API tests. Accepts one or more file/dir paths (shell-glob friendly: zond run tests/*.yaml). " +
+      "TASK-134: this command does NOT accept `--json` (which would collide with `--report json`). " +
+      "For JSON-envelope-style output use `--report json` (per-test breakdown) or `--report junit`. " +
+      "Other commands (`request`, `coverage`, `db diagnose`, etc.) DO accept `--json` — there it returns " +
+      "a small `{ok, data, errors}` envelope. The two flags are intentionally distinct: " +
+      "`run --report json` is a test-run report, `<cmd> --json` is a query-result envelope.",
+    )
+    .option("--env <name>", "Use environment file (.env.<name>.yaml)")
+    .option("--api <name>", "Use API collection (resolves test path automatically)")
+    .addOption(
+      new Option("--report <format>", "Output format")
+        .choices(["console", "json", "junit"])
+        .default("console")
+        .argParser(parseReporter),
+    )
+    .option("--timeout <ms>", "Override request timeout", parsePositiveInt("--timeout"))
+    .option("--rate-limit <N|auto>", "Throttle requests to at most N per second, or `auto` to adapt from ratelimit-* response headers. Default: adaptive (ARV-64) — no-op until the server publishes RateLimit-* headers, then paces requests automatically. Pass a number for hard caps; `off` is not supported (set --workers 1 + no flag for sequential).", parseRateLimit)
+    .option("--bail", "Stop on first suite failure")
+    .option("--sequential", "Run regular suites one after another instead of in parallel (opt-out of Promise.all)")
+    .option("--all", "TASK-116: discover every apis/<name>/tests/ directory in the workspace and merge them into a single run row (one runs.id per CI invocation, even with multiple registered APIs). Implies CI-style aggregation; pairs with auto-detected commit_sha / branch / trigger=ci.")
+    .option("--no-db", "Do not save results to .zond/zond.db")
+    .option("--db <path>", "Path to SQLite database file (default: .zond/zond.db)")
+    .option("--auth-token <token>", "Auth token injected as {{auth_token}} variable")
+    .option("--safe", "Run only GET tests (read-only, safe mode)")
+    .option("--tag <tag>", "Filter suites by tag (repeatable, comma-separated)", collect, [])
+    .option("--exclude-tag <tag>", "Exclude suites by tag (repeatable, comma-separated)", collect, [])
+    .option("--method <method>", "Filter tests by HTTP method (e.g. GET, POST)")
+    .option(
+      "--include <spec...>",
+      "ARV-25: keep only steps matching <selector>:<value> (path|method|tag|operation-id). Same grammar as `zond generate` / `zond checks run`. Repeatable, combines with OR.",
+    )
+    .option(
+      "--exclude <spec...>",
+      "ARV-25: drop steps matching <selector>:<value>. Same grammar as --include. Excludes evaluated after includes.",
+    )
+    .option("--env-var <KEY=VALUE>", "Inject env variable (repeatable, overrides env file)", collect, [])
+    .option("--strict-vars", "Hard-fail (exit 2) when a {{var}} reference has no producer (default: warn and continue)")
+    .option("--dry-run", "Show requests without sending them (exit code always 0)")
+    .option(
+      "--quiet",
+      "TASK-265: emit only the grand-total summary line — drops per-suite/per-test detail and warning footers. Exit code (0/1) still differentiates pass/fail. For CI logs and watcher loops where step-level output is noise.",
+    )
+    .option("--output <file>", "ARV-117: write the report to a file instead of stdout. Replaces the legacy --report-out flag. With --report console, falls back to JSON in the file (machine-parseable). Path is resolved relative to cwd; parent directories are auto-created.")
+    .option("--validate-schema", "Validate JSON responses against the OpenAPI schema (recommended for CRUD runs — catches contract drift like date-format and enum mismatches; requires --spec or a collection with openapi_spec set)")
+    .option("--spec <path>", "Path or URL to OpenAPI spec used for --validate-schema (overrides the collection's openapi_spec)")
+    .option("--session-id <id>", "Group this run under a session. Resolution order: --session-id flag > ZOND_SESSION_ID env > .zond/current-session file (set by 'zond session start')")
+    .option("--learn", "TASK-282: detect status-code drift (passing-test-but-wrong-status). Implies --validate-schema. Without --learn-apply prints the plan; combine with --learn-apply --learn-target=test|drifts to mutate.")
+    .option("--learn-apply", "Apply the drift plan instead of printing it. Requires --learn and --learn-target.")
+    .addOption(
+      new Option("--learn-target <where>", "What to mutate when --learn-apply is set: rewrite expect.status in YAML (test) or append to apis/<name>/tolerated-drifts.yaml (drifts)")
+        .choices(["test", "drifts"]),
+    )
+    .option(
+      "--retry-on-network <N>",
+      "Auto-retry on transient network errors (ECONNRESET, EPIPE, socket hang up, fetch failed, timeout) — HTTP status codes (incl. 5xx) are NOT retried. Exponential backoff with jitter, base 250ms. Default 1, 0 disables.",
+      parseNonNegativeInt("--retry-on-network"),
+      1,
+    )
+    .option(
+      "--no-fail-on-failures",
+      "ARV-72: keep exit code 0 even when steps failed (advisory runs). Default: exit 1 on any failure. The stderr tail still names the count for visibility.",
+    )
+    .option(
+      "--max-requests <N>",
+      "ARV-249: hard cap on outgoing HTTP requests across the whole run. Once reached, remaining steps short-circuit to `skip` with reason `max-requests-cap-reached`. Each retry_until attempt counts as one request. Useful for sampling huge probe-suite runs and for CI time-boxing.",
+      parsePositiveInt("--max-requests"),
+    )
+    .action(async (pathArgs: string[] | undefined, opts, cmd: Command) => {
+      let paths = pathArgs ?? [];
+      // ARV-53: explicit paths or --all suppress the current-API fallback —
+      // `run path/to/test.yaml` should never silently pick up `.zond/current-api`.
+      // Otherwise resolve via cli/util/api-context.ts.
+      const apiFlag = (paths.length > 0 || opts.all === true)
+        ? (opts.api as string | undefined)
+        : getApi(cmd, opts);
+      const dbPath = typeof opts.db === "string" ? opts.db : undefined;
+
+      // TASK-116: --all expands to every apis/<name>/tests/ directory in the
+      // workspace, merging them into a single run row.
+      if (opts.all === true) {
+        const discovered = discoverWorkspaceTestPaths();
+        if ("error" in discovered) {
+          printError(discovered.error);
+          process.exitCode = 2;
+          return;
+        }
+        if (discovered.paths.length === 0) {
+          printError("--all found no apis/<name>/tests/ directories in the workspace. Run `zond add api <name>` and `zond generate` first.");
+          process.exitCode = 1;
+          return;
+        }
+        paths = discovered.paths;
+      }
+
+      if (paths.length === 0 && apiFlag) {
+        const resolved = resolveApiCollection(apiFlag, dbPath);
+        if ("error" in resolved) {
+          printError(resolved.error);
+          process.exitCode = resolved.error.startsWith("Failed") ? 2 : 1;
+          return;
+        }
+        if (!resolved.testPath) {
+          printError(`API '${apiFlag}' has no test_path`);
+          process.exitCode = 1;
+          return;
+        }
+        paths = [resolved.testPath];
+      }
+      if (paths.length === 0) {
+        printError("No path given and no current API set; run `zond use <api>`, set ZOND_API, pass --api <name>, or pass path explicitly");
+        process.exitCode = 2;
+        return;
+      }
+
+      const tags = flatSplit(opts.tag);
+      const excludeTags = flatSplit(opts.excludeTag);
+      const envVars = (opts.envVar as string[] | undefined)?.length ? (opts.envVar as string[]) : undefined;
+      const includeSpecs = (opts.include as string[] | undefined)?.length ? (opts.include as string[]) : undefined;
+      const excludeSpecs = (opts.exclude as string[] | undefined)?.length ? (opts.exclude as string[]) : undefined;
+
+      process.exitCode = await runCommand({
+        paths,
+        env: opts.env,
+        report: opts.report as ReporterName,
+        timeout: opts.timeout,
+        rateLimit: opts.rateLimit,
+        bail: opts.bail === true,
+        sequential: opts.sequential === true,
+        noDb: opts.db === false,
+        dbPath: typeof opts.db === "string" ? opts.db : undefined,
+        authToken: opts.authToken,
+        safe: opts.safe === true,
+        tag: tags,
+        excludeTag: excludeTags,
+        method: opts.method,
+        include: includeSpecs,
+        exclude: excludeSpecs,
+        envVars,
+        strictVars: opts.strictVars === true,
+        dryRun: opts.dryRun === true,
+        quiet: opts.quiet === true,
+        failOnFailures: opts.failOnFailures !== false,
+        output: typeof opts.output === "string" ? opts.output : undefined,
+        validateSchema: opts.validateSchema === true,
+        specPath: typeof opts.spec === "string" ? opts.spec : undefined,
+        apiName: apiFlag,
+        sessionId: resolveSessionId({
+          flag: typeof opts.sessionId === "string" ? opts.sessionId : null,
+          env: process.env.ZOND_SESSION_ID ?? null,
+        }) ?? undefined,
+        json: false,
+        retryOnNetwork: typeof opts.retryOnNetwork === "number" ? opts.retryOnNetwork : 1,
+        learn: opts.learn === true,
+        learnApply: opts.learnApply === true,
+        learnTarget: opts.learnTarget as "test" | "drifts" | undefined,
+        maxRequests: typeof opts.maxRequests === "number" ? opts.maxRequests : undefined,
+      });
+    });
+}