@sanqianx/project-knowledge 5.0.24 → 5.0.25

package/_site/_test/harness-isolation-test.js

@@ -0,0 +1,138 @@
+'use strict';
+// F-ENV-LEAK-001 canonical regression: a unit test and the suite runner are
+// decided by their own fixtures, never by ambient module URLs or an ambient
+// KB_KNOWLEDGE_DATA_DIR inherited from the developer shell. The read-only
+// sentinel below stands in for the user's live instance: it records every
+// request, so a leak is observable WITHOUT ever contacting a real instance,
+// and it refuses every binding as foreign — exactly the protective 409 the
+// real instance gave, which must surface, never be swallowed.
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+const { spawn } = require('node:child_process');
+const { StorageLayout } = require('../lib/storage-layout');
+const { EngineKnowledgeClient } = require('../lib/engine-knowledge-client');
+
+const MODULE_URL_VARS = ['KB_KNOWLEDGE_ENGINE_URL', 'KB_VECTORHUB_URL', 'KB_TERMINAL_URL', 'KB_EVENTBRIDGE_URL'];
+const REPO = path.resolve(__dirname, '..', '..');
+
+// The sentinel lives in THIS process, so children must be spawned
+// asynchronously: a synchronous spawn would freeze the event loop and the
+// sentinel could never answer (the leak-probe child would just time out).
+function run(file, args, options, timeoutMs) {
+  return new Promise(resolve => {
+    const child = spawn(file, args, { ...options, windowsHide: true });
+    let out = '', err = '';
+    child.stdout.on('data', b => { out += b; }); child.stderr.on('data', b => { err += b; });
+    const timer = setTimeout(() => { child.kill(); resolve({ status: null, timedOut: true, out, err }); }, timeoutMs);
+    child.once('error', error => { clearTimeout(timer); resolve({ status: null, error, out, err }); });
+    child.once('close', status => { clearTimeout(timer); resolve({ status, out, err }); });
+  });
+}
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-isolation-'));
+  const sentinelHits = [];
+  const sentinel = http.createServer((req, res) => {
+    sentinelHits.push(req.url);
+    res.setHeader('Content-Type', 'application/json');
+    if (req.url === '/api/health') return res.end(JSON.stringify({ name: 'knowledge-engine', dataSchemaVersion: 3 }));
+    if (req.url === '/api/projects') return res.end(JSON.stringify({ projects: [{ projectId: 'foreign', repoPath: path.join(root, 'foreign-repo'), knowledgePath: path.join(root, 'foreign-knowledge'), enabled: true }] }));
+    res.statusCode = 409;
+    res.end(JSON.stringify({ ok: false, error: { code: 'ENGINE_IDENTITY_MISMATCH' } }));
+  });
+  await new Promise(resolve => sentinel.listen(0, '127.0.0.1', resolve));
+  const sentinelUrl = `http://127.0.0.1:${sentinel.address().port}`;
+  const decoySite = path.join(root, 'decoy-site-data'), decoyKnowledge = path.join(root, 'decoy-knowledge-data');
+  fs.mkdirSync(decoySite); fs.mkdirSync(decoyKnowledge);
+  const polluted = {
+    ...process.env,
+    KB_KNOWLEDGE_ENGINE_URL: sentinelUrl, KB_VECTORHUB_URL: sentinelUrl, KB_TERMINAL_URL: sentinelUrl, KB_EVENTBRIDGE_URL: sentinelUrl,
+    KB_DATA_DIR: decoySite, KB_KNOWLEDGE_DATA_DIR: decoyKnowledge,
+  };
+  try {
+    // 1. Detector control: a client built WITHOUT an explicit engineUrl
+    //    under the polluted env does reach the ambient address, and the
+    //    identity guard refuses the foreign binding out loud.
+    const leakProbe = path.join(root, 'leak-probe.js');
+    fs.writeFileSync(leakProbe, `'use strict';
+const { StorageLayout } = require(${JSON.stringify(path.resolve(__dirname, '../lib/storage-layout'))});
+const { EngineKnowledgeClient } = require(${JSON.stringify(path.resolve(__dirname, '../lib/engine-knowledge-client'))});
+(async () => {
+  const layout = new StorageLayout({ dataDir: process.env.KB_DATA_DIR });
+  const client = new EngineKnowledgeClient({ layout });
+  try {
+    await client.request('search', { query: 'probe' }, { projectId: 'foreign', repoPath: process.env.KB_DATA_DIR, knowledgePath: process.env.KB_DATA_DIR });
+  } catch (error) {
+    if (error.code !== 'ENGINE_IDENTITY_MISMATCH' || error.status !== 409) throw error;
+    console.log('LEAK_REJECTED_ENGINE_IDENTITY_MISMATCH');
+    return;
+  }
+  throw new Error('the sentinel must refuse the foreign binding');
+})().catch(error => { console.error(error); process.exit(1); });
+`);
+    const leak = await run(process.execPath, [leakProbe], { env: polluted }, 30000);
+    assert.equal(leak.status, 0, `detector control must fail loudly if broken: ${leak.err}`);
+    assert.match(leak.out, /LEAK_REJECTED_ENGINE_IDENTITY_MISMATCH/);
+    assert.ok(sentinelHits.length >= 1, 'the detector control must observe the leaked request');
+    const hitsAfterControl = sentinelHits.length;
+
+    // 2. The fixed canonical test under the same polluted env passes and
+    //    sends not a single request to the ambient address.
+    const canonical = await run(process.execPath, [path.resolve(__dirname, 'knowledge-engine-client-test.js')], { env: polluted }, 120000);
+    assert.equal(canonical.status, 0, `canonical test must pass under a polluted environment: ${canonical.err}`);
+    assert.equal(sentinelHits.length, hitsAfterControl, 'the canonical test must not contact an ambient module address');
+
+    // 3. The runner scrubs its children: exclusive probe dir with the real
+    //    (fixed) run-all-tests.js and one env-dump test file. The child of
+    //    the runner must see no ambient module URL, must NOT see the decoy
+    //    KB data dirs, and must get its own sandboxes instead.
+    const probeOut = path.join(root, 'probe-env.json');
+    const runnerDir = path.join(root, 'runner-probe', '_site', '_test');
+    fs.mkdirSync(runnerDir, { recursive: true });
+    fs.copyFileSync(path.resolve(__dirname, 'run-all-tests.js'), path.join(runnerDir, 'run-all-tests.js'));
+    fs.writeFileSync(path.join(runnerDir, 'zz-env-probe-test.js'), `'use strict';
+const fs = require('node:fs');
+fs.writeFileSync(process.env.PROBE_OUT, JSON.stringify({
+  ${MODULE_URL_VARS.map(name => `${name}: process.env.${name}`).join(', ')},
+  KB_DATA_DIR: process.env.KB_DATA_DIR,
+  KB_KNOWLEDGE_DATA_DIR: process.env.KB_KNOWLEDGE_DATA_DIR,
+  AI_CODING_EVENT_BRIDGE_HOME: process.env.AI_CODING_EVENT_BRIDGE_HOME,
+  KB_MODULES_AUTOSTART: process.env.KB_MODULES_AUTOSTART,
+}));
+`);
+    const runner = await run(process.execPath, [path.join(runnerDir, 'run-all-tests.js'), '--no-report'], {
+      cwd: REPO, env: { ...polluted, PROBE_OUT: probeOut },
+    }, 120000);
+    assert.equal(runner.status, 0, `runner probe must pass: ${runner.err}`);
+    assert.match(runner.out, /1 passed, 0 failed/);
+    const seen = JSON.parse(fs.readFileSync(probeOut, 'utf8'));
+    for (const name of MODULE_URL_VARS) assert.equal(seen[name], undefined, `runner children must not inherit ${name}`);
+    assert.notEqual(seen.KB_DATA_DIR, decoySite, 'runner children must not inherit the ambient site data dir');
+    assert.notEqual(seen.KB_KNOWLEDGE_DATA_DIR, decoyKnowledge, 'runner children must not inherit the ambient knowledge data dir');
+    assert.ok(seen.KB_DATA_DIR && seen.KB_DATA_DIR.includes('kb-runall-data-'), 'site data must be a per-run sandbox');
+    assert.ok(seen.KB_KNOWLEDGE_DATA_DIR && seen.KB_KNOWLEDGE_DATA_DIR.includes('kb-runall-knowledge-'), 'knowledge data must be a per-run sandbox');
+    assert.ok(seen.AI_CODING_EVENT_BRIDGE_HOME, 'bridge home must stay sandboxed');
+    assert.equal(seen.KB_MODULES_AUTOSTART, '0', 'module autostart must stay disabled');
+    assert.equal(sentinelHits.length, hitsAfterControl, 'the runner child must not contact an ambient module address');
+
+    // 4. Deliberate configuration is untouched: an explicit engineUrl still
+    //    aims the client at the chosen address — proven by the sentinel hits
+    //    this final control produces on purpose.
+    const layout = new StorageLayout({ dataDir: path.join(root, 'site-data') });
+    const deliberate = new EngineKnowledgeClient({ layout, engineUrl: sentinelUrl });
+    await assert.rejects(
+      deliberate.request('search', { query: 'probe' }, { projectId: 'foreign', repoPath: path.join(root, 'site-repo'), knowledgePath: path.join(root, 'site-knowledge') }),
+      error => error.code === 'ENGINE_IDENTITY_MISMATCH' && error.status === 409,
+      'an explicitly configured client still gets the identity refusal surfaced, never swallowed',
+    );
+    assert.ok(sentinelHits.length > hitsAfterControl, 'the deliberate configuration must actually reach its target');
+    console.log('harness-isolation-test PASS (ambient module URLs and data dirs cannot decide tests; deliberate config and identity refusals stay loud)');
+  } finally {
+    sentinel.closeAllConnections();
+    await new Promise(resolve => sentinel.close(resolve));
+    fs.rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/helpers/cdp-browser.js

@@ -0,0 +1,383 @@
+const fs = require('fs');
+const http = require('http');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+const WebSocket = require('ws');
+
+const MAX_STREAM_TAIL_BYTES = 32 * 1024;
+const DEFAULT_HTTP_TIMEOUT_MS = 1000;
+// Hosted-runner cold starts (first Chrome launch of a suite, antivirus scan,
+// dbus stalls) can exceed a single budget window; launch stalls are transient,
+// so retry instead of failing the whole test run.
+const DEFAULT_LAUNCH_TIMEOUT_MS = Number(process.env.KB_CDP_LAUNCH_TIMEOUT_MS || 30000);
+const DEFAULT_LAUNCH_ATTEMPTS = Math.max(1, Number(process.env.KB_CDP_LAUNCH_ATTEMPTS || 3));
+
+function wait(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function waitFor(fn, label, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const result = await fn();
+      if (result) return result;
+    } catch (error) {
+      if (error && error.fatal) throw error;
+      lastError = error;
+    }
+    await wait(100);
+  }
+  throw new Error("Timed out waiting for " + label + (lastError ? ": " + lastError.message : ""));
+}
+
+function requestJson(url, timeoutMs = DEFAULT_HTTP_TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const request = http.get(url, response => {
+      let body = "";
+      response.setEncoding("utf8");
+      response.on("data", chunk => { body += chunk; });
+      response.on("end", () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        try { resolve(JSON.parse(body)); }
+        catch (error) { reject(error); }
+      });
+    });
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      const error = new Error("HTTP request timed out after " + timeoutMs + "ms: " + url);
+      error.code = "ETIMEDOUT";
+      request.destroy(error);
+      reject(error);
+    }, timeoutMs);
+    request.on("error", error => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+function createBoundedTail(maxBytes = MAX_STREAM_TAIL_BYTES) {
+  let buffer = Buffer.alloc(0);
+  return {
+    push(chunk) {
+      const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+      if (buffer.length + data.length <= maxBytes) {
+        buffer = Buffer.concat([buffer, data]);
+      } else {
+        buffer = Buffer.concat([buffer.slice(buffer.length + data.length - maxBytes), data]);
+      }
+    },
+    text() { return buffer.toString("utf8"); },
+  };
+}
+
+function hasExited(child) {
+  return !child || child.exitCode !== null || child.signalCode !== null;
+}
+
+function isWindowsChromeLauncher(executable) {
+  if (process.platform !== "win32") return false;
+  return /(?:chrome|msedge)\.exe$/i.test(path.basename(String(executable || "")));
+}
+
+function platformLaunchArgs(platform = process.platform) {
+  // GitHub Linux runners occasionally leave Chrome alive without publishing
+  // DevToolsActivePort when its sandbox or shared-memory backing stalls.
+  // These flags are scoped to isolated, disposable test browsers only.
+  return platform === 'linux' ? ['--disable-dev-shm-usage', '--no-sandbox'] : [];
+}
+
+function waitForExit(child, timeoutMs = 3000) {
+  if (hasExited(child)) return Promise.resolve();
+  return new Promise(resolve => {
+    const finish = () => { clearTimeout(timer); resolve(); };
+    const timer = setTimeout(finish, timeoutMs);
+    child.once("exit", finish);
+  });
+}
+
+function terminateProfileProcesses(profileDir) {
+  if (process.platform !== "win32" || !profileDir) return;
+  const command = "$profile = $env:PK_CDP_PROFILE; "
+    + "Get-CimInstance Win32_Process -Filter \"Name = 'chrome.exe' OR Name = 'msedge.exe'\" "
+    + "| Where-Object { $_.CommandLine -and $_.CommandLine.IndexOf($profile, [System.StringComparison]::OrdinalIgnoreCase) -ge 0 } "
+    + "| ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }";
+  try {
+    spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], {
+      stdio: "ignore",
+      timeout: 10000,
+      windowsHide: true,
+      env: { ...process.env, PK_CDP_PROFILE: profileDir },
+    });
+  } catch {}
+}
+
+async function terminateProcessTree(child, profileDir) {
+  if (!hasExited(child) && process.platform === "win32" && child.pid) {
+    try {
+      spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", timeout: 10000 });
+    } catch {}
+  }
+  if (!hasExited(child)) {
+    try { child.kill(); } catch {}
+    await waitForExit(child, 3000);
+  }
+  // Windows Chrome/Edge can detach from the launcher process. Clean those
+  // launchers by their unique profile, but do not pay for a machine-wide CIM
+  // scan when a non-browser failure fixture (for example node.exe) exited.
+  if (child && isWindowsChromeLauncher(child.spawnfile)) terminateProfileProcesses(profileDir);
+}
+
+function removeProfileDir(profileDir) {
+  try {
+    fs.rmSync(profileDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  } catch {}
+  return !fs.existsSync(profileDir);
+}
+
+async function cleanupSpawnedBrowser(child, profileDir) {
+  try {
+    await terminateProcessTree(child, profileDir);
+  } catch {}
+  if (profileDir) removeProfileDir(profileDir);
+}
+
+function enrichBrowserLaunchError(error, diagnostics) {
+  const parts = ["Failed to launch CDP browser: " + (error && error.message ? error.message : String(error))];
+  if (diagnostics.executable) parts.push("executable: " + diagnostics.executable);
+  if (diagnostics.pid) parts.push("pid: " + diagnostics.pid);
+  if (diagnostics.exitCode !== null && diagnostics.exitCode !== undefined) parts.push("exit code: " + diagnostics.exitCode);
+  if (diagnostics.signal) parts.push("signal: " + diagnostics.signal);
+  if (diagnostics.spawnError) parts.push("spawn error: " + diagnostics.spawnError);
+  if (diagnostics.profileDir) parts.push("user-data-dir: " + diagnostics.profileDir);
+  const stderrTail = String(diagnostics.stderrTail || "").trim();
+  const stdoutTail = String(diagnostics.stdoutTail || "").trim();
+  if (stderrTail) parts.push("stderr tail:\n" + stderrTail);
+  if (stdoutTail) parts.push("stdout tail:\n" + stdoutTail);
+  const enriched = new Error(parts.filter(Boolean).join("\n"));
+  if (error) {
+    enriched.cause = error;
+    if (error.code) enriched.code = error.code;
+    if (error.fatal) enriched.fatal = true;
+  }
+  enriched.diagnostics = diagnostics;
+  return enriched;
+}
+
+function describeEarlyExit(exitInfo, spawnError) {
+  if (spawnError) return "browser process failed to start: " + spawnError;
+  const code = exitInfo && exitInfo.code !== null && exitInfo.code !== undefined ? String(exitInfo.code) : "unknown";
+  const signal = exitInfo && exitInfo.signal ? " (signal " + exitInfo.signal + ")" : "";
+  return "browser exited before exposing CDP (exit code " + code + signal + ")";
+}
+
+async function waitForDevToolsPort(profileDir, state, timeoutMs, tolerateLauncherExit) {
+  const portFile = path.join(profileDir, "DevToolsActivePort");
+  return waitFor(() => {
+    let text;
+    try { text = fs.readFileSync(portFile, "utf8"); } catch {}
+    const port = Number.parseInt(String(text || "").split(/\r?\n/, 1)[0], 10);
+    if (Number.isInteger(port) && port > 0) return port;
+    if (state.exited && !tolerateLauncherExit) {
+      const error = new Error(describeEarlyExit(state.exitInfo, state.spawnError));
+      error.fatal = true;
+      throw error;
+    }
+    return null;
+  }, "DevToolsActivePort file", timeoutMs);
+}
+
+async function launchBrowserAttempt(options) {
+  const chrome = options.chrome;
+  const profileDir = path.resolve(options.profileDir);
+  const launchTimeoutMs = Number(options.launchTimeoutMs || DEFAULT_LAUNCH_TIMEOUT_MS);
+  const explicitPort = Number(options.debugPort) > 0 ? Number(options.debugPort) : 0;
+  const prependArgs = Array.isArray(options.prependArgs) ? options.prependArgs : [];
+  const tolerateLauncherExit = isWindowsChromeLauncher(chrome);
+
+  removeProfileDir(profileDir);
+  fs.mkdirSync(profileDir, { recursive: true });
+
+  const stdoutTail = createBoundedTail();
+  const stderrTail = createBoundedTail();
+  const state = { exited: false, exitInfo: null, spawnError: null };
+  const diagnostics = {
+    executable: chrome,
+    pid: null,
+    exitCode: null,
+    signal: null,
+    spawnError: null,
+    profileDir,
+    stdoutTail: "",
+    stderrTail: "",
+  };
+
+  let child = null;
+  let socket = null;
+
+  const failLaunch = async (error) => {
+    diagnostics.stdoutTail = stdoutTail.text();
+    diagnostics.stderrTail = stderrTail.text();
+    if (state.exitInfo) {
+      diagnostics.exitCode = state.exitInfo.code;
+      diagnostics.signal = state.exitInfo.signal;
+    }
+    if (state.spawnError) diagnostics.spawnError = state.spawnError;
+    if (socket) { try { socket.close(); } catch {} }
+    await cleanupSpawnedBrowser(child, profileDir);
+    throw enrichBrowserLaunchError(error, diagnostics);
+  };
+
+  try {
+    child = spawn(chrome, [
+      ...prependArgs,
+      ...platformLaunchArgs(),
+      "--headless=new",
+      "--disable-gpu",
+      "--disable-background-networking",
+      "--disable-default-apps",
+      "--disable-extensions",
+      "--no-first-run",
+      "--no-default-browser-check",
+      "--remote-debugging-port=" + explicitPort,
+      "--user-data-dir=" + profileDir,
+      "--window-size=" + Number(options.width || 1360) + "," + Number(options.height || 900),
+      "about:blank",
+    ], {
+      stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
+      ...(options.env ? { env: options.env } : {}),
+    });
+    diagnostics.pid = child.pid;
+
+    child.stdout.on("data", chunk => stdoutTail.push(chunk));
+    child.stderr.on("data", chunk => stderrTail.push(chunk));
+    child.on("error", error => {
+      state.exited = true;
+      state.spawnError = error && error.message ? error.message : String(error);
+      if (!state.exitInfo) state.exitInfo = { code: null, signal: null };
+    });
+    child.on("exit", (code, signal) => {
+      state.exited = true;
+      state.exitInfo = { code, signal };
+    });
+
+    const debugPort = explicitPort || await waitForDevToolsPort(profileDir, state, launchTimeoutMs, tolerateLauncherExit);
+
+    const pages = await waitFor(() => {
+      if (state.exited && !tolerateLauncherExit) {
+        const error = new Error(describeEarlyExit(state.exitInfo, state.spawnError));
+        error.fatal = true;
+        throw error;
+      }
+      return requestJson("http://127.0.0.1:" + debugPort + "/json").then(items => {
+        const available = items.filter(item => item.type === "page");
+        return available.length ? available : null;
+      });
+    }, "Chrome debugging page (port " + debugPort + ")", launchTimeoutMs);
+    const page = pages[0];
+    socket = new WebSocket(page.webSocketDebuggerUrl);
+    await new Promise((resolve, reject) => {
+      socket.once("open", resolve);
+      socket.once("error", reject);
+    });
+
+    let nextId = 1;
+    const pending = new Map();
+    const exceptions = [];
+    const consoleErrors = [];
+    socket.on("message", raw => {
+      const message = JSON.parse(String(raw));
+      if (message.method === "Runtime.exceptionThrown") exceptions.push(message.params);
+      if (message.method === "Log.entryAdded" && message.params && message.params.entry && message.params.entry.level === "error") {
+        consoleErrors.push(message.params.entry);
+      }
+      if (!message.id || !pending.has(message.id)) return;
+      const callbacks = pending.get(message.id);
+      pending.delete(message.id);
+      if (message.error) callbacks.reject(new Error(message.error.message));
+      else callbacks.resolve(message.result || {});
+    });
+
+    function send(method, params) {
+      return new Promise((resolve, reject) => {
+        const id = nextId++;
+        pending.set(id, { resolve, reject });
+        socket.send(JSON.stringify({ id, method, params: params || {} }));
+      });
+    }
+
+    async function evaluate(expression) {
+      const result = await send("Runtime.evaluate", {
+        expression,
+        awaitPromise: true,
+        returnByValue: true,
+        userGesture: true,
+      });
+      if (result.exceptionDetails) {
+        const detail = result.exceptionDetails.exception && result.exceptionDetails.exception.description;
+        throw new Error(detail || result.exceptionDetails.text || "Browser evaluation failed");
+      }
+      return result.result ? result.result.value : undefined;
+    }
+
+    await send("Page.enable");
+    await send("Runtime.enable");
+    await send("Log.enable");
+    await send("Page.navigate", { url: options.url });
+    await waitFor(() => evaluate("document.readyState === 'complete'"), "page load");
+
+    async function screenshot(filePath) {
+      const result = await send("Page.captureScreenshot", { format: "png", fromSurface: true, captureBeyondViewport: false });
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, Buffer.from(result.data, "base64"));
+    }
+
+    async function setViewport(width, height, deviceScaleFactor = 1) {
+      await send("Emulation.setDeviceMetricsOverride", {
+        width,
+        height,
+        deviceScaleFactor,
+        mobile: width < 620,
+        screenWidth: width,
+        screenHeight: height,
+      });
+    }
+
+    async function close() {
+      try { socket.close(); } catch {}
+      await terminateProcessTree(child, profileDir);
+      removeProfileDir(profileDir);
+    }
+
+    return { child, socket, send, evaluate, screenshot, setViewport, exceptions, consoleErrors, close };
+  } catch (error) {
+    await failLaunch(error);
+  }
+}
+
+async function launchCdpBrowser(options) {
+  const attempts = Math.max(1, Number(options.launchAttempts || DEFAULT_LAUNCH_ATTEMPTS));
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await launchBrowserAttempt(options);
+    } catch (error) {
+      lastError = error;
+      // Fatal failures (missing executable, deterministic early crash) never
+      // recover; only transient launch stalls get another attempt.
+      if (error && error.fatal) throw error;
+      if (attempt < attempts) console.log(`[cdp-browser] launch attempt ${attempt}/${attempts} failed (${String(error && error.message).split("\n")[0]}); retrying`);
+    }
+  }
+  throw lastError;
+}
+
+module.exports = { isWindowsChromeLauncher, platformLaunchArgs, launchCdpBrowser, requestJson, waitFor, wait };

