@mjasnikovs/pi-task 0.40.45 → 0.40.47

package/dist/shared/child-process.d.ts

@@ -3,6 +3,13 @@ import type { CommandKillReason } from './command-watchdog.js';
 import type { LoopHit } from '../task/loop-detector.js';
 /** Grace period between SIGTERM and SIGKILL (ms). */
 export declare const KILL_GRACE_MS = 5000;
+/**
+ * After a child EXITS, how long its pipes may still deliver buffered data before
+ * the run is reported. Not a wait for the pipes to CLOSE, which a grandchild holding
+ * them can put off for as long as it lives: just the turn or two the reader needs
+ * to hand over what it has.
+ */
+export declare const EXIT_DRAIN_MS = 50;
 /** Base flags shared by all child pi invocations. */
 export declare const CHILD_BASE_ARGS: readonly ["--print", "--no-skills", "--no-extensions", "--no-prompt-templates", "--no-context-files", "--no-session"];
 /** The subset of a child's stdin we use: write the prompt, then close it. */
@@ -15,8 +22,13 @@ export interface WritableLike {
 export interface ProcLike extends EventEmitter {
     /** Present only when the child was spawned with stdin 'pipe' (prompt delivery). */
     stdin: WritableLike | null;
-    stdout: EventEmitter | null;
-    stderr: EventEmitter | null;
+    /** `destroy` is a real pipe's; a fake without one is never held open by a grandchild. */
+    stdout: (EventEmitter & {
+        destroy?: () => unknown;
+    }) | null;
+    stderr: (EventEmitter & {
+        destroy?: () => unknown;
+    }) | null;
     killed: boolean;
     /** OS pid; used to signal the child's whole process GROUP (orphan reaping). May
      *  be undefined for a mock spawn or a spawn that failed. */
@@ -27,8 +39,9 @@ export type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
     cwd: string;
     shell: boolean;
     stdio: ['ignore' | 'pipe', 'pipe', 'pipe'];
-    /** Set only when the invocation needs env overrides — git-state-guard's
-     *  `GIT_INDEX_FILE` throwaway index is the one caller. Absent → the child
+    /** Set when the invocation needs env overrides — git-state-guard's
+     *  `GIT_INDEX_FILE` throwaway index — and for every model child, which
+     *  carries what leftovers.ts finds its descendants by. Absent → the child
      *  inherits this process's environment. */
     env?: NodeJS.ProcessEnv;
     /** true → give the child its own process group (POSIX `detached`), so any
@@ -53,8 +66,8 @@ export type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
  * `windowsHide` (CREATE_NO_WINDOW) instead: the child gets a windowless console
  * that its descendants inherit. Either/or is load-bearing — Windows ignores
  * CREATE_NO_WINDOW next to DETACHED_PROCESS. The win32 reap is `taskkill /T`,
- * which walks the live tree and needs no flag; unlike a POSIX group kill it
- * cannot catch what the child left behind after it exited.
+ * which walks the live tree and needs no flag. Neither reap reaches what pi's bash
+ * tool backgrounds, since it detaches every command; leftovers.ts finds that.
  */
 export declare function ownGroupSpawnOptions(platform: NodeJS.Platform): OwnGroupSpawnOptions;
 export type OwnGroupSpawnOptions = {
@@ -64,13 +77,22 @@ export type OwnGroupSpawnOptions = {
 };
 /**
  * Tear down a child spawned with `ownGroupSpawnOptions`, and whatever it
- * backgrounded. Best-effort: a group already gone is not an error. Kept beside
- * the spawn shape so a platform change edits one file.
+ * backgrounded that is still in its group. Best-effort: a group already gone is
+ * not an error. Kept beside the spawn shape so a platform change edits one file.
+ *
+ * `leaderExited` has no default: whether the leader still lives decides whether its
+ * pid is still its own. Returns whether a reap went out.
  */
-export declare function reapProcessGroup(pid: number, sig: NodeJS.Signals, { platform, leaderExited }?: {
+export declare function reapProcessGroup(pid: number, sig: NodeJS.Signals, { platform, leaderExited }: {
     platform?: NodeJS.Platform;
-    leaderExited?: boolean;
-}): void;
+    leaderExited: boolean;
+}): boolean;
+/**
+ * The sweep every runner makes once its leader exited: SIGTERM the group now, and
+ * SIGKILL what ignored it after the grace. A group whose last member is gone
+ * answers ESRCH, and POSIX keeps the pgid reserved while any member lives.
+ */
+export declare function reapGroupAfterExit(pid: number, platform?: NodeJS.Platform): void;
 /**
  * Why runChild killed the child. Five sources converge on one kill path, and
  * each names itself here rather than in its own flag — so a consumer reads ONE

package/dist/shared/child-process.js

@@ -1,10 +1,17 @@
 import { spawn as defaultSpawn, spawnSync as spawnSyncDefault } from 'node:child_process';
-import * as path from 'node:path';
+import { system32, trackLeftovers } from './leftovers.js';
 import { realStreamTimerDeps, StreamWatchdog } from './stream-watchdog.js';
 import { realStallTimerDeps, StallProbe } from './stall-probe.js';
 import { workerChannel } from '../workers/worker-channels.js';
 /** Grace period between SIGTERM and SIGKILL (ms). */
 export const KILL_GRACE_MS = 5000;
+/**
+ * After a child EXITS, how long its pipes may still deliver buffered data before
+ * the run is reported. Not a wait for the pipes to CLOSE, which a grandchild holding
+ * them can put off for as long as it lives: just the turn or two the reader needs
+ * to hand over what it has.
+ */
+export const EXIT_DRAIN_MS = 50;
 /** Base flags shared by all child pi invocations. */
 export const CHILD_BASE_ARGS = [
     '--print',
@@ -24,38 +31,50 @@ export const CHILD_BASE_ARGS = [
  * `windowsHide` (CREATE_NO_WINDOW) instead: the child gets a windowless console
  * that its descendants inherit. Either/or is load-bearing — Windows ignores
  * CREATE_NO_WINDOW next to DETACHED_PROCESS. The win32 reap is `taskkill /T`,
- * which walks the live tree and needs no flag; unlike a POSIX group kill it
- * cannot catch what the child left behind after it exited.
+ * which walks the live tree and needs no flag. Neither reap reaches what pi's bash
+ * tool backgrounds, since it detaches every command; leftovers.ts finds that.
  */
 export function ownGroupSpawnOptions(platform) {
     return platform === 'win32' ? { windowsHide: true } : { detached: true };
 }
 /**
  * Tear down a child spawned with `ownGroupSpawnOptions`, and whatever it
- * backgrounded. Best-effort: a group already gone is not an error. Kept beside
- * the spawn shape so a platform change edits one file.
+ * backgrounded that is still in its group. Best-effort: a group already gone is
+ * not an error. Kept beside the spawn shape so a platform change edits one file.
+ *
+ * `leaderExited` has no default: whether the leader still lives decides whether its
+ * pid is still its own. Returns whether a reap went out.
  */
-export function reapProcessGroup(pid, sig, { platform = process.platform, leaderExited = false } = {}) {
+export function reapProcessGroup(pid, sig, { platform = process.platform, leaderExited }) {
     // taskkill walks the tree down from a live leader. Once the leader has exited its
     // pid may already be another process's, and /T /F would kill that one instead.
     if (platform === 'win32' && leaderExited)
-        return;
+        return false;
     try {
         if (platform === 'win32') {
-            // System32's taskkill by absolute path, as pi's killProcessTree finds it, so
-            // neither PATH nor the working directory can supply another. Synchronous,
-            // unlike pi's: runChild kills the leader next, and the walk must end first.
-            const taskkill = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'taskkill.exe');
-            spawnSyncDefault(taskkill, ['/pid', String(pid), '/T', '/F']);
+            // Synchronous, unlike pi's killProcessTree: runChild kills the leader
+            // next, and the walk must end first.
+            spawnSyncDefault(system32('taskkill.exe'), ['/pid', String(pid), '/T', '/F']);
         }
         else {
             process.kill(-pid, sig);
         }
+        return true;
     }
     catch {
-        // group already gone
+        return false;
     }
 }
+/**
+ * The sweep every runner makes once its leader exited: SIGTERM the group now, and
+ * SIGKILL what ignored it after the grace. A group whose last member is gone
+ * answers ESRCH, and POSIX keeps the pgid reserved while any member lives.
+ */
+export function reapGroupAfterExit(pid, platform = process.platform) {
+    if (!reapProcessGroup(pid, 'SIGTERM', { platform, leaderExited: true }))
+        return;
+    setTimeout(() => reapProcessGroup(pid, 'SIGKILL', { platform, leaderExited: true }), KILL_GRACE_MS).unref();
+}
 /** The cause a signal was aborted with, when its owner attached one. */
 function abortCause(reason) {
     const tagged = reason;
@@ -268,17 +287,19 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         const usesStdin = invocation.stdin !== undefined;
         // Model children (json-events) run arbitrary bash — they can `bun run dev &`
         // a server that outlives the child and holds a port, wrecking the final gate
-        // with a self-inflicted EADDRINUSE. Spawn them in their
-        // OWN process group so every such grandchild can be reaped as a unit on exit.
+        // with a self-inflicted EADDRINUSE. They get their OWN process group, so a
+        // kill takes the child's tree with it, and leftovers.ts finds what escaped it.
         // Plumbing (git, mode:'text') never backgrounds anything and stays in-group.
         const ownGroup = opts?.mode === 'json-events';
         const platform = (ownGroup && opts.platform) || process.platform;
+        const leftovers = ownGroup ? trackLeftovers(platform, invocation.env ?? process.env, KILL_GRACE_MS) : null;
+        const env = leftovers?.env ?? invocation.env;
         const proc = spawn(invocation.command, invocation.args, {
             cwd,
             shell: false,
             stdio: [usesStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
             ...(ownGroup ? ownGroupSpawnOptions(platform) : {}),
-            ...(invocation.env ? { env: invocation.env } : {})
+            ...(env ? { env } : {})
         });
         if (usesStdin) {
             // A child killed before it read the prompt leaves the pipe broken, and an
@@ -294,28 +315,26 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
             proc.stdin?.end();
         }
         // Reap the child's whole process group — the child itself AND anything it
-        // backgrounded.
+        // backgrounded. Set by 'exit' or 'close', whichever a spawn reports first.
         let leaderExited = false;
-        proc.once('exit', () => (leaderExited = true));
-        const reapGroup = (sig) => {
-            if (!ownGroup || !proc.pid)
-                return;
-            reapProcessGroup(proc.pid, sig, { platform, leaderExited });
-        };
+        const reapGroup = (sig) => ownGroup && !!proc.pid && reapProcessGroup(proc.pid, sig, { platform, leaderExited });
         // One kill path for every source: SIGTERM, then SIGKILL after a grace
         // period if the child ignored the term. For a group-owning (model) child,
         // ALSO sweep the group so anything it backgrounded dies with it —
         // proc.kill hits only the leader, reapGroup the grandchildren. The sweep
         // goes first because win32's taskkill walks the tree down from a live
         // leader. The FIRST cause wins: a stall kill's SIGTERM can trip the abort
-        // path behind it.
+        // path behind it. A leader that already exited gave its own verdict.
         const killProc = (cause) => {
+            if (leaderExited)
+                return;
             kill ??= cause;
             reapGroup('SIGTERM');
             proc.kill('SIGTERM');
             setTimeout(() => {
                 reapGroup('SIGKILL');
-                if (!proc.killed)
+                // Not `proc.killed`: that turns true once SIGTERM is delivered.
+                if (!leaderExited)
                     proc.kill('SIGKILL');
             }, KILL_GRACE_MS);
         };
@@ -353,7 +372,14 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                     }
                 }
                 : opts;
-        const sink = sinkOpts ? new JsonEventSink(sinkOpts, hit => killProc({ by: 'loop', hit })) : null;
+        // A loop hit is the child's own verdict, not a kill from outside, so it stands
+        // even when the tail flushed after its exit is what carried it.
+        const sink = sinkOpts ?
+            new JsonEventSink(sinkOpts, hit => {
+                kill ??= { by: 'loop', hit };
+                killProc(kill);
+            })
+            : null;
         // Dead-backend stall guard (json-events children only; see the option docs).
         const stall = opts?.mode === 'json-events' ? opts.stall : undefined;
         const stallProbe = stall ?
@@ -432,15 +458,43 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
             settled = true;
             resolve(result);
         };
-        proc.once('close', (code) => {
-            // The child has exited, but anything it backgrounded (a dev server) may
-            // still hold its process group and a port — reap the group so the next
-            // gate's boot check does not collide with our own orphan. Best-effort:
-            // SIGTERM now, SIGKILL shortly after for anything that ignored it.
-            if (ownGroup) {
-                reapGroup('SIGTERM');
-                setTimeout(() => reapGroup('SIGKILL'), 1_000).unref();
-            }
+        // 'close' waits on every holder of the pipes, and a grandchild that inherited
+        // them holds them for as long as it lives. The run ends with the leader: at
+        // once if its pipes are already at EOF, otherwise after one drain.
+        let finished = false;
+        let exitCode = null;
+        let endedStreams = 0;
+        const expectedStreams = (proc.stdout ? 1 : 0) + (proc.stderr ? 1 : 0);
+        let drain;
+        const finishIfDrained = () => {
+            if (leaderExited && endedStreams >= expectedStreams)
+                finish(exitCode);
+        };
+        proc.stdout?.on('end', () => {
+            endedStreams++;
+            finishIfDrained();
+        });
+        proc.stderr?.on('end', () => {
+            endedStreams++;
+            finishIfDrained();
+        });
+        proc.once('exit', (code) => {
+            leaderExited = true;
+            exitCode = code;
+            finishIfDrained();
+            if (!finished)
+                drain = setTimeout(() => finish(exitCode), EXIT_DRAIN_MS);
+        });
+        proc.once('close', (code) => finish(code ?? exitCode));
+        const finish = (code) => {
+            if (finished)
+                return;
+            finished = true;
+            leaderExited = true;
+            clearTimeout(drain);
+            cleanup();
+            if (ownGroup && proc.pid)
+                reapGroupAfterExit(proc.pid, platform);
             if (sink)
                 sink.flush();
             const text = sink ? sink.text : undefined;
@@ -448,7 +502,7 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
             // killed means it ran on a prompt that never finished arriving. Its own
             // exit describes that half-spec, so it cannot stand as the verdict.
             const truncated = kill === undefined ? stdinError : undefined;
-            settle({
+            const result = {
                 stdout,
                 stderr: truncated ? `${stderr}\nprompt delivery failed: ${truncated.message}` : stderr,
                 exitCode: truncated ? (code ?? 0) || 1 : (code ?? 0),
@@ -456,9 +510,19 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                 ...(kill ? { kill } : {}),
                 text,
                 modelError: sink?.modelError
-            });
-        });
+            };
+            // A grandchild that inherited the pipes writes into them for as long as
+            // it lives; with the read ends closed that lands nowhere.
+            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);
+        };
         proc.once('error', () => {
+            void leftovers?.reap();
+            proc.stdout?.destroy?.();
+            proc.stderr?.destroy?.();
             settle({
                 stdout,
                 stderr,

package/dist/shared/leftovers.d.ts

@@ -0,0 +1,45 @@
+export declare const LEFTOVER_TOKEN_ENV = "PI_TASK_LEFTOVER_TOKEN";
+export interface Leftovers {
+    /** The environment to spawn the child with. */
+    env: NodeJS.ProcessEnv;
+    /** End whatever the child left running. Never rejects. */
+    reap: () => Promise<void>;
+}
+/** Start tracking a child about to be spawned with `base` as its environment. */
+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
+ * can supply another. `||`, not `??`: an empty SystemRoot would make it relative.
+ */
+export declare function system32(...segments: string[]): string;
+/** Pids whose environment holds `marker`, read from `<procRoot>/<pid>/environ`. */
+export declare function linuxPidsWith(marker: string, procRoot?: string): number[];
+/** Pids of the `ps -E` rows that carry `marker`. The pid is each row's first field. */
+export declare function pidsInPsTable(table: string, marker: string): number[];
+/**
+ * Sourced by every bash the child starts, after the user's own BASH_ENV so that one
+ * cannot replace the exit trap. Builtins only: a fork costs tens of milliseconds
+ * under MSYS. `/proc/$$/winpid` maps MSYS's pid to the Windows one.
+ */
+export declare const BASH_ENV_SCRIPT: string;
+/** A shell the registry recorded: its Windows pid and when it ran, as FILETIMEs. */
+export interface Shell {
+    pid: number;
+    ranAt: bigint;
+    /** Absent when the shell was killed, exec'd into its command, or is still running. */
+    exitedAt?: bigint;
+}
+/** Rows are `ran <pid> <time>` and `exited <pid> <time>`. Each exit closes its pid's latest run. */
+export declare function parseShells(text: string): Shell[];
+export interface ProcessRow {
+    pid: number;
+    ppid: number;
+    createdAt: bigint;
+}
+/**
+ * The processes a recorded shell started: those created while it lived. Windows
+ * hands a dead shell's pid to the next process, whose children carry the same
+ * parent pid, so only the shell's lifetime tells them apart.
+ */
+export declare function startedByShells(rows: ProcessRow[], shells: Shell[]): number[];
+export declare function parseProcessTable(text: string): ProcessRow[];

package/dist/shared/leftovers.js

@@ -0,0 +1,267 @@
+/**
+ * leftovers — what a model child started that is still running after it ended.
+ *
+ * A process-group reap misses it. pi's bash tool starts every command detached, in
+ * a group of its own, so a server a command backgrounds is in no group of the
+ * child's; on win32 the tree it hung from is gone once its shell exits. Measured
+ * with pi's own bash tool: the server outlived the group reap and `taskkill /T`,
+ * of the exited child and of the live one, on linux and on the windows runner.
+ *
+ * So descendants are found by what they inherit. On linux and darwin that is an
+ * environment token, read back from the process table. Windows cannot read another
+ * process's environment, so there `BASH_ENV` has every bash the child runs record
+ * its pid and lifetime, and whatever those shells started is found by parent pid.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+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. */
+export function trackLeftovers(platform, base, graceMs) {
+    if (platform === 'win32')
+        return trackShells(base, graceMs);
+    if (platform === 'linux' || platform === 'darwin')
+        return trackToken(platform, base, graceMs);
+    return { env: base, reap: () => Promise.resolve() };
+}
+/**
+ * A System32 executable by absolute path, so neither PATH nor the working directory
+ * can supply another. `||`, not `??`: an empty SystemRoot would make it relative.
+ */
+export function system32(...segments) {
+    return path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', ...segments);
+}
+// ─── linux, darwin: the environment token ───────────────────────────────────
+function trackToken(platform, base, graceMs) {
+    const token = randomUUID();
+    const marker = `${LEFTOVER_TOKEN_ENV}=${token}`;
+    const find = () => platform === 'linux' ? linuxPidsWith(marker) : pidsInPsTable(darwinPsTable(), marker);
+    return {
+        env: { ...base, [LEFTOVER_TOKEN_ENV]: token },
+        reap: () => new Promise(resolve => {
+            const started = performance.now();
+            let killed = false;
+            signalEach(find(), 'SIGTERM');
+            // Found again on every pass, never remembered: a pid that died in
+            // the grace period may already be someone else's. Each pass waits
+            // as long as the scan before it took, so the wait costs half a core
+            // at most and no invented interval.
+            const poll = () => {
+                const scanStart = performance.now();
+                const left = find();
+                const waited = performance.now() - started;
+                // A process SIGKILL cannot end (uninterruptible sleep) gets one
+                // more grace, then the run goes on without it.
+                if (left.length === 0 || waited >= 2 * graceMs)
+                    return resolve();
+                if (!killed && waited >= graceMs) {
+                    signalEach(left, 'SIGKILL');
+                    killed = true;
+                }
+                setTimeout(poll, performance.now() - scanStart).unref();
+            };
+            poll();
+        })
+    };
+}
+/** Pids whose environment holds `marker`, read from `<procRoot>/<pid>/environ`. */
+export function linuxPidsWith(marker, procRoot = '/proc') {
+    const inner = Buffer.from(`\0${marker}\0`);
+    const first = Buffer.from(`${marker}\0`);
+    let names;
+    try {
+        names = fs.readdirSync(procRoot);
+    }
+    catch {
+        return [];
+    }
+    const pids = [];
+    for (const name of names) {
+        if (!/^\d+$/.test(name))
+            continue;
+        try {
+            const environ = fs.readFileSync(path.join(procRoot, name, 'environ'));
+            if (environ.includes(inner) || environ.subarray(0, first.length).equals(first)) {
+                pids.push(Number(name));
+            }
+        }
+        catch {
+            // exited meanwhile, or not ours to read
+        }
+    }
+    return pids;
+}
+/** darwin's `ps -E` appends each process's environment to its command line. */
+function darwinPsTable() {
+    const r = spawnSync('/bin/ps', ['-Aww', '-o', 'pid=,ppid=,pgid=,lstart=,command=', '-E'], {
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024
+    });
+    return r.stdout ?? '';
+}
+/** Pids of the `ps -E` rows that carry `marker`. The pid is each row's first field. */
+export function pidsInPsTable(table, marker) {
+    return table
+        .split('\n')
+        .filter(row => row.includes(marker))
+        .map(row => Number.parseInt(row, 10))
+        .filter(pid => pid > 0);
+}
+function signalEach(pids, sig) {
+    let sent = 0;
+    for (const pid of pids) {
+        try {
+            process.kill(pid, sig);
+            sent++;
+        }
+        catch {
+            // already gone
+        }
+    }
+    return sent;
+}
+// ─── win32: the shells `BASH_ENV` recorded ──────────────────────────────────
+/**
+ * Sourced by every bash the child starts, after the user's own BASH_ENV so that one
+ * cannot replace the exit trap. Builtins only: a fork costs tens of milliseconds
+ * under MSYS. `/proc/$$/winpid` maps MSYS's pid to the Windows one.
+ */
+export const BASH_ENV_SCRIPT = [
+    `if [ -n "\${${USER_BASH_ENV}:-}" ]; then . "$${USER_BASH_ENV}"; fi`,
+    '__pi_task_winpid=$$',
+    'if [ -r /proc/$$/winpid ]; then read -r __pi_task_winpid < /proc/$$/winpid; fi',
+    // EPOCHREALTIME is bash 5.0; bash 4 has whole seconds, so the run is read at
+    // the start of its second and the exit at the end of it.
+    '__pi_task_now() { if [ -n "${EPOCHREALTIME:-}" ]; then __pi_task_t=$EPOCHREALTIME; else printf -v __pi_task_t "%(%s)T" -1; __pi_task_t="$((__pi_task_t + $1)).000000"; fi; }',
+    `__pi_task_now 0; printf 'ran %s %s\\n' "$__pi_task_winpid" "$__pi_task_t" >> "$${SHELL_REGISTRY_ENV}"`,
+    `trap '__pi_task_now 1; printf "exited %s %s\\n" "$__pi_task_winpid" "$__pi_task_t" >> "$${SHELL_REGISTRY_ENV}"' EXIT`,
+    ''
+].join('\n');
+function trackShells(base, graceMs) {
+    let dir;
+    try {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pi-task-shells-'));
+        fs.writeFileSync(path.join(dir, 'bash-env.sh'), BASH_ENV_SCRIPT);
+    }
+    catch {
+        return { env: base, reap: () => Promise.resolve() };
+    }
+    const registry = path.join(dir, 'shells');
+    const env = {
+        ...base,
+        BASH_ENV: forwardSlashes(path.join(dir, 'bash-env.sh')),
+        [SHELL_REGISTRY_ENV]: forwardSlashes(registry)
+    };
+    if (base.BASH_ENV)
+        env[USER_BASH_ENV] = base.BASH_ENV;
+    return {
+        env,
+        reap: async () => {
+            try {
+                const shells = parseShells(fs.existsSync(registry) ? fs.readFileSync(registry, 'utf8') : '');
+                if (shells.length === 0)
+                    return;
+                const table = await processTable(graceMs);
+                const started = startedByShells(parseProcessTable(table), shells);
+                await Promise.all(started.map(taskkillTree));
+            }
+            catch {
+                // best-effort, like every other reap
+            }
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // a handle still open in there; the run must not wait on it
+            }
+        }
+    };
+}
+/** Git Bash reads MSYS paths; forward slashes are the spelling both sides accept. */
+function forwardSlashes(p) {
+    return p.replace(/\\/g, '/');
+}
+/** FILETIME counts 100ns ticks from 1601; the Unix epoch is this many ticks in. */
+const UNIX_EPOCH_FILETIME = 116444736000000000n;
+/** `EPOCHREALTIME` as a FILETIME. Its decimal mark follows bash's locale. */
+function filetimeOf(epochRealtime) {
+    const m = /^(\d+)[.,](\d{6})$/.exec(epochRealtime);
+    return m ? (BigInt(m[1]) * 1000000n + BigInt(m[2])) * 10n + UNIX_EPOCH_FILETIME : undefined;
+}
+/** Rows are `ran <pid> <time>` and `exited <pid> <time>`. Each exit closes its pid's latest run. */
+export function parseShells(text) {
+    const shells = [];
+    for (const row of text.split('\n')) {
+        const m = /^(ran|exited) (\d+) (\S+)$/.exec(row.trim());
+        const at = m ? filetimeOf(m[3]) : undefined;
+        if (!m || at === undefined)
+            continue;
+        const pid = Number(m[2]);
+        if (m[1] === 'ran') {
+            shells.push({ pid, ranAt: at });
+        }
+        else {
+            const open = shells.findLast(s => s.pid === pid && s.exitedAt === undefined);
+            if (open)
+                open.exitedAt = at;
+        }
+    }
+    return shells;
+}
+/**
+ * The processes a recorded shell started: those created while it lived. Windows
+ * hands a dead shell's pid to the next process, whose children carry the same
+ * parent pid, so only the shell's lifetime tells them apart.
+ */
+export function startedByShells(rows, shells) {
+    const startedBy = (shell, row) => {
+        if (shell.pid !== row.ppid || row.createdAt < shell.ranAt)
+            return false;
+        if (shell.exitedAt !== undefined)
+            return row.createdAt <= shell.exitedAt;
+        // No exit on record: a process holding the pid since before the run is the shell.
+        return rows.some(r => r.pid === shell.pid && r.createdAt <= shell.ranAt);
+    };
+    return rows.filter(row => shells.some(shell => startedBy(shell, row))).map(row => row.pid);
+}
+export function parseProcessTable(text) {
+    const rows = [];
+    for (const line of text.split('\n')) {
+        const m = /^(\d+) (\d+) (\d+)$/.exec(line.trim());
+        if (m)
+            rows.push({ pid: Number(m[1]), ppid: Number(m[2]), createdAt: BigInt(m[3]) });
+    }
+    return rows;
+}
+/**
+ * Every process as `pid ppid creation-FILETIME`, one per line. A CIM query that
+ * has not answered within the kill grace is given up on: the run is waiting.
+ */
+function processTable(graceMs) {
+    const query = 'Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate'
+        + ' | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId) $($_.CreationDate.ToFileTimeUtc())" }';
+    return new Promise(resolve => {
+        let out = '';
+        const ps = spawn(system32('WindowsPowerShell', 'v1.0', 'powershell.exe'), ['-NoProfile', '-NonInteractive', '-Command', query], { stdio: ['ignore', 'pipe', 'ignore'] });
+        const giveUp = setTimeout(() => ps.kill(), graceMs);
+        ps.stdout.on('data', (d) => (out += d.toString()));
+        ps.on('error', () => resolve(''));
+        ps.on('close', () => {
+            clearTimeout(giveUp);
+            resolve(out);
+        });
+    });
+}
+function taskkillTree(pid) {
+    return new Promise(resolve => {
+        const tk = spawn(system32('taskkill.exe'), ['/pid', String(pid), '/T', '/F'], {
+            stdio: 'ignore'
+        });
+        tk.on('error', () => resolve());
+        tk.on('close', () => resolve());
+    });
+}

package/dist/task/boot-probe.d.ts

@@ -163,7 +163,7 @@ export interface BootDeps {
      * a fake child has no group to kill and a real `process.kill(pid)` against a
      * fake pid would signal something else entirely.
      */
-    killGroup?: (pid: number, signal: NodeJS.Signals) => void;
+    killGroup?: (pid: number, signal: NodeJS.Signals, leaderExited: boolean) => void;
     /** Which platform's spawn options, served-app rule and reap to use. Tests drive
      *  the win32 arm from a POSIX host; production leaves it to `process.platform`. */
     platform?: NodeJS.Platform;
@@ -249,6 +249,7 @@ export declare function defaultFindPortHolder(port: number): {
     pid: number;
     command: string;
 } | null;
+export declare const BOOT_KILL_GRACE_MS = 2000;
 /**
  * Exercise the start command ONCE. All four outcomes below were run against real
  * child processes in throwaway projects.

package/dist/task/boot-probe.js

@@ -501,6 +501,7 @@ function holderIsOurs(command, boot) {
     return ((c.includes('bun') || c.includes('node') || c.includes('npm') || c.includes('make'))
         && (c.includes(` ${script}`) || c.endsWith(script)));
 }
+export const BOOT_KILL_GRACE_MS = 2_000;
 /** The real spawn. Kept beside the seam so the default is one line to read. */
 function defaultSpawnBoot(bin, args, o) {
     return spawn(bin, args, o);
@@ -611,7 +612,7 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
         };
         let leaderExited = false;
         const reapGroup = opts.deps?.killGroup
-            ?? ((pid, sig) => reapProcessGroup(pid, sig, { platform, leaderExited }));
+            ?? ((pid, sig, exited) => reapProcessGroup(pid, sig, { platform, leaderExited: exited }));
         const killGroup = (sig) => {
             // Truthiness, deliberately: `process.kill(0, sig)` signals the
             // CALLER's own process group, so a pid of 0 turns a best-effort
@@ -619,17 +620,17 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
             // `spawnBoot` is a seam now and a fake or future child could.
             if (!child.pid)
                 return;
-            reapGroup(child.pid, sig);
+            reapGroup(child.pid, sig, leaderExited);
         };
         const passAndKill = (renderNote) => {
             settle(renderNote ? { outcome: 'pass', renderNote } : { outcome: 'pass' });
             killGroup('SIGTERM');
-            setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+            setTimeout(() => killGroup('SIGKILL'), BOOT_KILL_GRACE_MS).unref();
         };
         const failAndKill = (detail) => {
             settle({ outcome: 'fail', detail });
             killGroup('SIGTERM');
-            setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+            setTimeout(() => killGroup('SIGKILL'), BOOT_KILL_GRACE_MS).unref();
         };
         // Served apps only: poll for a listening socket owned by our process group.
         // As soon as one appears the boot has demonstrably served → run the render
@@ -716,7 +717,7 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
                     detail: `still running after ${graceMs}ms but never opened a listening socket — the spec/dependencies promise an HTTP server`
                 });
                 killGroup('SIGTERM');
-                setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+                setTimeout(() => killGroup('SIGKILL'), BOOT_KILL_GRACE_MS).unref();
                 return;
             }
             passAndKill();

package/dist/task/command-run.js

@@ -29,6 +29,7 @@
  * 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 { isCommandNotFound, resolveRunner, runnerEnv } from './runner-resolve.js';
 /**
  * How much of ONE stream may be held in the HOST process, and how it is split.
@@ -71,12 +72,6 @@ class BoundedOutput {
             : this.head + this.tail;
     }
 }
-/**
- * After the child EXITS, how long its pipes may still deliver buffered data
- * before the run is reported. Not a wait for the pipes to CLOSE — that is the
- * bug below — just the turn or two the reader needs to hand over what it has.
- */
-const DRAIN_MS = 50;
 /**
  * The real runner: one bounded child, output collected, never rejects.
  *
@@ -102,6 +97,8 @@ export const spawnCommand = spec => new Promise(resolve => {
     let exited = 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, {
         cwd: spec.cwd,
         // stdin CLOSED. `spawnSync` gave the child none; the default `spawn`
@@ -109,6 +106,7 @@ export const spawnCommand = spec => new Promise(resolve => {
         // 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 } : {})
     });
     const done = (status, failure) => {
@@ -132,6 +130,8 @@ export const spawnCommand = spec => new Promise(resolve => {
             done(exitStatus);
     };
     const kill = () => {
+        if (child.pid)
+            reapProcessGroup(child.pid, 'SIGKILL', { leaderExited: exited });
         try {
             child.kill('SIGKILL');
         }
@@ -140,14 +140,14 @@ export const spawnCommand = spec => new Promise(resolve => {
         }
     };
     /**
-     * The deadline and the cancel both END the run. The kill only reaches the
-     * direct child, so this cannot wait to observe its effect — it kills, gives
-     * the pipes one drain, and reports `status: null` regardless.
+     * 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.
      */
     const killAndSettle = () => {
         kill();
         clearTimeout(drain);
-        drain = setTimeout(() => done(null), DRAIN_MS);
+        drain = setTimeout(() => done(null), EXIT_DRAIN_MS);
     };
     // NOT unref'd. This timer is the only bound left on every gate command,
     // repo-health command and ACCEPT-debt re-run, and an unref'd timer is only
@@ -176,13 +176,15 @@ export const spawnCommand = spec => new Promise(resolve => {
     child.on('exit', (code) => {
         exited = true;
         exitStatus = code;
+        if (child.pid)
+            reapGroupAfterExit(child.pid);
         // 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) {
             clearTimeout(drain);
-            drain = setTimeout(() => done(exitStatus), DRAIN_MS);
+            drain = setTimeout(() => done(exitStatus), EXIT_DRAIN_MS);
         }
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.40.45",
+    "version": "0.40.47",
     "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",