toolnexus 0.19.0 → 0.20.0

package/dist/agents/home.js

@@ -188,9 +188,11 @@ export function startAgent(a, run, hb) {
                 });
             }
         }
-        cancel = runtime.clock.setTimeout(beat, hb.everyMs); // self-reschedule → one live timer
+        // keepAlive:false — a heartbeat is housekeeping and must never be the reason
+        // a host process stays up.
+        cancel = runtime.clock.setTimeout(beat, hb.everyMs, { keepAlive: false }); // self-reschedule → one live timer
     };
-    cancel = runtime.clock.setTimeout(beat, hb.everyMs);
+    cancel = runtime.clock.setTimeout(beat, hb.everyMs, { keepAlive: false });
     return {
         runtime,
         beats,

package/dist/agents/runtime.d.ts

@@ -22,10 +22,19 @@ import type { Answer, Request, Tool } from "../types.js";
 export interface Clock {
     /** Current time in ms (epoch or virtual). */
     now(): number;
-    /** Schedule `fn` after `ms`; returns a cancel function. */
-    setTimeout(fn: () => void, ms: number): () => void;
+    /** Schedule `fn` after `ms`; returns a cancel function.
+     *
+     * `keepAlive` defaults to TRUE, and the default is the important half: a timer
+     * that cannot hold the event loop open never fires when it is the only thing
+     * left to do — which is precisely a deadline whose promise nothing else will
+     * settle. Background housekeeping that should never hold a process open (a
+     * heartbeat) passes `false` explicitly. A host's own Clock may ignore the
+     * option; it then behaves as that host's timers always have. */
+    setTimeout(fn: () => void, ms: number, opts?: {
+        keepAlive?: boolean;
+    }): () => void;
 }
-/** The real clock (default). Timers are unref'd so they never hold the process open. */
+/** The real clock (default). See `Clock.setTimeout` for why `keepAlive` defaults to true. */
 export declare const systemClock: Clock;
 /** §7D hierarchical budget. Carved at spawn (`min(own, parent remaining)`) and
  * live-enforced against the whole ancestor chain before each turn and spawn.

package/dist/agents/runtime.js

@@ -2,12 +2,13 @@ import { createClient, createInProcessFetch, InMemoryConversationStore, } from "
 import { runGated } from "./loop.js";
 import { createToolkit } from "../toolkit.js";
 import { defineTool } from "../native.js";
-/** The real clock (default). Timers are unref'd so they never hold the process open. */
+/** The real clock (default). See `Clock.setTimeout` for why `keepAlive` defaults to true. */
 export const systemClock = {
     now: () => Date.now(),
-    setTimeout(fn, ms) {
+    setTimeout(fn, ms, opts) {
         const t = setTimeout(fn, ms);
-        t.unref?.();
+        if (opts?.keepAlive === false)
+            t.unref?.();
         return () => clearTimeout(t);
     },
 };

package/dist/builtin.d.ts

@@ -1,9 +1,33 @@
 import type { Tool } from "./types.js";
-/** Config for the single global builtin toggle (mirrors MCP isEnabled precedence). */
+/**
+ * Config for the single global builtin toggle (mirrors MCP isEnabled precedence),
+ * plus the host boundary: which interpreter `bash` runs, what a relative path
+ * resolves against, and whether paths leaving it are refused (SPEC §4A, ADR 0034).
+ */
 export type BuiltinsConfig = boolean | {
     enabled?: boolean;
     disabled?: boolean;
     tools?: Record<string, boolean>;
+    /**
+     * The argv prefix `bash` runs a command with — `["sh","-c"]`,
+     * `["cmd","/d","/s","/c"]`, `["powershell","-NoProfile","-Command"]`. Set,
+     * it is used verbatim. Absent, an interpreter is DETECTED at toolkit
+     * construction (POSIX `sh -c`; Windows %COMSPEC% → pwsh → powershell → bash).
+     */
+    shell?: string[];
+    /**
+     * What a RELATIVE path means, for every builtin that touches the
+     * filesystem — including the paths inside apply_patch's patch text, and as
+     * bash's default workdir. Empty ⇒ the process cwd, i.e. today's behaviour.
+     */
+    baseDir?: string;
+    /**
+     * Refuse any path whose CANONICAL form leaves baseDir (symlinks, Windows
+     * junctions and short names resolved on both sides), and Windows reserved
+     * device names. Default off. A guarantee about path resolution in the file
+     * builtins, NOT a sandbox — `bash` still reaches the whole filesystem.
+     */
+    confineToBaseDir?: boolean;
 };
 /**
  * Whether the builtin source is on. Default ON. Same precedence as MCP:
@@ -22,4 +46,10 @@ export declare function selectBuiltins(cfg: BuiltinsConfig | undefined): Tool[];
  * for parity: bash, read, write, edit, grep, glob, webfetch, question,
  * apply_patch, todowrite.
  */
-export declare function createBuiltinTools(): Tool[];
+export declare function createBuiltinTools(cfg?: BuiltinsConfig): Tool[];
+/**
+ * The interpreter the builtins resolved for `bash` — what a host prints, and
+ * what `metadata.shell` carries on every bash result. Throws the same error
+ * `selectBuiltins` fails construction with when nothing resolves.
+ */
+export declare function builtinShell(cfg?: BuiltinsConfig): string[];

package/dist/builtin.js

@@ -7,13 +7,151 @@
  * ToolResult{isError:true}, never a thrown exception across the boundary. Paths
  * resolve relative to the process working directory unless absolute.
  */
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, readdirSync, realpathSync } from "node:fs";
 import { compareCodePoints, sortEntriesByName, toPosixPath } from "./order.js";
 import path from "node:path";
 import { pending } from "./types.js";
 import { mediaTypeFor } from "./content.js";
+/**
+ * How long a job gets between "please stop" and "stop". Fixed, and identical in
+ * every port, so a timeout means the same thing everywhere.
+ */
+const KILL_GRACE_MS = 2000;
+const WIN_RESERVED = new Set([
+    "CON", "PRN", "AUX", "NUL",
+    "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
+    "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
+]);
+/** Does `name` resolve as an executable on PATH? (PATHEXT-aware on Windows.) */
+function resolvesOnPath(name) {
+    if (name.includes(path.sep) || name.includes("/"))
+        return existsSync(name);
+    const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    const exts = process.platform === "win32"
+        ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+        : [""];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            if (existsSync(path.join(dir, name + ext)))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * The interpreters tried when the host names none. %COMSPEC% leads on Windows
+ * because PowerShell is routinely blocked by execution or application-control
+ * policy, while %COMSPEC% is always present.
+ */
+function shellCandidates() {
+    // `/bin/sh` first, then a PATH lookup: `shell: true` means literally
+    // `/bin/sh`, while spawning the bare name `sh` is a PATH lookup — two
+    // different binaries on a machine that has both. Naming the absolute path
+    // first is what makes dropping `shell: true` byte-identical here.
+    if (process.platform !== "win32")
+        return [["/bin/sh", "-c"], ["sh", "-c"]];
+    const out = [];
+    if (process.env.COMSPEC)
+        out.push([process.env.COMSPEC, "/d", "/s", "/c"]);
+    out.push(["cmd.exe", "/d", "/s", "/c"], ["pwsh", "-NoProfile", "-Command"], ["powershell", "-NoProfile", "-Command"], ["bash", "-lc"]);
+    return out;
+}
+/**
+ * The host boundary the builtins are allowed to know about. Constructed once,
+ * at toolkit construction: a missing interpreter is a configuration fact, and
+ * turn fourteen of a paid run is the expensive place to learn it.
+ */
+class BuiltinEnv {
+    shell;
+    shellError;
+    baseDir;
+    confine;
+    constructor(cfg) {
+        const obj = typeof cfg === "object" && cfg !== null ? cfg : {};
+        this.baseDir = obj.baseDir ?? "";
+        this.confine = obj.confineToBaseDir === true;
+        if (obj.shell && obj.shell.length > 0) {
+            this.shell = obj.shell;
+            return;
+        }
+        const tried = [];
+        for (const argv of shellCandidates()) {
+            tried.push(argv[0]);
+            if (resolvesOnPath(argv[0])) {
+                this.shell = argv;
+                return;
+            }
+        }
+        this.shell = [];
+        this.shellError = new Error(`no shell interpreter found (tried: ${tried.join(", ")}); set builtins.shell, or disable the bash builtin with builtins.tools.bash = false`);
+    }
+    /** The interpreter argv, or the detection error when there is none. */
+    shellArgv() {
+        if (this.shellError)
+            throw this.shellError;
+        return this.shell;
+    }
+    get shellLabel() {
+        return this.shell.join(" ");
+    }
+    /** The directory a command or a walk starts from. */
+    dir() {
+        return this.baseDir || process.cwd();
+    }
+    /**
+     * Map a tool-supplied path onto the filesystem: relative to baseDir (or, with
+     * none, exactly as before), and refused when confinement is on and the
+     * canonical target is outside the base.
+     */
+    resolvePath(p) {
+        if (this.confine && !this.baseDir) {
+            throw new Error("confineToBaseDir is set but baseDir is empty");
+        }
+        const full = this.baseDir && !path.isAbsolute(p) ? path.join(this.baseDir, p) : p;
+        if (!this.confine)
+            return full;
+        if (process.platform === "win32") {
+            const base = path.basename(full).split(".")[0].trim().toUpperCase();
+            if (WIN_RESERVED.has(base)) {
+                throw new Error(`${p} names a reserved device, which is not a file inside ${this.baseDir}`);
+            }
+        }
+        const canonBase = canonicalPath(this.baseDir);
+        const canonTarget = canonicalPath(full);
+        const rel = path.relative(canonBase, canonTarget);
+        if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+            throw new Error(`${p} resolves outside baseDir ${this.baseDir}`);
+        }
+        return full;
+    }
+}
+/**
+ * Resolve a path for comparison. Symlinks — and, on Windows, directory
+ * junctions and 8.3 short names — are resolved on the DEEPEST EXISTING
+ * ancestor and the remaining segments re-attached, because a file `write` is
+ * about to create has no real path, and a check that only works on existing
+ * files is not a check for `write`.
+ */
+function canonicalPath(p) {
+    const abs = path.resolve(p);
+    let cur = abs;
+    let tail = "";
+    for (;;) {
+        try {
+            const resolved = realpathSync.native(cur);
+            return tail ? path.join(resolved, tail) : resolved;
+        }
+        catch {
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return abs;
+            tail = tail ? path.join(path.basename(cur), tail) : path.basename(cur);
+            cur = parent;
+        }
+    }
+}
 /**
  * Whether the builtin source is on. Default ON. Same precedence as MCP:
  * `disabled:true` wins, else `enabled:false` disables, otherwise enabled.
@@ -39,10 +177,14 @@ export function selectBuiltins(cfg) {
     if (!builtinsEnabled(cfg))
         return [];
     const map = typeof cfg === "object" ? cfg.tools : undefined;
-    const all = createBuiltinTools();
-    if (!map)
-        return all;
-    return all.filter((t) => map[t.name] !== false);
+    const all = createBuiltinTools(cfg);
+    const selected = map ? all.filter((t) => map[t.name] !== false) : all;
+    // A missing interpreter is a construction-time failure, and only when `bash`
+    // survived the toggles: a host that disabled it should run fine on a box with
+    // no shell at all (ADR 0034 D1).
+    if (selected.some((t) => t.name === "bash"))
+        builtinShell(cfg);
+    return selected;
 }
 const err = (output, metadata) => ({ output, isError: true, metadata });
 const ok = (output, metadata) => ({ output, isError: false, metadata });
@@ -133,7 +275,7 @@ function walkFiles(root) {
 // ---------------------------------------------------------------------------
 // individual tools
 // ---------------------------------------------------------------------------
-function bashTool() {
+function bashTool(env) {
     return builtin("bash", "Run a shell command and return its combined stdout+stderr. Non-zero exit is an error.", {
         type: "object",
         properties: {
@@ -144,37 +286,131 @@ function bashTool() {
         },
         required: ["command"],
         additionalProperties: false,
-    }, (args) => new Promise((resolve) => {
+    }, (args, ctx) => new Promise((resolve) => {
         const command = String(args.command ?? "");
         if (!command)
             return resolve(err("bash: command is required"));
-        const workdir = args.workdir ? String(args.workdir) : process.cwd();
+        let argv;
+        let workdir;
+        try {
+            argv = env.shellArgv();
+            workdir = args.workdir ? env.resolvePath(String(args.workdir)) : env.dir();
+        }
+        catch (e) {
+            return resolve(err(`bash: ${e.message}`));
+        }
         const timeout = typeof args.timeout === "number" ? args.timeout : 60_000;
-        const child = spawn(command, { shell: true, cwd: workdir });
+        const meta = { shell: env.shellLabel };
+        // NOT `shell: true`: on Windows that silently means cmd.exe while every
+        // other port fails loudly, and it hides WHICH interpreter ran. `detached`
+        // puts the child in its own process group so a kill reaches the command
+        // AND everything it started — without it the kill reaches the
+        // interpreter only and the real work runs on, reparented (ADR 0034 D4).
+        const child = spawn(argv[0], [...argv.slice(1), command], {
+            cwd: workdir,
+            detached: process.platform !== "win32",
+        });
         let out = "";
-        let timedOut = false;
-        const timer = setTimeout(() => {
-            timedOut = true;
-            child.kill("SIGKILL");
-        }, timeout);
+        let stopped = "";
+        let killedTree = false;
+        let settled = false;
+        // Captured once, at spawn: `detached` makes the child a process-group
+        // LEADER, so its pid is the pgid. Reading it later from `child` would
+        // risk signalling by a pid the runtime has already let go of.
+        const pgid = child.pid;
+        const killJob = (graceful) => {
+            // Nothing may be signalled once this call has settled: a stale timer
+            // firing after the fact would aim at a pid the OS may have reissued,
+            // and a NEGATED pid is a whole process group.
+            if (settled)
+                return false;
+            if (typeof pgid !== "number" || !Number.isInteger(pgid) || pgid <= 1)
+                return false;
+            try {
+                if (process.platform === "win32") {
+                    // Windows has NO graceful termination for a console process, and
+                    // asking anyway is worse than not asking: measured on a native
+                    // Windows box, `taskkill /T` without `/F` refuses every console
+                    // process in the tree ("can only be terminated forcefully") while
+                    // still being able to take the parent down — which reparents the
+                    // grandchild and leaves it running. So the job is terminated at
+                    // once there, and the grace window is a POSIX effect (ADR 0034 D4).
+                    const r = spawnSync("taskkill", ["/T", "/F", "/PID", String(pgid)]);
+                    return r.status === 0;
+                }
+                // Never signal a REAPED child by negated pid: that pid may belong to
+                // something else by now, and the blast radius is a whole process
+                // GROUP. (On Windows above, taskkill targets one pid and a dead pid
+                // is merely an error, so the same guard is not needed there — and
+                // must not be applied, because the tree can outlive the child.)
+                if (child.exitCode !== null || child.signalCode !== null)
+                    return false;
+                process.kill(-pgid, graceful ? "SIGTERM" : "SIGKILL");
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        // Ask, wait out the grace window, then insist. A runner that gets
+        // SIGTERM removes its temp directories; one that gets SIGKILL does not.
+        const stop = (why) => {
+            if (stopped)
+                return;
+            stopped = why;
+            killedTree = killJob(true);
+            graceTimer = setTimeout(() => {
+                if (killJob(false))
+                    killedTree = true;
+            }, KILL_GRACE_MS);
+        };
+        let graceTimer;
+        const timer = setTimeout(() => stop("timeout"), timeout);
+        const signal = ctx?.signal;
+        const onAbort = () => stop("cancelled");
+        signal?.addEventListener?.("abort", onAbort, { once: true });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (graceTimer)
+                clearTimeout(graceTimer);
+            signal?.removeEventListener?.("abort", onAbort);
+            resolve(result);
+        };
         child.stdout?.on("data", (d) => (out += d.toString()));
         child.stderr?.on("data", (d) => (out += d.toString()));
-        child.on("error", (e) => {
-            clearTimeout(timer);
-            resolve(err(`bash: ${e.message}`));
-        });
+        child.on("error", (e) => finish(err(`bash: ${e.message}`, meta)));
         child.on("close", (code) => {
-            clearTimeout(timer);
-            if (timedOut)
-                return resolve(err(`bash: command timed out after ${timeout}ms\n${out}`));
-            if (code !== 0) {
-                return resolve(err(`${out}\nbash: command exited with code ${code}`, { exitCode: code }));
+            if (stopped) {
+                // WINDOWS ONLY, and the platform guard is the point. There, the
+                // direct child closing does not mean the job is gone — a detached
+                // grandchild outlives it — so the tree is terminated here by pid.
+                //
+                // On POSIX this must NOT run. `close` only fires once the stdio the
+                // grandchild inherited has closed, so the job is already gone; and
+                // signalling `-pid` after the child has been reaped aims at whatever
+                // process now owns that pid. PIDs recycle fast on a busy CI box, and
+                // the blast radius of a negated pid is a whole process GROUP — which
+                // is how this killed sibling test workers on the GitHub runner while
+                // passing on macOS, in a container, and on its own.
+                if (!killedTree && process.platform === "win32")
+                    killedTree = killJob(false);
+                meta.timedOut = stopped === "timeout";
+                meta.killedTree = killedTree;
+                return finish(err(stopped === "timeout"
+                    ? `bash: command timed out after ${timeout}ms\n${out}`
+                    : `bash: command cancelled\n${out}`, meta));
             }
-            resolve(ok(out, { exitCode: code }));
+            meta.exitCode = code;
+            if (code !== 0)
+                return finish(err(`${out}\nbash: command exited with code ${code}`, meta));
+            finish(ok(out, meta));
         });
     }));
 }
-function readTool() {
+function readTool(env) {
     return builtin("read", "Read a file. Recognised media (png/jpg/jpeg/gif/webp/pdf/mp3/wav) comes back as a content part; anything else is read as UTF-8 text, with offset/limit returning that line window.", {
         type: "object",
         properties: {
@@ -189,15 +425,17 @@ function readTool() {
         if (!p)
             return err("read: path is required");
         let bytes;
+        let full;
         try {
-            bytes = await fs.readFile(p);
+            full = env.resolvePath(p);
+            bytes = await fs.readFile(full);
         }
         catch (e) {
             return err(`read: ${e instanceof Error ? e.message : String(e)}`);
         }
         // §6: a recognised media extension comes back as a part. The table is fixed — no magic-byte
         // sniffing and no platform mime database, whose contents vary per machine.
-        const media = mediaTypeFor(p);
+        const media = mediaTypeFor(full);
         if (media) {
             return {
                 output: `${p} (${media.mimeType}, ${bytes.length} bytes)`,
@@ -224,7 +462,7 @@ function readTool() {
         return ok(lines.slice(start, start + limit).join("\n"));
     });
 }
-function writeTool() {
+function writeTool(env) {
     return builtin("write", "Write content to a file (create/overwrite), creating parent directories.", {
         type: "object",
         properties: {
@@ -238,13 +476,20 @@ function writeTool() {
         if (!p)
             return err("write: path is required");
         const content = typeof args.content === "string" ? args.content : String(args.content ?? "");
-        await fs.mkdir(path.dirname(path.resolve(p)), { recursive: true });
-        await fs.writeFile(p, content, "utf8");
+        let full;
+        try {
+            full = env.resolvePath(p);
+        }
+        catch (e) {
+            return err(`write: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        await fs.mkdir(path.dirname(path.resolve(full)), { recursive: true });
+        await fs.writeFile(full, content, "utf8");
         const bytes = Buffer.byteLength(content, "utf8");
         return ok(`Wrote ${bytes} bytes to ${p}`, { bytes });
     });
 }
-function editTool() {
+function editTool(env) {
     return builtin("edit", "Exact-string replace in a file. Default replaces a single unique occurrence; replaceAll replaces all.", {
         type: "object",
         properties: {
@@ -265,8 +510,10 @@ function editTool() {
         const oldString = args.oldString;
         const newString = typeof args.newString === "string" ? args.newString : String(args.newString ?? "");
         let content;
+        let full;
         try {
-            content = await fs.readFile(p, "utf8");
+            full = env.resolvePath(p);
+            content = await fs.readFile(full, "utf8");
         }
         catch (e) {
             return err(`edit: ${e instanceof Error ? e.message : String(e)}`);
@@ -289,7 +536,7 @@ function editTool() {
         });
     });
 }
-function grepTool() {
+function grepTool(env) {
     return builtin("grep", "Search file contents by regex under a directory. Output is file:line:text matches.", {
         type: "object",
         properties: {
@@ -311,7 +558,13 @@ function grepTool() {
         catch (e) {
             return err(`grep: invalid regex: ${e instanceof Error ? e.message : String(e)}`);
         }
-        const root = args.path ? String(args.path) : process.cwd();
+        let root;
+        try {
+            root = args.path ? env.resolvePath(String(args.path)) : env.dir();
+        }
+        catch (e) {
+            return err(`grep: ${e instanceof Error ? e.message : String(e)}`);
+        }
         const include = args.include ? String(args.include) : undefined;
         const limit = typeof args.limit === "number" ? args.limit : 100;
         // Was the worse of the two builtins: capped MID-WALK and never sorted at all, so both the
@@ -341,7 +594,7 @@ function grepTool() {
         return ok(matches.join("\n"), { count: matches.length });
     });
 }
-function globTool() {
+function globTool(env) {
     return builtin("glob", "List files matching a glob under a directory. Output is newline-joined relative paths.", {
         type: "object",
         properties: {
@@ -355,7 +608,13 @@ function globTool() {
         const pattern = String(args.pattern ?? "");
         if (!pattern)
             return err("glob: pattern is required");
-        const root = args.path ? String(args.path) : process.cwd();
+        let root;
+        try {
+            root = args.path ? env.resolvePath(String(args.path)) : env.dir();
+        }
+        catch (e) {
+            return err(`glob: ${e instanceof Error ? e.message : String(e)}`);
+        }
         const limit = typeof args.limit === "number" ? args.limit : 100;
         // Collect ALL matches, order them, THEN cap (A24/A25): breaking the walk at the cap let
         // the filesystem decide WHICH files the model sees, not merely their order. The emitted
@@ -581,7 +840,7 @@ function applyUpdate(content, body) {
     }
     return result;
 }
-function applyPatchTool() {
+function applyPatchTool(env) {
     return builtin("apply_patch", "Apply a patch (Begin/End Patch grammar: Add/Update/Delete File). Atomic — a non-matching hunk aborts with no writes.", {
         type: "object",
         properties: {
@@ -600,6 +859,16 @@ function applyPatchTool() {
         catch (e) {
             return err(`apply_patch: ${e instanceof Error ? e.message : String(e)}`);
         }
+        // The paths live INSIDE the patch text, not in the arguments, so a host
+        // cannot rewrite them from a hook — this is the one case that genuinely
+        // needs the base directory to be library-side (ADR 0034 D2).
+        try {
+            for (const op of ops)
+                op.path = env.resolvePath(op.path);
+        }
+        catch (e) {
+            return err(`apply_patch: ${e instanceof Error ? e.message : String(e)}`);
+        }
         // Stage every write/delete first; only touch the filesystem once all hunks apply.
         const writes = [];
         const deletes = [];
@@ -643,17 +912,26 @@ function applyPatchTool() {
  * for parity: bash, read, write, edit, grep, glob, webfetch, question,
  * apply_patch, todowrite.
  */
-export function createBuiltinTools() {
+export function createBuiltinTools(cfg) {
+    const env = new BuiltinEnv(cfg);
     return [
-        bashTool(),
-        readTool(),
-        writeTool(),
-        editTool(),
-        grepTool(),
-        globTool(),
+        bashTool(env),
+        readTool(env),
+        writeTool(env),
+        editTool(env),
+        grepTool(env),
+        globTool(env),
         webfetchTool(),
         questionTool(),
-        applyPatchTool(),
+        applyPatchTool(env),
         todowriteTool(),
     ];
 }
+/**
+ * The interpreter the builtins resolved for `bash` — what a host prints, and
+ * what `metadata.shell` carries on every bash result. Throws the same error
+ * `selectBuiltins` fails construction with when nothing resolves.
+ */
+export function builtinShell(cfg) {
+    return new BuiltinEnv(cfg).shellArgv();
+}

package/dist/classifier.js

@@ -443,8 +443,10 @@ export class Classifier {
         let lastErr;
         for (let attempt = 0;; attempt++) {
             const timer = new AbortController();
+            // NOT unref'd: this watchdog is the only thing that will end a request an
+            // injected `fetch` never settles, and an unref'd timer cannot keep the
+            // loop alive long enough to fire. It is cleared on every exit path below.
             const t = setTimeout(() => timer.abort(new Error(`classifier: request timeout after ${this.timeoutMs}ms`)), this.timeoutMs);
-            t.unref?.();
             const onOuter = () => timer.abort(signal.reason);
             if (signal) {
                 if (signal.aborted) {

package/dist/client.d.ts

@@ -412,7 +412,17 @@ export declare class Client {
     /** §0.10 system message. The toolkit is OPTIONAL — with none there is no skills prompt and
      *  the system message is the system prompt alone. This deref was issue #86 (ADR 0023). */
     private system;
-    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
+    /** Run-scoped timeout timers, cleared by `releaseSignal` when the run settles. */
+    private readonly runTimers;
+    /** Drop a run's timeout timer. Idempotent, and safe on a signal that never had one. */
+    private releaseSignal;
+    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal.
+     *
+     * The timer is deliberately NOT `unref()`d. An unref'd timer cannot keep the event loop
+     * alive, so a run whose only pending work is a request that never settles — an injected
+     * `fetch`, an in-process transport, a stalled stream — drains the loop and the timeout never
+     * fires at all, which is the one case `timeoutMs` exists for. It is RELEASED instead: the
+     * caller clears it however the run leaves, so a finished run holds nothing open. */
     private makeSignal;
     /** fetch with retry + exponential backoff on the default retryable set (429/500/502/503/504/529)
      * plus network errors and anything `retryableStatuses` added, honoring Retry-After; aborts via signal.
@@ -425,6 +435,10 @@ export declare class Client {
     /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
     private llmCallJson;
     private runOpenAI;
+    private runAnthropic;
+    private streamOpenAI;
+    private streamAnthropic;
+    private runOpenAIWithSignal;
     private result;
     /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
     private pendingRun;
@@ -434,9 +448,9 @@ export declare class Client {
      * no `waitFor` is configured (the run should stop and surface the request).
      */
     private resolvePending;
-    private runAnthropic;
-    private streamOpenAI;
-    private streamAnthropic;
+    private runAnthropicWithSignal;
+    private streamOpenAIWithSignal;
+    private streamAnthropicWithSignal;
 }
 export declare function createClient(opts: ClientOptions): Client;
 /** One tool call an in-process model asks for. Flat on purpose: the nested