package/_site/_test/helpers/cdp-network-capture.js

@@ -0,0 +1,66 @@
+'use strict';
+// Records what the real UI actually sent and received over HTTP.
+//
+// The import id and the per-module wiring payload are decided by the running
+// product, so reading the UI source cannot stand in for this evidence: the
+// captured request body proves which import id travelled with the request,
+// and the captured response body proves which statuses the product reported.
+
+function parseJson(text) {
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+function attachNetworkCapture(browser) {
+  const requests = [];
+  const byId = new Map();
+  const onMessage = raw => {
+    let message;
+    try { message = JSON.parse(String(raw)); } catch { return; }
+    const params = message.params || {};
+    if (message.method === 'Network.requestWillBeSent') {
+      const request = params.request || {};
+      const entry = {
+        id: params.requestId,
+        method: request.method,
+        url: request.url,
+        postData: request.postData || '',
+        body: parseJson(request.postData),
+        status: null,
+      };
+      requests.push(entry);
+      byId.set(params.requestId, entry);
+      return;
+    }
+    if (message.method === 'Network.responseReceived' && byId.has(params.requestId)) {
+      const response = params.response || {};
+      byId.get(params.requestId).status = response.status === undefined ? null : response.status;
+    }
+  };
+  browser.socket.on('message', onMessage);
+
+  return {
+    requests,
+    async enable() { await browser.send('Network.enable'); },
+    find(predicate) { return requests.filter(predicate); },
+    lastApi(method, pathname) {
+      const matches = requests.filter(entry => entry.method === method && entry.url.includes(pathname));
+      return matches.length ? matches[matches.length - 1] : null;
+    },
+    async body(entry) {
+      if (!entry) return null;
+      for (let attempt = 0; attempt < 20; attempt += 1) {
+        try {
+          const result = await browser.send('Network.getResponseBody', { requestId: entry.id });
+          return parseJson(result.body);
+        } catch {
+          await new Promise(resolve => setTimeout(resolve, 100));
+        }
+      }
+      return null;
+    },
+    detach() { browser.socket.off('message', onMessage); },
+  };
+}
+
+module.exports = { attachNetworkCapture };

package/_site/_test/helpers/find-chrome.js

@@ -0,0 +1,34 @@
+const fs = require('fs');
+const path = require('path');
+
+function buildCandidates() {
+  return [
+    ['env', process.env.KB_CHROME_PATH],
+    ['chrome-localappdata', process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'Google', 'Chrome', 'Application', 'chrome.exe')],
+    ['chrome-programfiles', process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, 'Google', 'Chrome', 'Application', 'chrome.exe')],
+    ['chrome-programfiles-x86', process.env['PROGRAMFILES(X86)'] && path.join(process.env['PROGRAMFILES(X86)'], 'Google', 'Chrome', 'Application', 'chrome.exe')],
+    ['edge-programfiles', process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, 'Microsoft', 'Edge', 'Application', 'msedge.exe')],
+    ['edge-programfiles-x86', process.env['PROGRAMFILES(X86)'] && path.join(process.env['PROGRAMFILES(X86)'], 'Microsoft', 'Edge', 'Application', 'msedge.exe')],
+    ['linux-google-chrome', '/usr/bin/google-chrome'],
+    ['linux-google-chrome-stable', '/usr/bin/google-chrome-stable'],
+    ['linux-chromium', '/usr/bin/chromium'],
+    ['linux-chromium-browser', '/usr/bin/chromium-browser'],
+    ['macos-chrome', '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'],
+  ].filter(entry => entry[1]);
+}
+
+function findChromeDetailed() {
+  const candidates = buildCandidates();
+  for (const [source, candidate] of candidates) {
+    if (fs.existsSync(candidate)) return { path: candidate, source };
+  }
+  const error = new Error(`Chrome/Chromium not found; checked: ${candidates.map(entry => entry[1]).join(', ')}`);
+  error.code = 'KB_CHROME_NOT_FOUND';
+  throw error;
+}
+
+function findChrome() {
+  return findChromeDetailed().path;
+}
+
+module.exports = { findChrome, findChromeDetailed };

package/_site/_test/helpers/free-port.js

@@ -0,0 +1,8 @@
+const net = require('node:net');
+module.exports = async function freePort() {
+  const probe = net.createServer();
+  await new Promise((resolve, reject) => { probe.once('error', reject); probe.listen(0, '127.0.0.1', resolve); });
+  const port = probe.address().port;
+  await new Promise(resolve => probe.close(resolve));
+  return port;
+};