@backbencher/brain 0.0.0-stage → 0.1.0

package/dist/chunk-4H22TLOT.js

@@ -0,0 +1,543 @@
+// src/ast/pool-diagnostics.ts
+import { fork as forkChild, spawnSync } from "child_process";
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var WORKER_ENTRY_RELATIVE = path.join("src", "ast", "pool-worker.ts");
+var DEFAULT_WORKER_STARTUP_TIMEOUT_MS = 3e4;
+var DISABLED_VALUES = /* @__PURE__ */ new Set(["0", "false", "off", "no", "none"]);
+function poolStartupTimeoutMs(env = process.env) {
+  const raw = env.BB_WORKER_STARTUP_TIMEOUT_MS;
+  if (raw === void 0 || raw === "") return DEFAULT_WORKER_STARTUP_TIMEOUT_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_WORKER_STARTUP_TIMEOUT_MS;
+  return n;
+}
+function npmInstallFix(what) {
+  return [
+    `Install ${what}: \`npm install --include=dev\` in the bb checkout
+tsx is a DEV dependency. A production install (\`npm ci --omit=dev\`, NODE_ENV=production,
+a slim CI image) removes it, and the pool then fails exactly like this \u2014 silently,
+because nothing on the path from "tsx is gone" to "workers don't start" said so.`,
+    "Or run the published build, which needs no tsx at all: `npm i -g @backbencher/brain`"
+  ];
+}
+function reinstallFix() {
+  return [
+    "Reinstall dependencies: `rm -rf node_modules && npm install --include=dev`\nIf that still fails the checkout is incomplete \u2014 `git status` should be clean and\n`src/ast/pool-worker.ts` must exist."
+  ];
+}
+function inProcessOptOut() {
+  return "Or stay in-process (same index, slower): `BB_POOL_WORKER=0 bb index .`";
+}
+function remediationFor(reason, detail) {
+  const workerCommand = `BB_POOL_WORKER=1 ${[detail.workerPath, ...detail.workerArgs ?? []].filter(Boolean).join(" ")}`;
+  switch (reason) {
+    case "pool-disabled-by-env":
+      return [
+        "The pool is off by request, not by failure.\nUnset it to get parallel indexing back: `unset BB_POOL_WORKER`"
+      ];
+    case "runtime-unsupported":
+      return [
+        `bb is running under \`${detail.execPath}\`, which is neither Node nor Bun.
+Run it with Node >= 18 (\`node --version\`) or with Bun. The worker is forked with
+the SAME executable as the parent, so an unrecognised runtime cannot load one:
+answering "I don't know" costs an in-process index, guessing costs that plus a
+failure that explains nothing.`
+      ];
+    case "worker-entry-missing":
+      return [
+        `Compiled worker entry \`${detail.workerPath}\` does not exist \u2014 a partial build, or an
+install whose \`files\` list dropped dist/.`,
+        ...reinstallFix()
+      ];
+    case "tsx-missing":
+      return [...npmInstallFix("tsx, the TypeScript loader the dev worker needs"), inProcessOptOut()];
+    case "tsx-not-runnable":
+      return [
+        `\`${detail.workerPath}\` exists but cannot be executed.
+  \`chmod +x node_modules/.bin/tsx\`
+or reinstall: \`rm -rf node_modules && npm install --include=dev\``,
+        inProcessOptOut()
+      ];
+    case "worker-load-crash":
+      return [
+        // The classified cause leads when stderr gave one. "Rebuild the native
+        // module" and "install tsx" are OPPOSITE fixes, and guessing between
+        // them from a truncated stack would be worse than reporting what the
+        // child actually printed.
+        ...detail.causeRemediation ?? [],
+        detail.stderrTail ? `The worker's own words:
+\`\`\`
+${detail.stderrTail}
+\`\`\`` : "It printed nothing to stderr, so the cause is unknown.",
+        detail.cause ? null : `Or run the worker by hand to see for yourself:
+  \`${workerCommand}\``,
+        inProcessOptOut()
+      ].filter((x) => x !== null);
+    case "worker-exited-silently":
+      return [
+        'The worker exited cleanly WITHOUT sending `ready` \u2014 it never entered worker mode.\nMost often `BB_POOL_WORKER` is not "1" in the child environment: an exported\n`BB_POOL_WORKER=0` reads like a supported "don\'t use the pool" switch, and the\nonly consequence was that every forked worker left instantly.\nUnset it (`unset BB_POOL_WORKER`), or set it to 0 deliberately to index in-process.'
+      ];
+    case "worker-exit-nonzero":
+      return [
+        `Worker exited with code ${detail.exitCode}${detail.signal ? ` (signal ${detail.signal})` : ""} before it was ready.`,
+        detail.stderrTail ? `Its last words:
+\`\`\`
+${detail.stderrTail}
+\`\`\`` : "It printed nothing to stderr.",
+        ...detail.causeRemediation ?? [],
+        `Or re-run with the worker's own logging:
+  \`BB_LOG_LEVEL=debug bb index --force .\``,
+        inProcessOptOut()
+      ];
+    case "worker-startup-timeout":
+      return [
+        `The worker stayed alive but sent no \`ready\` within ${detail.timeoutMs}ms.
+It is loading slowly, or it is hung.`,
+        "Raise the watchdog on a slow machine or a cold cache:\n  `BB_WORKER_STARTUP_TIMEOUT_MS=120000 bb index .`",
+        `Or watch it start by hand:
+  \`${workerCommand}\``,
+        inProcessOptOut()
+      ];
+    case "worker-selftest-unsupported":
+      return [
+        "The installed worker did not answer bb's startup self-test, so bb cannot prove it\nstarts. That is expected for a build older than the self-test; it is NOT a failure\nof the pool.",
+        "Rebuild to get a verifiable worker: `npm run build` (and `npm install --include=dev`\nif you are running from source, where tsx is required)."
+      ];
+    case "fork-unavailable":
+      return [
+        "The operating system refused to fork a worker process.\nCheck for a sandbox ceiling (`ulimit -u`, a container pids limit) and for free\nfile descriptors (`ulimit -n`).",
+        inProcessOptOut()
+      ];
+  }
+}
+function fail(reason, message, detail) {
+  return { ok: false, reason, message, remediation: remediationFor(reason, detail), detail };
+}
+function findOnPath(name, env, exists) {
+  for (const dir of (env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
+    try {
+      if (exists(candidate)) return candidate;
+    } catch {
+    }
+  }
+  return null;
+}
+var MAX_ROOT_WALK = 6;
+function findPackageRoot(fromDir, exists = existsSync) {
+  let dir = path.resolve(fromDir);
+  for (let i = 0; i <= MAX_ROOT_WALK; i++) {
+    try {
+      if (exists(path.join(dir, "package.json"))) return dir;
+    } catch {
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+function looksLikeNode(execPath) {
+  const base = execPath.split(/[\\/]/).pop().toLowerCase().replace(/\.(exe|cmd|bat)$/, "");
+  return /^node(js)?\d*(\.\d+)*$/.test(base);
+}
+function looksLikeBun(execPath) {
+  return execPath.split(/[\\/]/).pop().toLowerCase().includes("bun");
+}
+function resolvePoolWorkerForkSafe(deps = {}) {
+  const env = deps.env ?? process.env;
+  const execPath = deps.execPath ?? process.execPath;
+  const exists = deps.exists ?? existsSync;
+  const moduleDir = deps.moduleDir ?? path.dirname(fileURLToPath(import.meta.url));
+  const baseDetail = {
+    execPath,
+    nodeVersion: deps.version ?? process.version,
+    moduleDir
+  };
+  const requested = (env.BB_POOL_WORKER ?? "").trim().toLowerCase();
+  if (DISABLED_VALUES.has(requested)) {
+    return fail(
+      "pool-disabled-by-env",
+      `pool disabled by BB_POOL_WORKER=${env.BB_POOL_WORKER} (in-process indexing will be used)`,
+      { ...baseDetail, workerArgs: [env.BB_POOL_WORKER ?? ""] }
+    );
+  }
+  const walked = findPackageRoot(moduleDir, exists);
+  const projectRoot = walked ?? path.resolve(moduleDir, "../..");
+  const isCompiled = (moduleDir.endsWith(`${path.sep}dist`) || moduleDir.includes(`${path.sep}dist${path.sep}`)) && !moduleDir.includes(`${path.sep}src${path.sep}`);
+  if (isCompiled) {
+    const candidates = [];
+    let dir = moduleDir;
+    for (let i = 0; i <= MAX_ROOT_WALK; i++) {
+      candidates.push(path.join(dir, "pool-worker.js"));
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    if (walked) candidates.push(path.join(walked, "dist", "pool-worker.js"));
+    const workerPath = candidates.find((p) => exists(p));
+    if (!workerPath) {
+      return fail("worker-entry-missing", `compiled worker entry is missing (tried ${candidates.length} locations)`, {
+        ...baseDetail,
+        projectRoot,
+        workerPath: candidates[0],
+        searchedPaths: candidates
+      });
+    }
+    return { ok: true, workerPath, workerArgs: [], source: "compiled-dist", projectRoot };
+  }
+  const workerEntry = path.join(projectRoot, WORKER_ENTRY_RELATIVE);
+  if (looksLikeNode(execPath)) {
+    const localTsx = path.join(projectRoot, "node_modules", ".bin", "tsx");
+    const localTsxExists = exists(localTsx);
+    const tsxPath = localTsxExists ? localTsx : findOnPath("tsx", env, exists);
+    if (!tsxPath) {
+      return fail(
+        "tsx-missing",
+        `tsx not found: no \`tsx\` in ${localTsx} and none on PATH \u2014 the dev worker cannot be started`,
+        {
+          ...baseDetail,
+          projectRoot,
+          workerPath: workerEntry,
+          searchedPaths: [localTsx, "$PATH"],
+          errorMessage: exists(localTsx) ? "tsx present on PATH but unusable" : void 0
+        }
+      );
+    }
+    return {
+      ok: true,
+      workerPath: tsxPath,
+      workerArgs: [workerEntry],
+      source: localTsxExists ? "tsx-local" : "tsx-path",
+      projectRoot
+    };
+  }
+  if (looksLikeBun(execPath)) {
+    return { ok: true, workerPath: workerEntry, workerArgs: [], source: "bun-native", projectRoot };
+  }
+  return fail(
+    "runtime-unsupported",
+    `cannot fork a worker under \`${execPath}\`: expected a Node or a Bun executable`,
+    { ...baseDetail, projectRoot, workerPath: workerEntry, searchedPaths: [localTsxPath(projectRoot)] }
+  );
+}
+function localTsxPath(projectRoot) {
+  return path.join(projectRoot, "node_modules", ".bin", "tsx");
+}
+function explainWorkerStderr(stderr) {
+  const s = stderr || "";
+  const rebuildNative = [
+    "The native module was built for a different Node ABI or platform. Rebuild it here:",
+    "  `npm rebuild better-sqlite3 --build-from-source`",
+    "or reinstall from scratch: `rm -rf node_modules && npm install --include=dev`"
+  ];
+  if (/NODE_MODULE_VERSION|was compiled against a different Node\.js version/i.test(s)) {
+    return {
+      cause: "native-abi-mismatch",
+      summary: "a native module was compiled against a different Node.js version",
+      remediation: rebuildNative
+    };
+  }
+  if (/ERR_DLOPEN_FAILED|invalid ELF header|wrong architecture|mach-o file, but this architecture|is not a valid Win32 application/i.test(s)) {
+    return {
+      cause: "native-platform-mismatch",
+      summary: "a native module was built for another platform or architecture",
+      remediation: [
+        "This node_modules came from another machine/container. Reinstall here:",
+        "  `rm -rf node_modules && npm install --include=dev`"
+      ]
+    };
+  }
+  if (/ERR_MODULE_NOT_FOUND|Cannot find module|Cannot find package '|Failed to resolve module|Cannot find module '\.\//i.test(s)) {
+    return {
+      cause: "missing-module",
+      summary: "a module in the worker's import graph is not installed",
+      remediation: [
+        "The worker entry exists but one of its imports does not \u2014 a partial install.",
+        "  `rm -rf node_modules && npm install --include=dev`"
+      ]
+    };
+  }
+  if (/SyntaxError: Unexpected token|Cannot use import statement outside a module|Unexpected token 'export'|unknown file extension \.ts/i.test(s)) {
+    return {
+      cause: "typescript-source-run-as-js",
+      summary: "TypeScript source was executed by a runtime that cannot load it (tsx did not apply)",
+      remediation: [
+        "tsx resolved but did not run: the `tsx` on PATH is a shim or a different tool.",
+        "Prefer the local one: `npm install --include=dev` (creates node_modules/.bin/tsx)",
+        "Or run the compiled build, which needs no loader: `npm run build && node dist/cli/index.js index .`"
+      ]
+    };
+  }
+  if (/EACCES|Permission denied/i.test(s)) {
+    return {
+      cause: "permission-denied",
+      summary: "the resolved worker/tsx file is not executable",
+      remediation: [
+        "`chmod +x node_modules/.bin/tsx`",
+        "or reinstall: `rm -rf node_modules && npm install --include=dev`"
+      ]
+    };
+  }
+  if (/ENOMEM|Reached heap limit|heap out of memory|Allocation failed - JavaScript/i.test(s)) {
+    return {
+      cause: "out-of-memory",
+      summary: "the worker ran out of memory during startup",
+      remediation: [
+        "Raise the heap the worker is allowed: `NODE_OPTIONS=--max-old-space-size=4096`",
+        "Fewer workers also helps: lower bb's concurrency or run with fewer cores visible."
+      ]
+    };
+  }
+  if (/ERR_OSSL_EVP_UNSUPPORTED|error:0308010C:digital envelope routines::unsupported|digital envelope routines/i.test(s)) {
+    return {
+      cause: "openssl-legacy-provider",
+      summary: "an OpenSSL 3 / legacy digest incompatibility (old dependency on a modern Node)",
+      remediation: [
+        "Update the offending dependency, or run bb on Node 18 LTS where it still works.",
+        "For webpack-era tools only: `NODE_OPTIONS=--openssl-legacy-provider`"
+      ]
+    };
+  }
+  if (/tsx|ts-node|esbuild/i.test(s) && /throw|error/i.test(s)) {
+    return {
+      cause: "tsx-loader-crash",
+      summary: "the tsx loader itself failed while starting the worker",
+      remediation: [
+        "tsx is installed but broken. Reinstall it:",
+        "  `npm install --include=dev tsx`",
+        "Check the loader version: `node_modules/.bin/tsx --version`"
+      ]
+    };
+  }
+  return {
+    cause: "unclassified",
+    summary: "the worker failed to start for an unrecognised reason",
+    remediation: [
+      "Re-run with the child's own output:",
+      "  `BB_LOG_LEVEL=debug BB_POOL_WORKER=1 node_modules/.bin/tsx src/ast/pool-worker.ts`",
+      "and report the stack above if it persists."
+    ]
+  };
+}
+var CAPTURE_TAIL_BYTES = 8 * 1024;
+var DEFAULT_CAPTURE_LINES = 20;
+var SELFTEST_ENV = "BB_POOL_WORKER_SELFTEST";
+var SELFTEST_MARKER = "[BB-WORKER-SELFTEST]";
+function probePoolWorkerSync(resolution, opts = {}) {
+  if (!resolution.ok) return resolution;
+  const env = opts.env ?? process.env;
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const startedAt = Date.now();
+  let res;
+  try {
+    res = spawnSync(
+      process.execPath,
+      [resolution.workerPath, ...resolution.workerArgs],
+      {
+        env: { ...env, [SELFTEST_ENV]: "1" },
+        encoding: "utf8",
+        timeout: timeoutMs,
+        killSignal: "SIGKILL",
+        maxBuffer: 4 * 1024 * 1024,
+        windowsHide: true
+      }
+    );
+  } catch (e) {
+    return fail("fork-unavailable", `could not start a worker self-test: ${e?.message ?? String(e)}`, {
+      workerPath: resolution.workerPath,
+      workerArgs: resolution.workerArgs,
+      errorMessage: String(e?.message ?? e)
+    });
+  }
+  const ms = Date.now() - startedAt;
+  const stdout = typeof res.stdout === "string" ? res.stdout : "";
+  const stderr = typeof res.stderr === "string" ? res.stderr : "";
+  const stderrTail = stderr.split("\n").map((l) => l.trimEnd()).filter((l) => l.trim().length > 0).slice(-DEFAULT_CAPTURE_LINES).join("\n");
+  if (res.error && res.error.code === "ETIMEDOUT") {
+    const explained2 = stderrTail ? explainWorkerStderr(stderrTail) : null;
+    const attributed2 = explained2 && explained2.cause !== "unclassified" ? explained2 : null;
+    return fail(
+      attributed2 ? "worker-load-crash" : "worker-startup-timeout",
+      attributed2 ? `worker self-test did not finish: ${attributed2.summary}` : `worker self-test did not finish within ${timeoutMs}ms`,
+      {
+        workerPath: resolution.workerPath,
+        workerArgs: resolution.workerArgs,
+        timeoutMs,
+        stderrTail: stderrTail || void 0,
+        ...attributed2 ? { cause: attributed2.cause, causeRemediation: attributed2.remediation } : {}
+      }
+    );
+  }
+  const markerLine = stdout.split("\n").find((l) => l.startsWith(SELFTEST_MARKER));
+  if (markerLine) {
+    let report = null;
+    try {
+      report = JSON.parse(markerLine.slice(SELFTEST_MARKER.length).trim());
+    } catch {
+      report = null;
+    }
+    if (report) {
+      return { ...resolution, ms, report, stderrTail };
+    }
+  }
+  if (res.status === 0 && !stderrTail) {
+    return fail(
+      "worker-selftest-unsupported",
+      "the installed worker did not run bb's startup self-test (it predates it)",
+      { workerPath: resolution.workerPath, workerArgs: resolution.workerArgs, exitCode: 0 }
+    );
+  }
+  const explained = stderrTail ? explainWorkerStderr(stderrTail) : null;
+  const attributed = explained && explained.cause !== "unclassified" ? explained : null;
+  return fail(
+    attributed ? "worker-load-crash" : "worker-exit-nonzero",
+    attributed ? `the worker failed to start: ${attributed.summary}` : `the worker exited with code ${res.status ?? "null"} before reporting a startup result`,
+    {
+      workerPath: resolution.workerPath,
+      workerArgs: resolution.workerArgs,
+      exitCode: res.status ?? null,
+      signal: res.signal ?? null,
+      stderrTail: stderrTail || void 0,
+      ...attributed ? { cause: attributed.cause, causeRemediation: attributed.remediation } : {}
+    }
+  );
+}
+function poolFailureLine(f) {
+  const first = (f.remediation[0] ?? "").split("\n")[0];
+  return `worker pool unavailable [${f.reason}]: ${f.message} \u2014 fix: ${first}`;
+}
+function renderPoolDiagnosis(r) {
+  if (r.ok) {
+    return `worker pool available: fork ${r.workerPath}${r.workerArgs.length ? " " + r.workerArgs.join(" ") : ""} (via ${r.source})`;
+  }
+  const lines = [];
+  lines.push(`worker pool unavailable [${r.reason}]: ${r.message}`);
+  const d = r.detail;
+  const evidence = [];
+  if (d.execPath) evidence.push(`runtime: ${d.execPath}${d.nodeVersion ? ` (${d.nodeVersion})` : ""}`);
+  if (d.projectRoot) evidence.push(`root: ${d.projectRoot}`);
+  if (d.searchedPaths?.length) evidence.push(`looked in: ${d.searchedPaths.join(", ")}`);
+  if (d.workerPath) evidence.push(`worker: ${d.workerPath}${d.workerArgs?.length ? " " + d.workerArgs.join(" ") : ""}`);
+  if (d.exitCode !== void 0) evidence.push(`exit: code=${d.exitCode}${d.signal ? ` signal=${d.signal}` : ""}`);
+  if (d.timeoutMs !== void 0) evidence.push(`timeout: ${d.timeoutMs}ms`);
+  if (evidence.length) lines.push("  " + evidence.join("\n  "));
+  lines.push("  fix:");
+  r.remediation.forEach((fix, i) => {
+    const [first, ...rest] = fix.split("\n");
+    lines.push(`    ${i + 1}. ${first.trim()}`);
+    for (const cont of rest) lines.push(cont.trim() ? `       ${cont.trim()}` : "");
+  });
+  return lines.join("\n");
+}
+function diagnosePoolStartupSync(opts = {}) {
+  const env = opts.env ?? process.env;
+  const findings = [];
+  let resolution;
+  try {
+    resolution = resolvePoolWorkerForkSafe({ moduleDir: opts.moduleDir, env });
+  } catch (e) {
+    const message = String(e?.message ?? e);
+    return {
+      status: "unavailable",
+      resolution: {
+        ok: false,
+        reason: "fork-unavailable",
+        message: `the pool resolver itself failed: ${message}`,
+        remediation: ["This is a bug in bb. Re-run with BB_LOG_LEVEL=debug and report it."],
+        detail: { errorMessage: message }
+      },
+      findings: [
+        {
+          id: "pool-resolver-crashed",
+          severity: "fail",
+          message: `the pool resolver threw: ${message}`,
+          fix: "This is a bug in bb \u2014 please report it with the message above."
+        }
+      ]
+    };
+  }
+  if (!resolution.ok) {
+    const disabled = resolution.reason === "pool-disabled-by-env";
+    findings.push({
+      id: `pool-${resolution.reason}`,
+      severity: disabled ? "info" : "fail",
+      message: renderPoolDiagnosis(resolution),
+      fix: resolution.remediation[0]
+    });
+    return { status: disabled ? "disabled" : "unavailable", resolution, findings };
+  }
+  const target = resolution.source === "compiled-dist" ? `the compiled worker (${resolution.workerPath})` : `tsx + TypeScript source (${resolution.workerPath} ${resolution.workerArgs.join(" ")})`;
+  findings.push({
+    id: "pool-target",
+    severity: "info",
+    message: `Pool workers fork ${target}
+  runtime: ${process.execPath} (${process.version})
+  root: ${resolution.projectRoot}`
+  });
+  if (opts.probe === false) return { status: "ok", resolution, findings };
+  let probe;
+  try {
+    probe = probePoolWorkerSync(resolution, { env, timeoutMs: opts.timeoutMs });
+  } catch (e) {
+    findings.push({
+      id: "pool-selftest-crashed",
+      severity: "warn",
+      message: `the worker self-test could not be run: ${String(e?.message ?? e)}`,
+      fix: "Re-run with BB_LOG_LEVEL=debug; if this repeats it is a bug in bb."
+    });
+    return { status: "ok", resolution, findings };
+  }
+  if (!probe.ok) {
+    const unverifiable = probe.reason === "worker-selftest-unsupported";
+    findings.push({
+      id: `pool-${probe.reason}`,
+      severity: unverifiable ? "warn" : "fail",
+      message: renderPoolDiagnosis(probe),
+      fix: probe.remediation[0]
+    });
+    return { status: unverifiable ? "ok" : "unavailable", resolution, probe, findings };
+  }
+  const r = probe.report;
+  if (r.engine === "unavailable") {
+    findings.push({
+      id: "pool-engine-unavailable",
+      severity: "warn",
+      message: `Pool workers START, but the AST engine did not load, so every file is parsed by regex
+extraction instead of its grammar. Indexing succeeds and returns FEWER symbols than a
+healthy run \u2014 which reads as "bb works" and is not.
+  worker said: ${r.diagnostics.join(" | ") || "(no detail)"}`,
+      fix: "npm rebuild --build-from-source && rm -rf node_modules && npm install --include=dev"
+    });
+  }
+  if (r.wasm === "unavailable") {
+    findings.push({
+      id: "pool-wasm-unavailable",
+      severity: "warn",
+      message: `Pool workers START, but the tree-sitter wasm registry did not load. Grammar-based
+parsing is unavailable; files still index through the regex fallback.
+  worker said: ${r.diagnostics.join(" | ") || "(no detail)"}`,
+      fix: "Check the grammars shipped with your install: `ls wasm | head`"
+    });
+  }
+  if (r.engine === "ok" && r.wasm === "ok") {
+    findings.push({
+      id: "pool-verified",
+      severity: "info",
+      message: `A pool worker started and loaded the engine and the grammars in ${probe.ms}ms (pid ${r.pid}, ${r.node}).`
+    });
+  }
+  const status = r.engine === "ok" && r.wasm === "ok" ? "ok" : "degraded";
+  return { status, resolution, probe, findings };
+}
+
+export {
+  poolStartupTimeoutMs,
+  findPackageRoot,
+  resolvePoolWorkerForkSafe,
+  poolFailureLine,
+  diagnosePoolStartupSync
+};