@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-wiki-devin/scripts/lib/bounded-child.mjs

@@ -0,0 +1,159 @@
+/**
+ * bounded-child — the plugin payload's child-start deadline.
+ *
+ * @remarks
+ * ## Why this exists separately from `scripts/lib/bounded-spawn.mjs`
+ *
+ * Same property, different reach. A plugin payload cannot import from
+ * `scripts/lib/`: the built plugin is a self-contained copy of
+ * `plugins/src/<name>/`, and nothing outside that tree exists at runtime. So the
+ * rule is written out here rather than pointed at — the accommodation
+ * `threshold-ratchet.mjs` and `preflight-secrets.mjs` already make for their
+ * entry guards.
+ *
+ * It is a MODULE rather than 28 inline copies because the fanout preserves
+ * relative imports. Measured in the built output, not assumed:
+ * `plugins/lisa/skills/lisa-setup-workstation/scripts/catalogue.mjs` exists and
+ * is imported as `../../lisa-setup-workstation/scripts/catalogue.mjs` from a
+ * sibling skill. The build copies the plugin tree wholesale, so a path that
+ * resolves in `plugins/src/base/` resolves in all five copies.
+ *
+ * That distinction matters because the accommodation above is narrower than its
+ * wording suggests. `threshold-ratchet.mjs` cannot import a sibling because it
+ * is **materialized into other lanes** — `typescript/`, `rails/` — where the
+ * sibling does not exist at the destination. A file that lives only in this
+ * plugin has no such problem.
+ *
+ * ## The one thing a deadline alone does not fix
+ *
+ * `spawnSync` does not throw when it kills a child. It returns:
+ *
+ * | outcome | `.code` | `.status` | `.signal` | streams |
+ * | --- | --- | --- | --- | --- |
+ * | killed at deadline | `"ETIMEDOUT"` | `null` | `"SIGKILL"` | **empty** |
+ * | ran, exited non-zero | *(absent)* | `3` | `null` | real |
+ * | binary not found | `"ENOENT"` | `null` | `null` | empty |
+ *
+ * So the shape that appears all over this tree —
+ *
+ * ```js
+ * return result.status === 0 ? result.stdout : null;
+ * ```
+ *
+ * — takes the benign branch for a killed child exactly as it does for a program
+ * that ran and said no. **Adding `timeout:` gives such a call site a deadline
+ * and changes nothing about its verdict.** There is no `catch` to fix, because
+ * the fail-open is in the conditional.
+ *
+ * That is why `boundedChild` THROWS rather than returning a flag: a caller that
+ * does nothing inherits fail-closed behaviour, and only one that deliberately
+ * catches can proceed.
+ * ## Why it lives in THIS skill's directory
+ *
+ * It is not about workstation setup, and it is here anyway, for a measured
+ * reason. The built Codex artifact — `plugins/lisa/.codex-plugin/` — copies
+ * `skills/` and nothing else: no `scripts/`, `agents/`, `commands/` or
+ * `rules/`. So a skill script importing `../../../scripts/lib/…` resolves to a
+ * path that does not exist in that copy, while `../../<skill>/scripts/…`
+ * resolves everywhere, which is exactly why `catalogue.mjs` beside this file is
+ * already imported that way from a sibling skill.
+ *
+ * A directory of its own under `skills/` was the tidier home and was rejected
+ * on evidence: every `skills/` subdirectory in this tree is a real skill with a
+ * `SKILL.md`, the generators parse that file to build their artifacts, and a
+ * directory without one is a shape nothing here has ever produced. Choosing an
+ * unproven layout is what put the import in the wrong place to begin with.
+ *
+ * **Do not delete this as unused from its host skill.** Its importers are in
+ * other skills and in `../../../scripts/`; `lisa-setup-workstation` hosts it,
+ * it does not own it.
+ * @module bounded-child
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+
+/**
+ * Deadline a child gets when the caller states none, in milliseconds.
+ *
+ * A hang detector, not a performance budget. `git` resolved through `PATH` on
+ * macOS goes via Apple's `xcrun` shim, measured at over 20 seconds under load
+ * against 11ms for a real binary (CodySwannGT/lisa#2887) — so a tighter
+ * deadline would make this module's own timeout the dominant failure mode, and
+ * the tool would start manufacturing the failures it exists to detect.
+ */
+export const CHILD_BUDGET_MS = 30_000;
+
+/**
+ * Whether this value is a child that was killed at its deadline.
+ *
+ * Reads `code` rather than an error class, because `ETIMEDOUT` is set by Node
+ * itself on all three call forms — it is a platform fact, not a convention this
+ * module invented, so the same test is correct anywhere including inline.
+ *
+ * Defensive about the shape: a `catch` binding is `unknown` and a thrown
+ * non-object is legal JavaScript, so this must answer `false` rather than crash
+ * the guard that was being careful.
+ * @param {unknown} error A caught value, or `result.error` from `spawnSync`.
+ * @returns {boolean} True when the child was killed at its deadline.
+ */
+export function isChildTimeout(error) {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    /** @type {{ code?: unknown }} */ (error).code === "ETIMEDOUT"
+  );
+}
+
+/**
+ * Re-raise a caught value when it is a killed child, otherwise do nothing.
+ *
+ * The correct spelling is `throw error` — not wrapping — because a wrapped
+ * error loses the `code` the next frame up needs to make the same decision.
+ * @param {unknown} error The caught value.
+ * @returns {void}
+ * @throws {unknown} The original value, when it is a killed child.
+ */
+export function rethrowIfChildTimeout(error) {
+  if (isChildTimeout(error)) throw error;
+}
+
+/**
+ * `spawnSync` with a deadline, refusing to return a killed child's result.
+ * @param {string} command The executable.
+ * @param {readonly string[]} args Arguments.
+ * @param {object} [options] `spawnSync` options; `timeout` overrides the default.
+ * @returns {import("node:child_process").SpawnSyncReturns<string>} The result.
+ * @throws {Error} When the child was killed at its deadline.
+ */
+export function boundedChild(command, args = [], options = {}) {
+  const result = spawnSync(command, [...args], {
+    ...options,
+    // `SIGKILL` rather than the default `SIGTERM`: the hang this exists for is
+    // a process not servicing signals, and a `SIGTERM` a child ignores turns
+    // the deadline into a suggestion.
+    killSignal: "SIGKILL",
+    timeout: options.timeout ?? CHILD_BUDGET_MS,
+  });
+  if (isChildTimeout(result.error)) throw result.error;
+  return result;
+}
+
+/**
+ * `execFileSync` with a deadline.
+ *
+ * `execFileSync` already throws on a timeout, so this changes the FAILURE MODE
+ * rather than adding one: without a `timeout` there is no deadline to reach and
+ * the call blocks for as long as the child lives.
+ * @param {string} command The executable.
+ * @param {readonly string[]} args Arguments.
+ * @param {object} [options] `execFileSync` options; `timeout` overrides the default.
+ * @returns {string|Buffer} Whatever the child wrote to stdout.
+ * @throws {Error} When the child was killed, or exited non-zero.
+ */
+export function boundedChildOutput(command, args = [], options = {}) {
+  return execFileSync(command, [...args], {
+    ...options,
+    killSignal: "SIGKILL",
+    timeout: options.timeout ?? CHILD_BUDGET_MS,
+  });
+}

