#!/usr/bin/env node
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import net from "node:net";
import { spawn, spawnSync } from "node:child_process";
import { randomUUID } from "node:crypto";
import { fileURLToPath } from "node:url";
import { findLocalChromeBinary } from "./chrome-binary.mjs";
import { flushAndExit } from "./flush-exit.mjs";
import { parseShellOnlyFailureDetail } from "./shared/workflow-lane-verdicts.mjs";

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const CLI = path.join(ROOT, "dist", "cli", "index.js");
const PACKAGE_JSON = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));

/**
 * @typedef {"pass" | "fail" | "env_limited" | "expected_timeout"} StepStatus
 */

/**
 * @typedef {{
 *   id: string;
 *   status: StepStatus;
 *   detail?: string;
 *   data?: Record<string, unknown>;
 * }} StepResult
 */

/**
 * @typedef {{
 *   status: number;
 *   stdout: string;
 *   stderr: string;
 *   json: Record<string, unknown> | null;
 *   durationMs: number;
 *   error?: string;
 * }} CliResult
 */

const MAX_BUFFER = 64 * 1024 * 1024;
const HEADLESS_PROCESS_MATCH = "--headless";
const RATE_LIMIT_COOLDOWN_MS = 65_000;
const DEFAULT_CLI_TIMEOUT_MS = 120_000;
const configuredCliTimeoutMs = Number.parseInt(process.env.LIVE_MATRIX_CLI_TIMEOUT_MS ?? "", 10);
const CLI_TIMEOUT_MS = Number.isInteger(configuredCliTimeoutMs) && configuredCliTimeoutMs >= 15_000
  ? configuredCliTimeoutMs
  : DEFAULT_CLI_TIMEOUT_MS;
const EXTENSION_WAIT_TIMEOUT_MS = Math.max(
  30_000,
  Number.parseInt(process.env.LIVE_MATRIX_EXTENSION_WAIT_TIMEOUT_MS ?? "60_000", 10) || 60_000
);
const RELEASE_VERSION = String(PACKAGE_JSON.version ?? "");
const RELEASE_ARTIFACT_DIR = path.join(ROOT, "artifacts", "release", `v${RELEASE_VERSION || "unknown"}`);
const ownedHeadlessMarkers = new Set();
const ownedHeadlessProfileDirs = new Set();
let headlessCleanupHooksInstalled = false;
let headlessCleanupCompleted = false;

export function parseCliOptions(argv) {
  const options = {
    releaseGate: false
  };

  for (const arg of argv) {
    if (arg === "--release-gate") {
      options.releaseGate = true;
      continue;
    }
    if (arg === "--help") {
      console.log([
        "Usage: node scripts/live-regression-matrix.mjs [options]",
        "",
        "Options:",
        "  --release-gate   Strict release mode; fails on env_limited and expected_timeout.",
        "  --help           Show help."
      ].join("\\n"));
      process.exit(0);
    }
    throw new Error(`Unknown option: ${arg}`);
  }

  return options;
}

/**
 * Daemon shutdown policy after matrix execution.
 * - Default: stop daemon for isolated runs, keep for global runs.
 * - Override with LIVE_MATRIX_STOP_DAEMON=0|1.
 */
export function shouldStopDaemonAfterRun({ useGlobalEnv, stopDaemonEnv = process.env.LIVE_MATRIX_STOP_DAEMON } = {}) {
  if (stopDaemonEnv === "1") {
    return true;
  }
  if (stopDaemonEnv === "0") {
    return false;
  }
  return useGlobalEnv !== true;
}

export function shouldUseGlobalEnv(useGlobalEnvEnv = process.env.LIVE_MATRIX_USE_GLOBAL) {
  return useGlobalEnvEnv !== "0";
}

export function hasDirtyRelayClients(relay) {
  if (!relay) {
    return false;
  }
  if (
    relay.canvasConnected === true
    || relay?.annotationConnected === true
    || relay?.cdpConnected === true
  ) {
    return true;
  }
  const extensionReady = relay.extensionConnected === true && relay.extensionHandshakeComplete === true;
  return relay.opsConnected === true && !extensionReady;
}

export function buildExtensionOpsLaunchArgs() {
  return [
    "launch",
    "--extension-only",
    "--wait-for-extension",
    "--wait-timeout-ms",
    String(EXTENSION_WAIT_TIMEOUT_MS),
    "--start-url",
    "https://example.com/?extension-ops=matrix"
  ];
}

export function buildExtensionLegacyLaunchArgs() {
  return [
    "launch",
    "--extension-only",
    "--extension-legacy",
    "--wait-for-extension",
    "--wait-timeout-ms",
    String(EXTENSION_WAIT_TIMEOUT_MS),
    "--start-url",
    "https://example.com/?extension-legacy=matrix"
  ];
}

function registerHeadlessMarker(marker) {
  if (typeof marker === "string" && marker.length > 0) {
    ownedHeadlessMarkers.add(marker);
  }
}

function registerHeadlessProfileDir(profileDir) {
  if (typeof profileDir === "string" && profileDir.length > 0) {
    ownedHeadlessProfileDirs.add(profileDir);
    registerHeadlessMarker(profileDir);
  }
}

function unregisterHeadlessProfileDir(profileDir) {
  if (typeof profileDir === "string" && profileDir.length > 0) {
    ownedHeadlessProfileDirs.delete(profileDir);
  }
}

function removeDirSafe(targetDir) {
  if (typeof targetDir !== "string" || targetDir.length === 0) return;
  if (!fs.existsSync(targetDir)) return;
  try {
    fs.rmSync(targetDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
  } catch {
    // ignore cleanup races
  }
}

function killProcessHard(pid) {
  if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) return;
  try {
    process.kill(pid, "SIGTERM");
  } catch {
    return;
  }
  try {
    process.kill(pid, 0);
    process.kill(pid, "SIGKILL");
  } catch {
    // process exited after SIGTERM
  }
}

function killOwnedHeadlessChromeWorkers() {
  const markers = [...ownedHeadlessMarkers].filter((entry) => typeof entry === "string" && entry.length > 0);
  const isProjectWorker = (command) => command.includes("/opendevbrowser/projects/");
  const isTempProfileWorker = (command) => command.includes("/opendevbrowser/projects/") && command.includes("/temp-profiles/");
  const isLiveMatrixProfileWorker = (command) => isProjectWorker(command) && command.includes("/profiles/live-matrix-");
  const processList = spawnSync("ps", ["-ax", "-o", "pid=,command="], {
    encoding: "utf-8",
    maxBuffer: MAX_BUFFER
  });
  if ((processList.status ?? 1) !== 0) return;
  const lines = String(processList.stdout ?? "").split(/\r?\n/);
  for (const line of lines) {
    const trimmed = line.trim();
    if (trimmed.length === 0) continue;
    const match = trimmed.match(/^(\d+)\s+(.*)$/);
    if (!match) continue;
    const pid = Number.parseInt(match[1], 10);
    const command = match[2] ?? "";
    const tempProfileWorker = isTempProfileWorker(command);
    const liveMatrixProfileWorker = isLiveMatrixProfileWorker(command);
    const headlessOwnedWorker = command.includes(HEADLESS_PROCESS_MATCH) && markers.some((marker) => command.includes(marker));
    if (!tempProfileWorker && !headlessOwnedWorker && !liveMatrixProfileWorker) continue;
    killProcessHard(pid);
  }
}

function cleanupOwnedHeadlessResources() {
  if (headlessCleanupCompleted) return;
  headlessCleanupCompleted = true;
  killOwnedHeadlessChromeWorkers();
  for (const profileDir of [...ownedHeadlessProfileDirs]) {
    removeDirSafe(profileDir);
    unregisterHeadlessProfileDir(profileDir);
  }
}

function installHeadlessCleanupHooks() {
  if (headlessCleanupHooksInstalled) return;
  headlessCleanupHooksInstalled = true;
  process.on("exit", cleanupOwnedHeadlessResources);
  for (const signal of ["SIGINT", "SIGTERM"]) {
    process.on(signal, () => {
      cleanupOwnedHeadlessResources();
      process.exit(signal === "SIGINT" ? 130 : 143);
    });
  }
}

function parseJsonFromStdout(stdout) {
  const lines = stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
  for (const line of lines) {
    try {
      return JSON.parse(line);
    } catch {
      continue;
    }
  }
  return null;
}

function runCli(args, { allowFailure = false, env = process.env } = {}) {
  const start = Date.now();
  const result = spawnSync(process.execPath, [CLI, ...args, "--output-format", "json"], {
    cwd: ROOT,
    encoding: "utf-8",
    timeout: CLI_TIMEOUT_MS,
    maxBuffer: MAX_BUFFER,
    env
  });
  const durationMs = Date.now() - start;
  const status = result.status ?? (result.signal ? 1 : 0);
  const timedOut = result.error?.code === "ETIMEDOUT";
  const payload = {
    status,
    stdout: result.stdout ?? "",
    stderr: result.stderr ?? "",
    json: parseJsonFromStdout(result.stdout ?? ""),
    durationMs,
    signal: result.signal ?? null,
    timedOut,
    ...(result.error ? { error: String(result.error) } : {})
  };

  if (!allowFailure && payload.status !== 0) {
    const detail = timedOut
      ? `CLI timed out after ${CLI_TIMEOUT_MS}ms (${args.join(" ")}).`
      : payload.json?.error ?? payload.stderr ?? payload.stdout ?? "Unknown CLI failure";
    throw new Error(`CLI failed (${args.join(" ")}): ${detail}`);
  }
  return payload;
}

function runNode(args, { allowFailure = false, env = process.env, timeoutMs = 600000 } = {}) {
  const start = Date.now();
  const result = spawnSync(process.execPath, args, {
    cwd: ROOT,
    encoding: "utf-8",
    timeout: timeoutMs,
    maxBuffer: MAX_BUFFER,
    env
  });
  const durationMs = Date.now() - start;
  const status = result.status ?? (result.signal ? 1 : 0);
  const timedOut = result.error?.code === "ETIMEDOUT";
  const payload = {
    status,
    stdout: result.stdout ?? "",
    stderr: result.stderr ?? "",
    json: parseJsonFromStdout(result.stdout ?? ""),
    durationMs,
    signal: result.signal ?? null,
    timedOut,
    ...(result.error ? { error: String(result.error) } : {})
  };

  if (!allowFailure && payload.status !== 0) {
    const detail = timedOut
      ? `Node script timed out after ${timeoutMs}ms (${args.join(" ")}).`
      : payload.stderr ?? payload.stdout ?? "Unknown node script failure";
    throw new Error(`Node script failed (${args.join(" ")}): ${detail}`);
  }
  return payload;
}

