@animalabs/agent-framework 0.22.2 → 0.22.4

package/dist/src/closest-names.js

@@ -0,0 +1,98 @@
+/**
+ * The names someone most likely meant, when the one they gave matches none:
+ * for a refusal's "did you mean", such as a tool name an agent got wrong.
+ *
+ * Case is ignored. A candidate that the name matches as a whole `--` segment
+ * ("ls" for "workspace--ls"), then one that starts with it or that it starts
+ * with, then one that contains it or that it contains, ranks ahead of one
+ * that is only a few edits away, however many edits those matches take. The
+ * prefix and substring matches need three characters on the shorter side,
+ * since a letter or two is in nearly every name. A candidate that matches in
+ * none of those ways counts only within the edits noiseLimit allows, and past
+ * that it's noise. So a name that is part of no candidate, holds none and is
+ * close to none gets nothing back, and a name in a crowded namespace doesn't
+ * get its neighbours (`workspace--write` for `workspace--read`).
+ */
+export function closestNames(name, candidates, max = 2) {
+    const wanted = name.toLowerCase();
+    const ranked = [];
+    for (const candidate of new Set(candidates)) {
+        const other = candidate.toLowerCase();
+        const shorter = Math.min(wanted.length, other.length);
+        const tier = other === wanted ? 0
+            : wanted && other.split('--').includes(wanted) ? 1
+                : shorter >= 3 && (other.startsWith(wanted) || wanted.startsWith(other)) ? 2
+                    : shorter >= 3 && (other.includes(wanted) || wanted.includes(other)) ? 3
+                        : 4;
+        // In tiers 0 to 3 one name holds the other, so the length difference is
+        // already their distance, and a long name skips the edit table.
+        const limit = tier === 4 ? noiseLimit(wanted, other) : Infinity;
+        const distance = tier === 4 ? editDistance(wanted, other, limit) : Math.abs(wanted.length - other.length);
+        if (distance > limit)
+            continue;
+        ranked.push({ candidate, tier, distance });
+    }
+    // A stable sort: candidates that tie keep the order they were given in.
+    ranked.sort((a, b) => a.tier - b.tier || a.distance - b.distance);
+    return ranked.slice(0, Math.max(0, max)).map((entry) => entry.candidate);
+}
+/**
+ * Whether `name` looks like a slip for `candidate`, ignoring case: the same;
+ * a few edits apart, where a transposition counts as one edit; or, at three
+ * characters or more, a part of it, which is a shortened attempt at it
+ * (`mode` for `deliveryMode`, `interval` for `refillIntervalMs`). A part
+ * counts only that way round: a name that holds the candidate, and is more
+ * edits from it than a slip allows, is another name, usually an extra that
+ * explains it (`channel_note` beside `channel`, where `channels` is a slip).
+ * Beyond these, two names are different names rather than one mistyped.
+ */
+export function isNearMiss(name, candidate) {
+    const a = name.toLowerCase(), b = candidate.toLowerCase();
+    if (a.length >= 3 && b.includes(a))
+        return true;
+    const limit = noiseLimit(a, b);
+    return editDistance(a, b, limit) <= limit;
+}
+/**
+ * The most edits that still read as a slip: a quarter of what follows the
+ * prefix the two names share, and at least one. A shared prefix is mostly a
+ * namespace (`workspace--`, `mcpl--discord--`) and says nothing about the
+ * rest, so `workspace--read` and `workspace--write` are four edits apart in
+ * a four-letter tool name, not in a fifteen-letter one.
+ */
+function noiseLimit(a, b) {
+    let shared = 0;
+    while (shared < a.length && shared < b.length && a[shared] === b[shared])
+        shared++;
+    return Math.max(1, Math.floor((Math.max(a.length, b.length) - shared) / 4));
+}
+/**
+ * Edits between two strings: insertions, deletions, substitutions and
+ * swaps of neighbours (optimal string alignment). Past `limit` the exact
+ * count doesn't matter, so it answers `limit + 1` as soon as it is sure.
+ */
+function editDistance(a, b, limit) {
+    if (Math.abs(a.length - b.length) > limit)
+        return limit + 1;
+    let before = [];
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        let best = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let value = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                value = Math.min(value, before[j - 2] + 1);
+            current.push(value);
+            best = Math.min(best, value);
+        }
+        // No row's smallest entry is below the one before it, so none later can come back under the limit.
+        if (best > limit)
+            return limit + 1;
+        before = previous;
+        previous = current;
+    }
+    return previous[b.length];
+}
+//# sourceMappingURL=closest-names.js.map

