@hominis/fireforge 0.46.2 → 0.47.1

package/dist/src/core/parent-exit-watchdog.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Detects the death of FireForge's own parent while a harness runs.
+ *
+ * A supervisor that SIGKILLs the process above `fireforge test` (the
+ * 2026-09-13 incident: a gate killed its `npm` step at the 15-minute bound)
+ * signals nothing below it. FireForge is not told; its stdout pipe merely
+ * breaks, and the broken-pipe handler swallows EPIPE on purpose so `| head`
+ * works. The mach tree it spawned as a separate process group keeps running
+ * under nobody's supervision, and the httpd in that tree spun at 100% CPU
+ * for hours.
+ *
+ * SIGKILL cannot be caught, but reparenting can be observed: once the parent
+ * is gone, `process.ppid` changes (to launchd/init, or to a subreaper). This
+ * watchdog polls for that while a dispatch is in flight and fires once. It
+ * does not decide what to do about it; the test command tears down the
+ * harness tree and ends the run.
+ *
+ * Off on Windows: `process.ppid` is not refreshed there after the parent
+ * exits, and there is no process group to signal in response anyway.
+ */
+/** Options for {@link startParentExitWatchdog}. */
+export interface ParentExitWatchdogOptions {
+    /** Probe interval, default {@link DEFAULT_INTERVAL_MS}. */
+    intervalMs?: number;
+    /** Called exactly once, the first time the parent is seen to be gone. */
+    onParentExit: (info: {
+        originalPpid: number;
+        currentPpid: number;
+    }) => void;
+    /**
+     * Reads the current parent pid; default `process.ppid`. Injectable because
+     * `process.ppid` cannot be stubbed on every Node line: redefining the
+     * property is honoured on Node 26 and silently ignored on Node 22, so a
+     * test that stubs it passes on one and never observes a reparent on the
+     * other.
+     */
+    readPpid?: () => number;
+}
+/** Handle for a running watchdog. */
+export interface ParentExitWatchdog {
+    /** Stops probing. Idempotent. A stopped watchdog never fires. */
+    stop(): void;
+}
+/**
+ * True once any watchdog in this process has seen the parent die. The
+ * dispatch loop reads it to end the run instead of classifying the killed
+ * harness as a crash and retrying it under a parent that no longer exists.
+ */
+export declare function parentExited(): boolean;
+/**
+ * Forgets an observed parent exit.
+ *
+ * @internal Exported only so tests can reach it. It is not part of the
+ * public surface.
+ */
+export declare function resetParentExitForTests(): void;
+/**
+ * Starts probing `process.ppid`. The timer is unref'd so the watchdog can
+ * never be the thing keeping FireForge alive; while a child runs, the child
+ * does that.
+ */
+export declare function startParentExitWatchdog(options: ParentExitWatchdogOptions): ParentExitWatchdog;

