toolnexus 0.19.0 → 0.21.0

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.d.ts

@@ -19,6 +19,8 @@ export declare const DEFAULT_CLASSIFIER_MODEL = "jev-latest";
 export declare const DEFAULT_CLASSIFIER_API_KEY_ENV = "TYPESAFE_API_KEY";
 /** Bounds ONE request; a classifier has no loop to bound. */
 export declare const DEFAULT_CLASSIFIER_TIMEOUT_MS = 10000;
+/** `evaluateBatch`: at most this many states in flight by default. */
+export declare const DEFAULT_BATCH_CONCURRENCY = 16;
 /**
  * A named BACKEND: `baseUrl`, `model` and `apiKeyEnv` are only jointly valid, so they travel as
  * a UNIT (ADR 0027 D1). `jev-latest` is TypeSafe's spelling; the gateway spells the same model
@@ -95,6 +97,8 @@ export declare function score(instructions: string, criteria: string[]): ScoreQu
  * obligation on `ChoiceQuestion`.
  */
 export declare function choiceOver(instructions: string, items: Record<string, string>): ChoiceQuestion;
+/** The wire form of one question — the object itself, minus an absent `criteria`. */
+export declare function questionWire(q: Question): Record<string, unknown>;
 /**
  * Canonical JSON: object keys sorted recursively in CODE-UNIT (ASCII) order, arrays NEVER
  * reordered, compact separators, and `<>&'"` plus non-ASCII transmitted raw.
@@ -298,6 +302,16 @@ export declare class Classifier {
      * INDEPENDENT — one answer is never context for another.
      */
     evaluate(state: unknown, questions: Record<string, Question>, signal?: AbortSignal): Promise<Decision>;
+    /**
+     * The same questions over many states (SPEC §8B "Batch"). Each state goes through
+     * `evaluate`, at most `concurrency` (default 16) in flight; decisions come back in STATE
+     * order. Fails closed: the first failing state's index is named and no decisions return.
+     * No states is an error and sends nothing.
+     */
+    evaluateBatch(states: readonly unknown[], questions: Record<string, Question>, opts?: {
+        signal?: AbortSignal;
+        concurrency?: number;
+    }): Promise<Decision[]>;
     /**
      * Emits ONE warning per degenerate question key per classifier, naming the key, and changes
      * nothing about the request. Repairing would invent option descriptions the caller did not

package/dist/classifier.js

@@ -9,6 +9,8 @@ export const DEFAULT_CLASSIFIER_MODEL = "jev-latest";
 export const DEFAULT_CLASSIFIER_API_KEY_ENV = "TYPESAFE_API_KEY";
 /** Bounds ONE request; a classifier has no loop to bound. */
 export const DEFAULT_CLASSIFIER_TIMEOUT_MS = 10_000;
+/** `evaluateBatch`: at most this many states in flight by default. */
+export const DEFAULT_BATCH_CONCURRENCY = 16;
 /** The two servable pairings, as configurations rather than six independently-choosable cells. */
 export const CLASSIFIER_BACKENDS = {
     typesafe: { baseUrl: DEFAULT_CLASSIFIER_BASE_URL, model: DEFAULT_CLASSIFIER_MODEL, apiKeyEnv: DEFAULT_CLASSIFIER_API_KEY_ENV },
@@ -45,7 +47,7 @@ export function choiceOver(instructions, items) {
     return choice(instructions, items);
 }
 /** The wire form of one question — the object itself, minus an absent `criteria`. */
-function questionWire(q) {
+export function questionWire(q) {
     switch (q.type) {
         case "noul":
             return q.criteria === undefined
@@ -362,6 +364,37 @@ export class Classifier {
         });
         return decision;
     }
+    /**
+     * The same questions over many states (SPEC §8B "Batch"). Each state goes through
+     * `evaluate`, at most `concurrency` (default 16) in flight; decisions come back in STATE
+     * order. Fails closed: the first failing state's index is named and no decisions return.
+     * No states is an error and sends nothing.
+     */
+    async evaluateBatch(states, questions, opts = {}) {
+        if (!states || states.length === 0)
+            throw new Error("classifier: no states to evaluate");
+        const limit = Math.max(1, opts.concurrency ?? DEFAULT_BATCH_CONCURRENCY);
+        const out = new Array(states.length);
+        const errs = new Array(states.length);
+        let next = 0;
+        const worker = async () => {
+            while (next < states.length) {
+                const i = next++;
+                try {
+                    out[i] = await this.evaluate(states[i], questions, opts.signal);
+                }
+                catch (e) {
+                    errs[i] = e;
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(limit, states.length) }, worker));
+        for (let i = 0; i < states.length; i++) {
+            if (i in errs)
+                throw new Error(`classifier: state ${i}: ${errText(errs[i])}`, { cause: errs[i] });
+        }
+        return out;
+    }
     // ---------------------------------------------------------------- degenerate
     /**
      * Emits ONE warning per degenerate question key per classifier, naming the key, and changes
@@ -443,8 +476,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) {