@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/commands/test-modes.js

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { loadConfig } from '../core/config.js';
 import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { info, success } from '../utils/logger.js';
@@ -46,7 +45,7 @@ export function canaryTimeoutSeconds(projectConfig) {
 /** Emits or throws the one-word canary verdict. */
 export function reportCanaryOutcome(outcome) {
     // Written raw as the run's last stdout line on green and throw paths
-    // alike — see the FIREFORGE-VERDICT contract in test-harness-crash.ts.
+    // alike. See the FIREFORGE-VERDICT contract in test-harness-crash.ts.
     try {
         if (outcome.verdict.kind === 'tests-ran-ok') {
             success('Canary: green');
@@ -98,16 +97,16 @@ function buildMixedHarnessMessage(classification) {
  * dispatch, so refusing it before spending minutes in a pre-test build
  * is strictly better. A nonexistent path classifies as
  * nonXpcshell (findNearestXpcshellManifest returns null), so classifying
- * before assertTestPathsExist is harmless — existence is still asserted
+ * before assertTestPathsExist is harmless: existence is still asserted
  * after the stale/coverage gates, preserving their precedence over
  * missing-path errors. `xpcshellOnly` (non-empty request, zero
  * nonXpcshell paths) gates the Marionette preflight and the mochitest
- * client flags; pathless runs keep the full-suite behavior.
+ * client flags. Pathless runs keep the full-suite behavior.
  */
 export async function classifyBeforeDispatch(engineDir, normalizedPaths, options) {
     const classification = await classifyTestHarnesses(engineDir, normalizedPaths);
     if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
-        // `--build-only` never dispatches, so a mixed request is legal there —
+        // `--build-only` never dispatches, so a mixed request is legal there:
         // packaging the union is the whole point.
         if (options?.allowMixed !== true) {
             throw new GeneralError(buildMixedHarnessMessage(classification));

package/dist/src/commands/test-register.js

@@ -28,7 +28,7 @@ const TEST_HELP_TEXT = [
     'Machine-readable verdict: every run (single, sharded, --canary,',
     '--doctor) ends with exactly one raw stdout line',
     '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|test-failures|',
-    '  no-tests|preflight|inconclusive|lock-timeout] [checks=<n>]',
+    '  no-tests|preflight|inconclusive|lock-timeout|killed] [checks=<n>]',
     '  [unexpected=<n>] [shards=<p>/<t>] [(<note>)] [log=<path>]',
     "log=<path> names this run's complete output, written to",
     '.fireforge/logs/ as the run streams, so a piped or truncated run',
@@ -41,7 +41,9 @@ const TEST_HELP_TEXT = [
     'errors); reason=inconclusive means engine/ changed while the',
     'tests ran, so the harness result cannot be trusted;',
     'reason=lock-timeout means the run never started because another',
-    'engine-mutating command held the lock past the wait budget. A sharded',
+    'engine-mutating command held the lock past the wait budget;',
+    'reason=killed means a signal terminated the run before it reached',
+    'any other outcome (written from the signal handler). A sharded',
     'aggregate reason is the most structural failing shard (crash,',
     'then no-tests, then test-failures). Count keys are omitted when',
     'the embedded summary did not print them. A trailing parenthetical',
@@ -71,7 +73,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--canary [path]', 'Run one short browser-chrome harness canary. Uses test.canaryPath from fireforge.json when no path is supplied.')
         .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
         .option('--mach-arg <arg>', 'Forward this argument verbatim to `mach test` (repeatable). Escape valve for upstream xpcshell/mochitest flags FireForge does not model.', ...stringListOption())
-        .option('--harness-retries <n>', `Retry budget for recognized harness crashes (resource-monitor tracebacks, pre-test hangs, post-green shutdown re-entry). 0 disables retries. Default: ${String(DEFAULT_HARNESS_RETRIES)}.`, commanderArgParser((raw) => {
+        .option('--harness-retries <n>', `Retry budget for recognized harness crashes (resource-monitor tracebacks, pre-test hangs, post-green shutdown re-entry). 0 disables retries. Default: ${DEFAULT_HARNESS_RETRIES}.`, commanderArgParser((raw) => {
         const n = Number.parseInt(raw, 10);
         if (!Number.isFinite(n) || n < 0 || n > 10) {
             throw new GeneralError(`--harness-retries must be an integer in 0..10 (got "${raw}")`);

package/dist/src/commands/test-run.d.ts

@@ -3,10 +3,10 @@
  * sequential per-file sharding of multi-path invocations.
  *
  * Sharding exists because passing several browser-chrome files to one mach
- * invocation destabilizes later files — cross-file profile/pref bleed in the
+ * invocation destabilizes later files: cross-file profile/pref bleed in the
  * shared mochitest profile makes the second file time out at window-open
  * while each file passes in isolation. Sequential single-file harness runs
- * cost startup time but make results reproducible; the combined invocation
+ * cost startup time but make results reproducible. The combined invocation
  * stays available via `--no-shard`.
  */
 import { type DisplaySleepState } from '../core/display-state.js';
@@ -54,8 +54,8 @@ export interface TestRunOutcome {
     /** Whether xpcshell appdir injection was attempted for this invocation. */
     appdirInjectionAttempted: boolean;
     /**
-     * Display power state measured for a HEADED no-output stall;
-     * undefined when the shape did not apply and no probe ran.
+     * Display power state measured for a HEADED no-output stall. Undefined
+     * when the shape did not apply and no probe ran.
      */
     displayState?: DisplaySleepState | undefined;
 }
@@ -68,7 +68,7 @@ export declare function runTestsWithRetries(ctx: TestRunContext, paths: string[]
 /**
  * One sequential harness invocation of a sharded run: a requested path
  * argument and the mach paths dispatched for it. A file argument is a group
- * of one; a directory argument groups its enumerated test files so the whole
+ * of one. A directory argument groups its enumerated test files so the whole
  * directory still runs in ONE browser instance, keeping cross-file state
  * behaviour within a directory run.
  */
@@ -88,25 +88,25 @@ export interface ShardedRunSummary {
     shards: ShardOutcome[];
     passed: number;
     total: number;
-    /** Aggregate classifier verdict — see {@link deriveAggregateShardVerdict}. */
+    /** Aggregate classifier verdict. See {@link deriveAggregateShardVerdict}. */
     aggregate: HarnessRunVerdict;
 }
 /**
  * Derives the aggregate classification for a sharded run: all-green is
- * `tests-ran-ok`; otherwise the most structural failure wins — a crashed
+ * `tests-ran-ok`. Otherwise the most structural failure wins. A crashed
  * shard makes the whole run `harness-crash`, then `no-tests`, then plain
- * `test-failures` — so the aggregate `reason=` keeps the classifier-driven
+ * `test-failures`, so the aggregate `reason=` keeps the classifier-driven
  * contract instead of collapsing every failure to `test-failures`.
  */
 export declare function deriveAggregateShardVerdict(shards: ShardOutcome[]): HarnessRunVerdict;
 /**
  * Runs each requested path argument as its own sequential harness
  * invocation (a directory argument's enumerated files stay together in
- * one invocation — see {@link ShardGroup}) and prints an aggregate
+ * one invocation, see {@link ShardGroup}) and prints an aggregate
  * report. Per-shard failures are diagnosed via `diagnoseShardFailure`
  * (which receives the throwing diagnosis chain from the command layer)
  * but downgraded to warnings so every shard runs. The aggregate verdict
- * line and the aggregate error are NOT produced here — the caller runs
+ * line and the aggregate error are not produced here: the caller runs
  * the engine-generation integrity check first and then calls
  * {@link finalizeShardedOutcome}, so a run invalidated by a concurrent
  * `engine/` mutation can never print `PASS` before the check fails.
@@ -114,7 +114,7 @@ export declare function deriveAggregateShardVerdict(shards: ShardOutcome[]): Har
 export declare function runShardedTests(ctx: TestRunContext, groups: ShardGroup[], diagnoseShardFailure: (outcome: TestRunOutcome, label: string) => string | undefined): Promise<ShardedRunSummary>;
 /**
  * Emits the aggregate FIREFORGE-VERDICT line for a sharded run, then
- * throws the aggregate error when any shard did not pass — the same
+ * throws the aggregate error when any shard did not pass, the same
  * emit-then-throw shape as `finalizeSingleRunOutcome`. Called only after
  * the engine-generation check succeeded.
  */

package/dist/src/commands/test-run.js

@@ -4,14 +4,14 @@
  * sequential per-file sharding of multi-path invocations.
  *
  * Sharding exists because passing several browser-chrome files to one mach
- * invocation destabilizes later files — cross-file profile/pref bleed in the
+ * invocation destabilizes later files: cross-file profile/pref bleed in the
  * shared mochitest profile makes the second file time out at window-open
  * while each file passes in isolation. Sequential single-file harness runs
- * cost startup time but make results reproducible; the combined invocation
+ * cost startup time but make results reproducible. The combined invocation
  * stays available via `--no-shard`.
  */
 import { probeDisplaySleepState } from '../core/display-state.js';
-import { mochitestWithOutput, testWithOutput, xpcshellTestWithOutput, } from '../core/mach.js';
+import { runMachTestSuite } from '../core/mach.js';
 import { getActiveRunLogPath } from '../core/run-log.js';
 import { changedPrefNoiseVerdictNote } from '../core/test-changed-prefs.js';
 import { buildHarnessCrashMessage, classifyHarnessRun, headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
@@ -24,13 +24,13 @@ import { maybeInjectAppdirArg } from './test-appdir.js';
 import { emitHarnessVerdict } from './test-verdict.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export const DEFAULT_HARNESS_RETRIES = 2;
-/** Resolves the capturing mach dispatcher for a suite. */
-function dispatchForSuite(suite) {
+/** Resolves the mach test command a suite dispatches to. */
+function machKindForSuite(suite) {
     if (suite === 'xpcshell')
-        return xpcshellTestWithOutput;
+        return 'xpcshell-test';
     if (suite === 'mochitest')
-        return mochitestWithOutput;
-    return testWithOutput;
+        return 'mochitest';
+    return 'test';
 }
 /**
  * Runs one mach test invocation for `paths`, retrying recognized harness
@@ -38,40 +38,47 @@ function dispatchForSuite(suite) {
  * stale-xpcshell-symlink repair path the single-run flow already used.
  */
 export async function runTestsWithRetries(ctx, paths) {
-    // Pure mochitest dispatches keep their env byte-identical — the profile
+    // Pure mochitest dispatches keep their env byte-identical, since the profile
     // variable is xpcshell-harness-specific. Generic `mach
     // test` runs may include xpcshell paths, so they get the isolation too.
     if (ctx.suite === 'mochitest') {
         return runTestsWithRetriesInner(ctx, paths, ctx.env);
     }
     // Fresh profile dir per harness invocation: shards isolate from each
-    // other and from concurrent `fireforge test` processes; the crash /
-    // symlink-repair retries inside one invocation deliberately REUSE the
-    // same directory (they are the same logical run and the harness
+    // other and from concurrent `fireforge test` processes. The crash /
+    // symlink-repair retries inside one invocation reuse the same directory
+    // on purpose (they are the same logical run and the harness
     // re-initialises the profile contents itself).
     return withXpcshellProfileDir(ctx.env, (env) => runTestsWithRetriesInner(ctx, paths, env));
 }
 async function runTestsWithRetriesInner(ctx, paths, env) {
     const extraArgs = [...ctx.baseExtraArgs];
     const appdirInjectionAttempted = await maybeInjectAppdirArg(ctx.engineDir, paths, ctx.objDir, extraArgs);
-    const dispatch = dispatchForSuite(ctx.suite);
+    const kind = machKindForSuite(ctx.suite);
     const maxAttempts = Math.max(1, ctx.harnessRetries + 1);
     let attempts = 0;
     let result;
     let verdict;
     for (;;) {
         attempts += 1;
-        // Arity is kept minimal when there is nothing extra to pass: the
-        // dispatchers' trailing parameters are optional, and appending explicit
-        // `undefined`s would only make every call site's shape depend on
-        // features the run is not using.
-        result =
-            ctx.fullOutput === true
-                ? await dispatch(ctx.engineDir, paths, extraArgs, env, true)
-                : env
-                    ? await dispatch(ctx.engineDir, paths, extraArgs, env)
-                    : await dispatch(ctx.engineDir, paths, extraArgs);
-        result = await retryAfterXpcshellSymlinkRepair(ctx.engineDir, ctx.objDir, result, ctx.classification, paths, extraArgs, env, dispatch, ctx.fullOutput);
+        result = await runMachTestSuite(kind, {
+            engineDir: ctx.engineDir,
+            testPaths: paths,
+            args: extraArgs,
+            env,
+            fullOutput: ctx.fullOutput,
+        });
+        result = await retryAfterXpcshellSymlinkRepair({
+            engineDir: ctx.engineDir,
+            objDir: ctx.objDir,
+            result,
+            classification: ctx.classification,
+            normalizedPaths: paths,
+            extraArgs,
+            env,
+            kind,
+            fullOutput: ctx.fullOutput,
+        });
         const combined = `${result.stdout}\n${result.stderr}`;
         verdict = classifyHarnessRun(result.exitCode, combined, paths);
         if (verdict.kind !== 'harness-crash' || attempts >= maxAttempts)
@@ -81,7 +88,7 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
             `Retrying (attempt ${attempts + 1} of ${maxAttempts})...`);
     }
     // A verdict whose every unexpected result is time-driven pref noise is
-    // still a FAIL — only the note changes, so a `unexpected=2` line is not
+    // still a FAIL. Only the note changes, so a `unexpected=2` line is not
     // read as two real assertion failures.
     if (verdict.kind === 'test-failures' && verdict.note === undefined) {
         const prefNote = changedPrefNoiseVerdictNote(`${result.stdout}\n${result.stderr}`);
@@ -101,9 +108,9 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
     return { result, verdict, attempts, appdirInjectionAttempted, displayState };
 }
 /**
- * Probes the display's power state for a HEADED no-output stall, and only for
- * that shape. Every other outcome — a passing run, a real test failure, a
- * headless run, any other crash shape — skips the probe entirely, so the
+ * Probes the display's power state for a headed no-output stall, and only for
+ * that shape. Every other outcome (a passing run, a real test failure, a
+ * headless run, any other crash shape) skips the probe entirely, so the
  * common paths spawn nothing.
  *
  * @returns The measured state, or undefined when the shape does not apply
@@ -125,9 +132,9 @@ const SHARD_STATUS_LABEL = {
 };
 /**
  * Derives the aggregate classification for a sharded run: all-green is
- * `tests-ran-ok`; otherwise the most structural failure wins — a crashed
+ * `tests-ran-ok`. Otherwise the most structural failure wins. A crashed
  * shard makes the whole run `harness-crash`, then `no-tests`, then plain
- * `test-failures` — so the aggregate `reason=` keeps the classifier-driven
+ * `test-failures`, so the aggregate `reason=` keeps the classifier-driven
  * contract instead of collapsing every failure to `test-failures`.
  */
 export function deriveAggregateShardVerdict(shards) {
@@ -143,11 +150,11 @@ export function deriveAggregateShardVerdict(shards) {
 /**
  * Runs each requested path argument as its own sequential harness
  * invocation (a directory argument's enumerated files stay together in
- * one invocation — see {@link ShardGroup}) and prints an aggregate
+ * one invocation, see {@link ShardGroup}) and prints an aggregate
  * report. Per-shard failures are diagnosed via `diagnoseShardFailure`
  * (which receives the throwing diagnosis chain from the command layer)
  * but downgraded to warnings so every shard runs. The aggregate verdict
- * line and the aggregate error are NOT produced here — the caller runs
+ * line and the aggregate error are not produced here: the caller runs
  * the engine-generation integrity check first and then calls
  * {@link finalizeShardedOutcome}, so a run invalidated by a concurrent
  * `engine/` mutation can never print `PASS` before the check fails.
@@ -186,7 +193,7 @@ export async function runShardedTests(ctx, groups, diagnoseShardFailure) {
 }
 /**
  * Emits the aggregate FIREFORGE-VERDICT line for a sharded run, then
- * throws the aggregate error when any shard did not pass — the same
+ * throws the aggregate error when any shard did not pass, the same
  * emit-then-throw shape as `finalizeSingleRunOutcome`. Called only after
  * the engine-generation check succeeded.
  */

package/dist/src/commands/test-stale-gate.d.ts

@@ -3,40 +3,40 @@
  * and a run against a stale or under-packaged runtime: the packaging
  * coverage refusal, the stale-content refusal, and the compiled
  * StaticComponents refusal. Split out of `test.ts` so the command module
- * stays wiring; the probes and refusal copy live in
+ * stays wiring. The probes and refusal copy live in
  * `src/core/test-stale-check.ts`.
  */
 import type { BuildBaseline } from '../core/build-baseline-types.js';
 import type { TestOptions } from '../types/commands/index.js';
 /**
- * Stale-build preflight — when `--build` was NOT requested, detect packageable
- * engine edits since the last successful build and fail UP-FRONT unless the
+ * Stale-build preflight: when `--build` was not requested, detect packageable
+ * engine edits since the last successful build and fail up front unless the
  * operator explicitly accepts the stale package risk.
  *
- * Packaging COVERAGE is checked first, on EVERY non-`--build` run and
+ * Packaging coverage is checked first, on every non-`--build` run and
  * regardless of staleness or `--allow-stale-build`: a runtime packaged by a
- * file-scoped `test --build` can lack support fixtures for OTHER manifests
- * even when nothing changed since — dispatching such a run hangs on missing
+ * file-scoped `test --build` can lack support fixtures for other manifests
+ * even when nothing changed since, and dispatching such a run hangs on missing
  * fixtures rather than failing, so the flag (which only accepts stale
- * CONTENT) must not be the trigger. A three-file scoped rebuild leaving one
+ * content) must not be the trigger. A three-file scoped rebuild leaving one
  * fixture unpackaged makes a later run over different files time out waiting
  * on an event that never fires.
  *
  * Exception: a path-less `test --doctor` stops at the Marionette health check
  * (`runDoctorPreflight` returns 'stop' when no test paths were given) and
- * never dispatches a test, so it needs no packaging coverage — treating it as
+ * never dispatches a test, so it needs no packaging coverage. Treating it as
  * a full-suite request would refuse a probe that touches no fixtures. The
  * stale-content refusal still applies to it unchanged.
  */
 export declare function enforceStaleBuildGate(projectRoot: string, engineDir: string, options: TestOptions, normalizedPaths: readonly string[]): Promise<void>;
 /**
- * Compiled-StaticComponents gate — refuses runs whose child process would
+ * Compiled-StaticComponents gate: refuses runs whose child process would
  * resolve a stale compiled component table. `components.conf` entries bake
- * into compiled code that only a FULL build regenerates; a scoped
+ * into compiled code that only a full build regenerates. A scoped
  * `test --build` repackages the file but the failure surfaces as
  * `NS_ERROR_MALFORMED_URI` inside the test. Applies to build-less runs
- * (after the coverage refusal) AND to scoped `test --build` runs (before
- * the pre-test build — that build cannot fix the table). A path-less
+ * (after the coverage refusal) and to scoped `test --build` runs (before
+ * the pre-test build, which cannot fix the table). A path-less
  * `test --build` is exempt: its full build refreshes the anchor itself.
  * `--allow-stale-components` downgrades the refusal to a warning.
  */

package/dist/src/commands/test-stale-gate.js

@@ -4,29 +4,29 @@
  * and a run against a stale or under-packaged runtime: the packaging
  * coverage refusal, the stale-content refusal, and the compiled
  * StaticComponents refusal. Split out of `test.ts` so the command module
- * stays wiring; the probes and refusal copy live in
+ * stays wiring. The probes and refusal copy live in
  * `src/core/test-stale-check.ts`.
  */
 import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
-import { GeneralError } from '../errors/base.js';
+import { PreflightRefusalError } from '../errors/base.js';
 import { warn } from '../utils/logger.js';
 /**
- * Stale-build preflight — when `--build` was NOT requested, detect packageable
- * engine edits since the last successful build and fail UP-FRONT unless the
+ * Stale-build preflight: when `--build` was not requested, detect packageable
+ * engine edits since the last successful build and fail up front unless the
  * operator explicitly accepts the stale package risk.
  *
- * Packaging COVERAGE is checked first, on EVERY non-`--build` run and
+ * Packaging coverage is checked first, on every non-`--build` run and
  * regardless of staleness or `--allow-stale-build`: a runtime packaged by a
- * file-scoped `test --build` can lack support fixtures for OTHER manifests
- * even when nothing changed since — dispatching such a run hangs on missing
+ * file-scoped `test --build` can lack support fixtures for other manifests
+ * even when nothing changed since, and dispatching such a run hangs on missing
  * fixtures rather than failing, so the flag (which only accepts stale
- * CONTENT) must not be the trigger. A three-file scoped rebuild leaving one
+ * content) must not be the trigger. A three-file scoped rebuild leaving one
  * fixture unpackaged makes a later run over different files time out waiting
  * on an event that never fires.
  *
  * Exception: a path-less `test --doctor` stops at the Marionette health check
  * (`runDoctorPreflight` returns 'stop' when no test paths were given) and
- * never dispatches a test, so it needs no packaging coverage — treating it as
+ * never dispatches a test, so it needs no packaging coverage. Treating it as
  * a full-suite request would refuse a probe that touches no fixtures. The
  * stale-content refusal still applies to it unchanged.
  */
@@ -37,10 +37,10 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
         const recordedCoverage = stale.baseline?.testPackagingCoverage;
         const uncovered = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
         if (uncovered.length > 0) {
-            // The refusal is correct on its own; naming the manifest that gained
+            // The refusal is correct on its own. Naming the manifest that gained
             // an entry is the triage step it otherwise leaves to the reader.
             const changedManifests = await findChangedTestManifestsForPaths(engineDir, stale.baseline, uncovered);
-            throw new GeneralError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests));
+            throw new PreflightRefusalError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests), 'coverage-replaced');
         }
     }
     await enforceStaticComponentsGate(engineDir, stale.baseline, options);
@@ -59,18 +59,18 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
             warn(staleMessage);
         }
         else {
-            throw new GeneralError(staleMessage);
+            throw new PreflightRefusalError(staleMessage, 'stale-build');
         }
     }
 }
 /**
- * Compiled-StaticComponents gate — refuses runs whose child process would
+ * Compiled-StaticComponents gate: refuses runs whose child process would
  * resolve a stale compiled component table. `components.conf` entries bake
- * into compiled code that only a FULL build regenerates; a scoped
+ * into compiled code that only a full build regenerates. A scoped
  * `test --build` repackages the file but the failure surfaces as
  * `NS_ERROR_MALFORMED_URI` inside the test. Applies to build-less runs
- * (after the coverage refusal) AND to scoped `test --build` runs (before
- * the pre-test build — that build cannot fix the table). A path-less
+ * (after the coverage refusal) and to scoped `test --build` runs (before
+ * the pre-test build, which cannot fix the table). A path-less
  * `test --build` is exempt: its full build refreshes the anchor itself.
  * `--allow-stale-components` downgrades the refusal to a warning.
  */
@@ -84,5 +84,5 @@ export async function enforceStaticComponentsGate(engineDir, baseline, options)
         warn(message);
         return;
     }
-    throw new GeneralError(message);
+    throw new PreflightRefusalError(message, 'stale-components');
 }

package/dist/src/commands/test-verdict.d.ts

@@ -1,7 +1,7 @@
 import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
 /**
  * Reason codes the emission layer can put on a `FIREFORGE-VERDICT: FAIL`
- * line. The first three mirror the harness classifier; `preflight` covers
+ * line. The first three mirror the harness classifier. `preflight` covers
  * every failure before harness classification (missing/stale builds,
  * invalid paths, port conflicts, config errors, spawn failures),
  * `inconclusive` marks a run whose harness result exists but cannot be
@@ -30,13 +30,27 @@ export declare function emitHarnessVerdict(verdict: HarnessRunVerdict, shards?:
 }): void;
 /** Emits the pathless `--doctor` PASS verdict. */
 export declare function emitPassVerdict(): void;
-/** Emits a FAIL verdict carrying an emission-layer reason code. */
-export declare function emitFailVerdict(reason: FireforgeVerdictReason): void;
+/**
+ * Emits a FAIL verdict carrying an emission-layer reason code, and
+ * optionally the refusal class that produced it.
+ *
+ * `note=` is additive, like the `log=`, `signal=` and `shards=` keys already
+ * on this line: `reason=` is unchanged and still comes from the closed set
+ * in `docs/machine-output.md`, so a consumer that tokenises `key=value`
+ * pairs is unaffected. It exists because `reason=preflight` covers every
+ * gate before the harness (a missing build, a peer's packaging record, a
+ * developer browser holding the objdir), and an unattended reader whose
+ * pipe kept only the verdict line could not tell those apart.
+ *
+ * @param reason - Closed-set verdict reason
+ * @param note - Stable refusal class, when the thrower named one
+ */
+export declare function emitFailVerdict(reason: FireforgeVerdictReason, note?: string): void;
 /**
  * Emits the terminal verdict for a run killed by a signal.
  *
- * Without it a killed run wrote NO terminal line, so a log tail could not
- * distinguish "killed" from "still running" from "never started" — recovery
+ * Without it a killed run wrote no terminal line, so a log tail could not
+ * distinguish "killed" from "still running" from "never started". Recovery
  * meant checking `ps` and the lock file by hand, at the exact moment (a
  * mass kill under a usage limit, mid-drain) when the tree's state most
  * needs to be readable. A no-op unless a run was actually in flight: the

package/dist/src/commands/test-verdict.js

@@ -27,21 +27,21 @@ export function verdictEmitted() {
     return emitted;
 }
 /**
- * Writes the run's single verdict line — raw stdout (clack's renderer can
- * drop output under non-TTY capture), first write wins. Every later call
+ * Writes the run's single verdict line to raw stdout (clack's renderer can
+ * drop output under non-TTY capture). First write wins. Every later call
  * is a no-op: the writer closest to the harness result runs first, so the
  * fallback layers (the engine-generation guard, the preflight wrapper)
  * can emit unconditionally without risking a second line. Writing also
- * seals stdout: the verdict must stay the run's LAST stdout write, so all
- * subsequent logger output — including the CLI-boundary error/cancel
- * rendering after an emit-then-throw path — routes to stderr.
+ * seals stdout: the verdict must stay the run's last stdout write, so all
+ * subsequent logger output, including the CLI-boundary error/cancel
+ * rendering after an emit-then-throw path, routes to stderr.
  */
 function writeVerdictLine(line) {
     if (emitted)
         return;
     emitted = true;
     // The run log's path rides the verdict line because the verdict must stay
-    // the run's LAST stdout write — a separate announcement after it would
+    // the run's last stdout write: a separate announcement after it would
     // break that contract, and one before it is the first thing a `tail` cuts.
     // Appended as an additive `key=value`, so consumers that tokenize the line
     // are unaffected and a truncated tail still says where the full output is.
@@ -61,15 +61,30 @@ export function emitHarnessVerdict(verdict, shards) {
 export function emitPassVerdict() {
     writeVerdictLine('FIREFORGE-VERDICT: PASS');
 }
-/** Emits a FAIL verdict carrying an emission-layer reason code. */
-export function emitFailVerdict(reason) {
-    writeVerdictLine(`FIREFORGE-VERDICT: FAIL reason=${reason}`);
+/**
+ * Emits a FAIL verdict carrying an emission-layer reason code, and
+ * optionally the refusal class that produced it.
+ *
+ * `note=` is additive, like the `log=`, `signal=` and `shards=` keys already
+ * on this line: `reason=` is unchanged and still comes from the closed set
+ * in `docs/machine-output.md`, so a consumer that tokenises `key=value`
+ * pairs is unaffected. It exists because `reason=preflight` covers every
+ * gate before the harness (a missing build, a peer's packaging record, a
+ * developer browser holding the objdir), and an unattended reader whose
+ * pipe kept only the verdict line could not tell those apart.
+ *
+ * @param reason - Closed-set verdict reason
+ * @param note - Stable refusal class, when the thrower named one
+ */
+export function emitFailVerdict(reason, note) {
+    const suffix = note === undefined ? '' : ` note=${note}`;
+    writeVerdictLine(`FIREFORGE-VERDICT: FAIL reason=${reason}${suffix}`);
 }
 /**
  * Emits the terminal verdict for a run killed by a signal.
  *
- * Without it a killed run wrote NO terminal line, so a log tail could not
- * distinguish "killed" from "still running" from "never started" — recovery
+ * Without it a killed run wrote no terminal line, so a log tail could not
+ * distinguish "killed" from "still running" from "never started". Recovery
  * meant checking `ps` and the lock file by hand, at the exact moment (a
  * mass kill under a usage limit, mid-drain) when the tree's state most
  * needs to be readable. A no-op unless a run was actually in flight: the

package/dist/src/commands/test.d.ts

@@ -4,9 +4,9 @@ import type { TestOptions } from '../types/commands/index.js';
  *
  * Owns the run's exactly-one-`FIREFORGE-VERDICT:`-line guarantee: the sink
  * is re-armed at entry, and any failure that reaches this boundary without
- * an inner writer having emitted — the preflight ladder (missing engine or
- * build, config errors, stale-build and port gates, missing paths), and a
- * harness process that failed to start — emits `FAIL reason=preflight`,
+ * an inner writer having emitted (the preflight ladder: missing engine or
+ * build, config errors, stale-build and port gates, missing paths, and a
+ * harness process that failed to start) emits `FAIL reason=preflight`,
  * since no harness classification exists for such a run. Writers closer to
  * the harness (doctor, canary, single, sharded, the engine-generation
  * guard) emit first and win.