package/dist/src/core/parent-exit-watchdog.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Detects the death of FireForge's own parent while a harness runs.
+ *
+ * A supervisor that SIGKILLs the process above `fireforge test` (the
+ * 2026-09-13 incident: a gate killed its `npm` step at the 15-minute bound)
+ * signals nothing below it. FireForge is not told; its stdout pipe merely
+ * breaks, and the broken-pipe handler swallows EPIPE on purpose so `| head`
+ * works. The mach tree it spawned as a separate process group keeps running
+ * under nobody's supervision, and the httpd in that tree spun at 100% CPU
+ * for hours.
+ *
+ * SIGKILL cannot be caught, but reparenting can be observed: once the parent
+ * is gone, `process.ppid` changes (to launchd/init, or to a subreaper). This
+ * watchdog polls for that while a dispatch is in flight and fires once. It
+ * does not decide what to do about it; the test command tears down the
+ * harness tree and ends the run.
+ *
+ * Off on Windows: `process.ppid` is not refreshed there after the parent
+ * exits, and there is no process group to signal in response anyway.
+ */
+/** How often the parent is probed. Cheap (one syscall), so a short interval is fine. */
+const DEFAULT_INTERVAL_MS = 2000;
+let parentExitObserved = false;
+/**
+ * True once any watchdog in this process has seen the parent die. The
+ * dispatch loop reads it to end the run instead of classifying the killed
+ * harness as a crash and retrying it under a parent that no longer exists.
+ */
+export function parentExited() {
+    return parentExitObserved;
+}
+/**
+ * Forgets an observed parent exit.
+ *
+ * @internal Exported only so tests can reach it. It is not part of the
+ * public surface.
+ */
+export function resetParentExitForTests() {
+    parentExitObserved = false;
+}
+/**
+ * Starts probing `process.ppid`. The timer is unref'd so the watchdog can
+ * never be the thing keeping FireForge alive; while a child runs, the child
+ * does that.
+ */
+export function startParentExitWatchdog(options) {
+    if (process.platform === 'win32') {
+        return { stop: () => undefined };
+    }
+    const readPpid = options.readPpid ?? (() => process.ppid);
+    const originalPpid = readPpid();
+    let timer = setInterval(() => {
+        const currentPpid = readPpid();
+        if (currentPpid === originalPpid)
+            return;
+        stop();
+        parentExitObserved = true;
+        options.onParentExit({ originalPpid, currentPpid });
+    }, options.intervalMs ?? DEFAULT_INTERVAL_MS);
+    timer.unref();
+    function stop() {
+        if (timer === undefined)
+            return;
+        clearInterval(timer);
+        timer = undefined;
+    }
+    return { stop };
+}

package/dist/src/core/patch-lint-imports.js

