type-a-bin 0.1.2 → 0.1.3

package/README.md

@@ -15,13 +15,17 @@ injecting a mock script into your `PATH`.
   takes over.
 - **Total control over output and exit codes.** Return whatever stdout,
   stderr, and exit status your tests need.
+- **Invocation recording.** Scripted mocks record every call — argv,
+  cwd, env, even stdin — on `mock.calls` for assertions.
 - **Conditional mocking.** Mock only the subcommands you care about and
   let everything else fall through to the real binary.
 - **Any interpreter.** Bash, Node, Python, Perl — if it has a shebang,
   you can use it.
 - **Cross-platform.** The same API works on Linux and Windows.
 - **TypeScript-first.** Full type definitions and overloaded signatures.
-- **Zero dependencies at runtime.** Pure Node.js standard library.
+- **Zero npm runtime dependencies.** Pure Node.js standard library, plus
+  a bundled (checked-in, ~14 KB) Windows launcher for `mockBin` — no
+  native add-ons, nothing compiled at install time.
 
 Type-A-Bin is a Node.js alternative to the npm packages
 [mock-bin](https://github.com/stevemao/mock-bin) and
@@ -41,6 +45,7 @@ fully typed, dependency-free library with richer features.
   - [1. Output shorthand](#1-output-shorthand)
   - [2. Full script](#2-full-script)
   - [3. Script file](#3-script-file)
+  - [4. Scripted behaviour](#4-scripted-behaviour)
   - [Conditional mocking](#conditional-mocking)
     - [Pattern-based mocking](#pattern-based-mocking)
     - [Script-based mocking with
@@ -53,6 +58,8 @@ fully typed, dependency-free library with richer features.
 - [Using with a test runner](#using-with-a-test-runner)
 - [API reference](#api-reference)
   - [`mockBin(...)`](#mockbin)
+  - [`withoutMocks(env)`](#withoutmocksenv)
+  - [`rmScratch(dir)`](#rmscratchdir)
   - [Types](#types)
 - [Packages](#packages)
 - [Prerequisites](#prerequisites)
@@ -147,7 +154,7 @@ cleanup(); // Restore the original PATH
 
 ## Usage
 
-`mockBin` offers three calling conventions. Choose the one that fits how
+`mockBin` offers five calling conventions. Choose the one that fits how
 much control you need.
 
 ### 1. Output shorthand
@@ -230,6 +237,32 @@ loaders work correctly. Internally, Type-A-Bin writes a tiny `/bin/sh`
 wrapper that `exec`s your file through the given interpreter, forwarding
 all arguments.
 
+**Picking the interpreter for you.** Skip the interpreter and pass only
+`{ file }` — the extension decides:
+
+``` ts
+const cleanup = await mockBin("dragon", {
+  file: "./src/tests/hoard-script.ts",
+});
+```
+
+| Extension | Interpreter |
+|----|----|
+| `.ts` `.tsx` `.mts` `.cts` | `node --import <tsx>` — the tsx loader, resolved to an absolute file URL |
+| `.js` `.mjs` `.cjs` | `node` |
+| `.sh` | `bash` |
+| anything else | throws — pass an interpreter explicitly |
+
+The absolute loader URL matters: a mocked binary often runs with a
+working directory outside your package (a temp dir, a fixture store),
+where a bare `node --import tsx` cannot resolve `tsx` and the mock would
+die on a module-not-found error. The shorthand resolves the loader once,
+from the script’s own package first and Type-A-Bin’s installed location
+second, and embeds the result. On Windows the trampoline bootstrap
+imports the same URL before loading a `.ts` entry. When tsx is not
+installed at all, Node’s native type stripping parses erasable
+TypeScript instead.
+
 This works with any language and any file extension:
 
 ``` ts
@@ -239,6 +272,60 @@ await mockBin("mycli", "python3", {
 });
 ```
 
+### 4. Scripted behaviour
+
+For the most common testing need — stub a binary’s output, set its exit
+code, and assert how it was invoked — skip the script entirely and pass
+a behaviour object. The mock prints your lines, exits with your code,
+and records every invocation:
+
+``` ts
+const mock = await mockBin("gh", {
+  stdout: ["#1 Fix login", "#2 Add docs"],
+  lineDelayMs: 50, // stream the lines one at a time
+  exitCode: 1,
+});
+
+// Anywhere in your code under test:
+// $ gh pr list  →  "#1 Fix login\n#2 Add docs\n", streamed, exit 1
+
+expect(mock.calls[0]?.args).toEqual(["pr", "list"]);
+expect(mock.calls[0]?.cwd).toBe(process.cwd());
+expect(mock.calls[0]?.env.GH_TOKEN).toBe("secret");
+
+mock(); // The handle is still the cleanup function
+```
+
+Each call is recorded the moment the mock starts — before it sleeps,
+streams, or answers — so `mock.calls` is ready to assert even while a
+slow mock is still running. Reading stdin blocks until the caller closes
+it, so it is opt-in: `record: { stdin: true }` captures the full input
+as `call.stdin`, ideal for asserting the payload your code piped into
+the binary.
+
+The behaviour object scripts the whole response:
+
+| Option | Type | Default | Description |
+|----|----|----|----|
+| `record` | `boolean \| { stdin?: boolean }` | `true` | Record invocations on `mock.calls` |
+| `stdout` | `string \| readonly string[]` | — | Line(s) written to stdout, each followed by a newline |
+| `stderr` | `string \| readonly string[]` | — | Line(s) written to stderr, after the stdout lines |
+| `exitCode` | `number` | `0` | Exit code the mock finishes with |
+| `delayMs` | `number` | `0` | Delay before the mock writes anything |
+| `lineDelayMs` | `number` | `0` | Gap between stdout lines, so a tailing consumer sees them one at a time |
+| `spawnChild` | `boolean \| { lifetimeMs?: number }` | — | Spawn a long-lived descendant, its pid recorded as `call.childPid` |
+| `trapSignals` | `boolean \| { lifetimeMs?: number }` | — | Ignore SIGINT/SIGTERM, forcing a stop to escalate to SIGKILL |
+
+The last two script lifecycle scenarios: `spawnChild` lets a test prove
+a stop reaps the whole process tree rather than the mock alone;
+`trapSignals` lets it prove a stop escalates to SIGKILL. Both keep the
+mock (and any descendant) alive for a bounded `lifetimeMs` — 120s by
+default — so a mock a test forgets to stop cannot outlive the suite.
+
+Pattern-based mocking composes here too: matching invocations run the
+behaviour, everything else falls through to the real binary and is not
+recorded (see [Conditional mocking](#conditional-mocking)).
+
 ### Conditional mocking
 
 Often you want to mock only *some* invocations of a command and let
@@ -275,7 +362,7 @@ name and all arguments (e.g. `gh pr list`). An empty pattern (`""`)
 mocks **every** invocation, just like passing no pattern at all — so you
 can toggle the behaviour dynamically.
 
-Pattern-based mocking composes with all three calling conventions,
+Pattern-based mocking composes with all five calling conventions,
 including the output shorthand:
 
 ``` ts
@@ -455,7 +542,24 @@ Creates a mock executable and prepends it to `PATH`. Returns an async
 **cleanup function** that restores the original `PATH` and removes the
 temp directory.
 
-The function is overloaded with three signatures:
+The function is overloaded with five signatures:
+
+#### Script file (interpreter inferred)
+
+``` ts
+mockBin(binNameOrConfig, script): Promise<MockBinCleanup>
+```
+
+| Parameter | Type | Description |
+|----|----|----|
+| `binNameOrConfig` | `string \| MockBinConfig` | Binary name, or a config with `binName` + `pattern` |
+| `script` | `MockBinScriptFile` | `{ file: string }` pointing at a script on disk |
+
+Runs a script file with the interpreter picked from its extension —
+TypeScript through the tsx loader (resolved to an absolute URL, so the
+mock works from any working directory), `.js` through node, `.sh`
+through bash. Throws for extensions with no known interpreter (pass one
+explicitly instead) or when the file does not exist.
 
 #### Output shorthand
 
@@ -502,6 +606,66 @@ Runs a script file through the given interpreter, keeping the file’s
 original extension so extension-aware loaders (e.g. `node --import tsx`)
 work. Throws if the file does not exist.
 
+#### Scripted behaviour
+
+``` ts
+mockBin(binNameOrConfig, behaviour): Promise<MockBinHandle>
+```
+
+| Parameter | Type | Description |
+|----|----|----|
+| `binNameOrConfig` | `string \| MockBinConfig` | Binary name, or a config with `binName` + `pattern` |
+| `behaviour` | `MockBinBehaviour` | Object scripting output, exit code, timing and lifecycle |
+
+Runs a mock scripted entirely by the `behaviour` object — no
+interpreter, no script. Returns a `MockBinHandle`: the ordinary cleanup
+function, extended with a `calls` property holding every recorded
+invocation in call order. `calls` is read fresh on each access and keeps
+serving the last snapshot after cleanup.
+
+### `withoutMocks(env)`
+
+Copies an environment without the mock registry, for spawns that must
+not be intercepted. Inside a mock, a child spawned with the inherited
+environment can re-enter the interception machinery — on Windows a spawn
+through a legacy hard-link shim resolves `process.execPath` to the shim
+itself. Passing `withoutMocks(process.env)` as the child’s `env` leaves
+any preload inert (it finds no registry), and a trampoline-launched mock
+handed such an environment forwards the invocation to the real binary
+instead of the mock.
+
+``` ts
+import { spawn } from "node:child_process";
+import { withoutMocks } from "type-a-bin";
+
+const child = spawn(
+  process.execPath,
+  ["-e", 'setTimeout(() => console.log("helper ran"), 1000)'],
+  { env: withoutMocks(process.env) },
+);
+```
+
+The registry variable’s name is exported as `MOCKS_VAR`, so callers that
+need to read or strip the registry never hardcode it.
+
+### `rmScratch(dir)`
+
+Removes a scratch directory tree without ever failing a test: the
+deletion is forced and retried (`maxRetries: 40`, `retryDelay: 250`),
+because Windows — and busy filesystems generally — can transiently deny
+deleting files a just-exited process still holds (shim executables,
+SQLite WAL files). A removal that still fails after the retries logs a
+warning instead of throwing: leaving a temp directory behind beats
+failing a suite that passed.
+
+``` ts
+import { rmScratch } from "type-a-bin";
+
+rmScratch(scratchDir); // never throws
+```
+
+`mockBin` cleanup uses this helper internally on every platform.
+
 ### Types
 
 ``` ts
@@ -524,6 +688,76 @@ interface MockBinScriptFile {
    */
   file: string;
 }
+
+/** A cleanup function, carrying the calls a scripted mock recorded. */
+type MockBinHandle = MockBinCleanup & {
+  /** Every recorded invocation, in call order. */
+  readonly calls: MockBinCall[];
+};
+
+/** One recorded invocation of a scripted mock. */
+interface MockBinCall {
+  /** Arguments the mock was invoked with, excluding the binary name. */
+  args: string[];
+  /** Working directory the mock ran in. */
+  cwd: string;
+  /** Environment the mock ran with. */
+  env: Record<string, string>;
+  /** Process id of the mock itself. */
+  pid: number;
+  /** Stdin, when the behaviour recorded it. */
+  stdin?: string;
+  /** Pid of the descendant, when the behaviour spawned one. */
+  childPid?: number;
+}
+
+/** How long a spawned descendant or a signal-trapped mock stays alive. */
+interface MockBinLifetimeOptions {
+  /** Lifetime in milliseconds. Default 120000. */
+  lifetimeMs?: number;
+}
+
+/** Extra recording knobs for a scripted mock. */
+interface MockBinRecordOptions {
+  /**
+   * Read stdin to end-of-file and record it as `call.stdin`. Off by
+   * default: a mock that drains stdin waits for the caller to close it.
+   */
+  stdin?: boolean;
+}
+
+/** Scripts a mock's output, exit code, timing and lifecycle. */
+interface MockBinBehaviour {
+  /**
+   * Record every invocation for `handle.calls`. On by default; pass
+   * `false` to skip recording, or `{ stdin: true }` to capture stdin
+   * as well.
+   */
+  record?: boolean | MockBinRecordOptions;
+  /** Line(s) written to stdout, each followed by a newline. */
+  stdout?: string | readonly string[];
+  /** Line(s) written to stderr, after the stdout lines. */
+  stderr?: string | readonly string[];
+  /** Exit code the mock finishes with. Default 0. */
+  exitCode?: number;
+  /** Delay before the mock writes anything, in milliseconds. */
+  delayMs?: number;
+  /**
+   * Gap between stdout lines, in milliseconds, so a consumer tailing
+   * the stream sees them arrive one at a time instead of one burst.
+   */
+  lineDelayMs?: number;
+  /**
+   * Spawn a long-lived descendant and record its pid as `call.childPid`,
+   * so a test can prove a stop reaps the whole process tree.
+   */
+  spawnChild?: boolean | MockBinLifetimeOptions;
+  /**
+   * Ignore SIGINT and SIGTERM, so stopping the mock has to escalate to
+   * SIGKILL.
+   */
+  trapSignals?: boolean | MockBinLifetimeOptions;
+}
 ```
 
 ## Packages
@@ -546,7 +780,10 @@ library lives at the root; additional packages live under `packages/`:
   library
 - On Windows: [Git for Windows](https://gitforwindows.org/) — its bash
   powers bash-interpreter mocks (node-interpreter mocks need nothing
-  beyond Node itself)
+  beyond Node itself). The `mockBin` launcher itself is bundled in the
+  package (`dist/native/win32`), rebuilt and checksum-verified from
+  `native/trampoline.c` in CI — no compiler or download is needed at
+  install time.
 
 ## Scripts
 
@@ -639,22 +876,42 @@ extensionless `#!` scripts — and Node refuses to spawn `.cmd`/`.bat`
 shims without a shell — the implementation swaps the mechanism, not the
 contract:
 
-- Each mock binary is a **hard link of `node.exe`** named `<bin>.exe`
-  (copied if the temp directory is on another volume), prepended to
-  `PATH` exactly as on Linux.
-- A small **preload** is registered through `NODE_OPTIONS --import` in
-  every spawned process. It detects that the process was started as a
-  mock shim (its first CLI argument is not a real file), then swaps the
-  entry for your mock script — argv, stdin, stdout, stderr, and exit
-  codes all pass through.
-- Node-interpreter mocks (and `node --import tsx` script files) run
-  **in-process** through loader hooks; other interpreters (`bash`,
-  `python`, …) are resolved from `PATH` and spawned with your script and
-  the original arguments.
-- The `mock-a-bin-run-original` helper, `pattern` conditionals, output
-  shorthand, script files, and cleanup contract all behave as on Linux.
-  Cleanup additionally restores `NODE_OPTIONS` and the internal mock
-  registry.
+- Each mock binary is a **copy of a tiny trampoline launcher**
+  (`type-a-bin-trampoline.exe`, built from
+  [`native/trampoline.c`](native/trampoline.c)) named `<bin>.exe`,
+  prepended to `PATH` exactly as on Linux.
+- The trampoline starts the real Node executable with a small
+  **bootstrap script** as Node’s script argument, passing the invoked
+  mock executable and the caller’s original arguments after it. A real
+  script occupies Node’s first positional slot, so every original
+  argument — including leading flags (`gh --version`), embedded quotes,
+  line breaks, trailing backslashes, and Unicode — arrives in the mock’s
+  `process.argv` exactly as the caller passed it. No shell and no Node
+  option parser sits in between.
+- The bootstrap dispatches through the same runtime the library uses
+  everywhere: node-interpreter mocks (and TypeScript script files,
+  loaded through the tsx loader URL) run **in-process** with
+  `process.argv` rewritten to `[node, entry, ...args]`; other
+  interpreters (`bash`, `python`, …) are resolved from `PATH` and
+  spawned with your script and the original arguments.
+- The launcher inherits stdin/stdout/stderr, the environment, and the
+  working directory, propagates the mock’s exit code, and starts the
+  mock inside a Windows Job Object — killing the process you spawned
+  reaps the mock and its descendants, while a mock that finishes
+  normally releases descendants it deliberately left behind.
+- Inside a mock, `process.execPath` is the real Node executable, and
+  unrelated Node children spawned during the test no longer carry a
+  preload: nothing is injected into `NODE_OPTIONS`.
+- The `mock-a-bin-run-original` helper, `pattern` conditionals (both
+  flag-first), output shorthand, script files, and cleanup contract all
+  behave as on Linux. Cleanup removes the launcher, bootstrap, and
+  scripts with the same retry semantics as before.
+
+A legacy mechanism — a hard link of `node.exe` plus a `NODE_OPTIONS`
+preload that redirects the shim’s entry — ships as a temporary escape
+hatch: set `TYPE_A_BIN_DISABLE_TRAMPOLINE=1` to force it while the
+launcher rollout is validated. It cannot support flag-first CLIs,
+because Node parses a leading option before the preload runs.
 
 Requirements and behaviour notes:
 
@@ -662,31 +919,31 @@ Requirements and behaviour notes:
   native `bash.exe` (Git Bash) over WSL’s launcher, which cannot run
   Windows-path scripts; well-known Git install locations are probed as a
   fallback.
-- **The first CLI argument must be positional.** A shim *is* `node.exe`,
-  so a leading flag (`gh --version`) is consumed by Node’s own option
-  parser before the mock can intercept it. Prefer the subcommand form
-  (`gh version`), or wrap the flag behind a positional subcommand.
 - **Pass-through needs a real `.exe`.** `mock-a-bin-run-original` and
   pattern fall-through locate and spawn the original binary directly;
   `.cmd`/`.bat`-only binaries (e.g. `npm.cmd`) cannot be spawned by Node
-  without a shell.
+  without a shell. (That limitation is about the *real* binary; the
+  mock’s own argv is always forwarded verbatim.)
 - **The output shorthand expands `$1`–`$9`, `$*`, and `$@`** from the
   command line (matching bash `echo` for positional parameters); other
   shell substitutions are printed literally.
 - **Stacked mocks clean up last-in, first-out.** Like `PATH`, the mock
-  registry and `NODE_OPTIONS` are snapshot-restored, so call the cleanup
-  functions in reverse order of the `mockBin` calls for a full restore.
+  registry is snapshot-restored, so call the cleanup functions in
+  reverse order of the `mockBin` calls for a full restore.
 
-`NODE_OPTIONS` is process environment, not global state: it only affects
-processes spawned while mocks are active, and the preload is inert for
-any process that is not a mock shim.
+The mock registry (`TYPE_A_BIN_MOCKS`) and the launcher’s Node
+executable (`TYPE_A_BIN_NODE_EXE`) are process environment, not global
+state: they only affect processes spawned while mocks are active.
+Children spawned from inside a mock escape interception on their own —
+[`withoutMocks(process.env)`](#withoutmocksenv) remains for spawns that
+must reach the real binary behind a mock.
 
 ## Comparison with other tools
 
 | Feature | Type-A-Bin | [mock-bin](https://github.com/stevemao/mock-bin) | [mock-a-bin](https://github.com/levibostian/mock-a-bin) |
 |----|:--:|:--:|:--:|
 | Mocks any binary via `PATH` | ✅ | ✅ | ✅ |
-| Runtime dependencies | 0 | several | several (Deno) |
+| Runtime dependencies | 0 npm (bundled Windows launcher) | several | several (Deno) |
 | TypeScript types & overloads | ✅ | ❌ | partial |
 | Output shorthand | ✅ | ❌ | ❌ |
 | Script-file mode (keeps extension) | ✅ | ❌ | ❌ |

package/dist/index.d.ts

@@ -1 +1,4 @@
 export { type MockBinCleanup, type MockBinConfig, type MockBinScriptFile, mockBin, } from "./mock-bin.js";
+export { type MockBinBehaviour, type MockBinCall, type MockBinHandle, type MockBinLifetimeOptions, type MockBinRecordOptions, } from "./mock-bin-behaviour.js";
+export { MOCKS_VAR, withoutMocks } from "./mock-bin-env.js";
+export { rmScratch } from "./rm-scratch.js";

package/dist/index.js

@@ -1 +1,3 @@
 export { mockBin, } from "./mock-bin.js";
+export { MOCKS_VAR, withoutMocks } from "./mock-bin-env.js";
+export { rmScratch } from "./rm-scratch.js";

package/dist/mock-bin-behaviour-runtime.d.ts

@@ -0,0 +1,21 @@
+interface MockBehaviourScript {
+    /** Binary name, as the pattern matches it against the command line. */
+    binName: string;
+    stdout: string[];
+    stderr: string[];
+    exitCode: number;
+    delayMs: number;
+    lineDelayMs: number;
+    recordStdin: boolean;
+    /** Regex source; only matching commands run the behaviour. */
+    pattern?: string;
+    /** Directory that receives one JSON record per invocation. */
+    recordDir?: string;
+    /** Life of the spawned descendant; absent means spawn none. */
+    spawnChildMs?: number;
+    /** How long trapped signals keep the mock alive; absent traps none. */
+    trapSignalsMs?: number;
+}
+/** Runs one invocation of a mock built from a scripted behaviour. */
+declare const runMockBehaviour: (script: MockBehaviourScript) => Promise<void>;
+export { type MockBehaviourScript, runMockBehaviour };

package/dist/mock-bin-behaviour-runtime.js

@@ -0,0 +1,164 @@
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, openSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+// Runs inside the mocked binary's own process — spawned on POSIX, in
+// the shim on Windows — so it must stay free of runtime imports beyond
+// node's own modules. mock-bin-behaviour compiles a MockBinBehaviour
+// into the script below and the mock hands it straight back here.
+// The registry env var must stay in sync with mock-bin-env.
+const MOCKS_VAR = "TYPE_A_BIN_MOCKS";
+const WINDOWS_EXTENSIONS = ["", ".exe", ".cmd", ".bat", ".com"];
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const isFile = (candidate) => {
+    try {
+        return statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** The PATH without the mock temp dirs, so the real binary wins. */
+const realBinary = (binName) => {
+    const dirs = (process.env.PATH ?? "")
+        .split(path.delimiter)
+        .filter((dir) => dir !== "" && !dir.includes("mock-bin-"));
+    const extensions = process.platform === "win32" ? WINDOWS_EXTENSIONS : [""];
+    for (const dir of dirs)
+        for (const extension of extensions) {
+            const candidate = path.join(dir, `${binName}${extension}`);
+            if (isFile(candidate))
+                return candidate;
+        }
+    return null;
+};
+/**
+ * Pattern miss: hand the invocation to the binary the mock shadows.
+ * The behaviour tests the pattern itself rather than leaning on the
+ * wrappers the other conventions use, because those are shell scripts
+ * and this mock is a node one on both platforms.
+ */
+const runRealBinary = (binName, args) => {
+    const real = realBinary(binName);
+    if (real === null) {
+        process.stderr.write(`Error: Real binary '${binName}' not found in PATH\n`);
+        process.exitCode = 127;
+        return;
+    }
+    // The real binary must not be re-intercepted by the Windows preload.
+    const env = { ...process.env };
+    delete env[MOCKS_VAR];
+    const result = spawnSync(real, args, { stdio: "inherit", env });
+    process.exitCode = result.status ?? 127;
+};
+/**
+ * Claims the next free record slot. Creating the file exclusively makes
+ * the number a race-free ticket, so concurrent invocations are recorded
+ * in the order they started.
+ */
+const reserveRecord = (recordDir) => {
+    for (let index = 0;; index += 1) {
+        const file = path.join(recordDir, `${index}.json`);
+        try {
+            closeSync(openSync(file, "wx"));
+            return file;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+};
+/** Publishes a record by rename, so a reader never sees half of one. */
+const writeRecord = (file, call) => {
+    const pending = `${file}.pending`;
+    writeFileSync(pending, JSON.stringify(call));
+    renameSync(pending, file);
+};
+const readStdin = async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf-8");
+};
+/**
+ * Spawns a descendant that outlives the mock's own work, so a test can
+ * prove a stop reaps the process tree rather than the mock alone.
+ */
+const spawnChild = (lifetimeMs) => {
+    // A Windows mock binary runs behind the type-a-bin trampoline
+    // launcher, which starts it inside a Job Object killed when the
+    // launcher dies — so a descendant detached from its console stays in
+    // the job: a killed mock takes it down with the tree, while a
+    // normally completed mock has the launcher clear the kill-on-close
+    // flag and lets it outlive the invocation. Dropping the mock registry
+    // from its env keeps any legacy NODE_OPTIONS preload inert there.
+    const env = { ...process.env };
+    delete env[MOCKS_VAR];
+    const child = spawn(process.execPath, ["-e", `setTimeout(() => {}, ${lifetimeMs})`], {
+        stdio: "ignore",
+        env,
+        // POSIX detaching would start a new session, moving the child out
+        // of the mock's process group and out of a group signal's reach.
+        // Windows is the opposite: a spawned child sits in a job that is
+        // killed when the mock exits, so only there must it detach to
+        // outlive the mock.
+        ...(process.platform === "win32" ? { detached: true } : {}),
+    });
+    // The child stays in the mock's process group, so a stop that signals
+    // the group reaps it; unref keeps it from holding the mock open, and
+    // its bounded life keeps a missed descendant from outliving the suite.
+    child.unref();
+    return child.pid;
+};
+/**
+ * Stop-escalation tests need a mock that ignores the graceful signals:
+ * no-op handlers swallow them, so the process survives until the
+ * ladder's SIGKILL rung lands.
+ */
+const trapSignals = (lifetimeMs) => {
+    process.on("SIGINT", () => undefined);
+    process.on("SIGTERM", () => undefined);
+    // Signal listeners do not hold node's event loop open, so a bounded
+    // timer keeps the mock running for the stop ladder to work against.
+    setTimeout(() => undefined, lifetimeMs);
+};
+/** Runs one invocation of a mock built from a scripted behaviour. */
+const runMockBehaviour = async (script) => {
+    const args = process.argv.slice(2);
+    const command = [script.binName, ...args].join(" ");
+    if (script.pattern !== undefined && !new RegExp(script.pattern).test(command))
+        return runRealBinary(script.binName, args);
+    if (script.trapSignalsMs !== undefined)
+        trapSignals(script.trapSignalsMs);
+    // The slot is claimed before anything can block and published as soon
+    // as the invocation is fully described, so a test can read the call
+    // while a slow or streaming mock is still running.
+    const record = script.recordDir === undefined
+        ? undefined
+        : reserveRecord(script.recordDir);
+    const childPid = script.spawnChildMs === undefined
+        ? undefined
+        : spawnChild(script.spawnChildMs);
+    const stdin = script.recordStdin ? await readStdin() : undefined;
+    if (record !== undefined)
+        writeRecord(record, {
+            args,
+            cwd: process.cwd(),
+            env: { ...process.env },
+            pid: process.pid,
+            ...(stdin === undefined ? {} : { stdin }),
+            ...(childPid === undefined ? {} : { childPid }),
+        });
+    if (script.delayMs > 0)
+        await sleep(script.delayMs);
+    for (const [index, line] of script.stdout.entries()) {
+        if (index > 0 && script.lineDelayMs > 0)
+            await sleep(script.lineDelayMs);
+        process.stdout.write(`${line}\n`);
+    }
+    for (const line of script.stderr)
+        process.stderr.write(`${line}\n`);
+    process.exitCode = script.exitCode;
+};
+export { runMockBehaviour };