@hominis/fireforge 0.44.4 → 0.46.0

package/dist/src/commands/test-build-phase.d.ts

@@ -3,8 +3,8 @@
  * the per-file line budget): the incremental protected mach build with
  * its baseline write, and the `--build-only` union-build shape.
  */
-import type { getProjectPaths, loadConfig } from '../core/config.js';
 import type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
 import type { HarnessClassification } from './test-modes.js';
 /**
  * Runs the pre-test build (or the stale-build gate when no build was
@@ -13,7 +13,7 @@ import type { HarnessClassification } from './test-modes.js';
  * (mixed harnesses legal, nothing dispatches), prints the per-harness
  * next steps, and emits the run's single `PASS` verdict.
  */
-export declare function runTestBuildPhase(projectRoot: string, paths: ReturnType<typeof getProjectPaths>, projectConfig: Awaited<ReturnType<typeof loadConfig>>, harnessRetries: number, options: TestOptions, request: {
+export declare function runTestBuildPhase(projectRoot: string, paths: ProjectPaths, projectConfig: FireForgeConfig, harnessRetries: number, options: TestOptions, request: {
     classification: HarnessClassification;
     normalizedPaths: string[];
 }): Promise<boolean>;

package/dist/src/commands/test-build-phase.js

@@ -16,7 +16,14 @@ import { info, notice, spinner, verbose } from '../utils/logger.js';
 import { reportBuildOnlyCompletion } from './test-modes.js';
 import { enforceStaleBuildGate, enforceStaticComponentsGate } from './test-stale-gate.js';
 import { emitPassVerdict } from './test-verdict.js';
-async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend) {
+/**
+ * Runs the incremental pre-test build under the build lock and records the
+ * baseline it produced.
+ *
+ * @param options - See {@link RunPreTestBuildOptions}
+ */
+async function runPreTestBuild(options) {
+    const { projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend, } = options;
     await withBuildLock(projectRoot, async () => {
         // Pass the previous baseline exactly like `fireforge build` does, so
         // auto-configure runs under the same conditions on both paths. The
@@ -43,7 +50,8 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
             // Warning severity, not info: agent-facing output filters
             // keep warnings and errors only, and this is the line that explains an
             // otherwise unexplained multi-minute build.
-            notice('A jar.mn registration changed since the last successful build; escalating this pre-test build to a full mach build so new install-manifest destinations are created.');
+            notice(preparation.fullBuildReason ??
+                'A jar.mn registration changed since the last successful build; escalating this pre-test build to a full mach build so new install-manifest destinations are created.');
         }
         const s = spinner(preparation.fullBuildRequired
             ? 'Running required full build...'
@@ -80,11 +88,20 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
                 const recordedCoverage = extend !== undefined
                     ? unionTestPackagingCoverage(previousBaseline?.testPackagingCoverage, extend.requestedPaths)
                     : testPackagingCoverage;
-                await writeBuildBaseline(projectRoot, paths.engine, projectConfig.binaryName, recordedCoverage, previousBaseline, describeBuildInvocation(extend !== undefined, testPackagingCoverage), preparation.fullBuildRequired
-                    ? 'refresh'
-                    : extend !== undefined
-                        ? 'carry-forward'
-                        : 'auto', buildKind);
+                await writeBuildBaseline({
+                    projectRoot,
+                    engineDir: paths.engine,
+                    binaryName: projectConfig.binaryName,
+                    testPackagingCoverage: recordedCoverage,
+                    previousBaseline,
+                    recordedBy: describeBuildInvocation(extend !== undefined, testPackagingCoverage),
+                    staticComponentsHandling: preparation.fullBuildRequired
+                        ? 'refresh'
+                        : extend !== undefined
+                            ? 'carry-forward'
+                            : 'auto',
+                    buildKind,
+                });
             }
             catch (baselineError) {
                 verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
@@ -165,7 +182,15 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
                 }
             }
         }
-        await runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, coverage, options.refuseUnexportedDrift === true, extending ? { requestedPaths: normalizedPaths } : undefined);
+        await runPreTestBuild({
+            projectRoot,
+            paths,
+            projectConfig,
+            harnessRetries,
+            testPackagingCoverage: coverage,
+            refuseUnexportedDrift: options.refuseUnexportedDrift === true,
+            extend: extending ? { requestedPaths: normalizedPaths } : undefined,
+        });
         info('');
         if (options.buildOnly) {
             // Union build for mixed harnesses: the coverage claim

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

@@ -7,11 +7,12 @@
  * `test-harness-crash.ts` for single and sharded invocations. Split out of
  * `test.ts` to keep both files within the per-file line budget.
  */
+import { getActiveRunLogPath } from '../core/run-log.js';
 import { describeChangedPrefNoise } from '../core/test-changed-prefs.js';
 import { buildGreenSummaryRejectedMessage, buildHarnessCrashMessage, buildNoTestsRanMessage, buildSilentSegfaultMessage, headedNoOutputTimeoutHint, isSilentSegfault, } from '../core/test-harness-crash.js';
 import { buildHarnessEarlyExitMessage, classifyHarnessEarlyExit, completePostRebuildFailureContext, prependPostRebuildFailureContext, } from '../core/test-harness-output.js';
 import { GeneralError } from '../errors/base.js';
-import { BuildError } from '../errors/build.js';
+import { TestFailureError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { info } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
@@ -132,7 +133,13 @@ function buildMochitestHttp3ServerMessage() {
  * broader ones, so a fork-owned module failure is not reported as a stale
  * build.
  */
-function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName, postRebuildContext) {
+function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName, postRebuildContext, 
+/**
+ * The classified verdict, when one was reached. Carries the failing-test
+ * evidence the final throw names; every branch ABOVE that throw is a
+ * different diagnosis and does not use it.
+ */
+verdict) {
     if (result.exitCode === 0 || result.exitCode === 130)
         return;
     const combinedOutput = `${result.stdout}\n${result.stderr}`;
@@ -194,8 +201,10 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
     // fail (exit code stays 5), so this only says WHICH KIND of failure it is.
     // Every branch above is a different diagnosis and outranks it.
     const changedPrefNoise = describeChangedPrefNoise(combinedOutput);
-    throw new BuildError(withContext(`Tests failed with exit code ${result.exitCode}. Check the output above for details.` +
-        (changedPrefNoise !== undefined ? `\n\n${changedPrefNoise}` : '')), 'mach test');
+    const failureBlocks = formatFailureBlocks(verdict?.realFailureBlocks);
+    const logPath = getActiveRunLogPath();
+    throw new TestFailureError(withContext(`Tests failed with exit code ${result.exitCode}.` +
+        (changedPrefNoise !== undefined ? `\n\n${changedPrefNoise}` : '')), 'mach test', failureBlocks, logPath);
 }
 /**
  * Applies the harness-run verdict for a single (non-sharded) invocation:
@@ -259,7 +268,7 @@ function applySingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuild
                 outcome.verdict.secondaryHarnessSignature.line);
         }
     }
-    handleNonZeroTestExit(outcome.result, normalizedPaths, outcome.appdirInjectionAttempted, binaryName, postRebuildContext);
+    handleNonZeroTestExit(outcome.result, normalizedPaths, outcome.appdirInjectionAttempted, binaryName, postRebuildContext, outcome.verdict);
 }
 /**
  * Shard-mode adapter over {@link handleNonZeroTestExit}: produces the

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

@@ -1,7 +1,7 @@
-import { loadConfig } from '../core/config.js';
 import type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
 import type { TestRunOutcome } from './test-run.js';
-type ProjectConfig = Awaited<ReturnType<typeof loadConfig>>;
+type ProjectConfig = FireForgeConfig;
 /** Rejects pathless `fireforge test` unless the operator selected a pathless mode. */
 export declare function assertPathlessTestMode(testPaths: readonly string[], options: TestOptions): void;
 /** Rejects invalid combinations for mode-like `fireforge test` options. */

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';

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',
@@ -67,10 +69,11 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--allow-stale-build', 'Allow tests to run even when packageable engine files changed since the last successful FireForge build')
         .option('--allow-stale-components', 'Run tests despite components.conf changes that only a full "fireforge build" compiles in (the packaged child process will resolve the OLD StaticComponents table)')
         .option('--kill-stale-marionette', 'Terminate a recognized stale browser from this objdir or one holding the Marionette port before running tests')
+        .option('--reap-orphans', 'Terminate harness helper processes (httpd, pywebsocket, ssltunnel, moz-http2) from this objdir that survived an earlier run. The census itself runs on every test dispatch and is report-only; this flag opts into the kill.')
         .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.js

@@ -11,25 +11,26 @@
  * 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';
 import { retryAfterXpcshellSymlinkRepair } from '../core/test-xpcshell-retry.js';
 import { withXpcshellProfileDir } from '../core/xpcshell-profile-dir.js';
-import { BuildError } from '../errors/build.js';
+import { TestFailureError } from '../errors/build.js';
 import { info, note, warn } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
 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
@@ -53,24 +54,31 @@ export async function runTestsWithRetries(ctx, paths) {
 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)
@@ -193,8 +201,8 @@ export function finalizeShardedOutcome(summary) {
     emitHarnessVerdict(summary.aggregate, { passed: summary.passed, total: summary.total });
     if (summary.passed < summary.total) {
         const failing = summary.shards.filter(({ outcome }) => outcome.verdict.kind !== 'tests-ran-ok');
-        throw new BuildError(`${failing.length} of ${summary.total} sharded test run(s) did not pass: ` +
+        throw new TestFailureError(`${failing.length} of ${summary.total} sharded test run(s) did not pass: ` +
             `${failing.map(({ label }) => label).join(', ')}. ` +
-            'See the per-shard diagnosis above. Use --no-shard to reproduce the combined single-invocation behaviour.', 'mach test');
+            'See the per-shard diagnosis above. Use --no-shard to reproduce the combined single-invocation behaviour.', 'mach test', undefined, getActiveRunLogPath());
     }
 }

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

@@ -7,8 +7,8 @@
  * stays wiring; the probes and refusal copy live in
  * `src/core/test-stale-check.ts`.
  */
-import { checkStaleBuildForTest, checkStaticComponentsStale, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
-import { GeneralError } from '../errors/base.js';
+import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
+import { PreflightRefusalError } from '../errors/base.js';
 import { warn } from '../utils/logger.js';
 /**
  * Stale-build preflight — when `--build` was NOT requested, detect packageable
@@ -37,7 +37,10 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
         const recordedCoverage = stale.baseline?.testPackagingCoverage;
         const uncovered = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
         if (uncovered.length > 0) {
-            throw new GeneralError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : []));
+            // 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 PreflightRefusalError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests), 'coverage-replaced');
         }
     }
     await enforceStaticComponentsGate(engineDir, stale.baseline, options);
@@ -56,7 +59,7 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
             warn(staleMessage);
         }
         else {
-            throw new GeneralError(staleMessage);
+            throw new PreflightRefusalError(staleMessage, 'stale-build');
         }
     }
 }
@@ -81,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

@@ -30,8 +30,22 @@ 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.
  *

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

@@ -61,9 +61,24 @@ 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.

package/dist/src/commands/test.js

@@ -3,17 +3,19 @@ import { join, resolve } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
 import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
+import { reportOrphanedHarnessProcesses } from '../core/harness-orphans.js';
 import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, ensureMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
-import { closeActiveRunLog, openRunLog, setActiveRunLog } from '../core/run-log.js';
+import { closeActiveRunLog, openRunLog, setActiveRunLog, writeToActiveRunLog, } from '../core/run-log.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
 import { assertObjdirMatchesTreeMarker } from '../core/tree-store.js';
-import { GeneralError } from '../errors/base.js';
+import { FireForgeError, GeneralError, PreflightRefusalError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, notice, outro, verbose } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
@@ -224,7 +226,7 @@ async function ensureTestMarionettePortAvailable(port, binaryName, options, skip
     }
     await assertMarionettePortAvailable(port, { binaryName });
 }
-async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellOnly, binaryName, options) {
+async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellOnly, binaryName, options, objDir) {
     // A timed-out mochitest can leave the built app alive after its Marionette
     // listener has disappeared. The port probe cannot see that case, but the
     // survivor can still steal focus and wedge every later headed run.
@@ -242,6 +244,12 @@ async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellO
             killStaleServer: options.killStaleMarionette === true,
         });
     }
+    // Helpers that outlived an earlier run (httpd, pywebsocket, ssltunnel,
+    // moz-http2) slow every later run without appearing in its output. Both
+    // harnesses are affected, so this census is not gated on xpcshellOnly.
+    await reportOrphanedHarnessProcesses(objDir, {
+        reap: options.reapOrphans === true,
+    });
     const forwardedPort = options.machArg
         ? extractForwardedMarionettePort(options.machArg)
         : undefined;
@@ -285,14 +293,50 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         await runTestCommandBody(projectRoot, testPaths, options);
     }
     catch (error) {
-        if (!verdictEmitted())
-            emitFailVerdict('preflight');
+        if (!verdictEmitted()) {
+            renderPreflightRefusal(error);
+            emitFailVerdict('preflight', refusalNote(error));
+        }
         throw error;
     }
     finally {
         await closeActiveRunLog();
     }
 }
+/** The refusal class a preflight gate named, when it named one. */
+function refusalNote(error) {
+    return error instanceof PreflightRefusalError ? error.note : undefined;
+}
+/**
+ * Puts a preflight refusal's own text on the operator's channel BEFORE the
+ * verdict line, and into the run log.
+ *
+ * Both halves are load-bearing, and neither happened before:
+ *
+ *  - `withErrorHandling` renders `error.userMessage` back in `cli.ts`, but
+ *    by then `emitFailVerdict` has called `setStdoutSealed(true)` — the seal
+ *    that keeps the verdict the LAST stdout write — so `logError` routes to
+ *    stderr. A run captured with `> file` therefore kept the verdict and
+ *    dropped the reason.
+ *  - That same rendering happens after this function's caller returns, and
+ *    the `finally` below has already closed the run log. So the artifact the
+ *    verdict's own `log=` key points at did not contain the refusal either,
+ *    which is what left `.fireforge/logs/test-*.log` holding only the
+ *    pre-test build.
+ *
+ * Writing here, before the seal, fixes both without trading away the
+ * contract: the refusal lands on stdout and in the log, and the verdict
+ * line still comes last.
+ */
+function renderPreflightRefusal(error) {
+    const text = error instanceof FireForgeError ? error.userMessage : toError(error).message;
+    const block = `Preflight refused:\n${text}\n`;
+    // Raw stdout rather than the clack logger: this must land on the captured
+    // stream verbatim, and clack's renderer can drop output under non-TTY
+    // capture — the same reason the verdict line is written this way.
+    process.stdout.write(block);
+    writeToActiveRunLog(block);
+}
 /**
  * Verifies `engine/` did not change under the run before any PASS verdict
  * may print. On failure the run's verdict is `FAIL reason=inconclusive` —
@@ -359,7 +403,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     // documented `--mach-arg --marionette-port=NNNN` route still hits the
     // wrapper preflight refusing on 2828 before the forwarded arg reaches
     // mach.
-    const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig.binaryName, options);
+    const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig.binaryName, options, buildCheck.objDir);
     if (options.doctor) {
         const doctorOutcome = await runDoctorPreflight({
             engineDir: paths.engine,
@@ -385,7 +429,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
         extraArgs.push('--auto');
     }
     if (canaryPath !== undefined) {
-        extraArgs.push(`--timeout=${String(canaryTimeoutSeconds(projectConfig))}`);
+        extraArgs.push(`--timeout=${canaryTimeoutSeconds(projectConfig)}`);
     }
     // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
     // flags FireForge does not model directly (see the xpcshell appdir hint

package/dist/src/commands/token-list.d.ts

@@ -0,0 +1,26 @@
+/** Options accepted by {@link tokenListCommand}. */
+export interface TokenListOptions {
+    /** Restrict the report to one category. */
+    category?: string;
+    /** Emit the machine-readable envelope instead of the human report. */
+    json?: boolean;
+}
+/**
+ * Lists the categories declared in the tokens CSS with their token names,
+ * in file order.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Filter and output-mode options
+ */
+export declare function tokenListCommand(projectRoot: string, options?: TokenListOptions): Promise<void>;
+/**
+ * Reports one token: the category that owns it and the value it takes in
+ * every block that declares it.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param tokenName - Custom-property name, with or without the leading `--`
+ * @param options - Output-mode options
+ */
+export declare function tokenShowCommand(projectRoot: string, tokenName: string, options?: {
+    json?: boolean;
+}): Promise<void>;