@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/runner/executor.ts

@@ -1,24 +1,106 @@
 import { resolve, dirname, basename } from "node:path";
-import type { TestSuite, TestStep, Environment } from "../parser/types.ts";
+import type { TestSuite, TestStep, Environment, SourceMetadata, AssertionRule } from "../parser/types.ts";
 import { substituteString, substituteStep, substituteDeep, extractVariableReferences } from "../parser/variables.ts";
-import type { TestRunResult, StepResult, HttpRequest } from "./types.ts";
+import type { TestRunResult, StepResult, HttpRequest, AssertionResult } from "./types.ts";
 import { executeRequest, type FetchOptions } from "./http-client.ts";
 import type { RateLimiter } from "./rate-limiter.ts";
-import { checkAssertions, extractCaptures } from "./assertions.ts";
+import { checkAssertions, extractCaptures, findMissedCaptures } from "./assertions.ts";
 import { evaluateExpr } from "./expr-eval.ts";
 import { applyTransform } from "./transforms.ts";
+import type { SchemaValidator } from "./schema-validator.ts";
+import { classifyFailure } from "../diagnostics/failure-class.ts";
+import { buildUrl } from "../util/url.ts";
+
+/** Shallow-merge suite-level и step-level provenance. Step перекрывает suite. */
+function mergeProvenance(
+  suiteSrc?: SourceMetadata,
+  stepSrc?: SourceMetadata,
+): SourceMetadata | null {
+  if (!suiteSrc && !stepSrc) return null;
+  return { ...(suiteSrc ?? {}), ...(stepSrc ?? {}) };
+}
 