package/plugins/lisa-wiki-devin/scripts/lint-wiki.mjs

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+/**
+ * lint-wiki.mjs — deterministic, dependency-free integrity checker for a lisa-wiki.
+ *
+ * Read-only: it reports findings, it never modifies the wiki. Default mode is
+ * "warning" (exit 1 only on FAIL items); `--strict` (hard-enforcement) also fails
+ * on WARN items. INFO items are reported and block in NEITHER mode — that is
+ * the level for a finding whose only available remedies would damage the wiki,
+ * such as an unresolved path cited by a preserved source note.
+ *
+ * Usage: node lint-wiki.mjs [--wiki <wikiRoot>] [--config <path>] [--strict] [--json]
+ * Exit 0 = clean (for the active mode), 1 = blocking findings.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  loadConfig,
+  loadStructure,
+  readJsonSafe,
+  pluginRootFrom,
+  walkFiles,
+  parseFrontmatter,
+  extractMarkdownLinks,
+  extractCitations,
+  SECRET_PATTERNS,
+  TEXT_EXTS,
+  makeReport,
+} from "./_wiki-lib.mjs";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = pluginRootFrom(scriptDir);
+
+const argv = process.argv.slice(2);
+const flag = name => argv.includes(name);
+const opt = name => {
+  const i = argv.indexOf(name);
+  return i !== -1 ? argv[i + 1] : undefined;
+};
+const strict = flag("--strict");
+const asJson = flag("--json");
+
+const { config } = loadConfig(opt("--config"));
+const structure = loadStructure(pluginRoot) ?? {};
+const wikiRoot = path.resolve(opt("--wiki") ?? config?.wikiRoot ?? "wiki");
+const report = makeReport();
+
+if (!config) {
+  report.add(
+    "config",
+    "not-loaded",
+    "WARN",
+    "config not found/invalid; using structure-manifest defaults"
+  );
+}
+
+if (!fs.existsSync(wikiRoot)) {
+  console.error(`✗ wiki root not found: ${wikiRoot}`);
+  process.exit(1);
+}
+
+const rel = p => path.relative(process.cwd(), p);
+const wrel = p => path.relative(wikiRoot, p);
+const categories = config?.categories ?? structure.categoryDirs?.default ?? [];
+const frontmatterRequired = config?.frontmatter !== false;
+const configPath = path.resolve(
+  opt("--config") ?? "wiki/lisa-wiki.config.json"
+);
+const localConfigPath = path.join(
+  path.dirname(configPath),
+  "lisa-wiki.config.local.json"
+);
+const localConfig = readJsonSafe(localConfigPath);
+
+const allMd = walkFiles(wikiRoot, { ext: ".md" });
+const allFiles = walkFiles(wikiRoot);
+const exists = p => fs.existsSync(p);
+const isUnder = (p, dir) => {
+  const r = path.relative(path.join(wikiRoot, dir), p);
+  return r !== "" && !r.startsWith("..") && !path.isAbsolute(r);
+};
+const isSynthesisPage = p => categories.some(c => isUnder(p, c));
+const isSourceNote = p => isUnder(p, "sources");
+
+// --- 0. redaction policy readiness ----------------------------------------
+const availableRedactionScanners = new Set(["builtin"]);
+const committedRedaction = config?.sensitivity?.redaction;
+const localRedaction = localConfig?.sensitivity?.redaction;
+const addUnsafeLocalOverride = message =>
+  report.add(
+    "redaction-policy",
+    "unsafe-local-override",
+    "FAIL",
+    message,
+    path.relative(wikiRoot, localConfigPath)
+  );
+const isArraySubset = (candidate, baseline) =>
+  candidate.every(value => baseline.includes(value));
+if (committedRedaction?.enabled === true) {
+  const scanners = Array.isArray(committedRedaction.scanners)
+    ? committedRedaction.scanners
+    : [];
+  const missingScanners = scanners.filter(
+    scanner => !availableRedactionScanners.has(scanner)
+  );
+  if (scanners.length === 0) {
+    report.add(
+      "redaction-policy",
+      "scanner-missing",
+      committedRedaction.failClosed === false ? "WARN" : "FAIL",
+      "redaction is enabled but no scanner is selected"
+    );
+  } else if (missingScanners.length > 0) {
+    report.add(
+      "redaction-policy",
+      "scanner-unavailable",
+      committedRedaction.failClosed === false ? "WARN" : "FAIL",
+      `redaction scanner unavailable: ${missingScanners.join(", ")}`
+    );
+  } else {
+    report.add(
+      "redaction-policy",
+      "scanner-available",
+      "PASS",
+      `redaction scanner available: ${scanners.join(", ")}`
+    );
+  }
+  if (committedRedaction.failClosed !== true) {
+    report.add(
+      "redaction-policy",
+      "fail-closed",
+      "WARN",
+      "redaction is enabled without failClosed=true"
+    );
+  }
+  if (committedRedaction.requireReview !== true) {
+    report.add(
+      "redaction-policy",
+      "review-required",
+      "WARN",
+      "redaction is enabled without requireReview=true"
+    );
+  }
+  if (localRedaction?.enabled === false) {
+    addUnsafeLocalOverride("local config disables committed redaction policy");
+  }
+  if (
+    committedRedaction.failClosed === true &&
+    localRedaction?.failClosed === false
+  ) {
+    addUnsafeLocalOverride(
+      "local config disables committed redaction fail-closed policy"
+    );
+  }
+  if (
+    committedRedaction.requireReview === true &&
+    localRedaction?.requireReview === false
+  ) {
+    addUnsafeLocalOverride(
+      "local config disables committed redaction review requirement"
+    );
+  }
+  if (localRedaction && Array.isArray(localRedaction.scanners)) {
+    const localScanners = localRedaction.scanners;
+    const unavailableLocalScanners = localScanners.filter(
+      scanner => !availableRedactionScanners.has(scanner)
+    );
+    const removedScanners = scanners.filter(
+      scanner => !localScanners.includes(scanner)
+    );
+    if (scanners.length > 0 && localScanners.length === 0) {
+      addUnsafeLocalOverride(
+        "local config removes committed redaction scanners"
+      );
+    } else if (unavailableLocalScanners.length > 0) {
+      addUnsafeLocalOverride(
+        `local config selects unavailable redaction scanner: ${unavailableLocalScanners.join(", ")}`
+      );
+    } else if (removedScanners.length > 0) {
+      addUnsafeLocalOverride(
+        `local config removes committed redaction scanner: ${removedScanners.join(", ")}`
+      );
+    }
+  }
+  if (
+    localRedaction &&
+    Array.isArray(committedRedaction.allowedEntities) &&
+    Array.isArray(localRedaction.allowedEntities) &&
+    !isArraySubset(
+      localRedaction.allowedEntities,
+      committedRedaction.allowedEntities
+    )
+  ) {
+    addUnsafeLocalOverride(
+      "local config expands committed redaction allowed entities"
+    );
+  }
+  if (
+    localRedaction &&
+    Array.isArray(committedRedaction.blockedEntities) &&
+    Array.isArray(localRedaction.blockedEntities) &&
+    !isArraySubset(
+      committedRedaction.blockedEntities,
+      localRedaction.blockedEntities
+    )
+  ) {
+    addUnsafeLocalOverride(
+      "local config removes committed redaction blocked entities"
+    );
+  }
+}
+
+// --- A. structure conformance ---------------------------------------------
+for (const f of structure.requiredFiles ?? []) {
+  report.add(
+    "structure",
+    `required-file:${f}`,
+    exists(path.join(wikiRoot, f)) ? "PASS" : "FAIL",
+    exists(path.join(wikiRoot, f))
+      ? `present: ${f}`
+      : `missing required file: ${f}`
+  );
+}
+for (const d of structure.requiredDirs ?? []) {
+  const ok =
+    fs.existsSync(path.join(wikiRoot, d)) &&
+    fs.statSync(path.join(wikiRoot, d)).isDirectory();
+  report.add(
+    "structure",
+    `required-dir:${d}`,
+    ok ? "PASS" : "FAIL",
+    ok ? `present: ${d}/` : `missing required dir: ${d}/`
+  );
+}
+
+// --- B. frontmatter on synthesis pages + source notes ---------------------
+if (frontmatterRequired) {
+  for (const f of allMd) {
+    if (!isSynthesisPage(f) && !isSourceNote(f)) continue;
+    const fm = parseFrontmatter(fs.readFileSync(f, "utf8"));
+    if (!fm.has) {
+      report.add("frontmatter", "missing", "WARN", `no frontmatter`, wrel(f));
+    } else {
+      const missing = ["type", "created", "updated"].filter(
+        k => !fm.keys.includes(k)
+      );
+      if (missing.length) {
+        report.add(
+          "frontmatter",
+          "incomplete",
+          "WARN",
+          `frontmatter missing keys: ${missing.join(", ")}`,
+          wrel(f)
+        );
+      }
+    }
+  }
+}
+
+// --- C/D. links: index coverage, broken links, citations ------------------
+const indexPath = path.join(wikiRoot, "index.md");
+const indexText = exists(indexPath) ? fs.readFileSync(indexPath, "utf8") : "";
+const indexTargets = new Set(
+  extractMarkdownLinks(indexText).map(t => path.resolve(wikiRoot, t))
+);
+// dangling index links
+for (const t of indexTargets) {
+  if (t.endsWith(".md") && !exists(t)) {
+    report.add(
+      "links",
+      "index-dangling",
+      "FAIL",
+      `index links to a missing page: ${wrel(t)}`,
+      "index.md"
+    );
+  }
+}
+// pages missing from index
+for (const f of allMd) {
+  if (!isSynthesisPage(f)) continue;
+  if (!indexTargets.has(f)) {
+    report.add(
+      "index",
+      "page-missing",
+      "WARN",
+      `synthesis page not linked from index.md`,
+      wrel(f)
+    );
+  }
+}
+// broken internal links + citations across all md; build link graph for orphans.
+// A link resolves if it exists relative to the file, OR as a wiki-root-relative /
+// repo-root-relative / "wiki/"-prefixed form (reduces false positives).
+const wikiBase = path.basename(wikiRoot);
+const linkResolution = (f, target) => {
+  const primary = path.resolve(path.dirname(f), target);
+  const stripped = target
+    .replace(/^\/+/, "")
+    .replace(new RegExp(`^${wikiBase}/`), "");
+  const cands = [
+    primary,
+    path.resolve(wikiRoot, target),
+    path.resolve(wikiRoot, "..", target),
+    path.resolve(wikiRoot, stripped),
+  ];
+  return { primary, hit: cands.find(exists) };
+};
+// A path inside `sources/` is PRESERVED material, not authored navigation.
+// The contract (`Required Provenance`) says a source note records "what was
+// ingested, when, from where, and with what scope" — so a path it names is a
+// statement about the subject AT INGESTION TIME, and the subject moves on.
+// `wiki/sources/repository/2026-05-14-monorepo-baseline.md` cites
+// `docs/lisa-architecture.svg`, which existed on that date and was deleted
+// three months later by the commit that made the wiki the documentation home.
+// The citation is not broken; it is accurate about a repository that changed.
+//
+// Neither remedy available to a reader is legitimate. Repointing the link
+// falsifies the record, and deleting it destroys the provenance the note
+// exists to carry — so this cannot be reported at a level that blocks, or the
+// only way to a green check is to damage the evidence. It is reported at INFO:
+// visible in every run and in `--json`, blocking in none, `--strict` included.
+// Authored pages are untouched and a broken link there still FAILs.
+const preservedFinding = (id, message, f) =>
+  report.add(
+    "links",
+    `source-${id}`,
+    "INFO",
+    `${message} (preserved)`,
+    wrel(f)
+  );
+const linkedTo = new Set();
+for (const f of allMd) {
+  const text = fs.readFileSync(f, "utf8");
+  const preserved = isSourceNote(f);
+  for (const target of extractMarkdownLinks(text)) {
+    const { primary, hit } = linkResolution(f, target);
+    if (target.endsWith(".md") || primary.endsWith(".md")) {
+      linkedTo.add(hit ?? primary);
+      if (hit) continue;
+      if (preserved) {
+        preservedFinding("citation", `cited page not present → ${target}`, f);
+      } else {
+        report.add(
+          "links",
+          "broken",
+          "FAIL",
+          `broken link → ${target}`,
+          wrel(f)
+        );
+      }
+    } else if (!hit) {
+      if (preserved) {
+        preservedFinding(
+          "citation-asset",
+          `cited path not present → ${target}`,
+          f
+        );
+      } else {
+        report.add(
+          "links",
+          "broken-asset",
+          "WARN",
+          `link to missing path → ${target}`,
+          wrel(f)
+        );
+      }
+    }
+  }
+  for (const cite of extractCitations(text)) {
+    const candidates = [
+      path.resolve(wikiRoot, cite),
+      path.resolve(wikiRoot, "..", cite),
+      path.resolve(path.dirname(f), cite),
+    ];
+    if (candidates.some(exists)) continue;
+    if (preserved) {
+      preservedFinding(
+        "citation-path",
+        `citation path not present → ${cite}`,
+        f
+      );
+    } else {
+      report.add(
+        "links",
+        "citation-unresolved",
+        "WARN",
+        `citation path not found → ${cite}`,
+        wrel(f)
+      );
+    }
+  }
+}
+
+// --- E. orphan pages ------------------------------------------------------
+for (const f of allMd) {
+  if (!isSynthesisPage(f)) continue;
+  if (!indexTargets.has(f) && !linkedTo.has(f)) {
+    report.add(
+      "orphans",
+      "orphan",
+      "WARN",
+      `page is unreferenced (not in index, not linked)`,
+      wrel(f)
+    );
+  }
+}
+
+// --- F. log non-empty -----------------------------------------------------
+const logPath = path.join(wikiRoot, "log.md");
+if (exists(logPath)) {
+  // Accept the canonical table row (| YYYY-MM-DD | ...) AND the legacy heading
+  // formats (## YYYY-MM-DD or ## [YYYY-MM-DD]) tolerated during migration.
+  const rows = fs
+    .readFileSync(logPath, "utf8")
+    .split("\n")
+    .filter(
+      l =>
+        /^\|\s*\d{4}-\d{2}-\d{2}\s*\|/.test(l) ||
+        /^##\s*\[?\d{4}-\d{2}-\d{2}/.test(l)
+    );
+  report.add(
+    "log",
+    "non-empty",
+    rows.length > 0 ? "PASS" : "WARN",
+    rows.length > 0
+      ? `${rows.length} log entr${rows.length === 1 ? "y" : "ies"}`
+      : "log.md has no dated entries"
+  );
+}
+
+// --- G. secret + contamination + binaries ---------------------------------
+const terms = (config?.contaminationTerms ?? []).filter(Boolean);
+for (const f of allFiles) {
+  const ext = path.extname(f);
+  if (!TEXT_EXTS.has(ext) && path.basename(f) !== ".gitkeep") {
+    report.add(
+      "binaries",
+      "stray",
+      "WARN",
+      `non-text file under wiki`,
+      wrel(f)
+    );
+    continue;
+  }
+  let text;
+  try {
+    text = fs.readFileSync(f, "utf8");
+  } catch {
+    continue;
+  }
+  for (const { name, re } of SECRET_PATTERNS) {
+    if (re.test(text))
+      report.add("secrets", "leak", "FAIL", `possible ${name}`, wrel(f));
+  }
+  // The config file legitimately lists the contamination terms it scans for; don't flag it.
+  if (path.basename(f) !== "lisa-wiki.config.json") {
+    for (const term of terms) {
+      if (text.toLowerCase().includes(term.toLowerCase())) {
+        report.add(
+          "contamination",
+          "term",
+          "FAIL",
+          `contamination term "${term}"`,
+          wrel(f)
+        );
+      }
+    }
+  }
+}
+
+// --- output + verdict -----------------------------------------------------
+const fails = report.items.filter(i => i.status === "FAIL");
+const warns = report.items.filter(i => i.status === "WARN");
+// INFO is reported and never counted. It is the level for a finding a reader
+// is not permitted to fix — see the preserved-source note above. Deliberately
+// excluded from `blocking` in BOTH modes, because `--strict` is what the
+// shipped CI workflow runs and a level that blocks under strict is a blocking
+// level with extra steps.
+const infos = report.items.filter(i => i.status === "INFO");
+const blocking = strict ? fails.length + warns.length : fails.length;
+
+if (asJson) {
+  console.log(
+    JSON.stringify(
+      {
+        wikiRoot: rel(wikiRoot),
+        strict,
+        fails: fails.length,
+        warns: warns.length,
+        infos: infos.length,
+        items: report.items.filter(i => i.status !== "PASS"),
+      },
+      null,
+      2
+    )
+  );
+} else {
+  const marker = { FAIL: "✗", INFO: "ℹ" };
+  for (const i of report.items.filter(i => i.status !== "PASS")) {
+    console.log(
+      `${marker[i.status] ?? "⚠"} [${i.group}] ${i.message}${i.file ? ` (${i.file})` : ""}`
+    );
+  }
+  console.log(
+    `\n${fails.length} fail, ${warns.length} warn, ${infos.length} info (never blocking)${strict ? " (strict: warnings block)" : ""} — ${blocking === 0 ? "OK" : "BLOCKING"}`
+  );
+}
+
+// Set exitCode instead of calling process.exit() so a large `--json` payload
+// written to a pipe (e.g. captured via spawnSync by verify-migration) is fully
+// flushed before the process exits. process.exit() can truncate async stdout
+// writes at the OS pipe buffer (~64KB), corrupting the JSON for the reader.
+process.exitCode = blocking === 0 ? 0 : 1;