@kirrosh/zond 0.23.0 → 0.26.0

package/src/cli/commands/refresh-api.ts

@@ -22,7 +22,15 @@ import {
   SPEC_SNAPSHOT_FILENAME,
 } from "../../core/setup-api.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
-import { printError, printSuccess } from "../output.ts";
+import { printError, printSuccess, printWarning } from "../output.ts";
+import { readFileSync as readFileSyncNode } from "node:fs";
+import {
+  loadSchemaOverlay,
+  mergePatch,
+  saveSchemaOverlay,
+  applySchemaOverlay,
+  type ResponseSchemaPatch,
+} from "../../core/spec/schema-overlay.ts";
 
 export interface RefreshApiOptions {
   api: string;
@@ -32,6 +40,11 @@ export interface RefreshApiOptions {
   insecure?: boolean;
   json?: boolean;
   dbPath?: string;
+  /** ARV-176: path to a patch.schema.json (from `schema-from-runs`) to fold
+   *  into the response-schema overlay before rebuilding spec.json. */
+  mergeSchema?: string;
+  /** ARV-176: overwrite response schemas already declared upstream. */
+  force?: boolean;
 }
 
 export async function refreshApiCommand(opts: RefreshApiOptions): Promise<number> {
@@ -92,6 +105,40 @@ export async function refreshApiCommand(opts: RefreshApiOptions): Promise<number
   // 3. Determine baseUrl from the doc
   const baseUrl = ((doc as any).servers?.[0]?.url as string | undefined) ?? "";
 
+  // ARV-176: response-schema overlay. Fold a --merge-schema patch into the
+  // persistent overlay first, then apply the (possibly-updated) overlay onto
+  // the freshly-pulled doc *before* it's serialised to spec.json. Applying on
+  // every refresh (not only when --merge-schema is passed) is what makes the
+  // overlay survive an upstream re-pull (AC#2).
+  let schemaReport: {
+    merged_from?: string;
+    applied: string[];
+    preserved: string[];
+    conflicts: string[];
+  } | undefined;
+  if (opts.mergeSchema) {
+    let incoming: ResponseSchemaPatch;
+    try {
+      incoming = JSON.parse(readFileSyncNode(opts.mergeSchema, "utf-8")) as ResponseSchemaPatch;
+    } catch (err) {
+      const m = `Failed to read --merge-schema "${opts.mergeSchema}": ${(err as Error).message}`;
+      if (opts.json) printJson(jsonError("refresh-api", [m])); else printError(m);
+      return 2;
+    }
+    const merged = mergePatch(loadSchemaOverlay(baseDir), incoming);
+    saveSchemaOverlay(baseDir, merged);
+  }
+  const overlay = loadSchemaOverlay(baseDir);
+  if (overlay) {
+    const r = applySchemaOverlay(doc, overlay, { force: opts.force === true });
+    schemaReport = {
+      ...(opts.mergeSchema ? { merged_from: opts.mergeSchema } : {}),
+      applied: r.applied,
+      preserved: r.preserved,
+      conflicts: r.conflicts,
+    };
+  }
+
   // 4. Write spec.json + 3 artifacts
   writeArtifactsFromDoc({
     doc,
@@ -117,6 +164,7 @@ export async function refreshApiCommand(opts: RefreshApiOptions): Promise<number
     pulledFrom: usedExternal ? specSource : null,
     endpointCount,
     artifacts: [".api-catalog.yaml", ".api-resources.yaml", ".api-fixtures.yaml"],
+    ...(schemaReport ? { schema_overlay: schemaReport } : {}),
   };
 
   if (opts.json) {
@@ -125,6 +173,12 @@ export async function refreshApiCommand(opts: RefreshApiOptions): Promise<number
     printSuccess(`Refreshed '${collection.name}' (${endpointCount} endpoints)${usedExternal ? ` from ${specSource}` : ""}`);
     process.stdout.write(`  spec: ${localSpec}\n`);
     process.stdout.write(`  artifacts: ${result.artifacts.join(", ")}\n`);
+    if (schemaReport) {
+      process.stdout.write(`  schema overlay: ${schemaReport.applied.length} applied, ${schemaReport.preserved.length} preserved, ${schemaReport.conflicts.length} conflict(s)\n`);
+      for (const c of schemaReport.conflicts) {
+        printWarning(`schema overlay conflict (endpoint not in upstream, skipped): ${c}`);
+      }
+    }
     process.stdout.write(`  Run \`zond doctor --api ${collection.name}\` to verify fixtures.\n`);
   }
   return 0;
@@ -156,12 +210,16 @@ export function registerRefreshApi(program: Command): void {
     .description("Re-snapshot the OpenAPI spec into apis/<name>/spec.json and regenerate the 3 artifacts (catalog/resources/fixtures)")
     .option("--spec <path>", "Pull fresh from this path or URL (overrides registered source)")
     .option("--insecure", "Allow self-signed TLS when --spec is an https URL")
+    .option("--merge-schema <path>", "ARV-176: fold a patch.schema.json (from `zond schema-from-runs`) into the persistent response-schema overlay (.api-schema.local.yaml) and apply it to spec.json. The overlay survives future refreshes.")
+    .option("--force", "ARV-176: overwrite response schemas already declared upstream (default: only fill gaps).")
     .option("--db <path>", "Path to SQLite database file")
     .action(async (name: string, opts, cmd: Command) => {
       process.exitCode = await refreshApiCommand({
         api: name,
         spec: opts.spec,
         insecure: opts.insecure === true,
+        mergeSchema: typeof opts.mergeSchema === "string" ? opts.mergeSchema : undefined,
+        force: opts.force === true,
         dbPath: typeof opts.db === "string" ? opts.db : undefined,
         json: globalJson(cmd),
       });

package/src/cli/commands/report-bundle.ts

@@ -49,7 +49,6 @@ interface BundleEntry {
   caseStudy?: string;
   htmlReport?: string;
   diagnose?: string;
-  agentDirective?: string | null;
 }
 
 export function parseBundleRange(input: string): number[] | { error: string } {
@@ -186,7 +185,6 @@ export async function reportBundleCommand(options: ReportBundleOptions): Promise
       const file = join(runDir, "diagnose.json");
       await Bun.write(file, JSON.stringify(diag, null, 2));
       entry.diagnose = file;
-      entry.agentDirective = (diag as unknown as { agent_directive?: string }).agent_directive ?? null;
     }
 
     entries.push(entry);
@@ -214,7 +212,6 @@ export async function reportBundleCommand(options: ReportBundleOptions): Promise
           caseStudy: e.caseStudy ?? null,
           htmlReport: e.htmlReport ?? null,
           diagnose: e.diagnose ?? null,
-          agentDirective: e.agentDirective ?? null,
         })),
         skipped,
       }),
@@ -284,8 +281,8 @@ function renderIndex(entries: BundleEntry[], skipped: Array<{ runId: number; rea
   lines.push(`Generated: ${new Date().toISOString()}`);
   lines.push(`Runs: ${entries.length}` + (skipped.length > 0 ? ` (skipped: ${skipped.length})` : ""));
   lines.push("");
-  lines.push("| Run | Spec | Total | Pass | Fail | Skip | Artefacts | Directive |");
-  lines.push("|----:|------|------:|-----:|-----:|-----:|-----------|-----------|");
+  lines.push("| Run | Spec | Total | Pass | Fail | Skip | Artefacts |");
+  lines.push("|----:|------|------:|-----:|-----:|-----:|-----------|");
 
   for (const e of entries) {
     const links: string[] = [];
@@ -293,7 +290,7 @@ function renderIndex(entries: BundleEntry[], skipped: Array<{ runId: number; rea
     if (e.htmlReport) links.push(`[html](${rel(e.htmlReport)})`);
     if (e.diagnose) links.push(`[diagnose](${rel(e.diagnose)})`);
     lines.push(
-      `| ${e.runId} | ${e.spec ?? "—"} | ${e.totals.total} | ${e.totals.passed} | ${e.totals.failed} | ${e.totals.skipped} | ${links.join(" · ") || "—"} | ${truncate(e.agentDirective ?? "", 80)} |`,
+      `| ${e.runId} | ${e.spec ?? "—"} | ${e.totals.total} | ${e.totals.passed} | ${e.totals.failed} | ${e.totals.skipped} | ${links.join(" · ") || "—"} |`,
     );
   }
 
@@ -311,8 +308,3 @@ function rel(p: string): string {
   const tail = seg.slice(-2);
   return tail.join("/");
 }
-
-function truncate(s: string, n: number): string {
-  if (s.length <= n) return s.replace(/\n/g, " ");
-  return s.slice(0, n - 1).replace(/\n/g, " ") + "…";
-}

package/src/cli/commands/request.ts

@@ -9,6 +9,7 @@ import { resolveCollectionSpec } from "../../core/setup-api.ts";
 import { findCollectionByNameOrId } from "../../db/queries.ts";
 import { getDb } from "../../db/schema.ts";
 import type { AssertionResult } from "../../core/runner/types.ts";
+import { applyEnvWrites } from "./fixtures.ts";
 
 // TASK-272: when the request fails authentication (401/403) and the user
 // did NOT pass `--api <name>`, surface a one-liner pointing at auto-auth via
@@ -86,6 +87,10 @@ export interface RequestOptions {
   env?: string;
   api?: string;
   jsonPath?: string;
+  /** ARV-355: write the --json-path scalar into apis/<api>/.env.yaml as this
+   *  var, so a POST-create's returned id lands in a fixture in one command
+   *  (the "execute create+capture" primitive of the agent seed loop). */
+  capture?: string;
   dbPath?: string;
   json?: boolean;
   /** TASK-142: validate the response body against the OpenAPI response schema. */
@@ -109,6 +114,18 @@ interface SchemaValidationOutcome {
 
 export async function requestCommand(options: RequestOptions): Promise<number> {
   try {
+    // ARV-355: --capture needs a value to extract (--json-path) and a target
+    // .env.yaml (--api). Fail fast with an actionable message rather than
+    // silently no-op'ing mid-seed-loop.
+    if (options.capture && (!options.jsonPath || !options.api)) {
+      printError(
+        "--capture requires --json-path <path> (the field to extract) and --api <name> " +
+        "(the .env.yaml to write). E.g. `zond request POST /v1/accounts --api stripe " +
+        "--json-path id --capture account`.",
+      );
+      return 2;
+    }
+
     const headers: Record<string, string> = {};
     if (options.headers) {
       for (const h of options.headers) {
@@ -141,6 +158,20 @@ export async function requestCommand(options: RequestOptions): Promise<number> {
       form: useForm,
     });
 
+    // ARV-265 (B3): persist this ad-hoc call into runs/results when a
+    // session is active, so `zond coverage --scope audit` attributes it.
+    // No session → no DB write (mirrors `curl`-replacement intent).
+    await maybePersistAuditedRequest({
+      options,
+      method: options.method.toUpperCase(),
+      url: options.url,
+      headers,
+      body: options.body,
+      result,
+    }).catch((err) => {
+      process.stderr.write(`zond: audit persistence failed (${(err as Error).message}).\n`);
+    });
+
     let validation: SchemaValidationOutcome | null = null;
     if (options.validateSchema || options.validateAgainst) {
       validation = await runSchemaValidation(options, result);
@@ -173,6 +204,33 @@ export async function requestCommand(options: RequestOptions): Promise<number> {
       if (validation) printSchemaValidation(validation);
     }
 
+    // ARV-355: create+capture. Write the extracted json-path scalar into the
+    // api's .env.yaml so the agent seed loop can chain a created id into
+    // dependent fixtures with one command. Deterministic plumbing only — the
+    // agent decides the body/endpoint/var; zond just POSTs and captures.
+    // Gated to a 2xx response (capturing an id from an error body is a bug —
+    // the agent reads the note, revises the body, and retries).
+    if (options.capture) {
+      const v = result.body;
+      const ok2xx = result.status >= 200 && result.status < 300;
+      const scalar =
+        typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? String(v) : null;
+      if (!ok2xx || scalar === null || scalar.length === 0) {
+        process.stderr.write(
+          `zond: --capture ${options.capture} skipped — need a non-empty scalar from a 2xx response ` +
+          `(status=${result.status}, --json-path '${options.jsonPath}' → ${scalar === null ? "non-scalar/null" : "empty"}). ` +
+          `Revise the request and retry.\n`,
+        );
+      } else {
+        const envPath = join(`apis/${options.api}`, ".env.yaml");
+        const { backup } = await applyEnvWrites(envPath, { [options.capture]: scalar });
+        process.stderr.write(
+          `zond: captured ${options.capture}=${scalar} → ${envPath}` +
+          (backup ? ` (backup: ${backup})` : "") + "\n",
+        );
+      }
+    }
+
     // TASK-272: post-response auto-auth hint on 401/403 without --api
     if (
       !options.json
@@ -211,6 +269,56 @@ export async function requestCommand(options: RequestOptions): Promise<number> {
   }
 }
 
+// ──────────────────────────────────────────────
+// ARV-265 (B3): persist an ad-hoc `zond request` call into runs/results
+// so `zond coverage --scope audit` sees the HTTP touch. Only fires when
+// a session is active — outside a session, the command stays a pure
+// curl-replacement and the DB doesn't grow with one-off requests.
+// ──────────────────────────────────────────────
+
+async function maybePersistAuditedRequest(args: {
+  options: RequestOptions;
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body: string | undefined;
+  result: { status: number; headers: Record<string, string>; body: unknown; duration_ms: number };
+}): Promise<void> {
+  const { readCurrentSession } = await import("../../core/context/session.ts");
+  const session = readCurrentSession();
+  if (!session) return; // B3: outside-session calls leave no trace.
+
+  const { checksPersistEnabled, beginAuditRun, finalizeAuditRun } =
+    await import("../../core/audit/persist.ts");
+  if (!checksPersistEnabled()) return;
+
+  getDb(args.options.dbPath);
+  const collectionId = args.options.api ? findCollectionByNameOrId(args.options.api)?.id : undefined;
+  const runId = beginAuditRun({
+    runKind: "request",
+    ...(collectionId != null ? { collectionId } : {}),
+    sessionId: session.id,
+    tags: ["request", "ad-hoc"],
+  });
+  const status = args.result.status >= 200 && args.result.status < 400 ? "pass" : "fail";
+  finalizeAuditRun(runId, [
+    {
+      suiteName: "request/ad-hoc",
+      suiteFile: `apis/${args.options.api ?? "_"}/request.yaml`,
+      testName: `request::${args.method} ${args.url}`,
+      status,
+      request: { method: args.method, url: args.url, headers: args.headers, body: args.body },
+      response: {
+        status: args.result.status,
+        headers: args.result.headers,
+        body: typeof args.result.body === "string" ? args.result.body : JSON.stringify(args.result.body ?? ""),
+        duration_ms: args.result.duration_ms,
+      },
+      durationMs: args.result.duration_ms,
+    },
+  ]);
+}
+
 // ──────────────────────────────────────────────
 // TASK-142: --validate-schema / --validate-against
 // ──────────────────────────────────────────────
@@ -398,6 +506,13 @@ export function registerRequest(program: Command): void {
       "(`id=$(zond request --json-path data.id ...)`), objects/arrays as compact JSON. " +
       "With --json, embeds the extracted value as the envelope's `body` field.",
     )
+    .option(
+      "--capture <var>",
+      "ARV-355: write the --json-path scalar into apis/<api>/.env.yaml as <var> " +
+      "(requires --json-path and --api). Captures a POST-create's returned id into " +
+      "a fixture in one command, so the agent seed loop can chain dependent creates. " +
+      "Only writes on a 2xx response; a .env.yaml.bak backup is made.",
+    )
     .option("--db <path>", "Path to SQLite database file")
     .option("--validate-schema", "TASK-142: validate the response body against the OpenAPI response schema (requires --api). Endpoint is auto-resolved from the request method + URL.path; templated paths like /users/{id} are matched via regex. Falls back gracefully if no endpoint matches — pass --validate-against to override.")
     .option("--validate-against <method:path>", "TASK-142: explicit endpoint override for --validate-schema, e.g. \"GET:/users/{id}\". Use the spec template form (with \"{...}\" placeholders).")
@@ -422,6 +537,7 @@ export function registerRequest(program: Command): void {
         env: opts.env,
         api,
         jsonPath: opts.jsonPath,
+        capture: opts.capture,
         dbPath: opts.db,
         json: globalJson(cmd),
         validateSchema: opts.validateSchema === true || typeof opts.validateAgainst === "string",

package/src/cli/commands/run.ts

@@ -189,6 +189,24 @@ export async function runCommand(options: RunOptions): Promise<number> {
       return 2;
     }
     printWarning(`No test files found in ${pathList}`);
+    // ARV-357: an empty dir used to exit 0 and write NO --output file, so a
+    // scripted pipeline saw a missing file with no error to key on. Still
+    // write the requested report (empty JSON `[]` / junit tests=0 envelope)
+    // so downstream stages parse "zero tests" instead of silently skipping.
+    if (options.output) {
+      try {
+        const spec = resolveOutput(RUN_OUTPUT_SPEC, { report: options.report, output: options.output });
+        if (spec.channel === "file") {
+          const content = spec.format === "junit" ? generateJunitXml([]) : generateJsonReport([]);
+          await mkdir(pathDirname(spec.path!), { recursive: true });
+          await writeFile(spec.path!, content, "utf-8");
+          process.stderr.write(`zond: empty report written to ${spec.path!} (0 tests)\n`);
+        }
+      } catch (err) {
+        printError(`Failed to write --output file ${options.output}: ${(err as Error).message}`);
+        return 2;
+      }
+    }
     return 0;
   }
 
@@ -447,9 +465,11 @@ export async function runCommand(options: RunOptions): Promise<number> {
   }
 
   // TASK-282: validate --learn flag combinations early (before run).
+  // ARV-199: --learn-apply implies --learn — cf. `git stash apply` (no
+  // explicit `git stash` toggle required). The earlier hard error here
+  // tripped up scripted callers that only thought to pass --learn-apply.
   if (options.learnApply && !options.learn) {
-    printError("--learn-apply requires --learn");
-    return 2;
+    options.learn = true;
   }
   if (options.learnApply && !options.learnTarget) {
     printError("--learn-apply requires --learn-target=test or --learn-target=drifts");
@@ -830,8 +850,16 @@ export async function runCommand(options: RunOptions): Promise<number> {
   // --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`);
+    // ARV-318: error steps (env_issue/network — couldn't execute) also drive
+    // the non-zero exit (see hasFailures above). The old line counted only
+    // `failed`, so an all-errored run printed "0 test step(s) failed —
+    // exiting with code 1", a contradiction. Name both classes.
+    const failed = results.reduce((s, r) => s + r.failed, 0);
+    const errored = results.reduce((s, r) => s + r.steps.filter((st) => st.status === "error").length, 0);
+    const parts: string[] = [];
+    if (failed > 0) parts.push(`${failed} step(s) failed`);
+    if (errored > 0) parts.push(`${errored} step(s) errored (couldn't execute — see failure_class)`);
+    process.stderr.write(`zond: ${parts.join(", ")} — exiting with code 1 (pass --no-fail-on-failures to suppress, e.g. for advisory runs).\n`);
   }
 
   if (hasFailures && options.failOnFailures === false) {
@@ -1000,7 +1028,7 @@ export function registerRun(program: Command): void {
     .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.")
+    .option("--learn-apply", "Apply the drift plan instead of printing it. Implies --learn; still requires --learn-target=test|drifts.")
     .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"]),

package/src/cli/commands/schema-from-runs.ts

@@ -0,0 +1,128 @@
+/**
+ * ARV-175: `zond schema-from-runs` — mine 2xx response bodies from a
+ * persisted run and emit `patch.schema.json` (inferred JSON Schema per
+ * endpoint+status). Pairs with `refresh-api --merge-schema` (ARV-176).
+ */
+import { writeFile } from "node:fs/promises";
+import type { Command } from "commander";
+import { readOpenApiSpec, extractEndpoints } from "../../core/generator/index.ts";
+import { schemaFromRuns, type ResultRow } from "../../core/spec/schema-from-runs.ts";
+import { getResultsByRunId, getLatestRunId } from "../../db/queries.ts";
+import { getDb } from "../../db/schema.ts";
+import { resolveApiCollection, globalJson } from "../resolve.ts";
+import { getApi } from "../util/api-context.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { printError, printSuccess, printWarning } from "../output.ts";
+import { parsePositiveInt } from "../argv.ts";
+
+export interface SchemaFromRunsCliOptions {
+  api?: string;
+  spec?: string;
+  db?: string;
+  run?: number;
+  minSamples?: number;
+  out?: string;
+  engine?: string;
+  json?: boolean;
+}
+
+export async function schemaFromRunsCommand(
+  opts: SchemaFromRunsCliOptions,
+  cmd: Command,
+): Promise<number> {
+  const json = opts.json === true || globalJson(cmd);
+  const label = "schema-from-runs";
+
+  // ARV-175 AC#2: only `builtin` is wired. quicktype/genson would each pull
+  // a large dependency tree, which contradicts zond's minimal-deps charter.
+  const engine = (opts.engine ?? "builtin").toLowerCase();
+  if (engine !== "builtin") {
+    const msg = `--engine "${opts.engine}" is not available. Only 'builtin' is wired (quicktype/genson would add heavy deps; see src/CLAUDE.md).`;
+    if (json) printJson(jsonError(label, [msg])); else printError(msg);
+    return 2;
+  }
+
+  // Resolve spec: --spec wins, else --api / current-api collection.
+  let spec = opts.spec;
+  const apiFlag = opts.spec ? opts.api : getApi(cmd, opts as Record<string, unknown>);
+  if (!spec && apiFlag) {
+    const resolved = resolveApiCollection(apiFlag, opts.db);
+    if ("error" in resolved) {
+      if (json) printJson(jsonError(label, [resolved.error])); else printError(resolved.error);
+      return resolved.error.startsWith("Failed") ? 2 : 1;
+    }
+    if (resolved.spec) spec = resolved.spec;
+  }
+  if (!spec) {
+    const msg = "No spec: pass --spec <path> or --api <name> (or set a current API).";
+    if (json) printJson(jsonError(label, [msg])); else printError(msg);
+    return 2;
+  }
+
+  getDb(opts.db);
+  const runId = opts.run ?? getLatestRunId();
+  if (runId == null) {
+    const msg = "No runs in the database. Run `zond run` / `zond checks run` first, then re-run schema-from-runs.";
+    if (json) printJson(jsonError(label, [msg])); else printError(msg);
+    return 2;
+  }
+
+  let doc;
+  try {
+    doc = await readOpenApiSpec(spec);
+  } catch (err) {
+    const msg = `Failed to read spec at "${spec}": ${(err as Error).message}`;
+    if (json) printJson(jsonError(label, [msg])); else printError(msg);
+    return 2;
+  }
+  const endpoints = extractEndpoints(doc);
+
+  const rows = getResultsByRunId(runId) as unknown as ResultRow[];
+  const minSamples = opts.minSamples ?? 2;
+  const result = schemaFromRuns({ results: rows, endpoints, minSamples });
+
+  const emitted = result.groups.filter((g) => g.emitted);
+  const skipped = result.groups.filter((g) => !g.emitted);
+  const out = opts.out ?? "patch.schema.json";
+
+  if (emitted.length > 0) {
+    await writeFile(out, JSON.stringify(result.patch, null, 2) + "\n", "utf-8");
+  }
+
+  if (json) {
+    printJson(jsonOk(label, {
+      run_id: runId,
+      out: emitted.length > 0 ? out : null,
+      min_samples: minSamples,
+      emitted: emitted.map((g) => ({ endpoint: g.endpoint, status: g.status, samples: g.samples })),
+      skipped: skipped.map((g) => ({ endpoint: g.endpoint, status: g.status, samples: g.samples, reason: g.reason })),
+    }));
+    return 0;
+  }
+
+  if (emitted.length === 0) {
+    printWarning(`No schemas emitted from run #${runId}: no (endpoint, status) group reached --min-samples ${minSamples}. ${skipped.length} group(s) had too few 2xx JSON samples.`);
+    return 0;
+  }
+  printSuccess(`Wrote ${emitted.length} response schema(s) from run #${runId} to ${out}`);
+  for (const g of emitted) console.log(`  ${g.endpoint} → ${g.status} (${g.samples} samples)`);
+  for (const g of skipped) printWarning(`skipped ${g.endpoint} → ${g.status}: ${g.reason} (${g.samples} sample(s))`);
+  console.log(`\nNext: zond refresh-api --api <name> --merge-schema ${out}`);
+  return 0;
+}
+
+export function registerSchemaFromRuns(program: Command): void {
+  program
+    .command("schema-from-runs")
+    .description("ARV-175: infer response JSON Schemas from a run's 2xx bodies → patch.schema.json (pairs with refresh-api --merge-schema). Revives response_schema_conformance on specs that declare no response schemas.")
+    .option("--api <name>", "Registered API (spec + DB lookup)")
+    .option("--spec <path>", "Explicit OpenAPI spec path (overrides --api)")
+    .option("--run <id>", "Run id to mine (default: latest)", parsePositiveInt("--run"))
+    .option("--min-samples <n>", "Minimum 2xx samples per endpoint+status to emit (default 2)", parsePositiveInt("--min-samples"))
+    .option("--out <path>", "Output path for patch.schema.json (default: patch.schema.json)")
+    .option("--engine <name>", "Schema engine. Only 'builtin' is wired (default).", "builtin")
+    .option("--db <path>", "SQLite path")
+    .action(async (opts, cmd: Command) => {
+      process.exitCode = await schemaFromRunsCommand(opts, cmd);
+    });
+}

package/src/cli/commands/secrets.ts

@@ -0,0 +1,133 @@
+/**
+ * `zond secrets set <key> <value>` — write a raw secret into
+ * `apis/<name>/.secrets.yaml` (ARV-377). Before this, rotating an expired
+ * token meant hand-editing the gitignored file (or a python script), since
+ * `zond fixtures add` only writes `.env.yaml` and the iron rules forbid an
+ * agent reading `.secrets.yaml` directly.
+ *
+ * Two safety properties:
+ *   • the value is NEVER echoed back (stdout, stderr, or JSON envelope) —
+ *     only the key name and whether a Bearer prefix was stripped;
+ *   • a `.secrets.yaml.bak` backup is written before the file is touched,
+ *     mirroring `fixtures add --apply`.
+ *
+ * Bearer trap (ARV-367/AC3): `.secrets.yaml` holds the RAW token — zond's
+ * runner adds the scheme prefix itself (`Authorization: Bearer <token>`).
+ * A pasted `Bearer eyJ…` is therefore always a mistake, so we strip a
+ * leading `Bearer ` (case-insensitive) and warn once. `--literal` keeps the
+ * value verbatim for the rare case someone really means to store it.
+ */
+import type { Command } from "commander";
+import { join } from "node:path";
+import { copyFile } from "node:fs/promises";
+
+import { getApi, MISSING_API_MESSAGE } from "../util/api-context.ts";
+import { resolveApiCollection } from "../resolve.ts";
+import { upsertEnvLine } from "./discover.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { printError, printSuccess } from "../output.ts";
+import { globalJson } from "../resolve.ts";
+
+interface SecretsSetOptions {
+  api?: string;
+  literal?: boolean;
+  json?: boolean;
+}
+
+const BEARER_PREFIX_RE = /^\s*Bearer\s+/i;
+
+/** Normalise a pasted secret value: strip a leading `Bearer ` prefix (unless
+ *  `literal`) so `.secrets.yaml` holds the raw token zond's runner expects.
+ *  Exported for unit tests. */
+export function normalizeSecretValue(raw: string, literal?: boolean): { value: string; bearerStripped: boolean } {
+  if (!literal && BEARER_PREFIX_RE.test(raw)) {
+    return { value: raw.replace(BEARER_PREFIX_RE, ""), bearerStripped: true };
+  }
+  return { value: raw, bearerStripped: false };
+}
+
+/** Upsert one `key: "value"` line into `.secrets.yaml`, backing up first.
+ *  Exported for unit tests. */
+export async function applySecretWrite(
+  secretsPath: string,
+  key: string,
+  value: string,
+): Promise<{ backup: string | null }> {
+  const file = Bun.file(secretsPath);
+  const exists = await file.exists();
+  let text = exists ? await file.text() : "";
+  let backup: string | null = `${secretsPath}.bak`;
+  if (exists) {
+    try { await copyFile(secretsPath, backup); } catch { backup = null; }
+  } else {
+    backup = null;
+  }
+  text = upsertEnvLine(text, key, value);
+  if (!text.endsWith("\n")) text += "\n";
+  await Bun.write(secretsPath, text);
+  return { backup };
+}
+
+async function setAction(key: string, valueParts: string[], cmd: Command): Promise<void> {
+  const opts = cmd.opts<SecretsSetOptions>();
+  const json = opts.json === true || globalJson(cmd);
+
+  const fail = (m: string, code = 2) => {
+    if (json) printJson(jsonError("secrets set", [m])); else printError(m);
+    process.exit(code);
+  };
+
+  const apiName = getApi(cmd, { api: opts.api } as Record<string, unknown>);
+  if (!apiName) return fail(MISSING_API_MESSAGE);
+  const col = resolveApiCollection(apiName, undefined);
+  if ("error" in col) return fail(col.error);
+  if (!col.baseDir) return fail(`API '${apiName}' has no base_dir registered.`);
+
+  const k = key.trim();
+  if (!k) return fail("Secret key must not be empty. Usage: zond secrets set <key> <value>");
+
+  // Join variadic value parts so an unquoted `Bearer eyJ…` paste (two argv
+  // tokens) still lands as one value instead of dropping the token.
+  const rawValue = valueParts.join(" ");
+  const { value, bearerStripped } = normalizeSecretValue(rawValue, opts.literal);
+  const warnings: string[] = [];
+  if (bearerStripped) {
+    warnings.push(
+      "Stripped a leading 'Bearer ' prefix — .secrets.yaml stores the raw token; zond adds the scheme prefix itself. Pass --literal to keep it verbatim.",
+    );
+  }
+
+  const secretsPath = join(col.baseDir, ".secrets.yaml");
+  const { backup } = await applySecretWrite(secretsPath, k, value);
+
+  // NEVER echo the value — key + metadata only.
+  if (json) {
+    printJson(jsonOk("secrets set", {
+      api: apiName,
+      secrets: secretsPath,
+      key: k,
+      bearer_stripped: bearerStripped,
+      backup,
+    }, warnings));
+  } else {
+    printSuccess(`Set secret '${k}' in ${secretsPath}` + (backup ? ` (backup: ${backup})` : ""));
+    process.stdout.write("  (value not echoed)\n");
+    for (const w of warnings) process.stderr.write(`Warning: ${w}\n`);
+  }
+  process.exit(0);
+}
+
+export function registerSecrets(program: Command): void {
+  const secrets = program
+    .command("secrets")
+    .description("Manage apis/<name>/.secrets.yaml (gitignored raw secret values, TASK-170). Values are never echoed back.");
+
+  secrets
+    .command("set <key> <value...>")
+    .description("Write a secret to .secrets.yaml (with .secrets.yaml.bak backup). Auto-strips a pasted 'Bearer ' prefix unless --literal. Never prints the value.")
+    .option("--api <name>", "Registered API (apis/<name>/.secrets.yaml). Falls back to ZOND_API / .zond/current-api.")
+    .option("--literal", "Store the value verbatim; do not strip a leading 'Bearer ' prefix.")
+    .action(async (key: string, value: string[], _opts, cmd: Command) => {
+      await setAction(key, value, cmd);
+    });
+}