jev-agent-tools 0.1.4 → 0.2.0

package/docs/mcp.md

@@ -0,0 +1,231 @@
+# MCP setup guide
+
+`jev-agent-tools-mcp` is a stdio [MCP](https://modelcontextprotocol.io) server that exposes the same six `jev_*` tools as the pi and omp extension to any MCP client. It ships in the `jev-agent-tools` npm package, has no runtime dependencies beyond that package, and runs one session per server process.
+
+Setup takes three steps: provide the endpoint and key, register the server with your client, and add the [agent instructions](agent-instructions.md) to your project.
+
+## 1. Requirements
+
+- Node.js 24 or later, and Git, on the machine that runs the client.
+- Bash for optional `jev_ask` command evidence. On Windows this is Git for Windows bash, found automatically next to `git` or under Program Files; set `JEV_TOOLS_BASH` to use another. The WSL `bash.exe` launchers are never used.
+- A Jev endpoint URL and API key.
+
+The server ships in `jev-agent-tools` version 0.2.0 and later. For a development checkout, see [From a clone](#from-a-clone).
+
+## 2. Provide the endpoint and key
+
+The server reads, per field, the environment first and then the configuration saved by `/jev-setup` in pi or omp. There is no interactive setup inside MCP.
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `JEV_TOOLS_URL` | yes | Complete endpoint URL compatible with the Jev API format. |
+| `JEV_TOOLS_API_KEY` | yes | Bearer credential. Never printed in tool output. |
+| `JEV_TOOLS_MODEL` | no | Requested model, default `openjev`. |
+| `JEV_TOOLS_ROOT` | no | Repository directory when `--root` is not given. |
+| `JEV_TOOLS_MAX_CALLS`, `JEV_TOOLS_MAX_USD` | no | Session call and cost limits for this server process. |
+| `JEV_TOOLS_ALLOW_COMMAND` | no | `0` removes `command` from `jev_ask`. |
+| `JEV_TOOLS_BASH` | no | Full path of the bash used for commands on Windows. |
+
+Prefer passing secrets through your client's environment-variable interpolation (shown per client below) rather than writing the key into a committed file. Saved configuration from `/jev-setup` lives in `~/.config/jev-agent-tools/config.json` and is refused unless the directory and file are private: owner-only mode bits on Linux and macOS, an access list limited to you, SYSTEM and Administrators on Windows. Unusable saved storage is reported on the server's stderr and never stops the server.
+
+Without an endpoint and key the server still starts, lists the tools and answers each call with what is missing.
+
+## 3. Register the server
+
+Every example registers a server named `jev`. Replace the repository path. The repository the tools work in is `--root`, else `JEV_TOOLS_ROOT`, else the directory the client starts the server in.
+
+**Windows:** most clients start the command without a shell, and `npx` is a `.cmd` script there, so `"command": "npx"` fails to start. Use `"command": "cmd"` with `"args": ["/c", "npx", ...]`, as in the Windows examples. This was checked on Windows 11 with Node.js 24: a shell-less spawn of `npx` failed with `ENOENT`, `cmd /c npx` started the server.
+
+The shared arguments are:
+
+```text
+npx -y -p jev-agent-tools jev-agent-tools-mcp --root <repository>
+```
+
+`-p jev-agent-tools` is required because the binary name differs from the package name. Pin a version (`jev-agent-tools@X.Y.Z`) for reproducible setups.
+
+### From the MCP Registry
+
+Releases are also published to the official [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.NomenAK/jev-agent-tools`, from [`server.json`](../server.json). Clients and catalogs that read the registry can install the server from there; they start it as `npx jev-agent-tools` (the package's only binary) and ask for `JEV_TOOLS_URL` and the secret `JEV_TOOLS_API_KEY`. The manual entries below give the same result.
+
+### Claude Code
+
+For a private registration, add it from the project directory with the CLI. Your shell expands the variables, so the values are stored in your private `~/.claude.json`, not in the project:
+
+```sh
+claude mcp add --scope local --env JEV_TOOLS_URL="$JEV_TOOLS_URL" --env JEV_TOOLS_API_KEY="$JEV_TOOLS_API_KEY" --transport stdio jev -- npx -y -p jev-agent-tools jev-agent-tools-mcp --root .
+```
+
+To share the server with the team, write `.mcp.json` at the project root instead. Claude Code expands `${VAR}` and `${VAR:-default}` from each user's environment when it loads the file, so no key is committed:
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "${CLAUDE_PROJECT_DIR:-.}"],
+      "env": {
+        "JEV_TOOLS_URL": "${JEV_TOOLS_URL}",
+        "JEV_TOOLS_API_KEY": "${JEV_TOOLS_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+On Windows use `"command": "cmd"` and prepend `"/c", "npx"` to `args`. Check with `claude mcp list`. Add the instructions to `CLAUDE.md` ([template](agent-instructions.md#claudemd)).
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings, Developer, Edit Config): `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Claude Desktop has no project directory, so `--root` is required. Its documentation does not describe variable interpolation, so values here are literal; keep this file private.
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "C:\\path\\to\\repository"],
+      "env": {
+        "JEV_TOOLS_URL": "https://your-jev-endpoint.example/judge",
+        "JEV_TOOLS_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+On macOS use `"command": "npx"` without `"/c", "npx"`. Restart Claude Desktop after saving. One server serves one repository; add a second entry with another name for another repository.
+
+### Kiro (IDE and CLI)
+
+Workspace: `.kiro/settings/mcp.json`. User: `~/.kiro/settings/mcp.json`. The workspace file wins for a server of the same name. Kiro expands `${VAR}`.
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "."],
+      "env": {
+        "JEV_TOOLS_URL": "${JEV_TOOLS_URL}",
+        "JEV_TOOLS_API_KEY": "${JEV_TOOLS_API_KEY}"
+      },
+      "disabled": false,
+      "autoApprove": ["jev_ask_files", "jev_find_files", "jev_locate_in_file", "jev_check_diff", "jev_select_tests"]
+    }
+  }
+}
+```
+
+`autoApprove` above leaves `jev_ask` on manual approval because it can run shell commands. On Windows use `"command": "cmd"` with `"/c", "npx"` first in `args`. Add the instructions as a steering file ([template](agent-instructions.md#kiro-steering)).
+
+### Cursor
+
+Project: `.cursor/mcp.json`. Global: `~/.cursor/mcp.json`. Cursor expands `${env:NAME}` and `${workspaceFolder}`.
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "${workspaceFolder}"],
+      "env": {
+        "JEV_TOOLS_URL": "${env:JEV_TOOLS_URL}",
+        "JEV_TOOLS_API_KEY": "${env:JEV_TOOLS_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+
+Workspace: `.vscode/mcp.json`. The top-level key is `servers`, not `mcpServers`.
+
+```json
+{
+  "servers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "${workspaceFolder}"],
+      "env": {
+        "JEV_TOOLS_URL": "https://your-jev-endpoint.example/judge",
+        "JEV_TOOLS_API_KEY": "${input:jev-api-key}"
+      }
+    }
+  },
+  "inputs": [
+    { "type": "promptString", "id": "jev-api-key", "description": "Jev API key", "password": true }
+  ]
+}
+```
+
+The `inputs` prompt follows VS Code's MCP configuration reference; check it for your VS Code version.
+
+### OpenAI Codex CLI
+
+```sh
+codex mcp add jev --env JEV_TOOLS_URL=https://your-jev-endpoint.example/judge -- npx -y -p jev-agent-tools jev-agent-tools-mcp --root .
+```
+
+Or in `~/.codex/config.toml` (or a trusted project's `.codex/config.toml`). `env_vars` forwards variables from your environment without writing them into the file:
+
+```toml
+[mcp_servers.jev]
+command = "npx"
+args = ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "."]
+env_vars = ["JEV_TOOLS_URL", "JEV_TOOLS_API_KEY"]
+```
+
+Add the instructions to `AGENTS.md` ([template](agent-instructions.md#agentsmd)).
+
+### Windsurf and other clients
+
+Clients that use an `mcpServers` object accept the Claude Code JSON entry above. Windsurf reads `mcp_config.json` (see its MCP documentation for the current path) and expands `${env:NAME}`.
+
+## 4. Verify
+
+Run the server once by hand; it reads protocol messages from stdin and writes diagnostics to stderr:
+
+```sh
+npx -y -p jev-agent-tools jev-agent-tools-mcp --version
+npx -y -p jev-agent-tools jev-agent-tools-mcp --root . < /dev/null
+```
+
+In PowerShell, run the second as `$null | npx -y -p jev-agent-tools jev-agent-tools-mcp --root .`.
+
+The second command prints `jev-agent-tools MCP server ready (root ...; endpoint configured)` on stderr and exits when stdin closes. In the client, the six tools should be listed: `jev_ask`, `jev_ask_files`, `jev_find_files`, `jev_locate_in_file`, `jev_check_diff`, `jev_select_tests`. Ask the agent to run `jev_ask` with a one-line note and a yes/no question; the result ends with the calls, cost and time footer.
+
+## From a clone
+
+```sh
+npm ci --include=optional
+npm run build
+```
+
+Then use `"command": "node"` with `"args": ["/absolute/path/to/jev-tools/dist/mcp/main.js", "--root", "<repository>"]`. This form also avoids the Windows `npx` issue. Node does not strip TypeScript types under `node_modules`, which is why the server ships as compiled `dist/` while pi and omp load `src/`.
+
+## Differences from pi and omp
+
+- **No run-end documentation check.** It is a host hook. Before finishing, ask the agent to call `jev_check_diff` with `check: "docs"`; the [instructions](agent-instructions.md) say so.
+- **Approval is the client's.** `jev_ask` is annotated as not read-only and potentially destructive while it accepts `command`; the other five are read-only. All six are open-world because evidence goes to your endpoint. `JEV_TOOLS_ALLOW_COMMAND=0` removes `command` from the schema and makes `jev_ask` read-only.
+- **Instructions.** The reading guide and the `jev_ask` policy are sent as the server's `instructions`. Clients may ignore them, so also add the [agent instructions](agent-instructions.md) to the project.
+- **Tool names in descriptions** refer to "your text search tool" and "your file-name search tool" instead of pi or omp tool names.
+- **Protocol.** Versions 2024-11-05 through 2025-11-25 via `initialize`, 2026-07-28 via `server/discover` and per-request `_meta`. Modern discovery supplies server identity in `_meta["io.modelcontextprotocol/serverInfo"]`; discovery and tool lists advertise `ttlMs: 0` and `cacheScope: "private"`, so clients must not share them across authorization contexts. Tools only; no resources, prompts or sampling. Cancelling a call aborts its Jev requests and command.
+- **One process, one session.** Limits, cache and counters last as long as the connection; restart the server to reset them.
+- **Command shutdown.** Cancellation, command timeout, stdin closure, SIGTERM and SIGINT wait for bounded command-tree termination. On POSIX the managed group receives SIGTERM, then SIGKILL after two seconds if it remains. On Windows, the server maps ordinary MSYS descendants through the same Bash installation's process table before running the system `taskkill /T /F`; each subprocess is bounded to five seconds. Cancelled calls receive no response. This is not a sandbox: descendants that deliberately detach from the managed group or escape the tracked tree are not contained.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| Client shows the server failed to start on Windows | `npx` cannot start without a shell. Use `cmd /c npx` or `node <path>/dist/mcp/main.js`. |
+| `jev-tools is not configured` in every result | The server did not receive `JEV_TOOLS_URL` and `JEV_TOOLS_API_KEY`. Check the client's `env` block and that interpolated variables exist where the client was started. |
+| stderr: `Cannot read or save Jev configuration` | Saved `/jev-setup` storage is not private or is malformed. Environment variables still apply. Fix permissions (on Windows, remove other accounts from the folder's Security tab) or delete the file and save again. |
+| `Repository directory not found` | `--root` or `JEV_TOOLS_ROOT` points to a missing directory. |
+| Command evidence reports `Command executable unavailable` | No usable bash. Install Git for Windows or set `JEV_TOOLS_BASH`. |
+| Results from the wrong repository | The client started the server elsewhere. Pass an absolute `--root`. |
+
+## Data and safety
+
+Repository evidence, notes and command output are sent to your configured endpoint; review its data-handling policy first. File collection is confined to the repository, but `jev_ask` commands run with your shell permissions and no sandbox. See [SECURITY.md](../SECURITY.md).

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "jev-agent-tools",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
-  "description": "Six evidence-oriented tools for pi and omp coding agents, compatible with the Jev API format.",
+  "mcpName": "io.github.NomenAK/jev-agent-tools",
+  "description": "Six evidence-oriented tools for pi and omp coding agents and any MCP client, compatible with the Jev API format.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/NomenAK/jev-tools.git"
@@ -19,7 +20,9 @@
     "test-selection",
     "pi",
     "omp",
-    "jev"
+    "jev",
+    "mcp",
+    "model-context-protocol"
   ],
   "files": [
     "src/",
@@ -33,8 +36,18 @@
     "docs/tools/jev_find_files.md",
     "docs/tools/jev_locate_in_file.md",
     "docs/tools/jev_check_diff.md",
-    "docs/tools/jev_select_tests.md"
+    "docs/tools/jev_select_tests.md",
+    "docs/mcp.md",
+    "docs/agent-instructions.md",
+    "dist/",
+    "server.json",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "docs/adr/"
   ],
+  "bin": {
+    "jev-agent-tools-mcp": "dist/mcp/main.js"
+  },
   "pi": {
     "extensions": [
       "./src/index.ts"
@@ -49,6 +62,8 @@
     "node": ">=24"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
     "typecheck": "tsc --noEmit",
     "check:imports": "node scripts/check-imports.ts",
     "lint": "biome check src test scripts",

package/server.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.NomenAK/jev-agent-tools",
+  "title": "Jev agent tools",
+  "description": "Evidence-oriented code questions, diff review and test selection via a Jev endpoint.",
+  "version": "0.2.0",
+  "repository": {
+    "url": "https://github.com/NomenAK/jev-tools",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/NomenAK/jev-tools/blob/main/docs/mcp.md",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "jev-agent-tools",
+      "version": "0.2.0",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      },
+      "packageArguments": [
+        {
+          "type": "named",
+          "name": "--root",
+          "description": "Repository directory the tools work in. Defaults to the directory the client starts the server in.",
+          "format": "filepath",
+          "isRequired": false
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "JEV_TOOLS_URL",
+          "description": "Complete endpoint URL compatible with the Jev API format.",
+          "isRequired": true
+        },
+        {
+          "name": "JEV_TOOLS_API_KEY",
+          "description": "Bearer credential for the endpoint.",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "JEV_TOOLS_MODEL",
+          "description": "Requested Jev model.",
+          "default": "openjev",
+          "isRequired": false
+        },
+        {
+          "name": "JEV_TOOLS_ALLOW_COMMAND",
+          "description": "Set to 0 to remove shell commands from jev_ask.",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}

package/src/adapters/canonical-path.ts

@@ -0,0 +1,18 @@
+import { realpath } from "node:fs";
+import { promisify } from "node:util";
+
+const nativeRealpath = promisify(realpath.native);
+
+/**
+ * Canonical form of an existing path: resolves symlinks and, on Windows,
+ * expands 8.3 short names (C:\Users\NAME~1) so the path relates correctly to
+ * `git rev-parse --show-toplevel`, which always reports the long form. Falls
+ * back to the input when the path cannot be resolved.
+ */
+export async function canonicalPath(path: string): Promise<string> {
+  try {
+    return await nativeRealpath(path);
+  } catch {
+    return path;
+  }
+}

package/src/adapters/command.ts

@@ -21,6 +21,7 @@ import {
 import type { GitExec } from "../core/git.ts";
 import type { Result } from "../result.ts";
 import { outputLines } from "./output-lines.ts";
+import { resolveShell } from "./shell.ts";
 
 export interface CommandOutput {
   command: string;
@@ -62,13 +63,15 @@ export async function captureCommand(
       killed: boolean;
     };
     try {
+      const shell = resolveShell();
+      // Fail closed: never spawn a bare name that PATH could resolve to WSL.
+      if (!shell.ok) throw new Error(shell.error);
       executed = await exec(
-        "env",
+        shell.executable,
         [
-          "CI=1",
-          "bash",
+          ...shell.prefix,
           "-c",
-          `exec >"$1" 2>"$2"; set --; (\n${command}\n)\nexit $?`,
+          `${shell.scriptPrefix}exec >"$1" 2>"$2"; set --; (\n${command}\n)\nexit $?`,
           "jev",
           stdoutPath,
           stderrPath,

package/src/adapters/exec.ts

@@ -0,0 +1,226 @@
+import { type ChildProcess, execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import {
+  PROCESS_KILL_GRACE_MS,
+  PROCESS_PIPE_GRACE_MS,
+  PROCESS_TREE_TIMEOUT_MS,
+} from "../constants.ts";
+import type { GitExec } from "../core/git.ts";
+
+/** Signal the managed process group, or await Windows process-tree termination. */
+export async function killTree(
+  child: ChildProcess,
+  signal: NodeJS.Signals = "SIGTERM",
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  const pid = child.pid;
+  if (pid === undefined) return;
+  if (platform === "win32") {
+    const taskkill = join(
+      process.env.SystemRoot ?? "C:\\Windows",
+      "System32",
+      "taskkill.exe",
+    );
+    const pids = [pid];
+    // MSYS fork/exec can leave Windows parent IDs pointing at vanished helper
+    // processes. Use the same Bash installation's POSIX table before killing
+    // the root; taskkill /T alone cannot find those ordinary descendants.
+    if (basename(child.spawnfile).toLowerCase() === "bash.exe") {
+      const directory = dirname(child.spawnfile);
+      const ps = [
+        join(directory, "ps.exe"),
+        join(directory, "..", "usr", "bin", "ps.exe"),
+      ].find(existsSync);
+      if (ps) {
+        const snapshot = Promise.withResolvers<string>();
+        execFile(
+          ps,
+          ["-e"],
+          { windowsHide: true, timeout: PROCESS_TREE_TIMEOUT_MS },
+          (error, stdout) => snapshot.resolve(error ? "" : stdout),
+        );
+        const rows = [];
+        for (const line of (await snapshot.promise).split("\n")) {
+          const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s/.exec(line);
+          if (!match) continue;
+          rows.push({
+            pid: Number(match[1]),
+            parent: Number(match[2]),
+            windows: Number(match[4]),
+          });
+        }
+        const root = rows.find((row) => row.windows === pid);
+        if (root) {
+          const managed = new Set([root.pid]);
+          let added = true;
+          while (added) {
+            added = false;
+            for (const row of rows) {
+              if (!managed.has(row.pid) && managed.has(row.parent)) {
+                managed.add(row.pid);
+                if (row.windows > 0) pids.push(row.windows);
+                added = true;
+              }
+            }
+          }
+        }
+      }
+    }
+    const { promise, resolve } = Promise.withResolvers<void>();
+    execFile(
+      taskkill,
+      [...new Set(pids)]
+        .flatMap((target) => ["/PID", String(target)])
+        .concat("/T", "/F"),
+      { windowsHide: true, timeout: PROCESS_TREE_TIMEOUT_MS },
+      (error) => {
+        if (error) child.kill();
+        resolve();
+      },
+    );
+    await promise;
+    return;
+  }
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    child.kill(signal);
+  }
+  return;
+}
+
+function groupExists(child: ChildProcess): boolean {
+  if (child.pid === undefined) return false;
+  try {
+    process.kill(-child.pid, 0);
+    return true;
+  } catch (error) {
+    return !(
+      error instanceof Error &&
+      "code" in error &&
+      error.code === "ESRCH"
+    );
+  }
+}
+
+/**
+ * Capture a process without a shell. Timeout and abort finish tree termination
+ * before resolving, even when the direct child exits before its descendants.
+ * Deliberately detached descendants are not sandboxed or tracked.
+ */
+export const spawnExec: GitExec = (command, args, options) => {
+  const { promise, resolve, reject } = Promise.withResolvers<{
+    stdout: string;
+    stderr: string;
+    code: number;
+    killed: boolean;
+  }>();
+  const posix = process.platform !== "win32";
+  // Git's bin/bash.exe forwards to usr/bin/bash.exe. Spawn the MSYS process
+  // directly so its Windows PID can be matched in the POSIX process table.
+  if (!posix && basename(command).toLowerCase() === "bash.exe") {
+    const direct = join(dirname(command), "..", "usr", "bin", "bash.exe");
+    if (existsSync(direct)) command = direct;
+  }
+  const child = spawn(command, args, {
+    cwd: options.cwd,
+    shell: false,
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+    detached: posix,
+  });
+  let stdout = "";
+  let stderr = "";
+  let killed = false;
+  let spawned = false;
+  let settled = false;
+  let finishing = false;
+  let force: NodeJS.Timeout | undefined;
+  let pipes: NodeJS.Timeout | undefined;
+  let termination: Promise<void> | undefined;
+  let terminated: (() => void) | undefined;
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", (chunk: string) => {
+    stdout += chunk;
+  });
+  child.stderr.on("data", (chunk: string) => {
+    stderr += chunk;
+  });
+  const kill = () => {
+    if (killed || settled) return;
+    killed = true;
+    if (posix) {
+      void killTree(child, "SIGTERM");
+      const completion = Promise.withResolvers<void>();
+      termination = completion.promise;
+      terminated = completion.resolve;
+      // Keep this timer referenced: a closing transport must not exit
+      // before a surviving member of the managed group receives SIGKILL.
+      force = setTimeout(() => {
+        void killTree(child, "SIGKILL");
+        completion.resolve();
+      }, PROCESS_KILL_GRACE_MS);
+    } else termination = killTree(child);
+  };
+  const timer =
+    options.timeout > 0 ? setTimeout(kill, options.timeout) : undefined;
+  if (options.signal?.aborted) kill();
+  else options.signal?.addEventListener("abort", kill, { once: true });
+  const cleanup = () => {
+    clearTimeout(timer);
+    clearTimeout(force);
+    clearTimeout(pipes);
+    options.signal?.removeEventListener("abort", kill);
+  };
+  const finish = async (code: number | null, signal: NodeJS.Signals | null) => {
+    if (settled || finishing) return;
+    finishing = true;
+    clearTimeout(pipes);
+    if (posix && terminated && !groupExists(child)) {
+      clearTimeout(force);
+      terminated();
+    }
+    if (termination) await termination;
+    settled = true;
+    cleanup();
+    resolve({
+      stdout,
+      stderr,
+      code: code ?? (signal ? 128 + signalNumber(signal) : 1),
+      killed,
+    });
+  };
+  child.on("spawn", () => {
+    spawned = true;
+  });
+  child.on("error", (error) => {
+    if (spawned) return;
+    settled = true;
+    cleanup();
+    reject(error);
+  });
+  child.on("exit", (code, signal) => {
+    // An escaped descendant may hold inherited pipes open indefinitely.
+    pipes = setTimeout(() => {
+      child.stdout.destroy();
+      child.stderr.destroy();
+      void finish(code, signal);
+    }, PROCESS_PIPE_GRACE_MS);
+  });
+  child.on("close", (code, signal) => {
+    void finish(code, signal);
+  });
+  return promise;
+};
+
+function signalNumber(signal: NodeJS.Signals): number {
+  const numbers: Partial<Record<NodeJS.Signals, number>> = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGKILL: 9,
+    SIGTERM: 15,
+  };
+  return numbers[signal] ?? 0;
+}