@hominis/fireforge 0.35.0 → 0.37.0

package/dist/src/utils/fs.js

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { randomUUID } from 'node:crypto';
 import { access, chmod, copyFile as fsCopyFile, lstat, mkdir, open, readdir, readFile, rename, rm, stat, statfs, } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 const RETRIABLE_REMOVE_ERRORS = new Set(['ENOTEMPTY', 'EBUSY', 'EPERM']);
+const RETRIABLE_RENAME_ERRORS = new Set(['EPERM', 'EACCES', 'EBUSY']);
 function sleep(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
@@ -199,7 +200,7 @@ export async function writeFileAtomic(path, content) {
         if (existingMode !== undefined) {
             await chmod(tempPath, existingMode);
         }
-        await rename(tempPath, path);
+        await renameWithRetries(tempPath, path);
         await syncParentDir(path);
     }
     catch (error) {
@@ -207,6 +208,31 @@ export async function writeFileAtomic(path, content) {
         throw error;
     }
 }
+/**
+ * Renames the temp file over its destination, retrying transient sharing
+ * violations. On Windows, a rename onto a target that another writer is
+ * concurrently replacing — or that an antivirus/indexer briefly holds open —
+ * fails with EPERM/EACCES/EBUSY even though the same rename succeeds a moment
+ * later; POSIX renames never hit this. Non-retriable codes and exhausted
+ * budgets rethrow, so a genuine permission problem still surfaces.
+ */
+async function renameWithRetries(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
+                ? error.code
+                : undefined;
+            if (!code || !RETRIABLE_RENAME_ERRORS.has(code) || attempt === 4) {
+                throw error;
+            }
+            await sleep(25 * (attempt + 1));
+        }
+    }
+}
 async function syncParentDir(path) {
     let directoryHandle;
     try {
@@ -270,7 +296,10 @@ export const FIREFORGE_TMP_PATH_PATTERN = /(^|\/)\.[^/]+\.fireforge-tmp-\d+-[0-9
  */
 function createAtomicTempPath(path) {
     const directory = dirname(path);
-    const filename = path.slice(directory.length + 1);
+    // basename, not slice(dirname.length + 1): when dirname ends with the
+    // separator (filesystem/drive roots, e.g. dirname('/foo') === '/'), the
+    // slice arithmetic chopped the first filename character ('/foo' → 'oo').
+    const filename = basename(path);
     return join(directory, `.${filename}.fireforge-tmp-${process.pid}-${randomUUID()}`);
 }
 /**
@@ -287,7 +316,11 @@ function createAtomicTempPath(path) {
 export async function checkDiskSpace(path, minBytes, onLowSpace) {
     try {
         const stats = await statfs(path);
-        const availableBytes = stats.bfree * stats.bsize;
+        // bavail = blocks available to UNPRIVILEGED users; bfree includes the
+        // root-reserved blocks (typically 5% on ext4), so it over-reported free
+        // space and silently suppressed the low-space warning exactly when it
+        // mattered.
+        const availableBytes = stats.bavail * stats.bsize;
         if (availableBytes < minBytes) {
             const availableGB = (availableBytes / (1024 * 1024 * 1024)).toFixed(1);
             const requiredGB = (minBytes / (1024 * 1024 * 1024)).toFixed(1);
@@ -302,4 +335,3 @@ export async function checkDiskSpace(path, minBytes, onLowSpace) {
         return undefined;
     }
 }
-//# sourceMappingURL=fs.js.map

package/dist/src/utils/logger.d.ts

@@ -3,6 +3,13 @@
  * @param enabled - Whether to enable verbose output
  */
 export declare function setVerbose(enabled: boolean): void;
+/**
+ * Switches the logger into (or out of) machine-output mode. Commands with
+ * `--json`/`--raw` flags call this before producing any output.
+ */
+export declare function setMachineOutputMode(enabled: boolean): void;
+/** True when machine-output mode is active. */
+export declare function isMachineOutputMode(): boolean;
 /**
  * Displays a verbose/debug message (only shown if verbose mode is enabled).
  * @param message - Message to display

package/dist/src/utils/logger.js

@@ -3,6 +3,19 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 /** Whether verbose mode is enabled */
 let verboseMode = false;
+/**
+ * Whether machine-output mode is active (`--json` / `--raw`).
+ *
+ * In machine mode, stdout belongs EXCLUSIVELY to the machine-readable
+ * payload: all human-facing diagnostics (intro/outro banners, info, warn,
+ * error, steps, notes) are routed to stderr as plain unstyled lines.
+ * Before this mode existed, clack's log helpers wrote styled warnings to
+ * stdout *before* the JSON body — a truncated-directory warning during
+ * `status --json` broke every `JSON.parse(stdout)` consumer, and error
+ * objects on the machine contract were followed by a styled duplicate on
+ * the same stream.
+ */
+let machineOutputMode = false;
 /**
  * Enables or disables verbose mode.
  * @param enabled - Whether to enable verbose output
@@ -10,6 +23,21 @@ let verboseMode = false;
 export function setVerbose(enabled) {
     verboseMode = enabled;
 }
+/**
+ * Switches the logger into (or out of) machine-output mode. Commands with
+ * `--json`/`--raw` flags call this before producing any output.
+ */
+export function setMachineOutputMode(enabled) {
+    machineOutputMode = enabled;
+}
+/** True when machine-output mode is active. */
+export function isMachineOutputMode() {
+    return machineOutputMode;
+}
+/** Writes a plain diagnostic line to stderr (machine-mode side channel). */
+function writeDiagnostic(prefix, message) {
+    process.stderr.write(`${prefix}${message}\n`);
+}
 /**
  * Checks if verbose mode is enabled.
  * @returns True if verbose mode is enabled
@@ -22,43 +50,75 @@ function isVerbose() {
  * @param message - Message to display
  */
 export function verbose(message) {
-    if (isVerbose()) {
-        p.log.info(`[debug] ${message}`);
+    if (!isVerbose())
+        return;
+    if (machineOutputMode) {
+        writeDiagnostic('[debug] ', message);
+        return;
     }
+    p.log.info(`[debug] ${message}`);
 }
 function supportsInteractiveSpinner() {
     return process.stdout.isTTY && process.stderr.isTTY;
 }
 /** Displays the top-level intro banner for a command. */
 export function intro(message) {
+    if (machineOutputMode)
+        return;
     p.intro(message);
 }
 /** Displays the closing outro banner for a command. */
 export function outro(message) {
+    if (machineOutputMode)
+        return;
     p.outro(message);
 }
 /** Logs an informational message. */
 export function info(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.info(message);
 }
 /** Logs a success message. */
 export function success(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.success(message);
 }
 /** Logs a warning message. */
 export function warn(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('warning: ', message);
+        return;
+    }
     p.log.warn(message);
 }
 /** Logs an error message. */
 export function error(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('error: ', message);
+        return;
+    }
     p.log.error(message);
 }
 /** Logs an in-progress step message. */
 export function step(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.step(message);
 }
 /** Logs a plain message without a status prefix. */
 export function message(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.message(message);
 }
 /** Formats text using the success color without logging it. */
@@ -75,6 +135,21 @@ export function formatErrorText(message) {
  * @returns Spinner handle with message(), stop(), and error() methods
  */
 export function spinner(initialMessage) {
+    if (machineOutputMode) {
+        // Spinner progress is diagnostics; keep stdout clean for the payload.
+        return {
+            message: (msg) => {
+                writeDiagnostic('', msg);
+            },
+            stop: (msg) => {
+                if (msg)
+                    writeDiagnostic('', msg);
+            },
+            error: (msg) => {
+                writeDiagnostic('error: ', msg ?? 'Failed');
+            },
+        };
+    }
     if (!supportsInteractiveSpinner()) {
         let latestMessage = initialMessage;
         return {
@@ -107,6 +182,10 @@ export function spinner(initialMessage) {
 }
 /** Emits a cancellation message. */
 export function cancel(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('cancelled: ', message);
+        return;
+    }
     p.cancel(message);
 }
 /** Checks whether a prompt result represents a user cancellation. */
@@ -115,6 +194,9 @@ export function isCancel(value) {
 }
 /** Displays a titled note block for follow-up details. */
 export function note(message, title) {
+    if (machineOutputMode) {
+        writeDiagnostic('', title ? `${title}: ${message}` : message);
+        return;
+    }
     p.note(message, title);
 }
-//# sourceMappingURL=logger.js.map

package/dist/src/utils/options.d.ts

@@ -6,3 +6,18 @@
 export declare function pickDefined<T extends Record<string, unknown>>(obj: T): {
     [K in keyof T]+?: Exclude<T[K], undefined>;
 };
+/**
+ * Wraps an option-argument parser so its failures surface through
+ * commander's own invalid-argument channel.
+ *
+ * Commander only treats errors whose `code` is `'commander.invalidArgument'`
+ * as argument-validation failures; anything else re-throws out of
+ * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
+ * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
+ * That was the observed behavior for `run --smoke-exit abc` (plain Error),
+ * `test --harness-retries 99` (GeneralError), and `export --order 0`
+ * (FireForge InvalidArgumentError, whose `code` is a numeric ExitCode).
+ * Every `.argParser()`/option-parser callback must be wrapped with this
+ * helper (or throw commander's InvalidArgumentError directly).
+ */
+export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw: string) => T;

package/dist/src/utils/options.js

@@ -13,4 +13,28 @@ export function pickDefined(obj) {
     }
     return result;
 }
-//# sourceMappingURL=options.js.map
+import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
+/**
+ * Wraps an option-argument parser so its failures surface through
+ * commander's own invalid-argument channel.
+ *
+ * Commander only treats errors whose `code` is `'commander.invalidArgument'`
+ * as argument-validation failures; anything else re-throws out of
+ * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
+ * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
+ * That was the observed behavior for `run --smoke-exit abc` (plain Error),
+ * `test --harness-retries 99` (GeneralError), and `export --order 0`
+ * (FireForge InvalidArgumentError, whose `code` is a numeric ExitCode).
+ * Every `.argParser()`/option-parser callback must be wrapped with this
+ * helper (or throw commander's InvalidArgumentError directly).
+ */
+export function commanderArgParser(parse) {
+    return (raw) => {
+        try {
+            return parse(raw);
+        }
+        catch (error) {
+            throw new CommanderInvalidArgumentError(error instanceof Error ? error.message : String(error));
+        }
+    };
+}

package/dist/src/utils/package-root.js

@@ -34,8 +34,8 @@ export function getPackageRoot() {
     }
     let current = dirname(fileURLToPath(import.meta.url));
     for (;;) {
+        const packagePath = join(current, 'package.json');
         try {
-            const packagePath = join(current, 'package.json');
             const pkg = readPackageMetadata(packagePath);
             if (isFireForgePackageMetadata(pkg)) {
                 cachedPackageRoot = current;
@@ -43,8 +43,16 @@ export function getPackageRoot() {
             }
         }
         catch (error) {
-            void error;
-            // no package.json here — keep walking
+            // Absent package.json: keep walking. A package.json that EXISTS but
+            // fails to parse is a different animal — walking past it could bind
+            // to a wrong ancestor package (any parent exposing bin.fireforge) or
+            // end in the unhelpful generic "could not locate" error, hiding the
+            // actual syntax problem.
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw new Error(`Found ${packagePath} but could not parse it: ` +
+                    (error instanceof Error ? error.message : String(error)), { cause: error });
+            }
         }
         const parent = dirname(current);
         if (parent === current) {
@@ -66,4 +74,3 @@ export function getPackageVersion() {
     const packageRoot = getPackageRoot();
     return readPackageMetadata(join(packageRoot, 'package.json')).version;
 }
-//# sourceMappingURL=package-root.js.map

package/dist/src/utils/parse.js

@@ -212,4 +212,3 @@ export function parseObject(data, label) {
     }
     return new ParsedRecord(data, label);
 }
-//# sourceMappingURL=parse.js.map

package/dist/src/utils/paths.js

@@ -75,4 +75,3 @@ export function toRootRelativePath(root, candidate) {
     }
     return normalizePathSlashes(relative(resolvedRoot, resolvedCandidate));
 }
-//# sourceMappingURL=paths.js.map

package/dist/src/utils/platform.js

@@ -53,4 +53,3 @@ export function isWindows() {
 export function getExecutableExtension() {
     return isWindows() ? '.exe' : '';
 }
-//# sourceMappingURL=platform.js.map

package/dist/src/utils/process-group.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Process-group kill and post-run sweep helpers for the exec layer
+ * (0.37.0 item 9a). Split out of `process.ts` to keep that file within the
+ * per-file line budget; deliberately spawn-based (not `exec`-based) so the
+ * two modules do not import each other cyclically.
+ */
+import { type ChildProcess } from 'node:child_process';
+/**
+ * Sends `signal` to the child's whole tree: the process GROUP on POSIX
+ * (negative-PID kill — reaches mach → python → firefox → content-process
+ * chains), or a `taskkill /T /F` tree kill plus a direct `child.kill`
+ * fallback on Windows. No-ops once the direct child has exited (group
+ * survivors after exit are the post-run sweep's job, not this function's).
+ */
+export declare function killProcessTree(child: ChildProcess, signal: NodeJS.Signals, usesProcessGroup: boolean): void;
+/** One process still alive in a swept group. */
+export interface ProcessGroupSurvivor {
+    /** PID, or -1 when pgrep was unavailable and only a liveness probe ran. */
+    pid: number;
+    /** Command line (pgrep -lf output), best-effort. */
+    command: string;
+}
+/**
+ * Post-run reaper for a process group FireForge itself spawned (`pgid` is
+ * the PID of a child started with `detached: true`): lists survivors,
+ * SIGTERMs the group, waits a short grace, escalates to SIGKILL, and warns
+ * about anything that still refuses to die. POSIX only (no-op on win32).
+ * The only kill target is `-pgid` — never anything outside the group.
+ * A healthy run costs exactly one `pgrep`.
+ */
+export declare function sweepProcessGroup(pgid: number, graceMs?: number): Promise<{
+    survivors: ProcessGroupSurvivor[];
+}>;

package/dist/src/utils/process-group.js

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Process-group kill and post-run sweep helpers for the exec layer
+ * (0.37.0 item 9a). Split out of `process.ts` to keep that file within the
+ * per-file line budget; deliberately spawn-based (not `exec`-based) so the
+ * two modules do not import each other cyclically.
+ */
+import { spawn } from 'node:child_process';
+import { verbose, warn } from './logger.js';
+/**
+ * Sends `signal` to the child's whole tree: the process GROUP on POSIX
+ * (negative-PID kill — reaches mach → python → firefox → content-process
+ * chains), or a `taskkill /T /F` tree kill plus a direct `child.kill`
+ * fallback on Windows. No-ops once the direct child has exited (group
+ * survivors after exit are the post-run sweep's job, not this function's).
+ */
+export function killProcessTree(child, signal, usesProcessGroup) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    const targetPid = child.pid;
+    if (targetPid === undefined)
+        return;
+    try {
+        if (usesProcessGroup) {
+            // Negative PID routes to the process group, killing the Python
+            // wrapper, the firefox it forked, and every content process
+            // that inherited the group.
+            process.kill(-targetPid, signal);
+        }
+        else {
+            // No process group on Windows — taskkill /T walks the descendant
+            // tree instead. Always forced (/F): there is no SIGTERM analogue,
+            // so the grace window only exists on POSIX.
+            spawn('taskkill', ['/pid', String(targetPid), '/T', '/F'], {
+                stdio: 'ignore',
+            }).on('error', () => {
+                // taskkill unavailable — nothing more we can do beyond the
+                // direct-child kill below.
+            });
+            child.kill(signal);
+        }
+    }
+    catch {
+        // Already gone. Nothing to do.
+    }
+}
+const SWEEP_GRACE_MS = 2000;
+const MULTIPROCESSING_WORKER_PATTERN = /multiprocessing\.(?:spawn|forkserver)|resource_tracker/;
+function sweepDelay(ms) {
+    // Deliberately ref'd (no unref()): this promise is AWAITED between the
+    // group SIGTERM and the post-grace re-list/SIGKILL escalation, from a
+    // child 'close' handler after the signal forwarder is disposed — with an
+    // unref'd timer nothing kept the event loop alive, so Node could exit
+    // mid-grace and skip the escalation entirely. Healthy runs never reach
+    // this function (sweepProcessGroup early-returns on zero survivors), so
+    // the ref never holds a clean exit open.
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Minimal spawn-based pgrep runner. exitCode -1 means pgrep itself was
+ * unavailable or errored (distinct from exit 1 = "no matches").
+ */
+async function runPgrep(args) {
+    return new Promise((resolve) => {
+        const child = spawn('pgrep', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        child.stdout.on('data', (data) => {
+            stdout += data.toString('utf8');
+        });
+        child.on('error', () => {
+            resolve({ exitCode: -1, stdout: '' });
+        });
+        child.on('close', (code) => {
+            resolve({ exitCode: code ?? -1, stdout });
+        });
+    });
+}
+/** Lists processes still in `pgid` via `pgrep -g -lf`, with a kill(0) fallback. */
+async function listGroupSurvivors(pgid) {
+    const result = await runPgrep(['-g', String(pgid), '-lf']);
+    if (result.exitCode === 0) {
+        return result.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map((line) => {
+            const match = /^(\d+)\s+(.*)$/.exec(line);
+            return match
+                ? { pid: Number(match[1]), command: match[2] ?? '' }
+                : { pid: -1, command: line };
+        });
+    }
+    if (result.exitCode === 1)
+        return []; // no matches
+    // pgrep unavailable/broken: fall back to a group liveness probe.
+    try {
+        process.kill(-pgid, 0);
+        return [{ pid: -1, command: 'unknown (pgrep unavailable; group still has live members)' }];
+    }
+    catch {
+        return [];
+    }
+}
+function describeSurvivors(list) {
+    return list
+        .map((s) => {
+        const tag = MULTIPROCESSING_WORKER_PATTERN.test(s.command)
+            ? ' [multiprocessing worker — the known busy-spin orphan shape]'
+            : '';
+        return `PID ${String(s.pid)}: ${s.command}${tag}`;
+    })
+        .join('; ');
+}
+/**
+ * Post-run reaper for a process group FireForge itself spawned (`pgid` is
+ * the PID of a child started with `detached: true`): lists survivors,
+ * SIGTERMs the group, waits a short grace, escalates to SIGKILL, and warns
+ * about anything that still refuses to die. POSIX only (no-op on win32).
+ * The only kill target is `-pgid` — never anything outside the group.
+ * A healthy run costs exactly one `pgrep`.
+ */
+export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
+    if (process.platform === 'win32')
+        return { survivors: [] };
+    const survivors = await listGroupSurvivors(pgid);
+    if (survivors.length === 0)
+        return { survivors };
+    warn(`Harness process group ${String(pgid)} left ${String(survivors.length)} surviving ` +
+        `process(es) after exit — reaping the group. ${describeSurvivors(survivors)}`);
+    try {
+        process.kill(-pgid, 'SIGTERM');
+    }
+    catch {
+        return { survivors };
+    }
+    await sweepDelay(graceMs);
+    let remaining = await listGroupSurvivors(pgid);
+    if (remaining.length > 0) {
+        try {
+            process.kill(-pgid, 'SIGKILL');
+        }
+        catch {
+            return { survivors };
+        }
+        await sweepDelay(Math.min(200, graceMs));
+        remaining = await listGroupSurvivors(pgid);
+        if (remaining.length > 0) {
+            warn(`Process group ${String(pgid)} still has survivors after SIGKILL: ${describeSurvivors(remaining)}. ` +
+                'Inspect manually (ps -axo pid,ppid,time,command) and kill by PID.');
+        }
+        else {
+            verbose(`Process group ${String(pgid)} reaped after SIGKILL escalation.`);
+        }
+    }
+    else {
+        verbose(`Process group ${String(pgid)} reaped cleanly with SIGTERM.`);
+    }
+    return { survivors };
+}

package/dist/src/utils/process.d.ts

@@ -8,6 +8,16 @@ export interface ExecResult {
     stderr: string;
     /** Process exit code */
     exitCode: number;
+    /**
+     * True when `stdout` was cut off at the 50 MB collector cap. Optional so
+     * existing mocks stay valid; absent means "not truncated". Callers that
+     * feed the output into safety decisions (e.g. archive-listing scans) must
+     * treat `true` as a hard failure — a truncated listing looks exactly like
+     * a complete one otherwise.
+     */
+    stdoutTruncated?: boolean;
+    /** True when `stderr` was cut off at the 50 MB collector cap. See {@link ExecResult.stdoutTruncated}. */
+    stderrTruncated?: boolean;
 }
 /**
  * Options for command execution.
@@ -19,6 +29,21 @@ export interface ExecOptions {
     env?: Record<string, string>;
     /** Timeout in milliseconds */
     timeout?: number;
+    /**
+     * POSIX: spawn the child as a process-group leader and route every kill
+     * (parent-signal forwarding, abort, escalation) to the whole GROUP, then
+     * sweep the group for survivors after close — so a harness that dies at
+     * startup cannot strand spinning `multiprocessing` workers (field
+     * incident: an orphaned Python spawn worker reparented to launchd and
+     * busy-spun at 100% CPU for ~26 days). Win32: tree-kill via
+     * `taskkill /T /F` on abort/signals only, no post-run sweep
+     * (best-effort). Default false — non-mach consumers are unaffected.
+     *
+     * NOTE for callers: a detached group leader does NOT receive terminal
+     * Ctrl+C; the exec layer installs its own group-aware signal forwarder
+     * whenever this option is set.
+     */
+    processGroup?: boolean;
 }
 /**
  * Executes a command and returns its output.
@@ -49,6 +74,13 @@ export interface StreamOptions extends ExecOptions {
  * @returns Exit code of the process
  */
 export declare function execStream(command: string, args: string[], options?: StreamOptions): Promise<number>;
+/**
+ * Waits (bounded) for every tracked child process to close. Called by the
+ * bin signal handler after forwarding SIGINT/SIGTERM, so the parent stays
+ * alive long enough for the grace-then-SIGKILL escalation to actually run.
+ * Resolves immediately when no children are active.
+ */
+export declare function waitForActiveChildShutdown(timeoutMs: number): Promise<void>;
 /**
  * Executes a command and inherits stdio (shows output directly).
  *
@@ -81,8 +113,16 @@ export declare function execInheritCapture(command: string, args: string[], opti
 }): Promise<ExecResult>;
 /** Per-line callback for smoke-run stream dispatch. */
 export type SmokeLineCallback = (line: string) => void;
-/** Options for {@link execSmokeRun}. */
-export interface SmokeRunOptions extends ExecOptions {
+/**
+ * Options for {@link execSmokeRun}.
+ *
+ * Deliberately omits `ExecOptions.timeout`: the smoke run's only deadline is
+ * {@link SmokeRunOptions.smokeTimeoutMs}, which signals the whole process
+ * group. Inheriting `timeout` used to be a leaky trap — it was accepted by
+ * the type but silently ignored, so a caller setting it got no deadline at
+ * all.
+ */
+export interface SmokeRunOptions extends Omit<ExecOptions, 'timeout'> {
     /**
      * Hard deadline in milliseconds. When it elapses the child process
      * group is sent SIGTERM and, after `killGraceMs`, SIGKILL. The returned
@@ -138,8 +178,12 @@ export interface SmokeRunResult extends ExecResult {
  * that inherited the group.
  *
  * Windows fallback: `detached: true` does not create an equivalent group
- * there, so we degrade to `child.kill()` and log a best-effort warning
- * via the `onStderrLine` callback if the caller wired one.
+ * there, so we kill the descendant tree with `taskkill /pid <pid> /T /F`
+ * instead. taskkill has no graceful-signal equivalent — both the deadline
+ * and the grace re-invocation are forced kills, so Windows children get
+ * no shutdown window (best-effort; Windows is untested, see README).
+ * `child.kill()` is still sent as a direct-child fallback in case
+ * taskkill itself is unavailable.
  */
 export declare function execSmokeRun(command: string, args: string[], options: SmokeRunOptions): Promise<SmokeRunResult>;
 /**