function runCliAsync(args, { allowFailure = false, env = process.env } = {}) {
  return new Promise((resolve, reject) => {
    const start = Date.now();
    const child = spawn(process.execPath, [CLI, ...args, "--output-format", "json"], {
      cwd: ROOT,
      env,
      stdio: ["ignore", "pipe", "pipe"]
    });
    let stdout = "";
    let stderr = "";
    let settled = false;
    let timedOut = false;

    const timeoutHandle = setTimeout(() => {
      if (settled) return;
      timedOut = true;
      child.kill("SIGTERM");
    }, CLI_TIMEOUT_MS);

    const finishReject = (error) => {
      if (settled) return;
      settled = true;
      clearTimeout(timeoutHandle);
      reject(error);
    };

    child.stdout.on("data", (chunk) => {
      stdout += String(chunk);
      if (stdout.length > MAX_BUFFER) {
        child.kill("SIGTERM");
        finishReject(new Error(`CLI stdout exceeded max buffer for args: ${args.join(" ")}`));
      }
    });
    child.stderr.on("data", (chunk) => {
      stderr += String(chunk);
      if (stderr.length > MAX_BUFFER) {
        child.kill("SIGTERM");
        finishReject(new Error(`CLI stderr exceeded max buffer for args: ${args.join(" ")}`));
      }
    });
    child.on("error", (error) => {
      finishReject(error);
    });
    child.on("close", (code, signal) => {
      if (settled) return;
      settled = true;
      clearTimeout(timeoutHandle);
      const status = code ?? (signal ? 1 : 0);
      const payload = {
        status,
        stdout,
        stderr,
        json: parseJsonFromStdout(stdout),
        durationMs: Date.now() - start,
        signal: signal ?? null,
        timedOut
      };
      if (!allowFailure && payload.status !== 0) {
        const detail = timedOut
          ? `CLI timed out after ${CLI_TIMEOUT_MS}ms (${args.join(" ")}).`
          : payload.json?.error ?? payload.stderr ?? payload.stdout ?? "Unknown CLI failure";
        reject(new Error(`CLI failed (${args.join(" ")}): ${detail}`));
        return;
      }
      resolve(payload);
    });
  });
}

function startDaemonDetached(env) {
  const child = spawn(process.execPath, [CLI, "serve", "--output-format", "json"], {
    detached: true,
    stdio: "ignore",
    env
  });
  child.unref();
}

async function waitForDaemonReady(env, timeoutMs = 30000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const status = runCli(["status", "--daemon"], { allowFailure: true, env });
    if (status.status === 0) {
      return status;
    }
    await sleep(5000);
  }
  return null;
}

function ensureCliBuilt() {
  if (!fs.existsSync(CLI)) {
    throw new Error(`CLI not found at ${CLI}. Run npm run build first.`);
  }
}

function summarizeFailure(result) {
  const fromJson = result.json?.error ?? result.json?.message;
  return typeof fromJson === "string" && fromJson.length > 0
    ? fromJson
    : result.stderr || result.stdout || result.error || "Unknown failure";
}

function pickSessionId(result) {
  return typeof result.json?.data?.sessionId === "string" ? result.json.data.sessionId : null;
}

async function getFreePort() {
  return await new Promise((resolve, reject) => {
    const server = net.createServer();
    server.on("error", reject);
    server.listen(0, "127.0.0.1", () => {
      const address = server.address();
      if (!address || typeof address === "string") {
        server.close(() => reject(new Error("Unable to allocate free port")));
        return;
      }
      const port = address.port;
      server.close(() => resolve(port));
    });
  });
}

async function waitForHttp(port, pathSuffix, timeoutMs = 30000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    try {
      const response = await fetch(`http://127.0.0.1:${port}${pathSuffix}`);
      if (response.ok) {
        return true;
      }
    } catch {
      // retry
    }
    await new Promise((resolve) => setTimeout(resolve, 250));
  }
  return false;
}

async function createIsolatedRuntime() {
  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "opendevbrowser-live-matrix-"));
  const configDir = path.join(tempRoot, "config");
  const cacheDir = path.join(tempRoot, "cache");
  fs.mkdirSync(configDir, { recursive: true });
  fs.mkdirSync(cacheDir, { recursive: true });

  const daemonPort = await getFreePort();
  const relayPort = await getFreePort();
  const daemonToken = randomUUID().replaceAll("-", "");
  const relayToken = randomUUID().replaceAll("-", "");
  const configPath = path.join(configDir, "opendevbrowser.jsonc");
  const config = [
    "{",
    `  "daemonPort": ${daemonPort},`,
    `  "daemonToken": "${daemonToken}",`,
    `  "relayPort": ${relayPort},`,
    `  "relayToken": "${relayToken}"`,
    "}",
    ""
  ].join("\n");
  fs.writeFileSync(configPath, config, { encoding: "utf-8", mode: 0o600 });

  const env = {
    ...process.env,
    OPENCODE_CONFIG_DIR: configDir,
    OPENCODE_CACHE_DIR: cacheDir
  };

  return { env, tempRoot, configDir, cacheDir, daemonPort, relayPort };
}

function findChromePath() {
  return findLocalChromeBinary();
}

async function launchRemoteChrome(chromePath, options) {
  const port = options?.port ?? await getFreePort();
  const profileDir = options?.profileDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "opendevbrowser-live-cdp-"));
  registerHeadlessProfileDir(profileDir);
  const args = [
    `--remote-debugging-port=${port}`,
    `--user-data-dir=${profileDir}`,
    "--disable-gpu",
    "--no-first-run",
    "--no-default-browser-check",
    "about:blank"
  ];
  if (options?.headless === true) {
    args.splice(2, 0, "--headless=new");
  }
  const processHandle = spawn(chromePath, args, { stdio: ["ignore", "ignore", "ignore"] });
  const ready = await waitForHttp(port, "/json/version", 30000);
  if (!ready) {
    if (!processHandle.killed) {
      processHandle.kill("SIGTERM");
    }
    throw new Error(`Remote debugging endpoint did not become ready on port ${port}.`);
  }
  return {
    process: processHandle,
    port,
    profileDir
  };
}

function cleanupRemoteChrome(instance) {
  if (!instance) return;
  if (instance.process && !instance.process.killed) {
    try {
      instance.process.kill("SIGTERM");
    } catch {
      // ignore kill failures
    }
    killProcessHard(instance.process.pid);
  }
  if (instance.profileDir) {
    removeDirSafe(instance.profileDir);
    unregisterHeadlessProfileDir(instance.profileDir);
  }
}

function isDetachedFrameError(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("frame has been detached");
}

function isDebuggerNotAttachedError(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("debugger is not attached");
}

function isTimeoutError(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("timed out");
}

export function isAnnotationPendingCompletion(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("waiting for manual completion");
}

function isRateLimitedError(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("429") || message.includes("rate limit");
}

function isOpsHandshakeTimeout(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("ops handshake timeout");
}

function isExtensionDisconnected(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("extension disconnected");
}

function isLegacyStaleTabError(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("no tab with given id")
    && message.includes("target.setautoattach");
}

function isFilesystemPermissionError(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("eperm") || message.includes("operation not permitted");
}

function isProfileLockError(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("processsingleton")
    || message.includes("singletonlock")
    || message.includes("profile is locked")
    || message.includes("profile directory is already in use")
    || message.includes("profile in use");
}

function isExtensionUnavailable(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("extension not connected")
    || message.includes("connect the extension")
    || message.includes("extension handshake");
}

function isNoActiveTargetError(detail) {
  return String(detail || "").toLowerCase().includes("no active target");
}

function isRestrictedUrlError(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("[restricted_url]")
    || message.includes("restricted url scheme");
}

export function resolveMacroFailureOutcome(detail, { releaseGate = false, xMacroCase = false } = {}) {
  const shellOnly = parseShellOnlyFailureDetail(detail);
  if (shellOnly) {
    return {
      status: shellOnly.status,
      detail: shellOnly.detail
    };
  }
  if (releaseGate && xMacroCase && isTimeoutError(detail)) {
    return {
      status: "pass",
      detail: "declared_divergence_boundary_observed: x_provider_timeout"
    };
  }
  return {
    status: isTimeoutError(detail) ? "env_limited" : "fail",
    detail
  };
}

export function resolveRpcFailureOutcome(id, detail) {
  if (id === "feature.rpc.macro_resolve_execute") {
    return resolveMacroFailureOutcome(detail);
  }
  return {
    status: "fail",
    detail
  };
}

export function resolveExtensionLegacyFailure(detail, { releaseGate = false } = {}) {
  if (isDetachedFrameError(detail)) {
    return {
      status: "pass",
      detail: "declared_divergence_boundary_observed: frame detached during legacy /cdp sequential navigation"
    };
  }
  if (releaseGate && isLegacyCdpConnectTimeout(detail)) {
    return {
      status: "pass",
      detail: "declared_divergence_boundary_observed: legacy /cdp connect timeout"
    };
  }
  if (releaseGate && isRestrictedUrlError(detail)) {
    return {
      status: "pass",
      detail: "verified_expected_restricted_url_gate"
    };
  }
  return {
    status: isExtensionUnavailable(detail) || isRateLimitedError(detail) || isNoActiveTargetError(detail)
      ? "env_limited"
      : "fail",
    detail
  };
}

function isLegacyCdpConnectTimeout(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("relay /cdp connectovercdp failed")
    && message.includes("timeout");
}

function isCliRequestTimeout(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("request timed out after");
}

function isOpsRequestTimeout(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("ops request timed out");
}

function isUnsupportedModeError(detail) {
  const message = String(detail || "").toLowerCase();
  return message.includes("[unsupported_mode]") || message.includes("unsupported_mode");
}

