@mjasnikovs/pi-task 0.40.49 → 0.40.50

package/dist/shared/child-process.js

@@ -446,10 +446,13 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         // invocation including its full prompt, and `opts`, along with everything
         // the caller's callbacks close over.
         let settled = false;
+        let endLeftoverWait;
         const cleanup = () => {
             stallProbe?.stop();
             streamWatch?.stop();
             signal?.removeEventListener('abort', onAbort);
+            if (endLeftoverWait)
+                signal?.removeEventListener('abort', endLeftoverWait);
         };
         const settle = (result) => {
             cleanup();
@@ -516,8 +519,11 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
             proc.stdout?.destroy?.();
             proc.stderr?.destroy?.();
             // Not settled before the leftovers are gone: the next phase needs their ports.
-            const done = () => settle(result);
-            void (leftovers?.reap() ?? Promise.resolve()).then(done, done);
+            // A cancel arriving meanwhile ends the wait, not the reap.
+            endLeftoverWait = () => settle(result);
+            if (!settled)
+                signal?.addEventListener('abort', endLeftoverWait, { once: true });
+            void (leftovers?.reap() ?? Promise.resolve()).then(endLeftoverWait, endLeftoverWait);
         };
         proc.once('error', () => {
             void leftovers?.reap();

package/dist/shared/leftovers.d.ts

@@ -5,7 +5,12 @@ export interface Leftovers {
     /** End whatever the child left running. Never rejects. */
     reap: () => Promise<void>;
 }
-/** Start tracking a child about to be spawned with `base` as its environment. */
+/**
+ * Start tracking a child about to be spawned with `base` as its environment.
+ * `graceMs` is POSIX's, between SIGTERM and SIGKILL. win32 has no grace to give:
+ * `taskkill /F` returns once the tree is dead, and its port free (40 of 40 on the
+ * windows runner).
+ */
 export declare function trackLeftovers(platform: NodeJS.Platform, base: NodeJS.ProcessEnv, graceMs: number): Leftovers;
 /**
  * A System32 executable by absolute path, so neither PATH nor the working directory

package/dist/shared/leftovers.js

@@ -20,7 +20,12 @@ import * as path from 'node:path';
 export const LEFTOVER_TOKEN_ENV = 'PI_TASK_LEFTOVER_TOKEN';
 const SHELL_REGISTRY_ENV = 'PI_TASK_SHELL_REGISTRY';
 const USER_BASH_ENV = 'PI_TASK_USER_BASH_ENV';
-/** Start tracking a child about to be spawned with `base` as its environment. */
+/**
+ * Start tracking a child about to be spawned with `base` as its environment.
+ * `graceMs` is POSIX's, between SIGTERM and SIGKILL. win32 has no grace to give:
+ * `taskkill /F` returns once the tree is dead, and its port free (40 of 40 on the
+ * windows runner).
+ */
 export function trackLeftovers(platform, base, graceMs) {
     if (platform === 'win32')
         return trackShells(base);

package/dist/task/command-run.d.ts

@@ -28,6 +28,7 @@
  * It also closes an asymmetry: `BootDeps` carries twelve injectable probes for
  * the gate's boot half, while its command half had none.
  */
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
 /** What one finished command looks like, stripped of how it was spawned. */
 export interface CommandRun {
     /** The runner binary itself never started (ENOENT, no POSIX shell). */
@@ -51,7 +52,7 @@ export interface CommandSpec {
      * rather than the live `process.env`.
      */
     env?: Record<string, string | undefined>;
-    /** The caller's cancel. Kills the child; the run reads as `status: null`. */
+    /** The caller's cancel. Kills a running child, whose run then reads as `status: null`. */
     signal?: AbortSignal;
 }
 /**
@@ -66,6 +67,11 @@ export interface CommandSpec {
  * paint a single frame through it.
  */
 export type CommandRunner = (spec: CommandSpec) => Promise<CommandRun>;
+/** What a runner spawns with. Tests hand in a fake child, and another platform's rules. */
+export interface CommandSpawner {
+    spawn: (bin: string, args: string[], options: SpawnOptions) => ChildProcess;
+    platform: NodeJS.Platform;
+}
 /**
  * The real runner: one bounded child, output collected, never rejects.
  *
@@ -83,7 +89,7 @@ export type CommandRunner = (spec: CommandSpec) => Promise<CommandRun>;
  * pipe. Waiting for `close` is therefore waiting for something no timeout can
  * reach. `exit` settles the run, and the deadline settles it itself.
  */
-export declare const spawnCommand: CommandRunner;
+export declare const spawnCommand: (spec: CommandSpec, spawner?: CommandSpawner) => Promise<CommandRun>;
 /**
  * A non-zero exit whose output shows an EXTERNAL runtime dependency is missing, not
  * a code fault: a browser suite (Playwright/Cypress) whose browser binaries or system

package/dist/task/command-run.js

@@ -29,7 +29,8 @@
  * the gate's boot half, while its command half had none.
  */
 import { spawn } from 'node:child_process';
-import { EXIT_DRAIN_MS, ownGroupSpawnOptions, reapGroupAfterExit, reapProcessGroup } from '../shared/child-process.js';
+import { EXIT_DRAIN_MS, KILL_GRACE_MS, ownGroupSpawnOptions, reapGroupAfterExit, reapProcessGroup } from '../shared/child-process.js';
+import { trackLeftovers } from '../shared/leftovers.js';
 import { isCommandNotFound, resolveRunner, runnerEnv } from './runner-resolve.js';
 /**
  * How much of ONE stream may be held in the HOST process, and how it is split.
@@ -72,6 +73,7 @@ class BoundedOutput {
             : this.head + this.tail;
     }
 }
+const HOST_SPAWNER = { spawn, platform: process.platform };
 /**
  * The real runner: one bounded child, output collected, never rejects.
  *
@@ -89,41 +91,56 @@ class BoundedOutput {
  * pipe. Waiting for `close` is therefore waiting for something no timeout can
  * reach. `exit` settles the run, and the deadline settles it itself.
  */
-export const spawnCommand = spec => new Promise(resolve => {
+export const spawnCommand = (spec, spawner = HOST_SPAWNER) => new Promise(resolve => {
+    const { platform } = spawner;
     const out = new BoundedOutput();
     const err = new BoundedOutput();
+    let result;
     let settled = false;
+    let cutShort = false;
     let exitStatus = null;
     let exited = false;
     let killed = false;
     let endedStreams = 0;
     let drain;
-    // Its own process group: a pretest that backgrounds a daemon, a build that
-    // leaves a watcher, would otherwise hold their ports into the boot check.
-    const child = spawn(spec.bin, spec.args, {
+    // Its own process group, and descendants found by what they inherit: a pretest
+    // that backgrounds a daemon, a build that leaves a watcher, would otherwise
+    // hold their ports into the boot check.
+    const leftovers = trackLeftovers(platform, spec.env ?? process.env, KILL_GRACE_MS);
+    const child = spawner.spawn(spec.bin, spec.args, {
         cwd: spec.cwd,
         // stdin CLOSED. `spawnSync` gave the child none; the default `spawn`
         // stdio is a live pipe nobody ever ends, so a check that reads stdin —
         // a `cat`-style pipeline, a tool that prompts, a pager — would block
         // until the kill timer fires instead of returning at once.
         stdio: ['ignore', 'pipe', 'pipe'],
-        ...ownGroupSpawnOptions(process.platform),
-        ...(spec.env ? { env: spec.env } : {})
+        ...ownGroupSpawnOptions(platform),
+        env: leftovers.env
     });
-    const done = (status, failure) => {
-        if (settled)
+    const settle = () => {
+        if (settled || !result)
             return;
         settled = true;
         clearTimeout(timer);
-        clearTimeout(drain);
         spec.signal?.removeEventListener('abort', killAndSettle);
-        resolve({
+        resolve(result);
+    };
+    const done = (status, failure) => {
+        if (result)
+            return;
+        clearTimeout(drain);
+        result = {
             failedToStart: failure !== undefined,
             ...(failure === undefined ? {} : { failureMessage: failure }),
             status,
             stdout: out.toString(),
             stderr: err.toString()
-        });
+        };
+        // Not settled before the leftovers are gone: the boot check binds their
+        // ports. The deadline and the cancel still end the wait.
+        void leftovers.reap().then(settle);
+        if (cutShort)
+            settle();
     };
     const expectedStreams = (child.stdout ? 1 : 0) + (child.stderr ? 1 : 0);
     const settleIfDrained = () => {
@@ -132,7 +149,7 @@ export const spawnCommand = spec => new Promise(resolve => {
     };
     const kill = () => {
         if (child.pid)
-            reapProcessGroup(child.pid, 'SIGKILL', { leaderExited: exited });
+            reapProcessGroup(child.pid, 'SIGKILL', { platform, leaderExited: exited });
         try {
             child.kill('SIGKILL');
         }
@@ -143,9 +160,14 @@ export const spawnCommand = spec => new Promise(resolve => {
     /**
      * The deadline and the cancel both END the run. This cannot wait to observe
      * the kill's effect — it kills, gives the pipes one drain, and reports
-     * `status: null` regardless.
+     * `status: null` regardless. A leader that already exited keeps its status.
      */
     const killAndSettle = () => {
+        cutShort = true;
+        if (result)
+            return settle();
+        if (exited)
+            return;
         killed = true;
         kill();
         clearTimeout(drain);
@@ -177,15 +199,16 @@ export const spawnCommand = spec => new Promise(resolve => {
     child.on('error', (e) => done(null, e.message));
     child.on('exit', (code) => {
         exited = true;
-        // taskkill /F ends a win32 child with exit code 1, which reads as a failed check.
-        exitStatus = killed ? null : code;
+        // A win32 kill ends the child with exit code 1, the code a failed check exits
+        // with too. A POSIX kill leaves no code, so a code there is the child's own.
+        exitStatus = killed && platform === 'win32' && code === 1 ? null : code;
         if (child.pid)
-            reapGroupAfterExit(child.pid);
+            reapGroupAfterExit(child.pid, platform);
         // Both ends of the same question: settle now if the pipes are already
         // at EOF, otherwise settle after one short drain rather than waiting on
         // whoever else is holding them.
         settleIfDrained();
-        if (!settled) {
+        if (!result) {
             clearTimeout(drain);
             drain = setTimeout(() => done(exitStatus), EXIT_DRAIN_MS);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.40.49",
+    "version": "0.40.50",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",