@codyswann/lisa 4.4.6 → 4.4.7

package/plugins/lisa-wiki-copilot/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-copilot/scripts/verify-migration.mjs

@@ -12,10 +12,11 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { loadConfig } from "./_wiki-lib.mjs";
 
+import { boundedChild } from "./lib/bounded-child.mjs";
+
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const argv = process.argv.slice(2);
 const opt = n => {
@@ -31,7 +32,7 @@ const groups = { A: [], B: [], C: [], D: [], E: [], F: [], G: [] };
 const add = (g, id, status, message) => groups[g].push({ id, status, message });
 
 function runNode(script, args) {
-  const res = spawnSync("node", [path.join(scriptDir, script), ...args], {
+  const res = boundedChild("node", [path.join(scriptDir, script), ...args], {
     encoding: "utf8",
   });
   return {

package/plugins/lisa-wiki-copilot/scripts/verify-wiki-safety.mjs

@@ -5,12 +5,16 @@
  * Scans only explicit wiki paths, or current git changes under the configured
  * wiki root when no paths are passed. Reports safe metadata only.
  */
-import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { loadConfig } from "./_wiki-lib.mjs";
 import { scanWikiGeneratedFiles } from "./wiki-safety.mjs";
 
+import {
+  boundedChildOutput,
+  rethrowIfChildTimeout,
+} from "./lib/bounded-child.mjs";
+
 const argv = process.argv.slice(2);
 const flag = name => argv.includes(name);
 const opt = name => {
@@ -32,11 +36,14 @@ const scanner = opt("--scanner") ?? "builtin";
 
 function commandExists(command) {
   try {
-    execFileSync("sh", ["-c", `command -v ${command}`], {
+    boundedChildOutput("sh", ["-c", `command -v ${command}`], {
       stdio: "ignore",
     });
     return true;
-  } catch {
+  } catch (error) {
+    // "I could not check whether the tool exists" is not "the tool is
+    // absent" — and absent silently downgrades the scan to the builtin.
+    rethrowIfChildTimeout(error);
     return false;
   }
 }
@@ -44,10 +51,13 @@ function commandExists(command) {
 function gitChangedPaths() {
   let out = "";
   try {
-    out = execFileSync("git", ["status", "--porcelain=v1", "-z"], {
+    out = boundedChildOutput("git", ["status", "--porcelain=v1", "-z"], {
       encoding: "utf8",
     });
-  } catch {
+  } catch (error) {
+    // An empty change set means this safety check inspects NOTHING and
+    // passes. A busy machine would clear the wiki without reading it.
+    rethrowIfChildTimeout(error);
     return [];
   }
   const entries = out.split("\0").filter(Boolean);

package/plugins/lisa-wiki-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.4.6",
+  "version": "4.4.7",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-cursor/scripts/diff-guard.mjs

@@ -16,9 +16,10 @@
  * Usage: node diff-guard.mjs --allow <glob> [--allow <glob>...] [--base <ref>]
  * Exit 0 = all changes within allowed globs, 1 = out-of-bounds change (or git error).
  */
-import { execFileSync } from "node:child_process";
 import { globToRegExp } from "./_wiki-lib.mjs";
 
+import { boundedChildOutput } from "./lib/bounded-child.mjs";
+
 function fail(msg) {
   console.error(`✗ ${msg}`);
   process.exit(1);
@@ -51,7 +52,7 @@ if (allows.length === 0) {
 }
 
 function git(args) {
-  return execFileSync("git", args, { encoding: "utf8" });
+  return boundedChildOutput("git", args, { encoding: "utf8" });
 }
 
 let repoRoot;

package/plugins/lisa-wiki-cursor/scripts/ensure-wiki.mjs

@@ -49,7 +49,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+
+import { boundedChildOutput } from "./lib/bounded-child.mjs";
 
 const GITIGNORE_BEGIN = "# BEGIN: AI GUARDRAILS WIKI MIRROR";
 const GITIGNORE_END = "# END: AI GUARDRAILS WIKI MIRROR";
@@ -71,7 +72,7 @@ function readJsonSafe(file) {
   }
 }
 function git(args, cwd) {
-  return execFileSync("git", args, {
+  return boundedChildOutput("git", args, {
     cwd,
     stdio: ["ignore", "pipe", "pipe"],
     encoding: "utf8",

package/plugins/lisa-wiki-cursor/scripts/ingest-git.mjs

@@ -14,9 +14,13 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
 import { readJsonSafe, writeSanitizedSourceNote } from "./_wiki-lib.mjs";
 
+import {
+  boundedChildOutput,
+  rethrowIfChildTimeout,
+} from "./lib/bounded-child.mjs";
+
 const argv = process.argv.slice(2);
 const opt = (n, d) => {
   const i = argv.indexOf(n);
@@ -35,7 +39,7 @@ const fail = m => {
   process.exit(1);
 };
 const git = args =>
-  execFileSync("git", ["-C", repo, ...args], { encoding: "utf8" }).trim();
+  boundedChildOutput("git", ["-C", repo, ...args], { encoding: "utf8" }).trim();
 const tryGit = args => {
   try {
     return git(args);
@@ -45,11 +49,13 @@ const tryGit = args => {
 };
 const commitExists = c => {
   try {
-    execFileSync("git", ["-C", repo, "cat-file", "-e", `${c}^{commit}`], {
+    boundedChildOutput("git", ["-C", repo, "cat-file", "-e", `${c}^{commit}`], {
       stdio: "ignore",
     });
     return true;
-  } catch {
+  } catch (error) {
+    // `false` is a verdict of "absent", not an admission of ignorance.
+    rethrowIfChildTimeout(error);
     return false;
   }
 };
@@ -87,7 +93,7 @@ let prSummary = "(no GitHub repo resolved — PR history skipped)";
 let ghRepo = githubRepo;
 if (!ghRepo) {
   try {
-    ghRepo = execFileSync(
+    ghRepo = boundedChildOutput(
       "gh",
       ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"],
       { cwd: repo, encoding: "utf8" }
@@ -99,7 +105,7 @@ if (!ghRepo) {
 if (ghRepo) {
   try {
     const prs = JSON.parse(
-      execFileSync(
+      boundedChildOutput(
         "gh",
         [
           "pr",

package/plugins/lisa-wiki-cursor/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-cursor/scripts/verify-migration.mjs

@@ -12,10 +12,11 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { loadConfig } from "./_wiki-lib.mjs";
 
+import { boundedChild } from "./lib/bounded-child.mjs";
+
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const argv = process.argv.slice(2);
 const opt = n => {
@@ -31,7 +32,7 @@ const groups = { A: [], B: [], C: [], D: [], E: [], F: [], G: [] };
 const add = (g, id, status, message) => groups[g].push({ id, status, message });
 
 function runNode(script, args) {
-  const res = spawnSync("node", [path.join(scriptDir, script), ...args], {
+  const res = boundedChild("node", [path.join(scriptDir, script), ...args], {
     encoding: "utf8",
   });
   return {

package/plugins/lisa-wiki-cursor/scripts/verify-wiki-safety.mjs

@@ -5,12 +5,16 @@
  * Scans only explicit wiki paths, or current git changes under the configured
  * wiki root when no paths are passed. Reports safe metadata only.
  */
-import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { loadConfig } from "./_wiki-lib.mjs";
 import { scanWikiGeneratedFiles } from "./wiki-safety.mjs";
 
+import {
+  boundedChildOutput,
+  rethrowIfChildTimeout,
+} from "./lib/bounded-child.mjs";
+
 const argv = process.argv.slice(2);
 const flag = name => argv.includes(name);
 const opt = name => {
@@ -32,11 +36,14 @@ const scanner = opt("--scanner") ?? "builtin";
 
 function commandExists(command) {
   try {
-    execFileSync("sh", ["-c", `command -v ${command}`], {
+    boundedChildOutput("sh", ["-c", `command -v ${command}`], {
       stdio: "ignore",
     });
     return true;
-  } catch {
+  } catch (error) {
+    // "I could not check whether the tool exists" is not "the tool is
+    // absent" — and absent silently downgrades the scan to the builtin.
+    rethrowIfChildTimeout(error);
     return false;
   }
 }
@@ -44,10 +51,13 @@ function commandExists(command) {
 function gitChangedPaths() {
   let out = "";
   try {
-    out = execFileSync("git", ["status", "--porcelain=v1", "-z"], {
+    out = boundedChildOutput("git", ["status", "--porcelain=v1", "-z"], {
       encoding: "utf8",
     });
-  } catch {
+  } catch (error) {
+    // An empty change set means this safety check inspects NOTHING and
+    // passes. A busy machine would clear the wiki without reading it.
+    rethrowIfChildTimeout(error);
     return [];
   }
   const entries = out.split("\0").filter(Boolean);

package/plugins/src/base/scripts/design-source-gate.mjs

@@ -38,6 +38,20 @@ import { execFileSync } from "node:child_process";
 import { readFileSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
+/**
+ * Hang-detector deadline for a child of this script, in milliseconds.
+ *
+ * Written inline rather than imported. The shared `bounded-child.mjs` lives in
+ * the `skills/` tree because the built Codex artifact copies `skills/` and
+ * nothing else — and these plugin-ROOT scripts are not in that artifact at all,
+ * so reaching across into `../skills/` would invent a dependency between two
+ * halves of the plugin for no gain.
+ *
+ * A ceiling, not a budget: `git` through PATH on macOS goes via Apple's `xcrun`
+ * shim, measured over 20s under load (CodySwannGT/lisa#2887).
+ */
+const CHILD_BUDGET_MS = 30_000;
+
 /** The one designated marker for UI deliberately not captured in Figma. */
 export const DESIGN_SOURCE_NONE_MARKER = "DESIGN-SOURCE: none — not in Figma";
 
@@ -404,9 +418,13 @@ export function collectChangedFiles(base, head) {
     output = execFileSync(
       "git",
       ["diff", "--name-status", "--no-renames", `${base}...${head}`],
-      { encoding: "utf8" }
+      { encoding: "utf8", killSignal: "SIGKILL", timeout: CHILD_BUDGET_MS }
     );
   } catch (error) {
+    // KEPT for a timeout too, deliberately: `files: null` already pushes
+    // `changed-files-unresolved` into the reasons and `diffError` carries the
+    // message, which for a kill names ETIMEDOUT. Already fail-closed and
+    // already speaking; re-raising would trade a good report for a crash.
     return { files: null, diffError: String(error?.message ?? error) };
   }
 

package/plugins/src/base/scripts/plugin-sync-explain.mjs

@@ -22,6 +22,20 @@ import process from "node:process";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
+/**
+ * Hang-detector deadline for a child of this script, in milliseconds.
+ *
+ * Written inline rather than imported. The shared `bounded-child.mjs` lives in
+ * the `skills/` tree because the built Codex artifact copies `skills/` and
+ * nothing else — and these plugin-ROOT scripts are not in that artifact at all,
+ * so reaching across into `../skills/` would invent a dependency between two
+ * halves of the plugin for no gain.
+ *
+ * A ceiling, not a budget: `git` through PATH on macOS goes via Apple's `xcrun`
+ * shim, measured over 20s under load (CodySwannGT/lisa#2887).
+ */
+const CHILD_BUDGET_MS = 30_000;
+
 export const PLUGIN_SYNC_CLASSIFICATIONS = [
   "SOURCE_NOT_BUILT",
   "GENERATED_ONLY",
@@ -373,11 +387,17 @@ function buildExpectedGeneratedFiles(root) {
     execFileSync("bash", ["scripts/build-plugins.sh"], {
       cwd: scratchRoot,
       encoding: "utf8",
+      killSignal: "SIGKILL",
+      // The plugin build is minutes, not seconds — a ceiling, not a budget.
+      timeout: 20 * 60 * 1000,
       env: gitEnv(),
       stdio: "ignore",
     });
     return collectGeneratedFiles(scratchRoot);
-  } catch {
+  } catch (error) {
+    // `undefined` reads as "there is nothing to explain here", which is a
+    // finding. A timeout has not found that; it has found nothing at all.
+    if (error?.code === "ETIMEDOUT") throw error;
     return undefined;
   } finally {
     rmSync(tempRoot, { force: true, recursive: true });
@@ -469,6 +489,8 @@ function gitStatus(root) {
     {
       cwd: root,
       encoding: "utf8",
+      killSignal: "SIGKILL",
+      timeout: CHILD_BUDGET_MS,
       env: gitEnv(root),
     }
   );