@mjasnikovs/pi-task 0.40.42 → 0.40.43

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

@@ -37,9 +37,37 @@ export type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
      *  possible at all: with `detached`, a `kill(-pid)` issued after the child
      *  has exited still takes the backgrounded grandchild with it; without it
      *  the same call throws ESRCH and the grandchild survives. Set only for
-     *  model children (json-events); plumbing stays in-group. */
+     *  model children (json-events); plumbing stays in-group. Never set on
+     *  win32 — see ownGroupSpawnOptions. */
     detached?: boolean;
+    /** win32 only: keep the child's console off-screen. */
+    windowsHide?: boolean;
 }) => ProcLike;
+/**
+ * Spawn options that make a model child reapable with everything it backgrounds.
+ *
+ * POSIX (linux, darwin): `detached` = own process group, so `kill(-pid)` sweeps
+ * the grandchildren. On win32 the same flag is a defect: libuv maps it to
+ * DETACHED_PROCESS, which gives the child NO console, so every console process
+ * the model then runs allocates a fresh visible one (issue #20). win32 gets
+ * `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.
+ */
+export declare function ownGroupSpawnOptions(platform: NodeJS.Platform): OwnGroupSpawnOptions;
+export type OwnGroupSpawnOptions = {
+    detached: true;
+} | {
+    windowsHide: 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.
+ */
+export declare function reapProcessGroup(pid: number, sig: NodeJS.Signals, 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
@@ -124,6 +152,9 @@ export interface RunChildTextOptions {
 }
 export interface RunChildJsonEventsOptions {
     mode: 'json-events';
+    /** Which platform's group options and reap to use. Tests drive the win32 arm
+     *  from a POSIX host with it; production leaves it to `process.platform`. */
+    platform?: NodeJS.Platform;
     onLine?: (line: string) => void;
     onContextUsage?: (snapshot: ContextSnapshot) => void;
     /**

package/dist/shared/child-process.js

@@ -13,6 +13,40 @@ export const CHILD_BASE_ARGS = [
     '--no-context-files',
     '--no-session'
 ];
+/**
+ * Spawn options that make a model child reapable with everything it backgrounds.
+ *
+ * POSIX (linux, darwin): `detached` = own process group, so `kill(-pid)` sweeps
+ * the grandchildren. On win32 the same flag is a defect: libuv maps it to
+ * DETACHED_PROCESS, which gives the child NO console, so every console process
+ * the model then runs allocates a fresh visible one (issue #20). win32 gets
+ * `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.
+ */
+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.
+ */
+export function reapProcessGroup(pid, sig, platform = process.platform) {
+    try {
+        if (platform === 'win32') {
+            spawnSyncDefault('taskkill', ['/pid', String(pid), '/T', '/F']);
+        }
+        else {
+            process.kill(-pid, sig);
+        }
+    }
+    catch {
+        // group already gone
+    }
+}
 /** The cause a signal was aborted with, when its owner attached one. */
 function abortCause(reason) {
     const tagged = reason;
@@ -229,11 +263,12 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         // OWN process group so every such grandchild can be reaped as a unit on exit.
         // 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 proc = spawn(invocation.command, invocation.args, {
             cwd,
             shell: false,
             stdio: [usesStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
-            ...(ownGroup ? { detached: true } : {}),
+            ...(ownGroup ? ownGroupSpawnOptions(platform) : {}),
             ...(invocation.env ? { env: invocation.env } : {})
         });
         if (usesStdin) {
@@ -250,23 +285,11 @@ 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. No-op unless the child owns a group (ownGroup) and we have a
-        // pid; ESRCH (group already gone) is swallowed. POSIX: negative-pid signals
-        // the group; Windows has no groups, so taskkill /T tears down the tree.
+        // backgrounded. No-op unless the child owns a group (ownGroup) and we have a pid.
         const reapGroup = (sig) => {
             if (!ownGroup || !proc.pid)
                 return;
-            try {
-                if (process.platform === 'win32') {
-                    spawnSyncDefault('taskkill', ['/pid', String(proc.pid), '/T', '/F']);
-                }
-                else {
-                    process.kill(-proc.pid, sig);
-                }
-            }
-            catch {
-                // group already gone
-            }
+            reapProcessGroup(proc.pid, sig, platform);
         };
         // 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,

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

@@ -1,4 +1,5 @@
 import type { RenderOutcome } from './render-check.js';
+import type { OwnGroupSpawnOptions } from '../shared/child-process.js';
 import { type DeepRenderOutcome } from './deep-render-check.js';
 import type { HealthCommand } from './repo-health-check.js';
 /**
@@ -163,14 +164,16 @@ export interface BootDeps {
      * fake pid would signal something else entirely.
      */
     killGroup?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Which platform's group options to spawn with. Tests drive the win32 arm
+     *  from a POSIX host; production leaves it to `process.platform`. */
+    platform?: NodeJS.Platform;
 }
 /** What `runBootCheck` passes to its spawn. */
-export interface BootSpawnOptions {
+export type BootSpawnOptions = {
     cwd: string;
-    detached: true;
     stdio: ['ignore', 'pipe', 'pipe'];
     env: Record<string, string | undefined>;
-}
+} & OwnGroupSpawnOptions;
 /** A stream the boot check reads output from. */
 export interface BootStream {
     on: (event: 'data', cb: (chunk: Buffer | string) => void) => void;
@@ -255,8 +258,9 @@ export declare function defaultFindPortHolder(port: number): {
  *
  *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
  *   - exit 0 before the window closes → PASS (a CLI-style "run" that finished);
- *   - still alive when the window closes → PASS, then the whole process group is
- *     killed (detached spawn = own group; SIGTERM, escalating to SIGKILL).
+ *   - still alive when the window closes → PASS, then the child and everything it
+ *     backgrounded are killed (ownGroupSpawnOptions + reapProcessGroup; SIGTERM,
+ *     escalating to SIGKILL).
  *
  * For a SERVED app (`expectServer` true — the spec/plan promised an HTTP server) mere
  * survival is not enough: a watcher (`dev` = tailwind/bundler --watch) stays alive

package/dist/task/boot-probe.js

@@ -25,6 +25,7 @@ import * as path from 'node:path';
 import { runRenderCheck } from './render-check.js';
 import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
 import { outputTail } from './command-run.js';
+import { ownGroupSpawnOptions, reapProcessGroup } from '../shared/child-process.js';
 import { packageScripts, makeHasTarget } from './launch-manifest.js';
 import { collectProjectEnv, pinnedLocalPort, runDeepRenderCheck } from './deep-render-check.js';
 /** Leading `FOO=bar` env assignments and `sudo`/`exec` wrappers carry no verb. */
@@ -435,7 +436,8 @@ function pgidOf(pid) {
     }
 }
 /** Default listener probe: any LISTENing socket owned by a pid in process group
- *  `pgid` (the detached boot child IS its own group leader, so pgid === child.pid). */
+ *  `pgid`. POSIX only (expectServer is fenced off win32): there the detached boot
+ *  child leads its own group, so pgid === child.pid. */
 function defaultGroupHasListener(pgid) {
     for (const { pid } of listeningSockets()) {
         if (pgidOf(pid) === pgid)
@@ -503,26 +505,9 @@ function holderIsOurs(command, boot) {
 function defaultSpawnBoot(bin, args, o) {
     return spawn(bin, args, o);
 }
-/**
- * The real group teardown, best-effort. A group already gone is not an error.
- *
- * On POSIX the negative pid signals the whole group, which is what makes a
- * `detached` spawn reapable together with anything it backgrounded. Windows has
- * neither process groups nor a negative-pid kill, so that branch shells out to
- * `taskkill /T /F` as a single forced tree teardown instead of escalating.
- */
+/** The real group teardown; the spawn shape's twin lives beside it. */
 function defaultKillGroup(pid, sig) {
-    try {
-        if (process.platform === 'win32') {
-            spawnSync('taskkill', ['/pid', String(pid), '/T', '/F']);
-        }
-        else {
-            process.kill(-pid, sig);
-        }
-    }
-    catch {
-        // group already gone
-    }
+    reapProcessGroup(pid, sig);
 }
 /**
  * Exercise the start command ONCE. All four outcomes below were run against real
@@ -533,8 +518,9 @@ function defaultKillGroup(pid, sig) {
  *
  *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
  *   - exit 0 before the window closes → PASS (a CLI-style "run" that finished);
- *   - still alive when the window closes → PASS, then the whole process group is
- *     killed (detached spawn = own group; SIGTERM, escalating to SIGKILL).
+ *   - still alive when the window closes → PASS, then the child and everything it
+ *     backgrounded are killed (ownGroupSpawnOptions + reapProcessGroup; SIGTERM,
+ *     escalating to SIGKILL).
  *
  * For a SERVED app (`expectServer` true — the spec/plan promised an HTTP server) mere
  * survival is not enough: a watcher (`dev` = tailwind/bundler --watch) stays alive
@@ -593,7 +579,7 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
     return new Promise(resolve => {
         const child = spawnBoot(runner.bin, args, {
             cwd,
-            detached: true,
+            ...ownGroupSpawnOptions(opts.deps?.platform ?? process.platform),
             stdio: ['ignore', 'pipe', 'pipe'],
             env: {
                 ...runnerEnv(runner),

package/dist/task/deep-render-check.js

@@ -44,6 +44,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import WebSocket from 'ws';
 import { findHeadlessBrowser, judgeRenderedDom } from './render-check.js';
+import { ownGroupSpawnOptions, reapProcessGroup } from '../shared/child-process.js';
 /** Identifier halves of a credential pair, in preference order. */
 const IDENTIFIER_SUFFIXES = ['PHONE', 'EMAIL', 'USERNAME', 'USER', 'LOGIN', 'IDENTIFIER'];
 const PASSWORD_SUFFIXES = ['PASSWORD', 'PASSWD', 'PASS'];
@@ -622,13 +623,8 @@ export async function launchBrowser(bin, userDataDir, { signal } = {}) {
         catch {
             // socket already gone
         }
-        try {
-            if (child?.pid)
-                process.kill(-child.pid, 'SIGKILL');
-        }
-        catch {
-            // group already gone
-        }
+        if (child?.pid)
+            reapProcessGroup(child.pid, 'SIGKILL');
         return Promise.resolve();
     };
     signal?.addEventListener('abort', () => void close(), { once: true });
@@ -647,7 +643,7 @@ export async function launchBrowser(bin, userDataDir, { signal } = {}) {
             `--user-data-dir=${userDataDir}`,
             '--remote-debugging-port=0',
             'about:blank'
-        ], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        ], { ...ownGroupSpawnOptions(process.platform), stdio: ['ignore', 'pipe', 'pipe'] });
         const proc = child;
         proc.unref();
         const wsUrl = await new Promise((resolve, reject) => {

package/package.json

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