@hominis/fireforge 0.45.0 → 0.46.0

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

@@ -6,7 +6,7 @@
  * the string only when the assertion actually fails, where a plain
  * template literal would build it on every call.
  */
-export type AssertionMessage = string | (() => string);
+type AssertionMessage = string | (() => string);
 /**
  * Asserts that an internal invariant holds.
  *
@@ -18,23 +18,10 @@ export type AssertionMessage = string | (() => string);
  * @throws {@link InternalInvariantError} when `condition` is falsy.
  */
 export declare function assert(condition: unknown, message: AssertionMessage): asserts condition;
-/**
- * Asserts that a value is neither `null` nor `undefined`, narrowing it in
- * place for the statements that follow.
- *
- * Use this in statement position, where the value is already bound to a
- * name. Use {@link expectDefined} in expression position, where it is not.
- *
- * @param value - The value that should be present
- * @param message - What was supposed to be present, and why
- * @throws {@link InternalInvariantError} when `value` is `null` or `undefined`.
- */
-export declare function assertDefined<T>(value: T, message: AssertionMessage): asserts value is NonNullable<T>;
 /**
  * Returns a value that must be present, throwing if it is not.
  *
- * The expression-position counterpart to {@link assertDefined}: it checks
- * and returns in one step, so an indexed read can be asserted inline
+ * Checks and returns in one step, so an indexed read can be asserted inline
  * (`push({ content: expectDefined(lines[k], …) })`) without first binding
  * it to a local.
  *
@@ -44,3 +31,4 @@ export declare function assertDefined<T>(value: T, message: AssertionMessage): a
  * @throws {@link InternalInvariantError} when `value` is `null` or `undefined`.
  */
 export declare function expectDefined<T>(value: T, message: AssertionMessage): NonNullable<T>;
+export {};

package/dist/src/utils/assert.js

@@ -46,27 +46,10 @@ export function assert(condition, message) {
         throw new InternalInvariantError(resolveMessage(message));
     }
 }
-/**
- * Asserts that a value is neither `null` nor `undefined`, narrowing it in
- * place for the statements that follow.
- *
- * Use this in statement position, where the value is already bound to a
- * name. Use {@link expectDefined} in expression position, where it is not.
- *
- * @param value - The value that should be present
- * @param message - What was supposed to be present, and why
- * @throws {@link InternalInvariantError} when `value` is `null` or `undefined`.
- */
-export function assertDefined(value, message) {
-    if (value === null || value === undefined) {
-        throw new InternalInvariantError(resolveMessage(message));
-    }
-}
 /**
  * Returns a value that must be present, throwing if it is not.
  *
- * The expression-position counterpart to {@link assertDefined}: it checks
- * and returns in one step, so an indexed read can be asserted inline
+ * Checks and returns in one step, so an indexed read can be asserted inline
  * (`push({ content: expectDefined(lines[k], …) })`) without first binding
  * it to a local.
  *

package/dist/src/utils/build-info.d.ts

@@ -1,5 +1,5 @@
 /** Source identity of the running build. */
