@gethmy/harness 1.0.0

package/src/oracle-collector.ts

@@ -0,0 +1,148 @@
+/**
+ * Evidence collector for the `oracle_passed` gate. It runs only AFTER the stage's
+ * subagent has exited (see stage-run.ts): the held test and a model must never
+ * share a filesystem window.
+ *
+ * It produces evidence and nothing else — `gateEvaluate` in @harmony/shared turns
+ * it into a verdict. A missing oracle is `blocked`, never `passed`: a gate with no
+ * signal cannot be satisfied.
+ *
+ * FIX ROUND 1 (Task 12 review, Important): `oracle_passed` is a SECRECY gate —
+ * the whole point of a held test is that the implementer never sees it. The
+ * persisted evidence must not leak it back out sideways. Telling the implementer
+ * WHY the held test failed is itself a partial oracle: an assertion diff
+ * ("expected X, got Y") hands over the test's expectations one failure at a
+ * time, which is just as much a leak as the file itself would be. So the raw
+ * runner output NEVER reaches `structured` — only `exitCode` and `path` do. The
+ * full output still goes to the motor's own local log (`log.info`/`log.warn`
+ * below) so a human operator can debug a red gate; that log is not the
+ * persisted evidence a stage-advance decision or an implementer-visible surface
+ * reads. `build_green`'s collector (`gate-collectors.ts`) keeps its raw output —
+ * deliberately: it is not a secrecy gate, and its output is exactly what a human
+ * needs to see. Do not "make them consistent."
+ */
+import type {
+  GateEvidence,
+  GateEvidenceCollector,
+  GateEvidenceContext,
+} from "@harmony/shared";
+import { log } from "./log.js";
+import type { HeldOracle, OracleDeps } from "./oracle.js";
+
+const TAG = "oracle-collector";
+
+export class OracleCollector implements GateEvidenceCollector {
+  readonly kind = "oracle_passed" as const;
+
+  constructor(private readonly deps: OracleDeps) {}
+
+  async collect(context: GateEvidenceContext): Promise<GateEvidence> {
+    const oracle = await this.deps.fetchOracle(
+      context.cardId,
+      context.stageId,
+      this.deps.sessionId,
+    );
+    if (!oracle) {
+      log.info(TAG, `No oracle held for stage ${context.stageId} — blocked`);
+      return {
+        result: "blocked",
+        structured: {
+          reason: `No oracle is held for stage ${context.stageId}.`,
+        },
+      };
+    }
+
+    return await this.runHeld(oracle);
+  }
+
+  private async runHeld(oracle: HeldOracle): Promise<GateEvidence> {
+    await this.deps.place(this.deps.repoPath, oracle);
+    try {
+      const { exitCode, output } = await this.deps.run(
+        this.deps.repoPath,
+        oracle,
+      );
+      // Full output is for the human operator's local log only — never the
+      // persisted evidence. See the class doc comment: oracle_passed is a
+      // secrecy gate, and an assertion diff is itself a partial oracle.
+      const logLine = `Oracle run for ${oracle.path} exited ${exitCode}:\n${output}`;
+      if (exitCode === 0) {
+        log.info(TAG, logLine);
+      } else {
+        log.warn(TAG, logLine);
+      }
+      return {
+        result: exitCode === 0 ? "passed" : "failed",
+        structured: {
+          oracle: {
+            exitCode,
+            path: oracle.path,
+            output:
+              "withheld — oracle_passed is a secrecy gate; see the motor's local log",
+          },
+        },
+      };
+    } catch (err) {
+      const message = errText(err);
+      log.warn(TAG, `Oracle run threw: ${message} — blocked`);
+      return {
+        result: "blocked",
+        structured: { oracle: { path: oracle.path }, error: message },
+      };
+    } finally {
+      // Always. A held test left in the worktree could be committed, which would
+      // hand the implementer the very file it must never see.
+      await this.removeBestEffort(oracle);
+    }
+  }
+
+  /**
+   * Remove the held test, and try ONCE more if that throws.
+   *
+   * `remove` is called from a `finally`, so a throw there would replace the
+   * evidence with the removal's own error AND leave the held test sitting in a
+   * worktree the daemon's completion path auto-commits — handing the
+   * implementer, and then the repo's history, the one file this gate exists to
+   * keep from it. Low likelihood (the path was already resolved for the write,
+   * and `rm` runs with `force: true`), high consequence.
+   *
+   * So: a second attempt, then give up LOUDLY. Deliberately not a retry
+   * framework — no backoff, no attempt budget. The realistic causes are a
+   * transient filesystem error, which one immediate retry covers, and a path
+   * the containment check refuses, which no number of retries will change.
+   *
+   * It never rethrows. The gate's own verdict — the exit code, or the `blocked`
+   * from a run that threw — is the honest answer about the implementer's work,
+   * and losing it to a cleanup failure would be a worse outcome than the failure
+   * itself. The loud log is what an operator acts on; the file is named in it so
+   * it can be deleted by hand.
+   */
+  private async removeBestEffort(oracle: HeldOracle): Promise<void> {
+    try {
+      await this.deps.remove(this.deps.repoPath, oracle);
+      return;
+    } catch (err) {
+      log.warn(
+        TAG,
+        `Removing the held test at ${oracle.path} failed (${errText(err)}) — retrying once`,
+      );
+    }
+    try {
+      await this.deps.remove(this.deps.repoPath, oracle);
+      log.info(
+        TAG,
+        `Held test at ${oracle.path} removed on the second attempt`,
+      );
+    } catch (err) {
+      log.error(
+        TAG,
+        `HELD TEST NOT REMOVED: ${oracle.path} is still in ${this.deps.repoPath} after two attempts (${errText(err)}). ` +
+          "It will be auto-committed by the completion path if it is left there — delete it by hand and check whether it reached a commit.",
+      );
+    }
+  }
+}
+
+function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/oracle.ts

