pi-daddy 0.28.0 → 0.32.0

package/src/kernel/run-child.ts

@@ -0,0 +1,418 @@
+/**
+ * Run a governed child process under hard limits.
+ *
+ * G8 (review findings A-R1/B-I5, A-R3). `delegate` used to spawn `pi` with no output cap, no timeout,
+ * an abort listener attached too late to observe an already-aborted signal, and a non-zero exit reported
+ * to the model as an ordinary result. Each of those is a way for a child to outlive or overwhelm the
+ * orchestrator that is supposed to be governing it — which is the whole premise of this package.
+ *
+ * It lives here, out of `extensions/grants.ts`, so it can be tested against real processes without pi.
+ */
+
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import { parseBound } from "./propagation.ts";
+import { ENV_CHILD_IDLE_TIMEOUT, ENV_CHILD_TIMEOUT } from "./env-names.ts";
+export { ENV_CHILD_IDLE_TIMEOUT, ENV_CHILD_TIMEOUT } from "./env-names.ts";
+
+interface RunChildTestControl {
+  hardDeadlineAtAfterSpawn(): number;
+}
+const TEST_CONTROL = Symbol.for("pi-daddy.internal.run-child-test-control");
+
+function currentRunChildTestControl(): RunChildTestControl | undefined {
+  if (process.env.NODE_TEST_CONTEXT !== "child-v8") return undefined;
+  const storage = (globalThis as Record<symbol, { getStore(): RunChildTestControl | undefined }>)[TEST_CONTROL];
+  return storage?.getStore();
+}
+
+/**
+ * The longest prefix of `text` that fits in `budget` BYTES, never splitting a character.
+ *
+ * Both halves matter. Truncating by `String.prototype.slice` counts UTF-16 code units against a byte budget,
+ * which overruns by the encoding width of whatever the child printed. Truncating the *buffer* instead would
+ * respect the budget and split a multi-byte character or a surrogate pair, putting a lone `\ud83d` in the
+ * result. So the walk is by code POINT (`for…of` iterates code points, keeping surrogate pairs whole) and the
+ * budget is checked in bytes before each one is admitted.
+ *
+ * Exported for the test that feeds it CJK and emoji: an ASCII-only test cannot fail on any of this, which is
+ * exactly why the original defect survived a test named for it.
+ */
+export function takeBytes(text: string, budget: number): string {
+  if (budget <= 0) return "";
+  if (Buffer.byteLength(text) <= budget) return text;
+  let out = "";
+  let used = 0;
+  for (const character of text) {
+    const size = Buffer.byteLength(character);
+    if (used + size > budget) break;
+    out += character;
+    used += size;
+  }
+  return out;
+}
+
+/**
+ * Operator override for the child wall-clock limit, in seconds.
+ *
+ * Deliberately NOT in `GRANT_ENV_KEYS`: those are stripped from a child's environment and re-supplied
+ * only by the spawn plan, which is right for capability state and wrong for an operator preference. This
+ * one should simply inherit, so a bound set at the root applies all the way down.
+ */
+
+/** Read the override, falling back to the default on absent *or* malformed input (G7's rule). */
+export function timeoutFromEnv(raw: string | undefined): number {
+  const seconds = parseBound(raw);
+  // `null` (malformed) and `0` both fall back rather than disabling the limit: a timeout that can be
+  // switched off by a typo is the A-S4 defect wearing different clothes.
+  return seconds === undefined || seconds === null || seconds === 0 ? DEFAULT_TIMEOUT_MS : seconds * 1000;
+}
+
+/** The inactivity bound, same rule: absent, malformed and zero all select the default rather than disabling it. */
+export function idleTimeoutFromEnv(raw: string | undefined): number {
+  const seconds = parseBound(raw);
+  return seconds === undefined || seconds === null || seconds === 0 ? DEFAULT_IDLE_TIMEOUT_MS : seconds * 1000;
+}
+
+export interface ChildRunRequest {
+  command: string;
+  args: string[];
+  env: NodeJS.ProcessEnv;
+  cwd: string;
+  signal?: AbortSignal;
+  /** Hard cap on captured output. Beyond it the child is killed and the result flagged. */
+  maxOutputBytes?: number;
+  /** Wall-clock ceiling. On expiry: SIGTERM, then SIGKILL after `killGraceMs`. A runaway bound, not the working bound. */
+  timeoutMs?: number;
+  killGraceMs?: number;
+  /**
+   * Inactivity bound (ADR-0038 note, PR 3e): the child is stopped when this long passes with no activity. Activity
+   * is any stdout/stderr byte, or a change in what `activityProbe` returns. Undefined means no inactivity bound.
+   */
+  idleTimeoutMs?: number;
+  /**
+   * A cheap marker of the child's progress that is not on its stdout, polled every `activityProbeIntervalMs`: the
+   * size and mtime of its pi session file, which pi appends to on every message and tool result. A change resets
+   * the inactivity clock; `undefined` (file not there yet) counts as no change. Never awaited on the control path.
+   */
+  activityProbe?: () => Promise<string | number | undefined> | string | number | undefined;
+  activityProbeIntervalMs?: number;
+  /** Absolute epoch-millisecond hard cap: SIGKILL fires here even when the SIGTERM grace has not elapsed. */
+  hardDeadlineAt?: number;
+  /**
+   * Called with each chunk as it arrives, for the parent's progress display (ADR-0032).
+   *
+   * **Display only, and the distinction is load-bearing.** The child's answer is still `text`, assembled here
+   * and returned; a caller must never treat what it saw streamed as the result. A partial stream that could be
+   * mistaken for a complete answer is R-03's defect — a missing result indistinguishable from an empty one —
+   * with a new cause.
+   *
+   * Bounded by the same `maxOutputBytes` as `text`, so the cap governs the transcript and not merely memory.
+   *
+   * Exceptions are swallowed: a renderer is not a governance control, and one that throws must not kill a
+   * governed child mid-task.
+   */
+  onOutput?: (chunk: string) => void;
+  /** Optional raw observation; isolated from control, never awaited, separate from display text. */
+  onObservation?: (stream: "stdout" | "stderr", bytes: Uint8Array) => void;
+  /** Passive EOF observation. Never a replacement child/settlement handle. Exceptions are isolated. */
+  onStreamEnd?: (stream: "stdout" | "stderr") => void;
+  /** Security hook called immediately after spawn, before output handling (for lease attachment). */
+  onSpawn?: (pid: number) => void;
+}
+
+export interface ChildRunResult {
+  /** Exit code, or `null` when nothing was spawned or the child was killed by a signal. */
+  code: number | null;
+  text: string;
+  truncated: boolean;
+  timedOut: boolean;
+  /** Set with `timedOut` when it was the inactivity bound, not the wall-clock ceiling, that stopped the child. */
+  idle?: true;
+  aborted: boolean;
+  /** Signal that ended the process, separate from the nullable numeric exit code. */
+  signal?: NodeJS.Signals | null;
+  /** Set when the process could not be started at all. */
+  spawnError?: string;
+}
+
+/** 1 MiB. A delegation returns a summary; anything larger is a runaway, not an answer. */
+export const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
+/**
+ * Six hours (PR 3e, 2026-09-22). No longer the working bound: `DEFAULT_IDLE_TIMEOUT_MS` is what stops a hung child.
+ * This is the runaway ceiling for a child that keeps producing events forever, and it exists so that no typo in the
+ * inactivity variable can make a child unbounded. The history: ten minutes, twenty (ADR-0038), sixty (its note), each
+ * time because a working child was cut off by a wall clock that cannot tell working from hung.
+ */
+export const DEFAULT_TIMEOUT_MS = 6 * 60 * 60 * 1000;
+/** Fifteen minutes with no stdout byte and no session-file change. A hung child is a silent one; a build is not. */
+export const DEFAULT_IDLE_TIMEOUT_MS = 15 * 60 * 1000;
+export const DEFAULT_ACTIVITY_PROBE_INTERVAL_MS = 2000;
+/** Grace between SIGTERM and SIGKILL. A child that ignores SIGTERM must not make the timeout advisory. */
+export const DEFAULT_KILL_GRACE_MS = 5000;
+
+export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
+  const testControl = currentRunChildTestControl();
+  const maxOutputBytes = request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const killGraceMs = request.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+  const hardDeadlineAt = request.hardDeadlineAt;
+
+  // A-R3: checked BEFORE spawning. `AbortSignal` does not replay, so a listener attached after an
+  // `await` cannot observe an abort that already happened — and the child would then run to completion
+  // outside the cancellation that was supposed to stop it. Nothing is started at all here.
+  if (request.signal?.aborted) {
+    return Promise.resolve({ code: null, text: "", truncated: false, timedOut: false, aborted: true });
+  }
+
+  return new Promise<ChildRunResult>((settle) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(request.command, request.args, {
+        env: request.env,
+        cwd: request.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      settle({ code: null, text: "", truncated: false, timedOut: false, aborted: false, spawnError: String(error) });
+      return;
+    }
+    try {
+      if (child.pid !== undefined) request.onSpawn?.(child.pid);
+    } catch (error) {
+      const failed = {
+        code: null,
+        text: "",
+        truncated: false,
+        timedOut: false,
+        aborted: false,
+        spawnError: String(error),
+      };
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      child.once("error", () => settle(failed));
+      child.once("close", () => settle(failed));
+      child.kill("SIGKILL");
+      return;
+    }
+
+    // One decoder for BOTH streams is deliberate: they are already interleaved into one `text`, and two
+    // decoders would each hold their own partial character, so a split byte could surface out of order.
+    const decoder = new StringDecoder("utf8");
+    let text = "";
+    let bytes = 0;
+    let truncated = false;
+    let timedOut = false;
+    let idle = false;
+    let aborted = false;
+    let done = false;
+
+    const timers: NodeJS.Timeout[] = [];
+    const clearTimers = () => timers.forEach(clearTimeout);
+
+    /** SIGTERM, then SIGKILL if the child is still alive — so a handler cannot ignore its way out. */
+    const stop = () => {
+      child.kill("SIGTERM");
+      timers.push(setTimeout(() => child.kill("SIGKILL"), killGraceMs));
+    };
+
+    // A timer phase may run before libuv delivers an exit that the OS already observed, especially after the
+    // controller event loop was blocked across the deadline. Give pending child-process events one turn to
+    // publish exitCode/signalCode before deciding that a governed PID is still live.
+    const controlIfRunning = (control: () => void) => {
+      setImmediate(() => {
+        if (done || child.exitCode !== null || child.signalCode !== null) return;
+        control();
+      });
+    };
+
+    /** How much of `text` the progress display has already been shown. */
+    let emittedUpTo = 0;
+
+    /**
+     * Stream whatever `text` has gained since the last call.
+     *
+     * **Derived from `text` rather than from the incoming chunk**, and that is the whole correctness argument:
+     * what gets streamed is then *by construction* a prefix of what gets returned, so the output cap bounds the
+     * parent's transcript exactly as it bounds the result. The first version emitted the raw chunk and pushed
+     * 1924 bytes through a 1024-byte cap on the truncating write — the cap bounded memory and not the screen
+     * it had just been extended to protect. Found by the test, not by reading it.
+     *
+     * Swallowing is deliberate: `onOutput` renders, and a renderer that throws must not become a way to kill a
+     * governed child. Nothing downstream depends on it having run.
+     */
+    const flush = () => {
+      if (!request.onOutput || text.length <= emittedUpTo) return;
+      const chunk = text.slice(emittedUpTo);
+      emittedUpTo = text.length;
+      try {
+        request.onOutput(chunk);
+      } catch {
+        /* display only */
+      }
+    };
+
+    const capture = (chunk: unknown) => {
+      if (truncated) return;
+      // **Decoded through a StringDecoder, not `String(chunk)`.** A pipe splits on byte boundaries, not
+      // character ones, so a multi-byte character straddling two `data` events was decoded as two invalid
+      // halves and became U+FFFD — in the child's ANSWER, not merely the display. Measured: 300,000 bytes of
+      // CJK produced **twelve** replacement characters, because 65536 % 3 == 1. Emoji happened to survive
+      // (65536 % 4 == 0), which is why width-dependent corruption went unnoticed. The decoder holds the
+      // partial bytes until the rest arrives.
+      const s = decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+      if (s.length === 0) return;
+
+      const size = Buffer.byteLength(s);
+      if (bytes + size > maxOutputBytes) {
+        // Keep what fits, mark it, and stop the child: an unbounded producer must not be able to exhaust the
+        // orchestrator's memory just because it was granted a tool that prints.
+        //
+        // **Trimmed by BYTES, and that is a fix rather than a refinement.** This was
+        // `text.slice(0, maxOutputBytes)` — a count of UTF-16 code units against a budget measured in bytes,
+        // so any non-ASCII output overran the cap by its own encoding width: 300 bytes of CJK through a
+        // 100-byte cap, and a measured **2048 bytes through the real 1024 default**. It is the same defect as
+        // the 1924-byte one already fixed here, one layer down: that fix bounded the *unit* count, and the
+        // budget was never in units. An odd cap also split a surrogate pair, putting a lone `\ud83d` into
+        // both the transcript and the returned answer.
+        text += takeBytes(s, maxOutputBytes - bytes);
+        bytes = maxOutputBytes;
+        truncated = true;
+        flush();
+        stop();
+        return;
+      }
+      bytes += size;
+      text += s;
+      flush();
+    };
+
+    const observe = (stream: "stdout" | "stderr", chunk: Buffer) => {
+      armIdle();
+      capture(chunk);
+      try {
+        request.onObservation?.(stream, chunk);
+      } catch {
+        /* observation only */
+      }
+    };
+    child.stdout?.on("data", (chunk: Buffer) => observe("stdout", chunk));
+    child.stderr?.on("data", (chunk: Buffer) => observe("stderr", chunk));
+    for (const stream of ["stdout", "stderr"] as const)
+      child[stream]?.on("end", () => {
+        try {
+          request.onStreamEnd?.(stream);
+        } catch {
+          /* passive observation only */
+        }
+      });
+
+    timers.push(
+      setTimeout(
+        () =>
+          controlIfRunning(() => {
+            timedOut = true;
+            stop();
+          }),
+        timeoutMs,
+      ),
+    );
+
+    // The inactivity bound. Re-armed by every output byte and by every probe change; a child that is working but
+    // quiet on stdout (a build, a long tool call) keeps its session file growing, and that is enough.
+    let idleTimer: NodeJS.Timeout | undefined;
+    function armIdle(): void {
+      if (request.idleTimeoutMs === undefined || done) return;
+      if (idleTimer) clearTimeout(idleTimer);
+      idleTimer = setTimeout(
+        () =>
+          controlIfRunning(() => {
+            timedOut = true;
+            idle = true;
+            stop();
+          }),
+        request.idleTimeoutMs,
+      );
+    }
+    armIdle();
+    let probeTimer: NodeJS.Timeout | undefined;
+    if (request.idleTimeoutMs !== undefined && request.activityProbe) {
+      let lastMarker: string | number | undefined;
+      let probing = false;
+      probeTimer = setInterval(() => {
+        if (probing || done) return;
+        probing = true;
+        void Promise.resolve()
+          .then(() => request.activityProbe?.())
+          .then((marker) => {
+            if (marker !== undefined && marker !== lastMarker) {
+              lastMarker = marker;
+              armIdle();
+            }
+          })
+          .catch(() => undefined) // an unreadable probe is "no activity seen", never a control decision
+          .finally(() => {
+            probing = false;
+          });
+      }, request.activityProbeIntervalMs ?? DEFAULT_ACTIVITY_PROBE_INTERVAL_MS);
+    }
+    const activeHardDeadlineAt = testControl?.hardDeadlineAtAfterSpawn() ?? hardDeadlineAt;
+    if (activeHardDeadlineAt !== undefined) {
+      // Independent of the soft timer and measured from the recorded epoch, not from `spawn`: neither a
+      // delayed soft callback nor spawn/setup time may start a fresh grace period beyond the lifecycle bound.
+      timers.push(
+        setTimeout(
+          () =>
+            controlIfRunning(() => {
+              timedOut = true;
+              child.kill("SIGKILL");
+            }),
+          Math.max(0, activeHardDeadlineAt - Date.now()),
+        ),
+      );
+    }
+
+    const onAbort = () => {
+      aborted = true;
+      stop();
+    };
+    request.signal?.addEventListener("abort", onAbort, { once: true });
+
+    const finish = (result: ChildRunResult) => {
+      if (done) return;
+      done = true;
+      clearTimers();
+      if (idleTimer) clearTimeout(idleTimer);
+      if (probeTimer) clearInterval(probeTimer);
+      request.signal?.removeEventListener("abort", onAbort);
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      settle(result);
+    };
+
+    child.on("error", (error) =>
+      finish({
+        code: null,
+        text,
+        truncated,
+        timedOut,
+        ...(idle ? { idle: true } : {}),
+        aborted,
+        spawnError: String(error),
+      }),
+    );
+    // `close` waits for every inherited pipe, including one retained by a detached grandchild. Once the
+    // governed PID exits, allow a short drain and settle anyway so timeout/output bounds remain bounds.
+    child.on("exit", (code, signal) => {
+      timers.push(
+        setTimeout(
+          () => finish({ code, signal, text, truncated, timedOut, ...(idle ? { idle: true } : {}), aborted }),
+          100,
+        ),
+      );
+    });
+    child.on("close", (code, signal) =>
+      finish({ code, signal, text, truncated, timedOut, ...(idle ? { idle: true } : {}), aborted }),
+    );
+  });
+}