-export interface BuildIdentity {
+interface BuildIdentity {
     shortCommit: string;
     dirty: boolean;
     /**

package/dist/src/utils/child-env.d.ts

@@ -5,7 +5,7 @@
  * file sits on a 500-line budget; the logic belongs to the exec layer.
  */
 /** The `env` / `envUnset` slice of exec options this module needs. */
-export interface ChildEnvOptions {
+interface ChildEnvOptions {
     /** Variables to add or overwrite on top of `process.env`. */
     env?: Record<string, string> | undefined;
     /** Variables to remove after the merge. */
@@ -28,3 +28,4 @@ export interface ChildEnvOptions {
  * @returns The environment to hand `spawn`
  */
 export declare function buildChildEnv(options: ChildEnvOptions): NodeJS.ProcessEnv;
+export {};

package/dist/src/utils/elapsed.js

@@ -1,5 +1,14 @@
 // SPDX-License-Identifier: EUPL-1.2
-/** Formats elapsed milliseconds for progress messages. */
+/**
+ * Formats a duration in milliseconds as `Xm Ys`, or `Ys` under a minute.
+ *
+ * The single spelling of FireForge's elapsed-time wording: `build` and
+ * `package` each hand-rolled the same minute/second split, so a change to
+ * the format silently applied to some progress lines and not others.
+ *
+ * @param ms - Duration in milliseconds; negative input is clamped to zero.
+ * @returns The duration as `Xm Ys`, or `Ys` when under one minute.
+ */
 function formatElapsed(ms) {
     const totalSeconds = Math.max(0, Math.round(ms / 1000));
     const minutes = Math.floor(totalSeconds / 60);

package/dist/src/utils/fs.js

@@ -3,13 +3,9 @@ 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 { basename, dirname, join } from 'node:path';
 import { getNodeErrorCode } from './errors.js';
+import { sleep } from './sleep.js';
 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);
-    });
-}
 /**
  * Checks if a path exists.
  * @param path - Path to check
@@ -19,8 +15,7 @@ export async function pathExists(path) {
         await access(path);
         return true;
     }
-    catch (error) {
-        void error;
+    catch {
         return false;
     }
 }
@@ -92,8 +87,7 @@ export async function isSymlink(path) {
     try {
         return (await lstat(path)).isSymbolicLink();
     }
-    catch (error) {
-        void error;
+    catch {
         return false;
     }
 }
@@ -234,15 +228,16 @@ async function syncParentDir(path) {
         directoryHandle = await open(dirname(path), 'r');
         await directoryHandle.sync();
     }
-    catch (error) {
-        void error;
+    catch {
+        // Best-effort durability: a directory that cannot be opened or fsynced
+        // (network mounts, Windows) must not fail the write it was protecting.
     }
     finally {
         try {
             await directoryHandle?.close();
         }
-        catch (error) {
-            void error;
+        catch {
+            // Nothing left to do — the handle is being discarded either way.
         }
     }
 }

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

@@ -0,0 +1,12 @@
+/**
+ * Computes the hexadecimal SHA-256 digest of a string or buffer.
+ *
+ * Eleven sites across `src/core/` inlined the same
+ * `createHash('sha256').update(input).digest('hex')` chain for cache keys,
+ * fingerprints and content addresses. They all share this helper instead, so
+ * the digest algorithm and encoding are decided in exactly one place.
+ *
+ * @param input - Data to digest, as a UTF-8 string or a raw buffer.
+ * @returns The 64-character lowercase hexadecimal digest.
+ */
+export declare function sha256Hex(input: string | Buffer): string;

package/dist/src/utils/hash.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { createHash } from 'node:crypto';
+/**
+ * Computes the hexadecimal SHA-256 digest of a string or buffer.
+ *
+ * Eleven sites across `src/core/` inlined the same
+ * `createHash('sha256').update(input).digest('hex')` chain for cache keys,
+ * fingerprints and content addresses. They all share this helper instead, so
+ * the digest algorithm and encoding are decided in exactly one place.
+ *
+ * @param input - Data to digest, as a UTF-8 string or a raw buffer.
+ * @returns The 64-character lowercase hexadecimal digest.
+ */
+export function sha256Hex(input) {
+    return createHash('sha256').update(input).digest('hex');
+}

package/dist/src/utils/line-dispatch.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Line splitting for the smoke-run stream dispatch in `process.ts`. Kept as
+ * a sibling so the exec module stays within its size budget; the contract
+ * (terminators, partial-line cap) is documented on the function.
+ */
+/**
+ * Drains complete lines from `buffer`, dispatching each to `cb`. Treats
+ * `\n`, `\r\n`, and lone `\r` as line terminators — the lone-`\r` case
+ * matters for progress-bar style output (mach, cargo) that repaints a line
+ * with carriage returns and never sends a newline, which otherwise
+ * accumulates indefinitely. A single trailing `\r` is held back since it may
+ * be the first half of a `\r\n` pair split across chunks. Returns the
+ * remaining partial line — callers keep accumulating into it.
+ */
+export declare function dispatchCompleteLines(buffer: string, cb: ((line: string) => void) | undefined): string;

package/dist/src/utils/line-dispatch.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Line splitting for the smoke-run stream dispatch in `process.ts`. Kept as
+ * a sibling so the exec module stays within its size budget; the contract
+ * (terminators, partial-line cap) is documented on the function.
+ */
+/**
+ * Cap on the partial-line tail kept between chunks. A child emitting one
+ * enormous line with no terminator (minified JS dumped to stderr, a raw
+ * binary blob) would otherwise grow the buffer without bound — the 50 MB cap
+ * guards the collector, not these line buffers. When the tail exceeds the
+ * cap it is dispatched as a synthetic (oversized) line so the matchers still
+ * see its content, then the buffer resets.
+ */
+const MAX_PARTIAL_LINE_SIZE = 1024 * 1024;
+/**
+ * Drains complete lines from `buffer`, dispatching each to `cb`. Treats
+ * `\n`, `\r\n`, and lone `\r` as line terminators — the lone-`\r` case
+ * matters for progress-bar style output (mach, cargo) that repaints a line
+ * with carriage returns and never sends a newline, which otherwise
+ * accumulates indefinitely. A single trailing `\r` is held back since it may
+ * be the first half of a `\r\n` pair split across chunks. Returns the
+ * remaining partial line — callers keep accumulating into it.
+ */
+export function dispatchCompleteLines(buffer, cb) {
+    let searchFrom = 0;
+    for (;;) {
+        const nl = buffer.indexOf('\n', searchFrom);
+        const cr = buffer.indexOf('\r', searchFrom);
+        const idx = nl === -1 ? cr : cr === -1 ? nl : Math.min(nl, cr);
+        if (idx === -1)
+            break;
+        if (buffer[idx] === '\r' && idx === buffer.length - 1) {
+            // Possible first half of a chunk-split \r\n — wait for the next chunk.
+            break;
+        }
+        const line = buffer.slice(0, idx);
+        const terminatorLength = buffer[idx] === '\r' && buffer[idx + 1] === '\n' ? 2 : 1;
+        buffer = buffer.slice(idx + terminatorLength);
+        searchFrom = 0;
+        cb?.(line);
+    }
+    if (buffer.length > MAX_PARTIAL_LINE_SIZE) {
+        cb?.(buffer);
+        return '';
+    }
+    return buffer;
+}

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

@@ -1,3 +1,4 @@
+import type { Command } from 'commander';
 /**
  * Filters an object to only include keys whose values are not undefined.
  * Designed for use with exactOptionalPropertyTypes — the result can be
@@ -15,7 +16,6 @@
 export declare function pickDefined<T extends object>(obj: T): {
     [K in keyof T]+?: Exclude<T[K], undefined>;
 };
-import type { Command } from 'commander';
 /**
  * Wraps an option-argument parser so its failures surface through
  * commander's own invalid-argument channel.
@@ -88,12 +88,6 @@ export declare function resolveWaitLockSeconds(value: string | number | boolean
  * @returns The session budget in milliseconds, or undefined
  */
 export declare function sessionWaitLockMs(): number | undefined;
-/**
- * True when `command` already declares `--wait-lock` itself. Used by the
- * CLI wiring to add the accept-and-ignore variant only where the honoring
- * one is absent.
- */
-export declare function hasWaitLockOption(command: Command): boolean;
 /**
  * Recursively gives every command in the tree a `--wait-lock` flag: the
  * honoring registration where one already exists, the accept-and-ignore

package/dist/src/utils/options.js

@@ -1,4 +1,6 @@
-// SPDX-License-Identifier: EUPL-1.2
+import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { toError } from './errors.js';
 /**
  * Filters an object to only include keys whose values are not undefined.
  * Designed for use with exactOptionalPropertyTypes — the result can be
@@ -22,9 +24,6 @@ export function pickDefined(obj) {
     }
     return result;
 }
-import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { toError } from './errors.js';
 /**
  * Wraps an option-argument parser so its failures surface through
  * commander's own invalid-argument channel.
@@ -106,7 +105,7 @@ function waitLockSecondsFromEnv() {
     }
     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);
+        throw new InvalidArgumentError(`${WAIT_LOCK_ENV_VAR} must be an integer in ${MIN_WAIT_LOCK_SECONDS}..${MAX_WAIT_LOCK_SECONDS} (got "${raw}")`, WAIT_LOCK_ENV_VAR);
     }
     return parsed;
 }
@@ -140,7 +139,7 @@ export function resolveWaitLockSeconds(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}")`);
+        throw new GeneralError(`--wait-lock must be an integer in ${MIN_WAIT_LOCK_SECONDS}..${MAX_WAIT_LOCK_SECONDS} (got "${value}")`);
     }
     return parsed;
 }
@@ -191,7 +190,7 @@ function addAcceptedWaitLockOption(command) {
  * CLI wiring to add the accept-and-ignore variant only where the honoring
  * one is absent.
  */
-export function hasWaitLockOption(command) {
+function hasWaitLockOption(command) {
     return command.options.some((option) => option.long === '--wait-lock');
 }
 /**

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

@@ -3,21 +3,12 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getNodeErrorCode, toError } from './errors.js';
+import { parseObject } from './parse.js';
 import { isObject } from './validation.js';
-function validatePackageMetadata(data, filePath) {
-    if (typeof data !== 'object' || data === null) {
-        throw new Error(`Invalid package metadata in ${filePath}: expected an object`);
-    }
-    const name = 'name' in data ? data.name : undefined;
-    const version = 'version' in data ? data.version : undefined;
-    if (typeof name !== 'string' || typeof version !== 'string') {
-        throw new Error(`Invalid package metadata in ${filePath}: expected string "name" and "version" fields`);
-    }
-    return { name, version, bin: 'bin' in data ? data.bin : undefined };
-}
 function readPackageMetadata(filePath) {
     const raw = readFileSync(filePath, 'utf-8');
-    return validatePackageMetadata(JSON.parse(raw), filePath);
+    const parsed = parseObject(JSON.parse(raw), 'package.json');
+    return { name: parsed.string('name'), version: parsed.string('version'), bin: parsed.raw('bin') };
 }
 let cachedPackageRoot;
 /**

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

@@ -2,10 +2,6 @@
  * Supported operating system platforms.
  */
 export type Platform = 'darwin' | 'linux' | 'win32';
-/**
- * Supported CPU architectures.
- */
-export type Arch = 'x64' | 'arm64';
 /**
  * Gets the current operating system platform.
  * @throws Error if running on an unsupported platform

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

@@ -19,7 +19,7 @@ import { type ChildProcess } from 'node:child_process';
  */
 export declare function killProcessTree(child: ChildProcess, signal: NodeJS.Signals, usesProcessGroup: boolean): void;
 /** One process still alive in a swept group. */
-export interface ProcessGroupSurvivor {
+interface ProcessGroupSurvivor {
     /** PID, or -1 when pgrep was unavailable and only a liveness probe ran. */
     pid: number;
     /** Command line (pgrep -lf output), best-effort. */
@@ -36,3 +36,4 @@ export interface ProcessGroupSurvivor {
 export declare function sweepProcessGroup(pgid: number, graceMs?: number): Promise<{
     survivors: ProcessGroupSurvivor[];
 }>;
+export {};

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

@@ -8,6 +8,7 @@
 import { spawn } from 'node:child_process';
 import { getNodeErrorCode } from './errors.js';
 import { verbose, warn } from './logger.js';
+import { sleep } from './sleep.js';
 /**
  * Sends `signal` to the child's whole tree: the process GROUP on POSIX
  * (negative-PID kill — reaches mach → python → firefox → content-process
@@ -61,18 +62,6 @@ export function killProcessTree(child, signal, usesProcessGroup) {
 }
 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").
@@ -130,7 +119,7 @@ function describeSurvivors(list) {
         const tag = MULTIPROCESSING_WORKER_PATTERN.test(s.command)
             ? ' [multiprocessing worker — the known busy-spin orphan shape]'
             : '';
-        return `PID ${String(s.pid)}: ${s.command}${tag}`;
+        return `PID ${s.pid}: ${s.command}${tag}`;
     })
         .join('; ');
 }
@@ -148,7 +137,7 @@ export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
     const survivors = await listGroupSurvivors(pgid);
     if (survivors.length === 0)
         return { survivors };
-    warn(`Harness process group ${String(pgid)} left ${String(survivors.length)} surviving ` +
+    warn(`Harness process group ${pgid} left ${survivors.length} surviving ` +
         `process(es) after exit — reaping the group. ${describeSurvivors(survivors)}`);
     try {
         process.kill(-pgid, 'SIGTERM');
@@ -158,7 +147,13 @@ export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
         // escalate against, so report the survivors collected so far.
         return { survivors };
     }
-    await sweepDelay(graceMs);
+    // Deliberately ref'd (sleep's default): this wait sits between the group
+    // SIGTERM and the post-grace re-list/SIGKILL escalation, awaited from a
+    // child 'close' handler after the signal forwarder is disposed. With an
+    // unref'd timer nothing keeps the event loop alive, so Node could exit
+    // mid-grace and skip the escalation entirely. Healthy runs never reach
+    // here (sweepProcessGroup early-returns on zero survivors).
+    await sleep(graceMs);
     let remaining = await listGroupSurvivors(pgid);
     if (remaining.length > 0) {
         try {
@@ -169,18 +164,24 @@ export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
             // nothing to signal.
             return { survivors };
         }
-        await sweepDelay(Math.min(200, graceMs));
+        // Deliberately ref'd (sleep's default): this wait sits between the group
+        // SIGTERM and the post-grace re-list/SIGKILL escalation, awaited from a
+        // child 'close' handler after the signal forwarder is disposed. With an
+        // unref'd timer nothing keeps the event loop alive, so Node could exit
+        // mid-grace and skip the escalation entirely. Healthy runs never reach
+        // here (sweepProcessGroup early-returns on zero survivors).
+        await sleep(Math.min(200, graceMs));
         remaining = await listGroupSurvivors(pgid);
         if (remaining.length > 0) {
-            warn(`Process group ${String(pgid)} still has survivors after SIGKILL: ${describeSurvivors(remaining)}. ` +
+            warn(`Process group ${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.`);
+            verbose(`Process group ${pgid} reaped after SIGKILL escalation.`);
         }
     }
     else {
-        verbose(`Process group ${String(pgid)} reaped cleanly with SIGTERM.`);
+        verbose(`Process group ${pgid} reaped cleanly with SIGTERM.`);
     }
     return { survivors };
 }

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

@@ -21,7 +21,12 @@ export interface ExecResult {
     stderrTruncated?: boolean;
 }
 /**
- * Options for command execution.
+ * Options for plain `exec()` — the pipe-capturing, non-grouped, non-mirrored
+ * path. The other wrappers extend this with the fields they actually read:
+ * `processGroup` lives in {@link ProcessGroupOptions}, `mirror` in
+ * {@link MirrorOptions}. Neither belongs here because `exec()` reads
+ * neither — a field the type accepts but the function ignores is a trap
+ * (the caller believes it got a process group, and never did).
  */
 export interface ExecOptions {
     /** Working directory for the command */
@@ -40,18 +45,32 @@ export interface ExecOptions {
      * that must not have any.
      */
     envUnset?: readonly string[];
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Output mirroring for the wrappers that capture through a collector
+ * ({@link execInheritCapture}, {@link execSmokeRun}).
+ */
+export interface MirrorOptions {
     /**
      * Streams to mirror the child's output into, replacing the default
      * `process.stdout` / `process.stderr` on the stdio-inheriting capture
+     * path, or an operator-supplied `--capture-console` file on the smoke
      * path. Lets a caller tee the live output somewhere else (a run log)
-     * without a second per-chunk hook.
+     * without a second per-chunk hook. Writes happen inline with capture and
+     * the stream is NOT closed here — the caller owns its lifecycle.
      */
     mirror?: {
         stdout?: NodeJS.WritableStream;
         stderr?: NodeJS.WritableStream;
     };
-    /** Timeout in milliseconds */
-    timeout?: number;
+}
+/**
+ * Process-group reaping for the long-lived wrappers ({@link execStream},
+ * {@link execInherit}, {@link execInheritCapture}).
+ */
+export interface ProcessGroupOptions {
     /**
      * POSIX: spawn the child as a process-group leader and route every kill
      * (parent-signal forwarding, abort, escalation) to the whole GROUP, then
@@ -78,11 +97,11 @@ export declare function exec(command: string, args: string[], options?: ExecOpti
 /**
  * Callback for streaming output.
  */
-export type StreamCallback = (data: string) => void;
+type StreamCallback = (data: string) => void;
 /**
  * Options for streaming command execution.
  */
-export interface StreamOptions extends ExecOptions {
+interface StreamOptions extends ExecOptions, ProcessGroupOptions {
     /** Callback for stdout data */
     onStdout?: StreamCallback;
     /** Callback for stderr data */
@@ -124,6 +143,14 @@ export declare function trackChildClosure(): {
  * Resolves immediately when no children are active.
  */
 export declare function waitForActiveChildShutdown(timeoutMs: number): Promise<void>;
+/** Options for {@link execInherit}. */
+export interface InheritOptions extends ExecOptions, ProcessGroupOptions {
+    /** Grace period between the forwarded SIGTERM and the SIGKILL escalation (default 1500 ms). */
+    shutdownGraceMs?: number;
+}
+/** Options for {@link execInheritCapture}: the inherit path plus output mirroring. */
+export interface InheritCaptureOptions extends InheritOptions, MirrorOptions {
+}
 /**
  * Executes a command and inherits stdio (shows output directly).
  *
@@ -140,9 +167,7 @@ export declare function waitForActiveChildShutdown(timeoutMs: number): Promise<v
  * @param options - Execution options
  * @returns Exit code of the process
  */
-export declare function execInherit(command: string, args: string[], options?: ExecOptions & {
-    shutdownGraceMs?: number;
-}): Promise<number>;
+export declare function execInherit(command: string, args: string[], options?: InheritOptions): Promise<number>;
 /**
  * Wires parent-process SIGINT/SIGTERM to a child: first signal → child.kill
  * (SIGTERM) + grace timer; second matching signal → immediate SIGKILL; grace
@@ -162,9 +187,7 @@ export declare function installGracefulShutdownForwarder(child: ReturnType<typeo
  * @param options - Execution options
  * @returns Execution result with stdout, stderr, and exit code
  */
-export declare function execInheritCapture(command: string, args: string[], options?: ExecOptions & {
-    shutdownGraceMs?: number;
-}): Promise<ExecResult>;
+export declare function execInheritCapture(command: string, args: string[], options?: InheritCaptureOptions): Promise<ExecResult>;
 /** Per-line callback for smoke-run stream dispatch. */
 export type SmokeLineCallback = (line: string) => void;
 /**
@@ -175,11 +198,11 @@ export type SmokeLineCallback = (line: string) => void;
  * 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.
+ * {@link ProcessGroupOptions} is not mixed in 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, 'processGroup' | 'timeout'> {
+interface SmokeRunOptions extends Omit<ExecOptions, 'timeout'>, MirrorOptions {
     /**
      * Hard deadline in milliseconds. When it elapses the child process
      * group is sent SIGTERM and, after `killGraceMs`, SIGKILL. The returned
@@ -199,16 +222,6 @@ export interface SmokeRunOptions extends Omit<ExecOptions, 'processGroup' | 'tim
     onStdoutLine?: SmokeLineCallback;
     /** Invoked once per complete line of stderr. Final partial line is flushed on close. */
     onStderrLine?: SmokeLineCallback;
-    /**
-     * Optional writable stream to mirror captured output to (e.g. an
-     * operator-supplied `--capture-console` file). Writes happen inline
-     * with line dispatch and the stream is NOT closed here — the caller
-     * owns its lifecycle.
-     */
-    mirror?: {
-        stdout?: NodeJS.WritableStream;
-        stderr?: NodeJS.WritableStream;
-    };
 }
 /** Result of {@link execSmokeRun}. */
 export interface SmokeRunResult extends ExecResult {
@@ -255,3 +268,4 @@ export declare function findExecutable(name: string): Promise<string | undefined
  * @returns True if the executable exists
  */
 export declare function executableExists(name: string): Promise<boolean>;
+export {};