-function buildUrl(baseUrl: string | undefined, path: string, query?: Record<string, string>): string {
-  let url = baseUrl ? `${baseUrl.replace(/\/+$/, "")}${path}` : path;
-  if (query && Object.keys(query).length > 0) {
-    const params = new URLSearchParams(query);
-    url += `?${params.toString()}`;
+/** ARV-157: build the top-level `schema_validation` summary for a step that
+ *  was run with `--validate-schema`. Mirrors the shape `zond request
+ *  --validate-schema` already produces (see src/cli/commands/request.ts);
+ *  consumers can `jq '.steps[] | .schema_validation'` instead of digging
+ *  into `assertions[] | select(.kind=="schema")`.
+ *
+ *  Returns undefined when the validator wasn't attached or the response had
+ *  no parseable JSON body — same precondition as `assertions.push(...)` at
+ *  the call site, so the summary is present iff schema actually ran. */
+function buildSchemaValidationSummary(
+  validator: SchemaValidator,
+  method: string,
+  path: string,
+  status: number,
+  schemaAssertions: AssertionResult[],
+): StepResult["schema_validation"] {
+  const ins = validator.inspect(method, path, status);
+  if (!ins.matchedEndpoint) {
+    return { result: "no-endpoint", matched_endpoint: null, matched_response_status: null, error_count: 0 };
+  }
+  if (!ins.hasJsonSchema) {
+    return {
+      result: "no-schema",
+      matched_endpoint: ins.matchedEndpoint,
+      matched_response_status: ins.matchedResponseStatus,
+      error_count: 0,
+    };
   }
-  return url;
+  const failed = schemaAssertions.filter((a) => !a.passed).length;
+  return {
+    result: failed === 0 ? "PASS" : "FAIL",
+    matched_endpoint: ins.matchedEndpoint,
+    matched_response_status: ins.matchedResponseStatus,
+    error_count: failed,
+  };
 }
 
-function makeSkippedResult(stepName: string, reason: string): StepResult {
-  return {
+/** TASK-256: turn each missed-capture (path didn't resolve in response)
+ *  into an auxiliary failed assertion. The step then fails loudly with
+ *  "capture <var>: path '<path>' not found in body" instead of producing
+ *  silent `captures: {}` that the user only notices when the next step in a
+ *  CRUD chain skips with `Depends on missing capture`. */
+function buildMissedCaptureAssertions(
+  misses: ReturnType<typeof findMissedCaptures>,
+): AssertionResult[] {
+  return misses.map((m) => ({
+    field: `capture ${m.var}`,
+    rule: m.source === "body" ? "body-path-exists" : "header-exists",
+    passed: false,
+    actual: undefined,
+    expected: `${m.source} '${m.path}' present`,
+    kind: "auxiliary",
+  }));
+}
+
+function collectChainCaptures(tests: TestStep[]): Set<string> {
+  const out = new Set<string>();
+  const visit = (rules: Record<string, AssertionRule> | undefined) => {
+    if (!rules) return;
+    for (const r of Object.values(rules)) {
+      if (r.capture) out.add(r.capture);
+      if (r.each) visit(r.each);
+      if (r.contains_item) visit(r.contains_item);
+    }
+  };
+  for (const step of tests) visit(step.expect?.body);
+  return out;
+}
+
+function emptyVarSkipReason(varName: string, chainCaptures: Set<string>): string {
+  return chainCaptures.has(varName)
+    ? `chain capture {{${varName}}} unbound (upstream step did not run or did not capture it)`
+    : `required fixture {{${varName}}} is empty`;
+}
+
+function makeSkippedResult(
+  stepName: string,
+  reason: string,
+  opts?: { cascade?: { missingCapture: string } },
+): StepResult {
+  const result: StepResult = {
     name: stepName,
     status: "skip",
     duration_ms: 0,
@@ -27,6 +109,11 @@ function makeSkippedResult(stepName: string, reason: string): StepResult {
     captures: {},
     error: reason,
   };
+  if (opts?.cascade) {
+    result.failure_class = "cascade";
+    result.failure_class_reason = `Upstream capture not produced: ${opts.cascade.missingCapture}`;
+  }
+  return result;
 }
 
 /** Interpolate {{var}} placeholders inside a test/step name. Falls back to
@@ -67,8 +154,46 @@ export function expandParameterize(params?: Record<string, unknown[]>): Record<s
 
 export interface RunSuiteOptions {
   rateLimiter?: RateLimiter;
+  /** Optional OpenAPI response-schema validator. When provided, every step's
+   *  parsed JSON body is validated against the matching schema; failures are
+   *  appended to the step's `assertions`. */
+  schemaValidator?: SchemaValidator;
+  /** TASK-144: per-step network-retry budget used by http-client for
+   *  ECONNRESET / EPIPE / `socket hang up` / `fetch failed` / abort cases.
+   *  Set by `zond run --retry-on-network <N>`. HTTP statuses are not retried
+   *  by this path. */
+  networkRetries?: number;
+  /** ARV-249: shared HTTP-request budget across all parallel suites. When
+   *  `used >= limit`, remaining steps short-circuit to `skip` with reason
+   *  `max-requests-cap-reached`. Each `retry_until` attempt counts as one
+   *  request; dry-run and set-only steps do not consume the budget. */
+  requestBudget?: RequestBudget;
+  /** ARV-249: invoked after every step completes (pass/fail/skip/error) so
+   *  the CLI can render a periodic progress line without each suite
+   *  knowing how many siblings are running in parallel. */
+  onStepDone?: (step: StepResult) => void;
 }
 
+/** ARV-249: shared `--max-requests` budget. Mutated in-place by every
+ *  parallel `runSuite` call — single-threaded JS makes the
+ *  check-then-increment race-free. `limit === Infinity` means "uncapped"
+ *  (the default). */
+export interface RequestBudget {
+  limit: number;
+  used: number;
+}
+
+/** Try to reserve one HTTP slot from the shared budget. Returns true if
+ *  the caller may proceed, false if the cap has been reached. */
+export function reserveRequest(budget: RequestBudget | undefined): boolean {
+  if (!budget) return true;
+  if (budget.used >= budget.limit) return false;
+  budget.used += 1;
+  return true;
+}
+
+export const MAX_REQUESTS_SKIP_REASON = "max-requests-cap-reached";
+
 export async function runSuite(
   suite: TestSuite,
   env: Environment = {},
@@ -78,14 +203,37 @@ export async function runSuite(
   const startedAt = new Date().toISOString();
   const steps: StepResult[] = [];
 
+  /** Push a step result, attaching provenance + failure classification. */
+  const pushStep = (result: StepResult, currentStep?: TestStep): void => {
+    const merged = mergeProvenance(suite.source, currentStep?.source);
+    if (merged !== null) result.provenance = merged;
+    const classification = classifyFailure(result);
+    if (classification) {
+      result.failure_class = classification.failure_class;
+      result.failure_class_reason = classification.failure_class_reason;
+    }
+    steps.push(result);
+    if (options.onStepDone) options.onStepDone(result);
+  };
+
   const fetchOptions: Partial<FetchOptions> = {
     timeout: suite.config.timeout,
     retries: suite.config.retries,
     retry_delay: suite.config.retry_delay,
     follow_redirects: suite.config.follow_redirects,
     rate_limiter: options.rateLimiter,
+    ...(options.networkRetries !== undefined ? { network_retries: options.networkRetries } : {}),
   };
 
+  // Names of every variable a step in this suite tries to capture from a
+  // response (expect.body.<field>.capture: <name>). When a later step
+  // references one of these and the value is empty — under --dry-run, or
+  // because the capturing step was skipped — the missing var is a chain
+  // capture, NOT a fixture in .env.yaml. Distinguishing them in the skip
+  // message stops users from chasing fixture seeding for vars that
+  // shouldn't live in .env.yaml at all.
+  const chainCaptures = collectChainCaptures(suite.tests);
+
   // parameterize cross-product → N iterations of the suite body.
   // Captures and tainted/missing sets are reset per iteration so that
   // values from one binding never leak into the next.
@@ -144,14 +292,14 @@ export async function runSuite(
         const substituted = substituteDeep(rawDirective, variables);
         variables[key] = applyTransform(substituted);
       }
-      steps.push({
+      pushStep({
         name: interpolateName(step.name, variables),
         status: "pass",
         duration_ms: 0,
         request: { method: "", url: "", headers: {} },
         assertions: [],
         captures: {},
-      });
+      }, step);
       continue;
     }
 
@@ -160,13 +308,27 @@ export async function runSuite(
     const referencedVars = extractVariableReferences(step);
     const missing = referencedVars.find((v) => missingCaptures.has(v));
     if (missing) {
-      steps.push(makeSkippedResult(interpolateName(step.name, variables), `Depends on missing capture: ${missing}`));
+      pushStep(
+        makeSkippedResult(
+          interpolateName(step.name, variables),
+          `Depends on missing capture: ${missing}`,
+          { cascade: { missingCapture: missing } },
+        ),
+        step,
+      );
       continue;
     }
     if (!step.always) {
       const tainted = referencedVars.find((v) => taintedCaptures.has(v));
       if (tainted) {
-        steps.push(makeSkippedResult(interpolateName(step.name, variables), `Depends on tainted capture: ${tainted} (use always: true on cleanup steps)`));
+        pushStep(
+          makeSkippedResult(
+            interpolateName(step.name, variables),
+            `Depends on tainted capture: ${tainted} (use always: true on cleanup steps)`,
+            { cascade: { missingCapture: tainted } },
+          ),
+          step,
+        );
         continue;
       }
     }
@@ -175,7 +337,11 @@ export async function runSuite(
     if (step.skip_if) {
       const exprAfterSubst = String(substituteString(step.skip_if, variables));
       if (evaluateExpr(exprAfterSubst)) {
-        steps.push(makeSkippedResult(interpolateName(step.name, variables), `Skipped: ${step.skip_if}`));
+        const varMatch = step.skip_if.match(/\{\{([^{}]+)\}\}/);
+        const skipMsg = varMatch
+          ? emptyVarSkipReason(varMatch[1]!.trim(), chainCaptures)
+          : step.skip_if;
+        pushStep(makeSkippedResult(interpolateName(step.name, variables), skipMsg), step);
         continue;
       }
     }
@@ -197,7 +363,7 @@ export async function runSuite(
       resolvedSuiteHeaders = suite.headers ? substituteDeep(suite.headers, variables) : undefined;
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
-      steps.push({
+      pushStep({
         name: interpolateName(step.name, variables),
         status: "error",
         duration_ms: 0,
@@ -205,7 +371,7 @@ export async function runSuite(
         assertions: [],
         captures: {},
         error: errorMsg,
-      });
+      }, step);
       // Substitution never produced a request → capture truly missing.
       if (step.expect.body) {
         for (const rule of Object.values(step.expect.body)) {
@@ -214,6 +380,25 @@ export async function runSuite(
       }
       continue;
     }
+    // Skip if any path-variable in the template resolved to empty — an empty
+    // path segment produces URLs like /repos//commits/ which always 404/500.
+    // The explicit skip_if guard only covers the first param (TASK-237);
+    // this catches all others.
+    {
+      let emptyVar: string | null = null;
+      for (const m of step.path.matchAll(/\{\{([^{}]+)\}\}/g)) {
+        const varName = m[1]!.trim();
+        const val = variables[varName];
+        if (val === "" || val === null || val === undefined) { emptyVar = varName; break; }
+      }
+      if (emptyVar) {
+        pushStep(makeSkippedResult(
+          interpolateName(step.name, variables),
+          emptyVarSkipReason(emptyVar, chainCaptures),
+        ), step);
+        continue;
+      }
+    }
     const url = buildUrl(resolvedBaseUrl, resolved.path, resolved.query);
     const headers: Record<string, string> = { ...resolvedSuiteHeaders, ...resolved.headers };
     let body: string | undefined;
@@ -249,7 +434,7 @@ export async function runSuite(
 
     // Validate absolute URL before attempting fetch
     if (!url.startsWith("http://") && !url.startsWith("https://")) {
-      steps.push({
+      pushStep({
         name: interpolateName(step.name, variables),
         status: "error",
         duration_ms: 0,
@@ -257,7 +442,7 @@ export async function runSuite(
         assertions: [],
         captures: {},
         error: `base_url is not configured — URL resolved to a relative path: "${url}". Set base_url in .env.yaml`,
-      });
+      }, step);
       if (step.expect.body) {
         for (const rule of Object.values(step.expect.body)) {
           if (rule.capture) missingCaptures.add(rule.capture);
@@ -270,7 +455,7 @@ export async function runSuite(
       const bodyPreview = formData
         ? ` [multipart: ${[...formData.keys()].length} field(s)]`
         : body ? ` ${body.slice(0, 200)}` : "";
-      steps.push({
+      pushStep({
         name: interpolateName(step.name, variables),
         status: "pass",
         duration_ms: 0,
@@ -278,7 +463,7 @@ export async function runSuite(
         assertions: [],
         captures: {},
         error: `[DRY RUN] ${resolved.method} ${url}${bodyPreview}`,
-      });
+      }, step);
       continue;
     }
 
@@ -287,10 +472,31 @@ export async function runSuite(
       const rt = step.retry_until;
       let lastStepResult: StepResult | undefined;
       for (let attempt = 0; attempt < rt.max_attempts; attempt++) {
+        if (!reserveRequest(options.requestBudget)) {
+          lastStepResult = makeSkippedResult(
+            interpolateName(step.name, variables),
+            MAX_REQUESTS_SKIP_REASON,
+          );
+          break;
+        }
         try {
           const response = await executeRequest(request, fetchOptions);
           const captures = extractCaptures(resolved.expect.body, response.body_parsed, resolved.expect.headers, response.headers);
+          const missedCaps = findMissedCaptures(resolved.expect.body, response.body_parsed, resolved.expect.headers, response.headers);
           const assertions = checkAssertions(resolved.expect, response);
+          assertions.push(...buildMissedCaptureAssertions(missedCaps));
+          let schemaValidationSummary: StepResult["schema_validation"] | undefined;
+          if (options.schemaValidator && response.body_parsed !== undefined) {
+            const schemaAssertions = options.schemaValidator.validate(resolved.method, resolved.path, response.status, response.body_parsed);
+            assertions.push(...schemaAssertions);
+            schemaValidationSummary = buildSchemaValidationSummary(
+              options.schemaValidator,
+              resolved.method,
+              resolved.path,
+              response.status,
+              schemaAssertions,
+            );
+          }
           const allPassed = assertions.every((a) => a.passed);
 
           lastStepResult = {
@@ -301,6 +507,10 @@ export async function runSuite(
             response,
             assertions,
             captures,
+            ...(response.network_retry_count && response.network_retry_count > 0
+              ? { network_retry: response.network_retry_count }
+              : {}),
+            ...(schemaValidationSummary ? { schema_validation: schemaValidationSummary } : {}),
           };
 
           // Evaluate condition with response context
@@ -331,7 +541,15 @@ export async function runSuite(
           };
         }
       }
-      if (lastStepResult) steps.push(lastStepResult);
+      if (lastStepResult) pushStep(lastStepResult, step);
+      continue;
+    }
+
+    if (!reserveRequest(options.requestBudget)) {
+      pushStep(makeSkippedResult(
+        interpolateName(step.name, variables),
+        MAX_REQUESTS_SKIP_REASON,
+      ), step);
       continue;
     }
 
@@ -352,10 +570,24 @@ export async function runSuite(
       }
 
       // Run assertions
+      const missedCaps = findMissedCaptures(resolved.expect.body, response.body_parsed, resolved.expect.headers, response.headers);
       const assertions = checkAssertions(resolved.expect, response);
+      assertions.push(...buildMissedCaptureAssertions(missedCaps));
+      let schemaValidationSummary: StepResult["schema_validation"] | undefined;
+      if (options.schemaValidator && response.body_parsed !== undefined) {
+        const schemaAssertions = options.schemaValidator.validate(resolved.method, resolved.path, response.status, response.body_parsed);
+        assertions.push(...schemaAssertions);
+        schemaValidationSummary = buildSchemaValidationSummary(
+          options.schemaValidator,
+          resolved.method,
+          resolved.path,
+          response.status,
+          schemaAssertions,
+        );
+      }
       const allPassed = assertions.every((a) => a.passed);
 
-      steps.push({
+      pushStep({
         name: interpolateName(step.name, variables),
         status: allPassed ? "pass" : "fail",
         duration_ms: response.duration_ms,
@@ -363,7 +595,11 @@ export async function runSuite(
         response,
         assertions,
         captures,
-      });
+        ...(response.network_retry_count && response.network_retry_count > 0
+          ? { network_retry: response.network_retry_count }
+          : {}),
+        ...(schemaValidationSummary ? { schema_validation: schemaValidationSummary } : {}),
+      }, step);
 
       // If step failed, captures that did extract are tainted (value is real
       // but came from a step whose other assertions failed). Always-steps may
@@ -377,7 +613,7 @@ export async function runSuite(
       }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
-      steps.push({
+      pushStep({
         name: interpolateName(step.name, variables),
         status: "error",
         duration_ms: 0,
@@ -385,7 +621,7 @@ export async function runSuite(
         assertions: [],
         captures: {},
         error: errorMsg,
-      });
+      }, step);
 
       // Network/runtime error → no response → capture truly missing.
       if (step.expect.body) {
@@ -409,15 +645,8 @@ export async function runSuite(
     passed: steps.filter((s) => s.status === "pass").length,
     failed: steps.filter((s) => s.status === "fail").length,
     skipped: steps.filter((s) => s.status === "skip").length,
+    // ARV-318: surface error steps so total = passed+failed+skipped+errored.
+    errored: steps.filter((s) => s.status === "error").length,
     steps,
   };
 }
-
-export async function runSuites(
-  suites: TestSuite[],
-  env: Environment = {},
-  dryRun = false,
-  options: RunSuiteOptions = {},
-): Promise<TestRunResult[]> {
-  return Promise.all(suites.map((suite) => runSuite(suite, env, dryRun, options)));
-}

package/src/core/runner/form-encode.ts

@@ -0,0 +1,41 @@
+/**
+ * ARV-149 / ARV-150: encode a nested JS object as
+ * `application/x-www-form-urlencoded` using bracket notation — the
+ * canonical Stripe / Rails / PHP convention for nested fields:
+ *
+ *   { address: { line1: "x", line2: "y" }, items: [{ id: 1 }, { id: 2 }] }
+ *   →  address[line1]=x&address[line2]=y&items[0][id]=1&items[1][id]=2
+ *
+ * Shared between `zond request --form`, the YAML runner's `form:` step,
+ * and the mass-assignment probe's form-bodied endpoints. The probe-side
+ * adoption (ARV-150) is what restores 265 SKIPPED Stripe endpoints.
+ */
+function appendFormParam(params: URLSearchParams, key: string, value: unknown): void {
+  if (value === null || value === undefined) return;
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) appendFormParam(params, `${key}[${i}]`, value[i]);
+  } else if (typeof value === "object") {
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      appendFormParam(params, `${key}[${k}]`, v);
+    }
+  } else {
+    params.append(key, String(value));
+  }
+}
+
+export function encodeFormBody(body: Record<string, unknown>): string {
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(body)) appendFormParam(params, k, v);
+  return params.toString();
+}
+
+/** Flatten a nested JS object to a `Record<string, string>` using the same
+ *  bracket-notation walk as `encodeFormBody`, suitable for the YAML
+ *  runner's `form:` step (which is typed as `Record<string, string>` and
+ *  serialised via `URLSearchParams`). */
+export function flattenToFormFields(body: unknown): Record<string, string> {
+  if (!body || typeof body !== "object") return {};
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(body as Record<string, unknown>)) appendFormParam(params, k, v);
+  return Object.fromEntries(params.entries());
+}

package/src/core/runner/http-client.ts

@@ -1,6 +1,34 @@
 import type { HttpRequest, HttpResponse } from "./types.ts";
 import { type RateLimiter, parseRetryAfter, parseRateLimitHeaders } from "./rate-limiter.ts";
 
+/**
+ * ARV-265: module-level audit hook for commands that don't drive their
+ * HTTP through the suite runner. Each `executeRequest` call fires the
+ * registered recorder with the final outcome (or the swallowed network
+ * error if the call exhausted its retry budget). Recorders MUST NOT
+ * throw — the http client treats them as fire-and-forget telemetry.
+ *
+ * Convention: a command sets the recorder before the live work begins,
+ * unsets it in a `finally` block. There can be at most one recorder at
+ * a time; nesting is a bug (we surface it on stderr but keep the inner
+ * recorder so the live command's results take precedence).
+ */
+export interface AuditRecord {
+  request: HttpRequest;
+  response?: HttpResponse;
+  durationMs: number;
+  error?: string;
+}
+
+let _auditRecorder: ((rec: AuditRecord) => void) | null = null;
+
+export function setHttpAuditRecorder(recorder: ((rec: AuditRecord) => void) | null): void {
+  if (recorder && _auditRecorder) {
+    process.stderr.write("zond: nested HTTP audit recorder — overriding the outer scope.\n");
+  }
+  _auditRecorder = recorder;
+}
+
 export interface FetchOptions {
   timeout: number;
   retries: number;
@@ -9,17 +37,69 @@ export interface FetchOptions {
   rate_limiter?: RateLimiter;
   rate_limit_retries: number;
   rate_limit_max_delay_ms: number;
+  /** TASK-144: number of network-level retries (ECONNRESET, EPIPE, socket hang
+   *  up, fetch failed without HTTP response, timeout without response). HTTP
+   *  status codes are NEVER retried by this path. Exponential backoff with
+   *  jitter, base = `network_retry_base_ms`. Default 0 (CLI sets it to 1). */
+  network_retries: number;
+  network_retry_base_ms: number;
+  network_retry_max_delay_ms: number;
 }
 
-export const DEFAULT_FETCH_OPTIONS: FetchOptions = {
+const DEFAULT_FETCH_OPTIONS: FetchOptions = {
   timeout: 30000,
   retries: 0,
   retry_delay: 1000,
   follow_redirects: true,
   rate_limit_retries: 5,
   rate_limit_max_delay_ms: 30000,
+  network_retries: 0,
+  network_retry_base_ms: 250,
+  network_retry_max_delay_ms: 8000,
 };
 
+/**
+ * Recognise transient TCP/transport-level errors that warrant a retry. We
+ * deliberately do NOT include HTTP status codes — a 5xx is a real response
+ * the server chose to send, not a flaky socket. Patterns cover Node/Bun
+ * error codes (`ECONNRESET`, `EPIPE`, `ECONNREFUSED`, `ETIMEDOUT`,
+ * `EAI_AGAIN`), the WHATWG `fetch failed` wrapper Bun throws, classic
+ * `socket hang up`, and `AbortError` raised by our own timeout watchdog.
+ */
+export function isTransientNetworkError(err: unknown): boolean {
+  if (!err) return false;
+  const e = err as { code?: string; cause?: unknown; name?: string; message?: string };
+  const code = e.code ?? (e.cause as { code?: string } | undefined)?.code;
+  if (code) {
+    if (
+      code === "ECONNRESET" ||
+      code === "EPIPE" ||
+      code === "ECONNREFUSED" ||
+      code === "ETIMEDOUT" ||
+      code === "EAI_AGAIN" ||
+      code === "ENOTFOUND" ||
+      code === "ENETUNREACH"
+    ) {
+      return true;
+    }
+  }
+  const msg = (e.message ?? String(err)).toLowerCase();
+  if (e.name === "AbortError" || msg.includes("aborted")) return true;
+  if (msg.includes("socket hang up")) return true;
+  if (msg.includes("fetch failed")) return true;
+  if (msg.includes("connection reset") || msg.includes("econnreset")) return true;
+  if (msg.includes("epipe")) return true;
+  if (msg.includes("network error")) return true;
+  return false;
+}
+
+/** Exponential backoff with full jitter (AWS-style): pick uniformly in
+ *  [0, min(cap, base * 2^attempt)). Returns ms. */
+export function networkBackoffMs(attempt: number, baseMs: number, capMs: number): number {
+  const exp = Math.min(capMs, baseMs * 2 ** attempt);
+  return Math.floor(Math.random() * exp);
+}
+
 export async function executeRequest(
   request: HttpRequest,
   options?: Partial<FetchOptions>,
@@ -27,6 +107,7 @@ export async function executeRequest(
   const opts = { ...DEFAULT_FETCH_OPTIONS, ...options };
   let lastError: Error | undefined;
   let networkAttempt = 0;
+  let networkRetryCount = 0;
   let rate429Attempt = 0;
 
   while (true) {
@@ -100,14 +181,43 @@ export async function executeRequest(
         }
       }
 
-      return { status: response.status, headers, body: bodyText, body_parsed, duration_ms };
+      const httpResp: HttpResponse = {
+        status: response.status,
+        headers,
+        body: bodyText,
+        body_parsed,
+        duration_ms,
+        network_retry_count: networkRetryCount,
+      };
+      if (_auditRecorder) {
+        try { _auditRecorder({ request, response: httpResp, durationMs: duration_ms }); }
+        catch { /* recorder is fire-and-forget */ }
+      }
+      return httpResp;
     } catch (err) {
       lastError = err instanceof Error ? err : new Error(String(err));
+      const isNet = isTransientNetworkError(lastError);
+      // TASK-144 path: dedicated network-retry budget with exp+jitter backoff.
+      if (isNet && networkRetryCount < opts.network_retries) {
+        const wait = networkBackoffMs(
+          networkRetryCount,
+          opts.network_retry_base_ms,
+          opts.network_retry_max_delay_ms,
+        );
+        networkRetryCount++;
+        await Bun.sleep(wait);
+        continue;
+      }
+      // Legacy linear path (yaml suite.config.retries).
       if (networkAttempt < opts.retries) {
         networkAttempt++;
         await Bun.sleep(opts.retry_delay);
         continue;
       }
+      if (_auditRecorder) {
+        try { _auditRecorder({ request, durationMs: 0, error: lastError.message }); }
+        catch { /* recorder is fire-and-forget */ }
+      }
       throw lastError;
     }
   }