@qatonic_innovations/qaios 0.3.2 → 0.4.1

package/dist/index.js

@@ -3,13 +3,14 @@ import { useApp, useInput, Box, Text } from 'ink';
 import { useState } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { realpathSync, readFileSync, existsSync, rmSync, mkdirSync, writeFileSync, statSync, mkdtempSync, copyFileSync, readdirSync } from 'fs';
-import path12 from 'path';
+import path15 from 'path';
 import { fileURLToPath } from 'url';
 import { Command, InvalidArgumentError } from 'commander';
-import { createHash } from 'crypto';
-import { createRequire } from 'module';
 import { z, ZodError } from 'zod';
 import { monotonicFactory } from 'ulid';
+import { gzipSync, gunzipSync } from 'zlib';
+import { createHash } from 'crypto';
+import { createRequire } from 'module';
 import Anthropic from '@anthropic-ai/sdk';
 import OpenAI from 'openai';
 import { zodToJsonSchema } from 'zod-to-json-schema';
@@ -384,6 +385,13 @@ var AuditEvent = z.enum([
   "execution.started",
   "execution.completed",
   "execution.failed",
+  // xray (network capture) — hash-chained like everything else.
+  "xray.capture",
+  // a net_run + its requests were persisted
+  "xray.diff",
+  // a run was diffed against a baseline
+  "xray.baseline.set",
+  // a baseline was pinned/cleared
   "audit.verified",
   "system.config_changed"
 ]);
@@ -587,6 +595,10 @@ var ResultClassification = z.object({
     "environmental",
     "locator_broken",
     "expectation_outdated",
+    // The UI behaved but the BACKEND diverged from its baseline contract — a
+    // 4xx/5xx, status change, or response-shape change on a call the test made.
+    // Sourced from xray's network diff (v0.4). Routes to create_defect.
+    "backend_divergence",
     "unknown"
   ]),
   confidence: z.number().min(0).max(1),
@@ -878,8 +890,11 @@ var QaiosConfig = z.object({
     }).default({}),
     // Lower-bounded: a 0/negative cap would silently disable enforcement.
     maxRetriesPerSkill: z.number().int().nonnegative().default(2),