package/dist/src/closest-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closest-names.js","sourceRoot":"","sources":["../../src/closest-names.ts"],"names":[],"mappings":"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"}

package/dist/src/code-execution/py-runner.d.ts

@@ -79,8 +79,6 @@ export declare class PyRunner {
     private idleTimer;
     private execCounter;
     private disposed;
-    /** An exec has passed the busy check but is still awaiting the interpreter. */
-    private starting;
     constructor(options: PyRunnerOptions);
     get busy(): boolean;
     /**
@@ -95,19 +93,32 @@ export declare class PyRunner {
      *
      * `opts.deadlineMs` replaces the runner's scriptTimeoutMs for this exec (a
      * per-call time limit); a background exec uses its `lifetimeMs` instead.
+     * `opts.ceilingMs` is the longest limit the deployment allows this kind of
+     * script: a script stopped at its limit is offered a longer one only below
+     * it. Without it, the stop doesn't say whether a longer limit would help.
+     * `opts.backgroundCeilingMs`, for a foreground exec, is the longest a
+     * background script may run: one stopped at its ceiling is offered
+     * background mode when that is longer.
      */
     exec(code: string, tools: InjectedTool[], background?: BackgroundExecOptions, opts?: {
         deadlineMs?: number;
+        ceilingMs?: number;
+        backgroundCeilingMs?: number;
     }): Promise<ExecResult>;
     /**
-     * Abort a running script (turn cancelled, agent reset/stopped). The
-     * interpreter is reclaimed: after an abort its state is suspect (a script
-     * died midway), and the next exec gets a fresh one.
+     * Abort the runner's script (its turn ended or is reset to run again, or the
+     * agent was reset or stopped), whether it's running or still waiting for its
+     * interpreter to start; a waiting script then never runs. The exec settles
+     * at once, and the interpreter is reclaimed, a starting one too: after an
+     * abort its state is suspect (a script died midway), and the next exec gets
+     * a fresh one.
      */
     abort(reason: string): void;
     dispose(): void;
     private ensureChild;
     private readyResolver;
+    /** Fails the readiness of an interpreter that is still starting (see reclaim). */
+    private readyFailer;
     private handleLine;
     private settlePending;
     /**

package/dist/src/code-execution/py-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"py-runner.d.ts","sourceRoot":"","sources":["../../../src/code-execution/py-runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"py-runner.d.ts","sourceRoot":"","sources":["../../../src/code-execution/py-runner.ts"],"names":[],"mappings":"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"}

package/dist/src/code-execution/py-runner.js

@@ -18,6 +18,7 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline';
+import { boundedErrorMessage } from '../error-message.js';
 import { PYTHON_RUNTIME_SOURCE } from './runtime-py.js';
 const DEFAULT_TOOL_CALL_TIMEOUT_MS = 270_000;
 const DEFAULT_SCRIPT_TIMEOUT_MS = 600_000;
@@ -35,6 +36,56 @@ export function formatLimit(ms) {
         return `${Math.round(ms / 6_000) / 10} min`;
     return `${Math.round(ms / 360_000) / 10} h`;
 }
+/**
+ * What a script stopped at its time limit is told after why: that the tool
+ * calls it made keep their effects, and whether a longer limit can help,
+ * which only the deployment's ceiling for its kind of script can say. A
+ * foreground script at its ceiling is offered background mode too, when its
+ * caller passes `backgroundCeilingMs` (the framework does for an agent that
+ * could start a background script as the script starts) and a background
+ * script may run longer.
+ */
+function limitRemedy(limitMs, ceilingMs, background, backgroundCeilingMs) {
+    const effects = 'Tool calls it had already made keep their effects, so check them before running it again.';
+    if (ceilingMs === undefined)
+        return effects;
+    if (limitMs < ceilingMs)
+        return `${effects} To give it longer, ${background ? 'start it with' : 'pass'} time_limit_ms up to ${ceilingMs} (${formatLimit(ceilingMs)}).`;
+    if (background)
+        return `${effects} ${formatLimit(limitMs)} is the longest a background script runs here; starting it again runs it from the top.`;
+    const inBackground = backgroundCeilingMs !== undefined && backgroundCeilingMs > limitMs
+        ? `, or run it with background: true, where a script can run up to ${formatLimit(backgroundCeilingMs)}` : '';
+    return `${effects} ${formatLimit(limitMs)} is the longest a script can run here, so split the work across shorter scripts${inBackground}.`;
+}
+/**
+ * Why a script didn't run when its interpreter didn't start. A spawn that
+ * found nothing it could run (ENOENT, EACCES) fails the same way until the
+ * host changes, so that one says code_execution can't run here rather than
+ * to try again. A failure before the spawn, while creating or writing the
+ * runtime's files, is about those files rather than the interpreter, and
+ * keeps Node's own text, which names the path for an open or a mkdtemp.
+ */
+function startFailure(pythonPath, err) {
+    const { code, syscall } = (err ?? {});
+    const spawning = typeof syscall === 'string' && syscall.startsWith('spawn');
+    if (spawning && (code === 'ENOENT' || code === 'EACCES')) {
+        const until = code === 'ENOENT' ? 'installs it or points this host at one' : 'makes it executable or points this host at another';
+        return `script didn't run: this host can't start its Python interpreter, ${pythonPath} (${code}), so code_execution can't run scripts here until whoever runs this host ${until}. Calling it again before then fails the same way.`;
+    }
+    if (typeof syscall === 'string' && !spawning) {
+        return `script didn't run: this host couldn't create or write the files its Python runtime starts from (${boundedErrorMessage(err)}), so none of the script ran. Run it again; if it fails the same way, ask whoever runs this host.`;
+    }
+    const why = typeof code === 'string' ? `couldn't be started (${code})` : boundedErrorMessage(err);
+    return `script didn't run: the Python interpreter, ${pythonPath}, ${why}, so none of the script ran. Run it again; if it fails the same way, ask whoever runs this host.`;
+}
+/** Why a script stopped when its interpreter exited under it, and what running it again does. */
+function interpreterExit(exitCode, signal, background) {
+    const how = signal ? `was ended by ${signal}` : `exited with code ${exitCode}`;
+    return `script stopped: the Python interpreter ${how} while it ran, so the rest of the script didn't run`
+        + `${background ? '' : ', and variables from earlier scripts are gone'}. Tool calls it had already made keep their effects, `
+        + 'so check them before you run it again in a new interpreter. If it stops the same way, check whether the script itself '
+        + `ends the process, for example ${signal ? 'by using too much memory' : 'with os._exit()'}; if not, ask whoever runs this host.`;
+}
 export class PyRunner {
     pythonPath;
     toolCallTimeoutMs;
@@ -52,8 +103,6 @@ export class PyRunner {
     idleTimer = null;
     execCounter = 0;
     disposed = false;
-    /** An exec has passed the busy check but is still awaiting the interpreter. */
-    starting = false;
     constructor(options) {
         this.pythonPath = options.pythonPath ?? 'python3';
         this.toolCallTimeoutMs = options.toolCallTimeoutMs ?? DEFAULT_TOOL_CALL_TIMEOUT_MS;
@@ -64,7 +113,7 @@ export class PyRunner {
         this.label = options.label ?? 'pytc';
     }
     get busy() {
-        return this.pending !== null || this.starting;
+        return this.pending !== null;
     }
     /**
      * Run one script. Tools are (re-)injected before every exec so the
@@ -78,6 +127,12 @@ export class PyRunner {
      *
      * `opts.deadlineMs` replaces the runner's scriptTimeoutMs for this exec (a
      * per-call time limit); a background exec uses its `lifetimeMs` instead.
+     * `opts.ceilingMs` is the longest limit the deployment allows this kind of
+     * script: a script stopped at its limit is offered a longer one only below
+     * it. Without it, the stop doesn't say whether a longer limit would help.
+     * `opts.backgroundCeilingMs`, for a foreground exec, is the longest a
+     * background script may run: one stopped at its ceiling is offered
+     * background mode when that is longer.
      */
     async exec(code, tools, background, opts) {
         if (this.disposed) {
@@ -86,90 +141,108 @@ export class PyRunner {
         if (this.busy) {
             return {
                 stdout: '',
-                stderr: 'RuntimeError: another code_execution script is already running for this agent',
+                stderr: "script didn't run: another code_execution script of yours is already running, and they run one at a time. "
+                    + 'Run this one again once that one has finished, or combine the two into one script.',
                 returnCode: 1,
                 aborted: true,
             };
         }
         this.clearIdleTimer();
-        this.starting = true; // claimed before the await: a same-tick second exec must see it
+        // The exec claims the runner before the await: a same-tick second exec
+        // sees it busy, and abort() or dispose() while the interpreter starts
+        // settles this exec, whose script then never runs.
+        let resolveResult;
+        const settled = new Promise((resolve) => {
+            resolveResult = resolve;
+        });
+        const pending = {
+            id: `e${++this.execCounter}`,
+            resolve: resolveResult,
+            deadlineTimer: null,
+            killTimer: null,
+            settled: false,
+            deadlineMs: null,
+            ceilingMs: opts?.ceilingMs,
+            backgroundCeilingMs: opts?.backgroundCeilingMs,
+            background: background !== undefined,
+            sent: false,
+        };
+        this.pending = pending;
         try {
             await this.ensureChild();
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            this.reclaim('spawn-failed');
-            return {
-                stdout: '',
-                stderr: `Failed to start python runtime (${this.pythonPath}): ${message}`,
-                returnCode: 1,
-                aborted: true,
-            };
-        }
-        finally {
-            this.starting = false; // `pending` is set below, with no await in between
+            // Settled already when an abort or dispose reclaimed the interpreter
+            // as it started; another exec may have claimed the runner since.
+            if (!pending.settled) {
+                this.settlePending({
+                    stdout: '',
+                    stderr: startFailure(this.pythonPath, err),
+                    returnCode: 1,
+                    aborted: true,
+                });
+                this.reclaim('spawn-failed');
+            }
+            return settled;
         }
-        const execId = `e${++this.execCounter}`;
+        if (pending.settled)
+            return settled;
+        const execId = pending.id;
         // Clamped: a deadline past Node's timer range would fire at once instead of never.
         const deadlineMs = Math.min(MAX_TIMER_MS, background?.lifetimeMs ?? opts?.deadlineMs ?? this.scriptTimeoutMs);
         this.onWake = background?.onWake ?? null;
-        const result = await new Promise((resolve) => {
-            const pending = {
-                id: execId,
-                resolve,
-                deadlineTimer: null,
-                killTimer: null,
-                settled: false,
-                deadlineMs: null,
-            };
-            this.pending = pending;
-            pending.deadlineTimer = setTimeout(() => {
-                pending.deadlineMs = deadlineMs;
-                // Deadline: ask politely first (script sees CancelledError and its
-                // exec_result still flows back), then kill on unresponsiveness.
-                this.send({ op: 'cancel', id: execId, reason: 'deadline' });
-                // The cancel lands only when the script awaits. Blocking code (time.sleep, a
-                // busy loop, a blocking read) never does, so interrupt it as well: the runtime
-                // raises KeyboardInterrupt in the script's own code, or schedules the
-                // cancellation of a script that is waiting. Repeated, because a waiting script
-                // can resume into blocking code before that cancellation runs; the runtime
-                // ignores the repeats once the script was interrupted or cancelled.
-                this.interruptChild();
-                pending.interruptTimer = setInterval(() => this.interruptChild(), INTERRUPT_REPEAT_MS);
-                pending.killTimer = setTimeout(() => {
-                    pending.deadlineMs = null; // this message already says why
-                    this.settlePending({
-                        stdout: '',
-                        stderr: `script stopped: it reached its ${formatLimit(deadlineMs)} time limit and did not respond, ` +
-                            'so it was killed and the interpreter restarted (variables from earlier scripts are gone)',
-                        returnCode: 1,
-                        aborted: true,
-                    });
-                    this.reclaim('deadline-kill');
-                }, this.cancelGraceMs);
-            }, deadlineMs);
-            // A day-scale background deadline must not hold the process open.
-            if (background)
-                pending.deadlineTimer.unref?.();
-            this.send({
-                op: 'init',
-                tools: tools.map((t) => ({ py_name: t.pyName, tool_name: t.toolName })),
-                call_timeout_s: Math.round(this.toolCallTimeoutMs / 1000),
-                ...(background
-                    ? { background: true, log_path: background.logPath ?? null }
-                    : {}),
-            });
-            this.send({ op: 'exec', id: execId, code });
+        pending.deadlineTimer = setTimeout(() => {
+            pending.deadlineMs = deadlineMs;
+            // Deadline: ask politely first (script sees CancelledError and its
+            // exec_result still flows back), then kill on unresponsiveness.
+            this.send({ op: 'cancel', id: execId, reason: 'deadline' });
+            // The cancel lands only when the script awaits. Blocking code (time.sleep, a
+            // busy loop, a blocking read) never does, so interrupt it as well: the runtime
+            // raises KeyboardInterrupt in the script's own code, or schedules the
+            // cancellation of a script that is waiting. Repeated, because a waiting script
+            // can resume into blocking code before that cancellation runs; the runtime
+            // ignores the repeats once the script was interrupted or cancelled.
+            this.interruptChild();
+            pending.interruptTimer = setInterval(() => this.interruptChild(), INTERRUPT_REPEAT_MS);
+            pending.killTimer = setTimeout(() => {
+                pending.deadlineMs = null; // this message already says why
+                this.settlePending({
+                    stdout: '',
+                    stderr: `script stopped: it reached its ${formatLimit(deadlineMs)} time limit and did not respond, so it was killed` +
+                        (pending.background ? '. ' : ' and the interpreter restarted (variables from earlier scripts are gone). ') +
+                        limitRemedy(deadlineMs, pending.ceilingMs, pending.background, pending.backgroundCeilingMs),
+                    returnCode: 1,
+                    aborted: true,
+                });
+                this.reclaim('deadline-kill');
+            }, this.cancelGraceMs);
+        }, deadlineMs);
+        // A day-scale background deadline must not hold the process open.
+        if (background)
+            pending.deadlineTimer.unref?.();
+        pending.sent = true;
+        this.send({
+            op: 'init',
+            tools: tools.map((t) => ({ py_name: t.pyName, tool_name: t.toolName })),
+            call_timeout_s: Math.round(this.toolCallTimeoutMs / 1000),
+            ...(background
+                ? { background: true, log_path: background.logPath ?? null }
+                : {}),
         });
+        this.send({ op: 'exec', id: execId, code });
+        const result = await settled;
         this.onWake = null;
         if (!background)
             this.armIdleTimer();
         return result;
     }
     /**
-     * Abort a running script (turn cancelled, agent reset/stopped). The
-     * interpreter is reclaimed: after an abort its state is suspect (a script
-     * died midway), and the next exec gets a fresh one.
+     * Abort the runner's script (its turn ended or is reset to run again, or the
+     * agent was reset or stopped), whether it's running or still waiting for its
+     * interpreter to start; a waiting script then never runs. The exec settles
+     * at once, and the interpreter is reclaimed, a starting one too: after an
+     * abort its state is suspect (a script died midway), and the next exec gets
+     * a fresh one.
      */
     abort(reason) {
         if (!this.pending)
@@ -217,15 +290,35 @@ export class PyRunner {
             // tracebacks etc.) — surface them in host logs.
             console.error(`[pytc:${this.label}] ${chunk.trimEnd()}`);
         });
+        // A write to an interpreter that no longer reads its input fails on the
+        // stream after write() returns; with no listener, that error is thrown as
+        // an uncaught exception. Such an interpreter can go on running, as after a
+        // script closes file descriptor 0, and every later message to it is lost:
+        // its exec would wait out its time limit. So end it, and its exit settles
+        // the exec now. One already dead or killed is left to its own exit.
+        let inputFailed = false;
+        child.stdin.on('error', (err) => {
+            console.error(`[pytc:${this.label}] write to the python runtime failed: ${err.message}`);
+            if (child.exitCode === null && !child.killed && child.pid !== undefined) {
+                inputFailed = true;
+                child.kill('SIGKILL');
+            }
+        });
         child.on('error', (err) => {
             // Spawn failure lands here (e.g. python3 missing); readiness rejects.
             console.error(`[pytc:${this.label}] python process error: ${err.message}`);
         });
         child.on('exit', (exitCode, signal) => {
-            if (this.pending) {
+            // An exec still waiting for the interpreter is settled by exec, as a
+            // runtime that failed to start.
+            if (this.pending?.sent) {
                 this.settlePending({
                     stdout: '',
-                    stderr: `python runtime exited unexpectedly (code=${exitCode}, signal=${signal ?? 'none'})`,
+                    stderr: inputFailed && signal === 'SIGKILL'
+                        ? 'python runtime stopped reading its input, so it was killed and the interpreter restarted ' +
+                            '(variables from earlier scripts are gone). A script that closes its standard input ' +
+                            '(file descriptor 0) does this.'
+                        : interpreterExit(exitCode, signal, this.pending.background),
                     returnCode: 1,
                     aborted: true,
                 });
@@ -243,7 +336,7 @@ export class PyRunner {
             };
             const onExit = () => {
                 cleanup();
-                reject(new Error('python runtime exited before becoming ready'));
+                reject(new Error('exited as it started'));
             };
             const onError = (err) => {
                 cleanup();
@@ -251,21 +344,25 @@ export class PyRunner {
             };
             const timeout = setTimeout(() => {
                 cleanup();
-                reject(new Error('python runtime did not become ready within 15s'));
+                reject(new Error("didn't start within 15 seconds"));
             }, 15_000);
             const cleanup = () => {
                 clearTimeout(timeout);
                 this.readyResolver = null;
+                this.readyFailer = null;
                 child.off('exit', onExit);
                 child.off('error', onError);
             };
             this.readyResolver = onReady;
+            this.readyFailer = onError;
             child.on('exit', onExit);
             child.on('error', onError);
         });
         return this.childReady;
     }
     readyResolver = null;
+    /** Fails the readiness of an interpreter that is still starting (see reclaim). */
+    readyFailer = null;
     handleLine(line, child) {
         let msg;
         try {
@@ -337,9 +434,12 @@ export class PyRunner {
         // Only a script that ended unsuccessfully was stopped: one that caught the cancellation
         // and finished its work returns 0, and must not read as stopped.
         if (pending.deadlineMs !== null && result.returnCode !== 0) {
-            const note = `script stopped: it reached its ${formatLimit(pending.deadlineMs)} time limit\n`;
+            const note = `script stopped: it reached its ${formatLimit(pending.deadlineMs)} time limit. `
+                + `${limitRemedy(pending.deadlineMs, pending.ceilingMs, pending.background, pending.backgroundCeilingMs)}\n`;
+            // On a line of its own: the runner's own texts, such as an interpreter's exit, end without a newline.
+            const withNote = (text) => (text === '' || text.endsWith('\n') ? text : `${text}\n`) + note;
             // A background script reports its output tail, so the note goes there too.
-            result = { ...result, stderr: result.stderr + note, ...(result.tail !== undefined ? { tail: result.tail + note } : {}) };
+            result = { ...result, stderr: withNote(result.stderr), ...(result.tail !== undefined ? { tail: withNote(result.tail) } : {}) };
         }
         if (pending.deadlineTimer)
             clearTimeout(pending.deadlineTimer);
@@ -400,6 +500,12 @@ export class PyRunner {
         if (this.child) {
             console.error(`[pytc:${this.label}] reclaiming python interpreter (${reason})`);
         }
+        // An interpreter killed as it starts never says it's ready: fail its
+        // readiness now, so an exec waiting on it returns at once rather than at
+        // the 15 s timeout. Here rather than in teardownChild, which an
+        // interpreter's own exit also runs, so that one still reads "exited as
+        // it started".
+        this.readyFailer?.(new Error(`python runtime reclaimed (${reason}) before it was ready`));
         this.teardownChild();
         this.clearIdleTimer();
     }
@@ -413,6 +519,7 @@ export class PyRunner {
             this.child = null;
             this.childReady = null;
             this.readyResolver = null;
+            this.readyFailer = null;
             child.removeAllListeners('exit');
             try {
                 child.stdin.end();
@@ -420,7 +527,12 @@ export class PyRunner {
             catch {
                 // stream may already be destroyed
             }
-            if (child.exitCode === null && !child.killed) {
+            // A child whose spawn failed has no pid, and its exitCode stays null
+            // until Node's 'error' for it, a tick later. A kill() in that tick, as
+            // from an abort or dispose on the tick exec was called, signals no
+            // child of ours but whatever pid Node's handle held: the host's own
+            // process group on Node 20.20.2, another process's pid on 24.19.
+            if (child.exitCode === null && !child.killed && child.pid !== undefined) {
                 child.kill('SIGKILL');
             }
         }