@animalabs/agent-framework 0.22.2 → 0.23.0

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

@@ -15,10 +15,12 @@
  */
 
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { buildChildEnv } from '../mcpl/transport.js';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { createInterface, type Interface } from 'node:readline';
+import { boundedErrorMessage } from '../error-message.js';
 import { PYTHON_RUNTIME_SOURCE } from './runtime-py.js';
 
 export interface InjectedTool {
@@ -53,11 +55,30 @@ export interface BackgroundExecOptions {
   lifetimeMs: number;
 }
 
-/** Resolves inner tool calls. Must never reject — map errors to strings. */
+/**
+ * An inner tool call's result as the script gets it. `text` is the string
+ * its await returns, and the runner sets `.is_error` on that string from
+ * `isError`. With `structuredJson`, `text` is the JSON object a structured
+ * result reaches a script as, in any of its forms, and `.structured` reads
+ * its `structuredContent`, None for a form that holds none, such as one past
+ * the size cap; without it, `.structured` is None.
+ */
+export interface ScriptToolResult {
+  text: string;
+  isError: boolean;
+  structuredJson?: boolean;
+}
+
+/**
+ * Resolves inner tool calls. Must never reject — map errors to results; a
+ * rejection reaches the script as an `Error: …` result. A plain string is
+ * the result's text with nothing said about it, so the script's
+ * `.is_error` and `.structured` are None.
+ */
 export type ScriptToolCallHandler = (
   toolName: string,
   args: Record<string, unknown>,
-) => Promise<string>;
+) => Promise<string | ScriptToolResult>;
 
 export interface PyRunnerOptions {
   pythonPath?: string;
@@ -72,6 +93,19 @@ export interface PyRunnerOptions {
   onToolCall: ScriptToolCallHandler;
   /** Log prefix, typically the agent name. */
   label?: string;
+  /** Variables for the interpreter beyond what it inherits, such as
+   *  PYTHONPATH or a venv's. It inherits only what stdio MCPL children do
+   *  (CHILD_ENV_ALLOWLIST and LC_*, CA bundles and proxy variables among
+   *  them, and a proxy URL can carry credentials), then these, then
+   *  PYTHONUNBUFFERED and PYTHONIOENCODING, which the runner sets last.
+   *  Like the allowlist, this limits what the model's code inherits, not
+   *  what a process running as the same user can read. */
+  env?: Record<string, string>;
+  /** Pass the host's whole environment instead of the allowlist, as before
+   *  `env` existed. That hands every host variable, provider keys included,
+   *  to the model's code and to every subprocess a script starts; listing
+   *  what scripts need in `env` is the safer route. */
+  inheritEnv?: boolean;
 }
 
 const DEFAULT_TOOL_CALL_TIMEOUT_MS = 270_000;
@@ -91,6 +125,56 @@ export function formatLimit(ms: number): string {
   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: number, ceilingMs: number | undefined, background: boolean, backgroundCeilingMs?: number): string {
+  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: string, err: unknown): string {
+  const { code, syscall } = (err ?? {}) as { code?: unknown; syscall?: unknown };
+  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: number | null, signal: NodeJS.Signals | null, background: boolean): string {
+  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.`;
+}
+
 interface PendingExec {
   id: string;
   resolve: (result: ExecResult) => void;
@@ -101,6 +185,27 @@ interface PendingExec {
   settled: boolean;
   /** Set once the deadline fired: the result then says the script ran out of time. */
   deadlineMs: number | null;
+  /** The longest limit this exec could have had (exec's opts): whether a longer one would help. */
+  ceilingMs: number | undefined;
+  /** For a foreground exec, the longest a background script may run (exec's opts): whether background mode would help. */
+  backgroundCeilingMs: number | undefined;
+  /** A background exec has its interpreter to itself, so no earlier script's state is lost with it. */
+  background: boolean;
+  /** Set once the script went to the interpreter. Before that, the exec is
+   *  waiting for the interpreter to start, and an interpreter that exits then
+   *  failed to start (see exec). */
+  sent: boolean;
+}
+
+/**
+ * The interpreter to spawn. A bare name is looked up on PATH. A path with a
+ * separator is resolved against the host's working directory, where it
+ * resolved before the interpreter got a working directory of its own: spawn
+ * would resolve it against the runtime directory instead.
+ */
+function spawnablePath(pythonPath: string): string {
+  const hasSeparator = pythonPath.includes('/') || (process.platform === 'win32' && pythonPath.includes('\\'));
+  return hasSeparator ? resolve(pythonPath) : pythonPath;
 }
 
 export class PyRunner {
@@ -111,6 +216,7 @@ export class PyRunner {
   private readonly idleReclaimMs: number;
   private readonly onToolCall: ScriptToolCallHandler;
   private readonly label: string;
+  private readonly envOptions: { env?: Record<string, string>; inheritEnv?: boolean };
 
   private onWake: ((line: number, payload: unknown) => Promise<string | null>) | null = null;
   private child: ChildProcessWithoutNullStreams | null = null;
@@ -121,8 +227,6 @@ export class PyRunner {
   private idleTimer: ReturnType<typeof setTimeout> | null = null;
   private execCounter = 0;
   private disposed = false;
-  /** An exec has passed the busy check but is still awaiting the interpreter. */
-  private starting = false;
 
   constructor(options: PyRunnerOptions) {
     this.pythonPath = options.pythonPath ?? 'python3';
@@ -132,10 +236,16 @@ export class PyRunner {
     this.idleReclaimMs = options.idleReclaimMs ?? DEFAULT_IDLE_RECLAIM_MS;
     this.onToolCall = options.onToolCall;
     this.label = options.label ?? 'pytc';
+    // The interpreter runs model-authored code: the same env discipline as an
+    // MCPL connector child (#175), for a child that deserves it more. Stored
+    // as options, not a snapshot — the env is rebuilt at every spawn so a
+    // respawn after idle reclaim sees current host values, as the old
+    // per-spawn `{ ...process.env }` did.
+    this.envOptions = { env: options.env, inheritEnv: options.inheritEnv };
   }
 
   get busy(): boolean {
-    return this.pending !== null || this.starting;
+    return this.pending !== null;
   }
 
   /**
@@ -150,12 +260,18 @@ 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: string,
     tools: InjectedTool[],
     background?: BackgroundExecOptions,
-    opts?: { deadlineMs?: number },
+    opts?: { deadlineMs?: number; ceilingMs?: number; backgroundCeilingMs?: number },
   ): Promise<ExecResult> {
     if (this.disposed) {
       return { stdout: '', stderr: 'code_execution runner disposed', returnCode: 1, aborted: true };
@@ -163,83 +279,98 @@ 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!: (result: ExecResult) => void;
+    const settled = new Promise<ExecResult>((resolve) => {
+      resolveResult = resolve;
+    });
+    const pending: PendingExec = {
+      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;
     }
+    if (pending.settled) return settled;
 
-    const execId = `e${++this.execCounter}`;
+    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<ExecResult>((resolve) => {
-      const pending: PendingExec = {
-        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();
@@ -247,9 +378,12 @@ export class PyRunner {
   }
 
   /**
-   * 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 {
     if (!this.pending) return;
@@ -285,13 +419,23 @@ export class PyRunner {
     }
     this.teardownChild();
 
-    this.runtimeDir = mkdtempSync(join(tmpdir(), 'af-pytc-'));
+    // Absolute, since the interpreter runs in it: from a relative TMPDIR,
+    // runtime.py's path would otherwise resolve against the directory itself.
+    this.runtimeDir = resolve(mkdtempSync(join(tmpdir(), 'af-pytc-')));
     const runtimePath = join(this.runtimeDir, 'runtime.py');
     writeFileSync(runtimePath, PYTHON_RUNTIME_SOURCE, 'utf8');
 
-    const child = spawn(this.pythonPath, [runtimePath], {
+    const child = spawn(spawnablePath(this.pythonPath), [runtimePath], {
       stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env, PYTHONUNBUFFERED: '1' },
+      // The runtime directory, not the host's working directory: a script's
+      // relative paths land here, and go at teardown, rather than beside the
+      // host's .env and data. An absolute path still reaches the host's files.
+      cwd: this.runtimeDir,
+      // Set last, over a declared env: the protocol needs both. It writes
+      // non-ASCII JSON on piped stdio, which Python before 3.15 on Windows
+      // encodes in the ANSI code page unless told otherwise, and a host's
+      // own PYTHONUTF8 no longer reaches the interpreter.
+      env: { ...buildChildEnv(this.envOptions), PYTHONUNBUFFERED: '1', PYTHONIOENCODING: 'utf-8' },
     });
     this.child = child;
 
@@ -302,16 +446,38 @@ export class PyRunner {
       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,
         });
@@ -331,7 +497,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: Error) => {
         cleanup();
@@ -339,15 +505,17 @@ 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);
     });
@@ -355,6 +523,8 @@ export class PyRunner {
   }
 
   private readyResolver: (() => void) | null = null;
+  /** Fails the readiness of an interpreter that is still starting (see reclaim). */
+  private readyFailer: ((err: Error) => void) | null = null;
 
   private handleLine(line: string, child: ChildProcessWithoutNullStreams): void {
     let msg: { op?: string; id?: string; name?: string; args?: unknown; stdout?: string; stderr?: string; return_code?: number };
@@ -379,9 +549,24 @@ export class PyRunner {
             ? (msg.args as Record<string, unknown>)
             : {};
         this.onToolCall(toolName, args)
-          .catch((err) => `Error: ${err instanceof Error ? err.message : String(err)}`)
+          .catch((err): ScriptToolResult => ({
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+            isError: true,
+          }))
           .then((result) => {
-            this.reply(child, { op: 'tool_result', id: callId, result }, `result of ${toolName} call ${callId}`);
+            // Only an object is a ScriptToolResult. Anything else a handler
+            // resolves with, a string or a value its type rules out, is sent
+            // as it is, so the call is still answered.
+            const reply = typeof result === 'object' && result !== null
+              ? {
+                op: 'tool_result',
+                id: callId,
+                result: result.text,
+                is_error: result.isError,
+                ...(result.structuredJson ? { structured_json: true } : {}),
+              }
+              : { op: 'tool_result', id: callId, result };
+            this.reply(child, reply, `result of ${toolName} call ${callId}`);
           });
         return;
       }
@@ -431,9 +616,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: string) => (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);
     if (pending.killTimer) clearTimeout(pending.killTimer);
@@ -492,6 +680,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();
   }
@@ -501,28 +695,45 @@ export class PyRunner {
       this.reader.close();
       this.reader = null;
     }
-    if (this.child) {
-      const child = this.child;
+    const child = this.child;
+    if (child) {
       this.child = null;
       this.childReady = null;
       this.readyResolver = null;
+      this.readyFailer = null;
       child.removeAllListeners('exit');
       try {
         child.stdin.end();
       } 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');
       }
     }
-    if (this.runtimeDir) {
-      try {
-        rmSync(this.runtimeDir, { recursive: true, force: true });
-      } catch {
-        // temp cleanup is best-effort
-      }
-      this.runtimeDir = null;
+    const dir = this.runtimeDir;
+    this.runtimeDir = null;
+    if (dir) {
+      const remove = (): void => {
+        try {
+          rmSync(dir, { recursive: true, force: true });
+        } catch {
+          // temp cleanup is best-effort
+        }
+      };
+      // The directory is the interpreter's working directory, which Windows
+      // won't remove while the process lives, so there it goes once the
+      // process has. Elsewhere it goes now, so a host that exits right after
+      // this doesn't leave it behind. A child that never started has no exit
+      // to wait for.
+      const running = child !== null && child.pid !== undefined && child.exitCode === null && child.signalCode === null;
+      if (running && process.platform === 'win32') child.once('exit', remove);
+      else remove();
     }
   }