@hominis/fireforge 0.43.1 → 0.44.1

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

@@ -1,9 +1,18 @@
 /**
  * Filters an object to only include keys whose values are not undefined.
  * Designed for use with exactOptionalPropertyTypes — the result can be
- * spread into typed option objects without assigning undefined to optional properties.
+ * spread into typed option objects without assigning undefined to optional
+ * properties.
+ *
+ * Constrained to `object`, not `Record<string, unknown>`: a named interface
+ * has no index signature, so the narrower constraint rejects exactly the
+ * annotations this helper is most useful with. Nothing in the body needs the
+ * index signature — the key walk goes through `Object.keys`.
+ *
+ * @param obj - Object to filter
+ * @returns The same object with every `undefined`-valued key removed
  */
-export declare function pickDefined<T extends Record<string, unknown>>(obj: T): {
+export declare function pickDefined<T extends object>(obj: T): {
     [K in keyof T]+?: Exclude<T[K], undefined>;
 };
 import type { Command } from 'commander';
@@ -15,11 +24,10 @@ import type { Command } from 'commander';
  * 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).
+ * That covers a plain Error, a `GeneralError`, and even a 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;
 /**
@@ -30,23 +38,32 @@ export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw:
  * .option('--mach-arg <arg>', 'Repeatable.', ...stringListOption())
  * ```
  *
- * Seven call sites open-coded this, each with its own `[] as string[]`
- * default — commander types that slot as `unknown`, so every one carried the
- * cast. Two of the seven also mutated the accumulator in place rather than
- * returning a new array. Returning a fresh array per call additionally means
- * the default cannot be shared between two `.option()` registrations.
+ * Commander types the default slot as `unknown`, so every open-coded copy
+ * carries an `[] as string[]` cast, and it is easy to mutate the accumulator
+ * in place instead of returning a new array. Returning a fresh array per
+ * call also means the default cannot be shared between two `.option()`
+ * registrations.
  */
 export declare function stringListOption(): [(value: string, previous: string[]) => string[], string[]];
+/** Environment variable naming a standing wait budget for the whole session. */
+export declare const WAIT_LOCK_ENV_VAR = "FIREFORGE_WAIT_LOCK";
 /**
  * Resolves the parsed `--wait-lock [seconds]` option value into a wait budget
  * in seconds for `withEngineSessionLock`:
- * - absent (`undefined`) → `undefined` (legacy ~1 s fail-fast),
+ * - absent (`undefined`) → {@link WAIT_LOCK_ENV_VAR} if set, else `undefined`
+ *   (the ~1 s fail-fast),
  * - bare flag (`true`) → {@link DEFAULT_WAIT_LOCK_SECONDS},
  * - explicit value → integer validated into 1..3600.
  *
+ * The flag always wins over the environment: the environment expresses a
+ * default for a session, and an invocation that names a budget has said
+ * something more specific than the session did.
+ *
  * Accepts the raw string too, so it doubles as the option's arg parser (wrap
  * with {@link commanderArgParser} so failures surface through commander's
- * invalid-argument channel).
+ * invalid-argument channel). In that role the value is never `undefined`, so
+ * the environment fallback cannot leak into flag PARSING — only into flag
+ * ABSENCE, which is where it belongs.
  */
 export declare function resolveWaitLockSeconds(value: string | number | boolean | undefined): number | undefined;
 /**

package/dist/src/utils/options.js

@@ -2,19 +2,28 @@
 /**
  * Filters an object to only include keys whose values are not undefined.
  * Designed for use with exactOptionalPropertyTypes — the result can be
- * spread into typed option objects without assigning undefined to optional properties.
+ * spread into typed option objects without assigning undefined to optional
+ * properties.
+ *
+ * Constrained to `object`, not `Record<string, unknown>`: a named interface
+ * has no index signature, so the narrower constraint rejects exactly the
+ * annotations this helper is most useful with. Nothing in the body needs the
+ * index signature — the key walk goes through `Object.keys`.
+ *
+ * @param obj - Object to filter
+ * @returns The same object with every `undefined`-valued key removed
  */
 export function pickDefined(obj) {
     const result = {};
-    for (const key of Object.keys(obj)) {
-        if (obj[key] !== undefined) {
-            result[key] = obj[key];
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined) {
+            result[key] = value;
         }
     }
     return result;
 }
 import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
