session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/vault-status/narrative-mirror.mjs

@@ -29,7 +29,6 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import os from 'node:os';
 
 import { emitEvent, sessionAttribution } from '../events.mjs';
 import { parseStateMd, parseMissionStatus } from '../state-md.mjs';
@@ -43,6 +42,7 @@ import { matchesModuloRedaction } from '../vault-mirror/process.mjs';
 import { readConfigFile, parseSessionConfig } from '../config.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { createSecretValueMasker } from '../secret-masker.mjs';
+import { expandTilde } from '../common.mjs';
 
 /** Frontmatter sentinel that identifies generator-owned narrative files. */
 export const GENERATOR_MARKER = 'session-orchestrator-vault-status-narrative@1';
@@ -63,23 +63,6 @@ const SECTION_TITLES = {
 
 // ── Raw section extraction ──────────────────────────────────────────────────────
 
-/**
- * Expand a leading `~` to the current user's home directory.
- *
- * NOTE: deferred shared-helper extraction. The same `expandHome` pattern lives in
- * other vault-status modules; W2 forbids introducing a shared new file, so this is
- * inlined here. Consolidate into a shared util in a follow-up wave.
- *
- * @param {string} p
- * @returns {string}
- */
-function expandHome(p) {
-  if (typeof p !== 'string' || p.length === 0) return p;
-  if (p === '~') return os.homedir();
-  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
-  return p;
-}
-
 /**
  * Match an ATX markdown heading line. Returns `{ level, text }` or null.
  *
@@ -235,15 +218,27 @@ export function extractNarrative(stateMdContents) {
  * REFERENCE (byte-identical downstream), and `mask` passes non-strings through —
  * masking must never be the reason a mirror run dies.
  *
+ * Takes the ALREADY-BUILT masker (rather than building its own) so
+ * `runNarrativeMirror` can build it exactly ONCE per run and reuse it for both
+ * the actual masking below AND the `orchestrator.secret_masker.applied`
+ * telemetry (#1028) — the masker's `needleCount` is measured once, not
+ * potentially twice with process.env read between the two reads.
+ *
  * @param {{ waveHistory: string, deviations: string, whatNotToRetry: string, missionStatus: object[]|null }} narrative
- * @returns {{ waveHistory: string, deviations: string, whatNotToRetry: string, missionStatus: object[]|null }}
+ * @param {{ mask: (text: string) => string, needleCount: number }} masker
+ * @returns {{ narrative: { waveHistory: string, deviations: string, whatNotToRetry: string, missionStatus: object[]|null }, hits: number }}
  */
-function maskNarrative(narrative) {
-  const { mask, needleCount } = createSecretValueMasker(process.env);
-  if (needleCount === 0) return narrative;
+function maskNarrative(narrative, masker) {
+  const { mask, needleCount } = masker;
+  if (needleCount === 0) return { narrative, hits: 0 };
 
+  let hits = 0;
   const walk = (value) => {
-    if (typeof value === 'string') return mask(value);
+    if (typeof value === 'string') {
+      const masked = mask(value);
+      if (masked !== value) hits++;
+      return masked;
+    }
     if (Array.isArray(value)) return value.map(walk);
     if (value && typeof value === 'object') {
       const out = {};
@@ -253,7 +248,7 @@ function maskNarrative(narrative) {
     return value;
   };
 
-  return walk(narrative);
+  return { narrative: walk(narrative), hits };
 }
 
 // ── Pure render ────────────────────────────────────────────────────────────────
@@ -421,6 +416,30 @@ function normalizeUpdated(content) {
  * between runs: run 1 (env set) → `skipped-noop`, run 2 (env absent) → `written`
  * with the raw value on disk.
  *
+ * WHY THERE IS NO `maskerWouldChange` RE-PROBE HERE (#1214). The two sibling
+ * sinks in `vault-mirror/process.mjs` (processLearning, processSession) guard
+ * all five of their `skipped-noop` returns with `maskerWouldChange(existing)`,
+ * because their five-field / date comparisons can report a match while the
+ * on-disk note still carries a raw needle. This sink compares the WHOLE
+ * document, which makes that residue unreachable: `matchesModuloRedaction`
+ * only fires when the EXISTING side carries a `[REDACTED]` marker, and every
+ * literal segment around such a marker must appear verbatim in the candidate —
+ * but the candidate comes through `maskNarrative` with the CURRENT masker, so
+ * it can never contain a value that masker would redact. A raw needle on disk
+ * therefore always lands in a literal segment that fails to match, and the run
+ * writes. Measured 2026-09-04 at HEAD cd785003 in both directions (no marker on
+ * disk; marker already on disk plus a second needle entering the env): both
+ * returned `written` with the raw value gone. The two tests named `(#1214)` in
+ * tests/lib/vault-status/narrative-mirror.test.mjs pin that invariant — an
+ * argument-order slip on the call below makes both return `skipped-noop` and
+ * republish the raw value, which is how they were verified to bite.
+ *
+ * NAMED CEILING: the invariant rests on `maskNarrative` walking EVERY string
+ * that reaches the render. `repo` is fed to `renderNarrative` outside that walk
+ * (it is a directory basename, not STATE.md content), so a future rendered
+ * field added outside the walk would reopen this. Revisit trigger: any new
+ * `renderNarrative` input that does not pass through `maskNarrative`.
+ *
  * `matchesModuloRedaction` is IMPORTED from `../vault-mirror/process.mjs`, not
  * re-derived here: `secret-masker.mjs`'s header states this compensation as a
  * contract binding on every consumer that diffs a written artifact against a fresh
@@ -681,6 +700,56 @@ async function emitNarrativeEvent({ repoRoot, action, path: outputPath, chars, e
   }
 }
 
+/**
+ * Emit this channel's `orchestrator.secret_masker.applied` record (#1028
+ * residue 2). Until now the narrative mirror was the ONLY masker channel of
+ * the three (`vault-mirror`, `narrative-mirror`, `export-hw-learnings`) that
+ * never emitted this event — `maskNarrative` has masked unconditionally since
+ * #1025, but nothing told the ledger. A census grepping event NAMES for
+ * `narrative` therefore read as "this channel masks nothing", which was never
+ * true; it just never SAID so.
+ *
+ * Emitted UNCONDITIONALLY once per `mirrorNarrative` run whenever a `repoRoot`
+ * was resolvable — including every skip outcome, not only `written` — so
+ * `needle_count: 0` is a REAL measured "the env carries no secret-shaped
+ * value" rather than a stand-in for "the masker never ran" (same
+ * force-build-don't-default posture as `getMaskerStats()` in
+ * `scripts/lib/vault-mirror/process.mjs`). `records` is the literal `1`: one
+ * `mirrorNarrative` run always masks (or attempts to mask) exactly one
+ * STATE.md, unlike the CLI channels that fan out over many JSONL lines.
+ *
+ * Same field set as the `vault-mirror` channel's own masker emit
+ * (`channel`, `needle_count`, `records`, `hits`, `dry_run`), PLUS
+ * `session_id`/`semantic_session_id` via `sessionAttribution` — matching this
+ * module's own `emitNarrativeEvent` above rather than the CLI's 2-arg
+ * `emitEvent` call, because `mirrorNarrative` (unlike the CLI) already always
+ * carries a `repoRoot` to attribute against.
+ *
+ * Best-effort: never throws, never alters the mirror result.
+ *
+ * @param {{ repoRoot?: string, needleCount: number, hits: number, dryRun: boolean }} opts
+ * @returns {Promise<void>}
+ */
+async function emitMaskerEvent({ repoRoot, needleCount, hits, dryRun }) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return;
+  try {
+    await emitEvent(
+      'orchestrator.secret_masker.applied',
+      {
+        channel: 'narrative-mirror',
+        needle_count: needleCount,
+        records: 1,
+        hits,
+        dry_run: dryRun,
+        ...sessionAttribution(repoRoot),
+      },
+      { repoRoot },
+    );
+  } catch {
+    /* Best-effort telemetry — see emitNarrativeEvent above for why. */
+  }
+}
+
 // ── Convenience orchestration ────────────────────────────────────────────────────
 
 /**
@@ -740,42 +809,62 @@ export async function mirrorNarrative(opts) {
     chars: outcome.chars,
   });
 
+  // #1028 residue 2: the masker-telemetry sibling of the narrative event
+  // above, on every non-throwing outcome (including skips) — see
+  // emitMaskerEvent for why this fires unconditionally.
+  await emitMaskerEvent({
+    repoRoot: opts?.repoRoot,
+    needleCount: outcome.needleCount,
+    hits: outcome.hits,
+    dryRun: outcome.dryRun,
+  });
+
   return outcome.result;
 }
 
 /**
  * The mirror itself — every early return of {@link mirrorNarrative} lives here.
  *
- * Split out so that exactly ONE emit site covers EVERY outcome: a future early
- * return added inside this function is telemetered by construction, whereas
- * hand-placing an emit beside each of the seven `return`s makes "forgot the new
- * one" the default failure. The `chars` companion travels beside the result
+ * Split out so that the two emit sites in `mirrorNarrative` (the narrative
+ * event AND, since #1028, the masker event) each cover EVERY outcome from
+ * ONE call: a future early return added inside this function is telemetered
+ * by construction, whereas hand-placing an emit beside each of the seven
+ * `return`s makes "forgot the new one" the default failure. The `chars` companion travels beside the result
  * rather than inside it because the returned object is a PUBLIC shape that
  * callers (and tests) compare with `toEqual` — adding a key there would be an
  * observable contract change for a purely internal measurement.
  *
  * @param {Parameters<typeof mirrorNarrative>[0]} opts
- * @returns {Promise<{ result: { action: string, path?: string }, chars?: number }>}
+ * @returns {Promise<{ result: { action: string, path?: string }, chars?: number, needleCount: number, hits: number, dryRun: boolean }>}
  */
 async function runNarrativeMirror(opts) {
   const { repoRoot, repo, now = new Date(), dryRun = false, fs: injectedFs, hostPaths } = opts;
 
   if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
-    return { result: { action: 'skipped-vault-disabled' } };
+    return { result: { action: 'skipped-vault-disabled' }, needleCount: 0, hits: 0, dryRun };
   }
 
+  // #1028: the masker is built ONCE per run, right here — before every
+  // remaining early-return below — so `mirrorNarrative`'s
+  // `orchestrator.secret_masker.applied` emit always carries a REAL measured
+  // `needle_count` on every outcome (including a skip), rather than a
+  // defaulted 0 that would be indistinguishable from "the masker never ran".
+  // Same "force-build, never default" posture as `getMaskerStats()` in
+  // `scripts/lib/vault-mirror/process.mjs`.
+  const masker = createSecretValueMasker(process.env);
+
   // Read Session Config (CLAUDE.md / AGENTS.md) and resolve vault settings.
   let config;
   try {
     const configText = await readConfigFile(repoRoot);
     config = parseSessionConfig(configText, { hostPaths });
   } catch {
-    return { result: { action: 'skipped-vault-disabled' } };
+    return { result: { action: 'skipped-vault-disabled' }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
   const vaultIntegration = config?.['vault-integration'];
   if (!vaultIntegration || vaultIntegration.enabled !== true) {
-    return { result: { action: 'skipped-vault-disabled' } };
+    return { result: { action: 'skipped-vault-disabled' }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
   // Defense-in-depth: when the caller omits (or passes an empty) `repo`, derive
@@ -792,10 +881,10 @@ async function runNarrativeMirror(opts) {
 
   const rawVaultDir = vaultIntegration['vault-dir'];
   if (!rawVaultDir || typeof rawVaultDir !== 'string') {
-    return { result: { action: 'skipped-vault-disabled' } };
+    return { result: { action: 'skipped-vault-disabled' }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
-  const vaultDir = path.resolve(expandHome(rawVaultDir));
+  const vaultDir = path.resolve(expandTilde(rawVaultDir));
   const candidateSlug = subjectToSlug(repoName) || 'unknown';
   // Loose-match against existing 01-projects/ folders before minting a new
   // slug (issue #829 Finding 3) — see resolveLooseSlug for the ambiguity
@@ -816,7 +905,7 @@ async function runNarrativeMirror(opts) {
     canonicalizeRoot: true,
   });
   if (!inside.ok) {
-    return { result: { action: 'skipped-invalid-path', path: outputPath } };
+    return { result: { action: 'skipped-invalid-path', path: outputPath }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
   // Read STATE.md (best-effort; absent STATE.md → nothing to mirror).
@@ -825,13 +914,13 @@ async function runNarrativeMirror(opts) {
   try {
     stateContents = await readFile(stateMdPath, 'utf8');
   } catch {
-    return { result: { action: 'skipped-no-statemd', path: outputPath } };
+    return { result: { action: 'skipped-no-statemd', path: outputPath }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
   // #1025: the ONE masking site for the narrative mirror — after the frontmatter
   // parse (so `[REDACTED]` can never break it) and before the render, the
   // idempotency comparison and the write. See maskNarrative above.
-  const narrative = maskNarrative(extractNarrative(stateContents));
+  const { narrative, hits } = maskNarrative(extractNarrative(stateContents), masker);
   const content = renderNarrative({ repo: repoName, narrative, now });
 
   // `chars` measures the document THIS call rendered — so it is present on
@@ -840,5 +929,8 @@ async function runNarrativeMirror(opts) {
   return {
     result: writeNarrative({ outputPath, content, dryRun, fs: injectedFs }),
     chars: content.length,
+    needleCount: masker.needleCount,
+    hits,
+    dryRun,
   };
 }

package/scripts/lib/wave-executor/dispatch-common.mjs

@@ -0,0 +1,164 @@
+/**
+ * dispatch-common.mjs — shared base for the two foreign-dispatch adapters:
+ * `foreign-dispatch.mjs` (Cursor channel, `cursor-agent`) and
+ * `remote-dispatch.mjs` (remote-host channel, `offload`). Two adapters, one
+ * base (#1204).
+ *
+ * These six symbols moved here because each one is an enforcement point or a
+ * budget constant that must NOT diverge between the two channels: the
+ * `never_foreign` role lock, the run-id path-segment validator, the
+ * SIGTERM→SIGKILL child runner, and the two dispatch-budget constants. Before
+ * this module existed, `remote-dispatch.mjs` imported all five from
+ * `foreign-dispatch.mjs` directly — a Cursor-specific file acting as a shared
+ * base for a channel that has nothing to do with Cursor. Both adapters now
+ * import from here instead, so neither exports something the other must reach
+ * through.
+ *
+ * Revisit-Trigger: if a THIRD dispatch channel ever needs a different budget
+ * default or a different never-foreign list, split the constant per-channel
+ * at that point rather than overriding it at the call site — a call-site
+ * override would silently diverge from the one enforcement point this module
+ * exists to be.
+ */
+
+/**
+ * Roles that may NEVER run on a foreign model. Copied verbatim from
+ * account-switch `tools/routing/routing.yaml` § never_foreign (read 2026-08-25).
+ * Keep in sync by hand — the YAML lives in a different repo and is parsed there
+ * by awk, not by a shared library.
+ * @type {readonly string[]}
+ */
+export const NEVER_FOREIGN_ROLES = Object.freeze([
+  'impl-core',
+  'security-review',
+  'migration',
+  'release',
+  'secrets',
+  'incident',
+  'refactor-crosscut',
+]);
+
+/** Default wall-clock budget for one foreign dispatch, in seconds.
+ * This is a FLOOR, not a suggestion: measured 2026-08-23, `cursor-grok-4.6-high`
+ * ran 2 of 3 hard-test tasks past a 540 s cap (recorded as DNF). Lowering this
+ * manufactures timeouts and reads as model failure. */
+export const DEFAULT_TIMEOUT_SEC = 900;
+
+/**
+ * Grace period between SIGTERM and SIGKILL, in ms.
+ *
+ * `child.kill('SIGTERM')` is a REQUEST: a child that installs a handler and
+ * ignores it never emits `close`, and this module's only resolve paths are
+ * `close` and `error` — so without escalation a wedged `cursor-agent` hangs
+ * `dispatchForeign` forever and takes the whole wave with it. SIGKILL is not
+ * catchable, so the escalation always terminates.
+ *
+ * Named ceiling (BV-004): 10 s is enough for a cooperative child to flush its
+ * stream-json tail and exit. Revisit if a well-behaved `cursor-agent` is ever
+ * measured needing longer than that to shut down — raise the constant, never
+ * drop the escalation.
+ */
+export const DEFAULT_KILL_GRACE_MS = 10_000;
+
+/** A runId names a directory and a log file. Anything outside this alphabet —
+ * or the two relative-path literals the alphabet happens to admit — can escape
+ * the parent it is joined to. */
+const SAFE_RUN_ID = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * @param {unknown} runId
+ * @returns {boolean} true when the id is safe to use as a path segment.
+ */
+export function isSafeRunId(runId) {
+  const s = String(runId ?? '');
+  if (s === '.' || s === '..') return false; // admitted by SAFE_RUN_ID, still an escape
+  return SAFE_RUN_ID.test(s);
+}
+
+/**
+ * @param {string} role
+ * @returns {boolean} true when the role is locked to Claude.
+ */
+export function isNeverForeignRole(role) {
+  return NEVER_FOREIGN_ROLES.includes(String(role || '').trim());
+}
+
+/**
+ * Run the child process, capturing stdout+stderr merged, with a hand-rolled
+ * SIGTERM timeout that ESCALATES to SIGKILL. `spawnFn` is the DI seam so tests
+ * never touch the real `cursor-agent` binary.
+ *
+ * The escalation is the difference between a bounded dispatch and a hung wave:
+ * this function's only resolve paths are the child's `close` and `error`
+ * events, so a child that ignores SIGTERM never lets the promise settle. See
+ * {@link DEFAULT_KILL_GRACE_MS}.
+ *
+ * @returns {Promise<{capture: string, exitCode: number|null, signal: string|null,
+ *   timerFired: boolean, killSignals: string[], errorCode: string|null}>}
+ */
+export function runChild(cmd, args, options, { spawnFn, timeoutMs, killGraceMs }) {
+  return new Promise((resolve) => {
+    /** @type {string[]} */
+    const killSignals = [];
+    let child;
+    try {
+      child = spawnFn(cmd, args, options);
+    } catch (err) {
+      resolve({
+        capture: `spawn failed: ${err && err.message}`,
+        exitCode: null,
+        signal: null,
+        timerFired: false,
+        killSignals,
+        errorCode: (err && err.code) || null,
+      });
+      return;
+    }
+
+    let capture = '';
+    let timerFired = false;
+    let settled = false;
+    let errorCode = null;
+    /** @type {ReturnType<typeof setTimeout>|null} */
+    let graceTimer = null;
+
+    const onChunk = (chunk) => {
+      capture += chunk.toString();
+    };
+    child.stdout?.on('data', onChunk);
+    child.stderr?.on('data', onChunk);
+
+    const send = (signal) => {
+      killSignals.push(signal);
+      try {
+        child.kill(signal);
+      } catch {
+        /* already gone */
+      }
+    };
+
+    const timer = setTimeout(() => {
+      timerFired = true;
+      send('SIGTERM');
+      // SIGTERM is a request; SIGKILL is not. A child that installs a handler
+      // and declines to exit would otherwise hang this promise forever.
+      graceTimer = setTimeout(() => send('SIGKILL'), killGraceMs);
+      graceTimer.unref?.();
+    }, timeoutMs);
+
+    const finish = (exitCode, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (graceTimer) clearTimeout(graceTimer);
+      resolve({ capture, exitCode, signal, timerFired, killSignals, errorCode });
+    };
+
+    child.on('error', (err) => {
+      errorCode = (err && err.code) || null;
+      capture += `\nchild error: ${err && err.message}`;
+      finish(null, null);
+    });
+    child.on('close', (code, signal) => finish(code, signal ?? null));
+  });
+}

package/scripts/lib/wave-executor/foreign-dispatch.mjs

@@ -54,45 +54,13 @@ import path from 'node:path';
 
 import { emitEvent, sessionAttribution } from '../events.mjs';
 import { isPathInside } from '../path-utils.mjs';
-
-/**
- * Roles that may NEVER run on a foreign model. Copied verbatim from
- * account-switch `tools/routing/routing.yaml` § never_foreign (read 2026-08-25).
- * Keep in sync by hand — the YAML lives in a different repo and is parsed there
- * by awk, not by a shared library.
- * @type {readonly string[]}
- */
-export const NEVER_FOREIGN_ROLES = Object.freeze([
-  'impl-core',
-  'security-review',
-  'migration',
-  'release',
-  'secrets',
-  'incident',
-  'refactor-crosscut',
-]);
-
-/** Default wall-clock budget for one foreign dispatch, in seconds.
- * This is a FLOOR, not a suggestion: measured 2026-08-23, `cursor-grok-4.6-high`
- * ran 2 of 3 hard-test tasks past a 540 s cap (recorded as DNF). Lowering this
- * manufactures timeouts and reads as model failure. */
-export const DEFAULT_TIMEOUT_SEC = 900;
-
-/**
- * Grace period between SIGTERM and SIGKILL, in ms.
- *
- * `child.kill('SIGTERM')` is a REQUEST: a child that installs a handler and
- * ignores it never emits `close`, and this module's only resolve paths are
- * `close` and `error` — so without escalation a wedged `cursor-agent` hangs
- * `dispatchForeign` forever and takes the whole wave with it. SIGKILL is not
- * catchable, so the escalation always terminates.
- *
- * Named ceiling (BV-004): 10 s is enough for a cooperative child to flush its
- * stream-json tail and exit. Revisit if a well-behaved `cursor-agent` is ever
- * measured needing longer than that to shut down — raise the constant, never
- * drop the escalation.
- */
-export const DEFAULT_KILL_GRACE_MS = 10_000;
+import {
+  DEFAULT_KILL_GRACE_MS,
+  DEFAULT_TIMEOUT_SEC,
+  isNeverForeignRole,
+  isSafeRunId,
+  runChild,
+} from './dispatch-common.mjs';
 
 /**
  * argv prefix for every foreign dispatch, ahead of `--model`/`--output-format`.
@@ -156,29 +124,6 @@ export const FOREIGN_ENV_ALLOWLIST = Object.freeze([
  * directory named this way. */
 export const FOREIGN_TMP_PREFIX = 'so-foreign';
 
-/** A runId names a directory and a log file. Anything outside this alphabet —
- * or the two relative-path literals the alphabet happens to admit — can escape
- * the parent it is joined to. */
-const SAFE_RUN_ID = /^[A-Za-z0-9._-]+$/;
-
-/**
- * @param {unknown} runId
- * @returns {boolean} true when the id is safe to use as a path segment.
- */
-function isSafeRunId(runId) {
-  const s = String(runId ?? '');
-  if (s === '.' || s === '..') return false; // admitted by SAFE_RUN_ID, still an escape
-  return SAFE_RUN_ID.test(s);
-}
-
-/**
- * @param {string} role
- * @returns {boolean} true when the role is locked to Claude.
- */
-export function isNeverForeignRole(role) {
-  return NEVER_FOREIGN_ROLES.includes(String(role || '').trim());
-}
-
 /**
  * Build the allowlisted child environment.
  * @param {Record<string, string|undefined>} [source]
@@ -317,86 +262,6 @@ export function parseCursorStream(raw) {
  */
 export const MEASUREMENT_EXCLUDES = Object.freeze(['node_modules']);
 
-/**
- * Run the child process, capturing stdout+stderr merged, with a hand-rolled
- * SIGTERM timeout that ESCALATES to SIGKILL. `spawnFn` is the DI seam so tests
- * never touch the real `cursor-agent` binary.
- *
- * The escalation is the difference between a bounded dispatch and a hung wave:
- * this function's only resolve paths are the child's `close` and `error`
- * events, so a child that ignores SIGTERM never lets the promise settle. See
- * {@link DEFAULT_KILL_GRACE_MS}.
- *
- * @returns {Promise<{capture: string, exitCode: number|null, signal: string|null,
- *   timerFired: boolean, killSignals: string[], errorCode: string|null}>}
- */
-function runChild(cmd, args, options, { spawnFn, timeoutMs, killGraceMs }) {
-  return new Promise((resolve) => {
-    /** @type {string[]} */
-    const killSignals = [];
-    let child;
-    try {
-      child = spawnFn(cmd, args, options);
-    } catch (err) {
-      resolve({
-        capture: `spawn failed: ${err && err.message}`,
-        exitCode: null,
-        signal: null,
-        timerFired: false,
-        killSignals,
-        errorCode: (err && err.code) || null,
-      });
-      return;
-    }
-
-    let capture = '';
-    let timerFired = false;
-    let settled = false;
-    let errorCode = null;
-    /** @type {ReturnType<typeof setTimeout>|null} */
-    let graceTimer = null;
-
-    const onChunk = (chunk) => {
-      capture += chunk.toString();
-    };
-    child.stdout?.on('data', onChunk);
-    child.stderr?.on('data', onChunk);
-
-    const send = (signal) => {
-      killSignals.push(signal);
-      try {
-        child.kill(signal);
-      } catch {
-        /* already gone */
-      }
-    };
-
-    const timer = setTimeout(() => {
-      timerFired = true;
-      send('SIGTERM');
-      // SIGTERM is a request; SIGKILL is not. A child that installs a handler
-      // and declines to exit would otherwise hang this promise forever.
-      graceTimer = setTimeout(() => send('SIGKILL'), killGraceMs);
-      graceTimer.unref?.();
-    }, timeoutMs);
-
-    const finish = (exitCode, signal) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (graceTimer) clearTimeout(graceTimer);
-      resolve({ capture, exitCode, signal, timerFired, killSignals, errorCode });
-    };
-
-    child.on('error', (err) => {
-      errorCode = (err && err.code) || null;
-      capture += `\nchild error: ${err && err.message}`;
-      finish(null, null);
-    });
-    child.on('close', (code, signal) => finish(code, signal ?? null));
-  });
-}
-
 /** Read `git` output as text, returning '' on failure (a detached worktree with
  * no commits still answers, but a broken invocation must not throw here). */
 function gitText(args, execFn) {