@@ -0,0 +1,434 @@
+/**
+ * The oracle module: fetch a held test from Harmony, place it in the worktree, run
+ * it, remove it. One interface, one implementation — seam ready, no registry.
+ *
+ * The held test is never committed: `remove` runs in a finally block in
+ * `oracle-collector.ts`, so even a crashed runner cannot leave it behind.
+ *
+ * `fetchOracle` carries a `sessionId` (Task 11 review, ruling 27): the
+ * `/stage-oracle/fetch` read route binds the caller to the card's ACTIVE agent
+ * session — workspace membership alone is not sufficient, and an ended session is
+ * refused. `GateEvidenceContext` (the collector's per-call input) carries
+ * `cardId`/`stageId`/`gate`/`workspaceId` but no session id, so it cannot flow
+ * through `collect(context)`. It comes in through `OracleDeps` instead, set once
+ * when the deps are constructed for the run (the driver that claimed the stage
+ * knows its own session id and threads it in as a CLI flag — Task 15's real CLI
+ * wiring). `OracleCollector` reads `this.deps.sessionId` at call time, the same
+ * way it already reads `this.deps.repoPath`.
+ *
+ * `place` is a SECOND, independent lock on the file it writes (Task 11 review,
+ * ruling 27). The `/stage-oracle` write route validates `path` against a charset
+ * allow-list before a row is ever stored — that is the trust boundary where a
+ * caller-supplied path enters the system. But `place` is the function that
+ * actually opens a file on the motor host, and a charset allow-list only ever
+ * covers the traversal shapes someone thought of: round 1 of that route's own
+ * validator missed `.git/config`, which does not traverse at all but is code
+ * execution on the worktree's next git operation (`[core] hooksPath`/
+ * `fsmonitor`), in a worktree where the harness runs git constantly. `place`
+ * does not rely on the route alone — it re-derives safety from a property that
+ * holds regardless of what a charset list forgot: resolve the target against
+ * `repoPath` and refuse anything that does not land strictly inside it. A `..`
+ * segment needs no separate rule — resolving it is exactly what pushes the
+ * target outside `repoPath`, so the one containment check catches it too. An
+ * absolute path IS checked separately, because `path.resolve` treats a later
+ * absolute argument as replacing the base entirely, and — in the rare case it
+ * happens to resolve to somewhere inside `repoPath` anyway — accepting it would
+ * still break the "repo-relative path" contract the route promises. An empty
+ * path or `"."` is refused explicitly too (Task 12 review, fix round 1) — both
+ * lexically resolve to `repoPath` itself, which would otherwise pass the
+ * containment check and send `place` to open the worktree ROOT as a file (it
+ * fails safe today with an `EISDIR`, but only by filesystem accident).
+ *
+ * FIX ROUND 1 (Critical): the containment check above is `path.resolve` plus a
+ * string-prefix compare — purely LEXICAL, so it never touches the filesystem and
+ * cannot see a symlink. The worktree is populated by the IMPLEMENTER's own
+ * commits before this collector ever runs, so the implementer can turn any
+ * directory the author will plausibly use into a symlink pointing outside the
+ * tree, and the lexical check alone would wave the resulting path straight
+ * through (it resolves inside `repoPath` right up until the OS follows the
+ * symlink at write time). So `resolveContained` is now also filesystem-aware:
+ * after the lexical check passes, it walks every segment of the relative path
+ * under the (realpath'd) root and `lstat`s each one, refusing if any segment
+ * that already exists is a symlink. Chosen over "realpath the deepest existing
+ * ancestor and compare" because walking + `lstat`-ing each segment reads more
+ * directly as "no symlink anywhere in this path", the exact property under
+ * test, without a second resolve-and-compare step for the ancestor. `repoPath`
+ * itself is realpath'd ONCE, unconditionally, and is exempt from this walk — it
+ * is the trusted root the caller supplied (worktrees legitimately sit behind a
+ * symlink, e.g. macOS's `/tmp` → `/private/tmp`), and realpath-ing it keeps
+ * every later comparison self-consistent regardless.
+ *
+ * A rejected path throws — before any write — and is not caught here. It
+ * propagates out of `OracleCollector.collect` to the dispatcher's existing catch
+ * (`collectGateEvidence` in `gate-collectors.ts`), which reports `blocked`.
+ * Failing the gate rather than writing is the point.
+ */
+import type { ChildProcess } from "node:child_process";
+import { lstat, mkdir, realpath, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { DEFAULT_METRIC_TIMEOUT_MS } from "./exec-types.js";
+import { reapGroup, spawnInGroup, terminateGroup } from "./process-group.js";
+
+export interface HeldOracle {
+  path: string;
+  content: string;
+  runnerHint: string | null;
+}
+
+export interface OracleDeps {
+  repoPath: string;
+  /**
+   * The card's ACTIVE agent session id — see the module doc comment above for
+   * why this lives here rather than on `GateEvidenceContext`. Threaded straight
+   * into `fetchOracle`'s third argument.
+   */
+  sessionId: string;
+  /** Reads via POST /stage-oracle/fetch with purpose "gate_evaluation". */
+  fetchOracle(
+    cardId: string,
+    stageId: string,
+    sessionId: string,
+  ): Promise<HeldOracle | null>;
+  place(repoPath: string, oracle: HeldOracle): Promise<void>;
+  remove(repoPath: string, oracle: HeldOracle): Promise<void>;
+  /**
+   * Executes the placed held test. {@link runHeldOracle} is the implementation
+   * (Task 15): it picks the argv from `runnerHint` through an allow-list and
+   * REJECTS — rather than returning a non-zero exit code — whenever no verdict
+   * was produced, so `OracleCollector` reports `blocked` instead of `failed`.
+   */
+  run(
+    repoPath: string,
+    oracle: HeldOracle,
+  ): Promise<{ exitCode: number; output: string }>;
+}
+
+/**
+ * Resolve `relativePath` against `repoPath` and refuse an absolute path, an
+ * empty path or `"."`, anything that resolves outside `repoPath` (which is how
+ * a `..` segment is refused too — resolving one is exactly what pushes the
+ * target outside `repoPath`), and — the filesystem-aware check fix round 1
+ * added — anything reached through an existing symlink. See the module doc
+ * comment for the full account of why each check exists and why the symlink
+ * walk cannot be replaced by the lexical checks alone.
+ *
+ * The lexical containment compare is `root + sep`, never a bare
+ * `startsWith(root)` — a bare prefix compare would wrongly ALLOW a sibling
+ * directory that merely shares a string prefix (`/tmp/wt2` starts with
+ * `/tmp/wt`, but is not inside it).
+ */
+async function resolveContained(
+  repoPath: string,
+  relativePath: string,
+): Promise<string> {
+  if (isAbsolute(relativePath)) {
+    throw new Error(
+      `refusing to place an oracle at an absolute path: ${relativePath}`,
+    );
+  }
+  if (relativePath === "" || relativePath === ".") {
+    throw new Error(
+      `refusing to place an oracle at the empty/self path: "${relativePath}"`,
+    );
+  }
+
+  // `repoPath` itself is the trusted root and may legitimately BE a symlink
+  // (e.g. macOS's /tmp -> /private/tmp) — realpath it ONCE, unconditionally, so
+  // every later comparison is self-consistent regardless.
+  const root = await realpath(repoPath);
+  const target = resolve(root, relativePath);
+  if (target !== root && !target.startsWith(root + sep)) {
+    throw new Error(
+      `refusing to place an oracle outside the worktree: ${relativePath}`,
+    );
+  }
+
+  // Filesystem-aware, unlike the lexical check above: walk every segment of the
+  // relative path under `root` and refuse if any segment that already exists is
+  // a symlink. A segment that does NOT exist yet is not a redirection risk —
+  // `place` is about to create it — so a missing segment is skipped, not
+  // refused; `lstat` throwing (ENOENT) is exactly that "does not exist" signal.
+  let cursor = root;
+  for (const segment of relativePath.split("/")) {
+    cursor = resolve(cursor, segment);
+    const stat = await lstat(cursor).catch(() => null);
+    if (stat?.isSymbolicLink()) {
+      throw new Error(
+        `refusing an oracle path through a symlink component: ${relativePath}`,
+      );
+    }
+  }
+
+  return target;
+}
+
+/**
+ * The real `place`: write the held test's content into the worktree at
+ * `oracle.path`, after independently verifying containment (see
+ * `resolveContained`'s doc comment). Creates any missing parent directories.
+ * Throws — and writes nothing — when the path is rejected.
+ */
+export async function place(
+  repoPath: string,
+  oracle: HeldOracle,
+): Promise<void> {
+  const target = await resolveContained(repoPath, oracle.path);
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, oracle.content, "utf8");
+}
+
+/**
+ * The real `remove`: delete the placed held test. Shares `resolveContained` with
+ * `place` (same hardened, filesystem-aware check) so the two can never disagree
+ * about where a file is — a path a rejected write never touches is also never
+ * resolved-and-deleted under a differently shaped input.
+ */
+export async function remove(
+  repoPath: string,
+  oracle: HeldOracle,
+): Promise<void> {
+  const target = await resolveContained(repoPath, oracle.path);
+  await rm(target, { force: true });
+}
+
+// ---------------------------------------------------------------------------
+// run — execute the placed held test (Task 15, the amendment's ruling 30)
+// ---------------------------------------------------------------------------
+
+/**
+ * The runner allow-list. A `runner_hint` is author-supplied data that reached
+ * the database through an HTTP route, so it selects a FIXED argv here and is
+ * never interpolated into one. `path` is author-supplied too: it travels as one
+ * argv element and is never part of a command string — nothing below is ever
+ * parsed by a shell (`spawnInGroup` spawns without one).
+ *
+ * Both entries were verified by hand against a real runner before they were
+ * added; adding a third is one line plus the same verification. `npx
+ * --no-install` deliberately refuses to download a runner the repo does not
+ * already have: an absent runner must fail the gate, not fetch a package onto
+ * the motor's host mid-stage.
+ */
+const ORACLE_RUNNERS: Record<string, (path: string) => OracleRunnerArgv> = {
+  vitest: (path) => ({
+    command: "npx",
+    args: ["--no-install", "vitest", "run", path],
+  }),
+  bun: (path) => ({ command: "bun", args: ["test", path] }),
+};
+
+/** The hints {@link resolveOracleRunner} accepts, for the refusal message. */
+export const ORACLE_RUNNER_HINTS: readonly string[] =
+  Object.keys(ORACLE_RUNNERS).sort();
+
+/** A resolved executable + args, ready for `spawnInGroup`. */
+export interface OracleRunnerArgv {
+  command: string;
+  args: string[];
+}
+
+/**
+ * Cap on the runner output kept in memory. The output is a DIAGNOSTIC only —
+ * `oracle-collector.ts` withholds it from the persisted evidence and writes it
+ * to the motor's local log — so this truncates rather than killing the run the
+ * way `runMetricCommand` must (there, stdout IS the measurement, so a partial
+ * read would corrupt the number). Memory stays bounded either way, and the
+ * timeout still bounds the process.
+ */
+const ORACLE_OUTPUT_LIMIT = 64 * 1024;
+
+/** Grace windows for the escalating group termination on a timeout. Mirrors
+ * `command-metric.ts`'s ladder — a runner gets a moment to shut down cleanly
+ * before the group is SIGKILLed. */
+const ORACLE_SIGINT_GRACE_MS = 2_000;
+const ORACLE_SIGTERM_GRACE_MS = 3_000;
+
+/** How long to wait after the leader exits for its stdio pipes to deliver the
+ * tail of the output. Bounded for the same reason `command-metric.ts` bounds
+ * its own: a grandchild that left the group with `setsid()` holds the pipe open
+ * forever, and a run that already produced its exit code must not wait on it. */
+const ORACLE_DRAIN_GRACE_MS = 500;
+
+/**
+ * Choose the argv for a held test from its `runnerHint`, through the allow-list
+ * above. THROWS on an unknown or absent hint, naming both the hint and the
+ * accepted set.
+ *
+ * A throw — not a non-zero exit code — is what refuses an unknown hint, and the
+ * distinction is load-bearing. `OracleCollector` maps a non-zero exit to
+ * `failed` and a thrown error to `blocked` (oracle-collector.ts). Nothing ran
+ * here, so there is no signal about the implementer's work: `failed` would
+ * blame the implementer for a defect in the oracle's own declaration, and would
+ * spend the card's attempt budget re-running a stage that cannot change the
+ * answer. `blocked` is the honest report, and it can never satisfy the gate.
+ *
+ * The throw is caught by `OracleCollector.runHeld`'s OWN try/catch (not the
+ * dispatcher's in `collectGateEvidence`), which returns
+ * `{ result: "blocked", structured: { oracle: { path }, error } }` — so the
+ * reason travels with the block. The Task 15 amendment asked for the `blocked`
+ * outcome by way of "returning a non-zero result"; that mechanism would land on
+ * `failed` instead, so this follows the outcome it named, not the mechanism.
+ */
+export function resolveOracleRunner(oracle: HeldOracle): OracleRunnerArgv {
+  const hint = oracle.runnerHint?.trim().toLowerCase() ?? "";
+  // `Object.hasOwn`, never a bare lookup: an inherited key ("constructor",
+  // "toString") would otherwise resolve to a function and be called.
+  const build = Object.hasOwn(ORACLE_RUNNERS, hint)
+    ? ORACLE_RUNNERS[hint]
+    : undefined;
+  if (!build) {
+    throw new Error(
+      `refusing to run the held test: runner_hint ${JSON.stringify(
+        oracle.runnerHint,
+      )} is not in the motor's allow-list (${ORACLE_RUNNER_HINTS.join(", ")})`,
+    );
+  }
+  return build(argvPath(oracle.path));
+}
+
+/**
+ * The path as it enters the argv. The `./` prefix is what keeps a path that
+ * begins with `-` (a legal relative path, and one `place`'s containment check
+ * has no reason to refuse) from being read as a FLAG by the runner. It does not
+ * make the path safe on its own — containment does that, in `place`.
+ */
+function argvPath(path: string): string {
+  return path.startsWith("./") ? path : `./${path}`;
+}
+
+/**
+ * The real `OracleDeps.run`: execute the placed held test and report its exit
+ * code plus its output.
+ *
+ * Resolves `{ exitCode, output }` for any run that produced an exit code —
+ * including a non-zero one, which is the gate's `failed` signal and the normal
+ * outcome of a held test that the implementer has not satisfied yet. REJECTS
+ * when no verdict exists at all: an unknown runner hint, a missing binary, a
+ * timeout, or a termination by a signal nobody here sent. `OracleCollector`
+ * turns a rejection into `blocked`.
+ *
+ * This does not reuse `runMetricCommand` (command-metric.ts) even though it
+ * follows its supervision pattern closely, because the two contracts are
+ * opposites at the point that matters: `runMetricCommand` REJECTS on a non-zero
+ * exit and its rejection carries only stderr, so a failing held test would both
+ * lose its `failed` signal and drop the stdout where a test runner prints what
+ * failed. The three properties are the same ones #823 established there:
+ *
+ *   1. **Group leader.** `spawnInGroup` makes the child a process-group leader,
+ *      so a timeout signals the whole tree, not just the direct child.
+ *   2. **Reaped on every path.** The pgid is recorded at spawn and swept with
+ *      `reapGroup` when the promise settles — clean exit included.
+ *   3. **Non-blocking.** Nothing here occupies the event loop.
+ *
+ * `timeoutMs` defaults to the motor's existing {@link DEFAULT_METRIC_TIMEOUT_MS}
+ * rather than a second convention; the parameter exists so a test can use a
+ * short cap.
+ */
+export async function runHeldOracle(
+  repoPath: string,
+  oracle: HeldOracle,
+  timeoutMs: number = DEFAULT_METRIC_TIMEOUT_MS,
+): Promise<{ exitCode: number; output: string }> {
+  const { command, args } = resolveOracleRunner(oracle);
+
+  return await new Promise<{ exitCode: number; output: string }>(
+    (settleOk, settleErr) => {
+      let child: ChildProcess;
+      try {
+        child = spawnInGroup(command, args, {
+          cwd: repoPath,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+      } catch (err) {
+        // A synchronous spawn throw (unusable cwd, bad argv) — no group exists.
+        settleErr(err);
+        return;
+      }
+
+      // Record the pgid AT SPAWN: `reapGroup` addresses the group by number, so
+      // it still sweeps stragglers once the leader handle is spent.
+      const pgid = child.pid;
+      let output = "";
+      let settled = false;
+      let killing = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let drainTimer: ReturnType<typeof setTimeout> | undefined;
+
+      /** Settle once, and never without sweeping the group. */
+      const settle = (
+        failure: Error | null,
+        result?: { exitCode: number; output: string },
+      ): void => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        if (drainTimer) clearTimeout(drainTimer);
+        reapGroup(pgid);
+        if (failure) settleErr(failure);
+        else settleOk(result!);
+      };
+
+      // stdout and stderr both land in one buffer: a test runner splits its
+      // report across them, and the collector only ever hands this to a human.
+      const append = (chunk: Buffer): void => {
+        if (output.length >= ORACLE_OUTPUT_LIMIT) return;
+        output += chunk.toString("utf8");
+        if (output.length > ORACLE_OUTPUT_LIMIT) {
+          output = `${output.slice(0, ORACLE_OUTPUT_LIMIT)}\n… output truncated at ${ORACLE_OUTPUT_LIMIT} characters`;
+        }
+      };
+      child.stdout?.on("data", append);
+      child.stderr?.on("data", append);
+
+      // A missing binary surfaces as an async `error` event (an async spawn
+      // never throws it) — no verdict, so it rejects.
+      child.once("error", (err) => settle(err));
+
+      const settleFromExit = (
+        code: number | null,
+        signal: NodeJS.Signals | null,
+      ): void => {
+        if (drainTimer) clearTimeout(drainTimer);
+        if (code === null) {
+          // A signal nobody here sent (an operator's `kill`, the OOM killer).
+          // The held test produced no verdict, so this is not a `failed` gate.
+          settle(new Error(`the held test was terminated by signal ${signal}`));
+          return;
+        }
+        settle(null, { exitCode: code, output });
+      };
+
+      child.once("exit", (code, signal) => {
+        if (killing) return; // the timeout path owns this outcome
+        // The timeout governs the RUN, which is over. Disarm it so a slow pipe
+        // drain cannot turn a finished run into a reported timeout.
+        if (timer) clearTimeout(timer);
+        // Reap before waiting on the pipes: a backgrounded grandchild inherits
+        // the stdout pipe, so `close` cannot fire while it lives.
+        reapGroup(pgid);
+        drainTimer = setTimeout(
+          () => settleFromExit(code, signal),
+          ORACLE_DRAIN_GRACE_MS,
+        );
+        child.once("close", () => settleFromExit(code, signal));
+      });
+
+      timer = setTimeout(() => {
+        if (settled) return;
+        killing = true;
+        terminateGroup(child, {
+          sigintTimeoutMs: ORACLE_SIGINT_GRACE_MS,
+          sigtermTimeoutMs: ORACLE_SIGTERM_GRACE_MS,
+        })
+          .catch(() => {
+            // terminateGroup swallows its own signal errors; guard anyway so a
+            // rejection can never strand the promise unsettled.
+          })
+          .then(() => {
+            settle(
+              new Error(`the held test did not finish within ${timeoutMs}ms`),
+            );
+          });
+      }, timeoutMs);
+    },
+  );
+}

package/src/pm.ts

@@ -0,0 +1,73 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { log } from "./log.js";
+
+const TAG = "pm";
+
+export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+
+let cached: PackageManager | null = null;
+
+/**
+ * Detect the package manager based on lockfiles in the repo root.
+ */
+export function detectPackageManager(): PackageManager {
+  if (cached) return cached;
+
+  let repoRoot: string;
+  try {
+    repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf-8",
+    }).trim();
+  } catch {
+    repoRoot = process.cwd();
+  }
+
+  if (
+    existsSync(`${repoRoot}/bun.lock`) ||
+    existsSync(`${repoRoot}/bun.lockb`)
+  ) {
+    cached = "bun";
+  } else if (existsSync(`${repoRoot}/pnpm-lock.yaml`)) {
+    cached = "pnpm";
+  } else if (existsSync(`${repoRoot}/yarn.lock`)) {
+    cached = "yarn";
+  } else {
+    cached = "npm";
+  }
+
+  log.info(TAG, `Detected package manager: ${cached}`);
+  return cached;
+}
+
+/**
+ * Return the install command string for the detected package manager.
+ */
+export function installCommand(): string {
+  const pm = detectPackageManager();
+  switch (pm) {
+    case "bun":
+      return "bun install --frozen-lockfile";
+    case "pnpm":
+      return "pnpm install --frozen-lockfile";
+    case "yarn":
+      return "yarn install --frozen-lockfile";
+    case "npm":
+      return "npm ci";
+  }
+}
+
+/**
+ * Return [cmd, args[]] suitable for spawn() or execFileSync() to run a package script.
+ * Adds `--` separator for npm and pnpm when extra args are present.
+ */
+export function spawnRunArgs(
+  script: string,
+  ...extra: string[]
+): [string, string[]] {
+  const pm = detectPackageManager();
+  if (extra.length > 0 && (pm === "npm" || pm === "pnpm")) {
+    return [pm, ["run", script, "--", ...extra]];
+  }
+  return [pm, ["run", script, ...extra]];
+}