-import { GeneralError } from '../errors/base.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from './errors.js';
 /**
  * Wraps an option-argument parser so its failures surface through
@@ -24,11 +33,10 @@ import { toError } from './errors.js';
  * 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).
+ * That covers a plain Error, a `GeneralError`, and even a 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) => {
@@ -48,31 +56,81 @@ export function commanderArgParser(parse) {
  * .option('--mach-arg <arg>', 'Repeatable.', ...stringListOption())
  * ```
  *
- * Seven call sites open-coded this, each with its own `[] as string[]`
- * default — commander types that slot as `unknown`, so every one carried the
- * cast. Two of the seven also mutated the accumulator in place rather than
- * returning a new array. Returning a fresh array per call additionally means
- * the default cannot be shared between two `.option()` registrations.
+ * Commander types the default slot as `unknown`, so every open-coded copy
+ * carries an `[] as string[]` cast, and it is easy to mutate the accumulator
+ * in place instead of returning a new array. Returning a fresh array per
+ * call also means the default cannot be shared between two `.option()`
+ * registrations.
  */
 export function stringListOption() {
     return [(value, previous) => [...previous, value], []];
 }
 /** Wait budget applied when `--wait-lock` is passed without a value. */
 const DEFAULT_WAIT_LOCK_SECONDS = 60;