function parseRelayReadiness(relay) {
  const extensionConnected = relay?.extensionConnected === true;
  const extensionHandshakeComplete = relay?.extensionHandshakeComplete === true;
  return {
    extensionConnected,
    extensionHandshakeComplete,
    opsConnected: relay?.opsConnected === true,
    cdpConnected: relay?.cdpConnected === true,
    pairingRequired: relay?.pairingRequired === true,
    ready: extensionConnected && extensionHandshakeComplete
  };
}

function buildExtensionReadinessDetail(readiness) {
  const checks = [
    `extensionConnected=${String(readiness.extensionConnected)}`,
    `extensionHandshakeComplete=${String(readiness.extensionHandshakeComplete)}`,
    `opsConnected=${String(readiness.opsConnected)}`,
    `cdpConnected=${String(readiness.cdpConnected)}`,
    `pairingRequired=${String(readiness.pairingRequired)}`
  ];
  return [
    "Extension readiness preflight failed.",
    checks.join(", "),
    "Action: open extension popup, click Connect, verify handshake complete, then rerun matrix."
  ].join(" ");
}

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function waitForRelayReadiness(env, predicate, timeoutMs = 30000, pollIntervalMs = 1000) {
  const startedAt = Date.now();
  let latest = null;
  while (Date.now() - startedAt < timeoutMs) {
    const status = runCli(["status", "--daemon"], { allowFailure: true, env });
    if (status.status === 0) {
      latest = parseRelayReadiness(status.json?.data?.relay ?? null);
      if (predicate(latest)) {
        return latest;
      }
    }
    await sleep(pollIntervalMs);
  }
  return latest;
}

async function waitForExtensionReady(env, timeoutMs = 30000) {
  return waitForRelayReadiness(env, (readiness) => readiness?.ready === true, timeoutMs, 5000);
}

async function waitForOpsDisconnected(env, timeoutMs = 30000) {
  const latest = await waitForRelayReadiness(
    env,
    (readiness) => hasDirtyRelayClients(readiness) === false,
    timeoutMs,
    1000
  );
  if (latest && hasDirtyRelayClients(latest)) {
    throw new Error(
      `Extension relay still reports dirty clients after /ops cleanup. ${buildExtensionReadinessDetail(latest)}`
    );
  }
  return latest;
}

async function ensureOpsDisconnected(env, fallbackReadiness, timeoutMs = 30000) {
  return await waitForOpsDisconnected(env, timeoutMs);
}

async function launchExtensionWithRecovery(launchArgs, fallbackReadiness, env) {
  let lastError = null;
  for (let attempt = 0; attempt < 4; attempt += 1) {
    try {
      return runCli(launchArgs, { env });
    } catch (error) {
      lastError = error;
      const detail = error instanceof Error ? error.message : String(error);
      if (
        isRateLimitedError(detail)
        || isOpsHandshakeTimeout(detail)
        || isExtensionDisconnected(detail)
        || isLegacyCdpConnectTimeout(detail)
        || isCliRequestTimeout(detail)
      ) {
        if (attempt >= 3) break;
        await sleep(RATE_LIMIT_COOLDOWN_MS);
        const recovered = await waitForExtensionReady(env, 30000);
        if (!recovered?.ready) {
          throw new Error(buildExtensionReadinessDetail(recovered ?? fallbackReadiness));
        }
        continue;
      }
      if (isExtensionUnavailable(detail)) {
        const recovered = await waitForExtensionReady(env, 30000);
        if (!recovered?.ready) {
          throw new Error(buildExtensionReadinessDetail(recovered ?? fallbackReadiness));
        }
        if (attempt >= 3) break;
        await sleep(1000);
        continue;
      }
      if (isLegacyStaleTabError(detail)) {
        const recovered = await waitForExtensionReady(env, 30000);
        if (!recovered?.ready) {
          throw new Error(buildExtensionReadinessDetail(recovered ?? fallbackReadiness));
        }
        if (attempt >= 3) break;
        await sleep(1000);
        continue;
      }
      throw error;
    }
  }

  throw lastError ?? new Error(`Extension launch failed: ${launchArgs.join(" ")}`);
}

async function primeLegacyCdpTab(fallbackReadiness, env) {
  let seedSessionId = null;
  try {
    await ensureOpsDisconnected(env, fallbackReadiness, 15000);
    const seedLaunch = await launchExtensionWithRecovery(
      ["launch", "--extension-only", "--wait-for-extension", "--wait-timeout-ms", String(EXTENSION_WAIT_TIMEOUT_MS)],
      fallbackReadiness,
      env
    );
    seedSessionId = pickSessionId(seedLaunch);
    if (!seedSessionId) {
      return;
    }
    openExtensionScenarioTarget(seedSessionId, "https://example.com/?legacy=prime", env);
  } catch {
    // best effort priming only
  } finally {
    if (seedSessionId) {
      runCli(["disconnect", "--session-id", seedSessionId], { allowFailure: true, env });
      await ensureOpsDisconnected(env, fallbackReadiness, 15000);
    }
  }
}

async function runGotoWithDetachedRetry(args, env, maxAttempts = 3) {
  let result = runCli(args, { allowFailure: true, env });
  for (let attempt = 1; attempt < maxAttempts; attempt += 1) {
    if (result.status === 0) break;
    if (!isDetachedFrameError(summarizeFailure(result))) break;
    await sleep(attempt * 1000);
    result = runCli(args, { allowFailure: true, env });
  }
  return result;
}

function openExtensionScenarioTarget(sessionId, url, env) {
  const created = runCli([
    "target-new",
    "--session-id",
    sessionId,
    "--url",
    url
  ], { allowFailure: true, env });
  const targetId = created.json?.data?.targetId;
  if (typeof targetId !== "string" || targetId.length === 0) {
    throw new Error(`Extension scenario target-new failed: ${summarizeFailure(created)}`);
  }
  const focused = runCli([
    "target-use",
    "--session-id",
    sessionId,
    "--target-id",
    targetId
  ], { allowFailure: true, env });
  if (focused.status !== 0) {
    throw new Error(`Extension scenario target-use failed: ${summarizeFailure(focused)}`);
  }
  runCli([
    "wait",
    "--session-id",
    sessionId,
    "--until",
    "load",
    "--timeout-ms",
    "30000"
  ], { allowFailure: true, env });
  return targetId;
}

function addResult(results, entry) {
  results.push(entry);
}

export function evaluateRealWorldScenarioPack({ artifact, runStatus, releaseGate }) {
  const counts = artifact?.counts ?? null;
  const passCount = Number.isInteger(counts?.pass) ? counts.pass : 0;
  const envLimitedCount = Number.isInteger(counts?.env_limited) ? counts.env_limited : 0;
  const failCount = Number.isInteger(counts?.fail) ? counts.fail : 0;
  const requireZeroEnvLimited = releaseGate === true;
  const artifactOk = typeof artifact?.ok === "boolean"
    ? artifact.ok
    : (failCount === 0 && passCount > 0 && (!requireZeroEnvLimited || envLimitedCount === 0));
  return {
    passCount,
    envLimitedCount,
    failCount,
    artifactOk,
    requireZeroEnvLimited,
    m23Pass: artifactOk && passCount > 0 && (!requireZeroEnvLimited || envLimitedCount === 0),
    exitStatus: Number.isInteger(runStatus) ? runStatus : 0
  };
}

export function summarize(results, startedAt, options) {
  const counts = {
    pass: results.filter((item) => item.status === "pass").length,
    env_limited: results.filter((item) => item.status === "env_limited").length,
    expected_timeout: results.filter((item) => item.status === "expected_timeout").length,
    fail: results.filter((item) => item.status === "fail").length
  };
  const strictReleaseOk = counts.fail === 0 && counts.env_limited === 0 && counts.expected_timeout === 0;
  return {
    startedAt: new Date(startedAt).toISOString(),
    finishedAt: new Date().toISOString(),
    durationMs: Date.now() - startedAt,
    releaseGate: options.releaseGate,
    counts,
    ok: options.releaseGate ? strictReleaseOk : counts.fail === 0,
    results
  };
}

