@codyswann/lisa 4.4.5 → 4.4.7

package/plugins/lisa-agy/skills/lisa-remote-dispatch/scripts/dispatch.mjs

@@ -19,7 +19,6 @@
  * @module dispatch
  */
 
-import { execFileSync } from "node:child_process";
 import {
   existsSync,
   mkdirSync,
@@ -30,6 +29,8 @@ import {
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { boundedChildOutput } from "../../lisa-setup-workstation/scripts/bounded-child.mjs";
+
 /** Surfaces this dispatcher knows how to reach. `local` means "do not dispatch". */
 export const EXECUTION_ENVS = new Set(["local", "codex-cloud", "claude-web"]);
 
@@ -249,7 +250,7 @@ function dispatchCodexCloud(block, prompt, payload) {
   const args = buildCodexArgs(block, prompt);
   let output;
   try {
-    output = execFileSync("codex", args, {
+    output = boundedChildOutput("codex", args, {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
     });
@@ -432,7 +433,7 @@ function resolveBearerToken(block) {
     "resolve-secret.mjs"
   );
   try {
-    return execFileSync("node", [resolver, "get", name], {
+    return boundedChildOutput("node", [resolver, "get", name], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
     }).trim();

package/plugins/lisa-agy/skills/lisa-secrets-access/scripts/providers.mjs

@@ -9,10 +9,13 @@
  * @module providers
  */
 
-import { execFileSync } from "node:child_process";
-
 import { readBootstrapFile } from "./bootstrap-store.mjs";
 
+import {
+  boundedChildOutput,
+  rethrowIfChildTimeout,
+} from "../../lisa-setup-workstation/scripts/bounded-child.mjs";
+
 /**
  * A provider key becomes a shell variable name on materializing surfaces, so
  * only names valid in every POSIX-like shell are accepted. Anything else stays
@@ -154,12 +157,15 @@ function fromKeychain(key) {
     // `bootstrapToken` has no handler — so a raw filesystem error would
     // replace the curated "not found in: ..." message with a stack trace.
     if (process.platform !== "darwin") return readBootstrapFile(key);
-    return execFileSync(
+    return boundedChildOutput(
       "security",
       ["find-generic-password", "-s", key, "-a", process.env.USER ?? "", "-w"],
       { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
     ).trim();
-  } catch {
+  } catch (error) {
+    // A killed child must not read as "this provider has no such
+    // secret" — that is a claim about the vault, and the caller acts on it.
+    rethrowIfChildTimeout(error);
     return "";
   }
 }
@@ -223,7 +229,7 @@ export function fetchRaw(cfg) {
  * @returns {string} Captured stdout.
  */
 function run(bin, args, env) {
-  return execFileSync(bin, args, {
+  return boundedChildOutput(bin, args, {
     encoding: "utf8",
     env,
     stdio: ["ignore", "pipe", "pipe"],

package/plugins/lisa-agy/skills/lisa-secrets-access/scripts/sync-secret-to-ci.mjs

@@ -47,13 +47,14 @@
  * @module sync-secret-to-ci
  */
 
-import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 
 import { ENV_KEY, fetchAll } from "./providers.mjs";
 import { readConfig } from "./surfaces.mjs";
 
+import { boundedChildOutput } from "../../lisa-setup-workstation/scripts/bounded-child.mjs";
+
 /**
  * How many secrets to ask for per listing page.
  *
@@ -266,7 +267,7 @@ export function confirmPresent(payload, dest) {
  */
 function gh(args, options = {}) {
   try {
-    return execFileSync("gh", args, {
+    return boundedChildOutput("gh", args, {
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"],
       ...options,

package/plugins/lisa-agy/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs

@@ -28,7 +28,6 @@
  * @module setup-remote-env
  */
 
-import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
   chmodSync,
@@ -51,6 +50,8 @@ import { pathDirs } from "../../lisa-setup-workstation/scripts/catalogue.mjs";
 
 import { assertPinned, extractVersion, planToolchain } from "./toolchain.mjs";
 
+import { boundedChildOutput } from "../../lisa-setup-workstation/scripts/bounded-child.mjs";
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 
 /**
@@ -117,7 +118,7 @@ export function readRemoteEnvConfig(cwd = process.cwd()) {
  * @param {Function} [exec] Command runner, for tests.
  * @returns {{version: string|null, present: boolean}} Probe result.
  */
-export function probe(name, exec = execFileSync) {
+export function probe(name, exec = boundedChildOutput) {
   try {
     const out = exec(name, ["--version"], {
       encoding: "utf8",
@@ -169,19 +170,23 @@ function installReleaseZip(tool, binDir) {
   mkdirSync(temporary, { recursive: true });
   try {
     const archive = join(temporary, "download.zip");
-    execFileSync("curl", ["-fsSL", tool.url, "-o", archive], {
+    boundedChildOutput("curl", ["-fsSL", tool.url, "-o", archive], {
       stdio: "inherit",
     });
     // Verify before unpacking, not after. An unexpected archive must fail
     // before any of its contents reach a directory that is on PATH.
     verifyChecksum(archive, tool.sha256, tool.name);
-    execFileSync("unzip", ["-q", "-o", archive, "-d", temporary], {
+    boundedChildOutput("unzip", ["-q", "-o", archive, "-d", temporary], {
       stdio: "inherit",
     });
     const binary = join(temporary, tool.binary ?? tool.name);
-    execFileSync("install", ["-m", "0755", binary, join(binDir, tool.name)], {
-      stdio: "inherit",
-    });
+    boundedChildOutput(
+      "install",
+      ["-m", "0755", binary, join(binDir, tool.name)],
+      {
+        stdio: "inherit",
+      }
+    );
   } finally {
     rmSync(temporary, { recursive: true, force: true });
   }
@@ -202,19 +207,23 @@ function installReleaseTar(tool, binDir) {
   mkdirSync(temporary, { recursive: true });
   try {
     const archive = join(temporary, "download.tar.gz");
-    execFileSync("curl", ["-fsSL", tool.url, "-o", archive], {
+    boundedChildOutput("curl", ["-fsSL", tool.url, "-o", archive], {
       stdio: "inherit",
     });
     verifyChecksum(archive, tool.sha256, tool.name);
-    execFileSync("tar", ["-xzf", archive, "-C", temporary], {
+    boundedChildOutput("tar", ["-xzf", archive, "-C", temporary], {
       stdio: "inherit",
     });
     // Release tarballs usually nest under a versioned directory, so `binary` is
     // a path within the archive rather than a bare name.
     const binary = join(temporary, tool.binary ?? tool.name);
-    execFileSync("install", ["-m", "0755", binary, join(binDir, tool.name)], {
-      stdio: "inherit",
-    });
+    boundedChildOutput(
+      "install",
+      ["-m", "0755", binary, join(binDir, tool.name)],
+      {
+        stdio: "inherit",
+      }
+    );
   } finally {
     rmSync(temporary, { recursive: true, force: true });
   }
@@ -260,7 +269,7 @@ function installReleaseTree(tool, binDir) {
   mkdirSync(temporary, { recursive: true });
   try {
     const archive = join(temporary, "download.archive");
-    execFileSync("curl", ["-fsSL", tool.url, "-o", archive], {
+    boundedChildOutput("curl", ["-fsSL", tool.url, "-o", archive], {
       stdio: "inherit",
     });
     // Verify before unpacking, as everywhere else here: an unexpected archive
@@ -273,11 +282,11 @@ function installReleaseTree(tool, binDir) {
     rmSync(prefix, { recursive: true, force: true });
     mkdirSync(prefix, { recursive: true });
     if (tool.url.endsWith(".zip")) {
-      execFileSync("unzip", ["-q", "-o", archive, "-d", prefix], {
+      boundedChildOutput("unzip", ["-q", "-o", archive, "-d", prefix], {
         stdio: "inherit",
       });
     } else {
-      execFileSync("tar", ["-xzf", archive, "-C", prefix], {
+      boundedChildOutput("tar", ["-xzf", archive, "-C", prefix], {
         stdio: "inherit",
       });
     }
@@ -330,7 +339,7 @@ function installReleaseBinary(tool, binDir) {
   mkdirSync(temporary, { recursive: true });
   try {
     const artifact = join(temporary, tool.name);
-    execFileSync("curl", ["-fsSL", tool.url, "-o", artifact], {
+    boundedChildOutput("curl", ["-fsSL", tool.url, "-o", artifact], {
       stdio: "inherit",
     });
     // Verify before it reaches a directory on PATH. For this kind that ordering
@@ -338,9 +347,13 @@ function installReleaseBinary(tool, binDir) {
     // executable, so a wrong artifact placed first is a wrong artifact that can
     // be run.
     verifyChecksum(artifact, tool.sha256, tool.name);
-    execFileSync("install", ["-m", "0755", artifact, join(binDir, tool.name)], {
-      stdio: "inherit",
-    });
+    boundedChildOutput(
+      "install",
+      ["-m", "0755", artifact, join(binDir, tool.name)],
+      {
+        stdio: "inherit",
+      }
+    );
   } finally {
     rmSync(temporary, { recursive: true, force: true });
   }
@@ -351,7 +364,7 @@ function installReleaseBinary(tool, binDir) {
  * @param {object} tool Manifest entry.
  */
 function installNpmGlobal(tool) {
-  execFileSync(
+  boundedChildOutput(
     "npm",
     ["install", "--global", `${tool.package}@${tool.version}`],
     {
@@ -495,7 +508,7 @@ function runHook(hook, dryRun) {
   console.log(`\nProject hook: ${hook}`);
   if (dryRun) return;
   chmodSync(path, 0o755);
-  execFileSync("bash", [path], { stdio: "inherit" });
+  boundedChildOutput("bash", [path], { stdio: "inherit" });
 }
 
 /** Phases this runner can execute, in the order they must happen. */
@@ -1181,7 +1194,7 @@ export function emitContainer({
  * skills has no detector, and that is not a reason to refuse to provision.
  * @param {Function} [exec] Seam for tests.
  */
-function reportUndeclaredTooling(exec = execFileSync) {
+function reportUndeclaredTooling(exec = boundedChildOutput) {
   let script;
   try {
     script = siblingScript("lisa-detect-tooling", "detect-tooling.mjs");
@@ -1489,7 +1502,7 @@ async function main() {
       if (hook.reason) console.log(`    ${hook.reason}`);
     }
     try {
-      execFileSync(
+      boundedChildOutput(
         "node",
         dryRun ? [materialize, "--dry-run"] : [materialize],
         { stdio: "inherit" }

package/plugins/lisa-agy/skills/lisa-setup-remote-env/scripts/verify-remote-env.mjs

@@ -21,7 +21,6 @@
  * @module verify-remote-env
  */
 
-import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { existsSync, readFileSync, statSync, realpathSync } from "node:fs";
 import { join } from "node:path";
@@ -29,6 +28,8 @@ import { join } from "node:path";
 import { probe, readRemoteEnvConfig } from "./setup-remote-env.mjs";
 import { planToolchain } from "./toolchain.mjs";
 
+import { boundedChildOutput } from "../../lisa-setup-workstation/scripts/bounded-child.mjs";
+
 /** Collected results, so every check runs before anything reports failure. */
 const results = [];
 
@@ -73,12 +74,15 @@ function checkMode(path, mode, label) {
  */
 function node(args) {
   try {
-    const out = execFileSync("node", args, {
+    const out = boundedChildOutput("node", args, {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
     });
     return { ok: true, out: out.trim() };
   } catch (err) {
+    // KEPT: `ok: false` fails the check either way, and a killed child's
+    // `err.message` already reads "... ETIMEDOUT", so the timeout names
+    // itself. This is the shape the others are being moved toward.
     return { ok: false, out: String(err.stderr ?? err.message).trim() };
   }
 }
@@ -149,7 +153,7 @@ export function verifyNotProxied(required, env, report) {
  */
 function verifyCleanCheckout() {
   try {
-    const out = execFileSync("git", ["status", "--porcelain"], {
+    const out = boundedChildOutput("git", ["status", "--porcelain"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
     });

package/plugins/lisa-agy/skills/lisa-setup-workstation/scripts/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-agy/skills/lisa-setup-workstation/scripts/workstation.mjs

@@ -33,10 +33,11 @@
  * @module workstation
  */
 
-import { execFileSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 
+import { boundedChildOutput } from "./bounded-child.mjs";
+
 import {
   AGENTS,
   CHECKSUMMED,
@@ -56,7 +57,7 @@ import {
  * @param {Function} [exec] Runner, injectable for tests.
  * @returns {string|null} Absolute path, or null when absent.
  */
-export function locate(name, exec = execFileSync) {
+export function locate(name, exec = boundedChildOutput) {
   try {
     return String(
       exec("command", ["-v", name], { encoding: "utf8", shell: true })
@@ -76,7 +77,7 @@ export function locate(name, exec = execFileSync) {
  * @param {Function} [exec] Runner, injectable for tests.
  * @returns {string|null} A dotted version, or null.
  */
-export function version(name, exec = execFileSync) {
+export function version(name, exec = boundedChildOutput) {
   const read = out => {
     const match = /(\d+(?:\.\d+)+)/.exec(String(out ?? ""));
     return match ? match[1] : null;
@@ -381,7 +382,7 @@ export function installEntry(entry, row, deps = {}) {
   const run =
     deps.run ??
     ((cmd, args, opts) =>
-      execFileSync(cmd, args, { stdio: "inherit", ...opts }));
+      boundedChildOutput(cmd, args, { stdio: "inherit", ...opts }));
   const find = deps.locate ?? locate;
 
   try {

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.4.5",
+  "version": "4.4.7",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.4.5",
+  "version": "4.4.7",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.4.5",
+  "version": "4.4.7",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.4.5",
+  "version": "4.4.7",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.4.5",
+  "version": "4.4.7",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.4.5",
+  "version": "4.4.7",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/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/lisa-copilot/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),
     }
   );