@@ -54,14 +54,14 @@ export function hasRelativeImport(content) {
     try {
         return astHasRelativeImport(content, 'module');
     }
-    catch (moduleError) {
-        void moduleError;
+    catch {
+        // Not parseable as an ES module; try classic-script mode next.
     }
     try {
         return astHasRelativeImport(content, 'script');
     }
-    catch (scriptError) {
-        void scriptError;
+    catch {
+        // Not parseable at all; fall back to stripped-text matching below.
     }
     return RELATIVE_IMPORT_FALLBACK_PATTERN.test(stripJsComments(content));
 }

package/dist/src/core/smoke-patterns.d.ts

@@ -29,6 +29,12 @@ export interface CompiledAllowlistEntry {
     source: string;
     /** Human-readable origin: `allow.txt:12` or `--console-allow #2`. */
     origin: string;
+    /**
+     * Ceiling from a `# max-hits: N` directive above the entry: how often the
+     * suppressed cause can physically fire in one boot. More hits than this
+     * is a flood wearing an allowlisted shape, and fails the run.
+     */
+    maxHits?: number;
 }
 /**
  * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
@@ -43,8 +49,26 @@ export declare function matchAllowlist(line: string, allow: readonly CompiledAll
  * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
  * pattern throws immediately: better to fail fast at CLI parse time than
  * to silently let a typo match nothing.
+ *
+ * A `# max-hits: N` comment sets the ceiling of the entry that follows it
+ * (other comment lines may sit between). A blank line or end of file with
+ * no entry after the directive is an error rather than a silently dropped
+ * cap, since a cap the operator wrote and the run ignored is the exact
+ * shape of failure this directive exists to prevent.
  */
 export declare function compileAllowlistFromFile(body: string, sourcePath: string): CompiledAllowlistEntry[];
+/** An allowlist entry that matched more lines than its `# max-hits` ceiling. */
+export interface OverCapAllowlistEntry {
+    entry: CompiledAllowlistEntry;
+    hits: number;
+    maxHits: number;
+}
+/**
+ * Entries whose per-entry hit count (every matched line, error-class or
+ * not: the `N×` number the attribution block prints and the operator tunes
+ * against) exceeds their ceiling. Entries without a ceiling never appear.
+ */
+export declare function findOverCapAllowlistEntries(allow: readonly CompiledAllowlistEntry[], hits: readonly number[]): OverCapAllowlistEntry[];
 /**
  * Compiles an array of regex-string inputs (e.g. repeated `--console-allow`
  * flag values). Same fail-fast semantics as {@link compileAllowlistFromFile}.

package/dist/src/core/smoke-patterns.js

@@ -56,6 +56,14 @@ export function matchesSmokeError(line) {
     }
     return false;
 }
+/** `# max-hits: N` on its own comment line, case-insensitive. */
+const MAX_HITS_DIRECTIVE = /^#\s*max-hits:\s*(\S+)\s*$/i;
+function parseMaxHitsDirective(raw, at) {
+    if (!/^[1-9]\d*$/.test(raw)) {
+        throw new Error(`Invalid allowlist max-hits directive at ${at}: expected a positive integer (got "${raw}")`);
+    }
+    return Number.parseInt(raw, 10);
+}
 /**
  * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
  * First-match attribution is deterministic and cheap. A line matching
@@ -71,30 +79,67 @@ export function matchAllowlist(line, allow) {
  * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
  * pattern throws immediately: better to fail fast at CLI parse time than
  * to silently let a typo match nothing.
+ *
+ * A `# max-hits: N` comment sets the ceiling of the entry that follows it
+ * (other comment lines may sit between). A blank line or end of file with
+ * no entry after the directive is an error rather than a silently dropped
+ * cap, since a cap the operator wrote and the run ignored is the exact
+ * shape of failure this directive exists to prevent.
  */
 export function compileAllowlistFromFile(body, sourcePath) {
     const lines = body.split(/\r?\n/);
     const compiled = [];
+    let pending;
+    const assertNoOrphanDirective = () => {
+        if (pending) {
+            throw new Error(`Invalid allowlist max-hits directive at ${pending.at}: no entry follows it (the ceiling applies to the next non-comment line)`);
+        }
+    };
     lines.forEach((raw, index) => {
         const line = raw.trim();
-        if (!line || line.startsWith('#'))
+        const at = `${sourcePath}:${index + 1}`;
+        if (!line) {
+            assertNoOrphanDirective();
             return;
+        }
+        if (line.startsWith('#')) {
+            const directive = MAX_HITS_DIRECTIVE.exec(line);
+            if (directive)
+                pending = { maxHits: parseMaxHitsDirective(directive[1] ?? '', at), at };
+            return;
+        }
         try {
             compiled.push({
                 pattern: new RegExp(line),
                 source: line,
-                origin: `${sourcePath}:${index + 1}`,
+                origin: at,
+                ...(pending ? { maxHits: pending.maxHits } : {}),
             });
         }
         catch (error) {
             const message = toError(error).message;
-            throw new Error(`Invalid allowlist regex at ${sourcePath}:${index + 1}: ${message}`, {
-                cause: error,
-            });
+            throw new Error(`Invalid allowlist regex at ${at}: ${message}`, { cause: error });
         }
+        pending = undefined;
     });
+    assertNoOrphanDirective();
     return compiled;
 }
+/**
+ * Entries whose per-entry hit count (every matched line, error-class or
+ * not: the `N×` number the attribution block prints and the operator tunes
+ * against) exceeds their ceiling. Entries without a ceiling never appear.
+ */
+export function findOverCapAllowlistEntries(allow, hits) {
+    const over = [];
+    allow.forEach((entry, index) => {
+        const count = hits[index] ?? 0;
+        if (entry.maxHits !== undefined && count > entry.maxHits) {
+            over.push({ entry, hits: count, maxHits: entry.maxHits });
+        }
+    });
+    return over;
+}
 /**
  * Compiles an array of regex-string inputs (e.g. repeated `--console-allow`
  * flag values). Same fail-fast semantics as {@link compileAllowlistFromFile}.

package/dist/src/types/commands/options.d.ts

@@ -612,9 +612,19 @@ export interface TestOptions extends EngineLockWaitable {
      * project's objdir. The census itself runs on every test dispatch and is
      * report-only. This flag opts into the kill. Survivors slow later runs
      * without appearing in their output, so the visibility is the default and
-     * the termination is the choice.
+     * the termination is the choice. `test.reapOrphans: "reap"` in
+     * `fireforge.json` makes it the repo's default.
      */
     reapOrphans?: boolean;
+    /**
+     * Path to write the harness process-group id to, rewritten on every mach
+     * spawn (each retry attempt and shard) and removed when the run ends under
+     * FireForge's control. mach runs as its own process-group leader, so a
+     * supervisor's kill of its own group never reaches it; a supervisor that
+     * had to SIGKILL FireForge takes the whole harness tree afterwards with
+     * `kill -- -<pgid>`. The file survives exactly that case, by design.
+     */
+    pgidFile?: string;
     /** Permit tests against packageable engine edits newer than the last successful build. */
     allowStaleBuild?: boolean;
     /**
@@ -655,6 +665,12 @@ export interface TestOptions extends EngineLockWaitable {
      * checkers that consume a sample artifact after the run.
      */
     perfSamples?: string;
+    /**
+     * Seeded file-order shuffle for mochitest runs. `true` draws a fresh seed;
+     * a number replays one. Forwarded as mach `--shuffle` with the seed
+     * exported as `FIREFORGE_SHUFFLE_SEED` and stamped on the verdict line.
+     */
+    shuffle?: number | boolean;
 }
 /**
  * Options for the furnace apply command.

package/dist/src/types/config.d.ts

@@ -47,6 +47,13 @@ export interface TestConfig {
     canaryPath?: string;
     /** Short no-output ceiling for `fireforge test --canary`, in seconds. */
     canaryTimeoutSeconds?: number;
+    /**
+     * What the preflight orphan census does with a harness helper that
+     * survived an earlier run in this objdir: `report` (default) names it and
+     * proceeds; `reap` terminates it and stamps `orphans-reaped=<n>` on the
+     * verdict line. `--reap-orphans` is the per-invocation equivalent.
+     */
+    reapOrphans?: 'report' | 'reap';
 }
 /** A single external executable required by a project-specific toolchain. */
 export interface ExternalToolRequirement {

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

@@ -32,8 +32,12 @@ interface ProcessGroupSurvivor {
  * 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`.
+ *
+ * `context` names why the group is being reaped in the warning; the default
+ * is the post-close sweep. The parent-exit watchdog passes its own, because
+ * there the group is still running when the sweep begins.
  */
-export declare function sweepProcessGroup(pgid: number, graceMs?: number): Promise<{
+export declare function sweepProcessGroup(pgid: number, graceMs?: number, context?: string): Promise<{
     survivors: ProcessGroupSurvivor[];
 }>;
 export {};

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

@@ -130,15 +130,19 @@ function describeSurvivors(list) {
  * 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`.
+ *
+ * `context` names why the group is being reaped in the warning; the default
+ * is the post-close sweep. The parent-exit watchdog passes its own, because
+ * there the group is still running when the sweep begins.
  */
-export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
+export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS, context = 'after exit') {
     if (process.platform === 'win32')
         return { survivors: [] };
     const survivors = await listGroupSurvivors(pgid);
     if (survivors.length === 0)
         return { survivors };
-    warn(`Harness process group ${pgid} left ${survivors.length} surviving ` +
-        `process(es) after exit — reaping the group. ${describeSurvivors(survivors)}`);
+    warn(`Harness process group ${pgid} has ${survivors.length} live ` +
+        `process(es) ${context} — reaping the group. ${describeSurvivors(survivors)}`);
     try {
         process.kill(-pgid, 'SIGTERM');
     }

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

@@ -85,6 +85,24 @@ export interface ProcessGroupOptions {
      * whenever this option is set.
      */
     processGroup?: boolean;
+    /**
+     * Receives the process-group id (the detached child's pid) right after a
+     * group-leader spawn. Lets a caller expose the group to a supervisor that
+     * cannot signal FireForge itself gracefully (`fireforge test --pgid-file`),
+     * or hold it for a teardown of its own. Not called when no group was
+     * created (`processGroup` unset, or win32).
+     */
+    onProcessGroup?: (pgid: number) => void;
+    /**
+     * Extra teardown the caller owns, awaited after the child's `close` and
+     * the post-run group sweep, before the child's closure settles. Placed
+     * here rather than after the wrapper resolves so the bin signal handler's
+     * `waitForActiveChildShutdown` covers it too: a reap that ran after the
+     * wrapper resolved would race `process.exit` on a forwarded SIGTERM. Must
+     * never throw; a rejection is swallowed so it cannot mask the child's
+     * result.
+     */
+    postCloseSweep?: () => Promise<void>;
 }
 /**
  * Executes a command and returns its output.

package/dist/src/utils/process.js

@@ -154,6 +154,8 @@ async function spawnTracked(spec) {
             detached: usesProcessGroup,
         });
         const groupPid = usesProcessGroup ? child.pid : undefined;
+        if (groupPid !== undefined)
+            options.onProcessGroup?.(groupPid);
         spec.attach?.(child);
         // Group-aware kills route to the whole tree. A non-group child is killed
         // directly by the forwarder's own `child.kill`.
@@ -183,11 +185,21 @@ async function spawnTracked(spec) {
                 closure.settle();
                 resolve(spec.result(code, signal));
             };
+            // Group sweep first (it takes the helpers that stayed in the group),
+            // then the caller's own sweep (the ones that did not), then settle.
+            const callerSweep = () => {
+                const sweep = options.postCloseSweep;
+                if (sweep === undefined) {
+                    finish();
+                    return;
+                }
+                sweep().then(finish, finish);
+            };
             if (groupPid !== undefined) {
-                sweepProcessGroup(groupPid).then(finish, finish);
+                sweepProcessGroup(groupPid).then(callerSweep, callerSweep);
             }
             else {
-                finish();
+                callerSweep();
             }
         });
     });

package/docs/configuration.md

@@ -113,7 +113,13 @@ gaps does not move a patch out of the band its category owns.
 ## `test`
 
 `test.canaryPath` and `test.canaryTimeoutSeconds` supply the defaults for
-`fireforge test --canary`. See [`testing.md`](testing.md).
+`fireforge test --canary`.
+
+`test.reapOrphans` is `"report"` (default) or `"reap"`: what the preflight
+census does with a harness helper that survived an earlier run in this
+objdir. `"reap"` terminates it and stamps `orphans-reaped=<n>` on the verdict
+line; `--reap-orphans` does the same for one invocation. The objdir anchor
+rule is the same under both. See [`testing.md`](testing.md).
 
 ## `buildAudit`
 
@@ -219,6 +225,14 @@ non-CI launches print a warning saying so. Exit codes 12 and 13 separate a
 console regression from a launch failure. See
 [`exit-codes.md`](exit-codes.md).
 
+The allowlist (`--console-allow-file`) is count-blind by default: a line that
+matches an entry never counts, however often it fires. A `# max-hits: N`
+comment directly above an entry (other comments may sit between) caps how
+many lines that entry may match in one run. The attribution block prints
+capped entries as `hits×/N`, and an entry that fires past its ceiling is
+reported and fails the run with exit 12, the same as an unallowed error. A
+directive with no entry after it is refused rather than silently ignored.
+
 ## Lock waits
 
 Every FireForge command that mutates the engine takes the engine-session

package/docs/exit-codes.md

@@ -7,25 +7,25 @@ branches on it, and CI uses it to decide whether to retry or escalate. The
 values live in `src/errors/codes.ts`. This file says what they mean and
 which error class produces each one.
 
-| Code | Name                   | Meaning                                                                                                                 | Produced by                                                                                       |
-| ---: | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined: declining is a successful run that chose not to proceed. | (none)                                                                                            |
-|    1 | `GENERAL_ERROR`        | Unspecified failure the operator has to act on.                                                                         | `GeneralError` (and `PreflightRefusalError`), `ParserFallbackError`, `ExecTimeoutError`           |
-|    2 | `CONFIG_ERROR`         | `fireforge.json` missing or invalid.                                                                                    | `ConfigError` and subclasses                                                                      |
-|    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                           | `DownloadError` and subclasses                                                                    |
-|    4 | `GIT_ERROR`            | A git operation failed.                                                                                                 | `GitError` and subclasses, except `GitNotFoundError`                                              |
-|    5 | `BUILD_ERROR`          | `mach build` failed, or a test suite went red.                                                                          | `BuildError` and subclasses, `TestFailureError`                                                   |
-|    6 | `PATCH_ERROR`          | A patch failed to apply, or the patch queue could not be mutated.                                                       | `PatchError`, `PatchManifestCorruptError`, `RebaseError` and subclasses                           |
-|    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                      | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError`                                    |
-|    8 | `INVALID_ARGUMENT`     | The flags were wrong. A usage problem, not an environment one.                                                          | `InvalidArgumentError`, plus commander usage errors (unknown command or option, missing argument) |
-|    9 | `FURNACE_ERROR`        | A Furnace component operation failed.                                                                                   | `FurnaceError`                                                                                    |
-|   10 | `RESOLUTION_ERROR`     | Conflict resolution failed.                                                                                             | `ResolutionError`                                                                                 |
-|   11 | `INTERNAL_ERROR`       | A FireForge invariant did not hold. This is a bug in FireForge, not something the operator can fix.                     | `InternalInvariantError`                                                                          |
-|   12 | `SMOKE_EXIT_FAILURE`   | `run --smoke-exit` saw console errors that were not allowed in the smoke window.                                        | `SmokeRunError`                                                                                   |
-|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw the browser exit uncleanly before the window elapsed.                                            | `SmokeRunError`                                                                                   |
-|   14 | `INCONCLUSIVE`         | A test run's verdict was thrown away because `engine/` moved while the harness ran. This is not red. Re-run it.         | `InconclusiveVerdictError`                                                                        |
-|   15 | `LOCK_TIMEOUT`         | A lock wait expired, so the run never started. Re-queue it with a larger `--wait-lock`.                                 | `LockContentionError`                                                                             |
-|  130 | `USER_CANCELLED`       | The operator interrupted a prompt (Esc or Ctrl+C). 128 + SIGINT.                                                        | `CancellationError`                                                                               |
+| Code | Name                   | Meaning                                                                                                                                       | Produced by                                                                                       |
+| ---: | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined: declining is a successful run that chose not to proceed.                       | (none)                                                                                            |
+|    1 | `GENERAL_ERROR`        | Unspecified failure the operator has to act on.                                                                                               | `GeneralError` (and `PreflightRefusalError`), `ParserFallbackError`, `ExecTimeoutError`           |
+|    2 | `CONFIG_ERROR`         | `fireforge.json` missing or invalid.                                                                                                          | `ConfigError` and subclasses                                                                      |
+|    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                                                 | `DownloadError` and subclasses                                                                    |
+|    4 | `GIT_ERROR`            | A git operation failed.                                                                                                                       | `GitError` and subclasses, except `GitNotFoundError`                                              |
+|    5 | `BUILD_ERROR`          | `mach build` failed, or a test suite went red.                                                                                                | `BuildError` and subclasses, `TestFailureError`                                                   |
+|    6 | `PATCH_ERROR`          | A patch failed to apply, or the patch queue could not be mutated.                                                                             | `PatchError`, `PatchManifestCorruptError`, `RebaseError` and subclasses                           |
+|    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                                            | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError`                                    |
+|    8 | `INVALID_ARGUMENT`     | The flags were wrong. A usage problem, not an environment one.                                                                                | `InvalidArgumentError`, plus commander usage errors (unknown command or option, missing argument) |
+|    9 | `FURNACE_ERROR`        | A Furnace component operation failed.                                                                                                         | `FurnaceError`                                                                                    |
+|   10 | `RESOLUTION_ERROR`     | Conflict resolution failed.                                                                                                                   | `ResolutionError`                                                                                 |
+|   11 | `INTERNAL_ERROR`       | A FireForge invariant did not hold. This is a bug in FireForge, not something the operator can fix.                                           | `InternalInvariantError`                                                                          |
+|   12 | `SMOKE_EXIT_FAILURE`   | `run --smoke-exit` saw console errors that were not allowed in the smoke window, or an allowlisted shape fired past its `# max-hits` ceiling. | `SmokeRunError`                                                                                   |
+|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw the browser exit uncleanly before the window elapsed.                                                                  | `SmokeRunError`                                                                                   |
+|   14 | `INCONCLUSIVE`         | A test run's verdict was thrown away because `engine/` moved while the harness ran. This is not red. Re-run it.                               | `InconclusiveVerdictError`                                                                        |
+|   15 | `LOCK_TIMEOUT`         | A lock wait expired, so the run never started. Re-queue it with a larger `--wait-lock`.                                                       | `LockContentionError`                                                                             |
+|  130 | `USER_CANCELLED`       | The operator interrupted a prompt (Esc or Ctrl+C). 128 + SIGINT.                                                                              | `CancellationError`                                                                               |
 
 Usage errors that commander detects itself (an unknown command, an unknown
 or malformed option, a missing required argument) never reach a command

package/docs/lifecycle-invariants.md

@@ -284,7 +284,10 @@ Wait ergonomics are opt-in: `pollMaxMs` (the poll interval doubles from
 `pollMs` up to the cap) and `waitProgressMs` with `onWaitProgress` (a periodic
 progress callback carrying the holder's PID, liveness, and owner-metadata
 lines from the pid file). All three are inert when unset, so existing callers
-keep byte-identical behavior.
+keep byte-identical behavior. Within one poll iteration a due progress probe
+runs before the deadline check, so a wait that times out has always reported
+the holder at least once when its budget exceeds `waitProgressMs`, however
+slow the host (`file-lock.test.ts`, "budget shorter than one iteration").
 
 ### `src/core/file-lock-owner.ts`
 
@@ -430,10 +433,23 @@ On SIGINT or SIGTERM, `bin/fireforge.ts`:
    - `waitForActiveCriticalSections(5 s)`, which holds the exit for in-flight
      "apply plus persist" pairs (invariant 4). It is bounded so that a stuck
      write cannot postpone the exit the user asked for.
+   - `waitForActiveChildShutdown(12 s)`, which holds the exit until every
+     tracked child has closed. For a process-group dispatch (`mach` under
+     `test`, `build`, `run`) "closed" includes the exec layer's post-close
+     work: the group sweep and the caller's `postCloseSweep` (the harness
+     helper reap in `fireforge test`). Both run before the child's closure
+     settles, so a forwarded SIGTERM cannot race `process.exit` past them.
 3. Force-releases the furnace lock directories of active operations, since
    `withFileLock`'s `finally` will never run past `process.exit`.
 4. Calls `process.exit(130 | 143)`.
 
+A parent that dies without signalling FireForge (SIGKILL on the `npm` above
+it) enters no handler here. `fireforge test` covers that case itself with
+the parent-exit watchdog (`src/core/parent-exit-watchdog.ts`): it writes the
+killed verdict, reaps the mach group and the tracked helpers, and lets the
+dispatch loop end the run; the process then exits through the ordinary
+error path, not through this pipeline.
+
 ## Choosing a primitive for a new mutation
 
 | Your operation                                                                                                       | Use                                                                                            |