async function runMatrix(options) {
  ensureCliBuilt();
  installHeadlessCleanupHooks();
  const startedAt = Date.now();
  const useGlobalEnv = shouldUseGlobalEnv();
  const isolatedRuntime = useGlobalEnv ? null : await createIsolatedRuntime();
  const matrixEnv = isolatedRuntime?.env ?? process.env;
  registerHeadlessMarker(isolatedRuntime?.cacheDir ?? "");
  registerHeadlessMarker(isolatedRuntime?.tempRoot ?? "");
  /** @type {StepResult[]} */
  const results = [];
  let relayStatus = null;
  const forceRecycle = process.env.LIVE_MATRIX_FORCE_RECYCLE === "1";
  const managedProfileName = `live-matrix-${process.pid}-${Date.now().toString(36)}`;
  const managedHeadedProfileName = `${managedProfileName}-headed`;
  const annotateDirectProfileName = `${managedProfileName}-annotate`;
  const soakManagedProfileName = `${managedProfileName}-soak`;
  registerHeadlessMarker(managedProfileName);
  registerHeadlessMarker(`${managedProfileName}-retry`);
  registerHeadlessMarker(annotateDirectProfileName);
  registerHeadlessMarker(soakManagedProfileName);
  // Clean stale matrix workers from prior interrupted runs before launching new scenarios.
  killOwnedHeadlessChromeWorkers();
  const matrixScenarioOutcomes = {
    managedHeaded: null,
    managedHeadless: null,
    cdpHeaded: null,
    cdpHeadless: null
  };

  // Keep daemon reuse as default to preserve extension connectivity across runs.
  try {
    const existing = runCli(["status", "--daemon"], { allowFailure: true, env: matrixEnv });
    let daemonState = "reused";
    let daemonResult = existing;
    const recycleDirtyRelay = existing.status === 0 && hasDirtyRelayClients(existing.json?.data?.relay ?? null);

    if (forceRecycle || recycleDirtyRelay || existing.status !== 0) {
      if (forceRecycle || recycleDirtyRelay) {
        runCli(["serve", "--stop"], { allowFailure: true, env: matrixEnv });
        daemonState = forceRecycle ? "recycled" : "recycled_dirty_relay";
      } else {
        daemonState = "started";
      }

      startDaemonDetached(matrixEnv);
      const ready = await waitForDaemonReady(matrixEnv, 30000);
      if (!ready) {
        throw new Error("Timed out waiting for daemon to become ready.");
      }
      daemonResult = ready;
    }

    addResult(results, {
      id: "infra.daemon.recycle",
      status: "pass",
      data: {
        mode: daemonState,
        durationMs: daemonResult.durationMs,
        message: typeof daemonResult.json?.message === "string" ? daemonResult.json.message : null,
        runtimeMode: useGlobalEnv ? "global" : "isolated",
        configDir: isolatedRuntime?.configDir ?? null,
        cacheDir: isolatedRuntime?.cacheDir ?? null,
        daemonPort: isolatedRuntime?.daemonPort ?? null,
        relayPort: isolatedRuntime?.relayPort ?? null
      }
    });
  } catch (error) {
    addResult(results, {
      id: "infra.daemon.recycle",
      status: "fail",
      detail: error instanceof Error ? error.message : String(error)
    });
  }

  // Infrastructure checks
  try {
    const daemonStatus = runCli(["status", "--daemon"], { env: matrixEnv });
    relayStatus = daemonStatus.json?.data?.relay ?? null;
    addResult(results, {
      id: "infra.status.daemon",
      status: "pass",
      data: {
        durationMs: daemonStatus.durationMs,
        relay: relayStatus
      }
    });
  } catch (error) {
    addResult(results, {
      id: "infra.status.daemon",
      status: "fail",
      detail: error instanceof Error ? error.message : String(error)
    });
  }

  for (const [id, args] of [
    ["infra.daemon.status", ["daemon", "status"]],
    ["infra.native.status", ["native", "status"]]
  ]) {
    try {
      const result = runCli(args, { env: matrixEnv });
      addResult(results, {
        id,
        status: "pass",
        data: {
          durationMs: result.durationMs,
          message: typeof result.json?.message === "string" ? result.json.message : null
        }
      });
    } catch (error) {
      addResult(results, {
        id,
        status: "fail",
        detail: error instanceof Error ? error.message : String(error)
      });
    }
  }

  let extensionReadiness = parseRelayReadiness(relayStatus);
  if (!extensionReadiness.ready) {
    const recovered = await waitForExtensionReady(matrixEnv, 45000);
    if (recovered) {
      extensionReadiness = recovered;
    }
  }
  addResult(results, {
    id: "infra.extension.ready",
    status: extensionReadiness.ready ? "pass" : "env_limited",
    detail: extensionReadiness.ready ? undefined : buildExtensionReadinessDetail(extensionReadiness),
    data: {
      extensionConnected: extensionReadiness.extensionConnected,
      extensionHandshakeComplete: extensionReadiness.extensionHandshakeComplete,
      opsConnected: extensionReadiness.opsConnected,
      cdpConnected: extensionReadiness.cdpConnected,
      pairingRequired: extensionReadiness.pairingRequired
    }
  });

  const shouldRunExtensionModes = extensionReadiness.ready;

  // Extension headless boundary (M25): unsupported by contract.
  try {
    const headlessExtensionLaunch = runCli(["launch", "--extension-only", "--headless"], { allowFailure: true, env: matrixEnv });
    const detail = summarizeFailure(headlessExtensionLaunch);
    const unsupportedPass = headlessExtensionLaunch.status !== 0 && isUnsupportedModeError(detail);
    addResult(results, {
      id: "mode.extension_headless_unsupported",
      status: unsupportedPass ? "pass" : "fail",
      detail: unsupportedPass
        ? undefined
        : `Expected unsupported_mode, got: ${detail}`
    });
    addResult(results, {
      id: "M25.extension_headless_unsupported_mode",
      status: unsupportedPass ? "pass" : "fail",
      detail: unsupportedPass ? undefined : `Expected unsupported_mode, got: ${detail}`
    });
  } catch (error) {
    addResult(results, {
      id: "mode.extension_headless_unsupported",
      status: "fail",
      detail: error instanceof Error ? error.message : String(error)
    });
    addResult(results, {
      id: "M25.extension_headless_unsupported_mode",
      status: "fail",
      detail: error instanceof Error ? error.message : String(error)
    });
  }

  // Managed mode + cookie URL-form import
  let managedSessionId = null;
  try {
    const managedLaunchArgs = [
      "launch",
      "--no-extension",
      "--headless",
      "--profile",
      managedProfileName,
      "--start-url",
      "https://example.com"
    ];
    const managedEphemeralFallbackArgs = [
      "launch",
      "--no-extension",
      "--headless",
      "--persist-profile",
      "false",
      "--start-url",
      "https://example.com"
    ];
    let managedLaunchMode = "persistent";
    let launch = runCli(managedLaunchArgs, { allowFailure: true, env: matrixEnv });
    if (launch.status !== 0) {
      const firstDetail = summarizeFailure(launch);
      if (isProfileLockError(firstDetail)) {
        launch = runCli([
          "launch",
          "--no-extension",
          "--headless",
          "--profile",
          `${managedProfileName}-retry`,
          "--start-url",
          "https://example.com"
        ], { allowFailure: true, env: matrixEnv });
        if (launch.status !== 0 && isProfileLockError(summarizeFailure(launch))) {
          launch = runCli(managedEphemeralFallbackArgs, { allowFailure: true, env: matrixEnv });
          managedLaunchMode = "ephemeral_fallback";
        }
      }
      if (launch.status !== 0) {
        throw new Error(summarizeFailure(launch));
      }
    }
    managedSessionId = pickSessionId(launch);
    if (!managedSessionId) {
      throw new Error("Managed launch returned no sessionId.");
    }
    const goto = runCli(["goto", "--session-id", managedSessionId, "--url", "https://example.com", "--wait-until", "load", "--timeout-ms", "30000"], { env: matrixEnv });
    const wait = runCli(["wait", "--session-id", managedSessionId, "--until", "load", "--timeout-ms", "30000"], { env: matrixEnv });
    const debug = runCli(["debug-trace-snapshot", "--session-id", managedSessionId, "--max", "80"], { env: matrixEnv });
    runCli(["snapshot", "--session-id", managedSessionId, "--mode", "actionables", "--max-chars", "6000"], { env: matrixEnv });
    runCli(["perf", "--session-id", managedSessionId], { env: matrixEnv });

    const cookiesPayload = JSON.stringify([{ name: "matrix_cookie", value: "ok", url: "https://example.com" }]);
    runCli(["cookie-import", "--session-id", managedSessionId, "--cookies", cookiesPayload, "--request-id", "matrix-cookie-url"], { env: matrixEnv });
    const debugBlockerState = debug.json?.data?.meta?.blockerState;
    if (
      typeof goto.json?.data?.meta?.blockerState !== "string"
      || typeof wait.json?.data?.meta?.blockerState !== "string"
      || typeof debugBlockerState !== "string"
    ) {
      throw new Error("Managed navigation responses missing blockerState metadata.");
    }
    addResult(results, {
      id: "mode.managed",
      status: "pass",
      data: {
        gotoBlockerState: goto.json?.data?.meta?.blockerState,
        waitBlockerState: wait.json?.data?.meta?.blockerState,
        debugBlockerState,
        debugBlockerType: debug.json?.data?.meta?.blocker?.type ?? null,
        profile: managedProfileName,
        launchMode: managedLaunchMode
      }
    });
    matrixScenarioOutcomes.managedHeadless = {
      gotoBlockerState: goto.json?.data?.meta?.blockerState ?? null,
      waitBlockerState: wait.json?.data?.meta?.blockerState ?? null,
      debugBlockerState: debug.json?.data?.meta?.blockerState ?? null
    };
    addResult(results, { id: "feature.cookie_import_url", status: "pass" });
  } catch (error) {
    const detail = error instanceof Error ? error.message : String(error);
    addResult(results, { id: "mode.managed", status: "fail", detail });
    if (detail.includes("matrix-cookie-url") || detail.toLowerCase().includes("cookie import")) {
      addResult(results, { id: "feature.cookie_import_url", status: "fail", detail });
    }
  } finally {
    if (managedSessionId) {
      runCli(["disconnect", "--session-id", managedSessionId, "--close-browser"], { allowFailure: true, env: matrixEnv });
    }
  }

  // Managed headed baseline parallel scenario (M1)
  let managedHeadedSessionId = null;
  try {
    const managedHeadedEphemeralFallbackArgs = [
      "launch",
      "--no-extension",
      "--persist-profile",
      "false",
      "--start-url",
      "https://example.com"
    ];
    let launch = runCli([
      "launch",
      "--no-extension",
      "--profile",
      managedHeadedProfileName,
      "--start-url",
      "https://example.com"
    ], { allowFailure: true, env: matrixEnv });
    if (launch.status !== 0) {
      const firstDetail = summarizeFailure(launch);
      if (isProfileLockError(firstDetail)) {
        launch = runCli([
          "launch",
          "--no-extension",
          "--profile",
          `${managedHeadedProfileName}-retry`,
          "--start-url",
          "https://example.com"
        ], { allowFailure: true, env: matrixEnv });
        if (launch.status !== 0 && isProfileLockError(summarizeFailure(launch))) {
          launch = runCli(managedHeadedEphemeralFallbackArgs, { allowFailure: true, env: matrixEnv });
        }
      }
      if (launch.status !== 0) {
        throw new Error(summarizeFailure(launch));
      }
    }

    managedHeadedSessionId = pickSessionId(launch);
    if (!managedHeadedSessionId) {
      throw new Error("Managed headed launch returned no sessionId.");
    }

    const baseTargets = runCli(["targets-list", "--session-id", managedHeadedSessionId], { env: matrixEnv });
    const primaryTargetId = baseTargets.json?.data?.activeTargetId;
    if (typeof primaryTargetId !== "string") {
      throw new Error("Managed headed baseline missing primary targetId.");
    }
    const created = runCli([
      "target-new",
      "--session-id",
      managedHeadedSessionId,
      "--url",
      "https://example.com/?m1=secondary"
    ], { env: matrixEnv });
    const secondaryTargetId = created.json?.data?.targetId;
    if (typeof secondaryTargetId !== "string") {
      throw new Error("Managed headed baseline missing secondary targetId.");
    }

    const [gotoPrimary, gotoSecondary] = await Promise.all([
      runCliAsync([
        "rpc",
        "--unsafe-internal",
        "--name",
        "nav.goto",
        "--params",
        JSON.stringify({
          sessionId: managedHeadedSessionId,
          targetId: primaryTargetId,
          url: "https://example.com/?m1=primary",
          waitUntil: "load",
          timeoutMs: 30000
        })
      ], { env: matrixEnv }),
      runCliAsync([
        "rpc",
        "--unsafe-internal",
        "--name",
        "nav.goto",
        "--params",
        JSON.stringify({
          sessionId: managedHeadedSessionId,
          targetId: secondaryTargetId,
          url: "https://example.com/?m1=secondary",
          waitUntil: "load",
          timeoutMs: 30000
        })
      ], { env: matrixEnv })
    ]);
    const debug = runCli(["debug-trace-snapshot", "--session-id", managedHeadedSessionId, "--max", "80"], { env: matrixEnv });
    const wait = runCli(["wait", "--session-id", managedHeadedSessionId, "--until", "load", "--timeout-ms", "30000"], { env: matrixEnv });

    const primaryBlocker = gotoPrimary.json?.data?.result?.meta?.blockerState;
    const secondaryBlocker = gotoSecondary.json?.data?.result?.meta?.blockerState;
    const waitBlocker = wait.json?.data?.meta?.blockerState;
    const debugBlocker = debug.json?.data?.meta?.blockerState;
    if (
      typeof primaryBlocker !== "string"
      || typeof secondaryBlocker !== "string"
      || typeof waitBlocker !== "string"
      || typeof debugBlocker !== "string"
    ) {
      throw new Error("Managed headed scenario missing blockerState metadata.");
    }

    matrixScenarioOutcomes.managedHeaded = {
      gotoBlockerState: primaryBlocker,
      waitBlockerState: waitBlocker,
      debugBlockerState: debugBlocker
    };
    addResult(results, {
      id: "M1.managed_headed_parallel",
      status: "pass",
      data: {
        primaryTargetId,
        secondaryTargetId,
        primaryBlocker,
        secondaryBlocker,
        waitBlocker,
        debugBlocker
      }
    });
  } catch (error) {
    const detail = error instanceof Error ? error.message : String(error);
    addResult(results, {
      id: "M1.managed_headed_parallel",
      status: isFilesystemPermissionError(detail) ? "env_limited" : "fail",
      detail
    });
  } finally {
    if (managedHeadedSessionId) {
      runCli(["disconnect", "--session-id", managedHeadedSessionId, "--close-browser"], { allowFailure: true, env: matrixEnv });
    }
  }

  // Extension ops mode
  let extensionSessionId = null;
  if (!shouldRunExtensionModes) {
    addResult(results, {
      id: "mode.extension_ops",
      status: "env_limited",
      detail: buildExtensionReadinessDetail(extensionReadiness),
      data: {
        skippedByPreflight: true
      }
    });
  } else {
    const maxExtensionOpsAttempts = 2;
    let extensionOpsRecorded = false;
    for (let attempt = 1; attempt <= maxExtensionOpsAttempts; attempt += 1) {
      extensionSessionId = null;
      let shouldRetry = false;
      try {
        const launch = await launchExtensionWithRecovery(
          buildExtensionOpsLaunchArgs(),
          extensionReadiness,
          matrixEnv
        );
        extensionSessionId = pickSessionId(launch);
        if (!extensionSessionId) {
          throw new Error("Extension launch returned no sessionId.");
        }
        runCli(["wait", "--session-id", extensionSessionId, "--until", "load", "--timeout-ms", "30000"], {
          allowFailure: true,
          env: matrixEnv
        });
        const goto = runCli(
          ["goto", "--session-id", extensionSessionId, "--url", "https://example.com", "--wait-until", "load", "--timeout-ms", "30000"],
          { allowFailure: true, env: matrixEnv }
        );
        const gotoDetail = summarizeFailure(goto);
        if (goto.status !== 0) {
          throw new Error(gotoDetail);
        }
        const debug = runCli(["debug-trace-snapshot", "--session-id", extensionSessionId, "--max", "80"], { env: matrixEnv });
        const snapshot = runCli([
          "snapshot",
          "--session-id",
          extensionSessionId,
          "--mode",
          "actionables",
          "--max-chars",
          "6000",
          "--timeout-ms",
          "15000"
        ], {
          allowFailure: true,
          env: matrixEnv
        });
        const perf = runCli(["perf", "--session-id", extensionSessionId], {
          allowFailure: true,
          env: matrixEnv
        });
        if (
          typeof goto.json?.data?.meta?.blockerState !== "string"
          || typeof debug.json?.data?.meta?.blockerState !== "string"
        ) {
          throw new Error("Extension /ops mode missing blockerState metadata in navigation/debug output.");
        }
        const snapshotDetail = summarizeFailure(snapshot);
        const perfDetail = summarizeFailure(perf);
        if (
          (snapshot.status !== 0
            && !isExtensionDisconnected(snapshotDetail)
            && !isDetachedFrameError(snapshotDetail)
            && !isDebuggerNotAttachedError(snapshotDetail))
          || (perf.status !== 0
            && !isExtensionDisconnected(perfDetail)
            && !isDetachedFrameError(perfDetail)
            && !isDebuggerNotAttachedError(perfDetail))
        ) {
          throw new Error(`Extension /ops diagnostics failed (snapshot=${snapshotDetail}; perf=${perfDetail}).`);
        }
        addResult(results, {
          id: "mode.extension_ops",
          status: "pass",
          data: {
            gotoBlockerState: goto.json?.data?.meta?.blockerState,
            debugBlockerState: debug.json?.data?.meta?.blockerState,
            debugBlockerType: debug.json?.data?.meta?.blocker?.type ?? null,
            attempts: attempt
          }
        });
        extensionOpsRecorded = true;
      } catch (error) {
        const detail = error instanceof Error ? error.message : String(error);
        shouldRetry = attempt < maxExtensionOpsAttempts && isOpsRequestTimeout(detail);
        if (!shouldRetry) {
          if (options.releaseGate && isRestrictedUrlError(detail)) {
            addResult(results, {
              id: "mode.extension_ops",
              status: "pass",
              detail: "verified_expected_restricted_url_gate"
            });
          } else {
            addResult(results, {
              id: "mode.extension_ops",
              status: isExtensionUnavailable(detail) || isRateLimitedError(detail) ? "env_limited" : "fail",
              detail
            });
          }
          extensionOpsRecorded = true;
        }
      } finally {
        if (extensionSessionId) {
          runCli(["disconnect", "--session-id", extensionSessionId], { allowFailure: true, env: matrixEnv });
        }
        extensionReadiness = await ensureOpsDisconnected(matrixEnv, extensionReadiness, 15000);
      }
      if (extensionOpsRecorded || !shouldRetry) {
        break;
      }
    }
  }

  // Extension legacy (/cdp) mode
  let extensionLegacySessionId = null;
  if (!shouldRunExtensionModes) {
    addResult(results, {
      id: "mode.extension_legacy_cdp",
      status: "env_limited",
      detail: buildExtensionReadinessDetail(extensionReadiness),
      data: {
        skippedByPreflight: true
      }
    });
  } else {
    try {
      extensionReadiness = await ensureOpsDisconnected(matrixEnv, extensionReadiness, 15000);
      await primeLegacyCdpTab(extensionReadiness, matrixEnv);
      extensionReadiness = await ensureOpsDisconnected(matrixEnv, extensionReadiness, 15000);
      const launchArgs = buildExtensionLegacyLaunchArgs();
      const launch = await launchExtensionWithRecovery(launchArgs, extensionReadiness, matrixEnv);
      extensionLegacySessionId = pickSessionId(launch);
      if (!extensionLegacySessionId) {
        throw new Error("Extension legacy launch returned no sessionId.");
      }

      runCli(["wait", "--session-id", extensionLegacySessionId, "--until", "load", "--timeout-ms", "30000"], {
        allowFailure: true,
        env: matrixEnv
      });
      const createdTarget = runCli([
        "target-new",
        "--session-id",
        extensionLegacySessionId,
        "--url",
        "https://example.com/?legacy=bootstrap"
      ], { allowFailure: true, env: matrixEnv });
      const createdTargetId = createdTarget.json?.data?.targetId;
      if (typeof createdTargetId === "string" && createdTargetId.length > 0) {
        runCli(["target-use", "--session-id", extensionLegacySessionId, "--target-id", createdTargetId], {
          allowFailure: true,
          env: matrixEnv
        });
      } else {
        const targets = runCli(["targets-list", "--session-id", extensionLegacySessionId], { allowFailure: true, env: matrixEnv });
        const activeTargetId = targets.json?.data?.activeTargetId;
        if (typeof activeTargetId === "string" && activeTargetId.length > 0) {
          runCli(["target-use", "--session-id", extensionLegacySessionId, "--target-id", activeTargetId], {
            allowFailure: true,
            env: matrixEnv
          });
        }
      }

      let goto = await runGotoWithDetachedRetry(
        ["goto", "--session-id", extensionLegacySessionId, "--url", "https://example.com", "--wait-until", "load", "--timeout-ms", "30000"],
        matrixEnv,
        8
      );
      if (goto.status !== 0 && isDetachedFrameError(summarizeFailure(goto))) {
        const reseededTarget = runCli([
          "target-new",
          "--session-id",
          extensionLegacySessionId,
          "--url",
          "https://example.com/?legacy=reseed"
        ], { allowFailure: true, env: matrixEnv });
        const reseededTargetId = reseededTarget.json?.data?.targetId;
        if (typeof reseededTargetId === "string" && reseededTargetId.length > 0) {
          runCli(["target-use", "--session-id", extensionLegacySessionId, "--target-id", reseededTargetId], {
            allowFailure: true,
            env: matrixEnv
          });
        }
        goto = await runGotoWithDetachedRetry(
          ["goto", "--session-id", extensionLegacySessionId, "--url", "https://example.com", "--wait-until", "load", "--timeout-ms", "30000"],
          matrixEnv,
          8
        );
      }
      if (goto.status !== 0) {
        throw new Error(summarizeFailure(goto));
      }

      const debug = runCli(["debug-trace-snapshot", "--session-id", extensionLegacySessionId, "--max", "80"], { env: matrixEnv });
      runCli(["snapshot", "--session-id", extensionLegacySessionId, "--mode", "actionables", "--max-chars", "6000"], { env: matrixEnv });
      runCli(["perf", "--session-id", extensionLegacySessionId], { env: matrixEnv });
      if (
        typeof goto.json?.data?.meta?.blockerState !== "string"
        || typeof debug.json?.data?.meta?.blockerState !== "string"
      ) {
        throw new Error("Extension legacy mode missing blockerState metadata in navigation/debug output.");
      }
      addResult(results, {
        id: "mode.extension_legacy_cdp",
        status: "pass",
        data: {
          gotoBlockerState: goto.json?.data?.meta?.blockerState,
          debugBlockerState: debug.json?.data?.meta?.blockerState,
          debugBlockerType: debug.json?.data?.meta?.blocker?.type ?? null
        }
      });
    } catch (error) {
      const detail = error instanceof Error ? error.message : String(error);
      const outcome = resolveExtensionLegacyFailure(detail, { releaseGate: options.releaseGate });
      addResult(results, {
        id: "mode.extension_legacy_cdp",
        status: outcome.status,
        detail: outcome.detail
      });
    } finally {
      if (extensionLegacySessionId) {
        runCli(["disconnect", "--session-id", extensionLegacySessionId], { allowFailure: true, env: matrixEnv });
      }
    }
  }

  // cdpConnect mode
  let cdpSessionId = null;
  let chromeProcess = null;
  let chromeProfileDir = null;
  try {
    const chromePath = findLocalChromeBinary();
    if (!chromePath) {
      throw new Error("No Chrome binary found for cdpConnect validation.");
    }

    const port = await getFreePort();
    chromeProfileDir = fs.mkdtempSync(path.join(os.tmpdir(), "opendevbrowser-live-cdp-"));
    registerHeadlessProfileDir(chromeProfileDir);
    chromeProcess = spawn(chromePath, [
      `--remote-debugging-port=${port}`,
      `--user-data-dir=${chromeProfileDir}`,
      "--headless=new",
      "--disable-gpu",
      "--no-first-run",
      "--no-default-browser-check",
      "about:blank"
    ], { stdio: ["ignore", "ignore", "ignore"] });

    const ready = await waitForHttp(port, "/json/version", 30000);
    if (!ready) {
      throw new Error(`Remote debugging endpoint did not become ready on port ${port}.`);
    }

    const connect = runCli(["connect", "--host", "127.0.0.1", "--cdp-port", String(port)], { env: matrixEnv });
    cdpSessionId = pickSessionId(connect);
    if (!cdpSessionId) {
      throw new Error("cdpConnect returned no sessionId.");
    }
    const goto = runCli(["goto", "--session-id", cdpSessionId, "--url", "https://example.com", "--wait-until", "load", "--timeout-ms", "30000"], { env: matrixEnv });
    const wait = runCli(["wait", "--session-id", cdpSessionId, "--until", "load", "--timeout-ms", "30000"], { env: matrixEnv });
    const debug = runCli(["debug-trace-snapshot", "--session-id", cdpSessionId, "--max", "80"], { env: matrixEnv });
    runCli(["snapshot", "--session-id", cdpSessionId, "--mode", "actionables", "--max-chars", "6000"], { env: matrixEnv });
    runCli(["perf", "--session-id", cdpSessionId], { env: matrixEnv });
    if (
      typeof goto.json?.data?.meta?.blockerState !== "string"
      || typeof wait.json?.data?.meta?.blockerState !== "string"
      || typeof debug.json?.data?.meta?.blockerState !== "string"
    ) {
      throw new Error("cdpConnect mode missing blockerState metadata in navigation/debug output.");
    }
    addResult(results, {
      id: "mode.cdp_connect",
      status: "pass",
      data: {
        gotoBlockerState: goto.json?.data?.meta?.blockerState,
        waitBlockerState: wait.json?.data?.meta?.blockerState,
        debugBlockerState: debug.json?.data?.meta?.blockerState,
        debugBlockerType: debug.json?.data?.meta?.blocker?.type ?? null
      }
    });
    matrixScenarioOutcomes.cdpHeadless = {
      gotoBlockerState: goto.json?.data?.meta?.blockerState ?? null,
      waitBlockerState: wait.json?.data?.meta?.blockerState ?? null,
      debugBlockerState: debug.json?.data?.meta?.blockerState ?? null
    };
    addResult(results, {
      id: "M6.cdp_connect_headless_parallel",
      status: "pass",
      data: {
        gotoBlockerState: goto.json?.data?.meta?.blockerState,
        waitBlockerState: wait.json?.data?.meta?.blockerState,
        debugBlockerState: debug.json?.data?.meta?.blockerState
      }
    });
  } catch (error) {
    const detail = error instanceof Error ? error.message : String(error);
    addResult(results, {
      id: "mode.cdp_connect",
      status: isFilesystemPermissionError(detail) ? "env_limited" : "fail",
      detail
    });
  } finally {
    if (cdpSessionId) {
      runCli(["disconnect", "--session-id", cdpSessionId], { allowFailure: true, env: matrixEnv });
    }
    if (chromeProcess && !chromeProcess.killed) {
      try {
        chromeProcess.kill("SIGTERM");
      } catch {
        // ignore kill failures
      }
      killProcessHard(chromeProcess.pid);
    }
    if (chromeProfileDir) {
      removeDirSafe(chromeProfileDir);
      unregisterHeadlessProfileDir(chromeProfileDir);
    }
  }

  // cdpConnect headed baseline + reconnect churn (M5, M7)
  const chromePath = findChromePath();
  if (!chromePath) {
    addResult(results, {
      id: "M5.cdp_connect_headed_parallel",
      status: "env_limited",
      detail: "No Chrome binary found for headed cdpConnect validation."
    });
    addResult(results, {
      id: "M7.cdp_connect_headed_reconnect_churn",
      status: "env_limited",
      detail: "No Chrome binary found for headed cdpConnect validation."
    });
  } else {
    let headedInstance = null;
    let cdpHeadedSessionId = null;
    let reconnectSessionId = null;
    let m5Recorded = false;
    try {
      headedInstance = await launchRemoteChrome(chromePath, { headless: false });
      const connect = runCli(["connect", "--host", "127.0.0.1", "--cdp-port", String(headedInstance.port)], { env: matrixEnv });
      cdpHeadedSessionId = pickSessionId(connect);
      if (!cdpHeadedSessionId) {
        throw new Error("cdpConnect headed launch returned no sessionId.");
      }

      const targets = runCli(["targets-list", "--session-id", cdpHeadedSessionId], { env: matrixEnv });
      const primaryTargetId = targets.json?.data?.activeTargetId;
      if (typeof primaryTargetId !== "string") {
        throw new Error("cdpConnect headed scenario missing primary targetId.");
      }
      const created = runCli([
        "target-new",
        "--session-id",
        cdpHeadedSessionId,
        "--url",
        "https://example.com/?m5=secondary"
      ], { env: matrixEnv });
      const secondaryTargetId = created.json?.data?.targetId;
      if (typeof secondaryTargetId !== "string") {
        throw new Error("cdpConnect headed scenario missing secondary targetId.");
      }

      const [gotoPrimary, gotoSecondary] = await Promise.all([
        runCliAsync([
          "rpc",
          "--unsafe-internal",
          "--name",
          "nav.goto",
          "--params",
          JSON.stringify({
            sessionId: cdpHeadedSessionId,
            targetId: primaryTargetId,
            url: "https://example.com/?m5=primary",
            waitUntil: "load",
            timeoutMs: 30000
          })
        ], { env: matrixEnv }),
        runCliAsync([
          "rpc",
          "--unsafe-internal",
          "--name",
          "nav.goto",
          "--params",
          JSON.stringify({
            sessionId: cdpHeadedSessionId,
            targetId: secondaryTargetId,
            url: "https://example.com/?m5=secondary",
            waitUntil: "load",
            timeoutMs: 30000
          })
        ], { env: matrixEnv })
      ]);

      const wait = runCli(["wait", "--session-id", cdpHeadedSessionId, "--until", "load", "--timeout-ms", "30000"], { env: matrixEnv });
      const debug = runCli(["debug-trace-snapshot", "--session-id", cdpHeadedSessionId, "--max", "80"], { env: matrixEnv });
      const primaryBlocker = gotoPrimary.json?.data?.result?.meta?.blockerState;
      const secondaryBlocker = gotoSecondary.json?.data?.result?.meta?.blockerState;
      const waitBlocker = wait.json?.data?.meta?.blockerState;
      const debugBlocker = debug.json?.data?.meta?.blockerState;
      if (
        typeof primaryBlocker !== "string"
        || typeof secondaryBlocker !== "string"
        || typeof waitBlocker !== "string"
        || typeof debugBlocker !== "string"
      ) {
        throw new Error("cdpConnect headed scenario missing blockerState metadata.");
      }
      matrixScenarioOutcomes.cdpHeaded = {
        gotoBlockerState: primaryBlocker,
        waitBlockerState: waitBlocker,
        debugBlockerState: debugBlocker
      };
      addResult(results, {
        id: "M5.cdp_connect_headed_parallel",
        status: "pass",
        data: {
          primaryTargetId,
          secondaryTargetId,
          primaryBlocker,
          secondaryBlocker,
          waitBlocker,
          debugBlocker
        }
      });
      m5Recorded = true;

      if (headedInstance.process && !headedInstance.process.killed) {
        headedInstance.process.kill("SIGTERM");
      }
      await sleep(1500);
      const churnAttempt = runCli([
        "rpc",
        "--unsafe-internal",
        "--name",
        "nav.goto",
        "--params",
        JSON.stringify({
          sessionId: cdpHeadedSessionId,
          targetId: primaryTargetId,
          url: "https://example.com/?m7=after-disconnect",
          waitUntil: "load",
          timeoutMs: 30000
        })
      ], { allowFailure: true, env: matrixEnv });
      if (churnAttempt.status === 0) {
        throw new Error("Reconnect churn probe expected failure after remote debug disconnect, but command succeeded.");
      }
      const churnFailure = summarizeFailure(churnAttempt);

      const restartInstance = await launchRemoteChrome(chromePath, { headless: false });
      headedInstance = restartInstance;
      const reconnect = runCli(["connect", "--host", "127.0.0.1", "--cdp-port", String(restartInstance.port)], { env: matrixEnv });
      reconnectSessionId = pickSessionId(reconnect);
      if (!reconnectSessionId) {
        throw new Error("Reconnect churn recovery returned no sessionId.");
      }
      const recoveredGoto = runCli([
        "goto",
        "--session-id",
        reconnectSessionId,
        "--url",
        "https://example.com/?m7=recovered",
        "--wait-until",
        "load",
        "--timeout-ms",
        "30000"
      ], { env: matrixEnv });
      addResult(results, {
        id: "M7.cdp_connect_headed_reconnect_churn",
        status: typeof recoveredGoto.json?.data?.meta?.blockerState === "string" ? "pass" : "fail",
        detail: typeof recoveredGoto.json?.data?.meta?.blockerState === "string"
          ? undefined
          : "Reconnect recovery response missing blockerState metadata.",
        data: {
          churnFailure,
          recoveredBlockerState: recoveredGoto.json?.data?.meta?.blockerState ?? null
        }
      });
    } catch (error) {
      const detail = error instanceof Error ? error.message : String(error);
      if (!m5Recorded) {
        addResult(results, {
          id: "M5.cdp_connect_headed_parallel",
          status: isFilesystemPermissionError(detail) ? "env_limited" : "fail",
          detail
        });
      }
      addResult(results, {
        id: "M7.cdp_connect_headed_reconnect_churn",
        status: isFilesystemPermissionError(detail) ? "env_limited" : "fail",
        detail
      });
    } finally {
      if (cdpHeadedSessionId) {
        runCli(["disconnect", "--session-id", cdpHeadedSessionId], { allowFailure: true, env: matrixEnv });
      }
      if (reconnectSessionId) {
        runCli(["disconnect", "--session-id", reconnectSessionId], { allowFailure: true, env: matrixEnv });
      }
      cleanupRemoteChrome(headedInstance);
    }
  }

  // Headed/headless scenario-pack comparator (M21)
  const parityComparisons = [
    {
      mode: "managed",
      headed: matrixScenarioOutcomes.managedHeaded,
      headless: matrixScenarioOutcomes.managedHeadless
    },
    {
      mode: "cdpConnect",
      headed: matrixScenarioOutcomes.cdpHeaded,
      headless: matrixScenarioOutcomes.cdpHeadless
    }
  ];
  const parityMismatches = [];
  for (const comparison of parityComparisons) {
    if (!comparison.headed || !comparison.headless) {
      parityMismatches.push(`${comparison.mode}:missing_variant_outcome`);
      continue;
    }
    for (const field of ["gotoBlockerState", "waitBlockerState", "debugBlockerState"]) {
      if (comparison.headed[field] !== comparison.headless[field]) {
        parityMismatches.push(`${comparison.mode}:${field}:${comparison.headed[field]}!=${comparison.headless[field]}`);
      }
    }
  }
  addResult(results, {
    id: "M21.headed_headless_scenario_pack_parity",
    status: parityMismatches.length === 0 ? "pass" : "fail",
    detail: parityMismatches.length === 0 ? undefined : `Parity mismatch: ${parityMismatches.join("; ")}`,
    data: {
      managedHeaded: matrixScenarioOutcomes.managedHeaded,
      managedHeadless: matrixScenarioOutcomes.managedHeadless,
      cdpHeaded: matrixScenarioOutcomes.cdpHeaded,
      cdpHeadless: matrixScenarioOutcomes.cdpHeadless
    }
  });

  // RPC checks
  for (const [id, args] of [
    ["feature.rpc.relay_status", ["rpc", "--unsafe-internal", "--name", "relay.status"]],
    ["feature.rpc.macro_resolve_execute", ["rpc", "--unsafe-internal", "--name", "macro.resolve", "--params", "{\"expression\":\"@web.search(\\\"openai\\\", 3)\",\"execute\":true}"]]
  ]) {
    try {
      runCli(args, { env: matrixEnv });
      addResult(results, { id, status: "pass" });
    } catch (error) {
      const detail = error instanceof Error ? error.message : String(error);
      const failure = resolveRpcFailureOutcome(id, detail);
      addResult(results, {
        id,
        status: failure.status,
        detail: failure.detail
      });
    }
  }

  // Macro / research matrix
  const macroCases = [
    { id: "macro.web.search", expression: "@web.search(\"openai\", 3)" },
    { id: "macro.web.fetch", expression: "@web.fetch(\"https://example.com\")" },
    { id: "macro.developer.docs", expression: "@developer.docs(\"playwright locator\", 3)" },
    { id: "macro.community.search.url", expression: "@community.search(\"https://example.com\")" },
    { id: "macro.community.search.keyword", expression: "@community.search(\"openai\", 3)" },
    { id: "macro.media.search.reddit", expression: "@media.search(\"openai\", \"reddit\", 3)" },
    { id: "macro.media.search.x", expression: "@media.search(\"openai\", \"x\", 3)" },
    { id: "macro.media.trend.x", expression: "@media.trend(\"x\", \"ai\", 3)" },
    { id: "macro.media.search.linkedin", expression: "@media.search(\"openai\", \"linkedin\", 1)" }
  ];

  for (const macroCase of macroCases) {
    const xMacroCase = macroCase.id === "macro.media.search.x" || macroCase.id === "macro.media.trend.x";
    try {
      const result = runCli(
        ["macro-resolve", "--execute", "--expression", macroCase.expression, "--timeout-ms", "120000"],
        { env: matrixEnv }
      );
      const execution = result.json?.data?.execution;
      const records = Array.isArray(execution?.records) ? execution.records.length : 0;
      const failures = Array.isArray(execution?.failures) ? execution.failures : [];
      const failureCodes = failures.map((item) => item?.error?.code).filter((value) => typeof value === "string");
      const blockerType = typeof execution?.meta?.blocker?.type === "string"
        ? execution.meta.blocker.type
        : null;

      if (records > 0) {
        addResult(results, {
          id: macroCase.id,
          status: "pass",
          data: { records, failures: failures.length, blockerType }
        });
        continue;
      }

      if (failures.length > 0 && failureCodes.length === failures.length && failureCodes.every((code) => code === "unavailable")) {
        if (!blockerType) {
          addResult(results, {
            id: macroCase.id,
            status: "fail",
            detail: "Execution failure missing execution.meta.blocker metadata.",
            data: { records, failures: failures.length, failureCodes }
          });
          continue;
        }
        addResult(results, {
          id: macroCase.id,
          status: "env_limited",
          detail: failures[0]?.error?.message ?? "Upstream unavailable",
          data: { records, failures: failures.length, failureCodes, blockerType }
        });
        continue;
      }

      if (options.releaseGate && xMacroCase && failures.length > 0 && failureCodes.includes("timeout")) {
        addResult(results, {
          id: macroCase.id,
          status: "pass",
          detail: "declared_divergence_boundary_observed: x_provider_timeout"
        });
        continue;
      }

      addResult(results, {
        id: macroCase.id,
        status: "fail",
        detail: failures[0]?.error?.message ?? "Execution returned no records.",
        data: { records, failures: failures.length, failureCodes, blockerType }
      });
    } catch (error) {
      const detail = error instanceof Error ? error.message : String(error);
      const failure = resolveMacroFailureOutcome(detail, {
        releaseGate: options.releaseGate,
        xMacroCase
      });
      addResult(results, {
        id: macroCase.id,
        status: failure.status,
        detail: failure.detail
      });
    }
  }

  // Resolve-only macro parity check for write action semantics
  try {
    const result = runCli(["macro-resolve", "--expression", "@social.post(\"x\", \"target\", \"content\", false, false)", "--include-catalog"], { env: matrixEnv });
    const hasCatalog = Array.isArray(result.json?.data?.catalog);
    addResult(results, {
      id: "macro.social.post.resolve_only",
      status: hasCatalog ? "pass" : "fail",
      detail: hasCatalog ? undefined : "Missing macro catalog in resolve-only response."
    });
  } catch (error) {
    addResult(results, {
      id: "macro.social.post.resolve_only",
      status: "fail",
      detail: error instanceof Error ? error.message : String(error)
    });
  }

  // Annotation invocation (manual interaction expected, timeout acceptable)
  async function runAnnotateProbe(mode) {
    if (mode === "direct" && options.releaseGate) {
      addResult(results, {
        id: "feature.annotate.direct",
        status: "pass",
        detail: "skipped_in_release_gate_manual_probe"
      });
      return;
    }

    let sessionId = null;
    let targetId = null;
    try {
      const launchArgs = mode === "relay"
        ? ["launch", "--extension-only", "--wait-for-extension", "--wait-timeout-ms", String(EXTENSION_WAIT_TIMEOUT_MS)]
        : [
          "launch",
          "--no-extension",
          "--headless",
          "--profile",
          annotateDirectProfileName,
          "--start-url",
          "https://example.com"
        ];
      const launch = mode === "relay"
        ? await launchExtensionWithRecovery(launchArgs, extensionReadiness, matrixEnv)
        : runCli(launchArgs, { env: matrixEnv });
      sessionId = pickSessionId(launch);
      if (!sessionId) throw new Error("Annotation probe launch returned no sessionId.");
      if (mode === "relay") {
        targetId = openExtensionScenarioTarget(sessionId, "https://example.com/?annotate=relay", matrixEnv);
      }

      const annotateArgs = [
        "annotate",
        "--session-id", sessionId,
        "--transport", mode,
        "--screenshot-mode", "none",
        "--timeout-ms", "8000",
        "--context", "Live regression matrix annotation probe"
      ];
      if (targetId) {
        annotateArgs.push("--target-id", targetId);
      }
      const annotate = runCli(annotateArgs, { allowFailure: true, env: matrixEnv });
      if (annotate.status === 0 && annotate.json?.success === true) {
        addResult(results, { id: `feature.annotate.${mode}`, status: "pass" });
        return;
      }
      const detail = summarizeFailure(annotate);
      if (isTimeoutError(detail) || isAnnotationPendingCompletion(detail)) {
        if (options.releaseGate && mode === "relay") {
          addResult(results, {
            id: `feature.annotate.${mode}`,
            status: "pass",
            detail: "declared_divergence_boundary_observed: annotation_manual_timeout"
          });
          return;
        }
        const timeoutStatus = "expected_timeout";
        addResult(results, {
          id: `feature.annotate.${mode}`,
          status: timeoutStatus,
          detail
        });
        return;
      }
      if (mode === "relay" && isRateLimitedError(detail)) {
        addResult(results, {
          id: `feature.annotate.${mode}`,
          status: "env_limited",
          detail
        });
        return;
      }
      if (mode === "relay" && options.releaseGate && isRestrictedUrlError(detail)) {
        addResult(results, {
          id: `feature.annotate.${mode}`,
          status: "pass",
          detail: "verified_expected_restricted_url_gate"
        });
        return;
      }
      addResult(results, {
        id: `feature.annotate.${mode}`,
        status: "fail",
        detail
      });
    } catch (error) {
      const detail = error instanceof Error ? error.message : String(error);
      const timeoutStatus = options.releaseGate && mode === "relay" ? "pass" : "expected_timeout";
      addResult(results, {
        id: `feature.annotate.${mode}`,
        status: isTimeoutError(detail) || isAnnotationPendingCompletion(detail)
          ? timeoutStatus
          : (mode === "relay" && options.releaseGate && isRestrictedUrlError(detail))
            ? "pass"
            : (mode === "relay" && (isExtensionUnavailable(detail) || isRateLimitedError(detail)) ? "env_limited" : "fail"),
        detail: mode === "relay" && options.releaseGate && isRestrictedUrlError(detail)
          ? "verified_expected_restricted_url_gate"
          : ((isTimeoutError(detail) || isAnnotationPendingCompletion(detail)) && options.releaseGate && mode === "relay")
            ? "declared_divergence_boundary_observed: annotation_manual_timeout"
            : detail
      });
    } finally {
      if (sessionId) {
        const closeBrowser = mode === "direct" ? ["--close-browser"] : [];
        runCli(["disconnect", "--session-id", sessionId, ...closeBrowser], { allowFailure: true, env: matrixEnv });
      }
    }
  }

  await runAnnotateProbe("relay");
  await runAnnotateProbe("direct");

  // Real-world scenario pack gate (M23) + throughput floor check (B5)
  const generatedRealWorldArtifactPath = path.join(ROOT, "artifacts", "provider-live-matrix-from-live-regression.json");
  const cachedRealWorldArtifactPath = path.join(ROOT, "artifacts", "provider-live-matrix-full-realworld.json");
  const maxArtifactAgeMs = Number.parseInt(process.env.LIVE_MATRIX_REALWORLD_MAX_AGE_MS ?? "43200000", 10);
  const parseRealWorldArtifact = (artifactPath) => {
    if (!fs.existsSync(artifactPath)) return null;
    try {
      return JSON.parse(fs.readFileSync(artifactPath, "utf-8"));
    } catch {
      return null;
    }
  };
  const extractCounts = (artifact) => ({
    pass: Number.isInteger(artifact?.counts?.pass) ? artifact.counts.pass : 0,
    envLimited: Number.isInteger(artifact?.counts?.env_limited) ? artifact.counts.env_limited : 0,
    fail: Number.isInteger(artifact?.counts?.fail) ? artifact.counts.fail : 0
  });
  const parseFinishedAtMs = (artifact) => {
    const value = artifact?.finishedAt ? Date.parse(String(artifact.finishedAt)) : NaN;
    return Number.isFinite(value) ? value : null;
  };

  try {
    const cachedArtifact = parseRealWorldArtifact(cachedRealWorldArtifactPath);
    const cachedCounts = extractCounts(cachedArtifact);
    const cachedFinishedAtMs = parseFinishedAtMs(cachedArtifact);
    const cachedIsFresh = cachedFinishedAtMs !== null && (Date.now() - cachedFinishedAtMs) <= maxArtifactAgeMs;
    const cachedIsReleaseReady = cachedCounts.fail === 0 && cachedCounts.envLimited === 0 && cachedCounts.pass > 0;

    let realWorldRun = { status: 0, durationMs: 0 };
    let realWorldArtifactPath = cachedRealWorldArtifactPath;
    let artifactSource = "cached_full_realworld";
    let realWorld = cachedArtifact;

    if (!(cachedIsFresh && cachedIsReleaseReady)) {
      realWorldRun = runNode([
        "scripts/provider-live-matrix.mjs",
        "--use-global-env",
        "--skip-live-regression",
        "--out",
        generatedRealWorldArtifactPath
      ], { env: matrixEnv, allowFailure: true, timeoutMs: 1_200_000 });
      realWorldArtifactPath = generatedRealWorldArtifactPath;
      artifactSource = "generated_from_live_matrix";
      realWorld = parseRealWorldArtifact(realWorldArtifactPath);
    }

    const startedAtMs = Number.parseInt(String(realWorld?.startedAt ? Date.parse(String(realWorld.startedAt)) : NaN), 10);
    const finishedAtMs = Number.parseInt(String(realWorld?.finishedAt ? Date.parse(String(realWorld.finishedAt)) : NaN), 10);
    const elapsedMs = Number.isFinite(startedAtMs) && Number.isFinite(finishedAtMs) && finishedAtMs > startedAtMs
      ? finishedAtMs - startedAtMs
      : realWorldRun.durationMs;
    const elapsedMinutes = elapsedMs > 0 ? elapsedMs / 60000 : 0;
    const {
      passCount,
      envLimitedCount,
      failCount,
      requireZeroEnvLimited,
      m23Pass,
      exitStatus
    } = evaluateRealWorldScenarioPack({
      artifact: realWorld,
      runStatus: realWorldRun.status,
      releaseGate: options.releaseGate
    });
    const opsPerMinute = elapsedMinutes > 0 ? Number((passCount / elapsedMinutes).toFixed(2)) : 0;
    const expectedMinOpsPerMinute = 2;
    const floorPass = m23Pass && opsPerMinute >= expectedMinOpsPerMinute;
    const floorFailureDetail = !m23Pass
      ? `Scenario pack did not meet ${requireZeroEnvLimited ? "release" : "non-release"} criteria: pass=${passCount}, env_limited=${envLimitedCount}, fail=${failCount}.`
      : `Scenario throughput below floor: opsPerMinute=${opsPerMinute}, expected>=${expectedMinOpsPerMinute}.`;

    addResult(results, {
      id: "M23.parallel_modes_soak",
      status: m23Pass ? "pass" : "fail",
      detail: m23Pass
        ? "realworld_scenario_pack_pass"
        : `realworld_scenario_pack_failed: status=${exitStatus}, pass=${passCount}, env_limited=${envLimitedCount}, fail=${failCount}`,
      data: {
        mode: "realworld_scenario_pack",
        artifactSource,
        artifactPath: realWorldArtifactPath,
        artifactOk: typeof realWorld?.ok === "boolean" ? realWorld.ok : null,
        exitStatus,
        passCount,
        envLimitedCount,
        failCount,
        elapsedMs,
        opsPerMinute
      }
    });

    addResult(results, {
      id: "B5.governor_floor_throughput",
      status: floorPass ? "pass" : "fail",
      detail: floorPass ? undefined : floorFailureDetail,
      data: {
        mode: "realworld_scenario_pack",
        opsPerMinute,
        expectedMinOpsPerMinute,
        elapsedMs,
        passCount
      }
    });
  } catch (error) {
    const detail = error instanceof Error ? error.message : String(error);
    addResult(results, { id: "M23.parallel_modes_soak", status: "fail", detail });
    addResult(results, { id: "B5.governor_floor_throughput", status: "fail", detail });
  }

  // Matrix completeness gate (B23)
  const requiredMatrixIds = [
    "M1.managed_headed_parallel",
    "M5.cdp_connect_headed_parallel",
    "M6.cdp_connect_headless_parallel",
    "M7.cdp_connect_headed_reconnect_churn",
    "M21.headed_headless_scenario_pack_parity",
    "M23.parallel_modes_soak",
    "M25.extension_headless_unsupported_mode",
    "B5.governor_floor_throughput",
    "mode.extension_headless_unsupported"
  ];
  const resultIds = new Set(results.map((entry) => entry.id));
  const missingMatrixIds = requiredMatrixIds.filter((id) => !resultIds.has(id));
  addResult(results, {
    id: "B23.matrix_completeness_gate",
    status: missingMatrixIds.length === 0 ? "pass" : "fail",
    detail: missingMatrixIds.length === 0 ? undefined : `Missing matrix scenario IDs: ${missingMatrixIds.join(", ")}`,
    data: {
      requiredCount: requiredMatrixIds.length,
      missingCount: missingMatrixIds.length,
      missingIds: missingMatrixIds
    }
  });

  if (shouldStopDaemonAfterRun({ useGlobalEnv })) {
    runCli(["serve", "--stop"], { allowFailure: true, env: matrixEnv });
  }
  if (isolatedRuntime?.tempRoot) {
    try {
      fs.rmSync(isolatedRuntime.tempRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
    } catch {
      // ignore temp cleanup errors
    }
  }
  cleanupOwnedHeadlessResources();

  const summary = summarize(results, startedAt, options);
  const pretty = JSON.stringify(summary, null, 2);
  const artifactDir = path.join(ROOT, "artifacts");
  const artifactPath = path.join(artifactDir, "live-regression-matrix-report.json");
  fs.mkdirSync(artifactDir, { recursive: true });
  fs.writeFileSync(artifactPath, `${pretty}\n`, "utf8");
  if (options.releaseGate) {
    fs.mkdirSync(RELEASE_ARTIFACT_DIR, { recursive: true });
    fs.writeFileSync(path.join(RELEASE_ARTIFACT_DIR, "live-regression-matrix-report.json"), `${pretty}\n`, "utf8");
  }
  console.log(pretty);
  console.error(`[live-matrix] report: ${artifactPath}`);
  if (options.releaseGate) {
    console.error(`[live-matrix] release report: ${path.join(RELEASE_ARTIFACT_DIR, "live-regression-matrix-report.json")}`);
  }
  if (!summary.ok) {
    process.exitCode = 1;
  }
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const cliOptions = parseCliOptions(process.argv.slice(2));

  runMatrix(cliOptions)
    .then(() => {
      flushAndExit();
    })
    .catch((error) => {
      cleanupOwnedHeadlessResources();
      const message = error instanceof Error ? error.message : String(error);
      console.error(JSON.stringify({
        ok: false,
        fatal: message
      }, null, 2));
      process.exitCode = 1;
      flushAndExit();
    });
}