+/** Environment variable naming a standing wait budget for the whole session. */
+export const WAIT_LOCK_ENV_VAR = 'FIREFORGE_WAIT_LOCK';
+/** Bounds shared by the flag and the environment variable. */
+const MIN_WAIT_LOCK_SECONDS = 1;
+const MAX_WAIT_LOCK_SECONDS = 3600;
+/**
+ * Parses a wait budget from text, or undefined when it is not an integer in
+ * range. Shared by the flag and {@link WAIT_LOCK_ENV_VAR} so the two cannot
+ * drift on what they accept.
+ */
+function parseWaitLockSeconds(raw) {
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < MIN_WAIT_LOCK_SECONDS || n > MAX_WAIT_LOCK_SECONDS) {
+        return undefined;
+    }
+    return n;
+}
+/**
+ * The standing wait budget from {@link WAIT_LOCK_ENV_VAR}, or undefined when
+ * it is unset or empty.
+ *
+ * Exists because a wait budget is a property of the SESSION, not of the
+ * invocation: a checkout worked by several concurrent agent sessions has a
+ * held lock as its normal state, and an unattended loop would otherwise have
+ * to thread `--wait-lock` through every command it issues — the one place
+ * it is easiest to forget, and the failure only shows up once the loop has
+ * already produced a tail of refusals.
+ *
+ * An unusable value is a usage error rather than a silent fall-back to
+ * fail-fast: the operator set it precisely because they did not want to
+ * discover the budget at refusal time.
+ */
+function waitLockSecondsFromEnv() {
+    const raw = process.env[WAIT_LOCK_ENV_VAR]?.trim();
+    if (raw === undefined || raw.length === 0) {
+        return undefined;
+    }
+    const parsed = parseWaitLockSeconds(raw);
+    if (parsed === undefined) {
+        throw new InvalidArgumentError(`${WAIT_LOCK_ENV_VAR} must be an integer in ${String(MIN_WAIT_LOCK_SECONDS)}..${String(MAX_WAIT_LOCK_SECONDS)} (got "${raw}")`, WAIT_LOCK_ENV_VAR);
+    }
+    return parsed;
+}
 /**
  * Resolves the parsed `--wait-lock [seconds]` option value into a wait budget
  * in seconds for `withEngineSessionLock`:
- * - absent (`undefined`) → `undefined` (legacy ~1 s fail-fast),
+ * - absent (`undefined`) → {@link WAIT_LOCK_ENV_VAR} if set, else `undefined`
+ *   (the ~1 s fail-fast),
  * - bare flag (`true`) → {@link DEFAULT_WAIT_LOCK_SECONDS},
  * - explicit value → integer validated into 1..3600.
  *
+ * The flag always wins over the environment: the environment expresses a
+ * default for a session, and an invocation that names a budget has said
+ * something more specific than the session did.
+ *
  * Accepts the raw string too, so it doubles as the option's arg parser (wrap
  * with {@link commanderArgParser} so failures surface through commander's
- * invalid-argument channel).
+ * invalid-argument channel). In that role the value is never `undefined`, so
+ * the environment fallback cannot leak into flag PARSING — only into flag
+ * ABSENCE, which is where it belongs.
  */
 export function resolveWaitLockSeconds(value) {
     if (value === undefined || value === false) {
-        return undefined;
+        return waitLockSecondsFromEnv();
     }
     if (value === true) {
         return DEFAULT_WAIT_LOCK_SECONDS;
@@ -80,23 +138,21 @@ export function resolveWaitLockSeconds(value) {
     if (typeof value === 'number') {
         return value;
     }
-    const n = Number.parseInt(value, 10);
-    if (!Number.isFinite(n) || n < 1 || n > 3600) {
-        throw new GeneralError(`--wait-lock must be an integer in 1..3600 (got "${value}")`);
+    const parsed = parseWaitLockSeconds(value);
+    if (parsed === undefined) {
+        throw new GeneralError(`--wait-lock must be an integer in ${String(MIN_WAIT_LOCK_SECONDS)}..${String(MAX_WAIT_LOCK_SECONDS)} (got "${value}")`);
     }
-    return n;
+    return parsed;
 }
 /**
  * Registers `--wait-lock [seconds]` on a command that takes NO lock, so a
  * scripted sequence can blanket-append the flag without hitting a usage
- * error.
+ * error — a command that rejects it with "unknown option" kills the whole
+ * sequence with a usage error instead of a lock message.
  *
- * `export` / `re-export` / `build` / `test` / `patch move-files` all
- * accept the flag; `status` and `patch staged-dependency` used to reject
- * it with "unknown option", which killed the whole sequence with a usage
- * error instead of a lock message. The flag is accepted and ignored here —
- * never silently repurposed — and the help text says so, so nobody reads
- * its presence as evidence that this command waits for anything.
+ * The flag is accepted and ignored here — never silently repurposed — and
+ * the help text says so, so nobody reads its presence as evidence that this
+ * command waits for anything.
  *
  * The value is parsed and validated exactly as the honoring variant does:
  * `--wait-lock nonsense` must still be a usage error everywhere, or the
@@ -134,5 +190,5 @@ export function ensureWaitLockOptionEverywhere(command) {
  * `waitLockSeconds` for `withEngineSessionLock`/`withPatchDirectoryLock`.
  */
 export function addWaitLockOption(command) {
-    return command.option('--wait-lock [seconds]', 'Wait up to this many seconds (default 60) for another FireForge command to release the contended lock, instead of failing on the default budget', commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
+    return command.option('--wait-lock [seconds]', `Wait up to this many seconds (default 60) for another FireForge command to release the contended lock, instead of failing on the default budget. Set ${WAIT_LOCK_ENV_VAR} to apply a budget to every command in a session`, commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
 }

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

@@ -4,15 +4,17 @@ export declare function normalizePathSlashes(path: string): string;
  * Strips a leading `engine/` (or `engine\\`) segment from a user-supplied
  * path so the same command invocation accepts both repo-root-relative paths
  * (`engine/browser/base/content/foo.js`) and engine-relative paths
- * (`browser/base/content/foo.js`). The match is case-insensitive because
- * default macOS and Windows filesystems treat `Engine/` and `engine/` as
- * the same directory; a literal lowercase-only check previously left `mach`
- * / the manifest writers resolving against a wrongly-cased prefix. Leading
- * whitespace is ignored so tab-completed inputs don't slip past the strip.
+ * (`browser/base/content/foo.js`).
  *
- * The return value is trimmed of the same leading whitespace when the
- * prefix matched, and otherwise passed through verbatim — callers that
- * care about internal whitespace can trim on their side.
+ * The match is case-insensitive because default macOS and Windows
+ * filesystems treat `Engine/` and `engine/` as the same directory; a literal
+ * lowercase-only check leaves `mach` and the manifest writers resolving
+ * against a wrongly-cased prefix. Leading whitespace is ignored so
+ * tab-completed inputs do not slip past the strip.
+ *
+ * The return value is trimmed of that leading whitespace when the prefix
+ * matched, and otherwise passed through verbatim — callers that care about
+ * internal whitespace can trim on their side.
  *
  * @param filePath Path as provided by the user
  * @returns Path relative to the engine directory (or the original when the

package/dist/src/utils/paths.js

@@ -18,15 +18,17 @@ export function normalizePathSlashes(path) {
  * Strips a leading `engine/` (or `engine\\`) segment from a user-supplied
  * path so the same command invocation accepts both repo-root-relative paths
  * (`engine/browser/base/content/foo.js`) and engine-relative paths
- * (`browser/base/content/foo.js`). The match is case-insensitive because
- * default macOS and Windows filesystems treat `Engine/` and `engine/` as
- * the same directory; a literal lowercase-only check previously left `mach`
- * / the manifest writers resolving against a wrongly-cased prefix. Leading
- * whitespace is ignored so tab-completed inputs don't slip past the strip.
+ * (`browser/base/content/foo.js`).
  *
- * The return value is trimmed of the same leading whitespace when the
- * prefix matched, and otherwise passed through verbatim — callers that
- * care about internal whitespace can trim on their side.
+ * The match is case-insensitive because default macOS and Windows
+ * filesystems treat `Engine/` and `engine/` as the same directory; a literal
+ * lowercase-only check leaves `mach` and the manifest writers resolving
+ * against a wrongly-cased prefix. Leading whitespace is ignored so
+ * tab-completed inputs do not slip past the strip.
+ *
+ * The return value is trimmed of that leading whitespace when the prefix
+ * matched, and otherwise passed through verbatim — callers that care about
+ * internal whitespace can trim on their side.
  *
  * @param filePath Path as provided by the user
  * @returns Path relative to the engine directory (or the original when the

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

@@ -11,28 +11,3 @@ export type Arch = 'x64' | 'arm64';
  * @throws Error if running on an unsupported platform
  */
 export declare function getPlatform(): Platform;
-/**
- * Gets the current CPU architecture.
- * @throws Error if running on an unsupported architecture
- */
-export declare function getArch(): Arch;
-/**
- * Gets the mozconfig filename for the current platform.
- */
-export declare function getMozconfigName(): string;
-/**
- * Checks if the current platform is macOS.
- */
-export declare function isDarwin(): boolean;
-/**
- * Checks if the current platform is Linux.
- */
-export declare function isLinux(): boolean;
-/**
- * Checks if the current platform is Windows.
- */
-export declare function isWindows(): boolean;
-/**
- * Gets the appropriate file extension for executables on the current platform.
- */
-export declare function getExecutableExtension(): string;

package/dist/src/utils/platform.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { arch, platform } from 'node:os';
+import { platform } from 'node:os';
 import { GeneralError } from '../errors/base.js';
 /**
  * Gets the current operating system platform.
@@ -12,44 +12,3 @@ export function getPlatform() {
     }
     throw new GeneralError(`Unsupported platform: ${p}. FireForge supports darwin, linux, and win32.`);
 }
-/**
- * Gets the current CPU architecture.
- * @throws Error if running on an unsupported architecture
- */
-export function getArch() {
-    const a = arch();
-    if (a === 'x64' || a === 'arm64') {
-        return a;
-    }
-    throw new GeneralError(`Unsupported architecture: ${a}. FireForge supports x64 and arm64.`);
-}
-/**
- * Gets the mozconfig filename for the current platform.
- */
-export function getMozconfigName() {
-    return `${getPlatform()}.mozconfig`;
-}
-/**
- * Checks if the current platform is macOS.
- */
-export function isDarwin() {
-    return platform() === 'darwin';
-}
-/**
- * Checks if the current platform is Linux.
- */
-export function isLinux() {
-    return platform() === 'linux';
-}
-/**
- * Checks if the current platform is Windows.
- */
-export function isWindows() {
-    return platform() === 'win32';
-}
-/**
- * Gets the appropriate file extension for executables on the current platform.
- */
-export function getExecutableExtension() {
-    return isWindows() ? '.exe' : '';
-}

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

@@ -1,8 +1,8 @@
 /**
- * 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.
+ * Process-group kill and post-run sweep helpers for the exec layer. 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';
 /**
@@ -11,6 +11,11 @@ import { type ChildProcess } from 'node:child_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).
+ *
+ * A failed group kill falls through to a direct `child.kill` on POSIX too:
+ * ESRCH/EPERM on the negative PID means the group is gone or was never
+ * created, and signalling the direct child is strictly better than
+ * returning silently.
  */
 export declare function killProcessTree(child: ChildProcess, signal: NodeJS.Signals, usesProcessGroup: boolean): void;
 /** One process still alive in a swept group. */

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

@@ -1,9 +1,9 @@
 // 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.
+ * Process-group kill and post-run sweep helpers for the exec layer. 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 { getNodeErrorCode } from './errors.js';
@@ -14,6 +14,11 @@ import { verbose, warn } from './logger.js';
  * 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).
+ *
+ * A failed group kill falls through to a direct `child.kill` on POSIX too:
+ * ESRCH/EPERM on the negative PID means the group is gone or was never
+ * created, and signalling the direct child is strictly better than
+ * returning silently.
  */
 export function killProcessTree(child, signal, usesProcessGroup) {
     if (child.exitCode !== null || child.signalCode !== null)
@@ -26,7 +31,16 @@ export function killProcessTree(child, signal, 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);
+            try {
+                process.kill(-targetPid, signal);
+            }
+            catch {
+                // ESRCH/EPERM: the group is gone, or was never created because the
+                // platform ignored `detached`. Signal the direct child rather than
+                // doing nothing — it may well still be alive. Without this
+                // fall-through a failed group kill left the child running.
+                child.kill(signal);
+            }
         }
         else {
             // No process group on Windows — taskkill /T walks the descendant

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

@@ -1,3 +1,4 @@
+import { spawn } from 'node:child_process';
 /**
  * Result of executing a command.
  */
@@ -33,9 +34,8 @@ export interface ExecOptions {
      * 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
+     * startup cannot strand spinning `multiprocessing` workers, which reparent
+     * to launchd and busy-spin at 100% CPU indefinitely. Win32: tree-kill via
      * `taskkill /T /F` on abort/signals only, no post-run sweep
      * (best-effort). Default false — non-mach consumers are unaffected.
      *
@@ -74,6 +74,27 @@ export interface StreamOptions extends ExecOptions {
  * @returns Exit code of the process
  */
 export declare function execStream(command: string, args: string[], options?: StreamOptions): Promise<number>;
+/**
+ * Registers a child with {@link waitForActiveChildShutdown}.
+ *
+ * Exported for the one legitimate spawn outside this module:
+ * `core/marionette-preflight.ts` keeps its own `spawn` because it needs the
+ * live `ChildProcess` mid-run, returns while the child is still running, and
+ * aborts on a TCP byte rather than a deadline — none of which any wrapper
+ * here can express. It still needs the shutdown contract, and a second
+ * hand-rolled copy is what lets a Ctrl+C orphan the whole mach → Firefox
+ * tree.
+ */
+/**
+ * Registers a child whose shutdown {@link waitForActiveChildShutdown} must
+ * wait for, and returns the handle that deregisters it.
+ *
+ * @returns `settle()` — call from both the child's `close` and `error`
+ *   handlers so a dead child never holds the shutdown wait open
+ */
+export declare function trackChildClosure(): {
+    settle: () => void;
+};
 /**
  * Waits (bounded) for every tracked child process to close. Called by the
  * bin signal handler after forwarding SIGINT/SIGTERM, so the parent stays
@@ -100,6 +121,17 @@ export declare function waitForActiveChildShutdown(timeoutMs: number): Promise<v
 export declare function execInherit(command: string, args: string[], options?: ExecOptions & {
     shutdownGraceMs?: number;
 }): Promise<number>;
+/**
+ * Wires parent-process SIGINT/SIGTERM to a child: first signal → child.kill
+ * (SIGTERM) + grace timer; second matching signal → immediate SIGKILL; grace
+ * timer expiry → SIGKILL. Returns a `dispose()` that clears the listeners and
+ * any outstanding timer. Callers must invoke `dispose()` from both the child's
+ * `close` and `error` handlers so the process does not accumulate signal
+ * listeners across repeated spawns.
+ */
+export declare function installGracefulShutdownForwarder(child: ReturnType<typeof spawn>, graceMs: number, killTarget?: (signal: NodeJS.Signals) => void): {
+    dispose: () => void;
+};
 /**
  * Executes a command while inheriting stdin, streaming stdout/stderr live,
  * and capturing the emitted output for diagnostics.
@@ -118,11 +150,14 @@ export type SmokeLineCallback = (line: string) => void;
  *
  * 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.
+ * group. Inheriting `timeout` is a leaky trap — accepted by the type but
+ * silently ignored, so a caller setting it gets no deadline at all.
+ *
+ * `processGroup` is omitted for the same reason: a smoke run is ALWAYS
+ * detached on POSIX (`usesProcessGroup` is derived from `process.platform`
+ * alone), so the field would be accepted and never read.
  */
-export interface SmokeRunOptions extends Omit<ExecOptions, 'timeout'> {
+export interface SmokeRunOptions extends Omit<ExecOptions, 'processGroup' | 'timeout'> {
     /**
      * Hard deadline in milliseconds. When it elapses the child process
      * group is sent SIGTERM and, after `killGraceMs`, SIGKILL. The returned