-    maxLlmCallsPerWorkflow: z.number().int().positive().default(15),
-    costAlertThresholdUsdCents: z.number().int().positive().default(50)
+    // Raised from 15/50¢ after real-app e2e — a real OpenAPI spec or complex
+    // site legitimately costs ~$0.70 to generate from, so the old cap aborted
+    // valid single-feature generation. Still a runaway-loop guard.
+    maxLlmCallsPerWorkflow: z.number().int().positive().default(20),
+    costAlertThresholdUsdCents: z.number().int().positive().default(100)
   }).default({}),
   testing: z.object({
     framework: z.literal("playwright").default("playwright"),
@@ -925,6 +940,31 @@ var QaiosConfig = z.object({
   telemetry: z.object({
     enabled: z.boolean().default(false),
     endpoint: z.string().default("https://telemetry.qaios.dev/v1")
+  }).default({}),
+  // Network capture + API-divergence (`qaios run --xray`, `qaios explore`).
+  // Safe to `.default({})`: every field has a defaulted scalar/array (no
+  // optional probe like `app`), so `qaios init` serializes a complete block,
+  // not a stub. `enabled: false` keeps capture opt-in for v0.4 — the `--xray`
+  // flag turns it on per-run regardless. See QAIOS xray spec §9.
+  xray: z.object({
+    enabled: z.boolean().default(false),
+    level: z.enum(["off", "headers", "summary", "full"]).default("summary"),
+    // Quiet window after an action with no new request before a step's
+    // network window closes (capped at 15s by the causality engine).
+    quiescenceMs: z.number().int().positive().default(500),
+    // Response bodies above this are hashed/shape-summarized but not stored.
+    // Spec: 16 at summary, 256 at full — the resolver bumps it when level=full.
+    bodyMaxKb: z.number().int().positive().default(16),
+    // Extends the built-in volatile-query-param denylist (t, ts, nonce, …).
+    volatileParams: z.array(z.string()).default([]),
+    // JSONPaths redacted (→ "<redacted>") BEFORE hashing/storage, so secrets
+    // never touch disk. The header denylist (authorization, cookie, …) is
+    // always applied regardless.
+    redact: z.array(z.string()).default([]),
+    // Glob hosts whose traffic is dropped at capture time (analytics noise).
+    ignoreHosts: z.array(z.string()).default([]),
+    // Raw rows retained per (test, browser) beyond baselines; older pruned.
+    retainRuns: z.number().int().positive().default(10)
   }).default({})
 });
 var RunStatus = z.enum(["running", "passed", "failed", "mixed", "errored", "flaky"]);
@@ -964,6 +1004,101 @@ z.object({
   // serialized to value_json
   updatedAt: z.string()
 });
+var XrayTier = z.enum(["A", "B"]);
+var XrayCaptureLevel = z.enum(["off", "headers", "summary", "full"]);
+var XrayAttribution = z.enum([
+  "initiator",
+  // Tier-A initiator stack tied into a step window
+  "temporal",
+  // started inside exactly one open step window
+  "temporal_ambiguous",
+  // inside multiple overlapping windows → most-recent
+  "background"
+  // no step window (polling/analytics/heartbeats)
+]);
+var XrayTargetType = z.enum(["page", "iframe", "service_worker"]);
+var XrayBodyStatus = z.enum(["stored", "evicted", "truncated", "streaming", "skipped"]);
+var XrayRequestEvent = z.object({
+  method: z.string(),
+  url: z.string(),
+  // HAR `_initiator` is coarse (type + optional url); no deep stack. Kept for
+  // forward-compat with an opt-in initiator fixture; null for HAR capture.
+  initiator: z.object({
+    type: z.string(),
+    // script|parser|preload|other|...
+    url: z.string().nullable().default(null)
+  }).nullable().default(null),
+  status: z.number().int().nullable().default(null),
+  errorText: z.string().nullable().default(null),
+  // populated for failed entries
+  mime: z.string().nullable().default(null),
+  fromServiceWorker: z.boolean().default(false),
+  fromDiskCache: z.boolean().default(false),
+  // Raw bodies as captured (subject to level/MIME/size gates). The runtime
+  // canonicalizes + redacts + hashes these; they never round-trip raw.
+  reqBody: z.string().nullable().default(null),
+  respBody: z.string().nullable().default(null),
+  bodyStatus: XrayBodyStatus.default("skipped"),
+  redirects: z.array(z.object({ url: z.string(), status: z.number().int() })).default([]),
+  timings: z.record(z.string(), z.number()).default({}),
+  // dns/connect/ttfb/total ms
+  wallStart: z.number()
+  // epoch ms — drives temporal attribution + display
+});
+z.object({
+  stepId: z.string(),
+  title: z.string(),
+  category: z.string(),
+  // 'pw:api' | 'test.step' | ...
+  startWall: z.number(),
+  // epoch ms
+  endWall: z.number()
+  // epoch ms
+});
+var NetRunRow = z.object({
+  runId: z.string(),
+  workflowId: z.string(),
+  testId: z.string(),
+  browser: z.string(),
+  tier: XrayTier,
+  captureLevel: XrayCaptureLevel,
+  startedAt: z.string(),
+  isGreen: z.boolean().default(false),
+  isBaseline: z.boolean().default(false)
+});
+var NetRequestRow = z.object({
+  id: z.string(),
+  runId: z.string(),
+  stepId: z.string().nullable(),
+  attribution: XrayAttribution,
+  targetType: XrayTargetType,
+  method: z.string(),
+  urlRaw: z.string(),
+  urlTemplate: z.string(),
+  gqlOperation: z.string().nullable(),
+  identityKey: z.string(),
+  status: z.number().int().nullable(),
+  errorText: z.string().nullable(),
+  mime: z.string().nullable(),
+  reqHash: z.string().nullable(),
+  respHash: z.string().nullable(),
+  shapeHash: z.string().nullable(),
+  reqBodyRef: z.string().nullable(),
+  respBodyRef: z.string().nullable(),
+  bodyStatus: XrayBodyStatus.nullable(),
+  redirectsJson: z.string().nullable(),
+  timingsJson: z.string().nullable(),
+  initiatorJson: z.string().nullable(),
+  wallStart: z.string()
+});
+var NetVolatilityRow = z.object({
+  testId: z.string(),
+  identityKey: z.string(),
+  jsonPath: z.string(),
+  // '' => presence-level
+  kind: z.enum(["value", "presence"]),
+  learnedAt: z.string()
+});
 var ulidImpl = monotonicFactory();
 function ulid() {
   return ulidImpl();
@@ -998,6 +1133,12 @@ var LlmError = class extends QaiosError {
     this.name = "LlmError";
   }
 };
+var XrayError = class extends QaiosError {
+  constructor(opts) {
+    super(opts);
+    this.name = "XrayError";
+  }
+};
 function isQaiosShaped(err) {
   if (!err || typeof err !== "object") return false;
   const e = err;
@@ -1054,6 +1195,1376 @@ function formatQaiosError(err, opts = {}) {
   }
   return lines.join("\n") + "\n";
 }
+var __defProp2 = Object.defineProperty;
+var __getOwnPropNames2 = Object.getOwnPropertyNames;
+var __esm2 = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames2(fn)[0]])(fn = 0)), res;
+};
+var __export2 = (target, all) => {
+  for (var name in all)
+    __defProp2(target, name, { get: all[name], enumerable: true });
+};
+function rowToNetRun(row) {
+  return NetRunRow.parse({
+    runId: row.run_id,
+    workflowId: row.workflow_id,
+    testId: row.test_id,
+    browser: row.browser,
+    tier: row.tier,
+    captureLevel: row.capture_level,
+    startedAt: row.started_at,
+    isGreen: row.is_green === 1,
+    isBaseline: row.is_baseline === 1
+  });
+}
+var NetRunsRepository;
+var init_net_runs = __esm2({
+  "src/storage/repositories/net-runs.ts"() {
+    NetRunsRepository = class {
+      constructor(db) {
+        this.db = db;
+      }
+      db;
+      create(input) {
+        const r = NetRunRow.parse(input);
+        this.db.prepare(
+          `INSERT INTO net_runs
+          (run_id, workflow_id, test_id, browser, tier, capture_level,
+           started_at, is_green, is_baseline)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        ).run(
+          r.runId,
+          r.workflowId,
+          r.testId,
+          r.browser,
+          r.tier,
+          r.captureLevel,
+          r.startedAt,
+          r.isGreen ? 1 : 0,
+          r.isBaseline ? 1 : 0
+        );
+        return r;
+      }
+      findById(runId) {
+        const row = this.db.prepare("SELECT * FROM net_runs WHERE run_id = ?").get(runId);
+        return row ? rowToNetRun(row) : null;
+      }
+      listByWorkflow(workflowId) {
+        const rows = this.db.prepare("SELECT * FROM net_runs WHERE workflow_id = ? ORDER BY started_at DESC").all(workflowId);
+        return rows.map(rowToNetRun);
+      }
+      /**
+       * Runs for a test, newest first. Used by baseline selection (last green per
+       * test+browser) and volatility learning (compare consecutive green runs).
+       */
+      listByTest(testId, browser) {
+        const sql = browser === void 0 ? "SELECT * FROM net_runs WHERE test_id = ? ORDER BY started_at DESC" : "SELECT * FROM net_runs WHERE test_id = ? AND browser = ? ORDER BY started_at DESC";
+        const rows = browser === void 0 ? this.db.prepare(sql).all(testId) : this.db.prepare(sql).all(testId, browser);
+        return rows.map(rowToNetRun);
+      }
+      /** Flip green/baseline flags as the run is finalized / a baseline is pinned. */
+      update(runId, patch) {
+        const fields = [];
+        const params = [];
+        if (patch.isGreen !== void 0) {
+          fields.push("is_green = ?");
+          params.push(patch.isGreen ? 1 : 0);
+        }
+        if (patch.isBaseline !== void 0) {
+          fields.push("is_baseline = ?");
+          params.push(patch.isBaseline ? 1 : 0);
+        }
+        if (fields.length === 0) return this.findById(runId);
+        params.push(runId);
+        this.db.prepare(`UPDATE net_runs SET ${fields.join(", ")} WHERE run_id = ?`).run(...params);
+        return this.findById(runId);
+      }
+      /** Clear the baseline pin for every run of a (test, browser). */
+      clearBaseline(testId, browser) {
+        this.db.prepare("UPDATE net_runs SET is_baseline = 0 WHERE test_id = ? AND browser = ?").run(testId, browser);
+      }
+      delete(runId) {
+        this.db.prepare("DELETE FROM net_runs WHERE run_id = ?").run(runId);
+      }
+    };
+  }
+});
+function rowToNetRequest(row) {
+  return NetRequestRow.parse({
+    id: row.id,
+    runId: row.run_id,
+    stepId: row.step_id,
+    attribution: row.attribution,
+    targetType: row.target_type,
+    method: row.method,
+    urlRaw: row.url_raw,
+    urlTemplate: row.url_template,
+    gqlOperation: row.gql_operation,
+    identityKey: row.identity_key,
+    status: row.status,
+    errorText: row.error_text,
+    mime: row.mime,
+    reqHash: row.req_hash,
+    respHash: row.resp_hash,
+    shapeHash: row.shape_hash,
+    reqBodyRef: row.req_body_ref,
+    respBodyRef: row.resp_body_ref,
+    bodyStatus: row.body_status,
+    redirectsJson: row.redirects_json,
+    timingsJson: row.timings_json,
+    initiatorJson: row.initiator_json,
+    wallStart: row.wall_start
+  });
+}
+var NetRequestsRepository;
+var init_net_requests = __esm2({
+  "src/storage/repositories/net-requests.ts"() {
+    NetRequestsRepository = class {
+      constructor(db) {
+        this.db = db;
+      }
+      db;
+      create(input) {
+        const r = NetRequestRow.parse(input);
+        this.db.prepare(
+          `INSERT INTO net_requests
+          (id, run_id, step_id, attribution, target_type, method, url_raw,
+           url_template, gql_operation, identity_key, status, error_text, mime,
+           req_hash, resp_hash, shape_hash, req_body_ref, resp_body_ref,
+           body_status, redirects_json, timings_json, initiator_json, wall_start)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        ).run(
+          r.id,
+          r.runId,
+          r.stepId,
+          r.attribution,
+          r.targetType,
+          r.method,
+          r.urlRaw,
+          r.urlTemplate,
+          r.gqlOperation,
+          r.identityKey,
+          r.status,
+          r.errorText,
+          r.mime,
+          r.reqHash,
+          r.respHash,
+          r.shapeHash,
+          r.reqBodyRef,
+          r.respBodyRef,
+          r.bodyStatus,
+          r.redirectsJson,
+          r.timingsJson,
+          r.initiatorJson,
+          r.wallStart
+        );
+        return r;
+      }
+      /** Bulk insert in one transaction — a run can produce hundreds of requests. */
+      createMany(rows) {
+        const insert = this.db.transaction((items) => {
+          for (const item of items) this.create(item);
+        });
+        insert(rows);
+      }
+      listByRun(runId) {
+        const rows = this.db.prepare("SELECT * FROM net_requests WHERE run_id = ? ORDER BY wall_start ASC").all(runId);
+        return rows.map(rowToNetRequest);
+      }
+      listByRunStep(runId, stepId) {
+        const sql = stepId === null ? "SELECT * FROM net_requests WHERE run_id = ? AND step_id IS NULL ORDER BY wall_start ASC" : "SELECT * FROM net_requests WHERE run_id = ? AND step_id = ? ORDER BY wall_start ASC";
+        const rows = stepId === null ? this.db.prepare(sql).all(runId) : this.db.prepare(sql).all(runId, stepId);
+        return rows.map(rowToNetRequest);
+      }
+      deleteByRun(runId) {
+        this.db.prepare("DELETE FROM net_requests WHERE run_id = ?").run(runId);
+      }
+    };
+  }
+});
+var NetBodiesRepository;
+var init_net_bodies = __esm2({
+  "src/storage/repositories/net-bodies.ts"() {
+    NetBodiesRepository = class {
+      constructor(db) {
+        this.db = db;
+      }
+      db;
+      /**
+       * Store a canonical body and return its hash (the ref stored on the request
+       * row). Idempotent: an already-present hash is left untouched (`INSERT OR
+       * IGNORE`), so two runs producing the same body share one BLOB. The caller
+       * passes the ALREADY-canonicalized + redacted bytes — secrets must never
+       * reach here.
+       */
+      putBody(canonical) {
+        const hash = createHash("sha256").update(canonical).digest("hex");
+        const compressed = gzipSync(canonical);
+        this.db.prepare("INSERT OR IGNORE INTO net_bodies (hash, compressed, size_raw) VALUES (?, ?, ?)").run(hash, compressed, canonical.byteLength);
+        return hash;
+      }
+      /** Retrieve + decompress a body by hash, or null if absent (e.g. GC'd). */
+      getBody(hash) {
+        const row = this.db.prepare("SELECT * FROM net_bodies WHERE hash = ?").get(hash);
+        if (row === void 0) return null;
+        return gunzipSync(Buffer.from(row.compressed));
+      }
+      has(hash) {
+        const row = this.db.prepare("SELECT 1 AS present FROM net_bodies WHERE hash = ?").get(hash);
+        return row !== void 0;
+      }
+      /**
+       * Garbage-collect bodies no longer referenced by any net_requests row. Called
+       * after pruning old runs (retainRuns). Refcounting is implicit: a body is live
+       * iff some request still points at it via req_body_ref / resp_body_ref.
+       * Returns the number of orphaned bodies deleted.
+       */
+      gcOrphans() {
+        const result = this.db.prepare(
+          `DELETE FROM net_bodies
+         WHERE hash NOT IN (
+           SELECT req_body_ref FROM net_requests WHERE req_body_ref IS NOT NULL
+           UNION
+           SELECT resp_body_ref FROM net_requests WHERE resp_body_ref IS NOT NULL
+         )`
+        ).run();
+        return Number(result.changes);
+      }
+    };
+  }
+});
+function rowToVolatility(row) {
+  return NetVolatilityRow.parse({
+    testId: row.test_id,
+    identityKey: row.identity_key,
+    jsonPath: row.json_path,
+    kind: row.kind,
+    learnedAt: row.learned_at
+  });
+}
+var NetVolatilityRepository;
+var init_net_volatility = __esm2({
+  "src/storage/repositories/net-volatility.ts"() {
+    NetVolatilityRepository = class {
+      constructor(db) {
+        this.db = db;
+      }
+      db;
+      /** Upsert a volatility entry (idempotent on the composite PK). */
+      mark(entry) {
+        const e = NetVolatilityRow.parse(entry);
+        this.db.prepare(
+          `INSERT INTO net_volatility (test_id, identity_key, json_path, kind, learned_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(test_id, identity_key, json_path)
+         DO UPDATE SET kind = excluded.kind, learned_at = excluded.learned_at`
+        ).run(e.testId, e.identityKey, e.jsonPath, e.kind, e.learnedAt);
+      }
+      listByTest(testId) {
+        const rows = this.db.prepare("SELECT * FROM net_volatility WHERE test_id = ?").all(testId);
+        return rows.map(rowToVolatility);
+      }
+      reset(testId) {
+        const result = testId === void 0 ? this.db.prepare("DELETE FROM net_volatility").run() : this.db.prepare("DELETE FROM net_volatility WHERE test_id = ?").run(testId);
+        return Number(result.changes);
+      }
+    };
+  }
+});
+function stepReporterPath() {
+  const candidates = [
+    path15.resolve(here, "scripts", "xray-step-reporter.mjs"),
+    // dist/xray/scripts
+    path15.resolve(here, "xray", "scripts", "xray-step-reporter.mjs"),
+    path15.resolve(here, "..", "xray", "scripts", "xray-step-reporter.mjs")
+  ];
+  for (const c of candidates) if (existsSync(c)) return c;
+  return candidates[0];
+}
+function resolveUserConfig(cwd) {
+  for (const name of USER_CONFIG_NAMES) {
+    const p = path15.join(cwd, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+function wrapperWithUserConfig(spec) {
+  return `// AUTO-GENERATED by QAIOS xray \u2014 temporary; deleted after the run. Extends your
+// playwright config with recordHar so QAIOS can capture network traffic. Your
+// config is never modified. This file sits beside your config so all relative
+// paths in it (webServer, globalSetup, testDir, \u2026) resolve normally.
+import base from ${JSON.stringify(spec)};
+
+const harPath = process.env.QAIOS_XRAY_HAR_PATH;
+const level = process.env.QAIOS_XRAY_LEVEL ?? 'summary';
+const harContent = level === 'headers' ? 'omit' : 'embed';
+
+const baseConfig = base && base.default ? base.default : base;
+
+export default {
+  ...baseConfig,
+  use: {
+    ...(baseConfig && baseConfig.use ? baseConfig.use : {}),
+    contextOptions: {
+      ...(baseConfig && baseConfig.use && baseConfig.use.contextOptions
+        ? baseConfig.use.contextOptions
+        : {}),
+      recordHar: { path: harPath, content: harContent, mode: 'full' },
+    },
+  },
+};
+`;
+}
+function wrapperStandalone() {
+  return `// AUTO-GENERATED by QAIOS xray \u2014 do not edit. No user playwright config was
+// found, so this is a minimal config with recordHar enabled.
+import path from 'node:path';
+
+const harPath = process.env.QAIOS_XRAY_HAR_PATH;
+const level = process.env.QAIOS_XRAY_LEVEL ?? 'summary';
+const cwd = process.env.QAIOS_XRAY_CWD ?? process.cwd();
+const testDirRel = process.env.QAIOS_XRAY_TESTDIR ?? 'tests';
+const harContent = level === 'headers' ? 'omit' : 'embed';
+
+export default {
+  testDir: path.isAbsolute(testDirRel) ? testDirRel : path.resolve(cwd, testDirRel),
+  use: {
+    contextOptions: { recordHar: { path: harPath, content: harContent, mode: 'full' } },
+  },
+};
+`;
+}
+function materializeWrapperConfig(opts) {
+  mkdirSync(opts.xrayDir, { recursive: true });
+  const userConfig = resolveUserConfig(opts.cwd);
+  let source;
+  let ext;
+  if (userConfig !== null) {
+    const userExt = path15.extname(userConfig);
+    ext = userExt === ".cjs" ? ".cjs" : userExt;
+    const baseName = path15.basename(userConfig).replace(/\.[^.]+$/, "");
+    const spec = userExt === ".mjs" || userExt === ".cjs" ? `./${baseName}${userExt}` : `./${baseName}`;
+    source = wrapperWithUserConfig(spec);
+  } else {
+    ext = ".mjs";
+    source = wrapperStandalone();
+  }
+  const configPath = path15.join(opts.cwd, `${WRAPPER_BASENAME}${ext}`);
+  try {
+    writeFileSync(configPath, source, "utf-8");
+  } catch (err) {
+    throw new XrayError({
+      code: "qaios.xray.config_resolve_failed",
+      message: "Failed to write the xray wrapper Playwright config.",
+      detail: `Could not write ${configPath}.`,
+      cause: err
+    });
+  }
+  const stepsPath = path15.join(opts.xrayDir, `${path15.basename(opts.harPath, ".har")}.steps.ndjson`);
+  return {
+    configPath,
+    cleanupPath: configPath,
+    stepReporterPath: stepReporterPath(),
+    stepsPath,
+    env: {
+      QAIOS_XRAY_USER_CONFIG: userConfig ?? "",
+      QAIOS_XRAY_HAR_PATH: opts.harPath,
+      QAIOS_XRAY_LEVEL: opts.level,
+      QAIOS_XRAY_CWD: opts.cwd,
+      QAIOS_XRAY_TESTDIR: opts.testDir ?? "tests",
+      QAIOS_XRAY_STEPS_PATH: stepsPath
+    }
+  };
+}
+var here;
+var USER_CONFIG_NAMES;
+var WRAPPER_BASENAME;
+var init_wrapper_config = __esm2({
+  "src/xray/wrapper-config.ts"() {
+    here = path15.dirname(fileURLToPath(import.meta.url));
+    USER_CONFIG_NAMES = [
+      "playwright.config.ts",
+      "playwright.config.js",
+      "playwright.config.mjs",
+      "playwright.config.cjs"
+    ];
+    WRAPPER_BASENAME = ".qaios-xray.pw.config";
+  }
+});
+function mimeOf(entry) {
+  const ct = entry.response?.content?.mimeType;
+  if (!ct) return null;
+  return ct.split(";")[0].trim() || null;
+}
+function bodyOf(entry) {
+  const content = entry.response?.content;
+  if (!content || typeof content.text !== "string" || content.text.length === 0) {
+    return { text: null, status: "skipped" };
+  }
+  if (content.encoding === "base64") {
+    try {
+      return { text: Buffer.from(content.text, "base64").toString("utf-8"), status: "stored" };
+    } catch {
+      return { text: null, status: "skipped" };
+    }
+  }
+  return { text: content.text, status: "stored" };
+}
+function timingsOf(entry) {
+  const t = entry.timings ?? {};
+  const out = {};
+  if (typeof t.dns === "number" && t.dns >= 0) out.dns = t.dns;
+  if (typeof t.connect === "number" && t.connect >= 0) out.connect = t.connect;
+  if (typeof t.wait === "number" && t.wait >= 0) out.ttfb = t.wait;
+  if (typeof entry.time === "number" && entry.time >= 0) out.total = entry.time;
+  return out;
+}
+function parseHarFile(harPath) {
+  if (!existsSync(harPath)) {
+    return [];
+  }
+  let har;
+  try {
+    har = JSON.parse(readFileSync(harPath, "utf-8"));
+  } catch (err) {
+    throw new XrayError({
+      code: "qaios.xray.har_parse_failed",
+      message: "Failed to parse the Playwright HAR file produced by xray capture.",
+      detail: `HAR at ${harPath} was not valid JSON.`,
+      cause: err
+    });
+  }
+  const entries = har.log?.entries ?? [];
+  const events = [];
+  for (const entry of entries) {
+    const url = entry.request?.url;
+    if (typeof url !== "string" || !/^https?:/i.test(url)) continue;
+    const wallStart = typeof entry.startedDateTime === "string" ? Date.parse(entry.startedDateTime) : NaN;
+    const mime = mimeOf(entry);
+    const isTextual = mime !== null && /^(application\/json|application\/graphql|text\/)/i.test(mime);
+    const body = isTextual ? bodyOf(entry) : { text: null, status: "skipped" };
+    const failure = entry.response?._failureText ?? entry._failureText ?? null;
+    const event = XrayRequestEvent.parse({
+      method: entry.request?.method ?? "GET",
+      url,
+      initiator: null,
+      // HAR carries no usable initiator stack
+      status: typeof entry.response?.status === "number" ? entry.response.status : null,
+      errorText: failure,
+      mime,
+      fromServiceWorker: false,
+      fromDiskCache: Boolean(entry.cache && Object.keys(entry.cache).length > 0),
+      reqBody: typeof entry.request?.postData?.text === "string" ? entry.request.postData.text : null,
+      respBody: body.text,
+      bodyStatus: body.status,
+      redirects: typeof entry.response?.redirectURL === "string" && entry.response.redirectURL.length > 0 ? [{ url: entry.response.redirectURL, status: entry.response?.status ?? 0 }] : [],
+      timings: timingsOf(entry),
+      wallStart: Number.isFinite(wallStart) ? wallStart : 0
+    });
+    events.push(event);
+  }
+  events.sort((a, b) => a.wallStart - b.wallStart);
+  return events;
+}
+var init_har_parser = __esm2({
+  "src/xray/har-parser.ts"() {
+  }
+});
+function testIdFor(file, title) {
+  return `${file.replace(/\\/g, "/")}::${title}`;
+}
+function flattenSteps(steps, out) {
+  if (!steps) return;
+  for (const s of steps) {
+    if (s.category === "pw:api" && typeof s.startTime === "string") {
+      const start = Date.parse(s.startTime);
+      if (Number.isFinite(start)) {
+        const dur = typeof s.duration === "number" && s.duration >= 0 ? s.duration : 0;
+        out.push({
+          stepId: ulid(),
+          title: s.title ?? "(step)",
+          category: s.category,
+          startWall: start,
+          endWall: start + dur
+        });
+      }
+    }
+    flattenSteps(s.steps, out);
+  }
+}
+function walkSuite(suite, acc) {
+  for (const spec of suite.specs ?? []) {
+    const file = spec.file ?? suite.file ?? "";
+    const rel = file ? path15.basename(file) : "";
+    const title = spec.title ?? "(test)";
+    const test = spec.tests?.[spec.tests.length - 1];
+    const finalResult = test?.results?.[test.results.length - 1];
+    const windows = [];
+    flattenSteps(finalResult?.steps, windows);
+    windows.sort((a, b) => a.startWall - b.startWall);
+    acc.push({
+      testId: testIdFor(rel, title),
+      testTitle: title,
+      file: rel,
+      passed: finalResult?.status === "passed",
+      windows
+    });
+  }
+  for (const child of suite.suites ?? []) walkSuite(child, acc);
+}
+function parseStepWindows(reportPath) {
+  if (!existsSync(reportPath)) return [];
+  let report;
+  try {
+    report = JSON.parse(readFileSync(reportPath, "utf-8"));
+  } catch {
+    return [];
+  }
+  const acc = [];
+  for (const suite of report.suites ?? []) walkSuite(suite, acc);
+  return acc;
+}
+function parseStepSidecar(stepsPath) {
+  const byTest = /* @__PURE__ */ new Map();
+  if (!existsSync(stepsPath)) return byTest;
+  let raw;
+  try {
+    raw = readFileSync(stepsPath, "utf-8");
+  } catch {
+    return byTest;
+  }
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    const list = byTest.get(parsed.testId) ?? [];
+    list.push({
+      stepId: ulid(),
+      title: parsed.title,
+      category: parsed.category,
+      startWall: parsed.startWall,
+      endWall: parsed.endWall
+    });
+    byTest.set(parsed.testId, list);
+  }
+  for (const list of byTest.values()) list.sort((a, b) => a.startWall - b.startWall);
+  return byTest;
+}
+function parseStepWindowsWithSidecar(reportPath, stepsPath) {
+  const fromReport = parseStepWindows(reportPath);
+  if (stepsPath === void 0) return fromReport;
+  const sidecar = parseStepSidecar(stepsPath);
+  if (sidecar.size === 0) return fromReport;
+  const merged = fromReport.map((t) => {
+    const windows = sidecar.get(t.testId);
+    return windows !== void 0 ? { ...t, windows } : t;
+  });
+  const seen = new Set(merged.map((t) => t.testId));
+  for (const [testId, windows] of sidecar) {
+    if (!seen.has(testId)) {
+      const title = testId.split("::").slice(1).join("::") || testId;
+      merged.push({
+        testId,
+        testTitle: title,
+        file: testId.split("::")[0] ?? "",
+        passed: false,
+        windows
+      });
+    }
+  }
+  return merged;
+}
+var init_step_windows = __esm2({
+  "src/xray/step-windows.ts"() {
+  }
+});
+function attributeRequests(requests, windows, opts = {}) {
+  const quiescence = opts.quiescenceMs ?? DEFAULT_QUIESCENCE_MS;
+  const maxWindow = opts.maxWindowMs ?? DEFAULT_MAX_WINDOW_MS;
+  const effective = windows.map((w) => {
+    const rawEnd = w.endWall + quiescence;
+    const cappedEnd = Math.min(rawEnd, w.startWall + maxWindow);
+    return { stepId: w.stepId, start: w.startWall, end: Math.max(cappedEnd, w.startWall) };
+  });
+  return requests.map((event) => {
+    const t = event.wallStart;
+    const containing = effective.filter((w) => t >= w.start && t <= w.end);
+    if (containing.length === 0) {
+      return { event, stepId: null, attribution: "background" };
+    }
+    if (containing.length === 1) {
+      return { event, stepId: containing[0].stepId, attribution: "temporal" };
+    }
+    const winner = containing.reduce((a, b) => b.start > a.start ? b : a);
+    return { event, stepId: winner.stepId, attribution: "temporal_ambiguous" };
+  });
+}
+var DEFAULT_QUIESCENCE_MS;
+var DEFAULT_MAX_WINDOW_MS;
+var init_causality_engine = __esm2({
+  "src/xray/causality-engine.ts"() {
+    DEFAULT_QUIESCENCE_MS = 500;
+    DEFAULT_MAX_WINDOW_MS = 15e3;
+  }
+});
+function isVolatileParamName(name, extra) {
+  const lower = name.toLowerCase();
+  if (DEFAULT_VOLATILE_PARAMS.includes(lower)) return true;
+  if (/^(session|token|sig)/.test(lower)) return true;
+  return extra.some((p) => p.toLowerCase() === lower);
+}
+function templateSegment(seg) {
+  if (seg.length === 0) return seg;
+  if (NUMERIC_RE.test(seg)) return "{id}";
+  if (UUID_RE.test(seg) || ULID_RE.test(seg) || OBJECTID_RE.test(seg) || LONGHEX_RE.test(seg)) {
+    return "{id}";
+  }
+  if (BASE64URL_RE.test(seg)) return "{token}";
+  return seg;
+}
+function templateUrl(rawUrl, volatileParams = []) {
+  let u;
+  try {
+    u = new URL(rawUrl);
+  } catch {
+    return { host: "", urlTemplate: rawUrl };
+  }
+  const segs = u.pathname.split("/").map(templateSegment);
+  const pathTemplate = segs.join("/");
+  const params = [...u.searchParams.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const queryParts = params.map(
+    ([k, v]) => isVolatileParamName(k, volatileParams) ? k : `${k}=${templateSegment(v)}`
+  );
+  const query = queryParts.length > 0 ? `?${queryParts.join("&")}` : "";
+  return { host: u.host, urlTemplate: `${pathTemplate}${query}` };
+}
+function identityKey(method, host, urlTemplate, gqlOperation) {
+  const base = `${method.toUpperCase()}|${host}|${urlTemplate}`;
+  return gqlOperation ? `${base}|${gqlOperation}` : base;
+}
+var UUID_RE;
+var ULID_RE;
+var OBJECTID_RE;
+var LONGHEX_RE;
+var NUMERIC_RE;
+var BASE64URL_RE;
+var DEFAULT_VOLATILE_PARAMS;
+var init_identity = __esm2({
+  "src/xray/identity.ts"() {
+    UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+    OBJECTID_RE = /^[0-9a-f]{24}$/i;
+    LONGHEX_RE = /^[0-9a-f]{16,}$/i;
+    NUMERIC_RE = /^\d+$/;
+    BASE64URL_RE = /^[A-Za-z0-9_-]{22,}$/;
+    DEFAULT_VOLATILE_PARAMS = [
+      "t",
+      "ts",
+      "timestamp",
+      "_",
+      "cb",
+      "nonce",
+      "state",
+      "code"
+    ];
+  }
+});
+function placeholderFor(value) {
+  if (ISO_DATE_RE.test(value)) return "<iso-date>";
+  if (JWT_RE.test(value) && value.length > 30) return "<jwt>";
+  if (UUID_RE2.test(value)) return "<uuid>";
+  if (ULID_RE2.test(value)) return "<ulid>";
+  if (EPOCH_MS_RE.test(value)) return "<epoch-ms>";
+  if (EPOCH_S_RE.test(value)) return "<epoch-s>";
+  return null;
+}
+function sha256Hex3(s) {
+  return createHash("sha256").update(s).digest("hex");
+}
+function parseRedactionRules(jsonPaths) {
+  const rules = [];
+  for (const raw of jsonPaths) {
+    const p = raw.trim();
+    if (p.startsWith("$..")) {
+      rules.push({ recursiveField: p.slice(3), path: null });
+    } else if (p.startsWith("$.")) {
+      const segs = p.slice(2).split(".").map((s) => s.replace(/\[[^\]]*\]/g, "")).filter((s) => s.length > 0);
+      rules.push({ recursiveField: null, path: segs });
+    }
+  }
+  return rules;
+}
+function redactJson(value, rules) {
+  if (rules.length === 0) return value;
+  const recursiveFields = new Set(
+    rules.map((r) => r.recursiveField).filter((f) => f !== null)
+  );
+  const anchored = rules.map((r) => r.path).filter((p) => p !== null);
+  function walk(node, trail) {
+    if (Array.isArray(node)) return node.map((v) => walk(v, trail));
+    if (node !== null && typeof node === "object") {
+      const out = {};
+      for (const [k, v] of Object.entries(node)) {
+        const here22 = [...trail, k];
+        if (recursiveFields.has(k)) {
+          out[k] = REDACTED;
+        } else if (anchored.some((p) => pathEquals(p, here22))) {
+          out[k] = REDACTED;
+        } else {
+          out[k] = walk(v, here22);
+        }
+      }
+      return out;
+    }
+    return node;
+  }
+  return walk(value, []);
+}
+function pathEquals(a, b) {
+  return a.length === b.length && a.every((s, i) => s === b[i]);
+}
+function canonicalizeValue(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeValue);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = canonicalizeValue(value[key]);
+    }
+    return out;
+  }
+  if (typeof value === "string") {
+    const ph = placeholderFor(value);
+    return ph ?? value;
+  }
+  return value;
+}
+function shapeOf(value) {
+  if (Array.isArray(value)) {
+    return value.length > 0 ? ["array", shapeOf(value[0])] : ["array"];
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = shapeOf(value[key]);
+    }
+    return out;
+  }
+  if (value === null) return "null";
+  return typeof value;
+}
+function canonicalizeBody(body, mime, redactionRules) {
+  const looksJson = mime !== null && /json|graphql/i.test(mime) || /^\s*[{[]/.test(body);
+  if (looksJson) {
+    try {
+      const parsed = JSON.parse(body);
+      const redacted = redactJson(parsed, redactionRules);
+      const canonical = canonicalizeValue(redacted);
+      const canonicalStr = JSON.stringify(canonical);
+      return {
+        hash: sha256Hex3(canonicalStr),
+        shapeHash: sha256Hex3(JSON.stringify(shapeOf(redacted))),
+        canonical: Buffer.from(canonicalStr, "utf-8"),
+        isJson: true
+      };
+    } catch {
+    }
+  }
+  return {
+    hash: sha256Hex3(body),
+    shapeHash: sha256Hex3("text"),
+    canonical: Buffer.from(body, "utf-8"),
+    isJson: false
+  };
+}
+function detectGraphql(url, reqBody) {
+  const looksGraphqlUrl = /\/graphql\b/i.test(url);
+  if (reqBody === null) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(reqBody);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object") return null;
+  const obj = parsed;
+  if (typeof obj.query !== "string") return null;
+  if (!looksGraphqlUrl && !/\b(query|mutation|subscription)\b/.test(obj.query)) return null;
+  const operationName = typeof obj.operationName === "string" && obj.operationName.length > 0 ? obj.operationName : extractOpName(obj.query) ?? "anonymous";
+  const queryHash = sha256Hex3(obj.query.replace(/\s+/g, " ").trim()).slice(0, 16);
+  return { operationName, queryHash };
+}
+function extractOpName(query) {
+  const m = query.match(/\b(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/);
+  return m ? m[1] : null;
+}
+function normalizeRequest(input) {
+  const { host, urlTemplate } = templateUrl(input.url, input.volatileParams);
+  const gql = detectGraphql(input.url, input.reqBody);
+  const idKey = gql ? identityKey(input.method, host, urlTemplate, `${gql.operationName}:${gql.queryHash}`) : identityKey(input.method, host, urlTemplate, null);
+  const req = input.reqBody !== null && input.reqBody.length > 0 ? canonicalizeBody(input.reqBody, input.mime, input.redactionRules) : null;
+  const resp = input.respBody !== null && input.respBody.length > 0 ? canonicalizeBody(input.respBody, input.mime, input.redactionRules) : null;
+  return {
+    host,
+    urlTemplate,
+    identityKey: idKey,
+    gqlOperation: gql ? gql.operationName : null,
+    reqHash: req ? req.hash : null,
+    // shapeHash describes the response shape (what SCHEMA_CHANGED compares).
+    respHash: resp ? resp.hash : null,
+    shapeHash: resp ? resp.shapeHash : null,
+    reqCanonical: req ? req.canonical : null,
+    respCanonical: resp ? resp.canonical : null
+  };
+}
+var ISO_DATE_RE;
+var EPOCH_MS_RE;
+var EPOCH_S_RE;
+var UUID_RE2;
+var ULID_RE2;
+var JWT_RE;
+var REDACTED;
+var DEFAULT_HEADER_DENYLIST;
+var init_normalizer = __esm2({
+  "src/xray/normalizer.ts"() {
+    init_identity();
+    ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?$/;
+    EPOCH_MS_RE = /^\d{13}$/;
+    EPOCH_S_RE = /^\d{10}$/;
+    UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    ULID_RE2 = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+    JWT_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+    REDACTED = "<redacted>";
+    DEFAULT_HEADER_DENYLIST = [
+      "authorization",
+      "cookie",
+      "set-cookie",
+      "x-api-key",
+      "proxy-authorization"
+    ];
+  }
+});
+function buildRunGraph(requests) {
+  const graph = /* @__PURE__ */ new Map();
+  for (const r of requests) {
+    const key = r.identityKey;
+    const existing = graph.get(key);
+    if (existing === void 0) {
+      graph.set(key, {
+        identityKey: r.identityKey,
+        stepId: r.stepId,
+        attribution: r.attribution,
+        method: r.method,
+        status: r.status,
+        errorText: r.errorText,
+        shapeHash: r.shapeHash,
+        respHash: r.respHash,
+        count: 1
+      });
+    } else {
+      existing.count += 1;
+      if (isErrorStatus(r.status) && !isErrorStatus(existing.status)) {
+        existing.status = r.status;
+        existing.errorText = r.errorText;
+      }
+    }
+  }
+  return graph;
+}
+function isErrorStatus(status) {
+  return status === null || status >= 400 || status < 0;
+}
+var BaselineSelector;
+var init_baseline = __esm2({
+  "src/xray/baseline.ts"() {
+    init_net_runs();
+    init_net_requests();
+    BaselineSelector = class {
+      netRuns;
+      netRequests;
+      constructor(db) {
+        this.netRuns = new NetRunsRepository(db);
+        this.netRequests = new NetRequestsRepository(db);
+      }
+      /**
+       * The baseline run for a (test, browser): the pinned baseline if one exists,
+       * else the most recent green run. Returns null if there's no green run yet.
+       * `excludeRunId` skips a candidate run (so a run never baselines against itself).
+       */
+      select(testId, browser, excludeRunId) {
+        const runs = this.netRuns.listByTest(testId, browser);
+        const pinned = runs.find((r) => r.isBaseline && r.runId !== excludeRunId);
+        if (pinned !== void 0) return pinned;
+        return runs.find((r) => r.isGreen && r.runId !== excludeRunId) ?? null;
+      }
+      /** Build the causal graph for a run by id (or null if the run is unknown). */
+      graphFor(runId) {
+        if (this.netRuns.findById(runId) === null) return null;
+        return buildRunGraph(this.netRequests.listByRun(runId));
+      }
+      /** Pin a run as the baseline for its (test, browser), clearing any prior pin. */
+      pin(runId) {
+        const run = this.netRuns.findById(runId);
+        if (run === null) return null;
+        this.netRuns.clearBaseline(run.testId, run.browser);
+        return this.netRuns.update(runId, { isBaseline: true });
+      }
+      /** Clear the baseline pin for a (test, browser). */
+      clear(testId, browser) {
+        this.netRuns.clearBaseline(testId, browser);
+      }
+    };
+  }
+});
+function learnVolatility(testId, graphA, graphB, learnedAt) {
+  const out = [];
+  for (const [key, a] of graphA) {
+    const b = graphB.get(key);
+    if (b === void 0) continue;
+    const sameShape = a.shapeHash !== null && b.shapeHash !== null && a.shapeHash === b.shapeHash;
+    const valueDiffers = a.respHash !== null && b.respHash !== null && a.respHash !== b.respHash;
+    if (sameShape && valueDiffers) {
+      out.push(
+        NetVolatilityRow.parse({
+          testId,
+          identityKey: key,
+          jsonPath: "",
+          kind: "value",
+          learnedAt
+        })
+      );
+    }
+  }
+  const onlyInOne = (from, other) => {
+    for (const key of from.keys()) {
+      if (!other.has(key)) {
+        out.push(
+          NetVolatilityRow.parse({
+            testId,
+            identityKey: key,
+            jsonPath: "",
+            kind: "presence",
+            learnedAt
+          })
+        );
+      }
+    }
+  };
+  onlyInOne(graphA, graphB);
+  onlyInOne(graphB, graphA);
+  const seen = /* @__PURE__ */ new Set();
+  return out.filter((r) => {
+    const k = `${r.identityKey}|${r.kind}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+var VolatilityLearner;
+var init_volatility = __esm2({
+  "src/xray/volatility.ts"() {
+    init_net_runs();
+    init_net_requests();
+    init_net_volatility();
+    init_baseline();
+    VolatilityLearner = class {
+      netRuns;
+      netRequests;
+      volatility;
+      constructor(db) {
+        this.netRuns = new NetRunsRepository(db);
+        this.netRequests = new NetRequestsRepository(db);
+        this.volatility = new NetVolatilityRepository(db);
+      }
+      /**
+       * Learn from the two most recent green runs of (test, browser). No-op (returns
+       * 0) until at least two green runs exist. Returns the number of rows learned.
+       */
+      learnForTest(testId, browser, learnedAt) {
+        const green = this.netRuns.listByTest(testId, browser).filter((r) => r.isGreen);
+        if (green.length < 2) return 0;
+        const [newest, prev] = green;
+        const graphA = buildRunGraph(this.netRequests.listByRun(newest.runId));
+        const graphB = buildRunGraph(this.netRequests.listByRun(prev.runId));
+        const rows = learnVolatility(testId, graphA, graphB, learnedAt);
+        for (const row of rows) this.volatility.mark(row);
+        return rows.length;
+      }
+    };
+  }
+});
+function windowEnvelope(windows) {
+  if (windows.length === 0) return null;
+  let start = Infinity;
+  let end = -Infinity;
+  for (const w of windows) {
+    if (w.startWall < start) start = w.startWall;
+    if (w.endWall > end) end = w.endWall;
+  }
+  return { start: start - 1e3, end: end + 15e3 };
+}
+var CaptureSession;
+var init_capture_session = __esm2({
+  "src/xray/capture-session.ts"() {
+    init_net_runs();
+    init_net_requests();
+    init_net_bodies();
+    init_har_parser();
+    init_step_windows();
+    init_causality_engine();
+    init_normalizer();
+    init_volatility();
+    CaptureSession = class {
+      constructor(deps) {
+        this.deps = deps;
+        this.netRuns = new NetRunsRepository(deps.db);
+        this.netRequests = new NetRequestsRepository(deps.db);
+        this.netBodies = new NetBodiesRepository(deps.db);
+        this.volatilityLearner = new VolatilityLearner(deps.db);
+      }
+      deps;
+      netRuns;
+      netRequests;
+      netBodies;
+      volatilityLearner;
+      /**
+       * Ingest a finished run's HAR + report. Because recordHar writes ONE HAR for
+       * the whole subprocess (all tests share it), requests are bucketed to tests by
+       * their step windows: a request that falls in a test's window-span belongs to
+       * that test; requests outside every test's span are attributed to that test's
+       * `background` only if they still fall in its outer [firstStep, lastStep]
+       * envelope, else dropped from per-test runs (true cross-test noise).
+       */
+      ingest(opts) {
+        const startedAt = opts.startedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+        const events = parseHarFile(opts.harPath);
+        const perTest = parseStepWindowsWithSidecar(opts.reportPath, opts.stepsPath);
+        const tier = opts.browser === "chromium" ? "A" : "B";
+        const volatileParams = opts.volatileParams ?? [];
+        const redactionRules = parseRedactionRules(opts.redact ?? []);
+        const runIds = [];
+        let requestCount = 0;
+        const greenTests = /* @__PURE__ */ new Set();
+        for (const test of perTest) {
+          const envelope = windowEnvelope(test.windows);
+          const testEvents = envelope === null ? perTest.length === 1 ? events : [] : events.filter((e) => e.wallStart >= envelope.start && e.wallStart <= envelope.end);
+          if (testEvents.length === 0 && perTest.length > 1) continue;
+          const attributed = attributeRequests(
+            testEvents,
+            test.windows,
+            opts.quiescenceMs !== void 0 ? { quiescenceMs: opts.quiescenceMs } : {}
+          );
+          const runId = ulid();
+          const isGreen = test.passed;
+          this.netRuns.create(
+            NetRunRow.parse({
+              runId,
+              workflowId: opts.workflowId,
+              testId: test.testId,
+              browser: opts.browser,
+              tier,
+              captureLevel: opts.level,
+              startedAt,
+              isGreen,
+              isBaseline: false
+            })
+          );
+          const rows = attributed.map(
+            (a) => this.toRequestRow(runId, a, volatileParams, redactionRules)
+          );
+          if (rows.length > 0) this.netRequests.createMany(rows);
+          runIds.push(runId);
+          requestCount += rows.length;
+          if (isGreen) greenTests.add(test.testId);
+        }
+        if (perTest.length === 0 && events.length > 0) {
+          const runId = ulid();
+          const testId = testIdFor(path15.basename(opts.harPath), "(unattributed)");
+          this.netRuns.create(
+            NetRunRow.parse({
+              runId,
+              workflowId: opts.workflowId,
+              testId,
+              browser: opts.browser,
+              tier,
+              captureLevel: opts.level,
+              startedAt,
+              isGreen: false,
+              isBaseline: false
+            })
+          );
+          const rows = events.map(
+            (e) => this.toRequestRow(
+              runId,
+              { event: e, stepId: null, attribution: "background" },
+              volatileParams,
+              redactionRules
+            )
+          );
+          if (rows.length > 0) this.netRequests.createMany(rows);
+          runIds.push(runId);
+          requestCount += rows.length;
+        }
+        for (const testId of greenTests) {
+          try {
+            this.volatilityLearner.learnForTest(testId, opts.browser, startedAt);
+          } catch {
+          }
+        }
+        this.deps.auditLogger.append({
+          workflowId: opts.workflowId,
+          phase: "EXECUTION",
+          skillId: null,
+          event: "xray.capture",
+          payload: {
+            runIds,
+            requestCount,
+            browser: opts.browser,
+            tier,
+            level: opts.level
+          },
+          actor: "system"
+        });
+        return { runIds, requestCount };
+      }
+      /** Build a persisted net_requests row from an attributed event. */
+      toRequestRow(runId, a, volatileParams, redactionRules) {
+        const e = a.event;
+        const norm = normalizeRequest({
+          method: e.method,
+          url: e.url,
+          mime: e.mime,
+          reqBody: e.reqBody,
+          respBody: e.bodyStatus === "stored" ? e.respBody : null,
+          volatileParams,
+          redactionRules
+        });
+        let reqBodyRef = null;
+        let respBodyRef = null;
+        if (norm.reqCanonical !== null) reqBodyRef = this.netBodies.putBody(norm.reqCanonical);
+        if (norm.respCanonical !== null) respBodyRef = this.netBodies.putBody(norm.respCanonical);
+        return NetRequestRow.parse({
+          id: ulid(),
+          runId,
+          stepId: a.stepId,
+          attribution: a.attribution,
+          targetType: "page",
+          method: e.method,
+          urlRaw: e.url,
+          urlTemplate: norm.urlTemplate,
+          gqlOperation: norm.gqlOperation,
+          identityKey: norm.identityKey,
+          status: e.status,
+          errorText: e.errorText,
+          mime: e.mime,
+          reqHash: norm.reqHash,
+          respHash: norm.respHash,
+          shapeHash: norm.shapeHash,
+          reqBodyRef,
+          respBodyRef,
+          bodyStatus: e.bodyStatus,
+          redirectsJson: e.redirects.length > 0 ? JSON.stringify(e.redirects) : null,
+          timingsJson: Object.keys(e.timings).length > 0 ? JSON.stringify(e.timings) : null,
+          initiatorJson: e.initiator ? JSON.stringify(e.initiator) : null,
+          wallStart: new Date(e.wallStart).toISOString()
+        });
+      }
+    };
+  }
+});
+function statusClass(status) {
+  if (status === null || status <= 0) return "unknown";
+  if (status >= 500) return "5xx";
+  if (status >= 400) return "4xx";
+  if (status >= 300) return "3xx";
+  if (status >= 200) return "2xx";
+  return "other";
+}
+function isErrorStatus2(status) {
+  return status !== null && status >= 400;
+}
+function isUnknownStatus(status, errorText) {
+  return errorText === null && (status === null || status <= 0);
+}
+function diffGraphs(run, baseline, opts = {}) {
+  const presenceUnstable = new Set(
+    (opts.volatility ?? []).filter((v) => v.kind === "presence").map((v) => v.identityKey)
+  );
+  const valueVolatile = new Set(
+    (opts.volatility ?? []).filter((v) => v.kind === "value").map((v) => v.identityKey)
+  );
+  const backgroundFailSignal = opts.backgroundIsFailSignal === true;
+  const divergences = [];
+  const emit2 = (diffClass, e, detail) => {
+    const isFail = FAIL_SIGNAL_CLASSES.has(diffClass) && (backgroundFailSignal || e.attribution !== "background");
+    divergences.push({
+      diffClass,
+      identityKey: e.identityKey,
+      stepId: e.stepId,
+      attribution: e.attribution,
+      detail,
+      failSignal: isFail
+    });
+  };
+  for (const [key, entry] of run) {
+    const base = baseline.get(key);
+    if (isUnknownStatus(entry.status, entry.errorText)) continue;
+    if (isErrorStatus2(entry.status) || entry.errorText !== null) {
+      const ui = opts.uiPassed === true ? " (UI assertions passed)" : "";
+      emit2(
+        "ERROR_RESPONSE",
+        entry,
+        `${describe(entry)} returned ${entry.errorText ?? entry.status ?? "error"}${ui}`
+      );
+      continue;
+    }
+    if (base !== void 0) {
+      const runClass = statusClass(entry.status);
+      const baseClass = statusClass(base.status);
+      if (runClass !== "unknown" && baseClass !== "unknown" && runClass !== baseClass) {
+        emit2(
+          "STATUS_CHANGED",
+          entry,
+          `${describe(entry)} status ${base.status ?? "\u2014"} \u2192 ${entry.status ?? "\u2014"}`
+        );
+      } else if (entry.shapeHash !== null && base.shapeHash !== null && entry.shapeHash !== base.shapeHash) {
+        emit2("SCHEMA_CHANGED", entry, `${describe(entry)} response shape changed`);
+      } else if (entry.respHash !== null && base.respHash !== null && entry.respHash !== base.respHash && !valueVolatile.has(key)) {
+        emit2("VALUE_CHANGED", entry, `${describe(entry)} response value changed`);
+      }
+    } else if (!presenceUnstable.has(key)) {
+      emit2("NEW_CALL", entry, `${describe(entry)} is new vs baseline`);
+    }
+  }
+  for (const [key, base] of baseline) {
+    if (!run.has(key) && !presenceUnstable.has(key)) {
+      emit2("MISSING_CALL", base, `${describe(base)} was expected but did not occur`);
+    }
+  }
+  divergences.sort(
+    (a, b) => SEVERITY[b.diffClass] - SEVERITY[a.diffClass] || a.identityKey.localeCompare(b.identityKey)
+  );
+  return {
+    divergences,
+    hasFailSignal: divergences.some((d) => d.failSignal)
+  };
+}
+function describe(e) {
+  const parts = e.identityKey.split("|");
+  return parts.length >= 3 ? `${parts[0]} ${parts[1]}${parts[2]}` : e.identityKey;
+}
+function summarizeForClassifier(result, maxLines = 20) {
+  if (result.divergences.length === 0) return "No backend network divergences detected.";
+  const lines = result.divergences.slice(0, maxLines).map((d) => `- [${d.diffClass}] ${d.detail} {attribution: ${d.attribution}}`);
+  const omitted = result.divergences.length - lines.length;
+  if (omitted > 0) lines.push(`- \u2026and ${omitted} more (lower severity).`);
+  return lines.join("\n");
+}
+var FAIL_SIGNAL_CLASSES;
+var SEVERITY;
+var init_diff_engine = __esm2({
+  "src/xray/diff-engine.ts"() {
+    FAIL_SIGNAL_CLASSES = /* @__PURE__ */ new Set([
+      "ERROR_RESPONSE",
+      "STATUS_CHANGED"
+    ]);
+    SEVERITY = {
+      ERROR_RESPONSE: 6,
+      STATUS_CHANGED: 5,
+      MISSING_CALL: 4,
+      NEW_CALL: 3,
+      SCHEMA_CHANGED: 2,
+      VALUE_CHANGED: 1
+    };
+  }
+});
+function networkDiffForTest(db, workflowId, testFile, testName, uiPassed) {
+  const netRuns = new NetRunsRepository(db);
+  const netRequests = new NetRequestsRepository(db);
+  const volatility = new NetVolatilityRepository(db);
+  const baselines = new BaselineSelector(db);
+  const base = testFile.split(/[\\/]/).pop() ?? testFile;
+  const title = testName.includes(" > ") ? testName.slice(testName.lastIndexOf(" > ") + 3) : testName;
+  const candidates = [
+    testIdFor(base, title),
+    testIdFor(testFile, testName),
+    // exact, in case conventions already align
+    testIdFor(base, testName)
+  ];
+  const runsForWorkflow = netRuns.listByWorkflow(workflowId);
+  const runRow = runsForWorkflow.find((r) => candidates.includes(r.testId)) ?? // Last resort: match on the bare title alone (suffix).
+  runsForWorkflow.find((r) => r.testId.endsWith(`::${title}`));
+  if (runRow === void 0) return null;
+  const baseline = baselines.select(runRow.testId, runRow.browser, runRow.runId);
+  if (baseline === null) return null;
+  const runGraph = buildRunGraph(netRequests.listByRun(runRow.runId));
+  const baseGraph = buildRunGraph(netRequests.listByRun(baseline.runId));
+  const result = diffGraphs(runGraph, baseGraph, {
+    volatility: volatility.listByTest(runRow.testId),
+    uiPassed
+  });
+  if (result.divergences.length === 0) return null;
+  return {
+    summary: summarizeForClassifier(result),
+    hasFailSignal: result.hasFailSignal
+  };
+}
+var init_classify_bridge = __esm2({
+  "src/xray/classify-bridge.ts"() {
+    init_net_runs();
+    init_net_requests();
+    init_net_volatility();
+    init_baseline();
+    init_diff_engine();
+    init_step_windows();
+  }
+});
+var xray_exports = {};
+__export2(xray_exports, {
+  BaselineSelector: () => BaselineSelector,
+  CaptureSession: () => CaptureSession,
+  DEFAULT_HEADER_DENYLIST: () => DEFAULT_HEADER_DENYLIST,
+  DEFAULT_VOLATILE_PARAMS: () => DEFAULT_VOLATILE_PARAMS,
+  FAIL_SIGNAL_CLASSES: () => FAIL_SIGNAL_CLASSES,
+  VolatilityLearner: () => VolatilityLearner,
+  attributeRequests: () => attributeRequests,
+  buildRunGraph: () => buildRunGraph,
+  canonicalizeBody: () => canonicalizeBody,
+  detectGraphql: () => detectGraphql,
+  diffGraphs: () => diffGraphs,
+  identityKey: () => identityKey,
+  learnVolatility: () => learnVolatility,
+  materializeWrapperConfig: () => materializeWrapperConfig,
+  networkDiffForTest: () => networkDiffForTest,
+  normalizeRequest: () => normalizeRequest,
+  parseHarFile: () => parseHarFile,
+  parseRedactionRules: () => parseRedactionRules,
+  parseStepWindows: () => parseStepWindows,
+  redactJson: () => redactJson,
+  resolveUserConfig: () => resolveUserConfig,
+  summarizeForClassifier: () => summarizeForClassifier,
+  templateUrl: () => templateUrl,
+  testIdFor: () => testIdFor
+});
+var init_xray = __esm2({
+  "src/xray/index.ts"() {
+    init_wrapper_config();
+    init_har_parser();
+    init_step_windows();
+    init_causality_engine();
+    init_identity();
+    init_capture_session();
+    init_normalizer();
+    init_baseline();
+    init_diff_engine();
+    init_volatility();
+    init_classify_bridge();
+  }
+});
 var StorageError = class extends Error {
   code;
   cause;
@@ -1086,7 +2597,7 @@ function runMigrations(db, migrationsDir) {
   const applied = [];
   const skipped = [];
   for (const filename of files) {
-    const fullPath = path12.join(migrationsDir, filename);
+    const fullPath = path15.join(migrationsDir, filename);
     const sql = readFileSync(fullPath, "utf-8");
     const checksum = sha256Hex(sql);
     const knownChecksum = appliedMap.get(filename);
@@ -1228,8 +2739,8 @@ var SqliteDb = class {
     this.db.close();
   }
 };
-var __dirname$1 = path12.dirname(fileURLToPath(import.meta.url));
-var DEFAULT_MIGRATIONS_DIR = path12.resolve(__dirname$1, "migrations");
+var __dirname$1 = path15.dirname(fileURLToPath(import.meta.url));
+var DEFAULT_MIGRATIONS_DIR = path15.resolve(__dirname$1, "migrations");
 var Storage = class _Storage {
   db;
   path;
@@ -1923,6 +3434,10 @@ var VisualDiffsRepository = class {
     return this.findById(id);
   }
 };
+init_net_runs();
+init_net_requests();
+init_net_bodies();
+init_net_volatility();
 function canonicalize(value) {
   return JSON.stringify(sortedDeep(value));
 }
@@ -2681,7 +4196,7 @@ function tempForTier(tier) {
       return 0.1;
   }
 }
-var DEFAULT_LLM_TIMEOUT_MS = 12e4;
+var DEFAULT_LLM_TIMEOUT_MS = 24e4;
 function llmTimeoutMs() {
   const raw = process.env["QAIOS_LLM_TIMEOUT_MS"];
   if (raw === void 0) return DEFAULT_LLM_TIMEOUT_MS;
@@ -2965,14 +4480,14 @@ function formatZodError(err) {
 }
 var PROJECT_MEMORY_FILENAME = "QAIOS.md";
 function loadProjectMemory(projectRoot) {
-  const fullPath = path12.join(projectRoot, PROJECT_MEMORY_FILENAME);
+  const fullPath = path15.join(projectRoot, PROJECT_MEMORY_FILENAME);
   if (!existsSync(fullPath)) return null;
   const text = readFileSync(fullPath, "utf-8");
   return parseProjectMemory(text);
 }
 var DEFAULT_COST_CAP = {
-  maxCalls: 15,
-  maxUsdCents: 50
+  maxCalls: 20,
+  maxUsdCents: 100
 };
 var CostTracker = class {
   constructor(db) {
@@ -3109,8 +4624,8 @@ function expectedCostCents(skillId) {
 }
 var whereCache = /* @__PURE__ */ new Map();
 function resolveBinaryWindows(name) {
-  if (path12.isAbsolute(name)) return name;
-  if (name.includes(path12.sep) || name.includes("/")) return path12.resolve(name);
+  if (path15.isAbsolute(name)) return name;
+  if (name.includes(path15.sep) || name.includes("/")) return path15.resolve(name);
   if (whereCache.has(name)) return whereCache.get(name) ?? null;
   const r = spawnSync("where", [name], { encoding: "utf8", shell: false });
   if (r.status !== 0) {
@@ -3291,9 +4806,9 @@ var PlaywrightSubprocessAdapter = class {
     const runId = opts.runId ?? ulid();
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const startTimeMs = Date.now();
-    const artifactsDir = opts.artifactsDir ?? path12.join(opts.cwd, ".qaios", "runs", runId);
+    const artifactsDir = opts.artifactsDir ?? path15.join(opts.cwd, ".qaios", "runs", runId);
     mkdirSync(artifactsDir, { recursive: true });
-    const reportPath = path12.join(artifactsDir, "results.json");
+    const reportPath = path15.join(artifactsDir, "results.json");
     const runningRow = {
       id: runId,
       workflowId: opts.workflowId,
@@ -3318,20 +4833,59 @@ var PlaywrightSubprocessAdapter = class {
       );
     }
     const [bin, ...baseArgs] = command;
+    const xrayDir = path15.join(opts.cwd, ".qaios", "xray");
+    const harPath = path15.join(xrayDir, `${runId}.har`);
+    let xrayConfigArgs = [];
+    let xrayEnv = {};
+    let xrayActive = false;
+    let xrayCleanupPath = null;
+    let xrayStepsPath = null;
+    let reporterArg = "--reporter=json";
+    if (opts.xray !== void 0) {
+      try {
+        const { materializeWrapperConfig: materializeWrapperConfig2 } = await Promise.resolve().then(() => (init_xray(), xray_exports));
+        const wrapper = materializeWrapperConfig2({
+          cwd: opts.cwd,
+          xrayDir,
+          harPath,
+          level: opts.xray.level,
+          ...opts.xray.testDir !== void 0 ? { testDir: opts.xray.testDir } : {}
+        });
+        xrayConfigArgs = [`--config=${wrapper.configPath}`];
+        xrayEnv = wrapper.env;
+        xrayCleanupPath = wrapper.cleanupPath;
+        xrayStepsPath = wrapper.stepsPath;
+        reporterArg = `--reporter=json,${wrapper.stepReporterPath}`;
+        xrayActive = true;
+      } catch (err) {
+        process.stderr.write(
+          `[qaios xray] capture disabled for this run: ${err.message}
+`
+        );
+      }
+    }
     const args = [
       ...baseArgs,
-      "--reporter=json",
+      ...xrayConfigArgs,
+      reporterArg,
       ...opts.pattern !== void 0 ? [opts.pattern] : [],
       ...opts.extraArgs ?? []
     ];
     const env = {
       ...process.env,
+      ...xrayEnv,
       PLAYWRIGHT_JSON_OUTPUT_NAME: reportPath
     };
     const subprocessResult = await this.spawnPlaywright(bin, args, opts.cwd, env, {
       ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
       ...opts.cancelSignal !== void 0 ? { cancelSignal: opts.cancelSignal } : {}
     });
+    if (xrayCleanupPath !== null) {
+      try {
+        rmSync(xrayCleanupPath, { force: true });
+      } catch {
+      }
+    }
     let report;
     let parseFailedReason = null;
     try {
@@ -3387,6 +4941,32 @@ var PlaywrightSubprocessAdapter = class {
       },
       actor: "system"
     });
+    if (xrayActive && opts.xray !== void 0) {
+      try {
+        const { CaptureSession: CaptureSession2 } = await Promise.resolve().then(() => (init_xray(), xray_exports));
+        const session = new CaptureSession2({
+          db: this.deps.storage.db,
+          auditLogger: this.deps.auditLogger
+        });
+        session.ingest({
+          workflowId: opts.workflowId,
+          harPath,
+          reportPath,
+          browser: "chromium",
+          level: opts.xray.level,
+          startedAt,
+          ...xrayStepsPath !== null ? { stepsPath: xrayStepsPath } : {},
+          ...opts.xray.quiescenceMs !== void 0 ? { quiescenceMs: opts.xray.quiescenceMs } : {},
+          ...opts.xray.volatileParams !== void 0 ? { volatileParams: opts.xray.volatileParams } : {},
+          ...opts.xray.redact !== void 0 ? { redact: opts.xray.redact } : {}
+        });
+      } catch (err) {
+        process.stderr.write(
+          `[qaios xray] capture ingest failed (run still recorded): ${err.message}
+`
+        );
+      }
+    }
     const finalRow = this.runsRepo.findById(runId);
     if (!finalRow) {
       throw new PlaywrightAdapterError(
@@ -3495,16 +5075,16 @@ function truncateHtmlSafe(html, max = PAGE_CAPTURE_HTML_MAX_CHARS) {
   return slice + "\n<!-- truncated -->";
 }
 function defaultCaptureScriptPath() {
-  const here = path12.dirname(fileURLToPath(import.meta.url));
+  const here22 = path15.dirname(fileURLToPath(import.meta.url));
   const candidates = [
     // tsup flattens src/healing/page-capture.ts to dist/index.js, so
     // `here` is dist/. The mirror lives at dist/healing/scripts/.
-    path12.resolve(here, "healing", "scripts", "capture-page.mjs"),
+    path15.resolve(here22, "healing", "scripts", "capture-page.mjs"),
     // Co-located when bundled to dist/healing/.
-    path12.resolve(here, "scripts", "capture-page.mjs"),
+    path15.resolve(here22, "scripts", "capture-page.mjs"),
     // Source layout under vitest.
-    path12.resolve(here, "scripts", "capture-page.mjs"),
-    path12.resolve(here, "..", "healing", "scripts", "capture-page.mjs")
+    path15.resolve(here22, "scripts", "capture-page.mjs"),
+    path15.resolve(here22, "..", "healing", "scripts", "capture-page.mjs")
   ];
   for (const c of candidates) {
     if (existsSync(c)) return c;
@@ -3512,8 +5092,8 @@ function defaultCaptureScriptPath() {
   return candidates[0];
 }
 async function capturePageSnapshot(opts) {
-  const tmp = mkdtempSync(path12.join(tmpdir(), "qaios-capture-"));
-  const out = path12.join(tmp, "snapshot.json");
+  const tmp = mkdtempSync(path15.join(tmpdir(), "qaios-capture-"));
+  const out = path15.join(tmp, "snapshot.json");
   mkdirSync(tmp, { recursive: true });
   const timeoutMs = opts.timeoutMs ?? 3e4;
   const command = opts.command ?? ["node", defaultCaptureScriptPath()];
@@ -3699,14 +5279,14 @@ function applyLocatorFix(opts) {
     };
   }
   const cwd = opts.cwd ?? process.cwd();
-  const absPath = path12.isAbsolute(opts.testFile) ? opts.testFile : path12.resolve(cwd, opts.testFile);
+  const absPath = path15.isAbsolute(opts.testFile) ? opts.testFile : path15.resolve(cwd, opts.testFile);
   const oldContents = readFileSync(absPath, "utf-8");
   const occurrences = countOccurrences(oldContents, opts.fix.oldLocator);
   if (occurrences === 0) {
     return {
       applied: false,
       reason: "old_locator_not_found",
-      detail: `old locator not present in ${path12.relative(cwd, absPath)}: ${opts.fix.oldLocator}`,
+      detail: `old locator not present in ${path15.relative(cwd, absPath)}: ${opts.fix.oldLocator}`,
       oldContents,
       newContents: null
     };
@@ -3715,7 +5295,7 @@ function applyLocatorFix(opts) {
     return {
       applied: false,
       reason: "old_locator_not_unique",
-      detail: `old locator appears ${occurrences} times in ${path12.relative(cwd, absPath)}; refusing to patch ambiguously.`,
+      detail: `old locator appears ${occurrences} times in ${path15.relative(cwd, absPath)}; refusing to patch ambiguously.`,
       oldContents,
       newContents: null
     };
@@ -3753,7 +5333,7 @@ function applyLocatorFix(opts) {
       event: "artifact.updated",
       payload: {
         kind: "locator_fix",
-        testFile: path12.relative(cwd, absPath),
+        testFile: path15.relative(cwd, absPath),
         oldLocator: opts.fix.oldLocator,
         newLocator: opts.fix.newLocator,
         fixKind: opts.fix.fixKind,
@@ -3780,12 +5360,12 @@ function extractLocatorFromError(errorMessage) {
   return null;
 }
 function resolveTestFile(testFile, cwd, configuredTestDir) {
-  if (path12.isAbsolute(testFile)) return testFile;
+  if (path15.isAbsolute(testFile)) return testFile;
   const candidateDirs = ["", configuredTestDir ?? "tests", "tests", "test", "e2e"];
   for (const dir of candidateDirs) {
     if (dir === void 0) continue;
-    if (existsSync(path12.join(cwd, dir, testFile))) {
-      return path12.join(dir, testFile);
+    if (existsSync(path15.join(cwd, dir, testFile))) {
+      return path15.join(dir, testFile);
     }
   }
   return testFile;
@@ -3812,19 +5392,19 @@ async function fileDefect(opts) {
   const { defect, target } = opts;
   const allowedTools = opts.allowedTools ?? ["github:create_issue", "jira:create_issue"];
   if (target.integration === "stdout") {
-    const write = opts.stdoutWrite ?? ((s) => process.stdout.write(s));
-    write(`
+    const write2 = opts.stdoutWrite ?? ((s) => process.stdout.write(s));
+    write2(`
 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 DEFECT (stdout target) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 `);
-    write(`${defect.title}
+    write2(`${defect.title}
 
 `);
-    write(`${defect.body}
+    write2(`${defect.body}
 `);
-    if (defect.labels.length > 0) write(`
+    if (defect.labels.length > 0) write2(`
 Labels: ${defect.labels.join(", ")}
 `);
-    write(`\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    write2(`\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 `);
     audit(opts, "defect.filed", {
       target: "stdout",
@@ -4313,13 +5893,13 @@ function buildGatePayload(gateType, prior) {
   }
   if (gateType === "writing_review") {
     const writeKey2 = Object.keys(prior).find((k) => k.startsWith("write."));
-    const write = writeKey2 !== void 0 ? prior[writeKey2] : null;
-    const files = Array.isArray(write?.["files"]) ? write["files"] : [];
+    const write2 = writeKey2 !== void 0 ? prior[writeKey2] : null;
+    const files = Array.isArray(write2?.["files"]) ? write2["files"] : [];
     return {
       writeSkill: writeKey2 ?? null,
       fileCount: files.length,
-      qaiosMdSuggestionCount: Array.isArray(write?.["qaiosMdSuggestions"]) ? write["qaiosMdSuggestions"].length : 0,
-      reasoning: write?.["reasoning"] ?? null
+      qaiosMdSuggestionCount: Array.isArray(write2?.["qaiosMdSuggestions"]) ? write2["qaiosMdSuggestions"].length : 0,
+      reasoning: write2?.["reasoning"] ?? null
     };
   }
   return {};
@@ -4504,6 +6084,11 @@ var readyToRun = async (deps) => {
   }
   return { nextState: "completed" };
 };
+function isXrayArg(v) {
+  if (v === null || typeof v !== "object") return false;
+  const level = v.level;
+  return level === "headers" || level === "summary" || level === "full" || level === "off";
+}
 var running = async (deps) => {
   const cwd = typeof deps.args["cwd"] === "string" ? deps.args["cwd"] : process.cwd();
   const adapterOpts = {
@@ -4521,7 +6106,14 @@ var running = async (deps) => {
       )
     } : {},
     ...typeof deps.args["executionTimeoutMs"] === "number" ? { timeoutMs: deps.args["executionTimeoutMs"] } : {},
-    ...deps.skillCtx.cancelSignal !== void 0 ? { cancelSignal: deps.skillCtx.cancelSignal } : {}
+    ...deps.skillCtx.cancelSignal !== void 0 ? { cancelSignal: deps.skillCtx.cancelSignal } : {},
+    ...isXrayArg(deps.args["xray"]) ? {
+      xray: {
+        ...deps.args["xray"],
+        // Anchor capture's testDir to the same dir healing/writing use.
+        ...typeof deps.args["testDir"] === "string" ? { testDir: deps.args["testDir"] } : {}
+      }
+    } : {}
   };
   const adapterResult = await deps.executionAdapter.run(adapterOpts);
   return {
@@ -4543,14 +6135,39 @@ var running = async (deps) => {
     }
   };
 };
-var classifying = async (deps) => {
-  if (deps.args["noClassify"] === true) {
-    return { nextState: "completed" };
+async function emitPassWithDivergence(deps, testResults, networkDiffFor) {
+  if (deps.storage === void 0) return;
+  const passed = testResults.filter((t) => t.status === "passed");
+  const flagged = [];
+  for (const tr of passed) {
+    const diff = networkDiffFor(deps.storage.db, deps.workflow.id, tr.testFile, tr.testName, true);
+    if (diff !== null && diff.hasFailSignal) {
+      flagged.push({ test: tr.testName, summary: diff.summary });
+    }
   }
+  if (flagged.length === 0) return;
+  deps.auditLogger.append({
+    workflowId: deps.workflow.id,
+    phase: "EXECUTION",
+    skillId: null,
+    event: "xray.diff",
+    payload: { passWithDivergence: true, count: flagged.length, flagged },
+    actor: "system"
+  });
+}
+var classifying = async (deps) => {
   const exec = deps.prior["execute.playwright"];
   if (!exec || !Array.isArray(exec.testResults)) {
     return { nextState: "completed" };
   }
+  const xrayRan = isXrayArg(deps.args["xray"]) && deps.storage !== void 0;
+  const networkDiffFor = xrayRan ? (await Promise.resolve().then(() => (init_xray(), xray_exports))).networkDiffForTest : null;
+  if (networkDiffFor !== null && deps.storage !== void 0) {
+    await emitPassWithDivergence(deps, exec.testResults, networkDiffFor);
+  }
+  if (deps.args["noClassify"] === true) {
+    return { nextState: "completed" };
+  }
   const failed2 = exec.testResults.filter((t) => t.status === "failed");
   if (failed2.length === 0) {
     return { nextState: "completed" };
@@ -4568,6 +6185,7 @@ var classifying = async (deps) => {
       excludeRunId: tr.runId,
       limit: 10
     });
+    const netDiff = networkDiffFor !== null && deps.storage !== void 0 ? networkDiffFor(deps.storage.db, deps.workflow.id, tr.testFile, tr.testName, false) : null;
     const classifyInput = {
       testResult: {
         file: tr.testFile,
@@ -4577,7 +6195,8 @@ var classifying = async (deps) => {
         attachments: [],
         historicalRuns,
         ...errorBlock
-      }
+      },
+      ...netDiff !== null ? { networkDiff: netDiff } : {}
     };
     const result = await deps.skillRunner.run(classifySkill, deps.skillCtx, classifyInput);
     deps.testResultsRepo.setClassification(tr.id, result.output);
@@ -5321,6 +6940,8 @@ var Orchestrator = class {
           executionAdapter: this.executionAdapter,
           testResultsRepo: this.testResultsRepo,
           gatesRepo: this.gatesRepo,
+          // Storage handle for the classifying state's xray diff lookup (v0.4).
+          storage: this.deps.storage,
           // F3 pre-flight: hand the cost tracker + cap to runSkill so
           // it can abort before launching a skill that would tip the
           // cap. costCap=null (opt-out) is propagated as-is.
@@ -5474,11 +7095,11 @@ var AxeRunError = class extends Error {
   }
 };
 function defaultAxeScriptPath() {
-  const here = path12.dirname(fileURLToPath(import.meta.url));
+  const here22 = path15.dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    path12.resolve(here, "a11y", "scripts", "axe-runner.mjs"),
-    path12.resolve(here, "scripts", "axe-runner.mjs"),
-    path12.resolve(here, "..", "a11y", "scripts", "axe-runner.mjs")
+    path15.resolve(here22, "a11y", "scripts", "axe-runner.mjs"),
+    path15.resolve(here22, "scripts", "axe-runner.mjs"),
+    path15.resolve(here22, "..", "a11y", "scripts", "axe-runner.mjs")
   ];
   for (const c of candidates) {
     if (existsSync(c)) return c;
@@ -5486,8 +7107,8 @@ function defaultAxeScriptPath() {
   return candidates[0];
 }
 async function runAxe(opts) {
-  const tmp = mkdtempSync(path12.join(tmpdir(), "qaios-axe-"));
-  const out = path12.join(tmp, "findings.json");
+  const tmp = mkdtempSync(path15.join(tmpdir(), "qaios-axe-"));
+  const out = path15.join(tmp, "findings.json");
   mkdirSync(tmp, { recursive: true });
   const timeoutMs = opts.timeoutMs ?? 45e3;
   const command = opts.command ?? ["node", defaultAxeScriptPath()];
@@ -5612,14 +7233,14 @@ var SnapshotCaptureError = class extends Error {
   }
 };
 function defaultCaptureScriptPath2() {
-  const here = path12.dirname(fileURLToPath(import.meta.url));
+  const here22 = path15.dirname(fileURLToPath(import.meta.url));
   const candidates = [
     // Bundled (tsup flattens src/visual/snapshot-capture.ts → dist/index.js).
-    path12.resolve(here, "visual", "scripts", "capture-screenshot.mjs"),
+    path15.resolve(here22, "visual", "scripts", "capture-screenshot.mjs"),
     // Co-located fallback.
-    path12.resolve(here, "scripts", "capture-screenshot.mjs"),
+    path15.resolve(here22, "scripts", "capture-screenshot.mjs"),
     // Source layout under vitest.
-    path12.resolve(here, "..", "visual", "scripts", "capture-screenshot.mjs")
+    path15.resolve(here22, "..", "visual", "scripts", "capture-screenshot.mjs")
   ];
   for (const c of candidates) {
     if (existsSync(c)) return c;
@@ -5629,7 +7250,7 @@ function defaultCaptureScriptPath2() {
 function safeName(name) {
   return name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120) || "snapshot";
 }
-function sha256Hex3(buffer) {
+function sha256Hex4(buffer) {
   return createHash("sha256").update(buffer).digest("hex");
 }
 async function captureVisualBaselines(opts) {
@@ -5644,7 +7265,7 @@ async function captureVisualBaselines(opts) {
     );
   }
   const [bin, ...args] = command;
-  const baselinesDir = opts.baselinesDir ?? path12.join(opts.cwd, ".qaios", "baselines");
+  const baselinesDir = opts.baselinesDir ?? path15.join(opts.cwd, ".qaios", "baselines");
   const repo = new VisualBaselinesRepository(opts.storage.db);
   const viewportByName = new Map(opts.viewports.map((v) => [v.name, v]));
   const baselines = [];
@@ -5667,8 +7288,8 @@ async function captureVisualBaselines(opts) {
       const relImagePath = [".qaios", "baselines", dim.name, `${safeName(snapshot.name)}.png`].join(
         "/"
       );
-      const absImagePath = path12.join(baselinesDir, dim.name, `${safeName(snapshot.name)}.png`);
-      mkdirSync(path12.dirname(absImagePath), { recursive: true });
+      const absImagePath = path15.join(baselinesDir, dim.name, `${safeName(snapshot.name)}.png`);
+      mkdirSync(path15.dirname(absImagePath), { recursive: true });
       const env = {
         ...process.env,
         QAIOS_SCREENSHOT_URL: joinUrl(opts.baseUrl, snapshot.route),
@@ -5705,7 +7326,7 @@ async function captureVisualBaselines(opts) {
         );
       }
       const bytes = readFileSync(absImagePath);
-      const sha = sha256Hex3(bytes);
+      const sha = sha256Hex4(bytes);
       const baselineId = ulid();
       const approvedAt = (/* @__PURE__ */ new Date()).toISOString();
       const baselineInput = {
@@ -5936,7 +7557,7 @@ function diffImages(baselinePath, currentPath, diffOutPath, opts = {}) {
       diffMask[i] = 1;
     }
   }
-  mkdirSync(path12.dirname(diffOutPath), { recursive: true });
+  mkdirSync(path15.dirname(diffOutPath), { recursive: true });
   writeFileSync(diffOutPath, PNG.sync.write(diffPng));
   const totalPixels = width * height;
   const percentageChanged = Number((pixelsChanged / totalPixels * 100).toFixed(4));
@@ -6002,18 +7623,18 @@ var SnapshotCheckError = class extends Error {
   }
 };
 function defaultCaptureScriptPath3() {
-  const here = path12.dirname(fileURLToPath(import.meta.url));
+  const here22 = path15.dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    path12.resolve(here, "visual", "scripts", "capture-screenshot.mjs"),
-    path12.resolve(here, "scripts", "capture-screenshot.mjs"),
-    path12.resolve(here, "..", "visual", "scripts", "capture-screenshot.mjs")
+    path15.resolve(here22, "visual", "scripts", "capture-screenshot.mjs"),
+    path15.resolve(here22, "scripts", "capture-screenshot.mjs"),
+    path15.resolve(here22, "..", "visual", "scripts", "capture-screenshot.mjs")
   ];
   for (const c of candidates) {
     if (existsSync(c)) return c;
   }
   return candidates[0];
 }
-function sha256Hex4(buf) {
+function sha256Hex5(buf) {
   return createHash("sha256").update(buf).digest("hex");
 }
 function spawnCapture3(bin, args, cwd, env, opts) {
@@ -6083,8 +7704,8 @@ async function runVisualCheck(opts) {
   }
   const [bin, ...args] = command;
   const thresholdPct = opts.thresholdPct ?? 0.1;
-  const runsDir = opts.runsDir ?? path12.join(opts.cwd, ".qaios", "runs", opts.workflowId);
-  const diffsDir = opts.diffsDir ?? path12.join(opts.cwd, ".qaios", "diffs", opts.workflowId);
+  const runsDir = opts.runsDir ?? path15.join(opts.cwd, ".qaios", "runs", opts.workflowId);
+  const diffsDir = opts.diffsDir ?? path15.join(opts.cwd, ".qaios", "diffs", opts.workflowId);
   new VisualBaselinesRepository(opts.storage.db);
   const diffRepo = new VisualDiffsRepository(opts.storage.db);
   const skillRunner = opts.skillRunner ?? new SkillRunner();
@@ -6109,7 +7730,7 @@ async function runVisualCheck(opts) {
         `baseline ${baseline.id} references unknown viewport "${baseline.viewport}"`
       );
     }
-    const baselineAbsPath = path12.isAbsolute(baseline.imagePath) ? baseline.imagePath : path12.join(opts.cwd, baseline.imagePath);
+    const baselineAbsPath = path15.isAbsolute(baseline.imagePath) ? baseline.imagePath : path15.join(opts.cwd, baseline.imagePath);
     if (!existsSync(baselineAbsPath)) {
       perBaseline.push({
         baselineId: baseline.id,
@@ -6125,9 +7746,9 @@ async function runVisualCheck(opts) {
       summary.pendingReview++;
       continue;
     }
-    const safe = path12.basename(baseline.imagePath);
-    const currentAbsPath = path12.join(runsDir, baseline.viewport, safe);
-    mkdirSync(path12.dirname(currentAbsPath), { recursive: true });
+    const safe = path15.basename(baseline.imagePath);
+    const currentAbsPath = path15.join(runsDir, baseline.viewport, safe);
+    mkdirSync(path15.dirname(currentAbsPath), { recursive: true });
     const env = {
       ...process.env,
       QAIOS_SCREENSHOT_URL: joinUrl(opts.baseUrl, baseline.route),
@@ -6156,11 +7777,11 @@ async function runVisualCheck(opts) {
     }
     const baselineBytes = readFileSync(baselineAbsPath);
     const currentBytes = readFileSync(currentAbsPath);
-    const baselineSha = sha256Hex4(baselineBytes);
-    const currentSha = sha256Hex4(currentBytes);
-    const currentImagePath = path12.relative(opts.cwd, currentAbsPath).split(path12.sep).join("/");
-    const diffAbsPath = path12.join(diffsDir, baseline.viewport, safe);
-    const diffImagePath = path12.relative(opts.cwd, diffAbsPath).split(path12.sep).join("/");
+    const baselineSha = sha256Hex5(baselineBytes);
+    const currentSha = sha256Hex5(currentBytes);
+    const currentImagePath = path15.relative(opts.cwd, currentAbsPath).split(path15.sep).join("/");
+    const diffAbsPath = path15.join(diffsDir, baseline.viewport, safe);
+    const diffImagePath = path15.relative(opts.cwd, diffAbsPath).split(path15.sep).join("/");
     if (baselineSha === currentSha) {
       perBaseline.push({
         baselineId: baseline.id,
@@ -6176,7 +7797,7 @@ async function runVisualCheck(opts) {
       summary.noDiff++;
       continue;
     }
-    mkdirSync(path12.dirname(diffAbsPath), { recursive: true });
+    mkdirSync(path15.dirname(diffAbsPath), { recursive: true });
     const diff = diffImages(baselineAbsPath, currentAbsPath, diffAbsPath);
     if (diff.sizeMismatch) {
       const diffId2 = ulid();
@@ -6361,7 +7982,7 @@ var OpenApiParseError = class extends Error {
 };
 var HTTP_METHODS = /* @__PURE__ */ new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
 function parseOpenApi(specPath) {
-  const abs = path12.resolve(specPath);
+  const abs = path15.resolve(specPath);
   if (!existsSync(abs)) {
     throw new OpenApiParseError("qaios.openapi.spec_not_found", `OpenAPI spec not found at ${abs}`);
   }
@@ -6858,6 +8479,10 @@ var ExitCode = {
   // rate limit, timeout, key invalid
   INTERNAL: 5,
   // QAIOS bug — should be reported
+  // The UI tests passed, but xray detected a backend divergence (a 4xx/5xx or
+  // status change on a call the test made). Only returned under `--xray-strict`;
+  // without it, such a run is exit 0 with a warning. (v0.4)
+  PASS_WITH_NETWORK_DIVERGENCE: 6,
   CANCELLED: 130
   // user pressed Ctrl+C (SIGINT)
 };
@@ -6867,7 +8492,7 @@ function detectProject(projectRoot) {
   const playwrightVersion = readPlaywrightVersion(packageJson);
   const hasPlaywright = playwrightVersion !== null;
   const testDir = detectTestDir(projectRoot);
-  const projectName = packageJson?.name ?? path12.basename(path12.resolve(projectRoot));
+  const projectName = packageJson?.name ?? path15.basename(path15.resolve(projectRoot));
   const isEmpty = directoryIsEmpty(projectRoot);
   const looksLikeProject = packageJson !== null;
   return {
@@ -6882,7 +8507,7 @@ function detectProject(projectRoot) {
   };
 }
 function readPackageJson(projectRoot) {
-  const p = path12.join(projectRoot, "package.json");
+  const p = path15.join(projectRoot, "package.json");
   if (!existsSync(p)) return null;
   try {
     return JSON.parse(readFileSync(p, "utf-8"));
@@ -6891,10 +8516,10 @@ function readPackageJson(projectRoot) {
   }
 }
 function detectPackageManager(projectRoot) {
-  if (existsSync(path12.join(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync(path12.join(projectRoot, "bun.lockb"))) return "bun";
-  if (existsSync(path12.join(projectRoot, "yarn.lock"))) return "yarn";
-  if (existsSync(path12.join(projectRoot, "package-lock.json"))) return "npm";
+  if (existsSync(path15.join(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(path15.join(projectRoot, "bun.lockb"))) return "bun";
+  if (existsSync(path15.join(projectRoot, "yarn.lock"))) return "yarn";
+  if (existsSync(path15.join(projectRoot, "package-lock.json"))) return "npm";
   return "unknown";
 }
 function readPlaywrightVersion(pkg) {
@@ -6903,7 +8528,7 @@ function readPlaywrightVersion(pkg) {
 }
 function detectTestDir(projectRoot) {
   for (const candidate of ["tests", "e2e", "playwright"]) {
-    const full = path12.join(projectRoot, candidate);
+    const full = path15.join(projectRoot, candidate);
     if (existsSync(full)) {
       try {
         if (statSync(full).isDirectory()) return candidate;
@@ -6929,12 +8554,12 @@ function runDoctorEnv() {
   return { exitCode: ExitCode.SUCCESS, envSnapshot: snapshotEnv() };
 }
 function runDoctor(opts = {}) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
   const checks = [];
   checks.push(checkNode());
   const apiKeyCheck = checkProviderApiKey(cwd);
   checks.push(apiKeyCheck);
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const qaiosDir = path15.join(cwd, ".qaios");
   const qaiosExists = existsSync(qaiosDir) && safeIsDir(qaiosDir);
   checks.push({
     name: ".qaios/ directory",
@@ -6942,7 +8567,7 @@ function runDoctor(opts = {}) {
     detail: qaiosExists ? `present at ${qaiosDir}` : `missing at ${qaiosDir}. Run \`qaios init\` first.`
   });
   if (qaiosExists) {
-    const dbPath = path12.join(qaiosDir, "workflows.db");
+    const dbPath = path15.join(qaiosDir, "workflows.db");
     if (!existsSync(dbPath)) {
       checks.push({
         name: "SQLite DB",
@@ -6971,7 +8596,7 @@ function runDoctor(opts = {}) {
 function checkConfig(qaiosDir, qaiosExists) {
   const name = "config.yaml";
   if (!qaiosExists) return { name, status: "skip", detail: "skipped (no .qaios/)" };
-  const configPath = path12.join(qaiosDir, "config.yaml");
+  const configPath = path15.join(qaiosDir, "config.yaml");
   if (!existsSync(configPath)) {
     return { name, status: "skip", detail: "not present (defaults will be used)" };
   }
@@ -7002,7 +8627,7 @@ function checkNode() {
   };
 }
 function resolveProviderFromConfig(cwd) {
-  const candidate = path12.join(cwd, ".qaios", "config.yaml");
+  const candidate = path15.join(cwd, ".qaios", "config.yaml");
   if (!existsSync(candidate)) return { provider: "anthropic" };
   try {
     const raw = parse(readFileSync(candidate, "utf-8"));
@@ -7103,7 +8728,7 @@ function checkPlaywright(cwd) {
 }
 function checkAxeCore(cwd) {
   try {
-    const pkgPath = path12.join(cwd, "package.json");
+    const pkgPath = path15.join(cwd, "package.json");
     if (!existsSync(pkgPath)) {
       return { name: "axe-core (a11y)", status: "skip", detail: "no package.json" };
     }
@@ -7391,8 +9016,8 @@ function scopeFooterApi(scope) {
 }
 var STATUS_OR_RESPONSE_PATTERN = /\b[1-5]\d\d\b|response\./i;
 var MIN_SCENARIOS_PER_ENDPOINT = 3;
-function endpointStepPattern(path18, method) {
-  const escaped = path18.split("/").map(
+function endpointStepPattern(path20, method) {
+  const escaped = path20.split("/").map(
     (seg) => /^\{.*\}$/.test(seg) ? "[^/\\s?#]+" : seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
   ).join("/");
   return new RegExp(`\\b${method}\\b[\\s\\S]*?${escaped}(?=$|[\\s?#])`, "i");
@@ -7702,6 +9327,15 @@ var ClassifyResultInput = z.object({
   designSpec: z.object({
     scenarioId: z.string().optional(),
     oracle: z.string().optional()
+  }).optional(),
+  // xray (v0.4): a compact, deterministic summary of how this test's network
+  // traffic diverged from its baseline contract. Present only when xray ran.
+  // Lets the classifier reach `backend_divergence` when the UI error (or even a
+  // UI pass) is explained by a backend 4xx/5xx / status / shape change.
+  networkDiff: z.object({
+    summary: z.string(),
+    // already truncated ≤~1,500 tokens by the diff engine
+    hasFailSignal: z.boolean()
   }).optional()
 });
 function buildSystemPrompt5(projectMemory) {
@@ -7722,6 +9356,11 @@ Classification rubric:
 - expectation_outdated: app intentionally changed but test wasn't updated. Cues:
   app screenshot looks correct/intentional but assertion checks old text/structure.
   Difficult to detect without app context \u2014 be cautious here.
+- backend_divergence: the UI may look fine but the BACKEND diverged from its known-good
+  baseline. Cues: the "Network divergence" section below shows an ERROR_RESPONSE (a
+  4xx/5xx or failed request) or STATUS_CHANGED on a call this test made \u2014 especially
+  when the UI assertions passed. This is the class for "the page rendered but the API
+  broke". Prefer this over real_failure when a network fail-signal explains the result.
 - unknown: cannot classify with confidence. Default if multiple categories plausible.
 
 Suggested action mapping:
@@ -7730,6 +9369,7 @@ Suggested action mapping:
 - environmental \u2192 investigate_env (do not file as defect against the app)
 - locator_broken \u2192 heal_locator
 - expectation_outdated \u2192 update_test (but flag for human review)
+- backend_divergence \u2192 create_defect (cite the offending identity key + diff class)
 - unknown \u2192 needs_human_review
 
 Project context:
@@ -7744,6 +9384,10 @@ function buildUserPrompt5(input) {
   const attachments = tr.attachments.length === 0 ? "(none)" : tr.attachments.join(", ");
   const historicalJson = JSON.stringify(tr.historicalRuns, null, 2);
   const oracle = input.designSpec?.oracle ?? "(unspecified)";
+  const networkSection = input.networkDiff !== void 0 ? `
+
+Network divergence (vs baseline contract${input.networkDiff.hasFailSignal ? ", FAIL-SIGNAL present" : ""}):
+${input.networkDiff.summary}` : "";
   return `Test that failed:
 File: ${tr.file}
 Test: ${tr.name}
@@ -7761,7 +9405,7 @@ Attachments: ${attachments}
 Historical runs (most recent first):
 ${historicalJson}
 
-Oracle (if available): ${oracle}
+Oracle (if available): ${oracle}${networkSection}
 
 Classify this failure.`;
 }
@@ -8681,7 +10325,7 @@ function resolveLlmClient(injected, llmConfig) {
 
 // src/commands/a11y.ts
 function loadConfig(cwd) {
-  const candidate = path12.join(cwd, ".qaios", "config.yaml");
+  const candidate = path15.join(cwd, ".qaios", "config.yaml");
   if (!existsSync(candidate)) return null;
   try {
     return parse(readFileSync(candidate, "utf-8"));
@@ -8691,7 +10335,7 @@ function loadConfig(cwd) {
 }
 var GLYPH = { ok: "\u2713", failed: "\u2717", warn: "\u26A0", issue: "\u2691" };
 async function runA11y(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
   if (!opts.url || opts.url.trim().length === 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -8701,7 +10345,7 @@ async function runA11y(opts) {
       }
     };
   }
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -8716,7 +10360,7 @@ async function runA11y(opts) {
   const mode = opts.mode ?? config?.mode ?? "LITE";
   const wcagLevel = opts.wcagLevel ?? "AA";
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const auditLogger = new AuditLogger(storage.db);
   const workflowsRepo = new WorkflowsRepository(storage.db);
   const llm = resolveLlmClient(opts.llm, config?.llm);
@@ -8783,11 +10427,11 @@ async function runA11y(opts) {
       `  ${GLYPH.ok} scan complete \u2014 ${violationCount} violation(s), ${incompleteCount} needs-review, ${bestPracticeCount} best-practice`
     );
     writeOut("");
-    const specsDir = path12.join(qaiosDir, "specs", workflowId);
+    const specsDir = path15.join(qaiosDir, "specs", workflowId);
     if (findings.length === 0) {
       mkdirSync(specsDir, { recursive: true });
       writeFileSync(
-        path12.join(specsDir, "A11yReport.json"),
+        path15.join(specsDir, "A11yReport.json"),
         JSON.stringify({ url: opts.url, wcagLevel, findings: [], issues: [] }, null, 2) + "\n"
       );
       writeOut("No accessibility issues found.");
@@ -8841,7 +10485,7 @@ async function runA11y(opts) {
     const issues = triaged?.issues ?? [];
     mkdirSync(specsDir, { recursive: true });
     writeFileSync(
-      path12.join(specsDir, "A11yReport.json"),
+      path15.join(specsDir, "A11yReport.json"),
       JSON.stringify({ url: opts.url, wcagLevel, findings, issues }, null, 2) + "\n"
     );
     writeOut("");
@@ -8986,7 +10630,7 @@ async function fileIssueAsDefect(args) {
   };
 }
 function loadConfig2(cwd) {
-  const candidate = path12.join(cwd, ".qaios", "config.yaml");
+  const candidate = path15.join(cwd, ".qaios", "config.yaml");
   if (!existsSync(candidate)) return null;
   try {
     return parse(readFileSync(candidate, "utf-8"));
@@ -9004,7 +10648,7 @@ function renderTextLine(line) {
   return line + "\n";
 }
 async function runExplore(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
   if (!opts.url || opts.url.trim().length === 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -9014,7 +10658,7 @@ async function runExplore(opts) {
       }
     };
   }
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -9040,7 +10684,7 @@ async function runExplore(opts) {
   const memory = loadProjectMemory(cwd);
   const mode = opts.mode ?? config?.mode ?? "LITE";
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const auditLogger = new AuditLogger(storage.db);
   const workflowsRepo = new WorkflowsRepository(storage.db);
   const llm = resolveLlmClient(opts.llm, config?.llm);
@@ -9182,14 +10826,14 @@ async function runExplore(opts) {
     writeOut(`  Areas: ${exploreOutput.charter.areasToProbe.join("; ")}`);
     writeOut(`  Techniques: ${exploreOutput.charter.techniques.join(", ")}`);
     writeOut("");
-    const specsDir = path12.join(qaiosDir, "specs", workflowId);
+    const specsDir = path15.join(qaiosDir, "specs", workflowId);
     mkdirSync(specsDir, { recursive: true });
-    const charterPath = path12.join(specsDir, "Charter.json");
+    const charterPath = path15.join(specsDir, "Charter.json");
     writeFileSync(charterPath, JSON.stringify(exploreOutput.charter, null, 2) + "\n");
-    const notesPath = path12.join(specsDir, "SessionNotes.md");
+    const notesPath = path15.join(specsDir, "SessionNotes.md");
     writeFileSync(notesPath, renderSessionNotesMarkdown(exploreOutput));
-    writeOut(`Persisted ${path12.relative(cwd, charterPath)}`);
-    writeOut(`Persisted ${path12.relative(cwd, notesPath)}`);
+    writeOut(`Persisted ${path15.relative(cwd, charterPath)}`);
+    writeOut(`Persisted ${path15.relative(cwd, notesPath)}`);
     writeOut("");
     if (opts.charterOnly === true) {
       finalize2("succeeded");
@@ -9383,7 +11027,7 @@ async function fileFindingAsDefect(args) {
   };
 }
 function loadConfig3(cwd) {
-  const candidate = path12.join(cwd, ".qaios", "config.yaml");
+  const candidate = path15.join(cwd, ".qaios", "config.yaml");
   if (!existsSync(candidate)) return null;
   try {
     return parse(readFileSync(candidate, "utf-8"));
@@ -9418,8 +11062,8 @@ function pickTarget(testResultsRepo, opts) {
       reason: "must pass a test file path or --last-failure."
     };
   }
-  const abs = path12.isAbsolute(opts.target) ? opts.target : path12.resolve(opts.cwd, opts.target);
-  const rel = path12.relative(opts.cwd, abs).split(path12.sep).join("/");
+  const abs = path15.isAbsolute(opts.target) ? opts.target : path15.resolve(opts.cwd, opts.target);
+  const rel = path15.relative(opts.cwd, abs).split(path15.sep).join("/");
   if (opts.scenarioId !== void 0 && opts.scenarioId.length > 0) {
     const row2 = testResultsRepo.mostRecentFailedForFileScenario(rel, opts.scenarioId);
     return row2 !== null ? { row: row2, reason: null } : {
@@ -9437,8 +11081,8 @@ function renderTextLine2(line) {
   return line + "\n";
 }
 async function runFix(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -9449,7 +11093,7 @@ async function runFix(opts) {
     };
   }
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const auditLogger = new AuditLogger(storage.db);
   const testResultsRepo = new TestResultsRepository(storage.db);
   const workflowsRepo = new WorkflowsRepository(storage.db);
@@ -9492,9 +11136,9 @@ async function runFix(opts) {
     ];
     let resolvedTestFile = tr.testFile;
     for (const dir of candidateDirs) {
-      const candidate = path12.isAbsolute(tr.testFile) ? tr.testFile : path12.join(cwd, dir, tr.testFile);
+      const candidate = path15.isAbsolute(tr.testFile) ? tr.testFile : path15.join(cwd, dir, tr.testFile);
       if (existsSync(candidate)) {
-        resolvedTestFile = path12.isAbsolute(tr.testFile) ? tr.testFile : path12.join(dir, tr.testFile);
+        resolvedTestFile = path15.isAbsolute(tr.testFile) ? tr.testFile : path15.join(dir, tr.testFile);
         break;
       }
     }
@@ -9748,7 +11392,7 @@ async function runFix(opts) {
     } else {
       writeOut(`${GLYPH3.failed} test still failing after patch`);
       if (opts.keepFailedPatch !== true && apply.oldContents !== null) {
-        const absPath = path12.isAbsolute(resolvedTestFile) ? resolvedTestFile : path12.resolve(cwd, resolvedTestFile);
+        const absPath = path15.isAbsolute(resolvedTestFile) ? resolvedTestFile : path15.resolve(cwd, resolvedTestFile);
         try {
           writeFileSync(absPath, apply.oldContents, "utf-8");
           rolledBack = true;
@@ -9893,8 +11537,8 @@ function renderVerify(result, genesis, latest) {
   ].join("\n");
 }
 async function runHistory(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -9905,7 +11549,7 @@ async function runHistory(opts) {
     };
   }
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const auditLogger = new AuditLogger(storage.db);
   const workflowsRepo = new WorkflowsRepository(storage.db);
   const runsRepo = new RunsRepository(storage.db);
@@ -9939,13 +11583,13 @@ async function runHistory(opts) {
     }
     if (opts.exportPath !== void 0) {
       const entries = auditLogger.listEntries();
-      const absPath = path12.resolve(cwd, opts.exportPath);
-      mkdirSync(path12.dirname(absPath), { recursive: true });
+      const absPath = path15.resolve(cwd, opts.exportPath);
+      mkdirSync(path15.dirname(absPath), { recursive: true });
       const lines = entries.map((e) => JSON.stringify(e)).join("\n");
       writeFileSync(absPath, lines + (entries.length > 0 ? "\n" : ""));
       if (!opts.quiet) {
         process.stdout.write(
-          `Exported ${entries.length} audit entries to ${path12.relative(cwd, absPath)}
+          `Exported ${entries.length} audit entries to ${path15.relative(cwd, absPath)}
 `
         );
       }
@@ -10012,8 +11656,8 @@ async function runHistory(opts) {
     if (ownsStorage) storage.close();
   }
 }
-var __dirname$2 = path12.dirname(fileURLToPath(import.meta.url));
-var DEFAULT_TEMPLATES_DIR = path12.resolve(__dirname$2);
+var __dirname$2 = path15.dirname(fileURLToPath(import.meta.url));
+var DEFAULT_TEMPLATES_DIR = path15.resolve(__dirname$2);
 function renderTemplate(template, vars) {
   let out = template;
   for (const [key, value] of Object.entries(vars)) {
@@ -10029,7 +11673,7 @@ function renderTemplate(template, vars) {
   return out;
 }
 function renderQaiosMd(vars, templatesDir = DEFAULT_TEMPLATES_DIR) {
-  const templatePath = path12.join(templatesDir, "QAIOS.md.template");
+  const templatePath = path15.join(templatesDir, "QAIOS.md.template");
   const template = readFileSync(templatePath, "utf-8");
   return renderTemplate(template, vars);
 }
@@ -10044,11 +11688,12 @@ var QAIOS_GITIGNORE = `# QAIOS managed directory.
 cache/
 runs/
 diffs/
+xray/
 workflows.db-wal
 workflows.db-shm
 `;
 function runInit(opts = {}) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
   const detection = detectProject(cwd);
   if (!detection.looksLikeProject && !detection.isEmpty && !opts.force) {
     return {
@@ -10060,7 +11705,7 @@ function runInit(opts = {}) {
       detection
     };
   }
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (existsSync(qaiosDir) && !opts.force) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -10103,7 +11748,7 @@ function runInit(opts = {}) {
     }
   });
   mkdirSync(qaiosDir, { recursive: true });
-  const dbPath = path12.join(qaiosDir, "workflows.db");
+  const dbPath = path15.join(qaiosDir, "workflows.db");
   let migrations;
   try {
     const storage = Storage.open(dbPath, { skipMigrations: true });
@@ -10129,14 +11774,14 @@ Original error: ${raw}` : `Failed to initialise workflows.db: ${raw}`;
     };
   }
   const filesWritten = [];
-  filesWritten.push(path12.relative(cwd, dbPath));
-  const configPath = path12.join(qaiosDir, "config.yaml");
+  filesWritten.push(path15.relative(cwd, dbPath));
+  const configPath = path15.join(qaiosDir, "config.yaml");
   writeFileSync(configPath, stringify(config), "utf-8");
-  filesWritten.push(path12.relative(cwd, configPath));
-  const gitignorePath = path12.join(qaiosDir, ".gitignore");
+  filesWritten.push(path15.relative(cwd, configPath));
+  const gitignorePath = path15.join(qaiosDir, ".gitignore");
   writeFileSync(gitignorePath, QAIOS_GITIGNORE, "utf-8");
-  filesWritten.push(path12.relative(cwd, gitignorePath));
-  const qaiosMdPath = path12.join(cwd, "QAIOS.md");
+  filesWritten.push(path15.relative(cwd, gitignorePath));
+  const qaiosMdPath = path15.join(cwd, "QAIOS.md");
   const qaiosMd = renderQaiosMd({
     projectName: detection.projectName,
     stack: stackHint(detection),
@@ -10145,7 +11790,7 @@ Original error: ${raw}` : `Failed to initialise workflows.db: ${raw}`;
   });
   if (!existsSync(qaiosMdPath) || opts.force) {
     writeFileSync(qaiosMdPath, qaiosMd, "utf-8");
-    filesWritten.push(path12.relative(cwd, qaiosMdPath));
+    filesWritten.push(path15.relative(cwd, qaiosMdPath));
   }
   return {
     exitCode: ExitCode.SUCCESS,
@@ -10179,9 +11824,9 @@ function isWritable(dir) {
   }
 }
 async function runConfig(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
-  const qaiosDir = path12.join(cwd, ".qaios");
-  const configPath = path12.join(qaiosDir, "config.yaml");
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
+  const qaiosDir = path15.join(cwd, ".qaios");
+  const configPath = path15.join(qaiosDir, "config.yaml");
   if (!existsSync(qaiosDir)) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -10501,8 +12146,8 @@ function validateAndWrite(configPath, text, writeOut) {
   return { exitCode: ExitCode.SUCCESS };
 }
 async function runMcp(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -10513,7 +12158,7 @@ async function runMcp(opts) {
     };
   }
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const repo = new McpServersRepository(storage.db);
   const writeOut = (line) => {
     if (opts.quiet === true) return;
@@ -10726,7 +12371,7 @@ async function testServer(repo, opts, writeOut) {
   }
 }
 function loadLlmConfig(cwd) {
-  const candidate = path12.join(cwd, ".qaios", "config.yaml");
+  const candidate = path15.join(cwd, ".qaios", "config.yaml");
   if (!existsSync(candidate)) return void 0;
   try {
     const parsed = parse(readFileSync(candidate, "utf-8"));
@@ -10777,8 +12422,8 @@ async function applyDecision(args) {
   return { resumed: true };
 }
 async function runReview(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -10792,7 +12437,7 @@ async function runReview(opts) {
     };
   }
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const auditLogger = new AuditLogger(storage.db);
   const gatesRepo = new GatesRepository(storage.db);
   const llm = resolveLlmClient(opts.llm, loadLlmConfig(cwd));
@@ -10897,7 +12542,7 @@ async function runReview(opts) {
   }
 }
 function loadRunConfig(cwd) {
-  const candidate = path12.join(cwd, ".qaios", "config.yaml");
+  const candidate = path15.join(cwd, ".qaios", "config.yaml");
   if (!existsSync(candidate)) return null;
   try {
     return parse(readFileSync(candidate, "utf-8"));
@@ -11006,9 +12651,32 @@ function exitCodeForOutcome(workflowStatus, runStatus, reason) {
       return ExitCode.INTERNAL;
   }
 }
+function readPassWithDivergence(db, workflowId) {
+  let row;
+  try {
+    row = db.prepare(
+      `SELECT payload_json FROM audit_log
+         WHERE workflow_id = ? AND event = 'xray.diff'
+         ORDER BY timestamp DESC LIMIT 1`
+    ).get(workflowId);
+  } catch {
+    return null;
+  }
+  if (row?.payload_json === void 0) return null;
+  try {
+    const payload = JSON.parse(row.payload_json);
+    if (payload.passWithDivergence !== true) return null;
+    return { count: payload.count ?? 0, flagged: payload.flagged ?? [] };
+  } catch {
+    return null;
+  }
+}
+function indent(s) {
+  return s.split("\n").map((l) => `      ${l}`).join("\n");
+}
 async function runRun(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -11019,7 +12687,7 @@ async function runRun(opts) {
     };
   }
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const auditLogger = new AuditLogger(storage.db);
   const config = loadRunConfig(cwd);
   const llm = resolveLlmClient(opts.llm, config?.llm);
@@ -11044,6 +12712,19 @@ async function runRun(opts) {
     extraArgs.push(`--retries=${opts.retry}`);
   }
   if (extraArgs.length > 0) args["executionExtraArgs"] = extraArgs;
+  const xrayCfg = config?.xray;
+  const flagOn = opts.xray !== void 0 && opts.xray !== false;
+  const enabled = flagOn || opts.xrayStrict === true || xrayCfg?.enabled === true;
+  if (enabled) {
+    const cfgLevel = xrayCfg?.level && xrayCfg.level !== "off" ? xrayCfg.level : "summary";
+    const level = typeof opts.xray === "string" ? opts.xray : cfgLevel;
+    const xrayArg = { level };
+    if (typeof xrayCfg?.quiescenceMs === "number") xrayArg["quiescenceMs"] = xrayCfg.quiescenceMs;
+    if (Array.isArray(xrayCfg?.volatileParams)) xrayArg["volatileParams"] = xrayCfg.volatileParams;
+    if (Array.isArray(xrayCfg?.ignoreHosts)) xrayArg["ignoreHosts"] = xrayCfg.ignoreHosts;
+    if (Array.isArray(xrayCfg?.redact)) xrayArg["redact"] = xrayCfg.redact;
+    args["xray"] = xrayArg;
+  }
   const capturePageSnapshot2 = opts.noHeal === true ? void 0 : opts.capturePageSnapshot ?? ((o) => capturePageSnapshot({ url: o.url, cwd: o.cwd }));
   const orchestrator = new Orchestrator({
     storage,
@@ -11096,7 +12777,22 @@ async function runRun(opts) {
     }
     const exec = result.outputs["execute.playwright"];
     const runStatus = exec?.runStatus;
-    const exitCode = exitCodeForOutcome(result.status, runStatus, result.blockedReason);
+    let exitCode = exitCodeForOutcome(result.status, runStatus, result.blockedReason);
+    if (exitCode === ExitCode.SUCCESS) {
+      const divergence = readPassWithDivergence(storage.db, result.workflowId);
+      if (divergence !== null) {
+        if (opts.quiet !== true) {
+          process.stderr.write(
+            `\u26A0 xray: ${divergence.count} test(s) passed but the backend diverged from baseline:
+` + divergence.flagged.map((f) => `  \xB7 ${f.test}
+${indent(f.summary)}`).join("\n") + "\n"
+          );
+        }
+        if (opts.xrayStrict === true) {
+          exitCode = ExitCode.PASS_WITH_NETWORK_DIVERGENCE;
+        }
+      }
+    }
     return {
       exitCode,
       workflowId: result.workflowId,
@@ -11113,8 +12809,574 @@ async function runRun(opts) {
     if (ownsStorage) storage.close();
   }
 }
+path15.dirname(fileURLToPath(import.meta.url));
+function rowToNetRun2(row) {
+  return NetRunRow.parse({
+    runId: row.run_id,
+    workflowId: row.workflow_id,
+    testId: row.test_id,
+    browser: row.browser,
+    tier: row.tier,
+    captureLevel: row.capture_level,
+    startedAt: row.started_at,
+    isGreen: row.is_green === 1,
+    isBaseline: row.is_baseline === 1
+  });
+}
+var NetRunsRepository2 = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  create(input) {
+    const r = NetRunRow.parse(input);
+    this.db.prepare(
+      `INSERT INTO net_runs
+          (run_id, workflow_id, test_id, browser, tier, capture_level,
+           started_at, is_green, is_baseline)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      r.runId,
+      r.workflowId,
+      r.testId,
+      r.browser,
+      r.tier,
+      r.captureLevel,
+      r.startedAt,
+      r.isGreen ? 1 : 0,
+      r.isBaseline ? 1 : 0
+    );
+    return r;
+  }
+  findById(runId) {
+    const row = this.db.prepare("SELECT * FROM net_runs WHERE run_id = ?").get(runId);
+    return row ? rowToNetRun2(row) : null;
+  }
+  listByWorkflow(workflowId) {
+    const rows = this.db.prepare("SELECT * FROM net_runs WHERE workflow_id = ? ORDER BY started_at DESC").all(workflowId);
+    return rows.map(rowToNetRun2);
+  }
+  /**
+   * Runs for a test, newest first. Used by baseline selection (last green per
+   * test+browser) and volatility learning (compare consecutive green runs).
+   */
+  listByTest(testId, browser) {
+    const sql = browser === void 0 ? "SELECT * FROM net_runs WHERE test_id = ? ORDER BY started_at DESC" : "SELECT * FROM net_runs WHERE test_id = ? AND browser = ? ORDER BY started_at DESC";
+    const rows = browser === void 0 ? this.db.prepare(sql).all(testId) : this.db.prepare(sql).all(testId, browser);
+    return rows.map(rowToNetRun2);
+  }
+  /** Flip green/baseline flags as the run is finalized / a baseline is pinned. */
+  update(runId, patch) {
+    const fields = [];
+    const params = [];
+    if (patch.isGreen !== void 0) {
+      fields.push("is_green = ?");
+      params.push(patch.isGreen ? 1 : 0);
+    }
+    if (patch.isBaseline !== void 0) {
+      fields.push("is_baseline = ?");
+      params.push(patch.isBaseline ? 1 : 0);
+    }
+    if (fields.length === 0) return this.findById(runId);
+    params.push(runId);
+    this.db.prepare(`UPDATE net_runs SET ${fields.join(", ")} WHERE run_id = ?`).run(...params);
+    return this.findById(runId);
+  }
+  /** Clear the baseline pin for every run of a (test, browser). */
+  clearBaseline(testId, browser) {
+    this.db.prepare("UPDATE net_runs SET is_baseline = 0 WHERE test_id = ? AND browser = ?").run(testId, browser);
+  }
+  delete(runId) {
+    this.db.prepare("DELETE FROM net_runs WHERE run_id = ?").run(runId);
+  }
+};
+function rowToNetRequest2(row) {
+  return NetRequestRow.parse({
+    id: row.id,
+    runId: row.run_id,
+    stepId: row.step_id,
+    attribution: row.attribution,
+    targetType: row.target_type,
+    method: row.method,
+    urlRaw: row.url_raw,
+    urlTemplate: row.url_template,
+    gqlOperation: row.gql_operation,
+    identityKey: row.identity_key,
+    status: row.status,
+    errorText: row.error_text,
+    mime: row.mime,
+    reqHash: row.req_hash,
+    respHash: row.resp_hash,
+    shapeHash: row.shape_hash,
+    reqBodyRef: row.req_body_ref,
+    respBodyRef: row.resp_body_ref,
+    bodyStatus: row.body_status,
+    redirectsJson: row.redirects_json,
+    timingsJson: row.timings_json,
+    initiatorJson: row.initiator_json,
+    wallStart: row.wall_start
+  });
+}
+var NetRequestsRepository2 = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  create(input) {
+    const r = NetRequestRow.parse(input);
+    this.db.prepare(
+      `INSERT INTO net_requests
+          (id, run_id, step_id, attribution, target_type, method, url_raw,
+           url_template, gql_operation, identity_key, status, error_text, mime,
+           req_hash, resp_hash, shape_hash, req_body_ref, resp_body_ref,
+           body_status, redirects_json, timings_json, initiator_json, wall_start)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      r.id,
+      r.runId,
+      r.stepId,
+      r.attribution,
+      r.targetType,
+      r.method,
+      r.urlRaw,
+      r.urlTemplate,
+      r.gqlOperation,
+      r.identityKey,
+      r.status,
+      r.errorText,
+      r.mime,
+      r.reqHash,
+      r.respHash,
+      r.shapeHash,
+      r.reqBodyRef,
+      r.respBodyRef,
+      r.bodyStatus,
+      r.redirectsJson,
+      r.timingsJson,
+      r.initiatorJson,
+      r.wallStart
+    );
+    return r;
+  }
+  /** Bulk insert in one transaction — a run can produce hundreds of requests. */
+  createMany(rows) {
+    const insert = this.db.transaction((items) => {
+      for (const item of items) this.create(item);
+    });
+    insert(rows);
+  }
+  listByRun(runId) {
+    const rows = this.db.prepare("SELECT * FROM net_requests WHERE run_id = ? ORDER BY wall_start ASC").all(runId);
+    return rows.map(rowToNetRequest2);
+  }
+  listByRunStep(runId, stepId) {
+    const sql = stepId === null ? "SELECT * FROM net_requests WHERE run_id = ? AND step_id IS NULL ORDER BY wall_start ASC" : "SELECT * FROM net_requests WHERE run_id = ? AND step_id = ? ORDER BY wall_start ASC";
+    const rows = stepId === null ? this.db.prepare(sql).all(runId) : this.db.prepare(sql).all(runId, stepId);
+    return rows.map(rowToNetRequest2);
+  }
+  deleteByRun(runId) {
+    this.db.prepare("DELETE FROM net_requests WHERE run_id = ?").run(runId);
+  }
+};
+function buildRunGraph2(requests) {
+  const graph = /* @__PURE__ */ new Map();
+  for (const r of requests) {
+    const key = r.identityKey;
+    const existing = graph.get(key);
+    if (existing === void 0) {
+      graph.set(key, {
+        identityKey: r.identityKey,
+        stepId: r.stepId,
+        attribution: r.attribution,
+        method: r.method,
+        status: r.status,
+        errorText: r.errorText,
+        shapeHash: r.shapeHash,
+        respHash: r.respHash,
+        count: 1
+      });
+    } else {
+      existing.count += 1;
+      if (isErrorStatus3(r.status) && !isErrorStatus3(existing.status)) {
+        existing.status = r.status;
+        existing.errorText = r.errorText;
+      }
+    }
+  }
+  return graph;
+}
+function isErrorStatus3(status) {
+  return status === null || status >= 400 || status < 0;
+}
+var BaselineSelector2 = class {
+  netRuns;
+  netRequests;
+  constructor(db) {
+    this.netRuns = new NetRunsRepository2(db);
+    this.netRequests = new NetRequestsRepository2(db);
+  }
+  /**
+   * The baseline run for a (test, browser): the pinned baseline if one exists,
+   * else the most recent green run. Returns null if there's no green run yet.
+   * `excludeRunId` skips a candidate run (so a run never baselines against itself).
+   */
+  select(testId, browser, excludeRunId) {
+    const runs = this.netRuns.listByTest(testId, browser);
+    const pinned = runs.find((r) => r.isBaseline && r.runId !== excludeRunId);
+    if (pinned !== void 0) return pinned;
+    return runs.find((r) => r.isGreen && r.runId !== excludeRunId) ?? null;
+  }
+  /** Build the causal graph for a run by id (or null if the run is unknown). */
+  graphFor(runId) {
+    if (this.netRuns.findById(runId) === null) return null;
+    return buildRunGraph2(this.netRequests.listByRun(runId));
+  }
+  /** Pin a run as the baseline for its (test, browser), clearing any prior pin. */
+  pin(runId) {
+    const run = this.netRuns.findById(runId);
+    if (run === null) return null;
+    this.netRuns.clearBaseline(run.testId, run.browser);
+    return this.netRuns.update(runId, { isBaseline: true });
+  }
+  /** Clear the baseline pin for a (test, browser). */
+  clear(testId, browser) {
+    this.netRuns.clearBaseline(testId, browser);
+  }
+};
+var FAIL_SIGNAL_CLASSES2 = /* @__PURE__ */ new Set([
+  "ERROR_RESPONSE",
+  "STATUS_CHANGED"
+]);
+var SEVERITY2 = {
+  ERROR_RESPONSE: 6,
+  STATUS_CHANGED: 5,
+  MISSING_CALL: 4,
+  NEW_CALL: 3,
+  SCHEMA_CHANGED: 2,
+  VALUE_CHANGED: 1
+};
+function statusClass2(status) {
+  if (status === null || status <= 0) return "unknown";
+  if (status >= 500) return "5xx";
+  if (status >= 400) return "4xx";
+  if (status >= 300) return "3xx";
+  if (status >= 200) return "2xx";
+  return "other";
+}
+function isErrorStatus22(status) {
+  return status !== null && status >= 400;
+}
+function isUnknownStatus2(status, errorText) {
+  return errorText === null && (status === null || status <= 0);
+}
+function diffGraphs2(run, baseline, opts = {}) {
+  const presenceUnstable = new Set(
+    (opts.volatility ?? []).filter((v) => v.kind === "presence").map((v) => v.identityKey)
+  );
+  const valueVolatile = new Set(
+    (opts.volatility ?? []).filter((v) => v.kind === "value").map((v) => v.identityKey)
+  );
+  const backgroundFailSignal = opts.backgroundIsFailSignal === true;
+  const divergences = [];
+  const emit2 = (diffClass, e, detail) => {
+    const isFail = FAIL_SIGNAL_CLASSES2.has(diffClass) && (backgroundFailSignal || e.attribution !== "background");
+    divergences.push({
+      diffClass,
+      identityKey: e.identityKey,
+      stepId: e.stepId,
+      attribution: e.attribution,
+      detail,
+      failSignal: isFail
+    });
+  };
+  for (const [key, entry] of run) {
+    const base = baseline.get(key);
+    if (isUnknownStatus2(entry.status, entry.errorText)) continue;
+    if (isErrorStatus22(entry.status) || entry.errorText !== null) {
+      const ui = opts.uiPassed === true ? " (UI assertions passed)" : "";
+      emit2(
+        "ERROR_RESPONSE",
+        entry,
+        `${describe2(entry)} returned ${entry.errorText ?? entry.status ?? "error"}${ui}`
+      );
+      continue;
+    }
+    if (base !== void 0) {
+      const runClass = statusClass2(entry.status);
+      const baseClass = statusClass2(base.status);
+      if (runClass !== "unknown" && baseClass !== "unknown" && runClass !== baseClass) {
+        emit2(
+          "STATUS_CHANGED",
+          entry,
+          `${describe2(entry)} status ${base.status ?? "\u2014"} \u2192 ${entry.status ?? "\u2014"}`
+        );
+      } else if (entry.shapeHash !== null && base.shapeHash !== null && entry.shapeHash !== base.shapeHash) {
+        emit2("SCHEMA_CHANGED", entry, `${describe2(entry)} response shape changed`);
+      } else if (entry.respHash !== null && base.respHash !== null && entry.respHash !== base.respHash && !valueVolatile.has(key)) {
+        emit2("VALUE_CHANGED", entry, `${describe2(entry)} response value changed`);
+      }
+    } else if (!presenceUnstable.has(key)) {
+      emit2("NEW_CALL", entry, `${describe2(entry)} is new vs baseline`);
+    }
+  }
+  for (const [key, base] of baseline) {
+    if (!run.has(key) && !presenceUnstable.has(key)) {
+      emit2("MISSING_CALL", base, `${describe2(base)} was expected but did not occur`);
+    }
+  }
+  divergences.sort(
+    (a, b) => SEVERITY2[b.diffClass] - SEVERITY2[a.diffClass] || a.identityKey.localeCompare(b.identityKey)
+  );
+  return {
+    divergences,
+    hasFailSignal: divergences.some((d) => d.failSignal)
+  };
+}
+function describe2(e) {
+  const parts = e.identityKey.split("|");
+  return parts.length >= 3 ? `${parts[0]} ${parts[1]}${parts[2]}` : e.identityKey;
+}
+
+// src/commands/xray.ts
+function write(s) {
+  process.stdout.write(s.endsWith("\n") ? s : s + "\n");
+}
+function userError(code, message) {
+  return { exitCode: ExitCode.USER_ERROR, error: { code, message } };
+}
+function renderRun(run, requests) {
+  const lines = [];
+  const greenMark = run.isGreen ? "\u2713 green" : "\xB7 not-green";
+  const baseMark = run.isBaseline ? "  \u2605 baseline" : "";
+  lines.push("");
+  lines.push(`\u25B8 ${run.testId}`);
+  lines.push(
+    `  run ${run.runId}  \xB7  ${run.browser} (tier ${run.tier})  \xB7  ${run.captureLevel}  \xB7  ${greenMark}${baseMark}  \xB7  ${requests.length} requests`
+  );
+  const byStep = /* @__PURE__ */ new Map();
+  for (const r of requests) {
+    const key = r.stepId ?? "(background)";
+    const list = byStep.get(key) ?? [];
+    list.push(r);
+    byStep.set(key, list);
+  }
+  for (const [stepKey, reqs] of byStep) {
+    const stepLabel = stepKey === "(background)" ? "background / setup" : `step ${stepKey.slice(-6)}`;
+    lines.push(`    ${stepLabel}`);
+    for (const r of reqs) {
+      const status = r.status === null ? r.errorText ? `ERR ${r.errorText}` : "\u2014" : String(r.status);
+      const flag = statusFlag(r);
+      const gql = r.gqlOperation ? ` {gql:${r.gqlOperation}}` : "";
+      lines.push(
+        `      ${flag}${r.method.padEnd(5)} ${status.padEnd(14)} ${r.identityKey.split("|").slice(1).join(" ")}${gql}  [${r.attribution}]`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+function statusFlag(r) {
+  if (r.errorText) return "\u2717 ";
+  if (typeof r.status === "number" && r.status >= 400) return "\u2717 ";
+  return "  ";
+}
+async function runXray(opts) {
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
+  const qaiosDir = path15.join(cwd, ".qaios");
+  if (!existsSync(qaiosDir) && opts.storage === void 0) {
+    return userError(
+      "qaios.xray.not_initialized",
+      `${cwd} is not a QAIOS project \u2014 run \`qaios init\` first.`
+    );
+  }
+  const ownsStorage = opts.storage === void 0;
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  try {
+    switch (opts.verb) {
+      case "show":
+        return showVerb(storage, opts);
+      case "diff":
+        return diffVerb(storage, opts);
+      case "baseline":
+        return baselineVerb(storage, opts);
+      case "volatility":
+        return volatilityVerb(storage, opts);
+      default:
+        return userError("qaios.xray.unknown_verb", `Unknown xray verb: ${String(opts.verb)}`);
+    }
+  } finally {
+    if (ownsStorage) storage.close();
+  }
+}
+function showVerb(storage, opts) {
+  const netRuns = new NetRunsRepository(storage.db);
+  const netRequests = new NetRequestsRepository(storage.db);
+  let runs = [];
+  if (opts.target !== void 0) {
+    const single = netRuns.findById(opts.target);
+    runs = single ? [single] : netRuns.listByWorkflow(opts.target);
+  }
+  if (runs.length === 0) {
+    const hint = opts.target ? ` for "${opts.target}"` : "";
+    return userError(
+      "qaios.xray.no_capture",
+      `No xray capture found${hint}. Run \`qaios run --xray\` first, then \`qaios xray show <runId|workflowId>\`.`
+    );
+  }
+  if (opts.json === true) {
+    write(
+      JSON.stringify(
+        runs.map((run) => ({ run, requests: netRequests.listByRun(run.runId) })),
+        null,
+        2
+      )
+    );
+    return { exitCode: ExitCode.SUCCESS };
+  }
+  if (opts.quiet !== true) {
+    write(`xray capture \u2014 ${runs.length} run(s)`);
+    for (const run of runs) write(renderRun(run, netRequests.listByRun(run.runId)));
+    write("");
+  }
+  return { exitCode: ExitCode.SUCCESS };
+}
+function diffVerb(storage, opts) {
+  const netRuns = new NetRunsRepository(storage.db);
+  const netRequests = new NetRequestsRepository(storage.db);
+  const volatility = new NetVolatilityRepository(storage.db);
+  const baselines = new BaselineSelector2(storage.db);
+  if (opts.target === void 0) {
+    return userError(
+      "qaios.xray.diff_usage",
+      "Usage: qaios xray diff <runA> [runB]. Omit runB to diff against the baseline."
+    );
+  }
+  const runA = netRuns.findById(opts.target);
+  if (runA === null) {
+    return userError("qaios.xray.run_not_found", `No captured run with id "${opts.target}".`);
+  }
+  let runB;
+  if (opts.target2 !== void 0) {
+    runB = netRuns.findById(opts.target2);
+    if (runB === null) {
+      return userError("qaios.xray.run_not_found", `No captured run with id "${opts.target2}".`);
+    }
+  } else {
+    runB = baselines.select(runA.testId, runA.browser, runA.runId);
+    if (runB === null) {
+      return userError(
+        "qaios.xray.no_baseline",
+        `No baseline (green run) for "${runA.testId}" yet \u2014 pass an explicit second run, or capture a green run first.`
+      );
+    }
+  }
+  const runGraph = buildRunGraph2(netRequests.listByRun(runA.runId));
+  const baseGraph = buildRunGraph2(netRequests.listByRun(runB.runId));
+  const result = diffGraphs2(runGraph, baseGraph, {
+    volatility: volatility.listByTest(runA.testId),
+    uiPassed: runA.isGreen
+  });
+  if (opts.json === true) {
+    write(JSON.stringify({ runA: runA.runId, runB: runB.runId, ...result }, null, 2));
+    return { exitCode: ExitCode.SUCCESS };
+  }
+  if (opts.quiet !== true) {
+    write(`xray diff \u2014 ${runA.runId} vs ${runB.runId} (${runA.testId})`);
+    if (result.divergences.length === 0) {
+      write("  \u2713 no divergences \u2014 backend contract matches the baseline.");
+    } else {
+      for (const d of result.divergences) {
+        const glyph = d.failSignal ? "\u2717" : "\u26A0";
+        write(`  ${glyph} [${d.diffClass}] ${d.detail}  {${d.attribution}}`);
+      }
+    }
+    write("");
+  }
+  return { exitCode: ExitCode.SUCCESS };
+}
+function baselineVerb(storage, opts) {
+  const baselines = new BaselineSelector2(storage.db);
+  const netRuns = new NetRunsRepository(storage.db);
+  const sub = opts.sub ?? "set";
+  if (sub === "set") {
+    if (opts.target === void 0) {
+      return userError("qaios.xray.baseline_usage", "Usage: qaios xray baseline set <runId>.");
+    }
+    const pinned = baselines.pin(opts.target);
+    if (pinned === null) {
+      return userError("qaios.xray.run_not_found", `No captured run with id "${opts.target}".`);
+    }
+    if (opts.quiet !== true) {
+      write(`\u2713 baseline pinned: ${pinned.testId} (${pinned.browser}) \u2192 run ${pinned.runId}`);
+    }
+    return { exitCode: ExitCode.SUCCESS };
+  }
+  if (sub === "clear") {
+    if (opts.target === void 0) {
+      return userError(
+        "qaios.xray.baseline_usage",
+        "Usage: qaios xray baseline clear <runId|testId>."
+      );
+    }
+    const run = netRuns.findById(opts.target);
+    if (run === null) {
+      return userError(
+        "qaios.xray.run_not_found",
+        `Pass a run id to clear its (test, browser) baseline.`
+      );
+    }
+    baselines.clear(run.testId, run.browser);
+    if (opts.quiet !== true) write(`\u2713 baseline cleared for ${run.testId} (${run.browser}).`);
+    return { exitCode: ExitCode.SUCCESS };
+  }
+  return userError("qaios.xray.baseline_usage", `Unknown baseline action "${sub}" (set|clear).`);
+}
+function volatilityVerb(storage, opts) {
+  const volatility = new NetVolatilityRepository(storage.db);
+  const sub = opts.sub ?? "show";
+  if (sub === "reset") {
+    const n = volatility.reset(opts.target);
+    if (opts.quiet !== true) {
+      write(
+        `\u2713 cleared ${n} learned volatility entr${n === 1 ? "y" : "ies"}${opts.target ? ` for ${opts.target}` : ""}.`
+      );
+    }
+    return { exitCode: ExitCode.SUCCESS };
+  }
+  if (sub === "show") {
+    if (opts.target === void 0) {
+      return userError(
+        "qaios.xray.volatility_usage",
+        "Usage: qaios xray volatility show <testId> | reset [testId]."
+      );
+    }
+    const rows = volatility.listByTest(opts.target);
+    if (opts.json === true) {
+      write(JSON.stringify(rows, null, 2));
+      return { exitCode: ExitCode.SUCCESS };
+    }
+    if (opts.quiet !== true) {
+      if (rows.length === 0) {
+        const greenRuns = new NetRunsRepository(storage.db).listByTest(opts.target).filter((r) => r.isGreen).length;
+        write(
+          greenRuns >= 2 ? `No volatility learned for "${opts.target}" \u2014 its ${greenRuns} green runs were identical (a stable contract, nothing to relax).` : `No learned volatility for "${opts.target}" yet \u2014 needs \u22652 green runs (have ${greenRuns}).`
+        );
+      } else {
+        write(`xray volatility \u2014 ${opts.target} (${rows.length} learned)`);
+        for (const r of rows) {
+          write(`  \xB7 [${r.kind}] ${r.identityKey.split("|").slice(0, 3).join(" ")}`);
+        }
+      }
+      write("");
+    }
+    return { exitCode: ExitCode.SUCCESS };
+  }
+  return userError(
+    "qaios.xray.volatility_usage",
+    `Unknown volatility action "${sub}" (show|reset).`
+  );
+}
 function loadConfig4(cwd) {
-  const candidate = path12.join(cwd, ".qaios", "config.yaml");
+  const candidate = path15.join(cwd, ".qaios", "config.yaml");
   if (!existsSync(candidate)) return null;
   try {
     return parse(readFileSync(candidate, "utf-8"));
@@ -11160,8 +13422,8 @@ function loadSnapshotSpec(specPath) {
   };
 }
 async function runSnapshotCapture(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -11180,7 +13442,7 @@ async function runSnapshotCapture(opts) {
       }
     };
   }
-  const specAbs = path12.isAbsolute(opts.spec) ? opts.spec : path12.resolve(cwd, opts.spec);
+  const specAbs = path15.isAbsolute(opts.spec) ? opts.spec : path15.resolve(cwd, opts.spec);
   if (!existsSync(specAbs)) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -11241,7 +13503,7 @@ async function runSnapshotCapture(opts) {
     };
   }
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const auditLogger = new AuditLogger(storage.db);
   const baselineRepo = new VisualBaselinesRepository(storage.db);
   if (opts.update !== true) {
@@ -11329,8 +13591,8 @@ function exitCodeForCheck(summary) {
   return ExitCode.SUCCESS;
 }
 async function runSnapshotCheck(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -11352,7 +13614,7 @@ async function runSnapshotCheck(opts) {
     };
   }
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const auditLogger = new AuditLogger(storage.db);
   const baselineRepo = new VisualBaselinesRepository(storage.db);
   const llm = resolveLlmClient(opts.llm, config?.llm);
@@ -11500,15 +13762,15 @@ function autoDecide(item, threshold) {
 function applyReviewDecision(args) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
   if (args.action === "approve") {
-    const currentAbs = path12.isAbsolute(args.diff.currentImagePath) ? args.diff.currentImagePath : path12.join(args.cwd, args.diff.currentImagePath);
+    const currentAbs = path15.isAbsolute(args.diff.currentImagePath) ? args.diff.currentImagePath : path15.join(args.cwd, args.diff.currentImagePath);
     if (!existsSync(currentAbs)) {
       return {
         applied: false,
         reason: `current image not found at ${currentAbs} \u2014 cannot copy to baseline.`
       };
     }
-    const baselineAbs = path12.isAbsolute(args.baseline.imagePath) ? args.baseline.imagePath : path12.join(args.cwd, args.baseline.imagePath);
-    mkdirSync(path12.dirname(baselineAbs), { recursive: true });
+    const baselineAbs = path15.isAbsolute(args.baseline.imagePath) ? args.baseline.imagePath : path15.join(args.cwd, args.baseline.imagePath);
+    mkdirSync(path15.dirname(baselineAbs), { recursive: true });
     copyFileSync(currentAbs, baselineAbs);
     args.storage.db.transaction(() => {
       args.baselineRepo.updateImage(args.baseline.id, {
@@ -11558,8 +13820,8 @@ function applyReviewDecision(args) {
   return { applied: true };
 }
 async function runSnapshotReview(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -11572,7 +13834,7 @@ async function runSnapshotReview(opts) {
     };
   }
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const auditLogger = new AuditLogger(storage.db);
   const baselineRepo = new VisualBaselinesRepository(storage.db);
   const diffRepo = new VisualDiffsRepository(storage.db);
@@ -11689,7 +13951,7 @@ async function runSnapshotReview(opts) {
   }
 }
 function loadConfig5(cwd) {
-  const candidate = path12.join(cwd, ".qaios", "config.yaml");
+  const candidate = path15.join(cwd, ".qaios", "config.yaml");
   if (!existsSync(candidate)) return null;
   try {
     return parse(readFileSync(candidate, "utf-8"));
@@ -11702,14 +13964,14 @@ function loadConfig5(cwd) {
   }
 }
 function detectInstallCommand(cwd) {
-  if (existsSync(path12.join(cwd, "pnpm-lock.yaml"))) return "pnpm add -D";
-  if (existsSync(path12.join(cwd, "bun.lockb"))) return "bun add -d";
-  if (existsSync(path12.join(cwd, "yarn.lock"))) return "yarn add -D";
+  if (existsSync(path15.join(cwd, "pnpm-lock.yaml"))) return "pnpm add -D";
+  if (existsSync(path15.join(cwd, "bun.lockb"))) return "bun add -d";
+  if (existsSync(path15.join(cwd, "yarn.lock"))) return "yarn add -D";
   return "npm install --save-dev";
 }
 function filterUninstalledDeps(cwd, imports) {
   if (imports.length === 0) return [];
-  const pkgPath = path12.join(cwd, "package.json");
+  const pkgPath = path15.join(cwd, "package.json");
   if (!existsSync(pkgPath)) return [];
   let installed;
   try {
@@ -11819,7 +14081,7 @@ function exitCodeForStatus(status, reason, runSummary) {
   }
 }
 async function runTest(opts) {
-  const cwd = path12.resolve(opts.cwd ?? process.cwd());
+  const cwd = path15.resolve(opts.cwd ?? process.cwd());
   if (!opts.description || opts.description.trim().length === 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -11829,7 +14091,7 @@ async function runTest(opts) {
       }
     };
   }
-  const qaiosDir = path12.join(cwd, ".qaios");
+  const qaiosDir = path15.join(cwd, ".qaios");
   if (!existsSync(qaiosDir) && opts.storage === void 0) {
     return {
       exitCode: ExitCode.USER_ERROR,
@@ -11851,11 +14113,11 @@ async function runTest(opts) {
     const candidates = [];
     if (opts.apiSpec !== void 0 && opts.apiSpec.trim().length > 0) {
       candidates.push(
-        path12.isAbsolute(opts.apiSpec) ? opts.apiSpec : path12.resolve(cwd, opts.apiSpec)
+        path15.isAbsolute(opts.apiSpec) ? opts.apiSpec : path15.resolve(cwd, opts.apiSpec)
       );
     }
     if (/\.(ya?ml|json)$/i.test(opts.description.trim())) {
-      const guess = path12.isAbsolute(opts.description) ? opts.description.trim() : path12.resolve(cwd, opts.description.trim());
+      const guess = path15.isAbsolute(opts.description) ? opts.description.trim() : path15.resolve(cwd, opts.description.trim());
       candidates.push(guess);
     }
     const found = candidates.find((c) => existsSync(c)) ?? null;
@@ -11879,7 +14141,7 @@ async function runTest(opts) {
       };
     }
     const isPathDescription = candidates.includes(
-      path12.isAbsolute(opts.description) ? opts.description : path12.resolve(cwd, opts.description)
+      path15.isAbsolute(opts.description) ? opts.description : path15.resolve(cwd, opts.description)
     );
     if (isPathDescription || opts.description.trim().length < 3) {
       const epSummary = parsedSpec.endpoints.slice(0, 8).map((e) => `${e.method} ${e.path}${e.summary ? ` \u2014 ${e.summary}` : ""}`).join("\n");
@@ -11929,7 +14191,7 @@ ${epSummary}`;
   if (opts.featureName !== void 0) args["featureName"] = opts.featureName;
   const mode = opts.mode ?? config?.mode ?? "LITE";
   const ownsStorage = opts.storage === void 0;
-  const storage = opts.storage ?? Storage.open(path12.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const storage = opts.storage ?? Storage.open(path15.join(qaiosDir, "workflows.db"), { skipMigrations: false });
   const auditLogger = new AuditLogger(storage.db);
   const llm = resolveLlmClient(opts.llm, config?.llm);
   const gateConfig = {};
@@ -11997,27 +14259,27 @@ ${epSummary}`;
     }
     const filesWritten = [];
     if (result.status === "succeeded") {
-      const specsDir = path12.join(qaiosDir, "specs", result.workflowId);
+      const specsDir = path15.join(qaiosDir, "specs", result.workflowId);
       mkdirSync(specsDir, { recursive: true });
       const designKey = Object.keys(result.outputs).find((k) => k.startsWith("design."));
       if (designKey !== void 0) {
         const design2 = result.outputs[designKey];
         if (design2 !== void 0 && design2["designSpec"] !== void 0) {
-          const designSpecPath = path12.join(specsDir, "DesignSpec.json");
+          const designSpecPath = path15.join(specsDir, "DesignSpec.json");
           writeFileSync(designSpecPath, JSON.stringify(design2["designSpec"], null, 2) + "\n");
-          filesWritten.push(path12.relative(cwd, designSpecPath));
+          filesWritten.push(path15.relative(cwd, designSpecPath));
         }
       }
       let importsRequired = [];
       let qaiosMdSuggestions = [];
       const writeKey2 = Object.keys(result.outputs).find((k) => k.startsWith("write."));
       if (writeKey2 !== void 0) {
-        const write = result.outputs[writeKey2];
+        const write2 = result.outputs[writeKey2];
         const generatedAtIso = (/* @__PURE__ */ new Date()).toISOString();
         const disallowedImportsByFile = /* @__PURE__ */ new Map();
-        for (const file of write.files ?? []) {
-          const absPath = path12.join(cwd, file.path);
-          mkdirSync(path12.dirname(absPath), { recursive: true });
+        for (const file of write2.files ?? []) {
+          const absPath = path15.join(cwd, file.path);
+          mkdirSync(path15.dirname(absPath), { recursive: true });
           const injected = injectGeneratedFileHeader(
             file.contents,
             result.workflowId,
@@ -12045,8 +14307,8 @@ ${epSummary}`;
 `
           );
         }
-        if (Array.isArray(write.importsRequired)) importsRequired = write.importsRequired;
-        if (Array.isArray(write.qaiosMdSuggestions)) qaiosMdSuggestions = write.qaiosMdSuggestions;
+        if (Array.isArray(write2.importsRequired)) importsRequired = write2.importsRequired;
+        if (Array.isArray(write2.qaiosMdSuggestions)) qaiosMdSuggestions = write2.qaiosMdSuggestions;
       }
       if (!opts.quiet && opts.json !== true) {
         process.stdout.write(`
@@ -12119,9 +14381,9 @@ Ran generated tests: ${runSummary.passedCount} passed, ${runSummary.failedCount}
 }
 
 // src/index.ts
-var __dirname2 = path12.dirname(fileURLToPath(import.meta.url));
+var __dirname2 = path15.dirname(fileURLToPath(import.meta.url));
 function readPackageVersion() {
-  for (const candidate of [path12.resolve(__dirname2, "..", "package.json")]) {
+  for (const candidate of [path15.resolve(__dirname2, "..", "package.json")]) {
     try {
       const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
       if (pkg.version) return pkg.version;
@@ -12152,7 +14414,7 @@ function buildProgram() {
     }
     const detected = result.detection;
     const lines = [];
-    lines.push(`\u2713 Created ${path12.relative(process.cwd(), result.qaiosDir)}/`);
+    lines.push(`\u2713 Created ${path15.relative(process.cwd(), result.qaiosDir)}/`);
     if (detected.hasPlaywright) {
       lines.push(`\u2713 Detected: Playwright ${detected.playwrightVersion}`);
     } else {
@@ -12197,7 +14459,9 @@ function buildProgram() {
     }
     process.exit(result.exitCode);
   });
-  program.command("test <description>").description("Generate (and optionally run) tests for a feature").option("--type <type>", "testing type: web | api", "web").option("--api-spec <path>", "path to an OpenAPI spec (required when --type=api)").option("--base-url <url>", "override app.baseUrl from .qaios/config.yaml for this run").option(
+  program.command("test <description>").description(
+    "GENERATE test files from a feature description (design \u2192 write); --run also executes them"
+  ).option("--type <type>", "testing type: web | api", "web").option("--api-spec <path>", "path to an OpenAPI spec (required when --type=api)").option("--base-url <url>", "override app.baseUrl from .qaios/config.yaml for this run").option(
     "--scope <scope>",
     "design scope: minimal (~3 scenarios) | standard (default) | exhaustive (~15-25 scenarios)",
     "standard"
@@ -12234,7 +14498,12 @@ function buildProgram() {
     }
     process.exit(result.exitCode);
   });
-  program.command("run [pattern]").description("Execute Playwright tests, classify failures, persist results").option("--no-classify", "skip LLM classification of failures").option("--no-heal", "skip auto-healing on locator failures").option("--no-heal-verify", "skip the re-run that confirms an applied heal").option("--no-defect", "skip defect creation for real failures").option("--retry <n>", "retry failed tests N times before classifying", (v) => parseInt(v, 10)).option("--workers <n>", "Playwright workers count", (v) => parseInt(v, 10)).option("--headed", "run browser headed").option("--workflow <id>", "attach to an existing workflow id").action(async (pattern, cmdOpts, command) => {
+  program.command("run [pattern]").description(
+    "EXECUTE existing Playwright tests, classify failures, auto-heal the first broken locator inline, file defects"
+  ).option("--no-classify", "skip LLM classification of failures").option("--no-heal", "skip auto-healing on locator failures").option("--no-heal-verify", "skip the re-run that confirms an applied heal").option("--no-defect", "skip defect creation for real failures").option("--retry <n>", "retry failed tests N times before classifying", (v) => parseInt(v, 10)).option("--workers <n>", "Playwright workers count", (v) => parseInt(v, 10)).option("--headed", "run browser headed").option("--xray [level]", "capture network traffic (headers|summary|full; default summary)").option(
+    "--xray-strict",
+    "fail (exit 6) when UI-green tests have a backend divergence (implies --xray)"
+  ).option("--workflow <id>", "attach to an existing workflow id").action(async (pattern, cmdOpts, command) => {
     const globalOpts = command.parent?.opts() ?? {};
     const opts = {
       // Commander turns --no-X flags into `X: false` (default true);
@@ -12252,6 +14521,18 @@ function buildProgram() {
     if (typeof cmdOpts["retry"] === "number") opts.retry = cmdOpts["retry"];
     if (typeof cmdOpts["workers"] === "number") opts.workers = cmdOpts["workers"];
     if (typeof cmdOpts["workflow"] === "string") opts.workflowId = cmdOpts["workflow"];
+    const xrayVal = cmdOpts["xray"];
+    if (xrayVal === true) opts.xray = true;
+    else if (xrayVal === "headers" || xrayVal === "summary" || xrayVal === "full") {
+      opts.xray = xrayVal;
+    } else if (typeof xrayVal === "string") {
+      process.stderr.write(
+        `\u2717 qaios.run.bad_xray_level: --xray must be headers|summary|full (got "${xrayVal}")
+`
+      );
+      process.exit(1);
+    }
+    if (cmdOpts["xrayStrict"] === true) opts.xrayStrict = true;
     if (globalOpts["mode"] === "LITE" || globalOpts["mode"] === "FULL" || globalOpts["mode"] === "TRUST") {
       opts.mode = globalOpts["mode"];
     }
@@ -12262,7 +14543,9 @@ function buildProgram() {
     }
     process.exit(result.exitCode);
   });
-  program.command("fix [target]").description("Self-heal a broken test (or a directory of tests)").option("--auto", "auto-apply fixes regardless of mode (TRUST behavior)").option("--dry-run", "propose fix, show patch, don't apply").option("--last-failure", "fix the test from the most recent failed run").option("--scenario <id>", "fix a specific scenario by ID").option(
+  program.command("fix [target]").description(
+    "Repair ONE specific broken test you select (targeted heal + re-verify) \u2014 vs `run` which auto-heals inline"
+  ).option("--auto", "auto-apply fixes regardless of mode (TRUST behavior)").option("--dry-run", "propose fix, show patch, don't apply").option("--last-failure", "fix the test from the most recent failed run").option("--scenario <id>", "fix a specific scenario by ID").option(
     "--keep-failed-patch",
     "keep the patch on disk even if the re-run still fails (default: roll back)"
   ).action(async (target, cmdOpts, command) => {
@@ -12305,7 +14588,9 @@ function buildProgram() {
     }
     process.exit(result.exitCode);
   });
-  snapshot.command("review").description("Interactively review pending visual diffs (Ink TUI)").option("--workflow <id>", "restrict to one workflow id").option(
+  snapshot.command("review").description(
+    "Approve/reject pending VISUAL DIFFs (screenshot regressions) \u2014 not workflow gates (see top-level `review`)"
+  ).option("--workflow <id>", "restrict to one workflow id").option(
     "--auto-apply",
     "non-interactive: apply high-confidence classifier suggestions; leave uncertain diffs pending"
   ).option(
@@ -12497,7 +14782,9 @@ function buildProgram() {
       process.exit(result.exitCode);
     });
   }
-  configGroup.command("get [key]").description("Print value (or full config when no key is given)").action((key, cmdOpts, command) => {
+  configGroup.command("get [key]").description(
+    "Print the RAW on-disk value (no defaults; one key or whole file) \u2014 vs `show` which applies defaults"
+  ).action((key, cmdOpts, command) => {
     void runConfigVerb("get", cmdOpts, command, key !== void 0 ? { key } : {});
   });
   configGroup.command("set <key> <value>").description("Set a value (validates against schema before writing)").action((key, value, cmdOpts, command) => {
@@ -12509,7 +14796,9 @@ function buildProgram() {
   configGroup.command("show").description("Print resolved config (defaults applied)").action((cmdOpts, command) => {
     void runConfigVerb("show", cmdOpts, command, {});
   });
-  program.command("review").description("Walk pending gates and approve/reject (interactive Ink TUI; W9-T2)").option("--workflow <id>", "restrict to one workflow id").option("--auto-approve", "approve all pending gates without prompting (CI-friendly)").action(async (cmdOpts, command) => {
+  program.command("review").description(
+    "Approve/reject pending workflow GATES (design/writing review pauses), then resume the workflow \u2014 not visual diffs (see `snapshot review`)"
+  ).option("--workflow <id>", "restrict to one workflow id").option("--auto-approve", "approve all pending gates without prompting (CI-friendly)").action(async (cmdOpts, command) => {
     const globalOpts = command.parent?.opts() ?? {};
     const workflowFlag = typeof cmdOpts["workflow"] === "string" ? cmdOpts["workflow"] : typeof globalOpts["workflow"] === "string" ? globalOpts["workflow"] : void 0;
     const opts = {
@@ -12526,7 +14815,9 @@ function buildProgram() {
     }
     process.exit(result.exitCode);
   });
-  program.command("history").description("Show workflow history and audit data").option("--workflow <id>", "show single workflow detail").option("--last", "shortcut for --workflow <most-recent-id>").option("--limit <n>", "limit row count (default 20)", (v) => parseInt(v, 10)).option("--since <duration>", "relative time (e.g. 2h, 1d, 30m)").option(
+  program.command("history").description(
+    "View PAST workflows + audit log (read-only; list / detail / --verify chain / --export)"
+  ).option("--workflow <id>", "show single workflow detail").option("--last", "shortcut for --workflow <most-recent-id>").option("--limit <n>", "limit row count (default 20)", (v) => parseInt(v, 10)).option("--since <duration>", "relative time (e.g. 2h, 1d, 30m)").option(
     "--status <status>",
     "filter by workflow status: succeeded | failed | blocked | cancelled | running"
   ).option("--verify", "verify audit log hash chain integrity").option("--export <path>", "export full audit log as JSONL").option("--suggestions", "show pending QAIOS.md suggestions").action(async (cmdOpts, command) => {
@@ -12553,6 +14844,53 @@ function buildProgram() {
     }
     process.exit(result.exitCode);
   });
+  const xrayGroup = program.command("xray").description(
+    "Inspect network captured by `run --xray` (read-only: show / diff / baseline / volatility)"
+  );
+  function dispatchXray(verb, command, extras = {}) {
+    const globalOpts = command.parent?.parent?.opts?.() ?? command.parent?.opts?.() ?? {};
+    const opts = {
+      verb,
+      json: Boolean(globalOpts["json"]),
+      quiet: Boolean(globalOpts["quiet"])
+    };
+    if (extras.target !== void 0) opts.target = extras.target;
+    if (extras.target2 !== void 0) opts.target2 = extras.target2;
+    if (extras.sub !== void 0) opts.sub = extras.sub;
+    return runXray(opts).then((result) => {
+      if (result.error) {
+        process.stderr.write(`\u2717 ${result.error.code}: ${result.error.message}
+`);
+      }
+      process.exit(result.exitCode);
+    });
+  }
+  xrayGroup.command("show [target]").description("Show the per-step causal graph of a run or workflow").action((target, _cmdOpts, command) => {
+    void dispatchXray("show", command, target !== void 0 ? { target } : {});
+  });
+  xrayGroup.command("diff <runA> [runB]").description("Diff a run against another run, or against its baseline").action((runA, runB, _cmdOpts, command) => {
+    void dispatchXray("diff", command, {
+      target: runA,
+      ...runB !== void 0 ? { target2: runB } : {}
+    });
+  });
+  const baselineGroup = xrayGroup.command("baseline").description("Pin or clear a capture baseline");
+  baselineGroup.command("set <runId>").description("Pin a run as the baseline for its (test, browser)").action((runId, _cmdOpts, command) => {
+    void dispatchXray("baseline", command, { sub: "set", target: runId });
+  });
+  baselineGroup.command("clear <runId>").description("Clear a (test, browser)'s pinned baseline").action((runId, _cmdOpts, command) => {
+    void dispatchXray("baseline", command, { sub: "clear", target: runId });
+  });
+  const volatilityGroup = xrayGroup.command("volatility").description("Show or reset learned field volatility");
+  volatilityGroup.command("show <testId>").description("Show the learned volatility contract for a test").action((testId, _cmdOpts, command) => {
+    void dispatchXray("volatility", command, { sub: "show", target: testId });
+  });
+  volatilityGroup.command("reset [testId]").description("Reset learned volatility (all tests, or one)").action((testId, _cmdOpts, command) => {
+    void dispatchXray("volatility", command, {
+      sub: "reset",
+      ...testId !== void 0 ? { target: testId } : {}
+    });
+  });
   return program;
 }
 function formatDoctor(checks) {
@@ -12583,11 +14921,11 @@ var invokedAsScript = (() => {
     try {
       return realpathSync(p);
     } catch {
-      return path12.resolve(p);
+      return path15.resolve(p);
     }
   };
   if (realOf(argv1) === realOf(thisFile)) return true;
-  const invokedName = path12.basename(argv1).replace(/\.(js|mjs|cjs)$/, "");
+  const invokedName = path15.basename(argv1).replace(/\.(js|mjs|cjs)$/, "");
   return invokedName === "qaios";
 })();
 if (invokedAsScript) {